vlc.Instance ============ .. py:class:: vlc.Instance Bases: :py:obj:`_Ctype` It may take as parameter either: * a string * a list of strings as first parameters * the parameters given as the constructor parameters (must be strings) .. py:method:: add_intf(name) Try to start a user interface for the libvlc instance. :param name: interface name, or None for default. :return: 0 on success, -1 on error. .. py:method:: audio_filter_list_get() Returns a list of available audio filters. .. py:method:: audio_output_device_count(psz_audio_output) Backward compatibility stub. Do not use in new code. .. warning:: **Deprecated!** Use :func:`audio_output_device_list_get` instead. :return: always 0. .. py:method:: audio_output_device_id(psz_audio_output, i_device) Backward compatibility stub. Do not use in new code. .. warning:: **Deprecated!** Use :func:`audio_output_device_list_get` instead. :return: always None. .. py:method:: audio_output_device_list_get(aout) Gets a list of audio output devices for a given audio output module, See :func:`audio_output_device_set`. .. note:: Not all audio outputs support this. In particular, an empty (None) list of devices does **not** imply that the specified audio output does not work. .. note:: The list might not be exhaustive. .. warning:: Some audio output devices in the list might not actually work in some circumstances. By default, it is recommended to not specify any explicit audio device. :param aout: audio output name. (as returned by libvlc_audio_output_list_get). :return: A None-terminated linked list of potential audio output devices. It must be freed with :func:`audio_output_device_list_release`. :version: LibVLC 2.1.0 or later. .. py:method:: audio_output_device_longname(psz_output, i_device) Backward compatibility stub. Do not use in new code. .. warning:: **Deprecated!** Use :func:`audio_output_device_list_get` instead. :return: always None. .. py:method:: audio_output_enumerate_devices() Enumerate the defined audio output devices. :return: list of dicts {name:, description:, devices:} .. py:method:: audio_output_list_get() Gets the list of available audio output modules. :return: list of available audio outputs. It must be freed with. See :func:`audio_output_list_release` See :class:`AudioOutput` . In case of error, None is returned. .. py:method:: dialog_set_callbacks(p_cbs, p_data) Register callbacks in order to handle VLC dialogs :param p_data: opaque pointer for the callback. :version: LibVLC 3.0.0 and later. .. py:method:: get_log_verbosity() Always returns minus one. This function is only provided for backward compatibility. :return: always -1. .. py:method:: log_open() This function does nothing useful. It is only provided for backward compatibility. :return: an unique pointer or None on error. .. py:method:: log_set(cb, data) Sets the logging callback for a LibVLC instance. This function is thread-safe: it will wait for any pending callbacks invocation to complete. .. note:: Some log messages (especially debug) are emitted by LibVLC while is being initialized. These messages cannot be captured with this interface. .. warning:: A deadlock may occur if this function is called from the callback. :param data: opaque data pointer for the callback function. :param p_instance: libvlc instance. :version: LibVLC 2.1.0 or later. .. py:method:: log_set_file(stream) Sets up logging to a file. :param stream: FILE pointer opened for writing. (the FILE pointer must remain valid until libvlc_log_unset). :version: LibVLC 2.1.0 or later. .. py:method:: log_unset() Unsets the logging callback. This function deregisters the logging callback for a LibVLC instance. This is rarely needed as the callback is implicitly unset when the instance is destroyed. .. note:: This function will wait for any pending callbacks invocation to complete (causing a deadlock if called from within the callback). :version: LibVLC 2.1.0 or later. .. py:method:: media_discoverer_list_get(i_cat, ppp_services) Get media discoverer services by category :param i_cat: category of services to fetch. :param ppp_services: address to store an allocated array of media discoverer. services (must be freed with :func:`media_discoverer_list_release` by. the caller) [OUT]. :return: the number of media discoverer services (0 on error). :version: LibVLC 3.0.0 and later. .. py:method:: media_discoverer_new(psz_name) Create a media discoverer object by name. After this object is created, you should attach to media_list events in order to be notified of new items discovered. You need to call :func:`media_discoverer_start` in order to start the discovery. See :func:`media_discoverer_media_list` See :func:`media_discoverer_event_manager` See :func:`media_discoverer_start` :param psz_name: service name; use :func:`media_discoverer_list_get` to get. a list of the discoverer names available in this libVLC instance. :return: media discover object or None in case of error. :version: LibVLC 3.0.0 or later. .. py:method:: media_discoverer_new_from_name(psz_name) .. warning:: **Deprecated!** Use :func:`media_discoverer_new` and :func:`media_discoverer_start`. .. py:method:: media_library_new() Create an new Media Library object :return: a new object or None on error. .. py:method:: media_list_new(mrls=None) Create a new :class:`MediaList` instance. :param mrls: optional list of MRL strings, bytes, or PathLike objects. .. py:method:: media_list_player_new() Create a new :class:`MediaListPlayer` instance. .. py:method:: media_new(mrl, *options) Create a new :class:`Media` instance. If mrl contains a colon (:) preceded by more than 1 letter, it will be treated as a URL. Else, it will be considered as a local path. If you need more control, directly use :meth:`media_new_location` or :meth:`media_new_path`. Options can be specified as supplementary string parameters, but note that many options cannot be set at the media level, and rather at the :class:`Instance` level. For instance, the marquee filter must be specified when creating the :class:`Instance` or :class:`MediaPlayer`. Alternatively, options can be added to the media using the :meth:`Media.add_options` method (with the same limitation). :param mrl: A str, bytes or PathLike object :param options: optional media option=value strings .. py:method:: media_new_as_node(psz_name) Create a media as an empty node with a given name. See :func:`media_release` :param psz_name: the name of the node. :return: the new empty media or None on error. .. py:method:: media_new_callbacks(open_cb, read_cb, seek_cb, close_cb, opaque) Create a media with custom callbacks to read the data from. .. note:: If *open_cb* is None, the *opaque* pointer will be passed to *read_cb*, *seek_cb* and *close_cb*, and the stream size will be treated as unknown. .. note:: 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 :func:`media_release` :param open_cb: callback to open the custom bitstream input media. :param read_cb: callback to read data (must not be None). :param seek_cb: callback to seek, or None if seeking is not supported. :param close_cb: callback to close the media, or None if unnecessary. :param opaque: data pointer for the open callback. :return: the newly created media or None on error. :version: LibVLC 3.0.0 and later. .. py:method:: media_new_fd(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 :func:`media_release` :param fd: open file descriptor. :return: the newly created media or None on error. :version: LibVLC 1.1.5 and later. .. py:method:: media_new_location(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 :func:`media_new_path` instead when dealing with local files. See :func:`media_release` :param psz_mrl: the media location. :return: the newly created media or None on error. .. py:method:: media_new_path(path) Create a media for a certain file path. See :meth:`media_release`. :param path: A str, byte, or PathLike object representing a local filesystem path. :return: the newly created media or None on error. .. py:method:: media_player_new(uri=None) Create a new :class:`MediaPlayer` instance. :param uri: an optional URI to play in the player as a str, bytes or PathLike object. .. py:method:: playlist_play(i_id, i_options, ppsz_options) Start playing (if there is any item in the playlist). Additionnal playlist item options can be specified for addition to the item before it is played. :param i_id: the item to play. If this is a negative number, the next. item will be selected. Otherwise, the item with the given ID will be. played. :param i_options: the number of options to add to the item. :param ppsz_options: the options to add to the item. .. py:method:: release() Decrement the reference count of a libvlc instance, and destroy it if it reaches zero. .. py:method:: renderer_discoverer_list_get(ppp_services) Get media discoverer services See libvlc_renderer_list_release :param ppp_services: address to store an allocated array of renderer. discoverer services (must be freed with libvlc_renderer_list_release by. the caller) [OUT]. :return: the number of media discoverer services (0 on error). :version: LibVLC 3.0.0 and later. .. py:method:: renderer_discoverer_new(psz_name) Create a renderer discoverer object by name After this object is created, you should attach to events in order to be notified of the discoverer events. You need to call :func:`renderer_discoverer_start` in order to start the discovery. See :func:`renderer_discoverer_event_manager` See :func:`renderer_discoverer_start` :param psz_name: service name; use :func:`renderer_discoverer_list_get` to. get a list of the discoverer names available in this libVLC instance. :return: media discover object or None in case of error. :version: LibVLC 3.0.0 or later. .. py:method:: retain() Increments the reference count of a libvlc instance. The initial reference count is 1 after :func:`new` returns. .. py:method:: set_app_id(id, version, icon) Sets some meta-information about the application. See also :func:`set_user_agent`. :param id: Java-style application identifier, e.g. "com.acme.foobar". :param version: application version numbers, e.g. "1.2.3". :param icon: application icon name, e.g. "foobar". :version: LibVLC 2.1.0 or later. .. py:method:: set_exit_handler(cb, opaque) Registers a callback for the LibVLC exit event. This is mostly useful if the VLC playlist and/or at least one interface are started with :func:`playlist_play` or :func:`add_intf` respectively. Typically, this function will wake up your application main loop (from another thread). .. note:: This function should be called before the playlist or interface are started. Otherwise, there is a small race condition: the exit event could be raised before the handler is registered. .. warning:: This function and :func:`wait` cannot be used at the same time. :param cb: callback to invoke when LibVLC wants to exit, or None to disable the exit handler (as by default). :param opaque: data pointer for the callback. .. py:method:: set_log_verbosity(level) This function does nothing. It is only provided for backward compatibility. :param level: ignored. .. py:method:: set_user_agent(name, http) Sets the application *name*. LibVLC passes this as the user agent string when a protocol requires it. :param name: human-readable application name, e.g. "FooBar player 1.2.3". :param http: HTTP User Agent, e.g. "FooBar/1.2.3 Python/2.6.0". :version: LibVLC 1.1.1 or later. .. py:method:: video_filter_list_get() Returns a list of available video filters. .. py:method:: vlm_add_broadcast(psz_name, psz_input, psz_output, i_options, ppsz_options, b_enabled, b_loop) Add a broadcast, with one input. :param psz_name: the name of the new broadcast. :param psz_input: the input MRL. :param psz_output: the output MRL (the parameter to the "sout" variable). :param i_options: number of additional options. :param ppsz_options: additional options. :param b_enabled: boolean for enabling the new broadcast. :param b_loop: Should this broadcast be played in loop ? :return: 0 on success, -1 on error. .. py:method:: vlm_add_input(psz_name, psz_input) Add a media's input MRL. This will add the specified one. :param psz_name: the media to work on. :param psz_input: the input MRL. :return: 0 on success, -1 on error. .. py:method:: vlm_add_vod(psz_name, psz_input, i_options, ppsz_options, b_enabled, psz_mux) Add a vod, with one input. :param psz_name: the name of the new vod media. :param psz_input: the input MRL. :param i_options: number of additional options. :param ppsz_options: additional options. :param b_enabled: boolean for enabling the new vod. :param psz_mux: the muxer of the vod media. :return: 0 on success, -1 on error. .. py:method:: vlm_change_media(psz_name, psz_input, psz_output, i_options, ppsz_options, b_enabled, b_loop) Edit the parameters of a media. This will delete all existing inputs and add the specified one. :param psz_name: the name of the new broadcast. :param psz_input: the input MRL. :param psz_output: the output MRL (the parameter to the "sout" variable). :param i_options: number of additional options. :param ppsz_options: additional options. :param b_enabled: boolean for enabling the new broadcast. :param b_loop: Should this broadcast be played in loop ? :return: 0 on success, -1 on error. .. py:method:: vlm_del_media(psz_name) Delete a media (VOD or broadcast). :param psz_name: the media to delete. :return: 0 on success, -1 on error. .. py:method:: vlm_get_event_manager() Get libvlc_event_manager from a vlm media. The p_event_manager is immutable, so you don't have to hold the lock :return: libvlc_event_manager. .. py:method:: vlm_get_media_instance_length(psz_name, i_instance) Get vlm_media instance length by name or instance id :param psz_name: name of vlm media instance. :param i_instance: instance id. :return: length of media item or -1 on error. .. py:method:: vlm_get_media_instance_position(psz_name, i_instance) Get vlm_media instance position by name or instance id :param psz_name: name of vlm media instance. :param i_instance: instance id. :return: position as float or -1. on error. .. py:method:: vlm_get_media_instance_rate(psz_name, i_instance) Get vlm_media instance playback rate by name or instance id :param psz_name: name of vlm media instance. :param i_instance: instance id. :return: playback rate or -1 on error. .. py:method:: vlm_get_media_instance_time(psz_name, i_instance) Get vlm_media instance time by name or instance id :param psz_name: name of vlm media instance. :param i_instance: instance id. :return: time as integer or -1 on error. .. py:method:: vlm_pause_media(psz_name) Pause the named broadcast. :param psz_name: the name of the broadcast. :return: 0 on success, -1 on error. .. py:method:: vlm_play_media(psz_name) Play the named broadcast. :param psz_name: the name of the broadcast. :return: 0 on success, -1 on error. .. py:method:: vlm_release() Release the vlm instance related to the given :class:`Instance` .. py:method:: vlm_seek_media(psz_name, f_percentage) Seek in the named broadcast. :param psz_name: the name of the broadcast. :param f_percentage: the percentage to seek to. :return: 0 on success, -1 on error. .. py:method:: vlm_set_enabled(psz_name, b_enabled) Enable or disable a media (VOD or broadcast). :param psz_name: the media to work on. :param b_enabled: the new status. :return: 0 on success, -1 on error. .. py:method:: vlm_set_input(psz_name, psz_input) Set a media's input MRL. This will delete all existing inputs and add the specified one. :param psz_name: the media to work on. :param psz_input: the input MRL. :return: 0 on success, -1 on error. .. py:method:: vlm_set_loop(psz_name, b_loop) Set a media's loop status. :param psz_name: the media to work on. :param b_loop: the new status. :return: 0 on success, -1 on error. .. py:method:: vlm_set_mux(psz_name, psz_mux) Set a media's vod muxer. :param psz_name: the media to work on. :param psz_mux: the new muxer. :return: 0 on success, -1 on error. .. py:method:: vlm_set_output(psz_name, psz_output) Set the output for a media. :param psz_name: the media to work on. :param psz_output: the output MRL (the parameter to the "sout" variable). :return: 0 on success, -1 on error. .. py:method:: vlm_show_media(psz_name) Return information about the named media as a JSON string representation. This function is mainly intended for debugging use, if you want programmatic access to the state of a vlm_media_instance_t, please use the corresponding libvlc_vlm_get_media_instance_xxx -functions. Currently there are no such functions available for vlm_media_t though. :param psz_name: the name of the media, if the name is an empty string, all media is described. :return: string with information about named media, or None on error. .. py:method:: vlm_stop_media(psz_name) Stop the named broadcast. :param psz_name: the name of the broadcast. :return: 0 on success, -1 on error. .. py:method:: wait() Waits until an interface causes the instance to exit. You should start at least one interface first, using :func:`add_intf`. .. warning:: This function wastes one thread doing basically nothing. :func:`set_exit_handler` should be used instead.