LibVLC media

libvlc_media_t is an abstract representation of a playable media. More...

Collaboration diagram for LibVLC media:

Files
file	libvlc_media.h
	LibVLC media item/descriptor external API.

Data Structures
struct	libvlc_media_stats_t
struct	libvlc_media_slave_t
	A slave of a libvlc_media_t. More...

Macros
#define	libvlc_media_filestat_mtime   0
	Type of stat that can be requested from libvlc_media_get_filestat()
#define	libvlc_media_filestat_size   1
#define	VLC_FORWARD_DECLARE_OBJECT(a)   struct a

Typedefs
typedef struct libvlc_media_t	libvlc_media_t
typedef enum libvlc_meta_t	libvlc_meta_t
	Meta data types.
typedef enum libvlc_state_t	libvlc_state_t
	libvlc media or media_player state
typedef struct libvlc_media_stats_t	libvlc_media_stats_t
typedef enum libvlc_media_type_t	libvlc_media_type_t
	Media type.
typedef enum libvlc_media_parse_flag_t	libvlc_media_parse_flag_t
	Parse flags used by libvlc_media_parse_request()
typedef enum libvlc_media_parsed_status_t	libvlc_media_parsed_status_t
	Parse status used sent by libvlc_media_parse_request() or returned by libvlc_media_get_parsed_status()
typedef enum libvlc_media_slave_type_t	libvlc_media_slave_type_t
	Type of a media slave: subtitle or audio.
typedef struct libvlc_media_slave_t	libvlc_media_slave_t
	A slave of a libvlc_media_t.
typedef int(*	libvlc_media_open_cb) (void *opaque, void **datap, uint64_t *sizep)
	Callback prototype to open a custom bitstream input media.
typedef ptrdiff_t(*	libvlc_media_read_cb) (void *opaque, unsigned char *buf, size_t len)
	Callback prototype to read data from a custom bitstream input media.
typedef int(*	libvlc_media_seek_cb) (void *opaque, uint64_t offset)
	Callback prototype to seek a custom bitstream input media.
typedef void(*	libvlc_media_close_cb) (void *opaque)
	Callback prototype to close a custom bitstream input media.
typedef struct libvlc_media_thumbnail_request_t	libvlc_media_thumbnail_request_t
	libvlc_media_thumbnail_request_t An opaque thumbnail request object
typedef enum libvlc_thumbnailer_seek_speed_t	libvlc_thumbnailer_seek_speed_t

Enumerations
enum	libvlc_meta_t {   libvlc_meta_Title , libvlc_meta_Artist , libvlc_meta_Genre , libvlc_meta_Copyright ,   libvlc_meta_Album , libvlc_meta_TrackNumber , libvlc_meta_Description , libvlc_meta_Rating ,   libvlc_meta_Date , libvlc_meta_Setting , libvlc_meta_URL , libvlc_meta_Language ,   libvlc_meta_NowPlaying , libvlc_meta_Publisher , libvlc_meta_EncodedBy , libvlc_meta_ArtworkURL ,   libvlc_meta_TrackID , libvlc_meta_TrackTotal , libvlc_meta_Director , libvlc_meta_Season ,   libvlc_meta_Episode , libvlc_meta_ShowName , libvlc_meta_Actors , libvlc_meta_AlbumArtist ,   libvlc_meta_DiscNumber , libvlc_meta_DiscTotal }
	Meta data types. More...
enum	libvlc_state_t {   libvlc_NothingSpecial =0 , libvlc_Opening , libvlc_Buffering , libvlc_Playing ,   libvlc_Paused , libvlc_Stopped , libvlc_Stopping , libvlc_Error }
	libvlc media or media_player state More...
enum	{ libvlc_media_option_trusted = 0x2 , libvlc_media_option_unique = 0x100 }
enum	libvlc_media_type_t {   libvlc_media_type_unknown , libvlc_media_type_file , libvlc_media_type_directory , libvlc_media_type_disc ,   libvlc_media_type_stream , libvlc_media_type_playlist }
	Media type. More...
enum	libvlc_media_parse_flag_t {   libvlc_media_parse_local = 0x01 , libvlc_media_parse_network = 0x02 , libvlc_media_parse_forced = 0x04 , libvlc_media_fetch_local = 0x08 ,   libvlc_media_fetch_network = 0x10 , libvlc_media_do_interact = 0x20 }
	Parse flags used by libvlc_media_parse_request() More...
enum	libvlc_media_parsed_status_t {   libvlc_media_parsed_status_none , libvlc_media_parsed_status_pending , libvlc_media_parsed_status_skipped , libvlc_media_parsed_status_failed ,   libvlc_media_parsed_status_timeout , libvlc_media_parsed_status_cancelled , libvlc_media_parsed_status_done }
	Parse status used sent by libvlc_media_parse_request() or returned by libvlc_media_get_parsed_status() More...
enum	libvlc_media_slave_type_t { libvlc_media_slave_type_subtitle , libvlc_media_slave_type_generic , libvlc_media_slave_type_audio = libvlc_media_slave_type_generic }
	Type of a media slave: subtitle or audio. More...
