vlc.Media

class vlc.Media

Bases: _Ctype

Usage:

Media(MRL, *options)

See Instance.media_new() documentation for details.

add_option(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 Media 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 new() instead.

Parameters:: psz_options – the options (as a string).

add_option_flag(psz_options, 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:

psz_options – the options (as a string).
i_flags – the flags for this option.

add_options(*options)

Add a list of options to the media.

Note

Options must be written without the double-dash.

Warning

Most audio and video options, such as text renderer, have no effects on an individual media. These options must be set at the Instance or MediaPlayer instanciation.

Parameters:: options – optional media option=value strings

duplicate(): Duplicate a media descriptor object.

event_manager()

Get event manager from media descriptor object. NOTE: this function doesn’t increment reference counting.

Returns:: event manager object.

get_duration()

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

Returns:: duration of media item or -1 on error.

get_instance()

get_meta(e_meta)

Read the meta of the media.

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

See parse() See parse_with_options() See libvlc_MediaMetaChanged

Parameters:: e_meta – the meta to read.
Returns:: the media’s meta.

get_mrl()

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

Returns:: string with mrl of media descriptor object.

get_parsed_status()

Get Parsed status for media descriptor object.

See libvlc_MediaParsedChanged See MediaParsedStatus

Returns:: a value of the MediaParsedStatus enum.
Version:: LibVLC 3.0.0 or later.

get_state()

Get current state of media descriptor object. Possible media states are libvlc_NothingSpecial=0, libvlc_Opening, libvlc_Playing, libvlc_Paused, libvlc_Stopped, libvlc_Ended, libvlc_Error.

See State.

Returns:: state of media descriptor object.

get_stats(p_stats)

Get the current statistics about the media.

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

get_tracks_info()

Get media descriptor’s elementary streams description

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

Warning

Deprecated! Use tracks_get() instead

Parameters:: tracks – address to store an allocated array of Elementary Streams. descriptions (must be freed by the caller) [OUT].
Returns:: the number of Elementary Streams.

get_type()

Get the media type of the media descriptor object

See MediaType

Returns:: media type.
Version:: LibVLC 3.0.0 and later.

get_user_data(): 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 Media pointer

is_parsed()

Return true is the media descriptor object is parsed

Warning

Deprecated! This can return true in case of failure. Use get_parsed_status() instead

See libvlc_MediaParsedChanged

Returns:: true if media object has been parsed otherwise it returns false.

parse()

Parse a media.

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

Warning

Deprecated! This function could block indefinitely. Use parse_with_options() instead

See parse_with_options() See get_meta() See get_tracks_info()

parse_async()

Parse a media.

This fetches (local) art, meta data and tracks information. The method is the asynchronous of 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.

Warning

Deprecated! You can’t be sure to receive the libvlc_MediaParsedChanged event (you can wait indefinitely for this event). Use parse_with_options() instead

See parse() See libvlc_MediaParsedChanged See get_meta() See get_tracks_info()

parse_stop()

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 parse_with_options()

Version:: LibVLC 3.0.0 or later.

parse_with_options(parse_flag, timeout)

Parse the media asynchronously with options.

This fetches (local or network) art, meta data and/or tracks information. This method is the extended version of parse_with_options().

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 parse_stop().

See libvlc_MediaParsedChanged See get_meta() See tracks_get() See get_parsed_status() See MediaParseFlag

Parameters:

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 3.0.0 or later.

player_new_from_media()

Create a Media Player object from a Media

destroyed.

Returns:: a new media player object, or None on error.

release(): Decrement the reference count of a media descriptor object. If the reference count is 0, then 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.

retain(): Retain a reference to a media descriptor object (libvlc_media_t). Use release() to decrement the reference count of a media descriptor object.

save_meta()

Save the meta previously set

Returns:: true if the write operation was successful.

set_meta(e_meta, psz_value)

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

Parameters:

e_meta – the meta to write.
psz_value – the media’s meta.

set_user_data(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 Media pointer

Parameters:: p_new_user_data – pointer to user data.

slaves_add(i_type, i_priority, 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_with_options) or before the media is played (via libvlc_media_player_play)

Parameters:

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.

Version:

LibVLC 3.0.0 and later.

slaves_clear()

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

Version:: LibVLC 3.0.0 and later.

slaves_get(ppp_slaves)

Get a media descriptor’s slave list

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

See slaves_add()

Parameters:: 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).
Version:: LibVLC 3.0.0 and later.

subitems()

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

Returns:: list of media descriptor subitems or None.

tracks_get()

Get media descriptor’s elementary streams description.

Note

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

Note

The result must be freed with tracks_release().

Version:: LibVLC 2.1.0 and later.