1 /*****************************************************************************
2 * libvlc_media.h: libvlc external API
3 *****************************************************************************
4 * Copyright (C) 1998-2009 VLC authors and VideoLAN
6 * Authors: Clément Stenac <zorglub@videolan.org>
7 * Jean-Paul Saman <jpsaman@videolan.org>
8 * Pierre d'Herbemont <pdherbemont@videolan.org>
10 * This program is free software; you can redistribute it and/or modify it
11 * under the terms of the GNU Lesser General Public License as published by
12 * the Free Software Foundation; either version 2.1 of the License, or
13 * (at your option) any later version.
15 * This program is distributed in the hope that it will be useful,
16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 * GNU Lesser General Public License for more details.
20 * You should have received a copy of the GNU Lesser General Public License
21 * along with this program; if not, write to the Free Software Foundation,
22 * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
23 *****************************************************************************/
25 #ifndef VLC_LIBVLC_MEDIA_H
26 #define VLC_LIBVLC_MEDIA_H 1
28 #include <vlc/libvlc_media_track.h>
36 /** \defgroup libvlc_media LibVLC media
38 * @ref libvlc_media_t is an abstract representation of a playable media.
39 * It consists of a media location and various optional meta data.
42 * LibVLC media item/descriptor external API
45 typedef struct libvlc_media_t libvlc_media_t
;
47 /** Meta data types */
48 typedef enum libvlc_meta_t
{
52 libvlc_meta_Copyright
,
54 libvlc_meta_TrackNumber
,
55 libvlc_meta_Description
,
61 libvlc_meta_NowPlaying
,
62 libvlc_meta_Publisher
,
63 libvlc_meta_EncodedBy
,
64 libvlc_meta_ArtworkURL
,
66 libvlc_meta_TrackTotal
,
72 libvlc_meta_AlbumArtist
,
73 libvlc_meta_DiscNumber
,
75 /* Add new meta types HERE */
79 * Note the order of libvlc_state_t enum must match exactly the order of
80 * \see mediacontrol_PlayerStatus, \see input_state_e enums,
81 * and VideoLAN.LibVLC.State (at bindings/cil/src/media.cs).
83 * Expected states by web plugins are:
84 * IDLE/CLOSE=0, OPENING=1, PLAYING=3, PAUSED=4,
85 * STOPPING=5, ENDED=6, ERROR=7
87 typedef enum libvlc_state_t
89 libvlc_NothingSpecial
=0,
91 libvlc_Buffering
, /* XXX: Deprecated value. Check the
92 * libvlc_MediaPlayerBuffering event to know the
93 * buffering state of a libvlc_media_player */
103 libvlc_media_option_trusted
= 0x2,
104 libvlc_media_option_unique
= 0x100
107 typedef struct libvlc_media_stats_t
111 float f_input_bitrate
;
114 int i_demux_read_bytes
;
115 float f_demux_bitrate
;
116 int i_demux_corrupted
;
117 int i_demux_discontinuity
;
124 int i_displayed_pictures
;
129 int i_played_abuffers
;
131 } libvlc_media_stats_t
;
136 * \see libvlc_media_get_type
138 typedef enum libvlc_media_type_t
{
139 libvlc_media_type_unknown
,
140 libvlc_media_type_file
,
141 libvlc_media_type_directory
,
142 libvlc_media_type_disc
,
143 libvlc_media_type_stream
,
144 libvlc_media_type_playlist
,
145 } libvlc_media_type_t
;
148 * Parse flags used by libvlc_media_parse_with_options()
150 * \see libvlc_media_parse_with_options
152 typedef enum libvlc_media_parse_flag_t
155 * Parse media if it's a local file
157 libvlc_media_parse_local
= 0x00,
159 * Parse media even if it's a network file
161 libvlc_media_parse_network
= 0x01,
163 * Fetch meta and covert art using local resources
165 libvlc_media_fetch_local
= 0x02,
167 * Fetch meta and covert art using network resources
169 libvlc_media_fetch_network
= 0x04,
171 * Interact with the user (via libvlc_dialog_cbs) when preparsing this item
172 * (and not its sub items). Set this flag in order to receive a callback
173 * when the input is asking for credentials.
175 libvlc_media_do_interact
= 0x08,
176 } libvlc_media_parse_flag_t
;
179 * Parse status used sent by libvlc_media_parse_with_options() or returned by
180 * libvlc_media_get_parsed_status()
182 * \see libvlc_media_parse_with_options
183 * \see libvlc_media_get_parsed_status
185 typedef enum libvlc_media_parsed_status_t
187 libvlc_media_parsed_status_skipped
= 1,
188 libvlc_media_parsed_status_failed
,
189 libvlc_media_parsed_status_timeout
,
190 libvlc_media_parsed_status_done
,
191 } libvlc_media_parsed_status_t
;
194 * Type of a media slave: subtitle or audio.
196 typedef enum libvlc_media_slave_type_t
198 libvlc_media_slave_type_subtitle
,
199 libvlc_media_slave_type_audio
,
200 } libvlc_media_slave_type_t
;
203 * A slave of a libvlc_media_t
204 * \see libvlc_media_slaves_get
206 typedef struct libvlc_media_slave_t
209 libvlc_media_slave_type_t i_type
;
210 unsigned int i_priority
;
211 } libvlc_media_slave_t
;
214 * Callback prototype to open a custom bitstream input media.
216 * The same media item can be opened multiple times. Each time, this callback
217 * is invoked. It should allocate and initialize any instance-specific
218 * resources, then store them in *datap. The instance resources can be freed
219 * in the @ref libvlc_media_close_cb callback.
221 * \param opaque private pointer as passed to libvlc_media_new_callbacks()
222 * \param datap storage space for a private data pointer [OUT]
223 * \param sizep byte length of the bitstream or UINT64_MAX if unknown [OUT]
225 * \note For convenience, *datap is initially NULL and *sizep is initially 0.
227 * \return 0 on success, non-zero on error. In case of failure, the other
228 * callbacks will not be invoked and any value stored in *datap and *sizep is
231 typedef int (*libvlc_media_open_cb
)(void *opaque
, void **datap
,
235 * Callback prototype to read data from a custom bitstream input media.
237 * \param opaque private pointer as set by the @ref libvlc_media_open_cb
239 * \param buf start address of the buffer to read data into
240 * \param len bytes length of the buffer
242 * \return strictly positive number of bytes read, 0 on end-of-stream,
243 * or -1 on non-recoverable error
245 * \note If no data is immediately available, then the callback should sleep.
246 * \warning The application is responsible for avoiding deadlock situations.
248 typedef ssize_t (*libvlc_media_read_cb
)(void *opaque
, unsigned char *buf
,
252 * Callback prototype to seek a custom bitstream input media.
254 * \param opaque private pointer as set by the @ref libvlc_media_open_cb
256 * \param offset absolute byte offset to seek to
257 * \return 0 on success, -1 on error.
259 typedef int (*libvlc_media_seek_cb
)(void *opaque
, uint64_t offset
);
262 * Callback prototype to close a custom bitstream input media.
264 * \param opaque private pointer as set by the @ref libvlc_media_open_cb
267 typedef void (*libvlc_media_close_cb
)(void *opaque
);
270 * Create a media with a certain given media resource location,
271 * for instance a valid URL.
273 * \note To refer to a local file with this function,
274 * the file://... URI syntax <b>must</b> be used (see IETF RFC3986).
275 * We recommend using libvlc_media_new_path() instead when dealing with
278 * \see libvlc_media_release
280 * \param p_instance the instance
281 * \param psz_mrl the media location
282 * \return the newly created media or NULL on error
284 LIBVLC_API libvlc_media_t
*libvlc_media_new_location(
285 libvlc_instance_t
*p_instance
,
286 const char * psz_mrl
);
289 * Create a media for a certain file path.
291 * \see libvlc_media_release
293 * \param p_instance the instance
294 * \param path local filesystem path
295 * \return the newly created media or NULL on error
297 LIBVLC_API libvlc_media_t
*libvlc_media_new_path(
298 libvlc_instance_t
*p_instance
,
302 * Create a media for an already open file descriptor.
303 * The file descriptor shall be open for reading (or reading and writing).
305 * Regular file descriptors, pipe read descriptors and character device
306 * descriptors (including TTYs) are supported on all platforms.
307 * Block device descriptors are supported where available.
308 * Directory descriptors are supported on systems that provide fdopendir().
309 * Sockets are supported on all platforms where they are file descriptors,
310 * i.e. all except Windows.
312 * \note This library will <b>not</b> automatically close the file descriptor
313 * under any circumstance. Nevertheless, a file descriptor can usually only be
314 * rendered once in a media player. To render it a second time, the file
315 * descriptor should probably be rewound to the beginning with lseek().
317 * \see libvlc_media_release
319 * \version LibVLC 1.1.5 and later.
321 * \param p_instance the instance
322 * \param fd open file descriptor
323 * \return the newly created media or NULL on error
325 LIBVLC_API libvlc_media_t
*libvlc_media_new_fd(
326 libvlc_instance_t
*p_instance
,
330 * Create a media with custom callbacks to read the data from.
332 * \param instance LibVLC instance
333 * \param open_cb callback to open the custom bitstream input media
334 * \param read_cb callback to read data (must not be NULL)
335 * \param seek_cb callback to seek, or NULL if seeking is not supported
336 * \param close_cb callback to close the media, or NULL if unnecessary
337 * \param opaque data pointer for the open callback
339 * \return the newly created media or NULL on error
341 * \note If open_cb is NULL, the opaque pointer will be passed to read_cb,
342 * seek_cb and close_cb, and the stream size will be treated as unknown.
344 * \note The callbacks may be called asynchronously (from another thread).
345 * A single stream instance need not be reentrant. However the open_cb needs to
346 * be reentrant if the media is used by multiple player instances.
348 * \warning The callbacks may be used until all or any player instances
349 * that were supplied the media item are stopped.
351 * \see libvlc_media_release
353 * \version LibVLC 3.0.0 and later.
355 LIBVLC_API libvlc_media_t
*libvlc_media_new_callbacks(
356 libvlc_instance_t
*instance
,
357 libvlc_media_open_cb open_cb
,
358 libvlc_media_read_cb read_cb
,
359 libvlc_media_seek_cb seek_cb
,
360 libvlc_media_close_cb close_cb
,
364 * Create a media as an empty node with a given name.
366 * \see libvlc_media_release
368 * \param p_instance the instance
369 * \param psz_name the name of the node
370 * \return the new empty media or NULL on error
372 LIBVLC_API libvlc_media_t
*libvlc_media_new_as_node(
373 libvlc_instance_t
*p_instance
,
374 const char * psz_name
);
377 * Add an option to the media.
379 * This option will be used to determine how the media_player will
380 * read the media. This allows to use VLC's advanced
381 * reading/streaming options on a per-media basis.
383 * \note The options are listed in 'vlc --longhelp' from the command line,
384 * e.g. "--sout-all". Keep in mind that available options and their semantics
385 * vary across LibVLC versions and builds.
386 * \warning Not all options affects libvlc_media_t objects:
387 * Specifically, due to architectural issues most audio and video options,
388 * such as text renderer options, have no effects on an individual media.
389 * These options must be set through libvlc_new() instead.
391 * \param p_md the media descriptor
392 * \param psz_options the options (as a string)
394 LIBVLC_API
void libvlc_media_add_option(
395 libvlc_media_t
*p_md
,
396 const char * psz_options
);
399 * Add an option to the media with configurable flags.
401 * This option will be used to determine how the media_player will
402 * read the media. This allows to use VLC's advanced
403 * reading/streaming options on a per-media basis.
405 * The options are detailed in vlc --longhelp, for instance
406 * "--sout-all". Note that all options are not usable on medias:
407 * specifically, due to architectural issues, video-related options
408 * such as text renderer options cannot be set on a single media. They
409 * must be set on the whole libvlc instance instead.
411 * \param p_md the media descriptor
412 * \param psz_options the options (as a string)
413 * \param i_flags the flags for this option
415 LIBVLC_API
void libvlc_media_add_option_flag(
416 libvlc_media_t
*p_md
,
417 const char * psz_options
,
422 * Retain a reference to a media descriptor object (libvlc_media_t). Use
423 * libvlc_media_release() to decrement the reference count of a
424 * media descriptor object.
426 * \param p_md the media descriptor
428 LIBVLC_API
void libvlc_media_retain( libvlc_media_t
*p_md
);
431 * Decrement the reference count of a media descriptor object. If the
432 * reference count is 0, then libvlc_media_release() will release the
433 * media descriptor object. It will send out an libvlc_MediaFreed event
434 * to all listeners. If the media descriptor object has been released it
435 * should not be used again.
437 * \param p_md the media descriptor
439 LIBVLC_API
void libvlc_media_release( libvlc_media_t
*p_md
);
443 * Get the media resource locator (mrl) from a media descriptor object
445 * \param p_md a media descriptor object
446 * \return string with mrl of media descriptor object
448 LIBVLC_API
char *libvlc_media_get_mrl( libvlc_media_t
*p_md
);
451 * Duplicate a media descriptor object.
453 * \warning the duplicated media won't share forthcoming updates from the
456 * \param p_md a media descriptor object.
458 LIBVLC_API libvlc_media_t
*libvlc_media_duplicate( libvlc_media_t
*p_md
);
461 * Read the meta of the media.
463 * Note, you need to call libvlc_media_parse_with_options() or play the media
464 * at least once before calling this function.
465 * If the media has not yet been parsed this will return NULL.
467 * \see libvlc_media_parse_with_options
468 * \see libvlc_MediaMetaChanged
470 * \param p_md the media descriptor
471 * \param e_meta the meta to read
472 * \return the media's meta
474 LIBVLC_API
char *libvlc_media_get_meta( libvlc_media_t
*p_md
,
475 libvlc_meta_t e_meta
);
478 * Set the meta of the media (this function will not save the meta, call
479 * libvlc_media_save_meta in order to save the meta)
481 * \param p_md the media descriptor
482 * \param e_meta the meta to write
483 * \param psz_value the media's meta
485 LIBVLC_API
void libvlc_media_set_meta( libvlc_media_t
*p_md
,
486 libvlc_meta_t e_meta
,
487 const char *psz_value
);
491 * Save the meta previously set
493 * \param p_md the media desriptor
494 * \return true if the write operation was successful
496 LIBVLC_API
int libvlc_media_save_meta( libvlc_media_t
*p_md
);
500 * Get current state of media descriptor object. Possible media states are
501 * libvlc_NothingSpecial=0, libvlc_Opening, libvlc_Playing, libvlc_Paused,
502 * libvlc_Stopped, libvlc_Ended, libvlc_Error.
504 * \see libvlc_state_t
505 * \param p_md a media descriptor object
506 * \return state of media descriptor object
508 LIBVLC_API libvlc_state_t
libvlc_media_get_state(
509 libvlc_media_t
*p_md
);
513 * Get the current statistics about the media
514 * \param p_md: media descriptor object
515 * \param p_stats: structure that contain the statistics about the media
516 * (this structure must be allocated by the caller)
517 * \retval true statistics are available
518 * \retval false otherwise
520 LIBVLC_API
bool libvlc_media_get_stats(libvlc_media_t
*p_md
,
521 libvlc_media_stats_t
*p_stats
);
523 /* The following method uses libvlc_media_list_t, however, media_list usage is optionnal
524 * and this is here for convenience */
525 #define VLC_FORWARD_DECLARE_OBJECT(a) struct a
528 * Get subitems of media descriptor object. This will increment
529 * the reference count of supplied media descriptor object. Use
530 * libvlc_media_list_release() to decrement the reference counting.
532 * \param p_md media descriptor object
533 * \return list of media descriptor subitems or NULL
535 LIBVLC_API
VLC_FORWARD_DECLARE_OBJECT(libvlc_media_list_t
*)
536 libvlc_media_subitems( libvlc_media_t
*p_md
);
539 * Get event manager from media descriptor object.
540 * NOTE: this function doesn't increment reference counting.
542 * \param p_md a media descriptor object
543 * \return event manager object
545 LIBVLC_API libvlc_event_manager_t
*
546 libvlc_media_event_manager( libvlc_media_t
*p_md
);
549 * Get duration (in ms) of media descriptor object item.
551 * Note, you need to call libvlc_media_parse_with_options() or play the media
552 * at least once before calling this function.
553 * Not doing this will result in an undefined result.
555 * \see libvlc_media_parse_with_options
557 * \param p_md media descriptor object
558 * \return duration of media item or -1 on error
560 LIBVLC_API libvlc_time_t
561 libvlc_media_get_duration( libvlc_media_t
*p_md
);
564 * Parse the media asynchronously with options.
566 * This fetches (local or network) art, meta data and/or tracks information.
568 * To track when this is over you can listen to libvlc_MediaParsedChanged
569 * event. However if this functions returns an error, you will not receive any
572 * It uses a flag to specify parse options (see libvlc_media_parse_flag_t). All
573 * these flags can be combined. By default, media is parsed if it's a local
576 * \note Parsing can be aborted with libvlc_media_parse_stop().
578 * \see libvlc_MediaParsedChanged
579 * \see libvlc_media_get_meta
580 * \see libvlc_media_get_tracklist
581 * \see libvlc_media_get_parsed_status
582 * \see libvlc_media_parse_flag_t
584 * \param p_md media descriptor object
585 * \param parse_flag parse options:
586 * \param timeout maximum time allowed to preparse the media. If -1, the
587 * default "preparse-timeout" option will be used as a timeout. If 0, it will
588 * wait indefinitely. If > 0, the timeout will be used (in milliseconds).
589 * \return -1 in case of error, 0 otherwise
590 * \version LibVLC 3.0.0 or later
593 libvlc_media_parse_with_options( libvlc_media_t
*p_md
,
594 libvlc_media_parse_flag_t parse_flag
,
598 * Stop the parsing of the media
600 * When the media parsing is stopped, the libvlc_MediaParsedChanged event will
601 * be sent with the libvlc_media_parsed_status_timeout status.
603 * \see libvlc_media_parse_with_options
605 * \param p_md media descriptor object
606 * \version LibVLC 3.0.0 or later
609 libvlc_media_parse_stop( libvlc_media_t
*p_md
);
612 * Get Parsed status for media descriptor object.
614 * \see libvlc_MediaParsedChanged
615 * \see libvlc_media_parsed_status_t
616 * \see libvlc_media_parse_with_options
618 * \param p_md media descriptor object
619 * \return a value of the libvlc_media_parsed_status_t enum
620 * \version LibVLC 3.0.0 or later
622 LIBVLC_API libvlc_media_parsed_status_t
623 libvlc_media_get_parsed_status( libvlc_media_t
*p_md
);
626 * Sets media descriptor's user_data. user_data is specialized data
627 * accessed by the host application, VLC.framework uses it as a pointer to
628 * an native object that references a libvlc_media_t pointer
630 * \param p_md media descriptor object
631 * \param p_new_user_data pointer to user data
634 libvlc_media_set_user_data( libvlc_media_t
*p_md
, void *p_new_user_data
);
637 * Get media descriptor's user_data. user_data is specialized data
638 * accessed by the host application, VLC.framework uses it as a pointer to
639 * an native object that references a libvlc_media_t pointer
641 * \see libvlc_media_set_user_data
643 * \param p_md media descriptor object
645 LIBVLC_API
void *libvlc_media_get_user_data( libvlc_media_t
*p_md
);
648 * Get the track list for one type
650 * \version LibVLC 4.0.0 and later.
652 * \note You need to call libvlc_media_parse_with_options() or play the media
653 * at least once before calling this function. Not doing this will result in
656 * \see libvlc_media_parse_with_options
657 * \see libvlc_media_tracklist_count
658 * \see libvlc_media_tracklist_at
660 * \param p_md media descriptor object
661 * \param type type of the track list to request
663 * \return a valid libvlc_media_tracklist_t or NULL in case of error, if there
664 * is no track for a category, the returned list will have a size of 0, delete
665 * with libvlc_media_tracklist_delete()
667 LIBVLC_API libvlc_media_tracklist_t
*
668 libvlc_media_get_tracklist( libvlc_media_t
*p_md
, libvlc_track_type_t type
);
671 * Get codec description from media elementary stream
673 * Note, you need to call libvlc_media_parse_with_options() or play the media
674 * at least once before calling this function.
676 * \version LibVLC 3.0.0 and later.
678 * \see libvlc_media_track_t
679 * \see libvlc_media_parse_with_options
681 * \param i_type i_type from libvlc_media_track_t
682 * \param i_codec i_codec or i_original_fourcc from libvlc_media_track_t
684 * \return codec description
687 const char *libvlc_media_get_codec_description( libvlc_track_type_t i_type
,
691 * Get the media type of the media descriptor object
693 * \version LibVLC 3.0.0 and later.
695 * \see libvlc_media_type_t
697 * \param p_md media descriptor object
702 libvlc_media_type_t
libvlc_media_get_type( libvlc_media_t
*p_md
);
705 * \brief libvlc_media_thumbnail_request_t An opaque thumbnail request object
707 typedef struct libvlc_media_thumbnail_request_t libvlc_media_thumbnail_request_t
;
709 typedef enum libvlc_thumbnailer_seek_speed_t
711 libvlc_media_thumbnail_seek_precise
,
712 libvlc_media_thumbnail_seek_fast
,
713 } libvlc_thumbnailer_seek_speed_t
;
716 * \brief libvlc_media_get_thumbnail_by_time Start an asynchronous thumbnail generation
718 * If the request is successfuly queued, the libvlc_MediaThumbnailGenerated
719 * is guaranteed to be emited.
720 * The resulting thumbnail size can either be:
721 * - Hardcoded by providing both width & height. In which case, the image will
722 * be stretched to match the provided aspect ratio, or cropped if crop is true.
723 * - Derived from the media aspect ratio if only width or height is provided and
724 * the other one is set to 0.
726 * \param md media descriptor object
727 * \param time The time at which the thumbnail should be generated
728 * \param speed The seeking speed \sa{libvlc_thumbnailer_seek_speed_t}
729 * \param width The thumbnail width
730 * \param height the thumbnail height
731 * \param crop Should the picture be cropped to preserve source aspect ratio
732 * \param picture_type The thumbnail picture type \sa{libvlc_picture_type_t}
733 * \param timeout A timeout value in ms, or 0 to disable timeout
735 * \return A valid opaque request object, or NULL in case of failure.
736 * It may be cancelled by libvlc_media_thumbnail_request_cancel().
737 * It must be released by libvlc_media_thumbnail_request_destroy().
739 * \version libvlc 4.0 or later
741 * \see libvlc_picture_t
742 * \see libvlc_picture_type_t
744 LIBVLC_API libvlc_media_thumbnail_request_t
*
745 libvlc_media_thumbnail_request_by_time( libvlc_media_t
*md
,
747 libvlc_thumbnailer_seek_speed_t speed
,
748 unsigned int width
, unsigned int height
,
749 bool crop
, libvlc_picture_type_t picture_type
,
750 libvlc_time_t timeout
);
753 * \brief libvlc_media_get_thumbnail_by_pos Start an asynchronous thumbnail generation
755 * If the request is successfuly queued, the libvlc_MediaThumbnailGenerated
756 * is guaranteed to be emited.
757 * The resulting thumbnail size can either be:
758 * - Hardcoded by providing both width & height. In which case, the image will
759 * be stretched to match the provided aspect ratio, or cropped if crop is true.
760 * - Derived from the media aspect ratio if only width or height is provided and
761 * the other one is set to 0.
763 * \param md media descriptor object
764 * \param pos The position at which the thumbnail should be generated
765 * \param speed The seeking speed \sa{libvlc_thumbnailer_seek_speed_t}
766 * \param width The thumbnail width
767 * \param height the thumbnail height
768 * \param crop Should the picture be cropped to preserve source aspect ratio
769 * \param picture_type The thumbnail picture type \sa{libvlc_picture_type_t}
770 * \param timeout A timeout value in ms, or 0 to disable timeout
772 * \return A valid opaque request object, or NULL in case of failure.
773 * It may be cancelled by libvlc_media_thumbnail_request_cancel().
774 * It must be released by libvlc_media_thumbnail_request_destroy().
776 * \version libvlc 4.0 or later
778 * \see libvlc_picture_t
779 * \see libvlc_picture_type_t
781 LIBVLC_API libvlc_media_thumbnail_request_t
*
782 libvlc_media_thumbnail_request_by_pos( libvlc_media_t
*md
,
784 libvlc_thumbnailer_seek_speed_t speed
,
785 unsigned int width
, unsigned int height
,
786 bool crop
, libvlc_picture_type_t picture_type
,
787 libvlc_time_t timeout
);
790 * @brief libvlc_media_thumbnail_cancel cancels a thumbnailing request
791 * @param p_req An opaque thumbnail request object.
793 * Cancelling the request will still cause libvlc_MediaThumbnailGenerated event
794 * to be emited, with a NULL libvlc_picture_t
795 * If the request is cancelled after its completion, the behavior is undefined.
798 libvlc_media_thumbnail_request_cancel( libvlc_media_thumbnail_request_t
*p_req
);
801 * @brief libvlc_media_thumbnail_destroy destroys a thumbnail request
802 * @param p_req An opaque thumbnail request object.
804 * If the request has not completed or hasn't been cancelled yet, the behavior
808 libvlc_media_thumbnail_request_destroy( libvlc_media_thumbnail_request_t
*p_req
);
811 * Add a slave to the current media.
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).
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())
820 * \version LibVLC 3.0.0 and later.
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).
827 * \return 0 on success, -1 on error.
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
);
836 * Clear all slaves previously added by libvlc_media_slaves_add() or
839 * \version LibVLC 3.0.0 and later.
841 * \param p_md media descriptor object
844 void libvlc_media_slaves_clear( libvlc_media_t
*p_md
);
847 * Get a media descriptor's slave list
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.
853 * \version LibVLC 3.0.0 and later.
855 * \see libvlc_media_slaves_add
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]
861 * \return the number of slaves (zero on error)
864 unsigned int libvlc_media_slaves_get( libvlc_media_t
*p_md
,
865 libvlc_media_slave_t
***ppp_slaves
);
868 * Release a media descriptor's slave list
870 * \version LibVLC 3.0.0 and later.
872 * \param pp_slaves slave array to release
873 * \param i_count number of elements in the array
876 void libvlc_media_slaves_release( libvlc_media_slave_t
**pp_slaves
,
877 unsigned int i_count
);
885 #endif /* VLC_LIBVLC_MEDIA_H */