enum	libvlc_thumbnailer_seek_speed_t { libvlc_media_thumbnail_seek_precise , libvlc_media_thumbnail_seek_fast }

Functions
LIBVLC_API libvlc_media_t *	libvlc_media_new_location (const char *psz_mrl)
	Create a media with a certain given media resource location, for instance a valid URL.
LIBVLC_API libvlc_media_t *	libvlc_media_new_path (const char *path)
	Create a media for a certain file path.
LIBVLC_API libvlc_media_t *	libvlc_media_new_fd (int fd)
	Create a media for an already open file descriptor.
LIBVLC_API libvlc_media_t *	libvlc_media_new_callbacks (libvlc_media_open_cb open_cb, libvlc_media_read_cb read_cb, libvlc_media_seek_cb seek_cb, libvlc_media_close_cb close_cb, void *opaque)
	Create a media with custom callbacks to read the data from.
LIBVLC_API libvlc_media_t *	libvlc_media_new_as_node (const char *psz_name)
	Create a media as an empty node with a given name.
LIBVLC_API void	libvlc_media_add_option (libvlc_media_t *p_md, const char *psz_options)
	Add an option to the media.
LIBVLC_API void	libvlc_media_add_option_flag (libvlc_media_t *p_md, const char *psz_options, unsigned i_flags)
	Add an option to the media with configurable flags.
LIBVLC_API libvlc_media_t *	libvlc_media_retain (libvlc_media_t *p_md)
	Retain a reference to a media descriptor object (libvlc_media_t).
LIBVLC_API void	libvlc_media_release (libvlc_media_t *p_md)
	Decrement the reference count of a media descriptor object.
LIBVLC_API char *	libvlc_media_get_mrl (libvlc_media_t *p_md)
	Get the media resource locator (mrl) from a media descriptor object.
LIBVLC_API libvlc_media_t *	libvlc_media_duplicate (libvlc_media_t *p_md)
	Duplicate a media descriptor object.
LIBVLC_API char *	libvlc_media_get_meta (libvlc_media_t *p_md, libvlc_meta_t e_meta)
	Read the meta of the media.
LIBVLC_API void	libvlc_media_set_meta (libvlc_media_t *p_md, libvlc_meta_t e_meta, const char *psz_value)
	Set the meta of the media (this function will not save the meta, call libvlc_media_save_meta in order to save the meta)
LIBVLC_API char *	libvlc_media_get_meta_extra (libvlc_media_t *p_md, const char *psz_name)
	Read the meta extra of the media.
LIBVLC_API void	libvlc_media_set_meta_extra (libvlc_media_t *p_md, const char *psz_name, const char *psz_value)
	Set the meta of the media (this function will not save the meta, call libvlc_media_save_meta in order to save the meta)
LIBVLC_API unsigned	libvlc_media_get_meta_extra_names (libvlc_media_t *p_md, char ***pppsz_names)
	Read the meta extra names of the media.
LIBVLC_API void	libvlc_media_meta_extra_names_release (char **ppsz_names, unsigned i_count)
	Release a media meta extra names.
LIBVLC_API int	libvlc_media_save_meta (libvlc_instance_t *inst, libvlc_media_t *p_md)
	Save the meta previously set.
LIBVLC_API bool	libvlc_media_get_stats (libvlc_media_t *p_md, libvlc_media_stats_t *p_stats)
	Get the current statistics about the media.
LIBVLC_API struct libvlc_media_list_t *	libvlc_media_subitems (libvlc_media_t *p_md)
	Get subitems of media descriptor object.
LIBVLC_API libvlc_event_manager_t *	libvlc_media_event_manager (libvlc_media_t *p_md)
	Get event manager from media descriptor object.
LIBVLC_API libvlc_time_t	libvlc_media_get_duration (libvlc_media_t *p_md)
	Get duration (in ms) of media descriptor object item.
LIBVLC_API int	libvlc_media_get_filestat (libvlc_media_t *p_md, unsigned type, uint64_t *out)
	Get a 'stat' value of media descriptor object item.
LIBVLC_API int	libvlc_media_parse_request (libvlc_instance_t *inst, libvlc_media_t *p_md, libvlc_media_parse_flag_t parse_flag, int timeout)
	Parse the media asynchronously with options.
LIBVLC_API void	libvlc_media_parse_stop (libvlc_instance_t *inst, libvlc_media_t *p_md)
	Stop the parsing of the media.
LIBVLC_API libvlc_media_parsed_status_t	libvlc_media_get_parsed_status (libvlc_media_t *p_md)
	Get Parsed status for media descriptor object.
LIBVLC_API void	libvlc_media_set_user_data (libvlc_media_t *p_md, void *p_new_user_data)
	Sets media descriptor's user_data.
LIBVLC_API void *	libvlc_media_get_user_data (libvlc_media_t *p_md)
	Get media descriptor's user_data.
LIBVLC_API libvlc_media_tracklist_t *	libvlc_media_get_tracklist (libvlc_media_t *p_md, libvlc_track_type_t type)
	Get the track list for one type.
