1 /***************************************************************************** 2 * libvlc_media.h: libvlc external API 3 ***************************************************************************** 4 * Copyright (C) 1998-2009 VLC authors and VideoLAN 5 * $Id: 383f366b6940f7b3d89f5945e015793833ea541f $ 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 */ 894