vlc.Media ========= .. py:class:: vlc.Media Bases: :py:obj:`_Ctype` Usage: .. code-block:: python Media(MRL, *options) See :meth:`Instance.media_new` documentation for details. .. py:method:: 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 :class:`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 :func:`new` instead. :param psz_options: the options (as a string). .. py:method:: 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. :param psz_options: the options (as a string). :param i_flags: the flags for this option. .. py:method:: 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 :class:`Instance` or :class:`MediaPlayer` instanciation. :param options: optional media option=value strings .. py:method:: duplicate() Duplicate a media descriptor object. .. py:method:: event_manager() Get event manager from media descriptor object. NOTE: this function doesn't increment reference counting. :return: event manager object. .. py:method:: get_duration() Get duration (in ms) of media descriptor object item. :return: duration of media item or -1 on error. .. py:method:: get_instance() .. py:method:: get_meta(e_meta) Read the meta of the media. If the media has not yet been parsed this will return None. See :func:`parse` See :func:`parse_with_options` See libvlc_MediaMetaChanged :param e_meta: the meta to read. :return: the media's meta. .. py:method:: get_mrl() Get the media resource locator (mrl) from a media descriptor object :return: string with mrl of media descriptor object. .. py:method:: get_parsed_status() Get Parsed status for media descriptor object. See libvlc_MediaParsedChanged See :class:`MediaParsedStatus` :return: a value of the :class:`MediaParsedStatus` enum. :version: LibVLC 3.0.0 or later. .. py:method:: 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 :class:`State`. :return: state of media descriptor object. .. py:method:: get_stats(p_stats) Get the current statistics about the media. :param p_stats:: structure that contain the statistics about the media. (this structure must be allocated by the caller). :return: true if the statistics are available, false otherwise. .. py:method:: get_tracks_info() Get media descriptor's elementary streams description Note, you need to call :func:`parse` or play the media at least once before calling this function. Not doing this will result in an empty array. .. warning:: **Deprecated!** Use :func:`tracks_get` instead :param tracks: address to store an allocated array of Elementary Streams. descriptions (must be freed by the caller) [OUT]. :return: the number of Elementary Streams. .. py:method:: get_type() Get the media type of the media descriptor object See :class:`MediaType` :return: media type. :version: LibVLC 3.0.0 and later. .. py:method:: 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 :class:`Media` pointer .. py:method:: is_parsed() Return true is the media descriptor object is parsed .. warning:: **Deprecated!** This can return true in case of failure. Use :func:`get_parsed_status` instead See libvlc_MediaParsedChanged :return: true if media object has been parsed otherwise it returns false. .. py:method:: 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 :func:`parse_with_options` instead See :func:`parse_with_options` See :func:`get_meta` See :func:`get_tracks_info` .. py:method:: parse_async() Parse a media. This fetches (local) art, meta data and tracks information. The method is the asynchronous of :func:`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 :func:`parse_with_options` instead See :func:`parse` See libvlc_MediaParsedChanged See :func:`get_meta` See :func:`get_tracks_info` .. py:method:: 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 :func:`parse_with_options` :version: LibVLC 3.0.0 or later. .. py:method:: 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 :func:`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 :func:`parse_stop`. See libvlc_MediaParsedChanged See :func:`get_meta` See :func:`tracks_get` See :func:`get_parsed_status` See :class:`MediaParseFlag` :param parse_flag: parse options: :param 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). :return: -1 in case of error, 0 otherwise. :version: LibVLC 3.0.0 or later. .. py:method:: player_new_from_media() Create a Media Player object from a Media destroyed. :return: a new media player object, or None on error. .. py:method:: release() Decrement the reference count of a media descriptor object. If the reference count is 0, then :func:`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. .. py:method:: retain() Retain a reference to a media descriptor object (libvlc_media_t). Use :func:`release` to decrement the reference count of a media descriptor object. .. py:method:: save_meta() Save the meta previously set :return: true if the write operation was successful. .. py:method:: set_meta(e_meta, psz_value) Set the meta of the media (this function will not save the meta, call :func:`save_meta` in order to save the meta) :param e_meta: the meta to write. :param psz_value: the media's meta. .. py:method:: 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 :class:`Media` pointer :param p_new_user_data: pointer to user data. .. py:method:: 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) :param i_type: subtitle or audio. :param i_priority: from 0 (low priority) to 4 (high priority). :param psz_uri: Uri of the slave (should contain a valid scheme). :return: 0 on success, -1 on error. :version: LibVLC 3.0.0 and later. .. py:method:: slaves_clear() Clear all slaves previously added by :func:`slaves_add` or internally. :version: LibVLC 3.0.0 and later. .. py:method:: slaves_get(ppp_slaves) Get a media descriptor's slave list The list will contain slaves parsed by VLC or previously added by :func:`slaves_add`. The typical use case of this function is to save a list of slave in a database for a later use. See :func:`slaves_add` :param ppp_slaves: address to store an allocated array of slaves (must be. freed with libvlc_media_slaves_release) [OUT]. :return: the number of slaves (zero on error). :version: LibVLC 3.0.0 and later. .. py:method:: subitems() Get subitems of media descriptor object. This will increment the reference count of supplied media descriptor object. Use :func:`list_release` to decrement the reference counting. :return: list of media descriptor subitems or None. .. py:method:: tracks_get() Get media descriptor's elementary streams description. .. note:: You need to call :meth:`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 :meth:`tracks_release`. :version: LibVLC 2.1.0 and later.