LIBVLC_API const char *	libvlc_media_get_codec_description (libvlc_track_type_t i_type, uint32_t i_codec)
	Get codec description from media elementary stream.
LIBVLC_API libvlc_media_type_t	libvlc_media_get_type (libvlc_media_t *p_md)
	Get the media type of the media descriptor object.
LIBVLC_API libvlc_media_thumbnail_request_t *	libvlc_media_thumbnail_request_by_time (libvlc_instance_t *inst, libvlc_media_t *md, libvlc_time_t time, libvlc_thumbnailer_seek_speed_t speed, unsigned int width, unsigned int height, bool crop, libvlc_picture_type_t picture_type, libvlc_time_t timeout)
	libvlc_media_request_thumbnail_by_time Start an asynchronous thumbnail generation
LIBVLC_API libvlc_media_thumbnail_request_t *	libvlc_media_thumbnail_request_by_pos (libvlc_instance_t *inst, libvlc_media_t *md, double pos, libvlc_thumbnailer_seek_speed_t speed, unsigned int width, unsigned int height, bool crop, libvlc_picture_type_t picture_type, libvlc_time_t timeout)
	libvlc_media_request_thumbnail_by_pos Start an asynchronous thumbnail generation
LIBVLC_API void	libvlc_media_thumbnail_request_destroy (libvlc_media_thumbnail_request_t *p_req)
	libvlc_media_thumbnail_destroy destroys a thumbnail request
LIBVLC_API int	libvlc_media_slaves_add (libvlc_media_t *p_md, libvlc_media_slave_type_t i_type, unsigned int i_priority, const char *psz_uri)
	Add a slave to the current media.
LIBVLC_API void	libvlc_media_slaves_clear (libvlc_media_t *p_md)
	Clear all slaves previously added by libvlc_media_slaves_add() or internally.
LIBVLC_API unsigned int	libvlc_media_slaves_get (libvlc_media_t *p_md, libvlc_media_slave_t ***ppp_slaves)
	Get a media descriptor's slave list.
LIBVLC_API void	libvlc_media_slaves_release (libvlc_media_slave_t **pp_slaves, unsigned int i_count)
	Release a media descriptor's slave list.

Detailed Description

libvlc_media_t is an abstract representation of a playable media.

It consists of a media location and various optional meta data.

Macro Definition Documentation

libvlc_media_filestat_mtime

#define libvlc_media_filestat_mtime   0

Type of stat that can be requested from libvlc_media_get_filestat()

libvlc_media_filestat_size

#define libvlc_media_filestat_size   1

VLC_FORWARD_DECLARE_OBJECT

#define VLC_FORWARD_DECLARE_OBJECT

(

a

)

struct a

Typedef Documentation

libvlc_media_close_cb

typedef void(* libvlc_media_close_cb) (void *opaque)

Callback prototype to close a custom bitstream input media.

Parameters

opaque

private pointer as set by the libvlc_media_open_cb callback

libvlc_media_open_cb

typedef int(* libvlc_media_open_cb) (void *opaque, void **datap, uint64_t *sizep)

Callback prototype to open a custom bitstream input media.

The same media item can be opened multiple times. Each time, this callback is invoked. It should allocate and initialize any instance-specific resources, then store them in *datap. The instance resources can be freed in the libvlc_media_close_cb callback.

Parameters

opaque	private pointer as passed to libvlc_media_new_callbacks()
datap	storage space for a private data pointer [OUT]
sizep	byte length of the bitstream or UINT64_MAX if unknown [OUT]

Note

For convenience, *datap is initially NULL and *sizep is initially 0.

Returns

0 on success, non-zero on error. In case of failure, the other callbacks will not be invoked and any value stored in *datap and *sizep is discarded.

libvlc_media_parse_flag_t

typedef enum libvlc_media_parse_flag_t libvlc_media_parse_flag_t

Parse flags used by libvlc_media_parse_request()

libvlc_media_parsed_status_t

typedef enum libvlc_media_parsed_status_t libvlc_media_parsed_status_t

Parse status used sent by libvlc_media_parse_request() or returned by libvlc_media_get_parsed_status()

libvlc_media_read_cb

typedef ptrdiff_t(* libvlc_media_read_cb) (void *opaque, unsigned char *buf, size_t len)

Callback prototype to read data from a custom bitstream input media.

Parameters

opaque	private pointer as set by the libvlc_media_open_cb callback
buf	start address of the buffer to read data into
len	bytes length of the buffer

Returns

strictly positive number of bytes read, 0 on end-of-stream, or -1 on non-recoverable error

Note

If no data is immediately available, then the callback should sleep.

Warning

The application is responsible for avoiding deadlock situations.

libvlc_media_seek_cb

typedef int(* libvlc_media_seek_cb) (void *opaque, uint64_t offset)

Callback prototype to seek a custom bitstream input media.

Parameters

opaque	private pointer as set by the libvlc_media_open_cb callback
offset	absolute byte offset to seek to

Returns

0 on success, -1 on error.

libvlc_media_slave_t

typedef struct libvlc_media_slave_t libvlc_media_slave_t

A slave of a libvlc_media_t.

