vlc.Instance

class vlc.Instance

Bases: _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)

add_intf(name)

Try to start a user interface for the libvlc instance.

Parameters:

name – interface name, or None for default.

Returns:

0 on success, -1 on error.

audio_filter_list_get()

Returns a list of available audio filters.

audio_output_device_count(psz_audio_output)

Backward compatibility stub. Do not use in new code.

Warning

Deprecated! Use audio_output_device_list_get() instead.

Returns:

always 0.

audio_output_device_id(psz_audio_output, i_device)

Backward compatibility stub. Do not use in new code.

Warning

Deprecated! Use audio_output_device_list_get() instead.

Returns:

always None.

audio_output_device_list_get(aout)

Gets a list of audio output devices for a given audio output module, See 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.

Parameters:

aout – audio output name. (as returned by libvlc_audio_output_list_get).

Returns:

A None-terminated linked list of potential audio output devices. It must be freed with audio_output_device_list_release().

Version:

LibVLC 2.1.0 or later.

audio_output_device_longname(psz_output, i_device)

Backward compatibility stub. Do not use in new code.

Warning

Deprecated! Use audio_output_device_list_get() instead.

Returns:

always None.

audio_output_enumerate_devices()

Enumerate the defined audio output devices.

Returns:

list of dicts {name:, description:, devices:}

audio_output_list_get()

Gets the list of available audio output modules.

Returns:

list of available audio outputs. It must be freed with. See audio_output_list_release() See AudioOutput . In case of error, None is returned.

dialog_set_callbacks(p_cbs, p_data)

Register callbacks in order to handle VLC dialogs

Parameters:

p_data – opaque pointer for the callback.

Version:

LibVLC 3.0.0 and later.

get_log_verbosity()

Always returns minus one. This function is only provided for backward compatibility.

Returns:

always -1.

log_open()

This function does nothing useful. It is only provided for backward compatibility.

Returns:

an unique pointer or None on error.

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.

Parameters:

  • data – opaque data pointer for the callback function.

  • p_instance – libvlc instance.

Version:

LibVLC 2.1.0 or later.

log_set_file(stream)

Sets up logging to a file.

Parameters:

stream – FILE pointer opened for writing. (the FILE pointer must remain valid until libvlc_log_unset).

Version:

LibVLC 2.1.0 or later.

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.

media_discoverer_list_get(i_cat, ppp_services)

Get media discoverer services by category

Parameters:

  • i_cat – category of services to fetch.

  • ppp_services – address to store an allocated array of media discoverer. services (must be freed with media_discoverer_list_release() by. the caller) [OUT].

Returns:

the number of media discoverer services (0 on error).

Version:

LibVLC 3.0.0 and later.

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 media_discoverer_start() in order to start the discovery.

See media_discoverer_media_list() See media_discoverer_event_manager() See media_discoverer_start()

Parameters:

psz_name – service name; use media_discoverer_list_get() to get. a list of the discoverer names available in this libVLC instance.

Returns:

media discover object or None in case of error.

Version:

LibVLC 3.0.0 or later.

media_discoverer_new_from_name(psz_name)

Warning

Deprecated! Use media_discoverer_new() and media_discoverer_start().

media_library_new()

Create an new Media Library object

Returns:

a new object or None on error.

media_list_new(mrls=None)

Create a new MediaList instance.

Parameters:

mrls – optional list of MRL strings, bytes, or PathLike objects.

media_list_player_new()

Create a new MediaListPlayer instance.

media_new(mrl, *options)

Create a new 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 media_new_location() or 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 Instance level. For instance, the marquee filter must be specified when creating the Instance or MediaPlayer.

Alternatively, options can be added to the media using the Media.add_options() method (with the same limitation).

Parameters:

  • mrl – A str, bytes or PathLike object

  • options – optional media option=value strings

media_new_as_node(psz_name)

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

See media_release()

Parameters:

psz_name – the name of the node.

Returns:

the new empty media or None on error.

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

