VLC  3.0.0-git
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Data Structures | Macros | Typedefs | Enumerations | Functions
LibVLC media
LibVLC

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

Collaboration diagram for LibVLC media:

Data Structures

struct  libvlc_media_stats_t
 defgroup libvlc_media_stats_t LibVLC media statistics More...
struct  libvlc_media_track_info_t
struct  libvlc_audio_track_t
struct  libvlc_video_track_t
struct  libvlc_subtitle_track_t
struct  libvlc_media_track_t

Macros

#define VLC_FORWARD_DECLARE_OBJECT(a)   struct a

Typedefs

typedef struct libvlc_media_t libvlc_media_t
typedef enum libvlc_state_t libvlc_state_t
 Note the order of libvlc_state_t enum must match exactly the order of.
typedef enum libvlc_track_type_t libvlc_track_type_t
typedef struct
libvlc_media_track_info_t 
libvlc_media_track_info_t
typedef struct libvlc_audio_track_t libvlc_audio_track_t
typedef struct libvlc_video_track_t libvlc_video_track_t
typedef struct
libvlc_subtitle_track_t 
libvlc_subtitle_track_t
typedef struct libvlc_media_track_t libvlc_media_track_t

Enumerations

enum  libvlc_state_t {
  libvlc_NothingSpecial = 0, libvlc_Opening, libvlc_Buffering, libvlc_Playing,
  libvlc_Paused, libvlc_Stopped, libvlc_Ended, libvlc_Error
}
 Note the order of libvlc_state_t enum must match exactly the order of. More...
enum  { libvlc_media_option_trusted = 0x2, libvlc_media_option_unique = 0x100 }
enum  libvlc_track_type_t { libvlc_track_unknown = -1, libvlc_track_audio = 0, libvlc_track_video = 1, libvlc_track_text = 2 }

Functions

LIBVLC_API libvlc_media_tlibvlc_media_new_location (libvlc_instance_t *p_instance, const char *psz_mrl)
 Create a media with a certain given media resource location, for instance a valid URL.
LIBVLC_API libvlc_media_tlibvlc_media_new_path (libvlc_instance_t *p_instance, const char *path)
 Create a media for a certain file path.
LIBVLC_API libvlc_media_tlibvlc_media_new_fd (libvlc_instance_t *p_instance, int fd)
 Create a media for an already open file descriptor.
LIBVLC_API libvlc_media_tlibvlc_media_new_as_node (libvlc_instance_t *p_instance, 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 void 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_tlibvlc_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 int libvlc_media_save_meta (libvlc_media_t *p_md)
 Save the meta previously set.
LIBVLC_API libvlc_state_t libvlc_media_get_state (libvlc_media_t *p_md)
 Get current state of media descriptor object.
LIBVLC_API int 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_tlibvlc_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 void libvlc_media_parse (libvlc_media_t *p_md)
 Parse a media.
LIBVLC_API void libvlc_media_parse_async (libvlc_media_t *p_md)
 Parse a media.
LIBVLC_API int libvlc_media_is_parsed (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_DEPRECATED LIBVLC_API int libvlc_media_get_tracks_info (libvlc_media_t *p_md, libvlc_media_track_info_t **tracks)
 Get media descriptor's elementary streams description.
LIBVLC_API unsigned libvlc_media_tracks_get (libvlc_media_t *p_md, libvlc_media_track_t ***tracks)
 Get media descriptor's elementary streams description.
LIBVLC_API void libvlc_media_tracks_release (libvlc_media_track_t **p_tracks, unsigned i_count)
 Release media descriptor's elementary streams description array.
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
}
 defgroup libvlc_meta LibVLC meta data More...
typedef enum libvlc_meta_t libvlc_meta_t
 defgroup libvlc_meta LibVLC meta data
typedef struct libvlc_media_stats_t libvlc_media_stats_t
 defgroup libvlc_media_stats_t LibVLC media statistics

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

#define VLC_FORWARD_DECLARE_OBJECT (   a)    struct a

Typedef Documentation

defgroup libvlc_media_stats_t LibVLC media statistics

defgroup libvlc_meta LibVLC meta data

Meta data types

Note the order of libvlc_state_t enum must match exactly the order of.

See Also
mediacontrol_PlayerStatus,
input_state_e enums, and VideoLAN.LibVLC.State (at bindings/cil/src/media.cs).

Expected states by web plugins are: IDLE/CLOSE=0, OPENING=1, BUFFERING=2, PLAYING=3, PAUSED=4, STOPPING=5, ENDED=6, ERROR=7

Enumeration Type Documentation

anonymous enum
Enumerator:
libvlc_media_option_trusted 
libvlc_media_option_unique 

defgroup libvlc_meta LibVLC meta data

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 

Note the order of libvlc_state_t enum must match exactly the order of.

See Also
mediacontrol_PlayerStatus,
input_state_e enums, and VideoLAN.LibVLC.State (at bindings/cil/src/media.cs).

Expected states by web plugins are: IDLE/CLOSE=0, OPENING=1, BUFFERING=2, PLAYING=3, PAUSED=4, STOPPING=5, ENDED=6, ERROR=7

Enumerator:
libvlc_NothingSpecial 
libvlc_Opening 
libvlc_Buffering 
libvlc_Playing 
libvlc_Paused 
libvlc_Stopped 
libvlc_Ended 
libvlc_Error 
Enumerator:
libvlc_track_unknown 
libvlc_track_audio 
libvlc_track_video 
libvlc_track_text 

Function Documentation

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 –long-help' 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_mdthe media descriptor
psz_optionsthe options (as a string)
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 –long-help, 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_mdthe media descriptor
psz_optionsthe options (as a string)
i_flagsthe flags for this option
LIBVLC_API libvlc_media_t* libvlc_media_duplicate ( libvlc_media_t p_md)

Duplicate a media descriptor object.

Parameters
p_mda 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.

NOTE: this function doesn't increment reference counting.

Parameters
p_mda media descriptor object
Returns
event manager object
LIBVLC_API libvlc_time_t libvlc_media_get_duration ( libvlc_media_t p_md)

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

Parameters
p_mdmedia descriptor object
Returns
duration of media item or -1 on error
LIBVLC_API char* libvlc_media_get_meta ( libvlc_media_t p_md,
libvlc_meta_t  e_meta 
)

Read the meta of the media.

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

This methods automatically calls libvlc_media_parse_async(), so after calling it you may receive a libvlc_MediaMetaChanged event. If you prefer a synchronous version ensure that you call libvlc_media_parse() before get_meta().

See Also
libvlc_media_parse
libvlc_media_parse_async
libvlc_MediaMetaChanged
Parameters
p_mdthe media descriptor
e_metathe meta to read
Returns
the media's meta
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_mda media descriptor object
Returns
string with mrl of media descriptor object
LIBVLC_API libvlc_state_t libvlc_media_get_state ( libvlc_media_t p_md)

Get current state of media descriptor object.

Possible media states are defined in libvlc_structures.c ( libvlc_NothingSpecial=0, libvlc_Opening, libvlc_Buffering, libvlc_Playing, libvlc_Paused, libvlc_Stopped, libvlc_Ended, libvlc_Error).

See Also
libvlc_state_t
Parameters
p_mda media descriptor object
Returns
state of media descriptor object
LIBVLC_API int 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)
Returns
true if the statistics are available, false otherwise
LIBVLC_DEPRECATED LIBVLC_API int libvlc_media_get_tracks_info ( libvlc_media_t p_md,
libvlc_media_track_info_t **  tracks 
)