See also

libvlc_media_slaves_get

libvlc_media_slave_type_t

typedef enum libvlc_media_slave_type_t libvlc_media_slave_type_t

Type of a media slave: subtitle or audio.

libvlc_media_stats_t

typedef struct libvlc_media_stats_t libvlc_media_stats_t

libvlc_media_t

typedef struct libvlc_media_t libvlc_media_t

libvlc_media_thumbnail_request_t

typedef struct libvlc_media_thumbnail_request_t libvlc_media_thumbnail_request_t

libvlc_media_thumbnail_request_t An opaque thumbnail request object

libvlc_media_type_t

typedef enum libvlc_media_type_t libvlc_media_type_t

Media type.

See also

libvlc_media_get_type

libvlc_meta_t

typedef enum libvlc_meta_t libvlc_meta_t

Meta data types.

libvlc_state_t

typedef enum libvlc_state_t libvlc_state_t

libvlc media or media_player state

libvlc_thumbnailer_seek_speed_t

typedef enum libvlc_thumbnailer_seek_speed_t libvlc_thumbnailer_seek_speed_t

Enumeration Type Documentation

anonymous enum

anonymous enum

Enumerator
libvlc_media_option_trusted
libvlc_media_option_unique

libvlc_media_parse_flag_t

enum libvlc_media_parse_flag_t

Parse flags used by libvlc_media_parse_request()

Enumerator
libvlc_media_parse_local	Parse media if it's a local file.
libvlc_media_parse_network	Parse media even if it's a network file.
libvlc_media_parse_forced	Force parsing the media even if it would be skipped.
libvlc_media_fetch_local	Fetch meta and cover art using local resources.
libvlc_media_fetch_network	Fetch meta and cover art using network resources.
libvlc_media_do_interact	Interact with the user (via libvlc_dialog_cbs) when preparsing this item (and not its sub items). Set this flag in order to receive a callback when the input is asking for credentials.

libvlc_media_parsed_status_t

enum libvlc_media_parsed_status_t

Parse status used sent by libvlc_media_parse_request() or returned by libvlc_media_get_parsed_status()

Enumerator
libvlc_media_parsed_status_none
libvlc_media_parsed_status_pending
libvlc_media_parsed_status_skipped
libvlc_media_parsed_status_failed
libvlc_media_parsed_status_timeout
libvlc_media_parsed_status_cancelled
libvlc_media_parsed_status_done

libvlc_media_slave_type_t

enum libvlc_media_slave_type_t

Type of a media slave: subtitle or audio.

Enumerator
libvlc_media_slave_type_subtitle
libvlc_media_slave_type_generic
libvlc_media_slave_type_audio

libvlc_media_type_t

enum libvlc_media_type_t

Media type.

See also

libvlc_media_get_type

Enumerator
libvlc_media_type_unknown
libvlc_media_type_file
libvlc_media_type_directory
libvlc_media_type_disc
libvlc_media_type_stream
libvlc_media_type_playlist

libvlc_meta_t

enum libvlc_meta_t

Meta data types.

Enumerator
libvlc_meta_Title
libvlc_meta_Artist
libvlc_meta_Genre
libvlc_meta_Copyright
libvlc_meta_Album
libvlc_meta_TrackNumber
libvlc_meta_Description
libvlc_meta_Rating
libvlc_meta_Date
libvlc_meta_Setting
libvlc_meta_URL
libvlc_meta_Language
libvlc_meta_NowPlaying
libvlc_meta_Publisher
libvlc_meta_EncodedBy
libvlc_meta_ArtworkURL
libvlc_meta_TrackID
libvlc_meta_TrackTotal
libvlc_meta_Director
libvlc_meta_Season
libvlc_meta_Episode
libvlc_meta_ShowName
libvlc_meta_Actors
libvlc_meta_AlbumArtist
libvlc_meta_DiscNumber
libvlc_meta_DiscTotal

libvlc_state_t

enum libvlc_state_t

libvlc media or media_player state

Enumerator
libvlc_NothingSpecial
libvlc_Opening
libvlc_Buffering
libvlc_Playing
libvlc_Paused
libvlc_Stopped
libvlc_Stopping
libvlc_Error

libvlc_thumbnailer_seek_speed_t

enum libvlc_thumbnailer_seek_speed_t

Enumerator
libvlc_media_thumbnail_seek_precise
libvlc_media_thumbnail_seek_fast

Function Documentation

libvlc_media_add_option()

LIBVLC_API void libvlc_media_add_option	(	libvlc_media_t *	p_md,
		const char *	psz_options
	)

Add an option to the media.

This option will be used to determine how the media_player will read the media. This allows to use VLC's advanced reading/streaming options on a per-media basis.

Note

The options are listed in 'vlc –longhelp' from the command line, e.g. "--sout-all". Keep in mind that available options and their semantics vary across LibVLC versions and builds.

Warning

Not all options affects libvlc_media_t objects: Specifically, due to architectural issues most audio and video options, such as text renderer options, have no effects on an individual media. These options must be set through libvlc_new() instead.

Parameters