Parameters:

  • open_cb – callback to open the custom bitstream input media.

  • read_cb – callback to read data (must not be None).

  • seek_cb – callback to seek, or None if seeking is not supported.

  • close_cb – callback to close the media, or None if unnecessary.

  • opaque – data pointer for the open callback.

Returns:

the newly created media or None on error.

Version:

LibVLC 3.0.0 and later.

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

Parameters:

fd – open file descriptor.

Returns:

the newly created media or None on error.

Version:

LibVLC 1.1.5 and later.

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 media_new_path() instead when dealing with local files.

See media_release()

Parameters:

psz_mrl – the media location.

Returns:

the newly created media or None on error.

media_new_path(path)

Create a media for a certain file path. See media_release().

Parameters:

path – A str, byte, or PathLike object representing a local filesystem path.

Returns:

the newly created media or None on error.

media_player_new(uri=None)

Create a new MediaPlayer instance.

Parameters:

uri – an optional URI to play in the player as a str, bytes or PathLike object.

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.

Parameters:

  • 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.

  • i_options – the number of options to add to the item.

  • ppsz_options – the options to add to the item.

release()

Decrement the reference count of a libvlc instance, and destroy it if it reaches zero.

renderer_discoverer_list_get(ppp_services)

Get media discoverer services

See libvlc_renderer_list_release

Parameters:

ppp_services – address to store an allocated array of renderer. discoverer services (must be freed with libvlc_renderer_list_release by. the caller) [OUT].

Returns:

the number of media discoverer services (0 on error).

Version:

LibVLC 3.0.0 and later.

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 renderer_discoverer_start() in order to start the discovery.

See renderer_discoverer_event_manager() See renderer_discoverer_start()

Parameters:

psz_name – service name; use renderer_discoverer_list_get() to. get a list of the discoverer names available in this libVLC instance.

Returns:

media discover object or None in case of error.

Version:

LibVLC 3.0.0 or later.

retain()

Increments the reference count of a libvlc instance. The initial reference count is 1 after new() returns.

set_app_id(id, version, icon)

Sets some meta-information about the application. See also set_user_agent().

Parameters:

  • id – Java-style application identifier, e.g. “com.acme.foobar”.

  • version – application version numbers, e.g. “1.2.3”.

  • icon – application icon name, e.g. “foobar”.

Version:

LibVLC 2.1.0 or later.

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 playlist_play() or 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 wait() cannot be used at the same time.

Parameters:

  • cb – callback to invoke when LibVLC wants to exit, or None to disable the exit handler (as by default).

  • opaque – data pointer for the callback.

set_log_verbosity(level)

This function does nothing. It is only provided for backward compatibility.

Parameters:

level – ignored.

set_user_agent(name, http)

Sets the application name. LibVLC passes this as the user agent string when a protocol requires it.

Parameters:

  • name – human-readable application name, e.g. “FooBar player 1.2.3”.

  • http – HTTP User Agent, e.g. “FooBar/1.2.3 Python/2.6.0”.

Version:

LibVLC 1.1.1 or later.

video_filter_list_get()

Returns a list of available video filters.

vlm_add_broadcast(psz_name, psz_input, psz_output, i_options, ppsz_options, b_enabled, b_loop)

Add a broadcast, with one input.

Parameters:

  • psz_name – the name of the new broadcast.

  • psz_input – the input MRL.

  • psz_output – the output MRL (the parameter to the “sout” variable).

  • i_options – number of additional options.

  • ppsz_options – additional options.

  • b_enabled – boolean for enabling the new broadcast.

  • b_loop – Should this broadcast be played in loop ?

Returns:

0 on success, -1 on error.

vlm_add_input(psz_name, psz_input)

Add a media’s input MRL. This will add the specified one.

Parameters:

  • psz_name – the media to work on.

  • psz_input – the input MRL.

Returns:

0 on success, -1 on error.

vlm_add_vod(psz_name, psz_input, i_options, ppsz_options, b_enabled, psz_mux)

Add a vod, with one input.