Get media descriptor's elementary streams description.

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

Deprecated:
Use libvlc_media_tracks_get instead
Parameters
p_mdmedia descriptor object
tracksaddress to store an allocated array of Elementary Streams descriptions (must be freed by the caller) [OUT]
Returns
the number of Elementary Streams
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

Parameters
p_mdmedia descriptor object
LIBVLC_API int libvlc_media_is_parsed ( libvlc_media_t p_md)

Get Parsed status for media descriptor object.

See Also
libvlc_MediaParsedChanged
Parameters
p_mdmedia descriptor object
Returns
true if media object has been parsed otherwise it returns false
LIBVLC_API libvlc_media_t* libvlc_media_new_as_node ( libvlc_instance_t p_instance,
const char *  psz_name 
)

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

See Also
libvlc_media_release
Parameters
p_instancethe instance
psz_namethe name of the node
Returns
the new empty media or NULL on error
LIBVLC_API libvlc_media_t* libvlc_media_new_fd ( libvlc_instance_t p_instance,
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
p_instancethe instance
fdopen file descriptor
Returns
the newly created media or NULL on error
LIBVLC_API libvlc_media_t* libvlc_media_new_location ( libvlc_instance_t p_instance,
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
p_instancethe instance
psz_mrlthe media location
Returns
the newly created media or NULL on error
LIBVLC_API libvlc_media_t* libvlc_media_new_path ( libvlc_instance_t p_instance,
const char *  path 
)

Create a media for a certain file path.

See Also
libvlc_media_release
Parameters
p_instancethe instance
pathlocal filesystem path
Returns
the newly created media or NULL on error
LIBVLC_API void libvlc_media_parse ( libvlc_media_t p_md)

Parse a media.

This fetches (local) meta data and tracks information. The method is synchronous.

See Also
libvlc_media_parse_async
libvlc_media_get_meta
libvlc_media_get_tracks_info
Parameters
p_mdmedia descriptor object
LIBVLC_API void libvlc_media_parse_async ( libvlc_media_t p_md)

Parse a media.

This fetches (local) meta data and tracks information. The method is the asynchronous of libvlc_media_parse().

To track when this is over you can listen to libvlc_MediaParsedChanged event. However if the media was already parsed you will not receive this event.

See Also
libvlc_media_parse
libvlc_MediaParsedChanged
libvlc_media_get_meta
libvlc_media_get_tracks_info
Parameters
p_mdmedia descriptor object
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. It will send out an libvlc_MediaFreed event to all listeners. If the media descriptor object has been released it should not be used again.

Parameters
p_mdthe media descriptor
LIBVLC_API void 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_mdthe media descriptor
LIBVLC_API int libvlc_media_save_meta ( libvlc_media_t p_md)

Save the meta previously set.

Parameters
p_mdthe media desriptor
Returns
true if the write operation was successful
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_mdthe media descriptor
e_metathe meta to write
psz_valuethe media's meta
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_mdmedia descriptor object
p_new_user_datapointer to user data
LIBVLC_API struct libvlc_media_list_t* libvlc_media_subitems ( libvlc_media_t p_md)
read

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_mdmedia descriptor object
Returns
list of media descriptor subitems or NULL
LIBVLC_API unsigned libvlc_media_tracks_get ( libvlc_media_t p_md,
libvlc_media_track_t ***  tracks 
)

Get media descriptor's elementary streams description.

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

Version
LibVLC 2.1.0 and later.
Parameters
p_mdmedia descriptor object
tracksaddress to store an allocated array of Elementary Streams descriptions (must be freed with libvlc_media_tracks_release by the caller) [OUT]
Returns
the number of Elementary Streams (zero on error)
LIBVLC_API void libvlc_media_tracks_release ( libvlc_media_track_t **  p_tracks,
unsigned  i_count 
)

Release media descriptor's elementary streams description array.

Version
LibVLC 2.1.0 and later.
Parameters
p_trackstracks info array to release
i_countnumber of elements in the array