p_md	the media descriptor
psz_options	the options (as a string)

libvlc_media_add_option_flag()

LIBVLC_API void libvlc_media_add_option_flag	(	libvlc_media_t *	p_md,
		const char *	psz_options,
		unsigned	i_flags
	)

Add an option to the media with configurable flags.

This option will be used to determine how the media_player will read the media. This allows to use VLC's advanced reading/streaming options on a per-media basis.

The options are detailed in vlc –longhelp, for instance "--sout-all". Note that all options are not usable on medias: specifically, due to architectural issues, video-related options such as text renderer options cannot be set on a single media. They must be set on the whole libvlc instance instead.

Parameters

p_md	the media descriptor
psz_options	the options (as a string)
i_flags	the flags for this option

libvlc_media_duplicate()

LIBVLC_API libvlc_media_t * libvlc_media_duplicate

(

libvlc_media_t *

p_md

)

Duplicate a media descriptor object.

Warning

the duplicated media won't share forthcoming updates from the original one.

Parameters

p_md	a media descriptor object.

libvlc_media_event_manager()

LIBVLC_API libvlc_event_manager_t * libvlc_media_event_manager

(

libvlc_media_t *

p_md

)

Get event manager from media descriptor object.

NOTE: this function doesn't increment reference counting.

Parameters

p_md	a media descriptor object

Returns

event manager object

libvlc_media_get_codec_description()

LIBVLC_API const char * libvlc_media_get_codec_description	(	libvlc_track_type_t	i_type,
		uint32_t	i_codec
	)

Get codec description from media elementary stream.

Note, you need to call libvlc_media_parse_request() or play the media at least once before calling this function.

Version

LibVLC 3.0.0 and later.

See also

libvlc_media_track_t

Parameters

i_type	i_type from libvlc_media_track_t
i_codec	i_codec or i_original_fourcc from libvlc_media_track_t

Returns

codec description

libvlc_media_get_duration()

LIBVLC_API libvlc_time_t libvlc_media_get_duration

(

libvlc_media_t *

p_md

)

Get duration (in ms) of media descriptor object item.

Note, you need to call libvlc_media_parse_request() or play the media at least once before calling this function. Not doing this will result in an undefined result.

Parameters

p_md	media descriptor object

Returns

duration of media item or -1 on error

libvlc_media_get_filestat()

LIBVLC_API int libvlc_media_get_filestat	(	libvlc_media_t *	p_md,
		unsigned	type,
		uint64_t *	out
	)

Get a 'stat' value of media descriptor object item.

Note

'stat' values are currently only parsed by directory accesses. This mean that only sub medias of a directory media, parsed with libvlc_media_parse_request() can have valid 'stat' properties.

Version

LibVLC 4.0.0 and later.

Parameters

p_md	media descriptor object
type	a valid libvlc_media_stat_ define
out	field in which the value will be stored

Returns

1 on success, 0 if not found, -1 on error.

libvlc_media_get_meta()

LIBVLC_API char * libvlc_media_get_meta	(	libvlc_media_t *	p_md,
		libvlc_meta_t	e_meta
	)

Read the meta of the media.

Note, you need to call libvlc_media_parse_request() or play the media at least once before calling this function. If the media has not yet been parsed this will return NULL.

See also

libvlc_MediaMetaChanged

Parameters

p_md	the media descriptor
e_meta	the meta to read

Returns

the media's meta

libvlc_media_get_meta_extra()

LIBVLC_API char * libvlc_media_get_meta_extra	(	libvlc_media_t *	p_md,
		const char *	psz_name
	)

Read the meta extra of the media.

If the media has not yet been parsed this will return NULL.

See also

libvlc_media_parse

libvlc_media_parse_with_options

Parameters

p_md	the media descriptor
psz_name	the meta extra to read (nonnullable)

Returns

the media's meta extra or NULL

libvlc_media_get_meta_extra_names()

LIBVLC_API unsigned libvlc_media_get_meta_extra_names	(	libvlc_media_t *	p_md,
		char ***	pppsz_names
	)

Read the meta extra names of the media.

Parameters

p_md	the media descriptor
pppsz_names	the media's meta extra name array you can access the elements using the return value (count) must be released with libvlc_media_meta_extra_names_release()

Returns

the meta extra count

libvlc_media_get_mrl()

LIBVLC_API char * libvlc_media_get_mrl

(

libvlc_media_t *

p_md

)

Get the media resource locator (mrl) from a media descriptor object.

Parameters

p_md	a media descriptor object

Returns

string with mrl of media descriptor object

libvlc_media_get_parsed_status()

LIBVLC_API libvlc_media_parsed_status_t libvlc_media_get_parsed_status

(

libvlc_media_t *

p_md

)

Get Parsed status for media descriptor object.

See also

libvlc_MediaParsedChanged

libvlc_media_parsed_status_t

libvlc_media_parse_request()

Parameters

p_md	media descriptor object

Returns

a value of the libvlc_media_parsed_status_t enum

Version

LibVLC 3.0.0 or later

libvlc_media_get_stats()

