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
30extern "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
42typedef struct libvlc_media_t libvlc_media_t;
43
44/** Meta data types */
45typedef 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 */
84typedef 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
98enum
99{
100 libvlc_media_option_trusted = 0x2,
101 libvlc_media_option_unique = 0x100
102};
103
104typedef 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
112typedef 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
142typedef 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
169typedef struct libvlc_audio_track_t
170{
171 unsigned i_channels;
172 unsigned i_rate;
173} libvlc_audio_track_t;
174
175typedef 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
187typedef 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 */
200typedef 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
208typedef 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
222typedef struct libvlc_subtitle_track_t
223{
224 char *psz_encoding;
225} libvlc_subtitle_track_t;
226
227typedef 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 */
256typedef 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 */
270typedef 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 */
303typedef 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 */
314typedef 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 */
324typedef 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 */
349typedef 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 */
368typedef 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 */
379typedef 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 */
387typedef 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 */
404LIBVLC_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 */
417LIBVLC_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 */
445LIBVLC_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 */
475LIBVLC_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 */
492LIBVLC_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 */
514LIBVLC_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 */
535LIBVLC_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 */
548LIBVLC_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 */
559LIBVLC_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 */
568LIBVLC_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 */
575LIBVLC_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 */
590LIBVLC_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 */
601LIBVLC_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 */
612LIBVLC_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 */
624LIBVLC_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 */
637LIBVLC_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 */
652LIBVLC_API VLC_FORWARD_DECLARE_OBJECT(libvlc_media_list_t *)
653libvlc_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 */
662LIBVLC_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 */
671LIBVLC_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 */
704LIBVLC_API int
705libvlc_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 */
720LIBVLC_API void
721libvlc_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 */
733LIBVLC_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 */
744LIBVLC_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 */
754LIBVLC_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 */
772LIBVLC_API
773unsigned 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 */
788LIBVLC_API
789const 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 */
800LIBVLC_API
801void 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 */
815LIBVLC_API
816libvlc_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 */
837LIBVLC_API
838int 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 */
851LIBVLC_API
852void 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 */
871LIBVLC_API
872unsigned 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 */
883LIBVLC_API
884void 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

source code of include/vlc/libvlc_media.h