Parameters:

  • psz_name – the name of the new vod media.

  • psz_input – the input MRL.

  • i_options – number of additional options.

  • ppsz_options – additional options.

  • b_enabled – boolean for enabling the new vod.

  • psz_mux – the muxer of the vod media.

Returns:

0 on success, -1 on error.

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.

Parameters:

  • psz_name – the name of the new broadcast.

  • psz_input – the input MRL.

  • psz_output – the output MRL (the parameter to the “sout” variable).

  • i_options – number of additional options.

  • ppsz_options – additional options.

  • b_enabled – boolean for enabling the new broadcast.

  • b_loop – Should this broadcast be played in loop ?

Returns:

0 on success, -1 on error.

vlm_del_media(psz_name)

Delete a media (VOD or broadcast).

Parameters:

psz_name – the media to delete.

Returns:

0 on success, -1 on error.

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

Returns:

libvlc_event_manager.

vlm_get_media_instance_length(psz_name, i_instance)

Get vlm_media instance length by name or instance id

Parameters:

  • psz_name – name of vlm media instance.

  • i_instance – instance id.

Returns:

length of media item or -1 on error.

vlm_get_media_instance_position(psz_name, i_instance)

Get vlm_media instance position by name or instance id

Parameters:

  • psz_name – name of vlm media instance.

  • i_instance – instance id.

Returns:

position as float or -1. on error.

vlm_get_media_instance_rate(psz_name, i_instance)

Get vlm_media instance playback rate by name or instance id

Parameters:

  • psz_name – name of vlm media instance.

  • i_instance – instance id.

Returns:

playback rate or -1 on error.

vlm_get_media_instance_time(psz_name, i_instance)

Get vlm_media instance time by name or instance id

Parameters:

  • psz_name – name of vlm media instance.

  • i_instance – instance id.

Returns:

time as integer or -1 on error.

vlm_pause_media(psz_name)

Pause the named broadcast.

Parameters:

psz_name – the name of the broadcast.

Returns:

0 on success, -1 on error.

vlm_play_media(psz_name)

Play the named broadcast.

Parameters:

psz_name – the name of the broadcast.

Returns:

0 on success, -1 on error.

vlm_release()

Release the vlm instance related to the given Instance

vlm_seek_media(psz_name, f_percentage)

Seek in the named broadcast.

Parameters:

  • psz_name – the name of the broadcast.

  • f_percentage – the percentage to seek to.

Returns:

0 on success, -1 on error.

vlm_set_enabled(psz_name, b_enabled)

Enable or disable a media (VOD or broadcast).

Parameters:

  • psz_name – the media to work on.

  • b_enabled – the new status.

Returns:

0 on success, -1 on error.

vlm_set_input(psz_name, psz_input)

Set a media’s input MRL. This will delete all existing inputs and add the specified one.

Parameters:

  • psz_name – the media to work on.

  • psz_input – the input MRL.

Returns:

0 on success, -1 on error.

vlm_set_loop(psz_name, b_loop)

Set a media’s loop status.

Parameters:

  • psz_name – the media to work on.

  • b_loop – the new status.

Returns:

0 on success, -1 on error.

vlm_set_mux(psz_name, psz_mux)

Set a media’s vod muxer.

Parameters:

  • psz_name – the media to work on.

  • psz_mux – the new muxer.

Returns:

0 on success, -1 on error.

vlm_set_output(psz_name, psz_output)

Set the output for a media.

Parameters:

  • psz_name – the media to work on.

  • psz_output – the output MRL (the parameter to the “sout” variable).

Returns:

0 on success, -1 on error.

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.

Parameters:

psz_name – the name of the media, if the name is an empty string, all media is described.

Returns:

string with information about named media, or None on error.

vlm_stop_media(psz_name)

Stop the named broadcast.

Parameters:

psz_name – the name of the broadcast.

Returns:

0 on success, -1 on error.

wait()

Waits until an interface causes the instance to exit. You should start at least one interface first, using add_intf().

Warning

This function wastes one thread doing basically nothing. set_exit_handler() should be used instead.