LIBVLC_API bool libvlc_media_get_stats	(	libvlc_media_t *	p_md,
		libvlc_media_stats_t *	p_stats
	)

Get the current statistics about the media.

Parameters

p_md	media descriptor object
p_stats	structure that contain the statistics about the media (this structure must be allocated by the caller)

Return values

true	statistics are available
false	otherwise

libvlc_media_get_tracklist()

LIBVLC_API libvlc_media_tracklist_t * libvlc_media_get_tracklist	(	libvlc_media_t *	p_md,
		libvlc_track_type_t	type
	)

Get the track list for one type.

Version

LibVLC 4.0.0 and later.

Note

You need to call libvlc_media_parse_request() or play the media at least once before calling this function. Not doing this will result in an empty list.

See also

libvlc_media_tracklist_count

libvlc_media_tracklist_at

Parameters

p_md	media descriptor object
type	type of the track list to request

Returns

a valid libvlc_media_tracklist_t or NULL in case of error, if there is no track for a category, the returned list will have a size of 0, delete with libvlc_media_tracklist_delete()

libvlc_media_get_type()

LIBVLC_API libvlc_media_type_t libvlc_media_get_type

(

libvlc_media_t *

p_md

)

Get the media type of the media descriptor object.

Version

LibVLC 3.0.0 and later.

See also

libvlc_media_type_t

Parameters

p_md	media descriptor object

Returns

media type

libvlc_media_get_user_data()

LIBVLC_API void * libvlc_media_get_user_data

(

libvlc_media_t *

p_md

)

Get media descriptor's user_data.

user_data is specialized data accessed by the host application, VLC.framework uses it as a pointer to an native object that references a libvlc_media_t pointer

See also

libvlc_media_set_user_data

Parameters

p_md	media descriptor object

libvlc_media_meta_extra_names_release()

LIBVLC_API void libvlc_media_meta_extra_names_release	(	char **	ppsz_names,
		unsigned	i_count
	)

Release a media meta extra names.

Parameters

ppsz_names	meta extra names array to release
i_count	number of elements in the array

libvlc_media_new_as_node()

LIBVLC_API libvlc_media_t * libvlc_media_new_as_node

(

const char *

psz_name

)

Create a media as an empty node with a given name.

See also

libvlc_media_release

Parameters

psz_name

the name of the node

Returns

the new empty media or NULL on error

libvlc_media_new_callbacks()

LIBVLC_API libvlc_media_t * libvlc_media_new_callbacks	(	libvlc_media_open_cb	open_cb,
		libvlc_media_read_cb	read_cb,
		libvlc_media_seek_cb	seek_cb,
		libvlc_media_close_cb	close_cb,
		void *	opaque
	)

Create a media with custom callbacks to read the data from.

Parameters

open_cb	callback to open the custom bitstream input media
read_cb	callback to read data (must not be NULL)
seek_cb	callback to seek, or NULL if seeking is not supported
close_cb	callback to close the media, or NULL if unnecessary
opaque	data pointer for the open callback

Returns

the newly created media or NULL on error

Note

If open_cb is NULL, the opaque pointer will be passed to read_cb, seek_cb and close_cb, and the stream size will be treated as unknown.

The callbacks may be called asynchronously (from another thread). A single stream instance need not be reentrant. However the open_cb needs to be reentrant if the media is used by multiple player instances.

Warning

The callbacks may be used until all or any player instances that were supplied the media item are stopped.

See also

libvlc_media_release

Version

LibVLC 3.0.0 and later.

libvlc_media_new_fd()

LIBVLC_API libvlc_media_t * libvlc_media_new_fd

(

int

fd

)

Create a media for an already open file descriptor.

The file descriptor shall be open for reading (or reading and writing).

Regular file descriptors, pipe read descriptors and character device descriptors (including TTYs) are supported on all platforms. Block device descriptors are supported where available. Directory descriptors are supported on systems that provide fdopendir(). Sockets are supported on all platforms where they are file descriptors, i.e. all except Windows.

Note

This library will not automatically close the file descriptor under any circumstance. Nevertheless, a file descriptor can usually only be rendered once in a media player. To render it a second time, the file descriptor should probably be rewound to the beginning with lseek().

See also

libvlc_media_release

Version

LibVLC 1.1.5 and later.

Parameters

fd	open file descriptor

Returns

the newly created media or NULL on error

libvlc_media_new_location()

LIBVLC_API libvlc_media_t * libvlc_media_new_location

(

const char *

psz_mrl

)

Create a media with a certain given media resource location, for instance a valid URL.

Note

To refer to a local file with this function, the file://... URI syntax must be used (see IETF RFC3986). We recommend using libvlc_media_new_path() instead when dealing with local files.

See also

libvlc_media_release

Parameters

psz_mrl

the media location

Returns

the newly created media or NULL on error

libvlc_media_new_path()

LIBVLC_API libvlc_media_t * libvlc_media_new_path

(

const char *

path

)

Create a media for a certain file path.

See also

libvlc_media_release

Parameters

path	local filesystem path

Returns

the newly created media or NULL on error

libvlc_media_parse_request()

