include/vlc/libvlc_media.h

   1 /*****************************************************************************
   2  * libvlc_media.h:  libvlc external API
   3  *****************************************************************************
   4  * Copyright (C) 1998-2009 VLC authors and VideoLAN
   5  * $Id$
   6  *
   7  * Authors: Clément Stenac <zorglub@videolan.org>
   8  *          Jean-Paul Saman <jpsaman@videolan.org>
   9  *          Pierre d'Herbemont <pdherbemont@videolan.org>
  10  *
  11  * This program is free software; you can redistribute it and/or modify it
  12  * under the terms of the GNU Lesser General Public License as published by
  13  * the Free Software Foundation; either version 2.1 of the License, or
  14  * (at your option) any later version.
  15  *
  16  * This program is distributed in the hope that it will be useful,
  17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  19  * GNU Lesser General Public License for more details.
  20  *
  21  * You should have received a copy of the GNU Lesser General Public License
  22  * along with this program; if not, write to the Free Software Foundation,
  23  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  24  *****************************************************************************/
  25
  26 #ifndef VLC_LIBVLC_MEDIA_H
  27 #define VLC_LIBVLC_MEDIA_H 1
  28
  29 # ifdef __cplusplus
  30 extern "C" {
  31 # endif
  32
  33 /** \defgroup libvlc_media LibVLC media
  34  * \ingroup libvlc
  35  * @ref libvlc_media_t is an abstract representation of a playable media.
  36  * It consists of a media location and various optional meta data.
  37  * @{
  38  * \file
  39  * LibVLC media item/descriptor external API
  40  */
  41
  42 typedef struct libvlc_media_t libvlc_media_t;
  43
  44 /** Meta data types */
  45 typedef enum libvlc_meta_t {
  46     libvlc_meta_Title,
  47     libvlc_meta_Artist,
  48     libvlc_meta_Genre,
  49     libvlc_meta_Copyright,
  50     libvlc_meta_Album,
  51     libvlc_meta_TrackNumber,
  52     libvlc_meta_Description,
  53     libvlc_meta_Rating,
  54     libvlc_meta_Date,
  55     libvlc_meta_Setting,
  56     libvlc_meta_URL,
  57     libvlc_meta_Language,
  58     libvlc_meta_NowPlaying,
  59     libvlc_meta_Publisher,
  60     libvlc_meta_EncodedBy,
  61     libvlc_meta_ArtworkURL,
  62     libvlc_meta_TrackID,
  63     libvlc_meta_TrackTotal,
  64     libvlc_meta_Director,
  65     libvlc_meta_Season,
  66     libvlc_meta_Episode,
  67     libvlc_meta_ShowName,
  68     libvlc_meta_Actors,
  69     libvlc_meta_AlbumArtist,
  70     libvlc_meta_DiscNumber,
  71     libvlc_meta_DiscTotal
  72     /* Add new meta types HERE */
  73 } libvlc_meta_t;
  74
  75 /**
  76  * Note the order of libvlc_state_t enum must match exactly the order of
  77  * \see mediacontrol_PlayerStatus, \see input_state_e enums,
  78  * and VideoLAN.LibVLC.State (at bindings/cil/src/media.cs).
  79  *
  80  * Expected states by web plugins are:
  81  * IDLE/CLOSE=0, OPENING=1, PLAYING=3, PAUSED=4,
  82  * STOPPING=5, ENDED=6, ERROR=7
  83  */
  84 typedef enum libvlc_state_t
  85 {
  86     libvlc_NothingSpecial=0,
  87     libvlc_Opening,
  88     libvlc_Buffering, /* XXX: Deprecated value. Check the
  89                        * libvlc_MediaPlayerBuffering event to know the
  90                        * buffering state of a libvlc_media_player */
  91     libvlc_Playing,
  92     libvlc_Paused,
  93     libvlc_Stopped,
  94     libvlc_Ended,
  95     libvlc_Error
  96 } libvlc_state_t;
  97
  98 enum
  99 {
 100     libvlc_media_option_trusted = 0x2,
 101     libvlc_media_option_unique = 0x100
 102 };
 103
 104 typedef enum libvlc_track_type_t
 105 {
 106     libvlc_track_unknown   = -1,
 107     libvlc_track_audio     = 0,
 108     libvlc_track_video     = 1,
 109     libvlc_track_text      = 2
 110 } libvlc_track_type_t;
 111
 112 typedef struct libvlc_media_stats_t
 113 {
 114     /* Input */
 115     int         i_read_bytes;
 116     float       f_input_bitrate;
 117
 118     /* Demux */
 119     int         i_demux_read_bytes;
 120     float       f_demux_bitrate;
 121     int         i_demux_corrupted;
 122     int         i_demux_discontinuity;
 123
 124     /* Decoders */
 125     int         i_decoded_video;
 126     int         i_decoded_audio;
 127
 128     /* Video Output */
 129     int         i_displayed_pictures;
 130     int         i_lost_pictures;
 131
 132     /* Audio output */
 133     int         i_played_abuffers;
 134     int         i_lost_abuffers;
 135
 136     /* Stream output */
 137     int         i_sent_packets;
 138     int         i_sent_bytes;
 139     float       f_send_bitrate;
 140 } libvlc_media_stats_t;
 141
 142 typedef struct libvlc_media_track_info_t
 143 {
 144     /* Codec fourcc */
 145     uint32_t    i_codec;
 146     int         i_id;
 147     libvlc_track_type_t i_type;
 148
 149     /* Codec specific */
 150     int         i_profile;
 151     int         i_level;
 152
 153     union {
 154         struct {
 155             /* Audio specific */
 156             unsigned    i_channels;
 157             unsigned    i_rate;
 158         } audio;
 159         struct {
 160             /* Video specific */
 161             unsigned    i_height;
 162             unsigned    i_width;
 163         } video;
 164     } u;
 165
 166 } libvlc_media_track_info_t;
 167
 168
 169 typedef struct libvlc_audio_track_t
 170 {
 171     unsigned    i_channels;
 172     unsigned    i_rate;
 173 } libvlc_audio_track_t;
 174
 175 typedef enum libvlc_video_orient_t
 176 {
 177     libvlc_video_orient_top_left,       /**< Normal. Top line represents top, left column left. */
 178     libvlc_video_orient_top_right,      /**< Flipped horizontally */
 179     libvlc_video_orient_bottom_left,    /**< Flipped vertically */
 180     libvlc_video_orient_bottom_right,   /**< Rotated 180 degrees */
 181     libvlc_video_orient_left_top,       /**< Transposed */
 182     libvlc_video_orient_left_bottom,    /**< Rotated 90 degrees clockwise (or 270 anti-clockwise) */
 183     libvlc_video_orient_right_top,      /**< Rotated 90 degrees anti-clockwise */
 184     libvlc_video_orient_right_bottom    /**< Anti-transposed */
 185 } libvlc_video_orient_t;
 186
 187 typedef enum libvlc_video_projection_t
 188 {
 189     libvlc_video_projection_rectangular,
 190     libvlc_video_projection_equirectangular, /**< 360 spherical */
 191
 192     libvlc_video_projection_cubemap_layout_standard = 0x100,
 193 } libvlc_video_projection_t;
 194
 195 typedef struct libvlc_video_track_t
 196 {
 197     unsigned    i_height;
 198     unsigned    i_width;
 199     unsigned    i_sar_num;
 200     unsigned    i_sar_den;
 201     unsigned    i_frame_rate_num;
 202     unsigned    i_frame_rate_den;
 203
 204     libvlc_video_orient_t       i_orientation;
 205     libvlc_video_projection_t   i_projection;
 206     struct {
 207         float f_yaw_degrees;    /**< View point yaw in degrees ]-180;180] */
 208         float f_pitch_degrees;  /**< View point pitch in degrees ]-90;90] */
 209         float f_roll_degrees;   /**< View point roll in degrees ]-180;180] */
 210         float f_fov_degrees;    /**< View point fov in degrees ]0;180[ */
 211     } pose; /**< Initial view point */
 212 } libvlc_video_track_t;
 213
 214 typedef struct libvlc_subtitle_track_t
 215 {
 216     char *psz_encoding;
 217 } libvlc_subtitle_track_t;
 218
 219 typedef struct libvlc_media_track_t
 220 {
 221     /* Codec fourcc */
 222     uint32_t    i_codec;
 223     uint32_t    i_original_fourcc;
 224     int         i_id;
 225     libvlc_track_type_t i_type;
 226
 227     /* Codec specific */
 228     int         i_profile;
 229     int         i_level;
 230
 231     union {
 232         libvlc_audio_track_t *audio;
 233         libvlc_video_track_t *video;
 234         libvlc_subtitle_track_t *subtitle;
 235     };
 236
 237     unsigned int i_bitrate;
 238     char *psz_language;
 239     char *psz_description;
 240
 241 } libvlc_media_track_t;
 242
 243 /**
 244  * Media type
 245  *
 246  * \see libvlc_media_get_type
 247  */
 248 typedef enum libvlc_media_type_t {
 249     libvlc_media_type_unknown,
 250     libvlc_media_type_file,
 251     libvlc_media_type_directory,
 252     libvlc_media_type_disc,
 253     libvlc_media_type_stream,
 254     libvlc_media_type_playlist,
 255 } libvlc_media_type_t;
 256
 257 /**
 258  * Parse flags used by libvlc_media_parse_with_options()
 259  *
 260  * \see libvlc_media_parse_with_options
 261  */
 262 typedef enum libvlc_media_parse_flag_t
 263 {
 264     /**
 265      * Parse media if it's a local file
 266      */
 267     libvlc_media_parse_local    = 0x00,
 268     /**
 269      * Parse media even if it's a network file
 270      */
 271     libvlc_media_parse_network  = 0x01,
 272     /**
 273      * Fetch meta and covert art using local resources
 274      */
 275     libvlc_media_fetch_local    = 0x02,
 276     /**
 277      * Fetch meta and covert art using network resources
 278      */
 279     libvlc_media_fetch_network  = 0x04,
 280     /**
 281      * Interact with the user (via libvlc_dialog_cbs) when preparsing this item
 282      * (and not its sub items). Set this flag in order to receive a callback
 283      * when the input is asking for credentials.
 284      */
 285     libvlc_media_do_interact    = 0x08,
 286 } libvlc_media_parse_flag_t;
 287
 288 /**
 289  * Parse status used sent by libvlc_media_parse_with_options() or returned by
 290  * libvlc_media_get_parsed_status()
 291  *
 292  * \see libvlc_media_parse_with_options
 293  * \see libvlc_media_get_parsed_status
 294  */
 295 typedef enum libvlc_media_parsed_status_t
 296 {
 297     libvlc_media_parsed_status_skipped = 1,
 298     libvlc_media_parsed_status_failed,
 299     libvlc_media_parsed_status_timeout,
 300     libvlc_media_parsed_status_done,
 301 } libvlc_media_parsed_status_t;
 302
 303 /**
 304  * Type of a media slave: subtitle or audio.
 305  */
 306 typedef enum libvlc_media_slave_type_t
 307 {
 308     libvlc_media_slave_type_subtitle,
 309     libvlc_media_slave_type_audio,
 310 } libvlc_media_slave_type_t;
 311
 312 /**
 313  * A slave of a libvlc_media_t
 314  * \see libvlc_media_slaves_get
 315  */
 316 typedef struct libvlc_media_slave_t
 317 {
 318     char *                          psz_uri;
 319     libvlc_media_slave_type_t       i_type;
 320     unsigned int                    i_priority;
 321 } libvlc_media_slave_t;
 322
 323 /**
 324  * Callback prototype to open a custom bitstream input media.
 325  *
 326  * The same media item can be opened multiple times. Each time, this callback
 327  * is invoked. It should allocate and initialize any instance-specific
 328  * resources, then store them in *datap. The instance resources can be freed
 329  * in the @ref libvlc_media_close_cb callback.
 330  *
 331  * \param opaque private pointer as passed to libvlc_media_new_callbacks()
 332  * \param datap storage space for a private data pointer [OUT]
 333  * \param sizep byte length of the bitstream or UINT64_MAX if unknown [OUT]
 334  *
 335  * \note For convenience, *datap is initially NULL and *sizep is initially 0.
 336  *
 337  * \return 0 on success, non-zero on error. In case of failure, the other
 338  * callbacks will not be invoked and any value stored in *datap and *sizep is
 339  * discarded.
 340  */
 341 typedef int (*libvlc_media_open_cb)(void *opaque, void **datap,
 342                                     uint64_t *sizep);
 343
 344 /**
 345  * Callback prototype to read data from a custom bitstream input media.
 346  *
 347  * \param opaque private pointer as set by the @ref libvlc_media_open_cb
 348  *               callback
 349  * \param buf start address of the buffer to read data into
 350  * \param len bytes length of the buffer
 351  *
 352  * \return strictly positive number of bytes read, 0 on end-of-stream,
 353  *         or -1 on non-recoverable error
 354  *
 355  * \note If no data is immediately available, then the callback should sleep.
 356  * \warning The application is responsible for avoiding deadlock situations.
 357  * In particular, the callback should return an error if playback is stopped;
 358  * if it does not return, then libvlc_media_player_stop() will never return.
 359  */
 360 typedef ssize_t (*libvlc_media_read_cb)(void *opaque, unsigned char *buf,
 361                                         size_t len);
 362
 363 /**
 364  * Callback prototype to seek a custom bitstream input media.
 365  *
 366  * \param opaque private pointer as set by the @ref libvlc_media_open_cb
 367  *               callback
 368  * \param offset absolute byte offset to seek to
 369  * \return 0 on success, -1 on error.
 370  */
 371 typedef int (*libvlc_media_seek_cb)(void *opaque, uint64_t offset);
 372
 373 /**
 374  * Callback prototype to close a custom bitstream input media.
 375  *
 376  * \param opaque private pointer as set by the @ref libvlc_media_open_cb
 377  *               callback
 378  */
 379 typedef void (*libvlc_media_close_cb)(void *opaque);
 380
 381 /**
 382  * Create a media with a certain given media resource location,
 383  * for instance a valid URL.
 384  *
 385  * \note To refer to a local file with this function,
 386  * the file://... URI syntax <b>must</b> be used (see IETF RFC3986).
 387  * We recommend using libvlc_media_new_path() instead when dealing with
 388  * local files.
 389  *
 390  * \see libvlc_media_release
 391  *
 392  * \param p_instance the instance
 393  * \param psz_mrl the media location
 394  * \return the newly created media or NULL on error
 395  */
 396 LIBVLC_API libvlc_media_t *libvlc_media_new_location(
 397                                    libvlc_instance_t *p_instance,
 398                                    const char * psz_mrl );
 399
 400 /**
 401  * Create a media for a certain file path.
 402  *
 403  * \see libvlc_media_release
 404  *
 405  * \param p_instance the instance
 406  * \param path local filesystem path
 407  * \return the newly created media or NULL on error
 408  */
 409 LIBVLC_API libvlc_media_t *libvlc_media_new_path(
 410                                    libvlc_instance_t *p_instance,
 411                                    const char *path );
 412
 413 /**
 414  * Create a media for an already open file descriptor.
 415  * The file descriptor shall be open for reading (or reading and writing).
 416  *
 417  * Regular file descriptors, pipe read descriptors and character device
 418  * descriptors (including TTYs) are supported on all platforms.
 419  * Block device descriptors are supported where available.
 420  * Directory descriptors are supported on systems that provide fdopendir().
 421  * Sockets are supported on all platforms where they are file descriptors,
 422  * i.e. all except Windows.
 423  *
 424  * \note This library will <b>not</b> automatically close the file descriptor
 425  * under any circumstance. Nevertheless, a file descriptor can usually only be
 426  * rendered once in a media player. To render it a second time, the file
 427  * descriptor should probably be rewound to the beginning with lseek().
 428  *
 429  * \see libvlc_media_release
 430  *
 431  * \version LibVLC 1.1.5 and later.
 432  *
 433  * \param p_instance the instance
 434  * \param fd open file descriptor
 435  * \return the newly created media or NULL on error
 436  */
 437 LIBVLC_API libvlc_media_t *libvlc_media_new_fd(
 438                                    libvlc_instance_t *p_instance,
 439                                    int fd );
 440
 441 /**
 442  * Create a media with custom callbacks to read the data from.
 443  *
 444  * \param instance LibVLC instance
 445  * \param open_cb callback to open the custom bitstream input media
 446  * \param read_cb callback to read data (must not be NULL)
 447  * \param seek_cb callback to seek, or NULL if seeking is not supported
 448  * \param close_cb callback to close the media, or NULL if unnecessary
 449  * \param opaque data pointer for the open callback
 450  *
 451  * \return the newly created media or NULL on error
 452  *
 453  * \note If open_cb is NULL, the opaque pointer will be passed to read_cb,
 454  * seek_cb and close_cb, and the stream size will be treated as unknown.
 455  *
 456  * \note The callbacks may be called asynchronously (from another thread).
 457  * A single stream instance need not be reentrant. However the open_cb needs to
 458  * be reentrant if the media is used by multiple player instances.
 459  *
 460  * \warning The callbacks may be used until all or any player instances
 461  * that were supplied the media item are stopped.
 462  *
 463  * \see libvlc_media_release
 464  *
 465  * \version LibVLC 3.0.0 and later.
 466  */
 467 LIBVLC_API libvlc_media_t *libvlc_media_new_callbacks(
 468                                    libvlc_instance_t *instance,
 469                                    libvlc_media_open_cb open_cb,
 470                                    libvlc_media_read_cb read_cb,
 471                                    libvlc_media_seek_cb seek_cb,
 472                                    libvlc_media_close_cb close_cb,
 473                                    void *opaque );
 474
 475 /**
 476  * Create a media as an empty node with a given name.
 477  *
 478  * \see libvlc_media_release
 479  *
 480  * \param p_instance the instance
 481  * \param psz_name the name of the node
 482  * \return the new empty media or NULL on error
 483  */
 484 LIBVLC_API libvlc_media_t *libvlc_media_new_as_node(
 485                                    libvlc_instance_t *p_instance,
 486                                    const char * psz_name );
 487
 488 /**
 489  * Add an option to the media.
 490  *
 491  * This option will be used to determine how the media_player will
 492  * read the media. This allows to use VLC's advanced
 493  * reading/streaming options on a per-media basis.
 494  *
 495  * \note The options are listed in 'vlc --long-help' from the command line,
 496  * e.g. "-sout-all". Keep in mind that available options and their semantics
 497  * vary across LibVLC versions and builds.
 498  * \warning Not all options affects libvlc_media_t objects:
 499  * Specifically, due to architectural issues most audio and video options,
 500  * such as text renderer options, have no effects on an individual media.
 501  * These options must be set through libvlc_new() instead.
 502  *
 503  * \param p_md the media descriptor
 504  * \param psz_options the options (as a string)
 505  */
 506 LIBVLC_API void libvlc_media_add_option(
 507                                    libvlc_media_t *p_md,
 508                                    const char * psz_options );
 509
 510 /**
 511  * Add an option to the media with configurable flags.
 512  *
 513  * This option will be used to determine how the media_player will
 514  * read the media. This allows to use VLC's advanced
 515  * reading/streaming options on a per-media basis.
 516  *
 517  * The options are detailed in vlc --long-help, for instance
 518  * "--sout-all". Note that all options are not usable on medias:
 519  * specifically, due to architectural issues, video-related options
 520  * such as text renderer options cannot be set on a single media. They
 521  * must be set on the whole libvlc instance instead.
 522  *
 523  * \param p_md the media descriptor
 524  * \param psz_options the options (as a string)
 525  * \param i_flags the flags for this option
 526  */
 527 LIBVLC_API void libvlc_media_add_option_flag(
 528                                    libvlc_media_t *p_md,
 529                                    const char * psz_options,
 530                                    unsigned i_flags );
 531
 532
 533 /**
 534  * Retain a reference to a media descriptor object (libvlc_media_t). Use
 535  * libvlc_media_release() to decrement the reference count of a
 536  * media descriptor object.
 537  *
 538  * \param p_md the media descriptor
 539  */
 540 LIBVLC_API void libvlc_media_retain( libvlc_media_t *p_md );
 541
 542 /**
 543  * Decrement the reference count of a media descriptor object. If the
 544  * reference count is 0, then libvlc_media_release() will release the
 545  * media descriptor object. It will send out an libvlc_MediaFreed event
 546  * to all listeners. If the media descriptor object has been released it
 547  * should not be used again.
 548  *
 549  * \param p_md the media descriptor
 550  */
 551 LIBVLC_API void libvlc_media_release( libvlc_media_t *p_md );
 552
 553
 554 /**
 555  * Get the media resource locator (mrl) from a media descriptor object
 556  *
 557  * \param p_md a media descriptor object
 558  * \return string with mrl of media descriptor object
 559  */
 560 LIBVLC_API char *libvlc_media_get_mrl( libvlc_media_t *p_md );
 561
 562 /**
 563  * Duplicate a media descriptor object.
 564  *
 565  * \param p_md a media descriptor object.
 566  */
 567 LIBVLC_API libvlc_media_t *libvlc_media_duplicate( libvlc_media_t *p_md );
 568
 569 /**
 570  * Read the meta of the media.
 571  *
 572  * If the media has not yet been parsed this will return NULL.
 573  *
 574  * \see libvlc_media_parse
 575  * \see libvlc_media_parse_with_options
 576  * \see libvlc_MediaMetaChanged
 577  *
 578  * \param p_md the media descriptor
 579  * \param e_meta the meta to read
 580  * \return the media's meta
 581  */
 582 LIBVLC_API char *libvlc_media_get_meta( libvlc_media_t *p_md,
 583                                              libvlc_meta_t e_meta );
 584
 585 /**
 586  * Set the meta of the media (this function will not save the meta, call
 587  * libvlc_media_save_meta in order to save the meta)
 588  *
 589  * \param p_md the media descriptor
 590  * \param e_meta the meta to write
 591  * \param psz_value the media's meta
 592  */
 593 LIBVLC_API void libvlc_media_set_meta( libvlc_media_t *p_md,
 594                                            libvlc_meta_t e_meta,
 595                                            const char *psz_value );
 596
 597
 598 /**
 599  * Save the meta previously set
 600  *
 601  * \param p_md the media desriptor
 602  * \return true if the write operation was successful
 603  */
 604 LIBVLC_API int libvlc_media_save_meta( libvlc_media_t *p_md );
 605
 606
 607 /**
 608  * Get current state of media descriptor object. Possible media states are
 609  * libvlc_NothingSpecial=0, libvlc_Opening, libvlc_Playing, libvlc_Paused,
 610  * libvlc_Stopped, libvlc_Ended, libvlc_Error.
 611  *
 612  * \see libvlc_state_t
 613  * \param p_md a media descriptor object
 614  * \return state of media descriptor object
 615  */
 616 LIBVLC_API libvlc_state_t libvlc_media_get_state(
 617                                    libvlc_media_t *p_md );
 618
 619
 620 /**
 621  * Get the current statistics about the media
 622  * \param p_md: media descriptor object
 623  * \param p_stats: structure that contain the statistics about the media
 624  *                 (this structure must be allocated by the caller)
 625  * \return true if the statistics are available, false otherwise
 626  *
 627  * \libvlc_return_bool
 628  */
 629 LIBVLC_API int libvlc_media_get_stats( libvlc_media_t *p_md,
 630                                            libvlc_media_stats_t *p_stats );
 631
 632 /* The following method uses libvlc_media_list_t, however, media_list usage is optionnal
 633  * and this is here for convenience */
 634 #define VLC_FORWARD_DECLARE_OBJECT(a) struct a
 635
 636 /**
 637  * Get subitems of media descriptor object. This will increment
 638  * the reference count of supplied media descriptor object. Use
 639  * libvlc_media_list_release() to decrement the reference counting.
 640  *
 641  * \param p_md media descriptor object
 642  * \return list of media descriptor subitems or NULL
 643  */
 644 LIBVLC_API VLC_FORWARD_DECLARE_OBJECT(libvlc_media_list_t *)
 645 libvlc_media_subitems( libvlc_media_t *p_md );
 646
 647 /**
 648  * Get event manager from media descriptor object.
 649  * NOTE: this function doesn't increment reference counting.
 650  *
 651  * \param p_md a media descriptor object
 652  * \return event manager object
 653  */
 654 LIBVLC_API libvlc_event_manager_t *
 655     libvlc_media_event_manager( libvlc_media_t *p_md );
 656
 657 /**
 658  * Get duration (in ms) of media descriptor object item.
 659  *
 660  * \param p_md media descriptor object
 661  * \return duration of media item or -1 on error
 662  */
 663 LIBVLC_API libvlc_time_t
 664    libvlc_media_get_duration( libvlc_media_t *p_md );
 665
 666 /**
 667  * Parse the media asynchronously with options.
 668  *
 669  * This fetches (local or network) art, meta data and/or tracks information.
 670  * This method is the extended version of libvlc_media_parse_with_options().
 671  *
 672  * To track when this is over you can listen to libvlc_MediaParsedChanged
 673  * event. However if this functions returns an error, you will not receive any
 674  * events.
 675  *
 676  * It uses a flag to specify parse options (see libvlc_media_parse_flag_t). All
 677  * these flags can be combined. By default, media is parsed if it's a local
 678  * file.
 679  *
 680  * \note Parsing can be aborted with libvlc_media_parse_stop().
 681  *
 682  * \see libvlc_MediaParsedChanged
 683  * \see libvlc_media_get_meta
 684  * \see libvlc_media_tracks_get
 685  * \see libvlc_media_get_parsed_status
 686  * \see libvlc_media_parse_flag_t
 687  *
 688  * \param p_md media descriptor object
 689  * \param parse_flag parse options:
 690  * \param timeout maximum time allowed to preparse the media. If -1, the
 691  * default "preparse-timeout" option will be used as a timeout. If 0, it will
 692  * wait indefinitely. If > 0, the timeout will be used (in milliseconds).
 693  * \return -1 in case of error, 0 otherwise
 694  * \version LibVLC 3.0.0 or later
 695  */
 696 LIBVLC_API int
 697 libvlc_media_parse_with_options( libvlc_media_t *p_md,
 698                                  libvlc_media_parse_flag_t parse_flag,
 699                                  int timeout );
 700
 701 /**
 702  * Stop the parsing of the media
 703  *
 704  * When the media parsing is stopped, the libvlc_MediaParsedChanged event will
 705  * be sent with the libvlc_media_parsed_status_timeout status.
 706  *
 707  * \see libvlc_media_parse_with_options
 708  *
 709  * \param p_md media descriptor object
 710  * \version LibVLC 3.0.0 or later
 711  */
 712 LIBVLC_API void
 713 libvlc_media_parse_stop( libvlc_media_t *p_md );
 714
 715 /**
 716  * Get Parsed status for media descriptor object.
 717  *
 718  * \see libvlc_MediaParsedChanged
 719  * \see libvlc_media_parsed_status_t
 720  *
 721  * \param p_md media descriptor object
 722  * \return a value of the libvlc_media_parsed_status_t enum
 723  * \version LibVLC 3.0.0 or later
 724  */
 725 LIBVLC_API libvlc_media_parsed_status_t
 726    libvlc_media_get_parsed_status( libvlc_media_t *p_md );
 727
 728 /**
 729  * Sets media descriptor's user_data. user_data is specialized data
 730  * accessed by the host application, VLC.framework uses it as a pointer to
 731  * an native object that references a libvlc_media_t pointer
 732  *
 733  * \param p_md media descriptor object
 734  * \param p_new_user_data pointer to user data
 735  */
 736 LIBVLC_API void
 737     libvlc_media_set_user_data( libvlc_media_t *p_md, void *p_new_user_data );
 738
 739 /**
 740  * Get media descriptor's user_data. user_data is specialized data
 741  * accessed by the host application, VLC.framework uses it as a pointer to
 742  * an native object that references a libvlc_media_t pointer
 743  *
 744  * \param p_md media descriptor object
 745  */
 746 LIBVLC_API void *libvlc_media_get_user_data( libvlc_media_t *p_md );
 747
 748 /**
 749  * Get media descriptor's elementary streams description
 750  *
 751  * Note, you need to call libvlc_media_parse() or play the media at least once
 752  * before calling this function.
 753  * Not doing this will result in an empty array.
 754  *
 755  * \version LibVLC 2.1.0 and later.
 756  *
 757  * \param p_md media descriptor object
 758  * \param tracks address to store an allocated array of Elementary Streams
 759  *        descriptions (must be freed with libvlc_media_tracks_release
 760           by the caller) [OUT]
 761  *
 762  * \return the number of Elementary Streams (zero on error)
 763  */
 764 LIBVLC_API
 765 unsigned libvlc_media_tracks_get( libvlc_media_t *p_md,
 766                                   libvlc_media_track_t ***tracks );
 767
 768 /**
 769  * Get codec description from media elementary stream
 770  *
 771  * \version LibVLC 3.0.0 and later.
 772  *
 773  * \see libvlc_media_track_t
 774  *
 775  * \param i_type i_type from libvlc_media_track_t
 776  * \param i_codec i_codec or i_original_fourcc from libvlc_media_track_t
 777  *
 778  * \return codec description
 779  */
 780 LIBVLC_API
 781 const char *libvlc_media_get_codec_description( libvlc_track_type_t i_type,
 782                                                 uint32_t i_codec );
 783
 784 /**
 785  * Release media descriptor's elementary streams description array
 786  *
 787  * \version LibVLC 2.1.0 and later.
 788  *
 789  * \param p_tracks tracks info array to release
 790  * \param i_count number of elements in the array
 791  */
 792 LIBVLC_API
 793 void libvlc_media_tracks_release( libvlc_media_track_t **p_tracks,
 794                                   unsigned i_count );
 795
 796 /**
 797  * Get the media type of the media descriptor object
 798  *
 799  * \version LibVLC 3.0.0 and later.
 800  *
 801  * \see libvlc_media_type_t
 802  *
 803  * \param p_md media descriptor object
 804  *
 805  * \return media type
 806  */
 807 LIBVLC_API
 808 libvlc_media_type_t libvlc_media_get_type( libvlc_media_t *p_md );
 809
 810 /**
 811  * Add a slave to the current media.
 812  *
 813  * A slave is an external input source that may contains an additional subtitle
 814  * track (like a .srt) or an additional audio track (like a .ac3).
 815  *
 816  * \note This function must be called before the media is parsed (via
 817  * libvlc_media_parse_with_options()) or before the media is played (via
 818  * libvlc_media_player_play())
 819  *
 820  * \version LibVLC 3.0.0 and later.
 821  *
 822  * \param p_md media descriptor object
 823  * \param i_type subtitle or audio
 824  * \param i_priority from 0 (low priority) to 4 (high priority)
 825  * \param psz_uri Uri of the slave (should contain a valid scheme).
 826  *
 827  * \return 0 on success, -1 on error.
 828  */
 829 LIBVLC_API
 830 int libvlc_media_slaves_add( libvlc_media_t *p_md,
 831                              libvlc_media_slave_type_t i_type,
 832                              unsigned int i_priority,
 833                              const char *psz_uri );
 834
 835 /**
 836  * Clear all slaves previously added by libvlc_media_slaves_add() or
 837  * internally.
 838  *
 839  * \version LibVLC 3.0.0 and later.
 840  *
 841  * \param p_md media descriptor object
 842  */
 843 LIBVLC_API
 844 void libvlc_media_slaves_clear( libvlc_media_t *p_md );
 845
 846 /**
 847  * Get a media descriptor's slave list
 848  *
 849  * The list will contain slaves parsed by VLC or previously added by
 850  * libvlc_media_slaves_add(). The typical use case of this function is to save
 851  * a list of slave in a database for a later use.
 852  *
 853  * \version LibVLC 3.0.0 and later.
 854  *
 855  * \see libvlc_media_slaves_add
 856  *
 857  * \param p_md media descriptor object
 858  * \param ppp_slaves address to store an allocated array of slaves (must be
 859  * freed with libvlc_media_slaves_release()) [OUT]
 860  *
 861  * \return the number of slaves (zero on error)
 862  */
 863 LIBVLC_API
 864 unsigned int libvlc_media_slaves_get( libvlc_media_t *p_md,
 865                                       libvlc_media_slave_t ***ppp_slaves );
 866
 867 /**
 868  * Release a media descriptor's slave list
 869  *
 870  * \version LibVLC 3.0.0 and later.
 871  *
 872  * \param pp_slaves slave array to release
 873  * \param i_count number of elements in the array
 874  */
 875 LIBVLC_API
 876 void libvlc_media_slaves_release( libvlc_media_slave_t **pp_slaves,
 877                                   unsigned int i_count );
 878
 879 /** @}*/
 880
 881 # ifdef __cplusplus
 882 }
 883 # endif
 884
 885 #endif /* VLC_LIBVLC_MEDIA_H */