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 /**
 196  * Viewpoint
 197  *
 198  * \warning allocate using libvlc_video_new_viewpoint()
 199  */
 200 typedef struct libvlc_video_viewpoint_t
 201 {
 202     float f_yaw;           /**< view point yaw in degrees  ]-180;180] */
 203     float f_pitch;         /**< view point pitch in degrees  ]-90;90] */
 204     float f_roll;          /**< view point roll in degrees ]-180;180] */
 205     float f_field_of_view; /**< field of view in degrees ]0;180[ (default 80.)*/
 206 } libvlc_video_viewpoint_t;
 207
 208 typedef struct libvlc_video_track_t
 209 {
 210     unsigned    i_height;
 211     unsigned    i_width;
 212     unsigned    i_sar_num;
 213     unsigned    i_sar_den;
 214     unsigned    i_frame_rate_num;
 215     unsigned    i_frame_rate_den;
 216
 217     libvlc_video_orient_t       i_orientation;
 218     libvlc_video_projection_t   i_projection;
 219     libvlc_video_viewpoint_t    pose; /**< Initial view point */
 220 } libvlc_video_track_t;
 221
 222 typedef struct libvlc_subtitle_track_t
 223 {
 224     char *psz_encoding;
 225 } libvlc_subtitle_track_t;
 226
 227 typedef struct libvlc_media_track_t
 228 {
 229     /* Codec fourcc */
 230     uint32_t    i_codec;
 231     uint32_t    i_original_fourcc;
 232     int         i_id;
 233     libvlc_track_type_t i_type;
 234
 235     /* Codec specific */
 236     int         i_profile;
 237     int         i_level;
 238
 239     union {
 240         libvlc_audio_track_t *audio;
 241         libvlc_video_track_t *video;
 242         libvlc_subtitle_track_t *subtitle;
 243     };
 244
 245     unsigned int i_bitrate;
 246     char *psz_language;
 247     char *psz_description;
 248
 249 } libvlc_media_track_t;
 250
 251 /**
 252  * Media type
 253  *
 254  * \see libvlc_media_get_type
 255  */
 256 typedef enum libvlc_media_type_t {
 257     libvlc_media_type_unknown,
 258     libvlc_media_type_file,
 259     libvlc_media_type_directory,
 260     libvlc_media_type_disc,
 261     libvlc_media_type_stream,
 262     libvlc_media_type_playlist,
 263 } libvlc_media_type_t;
 264
 265 /**
 266  * Parse flags used by libvlc_media_parse_with_options()
 267  *
 268  * \see libvlc_media_parse_with_options
 269  */
 270 typedef enum libvlc_media_parse_flag_t
 271 {
 272     /**
 273      * Parse media if it's a local file
 274      */
 275     libvlc_media_parse_local    = 0x00,
 276     /**
 277      * Parse media even if it's a network file
 278      */
 279     libvlc_media_parse_network  = 0x01,
 280     /**
 281      * Fetch meta and covert art using local resources
 282      */
 283     libvlc_media_fetch_local    = 0x02,
 284     /**
 285      * Fetch meta and covert art using network resources
 286      */
 287     libvlc_media_fetch_network  = 0x04,
 288     /**
 289      * Interact with the user (via libvlc_dialog_cbs) when preparsing this item
 290      * (and not its sub items). Set this flag in order to receive a callback
 291      * when the input is asking for credentials.
 292      */
 293     libvlc_media_do_interact    = 0x08,
 294 } libvlc_media_parse_flag_t;
 295
 296 /**
 297  * Parse status used sent by libvlc_media_parse_with_options() or returned by
 298  * libvlc_media_get_parsed_status()
 299  *
 300  * \see libvlc_media_parse_with_options
 301  * \see libvlc_media_get_parsed_status
 302  */
 303 typedef enum libvlc_media_parsed_status_t
 304 {
 305     libvlc_media_parsed_status_skipped = 1,
 306     libvlc_media_parsed_status_failed,
 307     libvlc_media_parsed_status_timeout,
 308     libvlc_media_parsed_status_done,
 309 } libvlc_media_parsed_status_t;
 310
 311 /**
 312  * Type of a media slave: subtitle or audio.
 313  */
 314 typedef enum libvlc_media_slave_type_t
 315 {
 316     libvlc_media_slave_type_subtitle,
 317     libvlc_media_slave_type_audio,
 318 } libvlc_media_slave_type_t;
 319
 320 /**
 321  * A slave of a libvlc_media_t
 322  * \see libvlc_media_slaves_get
 323  */
 324 typedef struct libvlc_media_slave_t
 325 {
 326     char *                          psz_uri;
 327     libvlc_media_slave_type_t       i_type;
 328     unsigned int                    i_priority;
 329 } libvlc_media_slave_t;
 330
 331 /**
 332  * Callback prototype to open a custom bitstream input media.
 333  *
 334  * The same media item can be opened multiple times. Each time, this callback
 335  * is invoked. It should allocate and initialize any instance-specific
 336  * resources, then store them in *datap. The instance resources can be freed
 337  * in the @ref libvlc_media_close_cb callback.
 338  *
 339  * \param opaque private pointer as passed to libvlc_media_new_callbacks()
 340  * \param datap storage space for a private data pointer [OUT]
 341  * \param sizep byte length of the bitstream or UINT64_MAX if unknown [OUT]
 342  *
 343  * \note For convenience, *datap is initially NULL and *sizep is initially 0.
 344  *
 345  * \return 0 on success, non-zero on error. In case of failure, the other
 346  * callbacks will not be invoked and any value stored in *datap and *sizep is
 347  * discarded.
 348  */
 349 typedef int (*libvlc_media_open_cb)(void *opaque, void **datap,
 350                                     uint64_t *sizep);
 351
 352 /**
 353  * Callback prototype to read data from a custom bitstream input media.
 354  *
 355  * \param opaque private pointer as set by the @ref libvlc_media_open_cb
 356  *               callback
 357  * \param buf start address of the buffer to read data into
 358  * \param len bytes length of the buffer
 359  *
 360  * \return strictly positive number of bytes read, 0 on end-of-stream,
 361  *         or -1 on non-recoverable error
 362  *
 363  * \note If no data is immediately available, then the callback should sleep.
 364  * \warning The application is responsible for avoiding deadlock situations.
 365  * In particular, the callback should return an error if playback is stopped;
 366  * if it does not return, then libvlc_media_player_stop() will never return.
 367  */
 368 typedef ssize_t (*libvlc_media_read_cb)(void *opaque, unsigned char *buf,
 369                                         size_t len);
 370
 371 /**
 372  * Callback prototype to seek a custom bitstream input media.
 373  *
 374  * \param opaque private pointer as set by the @ref libvlc_media_open_cb
 375  *               callback
 376  * \param offset absolute byte offset to seek to
 377  * \return 0 on success, -1 on error.
 378  */
 379 typedef int (*libvlc_media_seek_cb)(void *opaque, uint64_t offset);
 380
 381 /**
 382  * Callback prototype to close a custom bitstream input media.
 383  *
 384  * \param opaque private pointer as set by the @ref libvlc_media_open_cb
 385  *               callback
 386  */
 387 typedef void (*libvlc_media_close_cb)(void *opaque);
 388
 389 /**
 390  * Create a media with a certain given media resource location,
 391  * for instance a valid URL.
 392  *
 393  * \note To refer to a local file with this function,
 394  * the file://... URI syntax <b>must</b> be used (see IETF RFC3986).
 395  * We recommend using libvlc_media_new_path() instead when dealing with
 396  * local files.
 397  *
 398  * \see libvlc_media_release
 399  *
 400  * \param p_instance the instance
 401  * \param psz_mrl the media location
 402  * \return the newly created media or NULL on error
 403  */
 404 LIBVLC_API libvlc_media_t *libvlc_media_new_location(
 405                                    libvlc_instance_t *p_instance,
 406                                    const char * psz_mrl );
 407
 408 /**
 409  * Create a media for a certain file path.
 410  *
 411  * \see libvlc_media_release
 412  *
 413  * \param p_instance the instance
 414  * \param path local filesystem path
 415  * \return the newly created media or NULL on error
 416  */
 417 LIBVLC_API libvlc_media_t *libvlc_media_new_path(
 418                                    libvlc_instance_t *p_instance,
 419                                    const char *path );
 420
 421 /**
 422  * Create a media for an already open file descriptor.
 423  * The file descriptor shall be open for reading (or reading and writing).
 424  *
 425  * Regular file descriptors, pipe read descriptors and character device
 426  * descriptors (including TTYs) are supported on all platforms.
 427  * Block device descriptors are supported where available.
 428  * Directory descriptors are supported on systems that provide fdopendir().
 429  * Sockets are supported on all platforms where they are file descriptors,
 430  * i.e. all except Windows.
 431  *
 432  * \note This library will <b>not</b> automatically close the file descriptor
 433  * under any circumstance. Nevertheless, a file descriptor can usually only be
 434  * rendered once in a media player. To render it a second time, the file
 435  * descriptor should probably be rewound to the beginning with lseek().
 436  *
 437  * \see libvlc_media_release
 438  *
 439  * \version LibVLC 1.1.5 and later.
 440  *
 441  * \param p_instance the instance
 442  * \param fd open file descriptor
 443  * \return the newly created media or NULL on error
 444  */
 445 LIBVLC_API libvlc_media_t *libvlc_media_new_fd(
 446                                    libvlc_instance_t *p_instance,
 447                                    int fd );
 448
 449 /**
 450  * Create a media with custom callbacks to read the data from.
 451  *
 452  * \param instance LibVLC instance
 453  * \param open_cb callback to open the custom bitstream input media
 454  * \param read_cb callback to read data (must not be NULL)
 455  * \param seek_cb callback to seek, or NULL if seeking is not supported
 456  * \param close_cb callback to close the media, or NULL if unnecessary
 457  * \param opaque data pointer for the open callback
 458  *
 459  * \return the newly created media or NULL on error
 460  *
 461  * \note If open_cb is NULL, the opaque pointer will be passed to read_cb,
 462  * seek_cb and close_cb, and the stream size will be treated as unknown.
 463  *
 464  * \note The callbacks may be called asynchronously (from another thread).
 465  * A single stream instance need not be reentrant. However the open_cb needs to
 466  * be reentrant if the media is used by multiple player instances.
 467  *
 468  * \warning The callbacks may be used until all or any player instances
 469  * that were supplied the media item are stopped.
 470  *
 471  * \see libvlc_media_release
 472  *
 473  * \version LibVLC 3.0.0 and later.
 474  */
 475 LIBVLC_API libvlc_media_t *libvlc_media_new_callbacks(
 476                                    libvlc_instance_t *instance,
 477                                    libvlc_media_open_cb open_cb,
 478                                    libvlc_media_read_cb read_cb,
 479                                    libvlc_media_seek_cb seek_cb,
 480                                    libvlc_media_close_cb close_cb,
 481                                    void *opaque );
 482
 483 /**
 484  * Create a media as an empty node with a given name.
 485  *
 486  * \see libvlc_media_release
 487  *
 488  * \param p_instance the instance
 489  * \param psz_name the name of the node
 490  * \return the new empty media or NULL on error
 491  */
 492 LIBVLC_API libvlc_media_t *libvlc_media_new_as_node(
 493                                    libvlc_instance_t *p_instance,
 494                                    const char * psz_name );
 495
 496 /**
 497  * Add an option to the media.
 498  *
 499  * This option will be used to determine how the media_player will
 500  * read the media. This allows to use VLC's advanced
 501  * reading/streaming options on a per-media basis.
 502  *
 503  * \note The options are listed in 'vlc --long-help' from the command line,
 504  * e.g. "-sout-all". Keep in mind that available options and their semantics
 505  * vary across LibVLC versions and builds.
 506  * \warning Not all options affects libvlc_media_t objects:
 507  * Specifically, due to architectural issues most audio and video options,
 508  * such as text renderer options, have no effects on an individual media.
 509  * These options must be set through libvlc_new() instead.
 510  *
 511  * \param p_md the media descriptor
 512  * \param psz_options the options (as a string)
 513  */
 514 LIBVLC_API void libvlc_media_add_option(
 515                                    libvlc_media_t *p_md,
 516                                    const char * psz_options );
 517
 518 /**
 519  * Add an option to the media with configurable flags.
 520  *
 521  * This option will be used to determine how the media_player will
 522  * read the media. This allows to use VLC's advanced
 523  * reading/streaming options on a per-media basis.
 524  *
 525  * The options are detailed in vlc --long-help, for instance
 526  * "--sout-all". Note that all options are not usable on medias:
 527  * specifically, due to architectural issues, video-related options
 528  * such as text renderer options cannot be set on a single media. They
 529  * must be set on the whole libvlc instance instead.
 530  *
 531  * \param p_md the media descriptor
 532  * \param psz_options the options (as a string)
 533  * \param i_flags the flags for this option
 534  */
 535 LIBVLC_API void libvlc_media_add_option_flag(
 536                                    libvlc_media_t *p_md,
 537                                    const char * psz_options,
 538                                    unsigned i_flags );
 539
 540
 541 /**
 542  * Retain a reference to a media descriptor object (libvlc_media_t). Use
 543  * libvlc_media_release() to decrement the reference count of a
 544  * media descriptor object.
 545  *
 546  * \param p_md the media descriptor
 547  */
 548 LIBVLC_API void libvlc_media_retain( libvlc_media_t *p_md );
 549
 550 /**
 551  * Decrement the reference count of a media descriptor object. If the
 552  * reference count is 0, then libvlc_media_release() will release the
 553  * media descriptor object. It will send out an libvlc_MediaFreed event
 554  * to all listeners. If the media descriptor object has been released it
 555  * should not be used again.
 556  *
 557  * \param p_md the media descriptor
 558  */
 559 LIBVLC_API void libvlc_media_release( libvlc_media_t *p_md );
 560
 561
 562 /**
 563  * Get the media resource locator (mrl) from a media descriptor object
 564  *
 565  * \param p_md a media descriptor object
 566  * \return string with mrl of media descriptor object
 567  */
 568 LIBVLC_API char *libvlc_media_get_mrl( libvlc_media_t *p_md );
 569
 570 /**
 571  * Duplicate a media descriptor object.
 572  *
 573  * \param p_md a media descriptor object.
 574  */
 575 LIBVLC_API libvlc_media_t *libvlc_media_duplicate( libvlc_media_t *p_md );
 576
 577 /**
 578  * Read the meta of the media.
 579  *
 580  * If the media has not yet been parsed this will return NULL.
 581  *
 582  * \see libvlc_media_parse
 583  * \see libvlc_media_parse_with_options
 584  * \see libvlc_MediaMetaChanged
 585  *
 586  * \param p_md the media descriptor
 587  * \param e_meta the meta to read
 588  * \return the media's meta
 589  */
 590 LIBVLC_API char *libvlc_media_get_meta( libvlc_media_t *p_md,
 591                                              libvlc_meta_t e_meta );
 592
 593 /**
 594  * Set the meta of the media (this function will not save the meta, call
 595  * libvlc_media_save_meta in order to save the meta)
 596  *
 597  * \param p_md the media descriptor
 598  * \param e_meta the meta to write
 599  * \param psz_value the media's meta
 600  */
 601 LIBVLC_API void libvlc_media_set_meta( libvlc_media_t *p_md,
 602                                            libvlc_meta_t e_meta,
 603                                            const char *psz_value );
 604
 605
 606 /**
 607  * Save the meta previously set
 608  *
 609  * \param p_md the media desriptor
 610  * \return true if the write operation was successful
 611  */
 612 LIBVLC_API int libvlc_media_save_meta( libvlc_media_t *p_md );
 613
 614
 615 /**
 616  * Get current state of media descriptor object. Possible media states are
 617  * libvlc_NothingSpecial=0, libvlc_Opening, libvlc_Playing, libvlc_Paused,
 618  * libvlc_Stopped, libvlc_Ended, libvlc_Error.
 619  *
 620  * \see libvlc_state_t
 621  * \param p_md a media descriptor object
 622  * \return state of media descriptor object
 623  */
 624 LIBVLC_API libvlc_state_t libvlc_media_get_state(
 625                                    libvlc_media_t *p_md );
 626
 627
 628 /**
 629  * Get the current statistics about the media
 630  * \param p_md: media descriptor object
 631  * \param p_stats: structure that contain the statistics about the media
 632  *                 (this structure must be allocated by the caller)
 633  * \return true if the statistics are available, false otherwise
 634  *
 635  * \libvlc_return_bool
 636  */
 637 LIBVLC_API int libvlc_media_get_stats( libvlc_media_t *p_md,
 638                                            libvlc_media_stats_t *p_stats );
 639
 640 /* The following method uses libvlc_media_list_t, however, media_list usage is optionnal
 641  * and this is here for convenience */
 642 #define VLC_FORWARD_DECLARE_OBJECT(a) struct a
 643
 644 /**
 645  * Get subitems of media descriptor object. This will increment
 646  * the reference count of supplied media descriptor object. Use
 647  * libvlc_media_list_release() to decrement the reference counting.
 648  *
 649  * \param p_md media descriptor object
 650  * \return list of media descriptor subitems or NULL
 651  */
 652 LIBVLC_API VLC_FORWARD_DECLARE_OBJECT(libvlc_media_list_t *)
 653 libvlc_media_subitems( libvlc_media_t *p_md );
 654
 655 /**
 656  * Get event manager from media descriptor object.
 657  * NOTE: this function doesn't increment reference counting.
 658  *
 659  * \param p_md a media descriptor object
 660  * \return event manager object
 661  */
 662 LIBVLC_API libvlc_event_manager_t *
 663     libvlc_media_event_manager( libvlc_media_t *p_md );
 664
 665 /**
 666  * Get duration (in ms) of media descriptor object item.
 667  *
 668  * \param p_md media descriptor object
 669  * \return duration of media item or -1 on error
 670  */
 671 LIBVLC_API libvlc_time_t
 672    libvlc_media_get_duration( libvlc_media_t *p_md );
 673
 674 /**
 675  * Parse the media asynchronously with options.
 676  *
 677  * This fetches (local or network) art, meta data and/or tracks information.
 678  * This method is the extended version of libvlc_media_parse_with_options().
 679  *
 680  * To track when this is over you can listen to libvlc_MediaParsedChanged
 681  * event. However if this functions returns an error, you will not receive any
 682  * events.
 683  *
 684  * It uses a flag to specify parse options (see libvlc_media_parse_flag_t). All
 685  * these flags can be combined. By default, media is parsed if it's a local
 686  * file.
 687  *
 688  * \note Parsing can be aborted with libvlc_media_parse_stop().
 689  *
 690  * \see libvlc_MediaParsedChanged
 691  * \see libvlc_media_get_meta
 692  * \see libvlc_media_tracks_get
 693  * \see libvlc_media_get_parsed_status
 694  * \see libvlc_media_parse_flag_t
 695  *
 696  * \param p_md media descriptor object
 697  * \param parse_flag parse options:
 698  * \param timeout maximum time allowed to preparse the media. If -1, the
 699  * default "preparse-timeout" option will be used as a timeout. If 0, it will
 700  * wait indefinitely. If > 0, the timeout will be used (in milliseconds).
 701  * \return -1 in case of error, 0 otherwise
 702  * \version LibVLC 3.0.0 or later
 703  */
 704 LIBVLC_API int
 705 libvlc_media_parse_with_options( libvlc_media_t *p_md,
 706                                  libvlc_media_parse_flag_t parse_flag,
 707                                  int timeout );
 708
 709 /**
 710  * Stop the parsing of the media
 711  *
 712  * When the media parsing is stopped, the libvlc_MediaParsedChanged event will
 713  * be sent with the libvlc_media_parsed_status_timeout status.
 714  *
 715  * \see libvlc_media_parse_with_options
 716  *
 717  * \param p_md media descriptor object
 718  * \version LibVLC 3.0.0 or later
 719  */
 720 LIBVLC_API void
 721 libvlc_media_parse_stop( libvlc_media_t *p_md );
 722
 723 /**
 724  * Get Parsed status for media descriptor object.
 725  *
 726  * \see libvlc_MediaParsedChanged
 727  * \see libvlc_media_parsed_status_t
 728  *
 729  * \param p_md media descriptor object
 730  * \return a value of the libvlc_media_parsed_status_t enum
 731  * \version LibVLC 3.0.0 or later
 732  */
 733 LIBVLC_API libvlc_media_parsed_status_t
 734    libvlc_media_get_parsed_status( libvlc_media_t *p_md );
 735
 736 /**
 737  * Sets media descriptor's user_data. user_data is specialized data
 738  * accessed by the host application, VLC.framework uses it as a pointer to
 739  * an native object that references a libvlc_media_t pointer
 740  *
 741  * \param p_md media descriptor object
 742  * \param p_new_user_data pointer to user data
 743  */
 744 LIBVLC_API void
 745     libvlc_media_set_user_data( libvlc_media_t *p_md, void *p_new_user_data );
 746
 747 /**
 748  * Get media descriptor's user_data. user_data is specialized data
 749  * accessed by the host application, VLC.framework uses it as a pointer to
 750  * an native object that references a libvlc_media_t pointer
 751  *
 752  * \param p_md media descriptor object
 753  */
 754 LIBVLC_API void *libvlc_media_get_user_data( libvlc_media_t *p_md );
 755
 756 /**
 757  * Get media descriptor's elementary streams description
 758  *
 759  * Note, you need to call libvlc_media_parse() or play the media at least once
 760  * before calling this function.
 761  * Not doing this will result in an empty array.
 762  *
 763  * \version LibVLC 2.1.0 and later.
 764  *
 765  * \param p_md media descriptor object
 766  * \param tracks address to store an allocated array of Elementary Streams
 767  *        descriptions (must be freed with libvlc_media_tracks_release
 768           by the caller) [OUT]
 769  *
 770  * \return the number of Elementary Streams (zero on error)
 771  */
 772 LIBVLC_API
 773 unsigned libvlc_media_tracks_get( libvlc_media_t *p_md,
 774                                   libvlc_media_track_t ***tracks );
 775
 776 /**
 777  * Get codec description from media elementary stream
 778  *
 779  * \version LibVLC 3.0.0 and later.
 780  *
 781  * \see libvlc_media_track_t
 782  *
 783  * \param i_type i_type from libvlc_media_track_t
 784  * \param i_codec i_codec or i_original_fourcc from libvlc_media_track_t
 785  *
 786  * \return codec description
 787  */
 788 LIBVLC_API
 789 const char *libvlc_media_get_codec_description( libvlc_track_type_t i_type,
 790                                                 uint32_t i_codec );
 791
 792 /**
 793  * Release media descriptor's elementary streams description array
 794  *
 795  * \version LibVLC 2.1.0 and later.
 796  *
 797  * \param p_tracks tracks info array to release
 798  * \param i_count number of elements in the array
 799  */
 800 LIBVLC_API
 801 void libvlc_media_tracks_release( libvlc_media_track_t **p_tracks,
 802                                   unsigned i_count );
 803
 804 /**
 805  * Get the media type of the media descriptor object
 806  *
 807  * \version LibVLC 3.0.0 and later.
 808  *
 809  * \see libvlc_media_type_t
 810  *
 811  * \param p_md media descriptor object
 812  *
 813  * \return media type
 814  */
 815 LIBVLC_API
 816 libvlc_media_type_t libvlc_media_get_type( libvlc_media_t *p_md );
 817
 818 /**
 819  * Add a slave to the current media.
 820  *
 821  * A slave is an external input source that may contains an additional subtitle
 822  * track (like a .srt) or an additional audio track (like a .ac3).
 823  *
 824  * \note This function must be called before the media is parsed (via
 825  * libvlc_media_parse_with_options()) or before the media is played (via
 826  * libvlc_media_player_play())
 827  *
 828  * \version LibVLC 3.0.0 and later.
 829  *
 830  * \param p_md media descriptor object
 831  * \param i_type subtitle or audio
 832  * \param i_priority from 0 (low priority) to 4 (high priority)
 833  * \param psz_uri Uri of the slave (should contain a valid scheme).
 834  *
 835  * \return 0 on success, -1 on error.
 836  */
 837 LIBVLC_API
 838 int libvlc_media_slaves_add( libvlc_media_t *p_md,
 839                              libvlc_media_slave_type_t i_type,
 840                              unsigned int i_priority,
 841                              const char *psz_uri );
 842
 843 /**
 844  * Clear all slaves previously added by libvlc_media_slaves_add() or
 845  * internally.
 846  *
 847  * \version LibVLC 3.0.0 and later.
 848  *
 849  * \param p_md media descriptor object
 850  */
 851 LIBVLC_API
 852 void libvlc_media_slaves_clear( libvlc_media_t *p_md );
 853
 854 /**
 855  * Get a media descriptor's slave list
 856  *
 857  * The list will contain slaves parsed by VLC or previously added by
 858  * libvlc_media_slaves_add(). The typical use case of this function is to save
 859  * a list of slave in a database for a later use.
 860  *
 861  * \version LibVLC 3.0.0 and later.
 862  *
 863  * \see libvlc_media_slaves_add
 864  *
 865  * \param p_md media descriptor object
 866  * \param ppp_slaves address to store an allocated array of slaves (must be
 867  * freed with libvlc_media_slaves_release()) [OUT]
 868  *
 869  * \return the number of slaves (zero on error)
 870  */
 871 LIBVLC_API
 872 unsigned int libvlc_media_slaves_get( libvlc_media_t *p_md,
 873                                       libvlc_media_slave_t ***ppp_slaves );
 874
 875 /**
 876  * Release a media descriptor's slave list
 877  *
 878  * \version LibVLC 3.0.0 and later.
 879  *
 880  * \param pp_slaves slave array to release
 881  * \param i_count number of elements in the array
 882  */
 883 LIBVLC_API
 884 void libvlc_media_slaves_release( libvlc_media_slave_t **pp_slaves,
 885                                   unsigned int i_count );
 886
 887 /** @}*/
 888
 889 # ifdef __cplusplus
 890 }
 891 # endif
 892
 893 #endif /* VLC_LIBVLC_MEDIA_H */