LIBVLC_API int libvlc_media_parse_request	(	libvlc_instance_t *	inst,
		libvlc_media_t *	p_md,
		libvlc_media_parse_flag_t	parse_flag,
		int	timeout
	)

Parse the media asynchronously with options.

This fetches (local or network) art, meta data and/or tracks information.

To track when this is over you can listen to libvlc_MediaParsedChanged event. However if this functions returns an error, you will not receive any events.

It uses a flag to specify parse options (see libvlc_media_parse_flag_t). All these flags can be combined. By default, media is parsed if it's a local file.

Note

Parsing can be aborted with libvlc_media_parse_stop().

See also

libvlc_MediaParsedChanged

libvlc_media_get_meta

libvlc_media_get_tracklist

libvlc_media_get_parsed_status

libvlc_media_parse_flag_t

Parameters

inst	LibVLC instance that is to parse the media
p_md	media descriptor object
parse_flag	parse options:
timeout	maximum time allowed to preparse the media. If -1, the default "preparse-timeout" option will be used as a timeout. If 0, it will wait indefinitely. If > 0, the timeout will be used (in milliseconds).

Returns

-1 in case of error, 0 otherwise

Version

LibVLC 4.0.0 or later

libvlc_media_parse_stop()

LIBVLC_API void libvlc_media_parse_stop	(	libvlc_instance_t *	inst,
		libvlc_media_t *	p_md
	)

Stop the parsing of the media.

When the media parsing is stopped, the libvlc_MediaParsedChanged event will be sent with the libvlc_media_parsed_status_timeout status.

See also

libvlc_media_parse_request()

Parameters

inst	LibVLC instance that is to cease or give up parsing the media
p_md	media descriptor object

Version

LibVLC 3.0.0 or later

libvlc_media_release()

LIBVLC_API void libvlc_media_release

(

libvlc_media_t *

p_md

)

Decrement the reference count of a media descriptor object.

If the reference count is 0, then libvlc_media_release() will release the media descriptor object. If the media descriptor object has been released it should not be used again.

Parameters

p_md	the media descriptor

libvlc_media_retain()

LIBVLC_API libvlc_media_t * libvlc_media_retain

(

libvlc_media_t *

p_md

)

Retain a reference to a media descriptor object (libvlc_media_t).

Use libvlc_media_release() to decrement the reference count of a media descriptor object.

Parameters

p_md	the media descriptor

Returns

the same object

libvlc_media_save_meta()

LIBVLC_API int libvlc_media_save_meta	(	libvlc_instance_t *	inst,
		libvlc_media_t *	p_md
	)

Save the meta previously set.

Parameters

inst	LibVLC instance
p_md	the media descriptor

Returns

true if the write operation was successful

libvlc_media_set_meta()

LIBVLC_API void libvlc_media_set_meta	(	libvlc_media_t *	p_md,
		libvlc_meta_t	e_meta,
		const char *	psz_value
	)

Set the meta of the media (this function will not save the meta, call libvlc_media_save_meta in order to save the meta)

Parameters

p_md	the media descriptor
e_meta	the meta to write
psz_value	the media's meta

libvlc_media_set_meta_extra()

LIBVLC_API void libvlc_media_set_meta_extra	(	libvlc_media_t *	p_md,
		const char *	psz_name,
		const char *	psz_value
	)

Set the meta of the media (this function will not save the meta, call libvlc_media_save_meta in order to save the meta)

Parameters

p_md	the media descriptor
psz_name	the meta extra to write (nonnullable)
psz_value	the media's meta extra (nullable) Removed from meta extra if set to NULL

libvlc_media_set_user_data()

LIBVLC_API void libvlc_media_set_user_data	(	libvlc_media_t *	p_md,
		void *	p_new_user_data
	)

Sets media descriptor's user_data.

user_data is specialized data accessed by the host application, VLC.framework uses it as a pointer to an native object that references a libvlc_media_t pointer

Parameters

p_md	media descriptor object
p_new_user_data	pointer to user data

libvlc_media_slaves_add()

LIBVLC_API int libvlc_media_slaves_add	(	libvlc_media_t *	p_md,
		libvlc_media_slave_type_t	i_type,
		unsigned int	i_priority,
		const char *	psz_uri
	)

Add a slave to the current media.

A slave is an external input source that may contains an additional subtitle track (like a .srt) or an additional audio track (like a .ac3).

Note

This function must be called before the media is parsed (via libvlc_media_parse_request()) or before the media is played (via libvlc_media_player_play())

Version

LibVLC 3.0.0 and later.

Parameters

p_md	media descriptor object
i_type	subtitle or audio
i_priority	from 0 (low priority) to 4 (high priority)
psz_uri	Uri of the slave (should contain a valid scheme).

Returns

0 on success, -1 on error.

libvlc_media_slaves_clear()

LIBVLC_API void libvlc_media_slaves_clear

(

libvlc_media_t *

p_md

)

Clear all slaves previously added by libvlc_media_slaves_add() or internally.

Version

LibVLC 3.0.0 and later.

Parameters

p_md	media descriptor object

libvlc_media_slaves_get()

LIBVLC_API unsigned int libvlc_media_slaves_get	(	libvlc_media_t *	p_md,
		libvlc_media_slave_t ***	ppp_slaves
	)

Get a media descriptor's slave list.

The list will contain slaves parsed by VLC or previously added by libvlc_media_slaves_add(). The typical use case of this function is to save a list of slave in a database for a later use.

Version

LibVLC 3.0.0 and later.

See also

libvlc_media_slaves_add

Parameters

p_md	media descriptor object
ppp_slaves	address to store an allocated array of slaves (must be freed with libvlc_media_slaves_release()) [OUT]

Returns

the number of slaves (zero on error)

libvlc_media_slaves_release()

LIBVLC_API void libvlc_media_slaves_release	(	libvlc_media_slave_t **	pp_slaves,
		unsigned int	i_count
	)

Release a media descriptor's slave list.

Version

LibVLC 3.0.0 and later.

Parameters

pp_slaves	slave array to release
i_count	number of elements in the array

libvlc_media_subitems()

LIBVLC_API struct libvlc_media_list_t * libvlc_media_subitems

(

libvlc_media_t *

p_md

)

Get subitems of media descriptor object.

This will increment the reference count of supplied media descriptor object. Use libvlc_media_list_release() to decrement the reference counting.

Parameters

p_md	media descriptor object

Returns

list of media descriptor subitems or NULL

libvlc_media_thumbnail_request_by_pos()

LIBVLC_API libvlc_media_thumbnail_request_t * libvlc_media_thumbnail_request_by_pos	(	libvlc_instance_t *	inst,
		libvlc_media_t *	md,
		double	pos,
		libvlc_thumbnailer_seek_speed_t	speed,
		unsigned int	width,
		unsigned int	height,
		bool	crop,
		libvlc_picture_type_t	picture_type,
		libvlc_time_t	timeout
	)

libvlc_media_request_thumbnail_by_pos Start an asynchronous thumbnail generation

If the request is successfully queued, the libvlc_MediaThumbnailGenerated is guaranteed to be emitted (except if the request is destroyed early by the user). The resulting thumbnail size can either be:

• Hardcoded by providing both width & height. In which case, the image will be stretched to match the provided aspect ratio, or cropped if crop is true.
• Derived from the media aspect ratio if only width or height is provided and the other one is set to 0.

Parameters

inst	LibVLC instance to generate the thumbnail with
md	media descriptor object
pos	The position at which the thumbnail should be generated
speed	The seeking speed

See also

{libvlc_thumbnailer_seek_speed_t}

Parameters

width	The thumbnail width
height	the thumbnail height
crop	Should the picture be cropped to preserve source aspect ratio
picture_type	The thumbnail picture type

See also

{libvlc_picture_type_t}

Parameters

timeout

A timeout value in ms, or 0 to disable timeout

Returns

A valid opaque request object, or NULL in case of failure. It must be released by libvlc_media_thumbnail_request_destroy().

Version

libvlc 4.0 or later

See also

libvlc_picture_t

libvlc_picture_type_t

libvlc_media_thumbnail_request_by_time()

LIBVLC_API libvlc_media_thumbnail_request_t * libvlc_media_thumbnail_request_by_time	(	libvlc_instance_t *	inst,
		libvlc_media_t *	md,
		libvlc_time_t	time,
		libvlc_thumbnailer_seek_speed_t	speed,
		unsigned int	width,
		unsigned int	height,
		bool	crop,
		libvlc_picture_type_t	picture_type,
		libvlc_time_t	timeout
	)

libvlc_media_request_thumbnail_by_time Start an asynchronous thumbnail generation

If the request is successfully queued, the libvlc_MediaThumbnailGenerated is guaranteed to be emitted (except if the request is destroyed early by the user). The resulting thumbnail size can either be:

• Hardcoded by providing both width & height. In which case, the image will be stretched to match the provided aspect ratio, or cropped if crop is true.
• Derived from the media aspect ratio if only width or height is provided and the other one is set to 0.

Parameters

inst	LibVLC instance to generate the thumbnail with
md	media descriptor object
time	The time at which the thumbnail should be generated
speed	The seeking speed

See also

{libvlc_thumbnailer_seek_speed_t}

Parameters

width	The thumbnail width
height	the thumbnail height
crop	Should the picture be cropped to preserve source aspect ratio
picture_type	The thumbnail picture type

See also

{libvlc_picture_type_t}

Parameters

timeout

A timeout value in ms, or 0 to disable timeout

Returns

A valid opaque request object, or NULL in case of failure. It must be released by libvlc_media_thumbnail_request_destroy() and can be cancelled by calling it early.

Version

libvlc 4.0 or later

See also

libvlc_picture_t

libvlc_picture_type_t

libvlc_media_thumbnail_request_destroy()

LIBVLC_API void libvlc_media_thumbnail_request_destroy

(

libvlc_media_thumbnail_request_t *

p_req

)

libvlc_media_thumbnail_destroy destroys a thumbnail request

Parameters

p_req

An opaque thumbnail request object.

This will also cancel the thumbnail request, no events will be emitted after this call.