tessl/pypi-python-vlc
VLC bindings for Python providing comprehensive multimedia functionality through LibVLC API.
—
Pending
core-playback.mddocs/
Core Media Playback
Essential media playback functionality including media players, media objects, and basic playback control. These classes form the foundation for any media application using Python-VLC.
Capabilities
Instance Management
The VLC Instance serves as the main entry point for all LibVLC functionality. It manages the LibVLC environment and creates media players and media objects.
class Instance:
def __init__(self, *args):
"""Create a new LibVLC instance.
Args:
*args: Command line arguments (strings) to pass to LibVLC.
Common options: '--no-audio', '--quiet', '--intf', 'dummy'
"""
...
def media_player_new(self, uri=None):
"""Create a new media player from this instance.
Args:
uri (str, optional): Media URI to load immediately
Returns:
MediaPlayer: New media player instance
"""
...
def media_new(self, mrl):
"""Create a new media object from a media resource locator.
Args:
mrl (str): Media resource locator (URI, file path, etc.)
Returns:
Media: New media object
"""
...
def media_new_path(self, path):
"""Create a new media object from a file path.
Args:
path (str): File system path to media file
Returns:
Media: New media object
"""
...
def media_list_new(self, mrls=None):
"""Create a new media list.
Args:
mrls (list, optional): Initial list of media resource locators
Returns:
MediaList: New media list instance
"""
...
def media_list_player_new(self):
"""Create a new media list player from this instance.
Returns:
MediaListPlayer: New media list player instance
"""
...
def audio_output_enumerate_devices(self):
"""Enumerate available audio output devices.
Returns:
list: List of available audio output devices
"""
...
def media_new_callbacks(self, open_cb, read_cb, seek_cb, close_cb, opaque):
"""Create a media with custom I/O callbacks. (LibVLC 3.0.0+)
Args:
open_cb: Open callback function
read_cb: Read callback function
seek_cb: Seek callback function
close_cb: Close callback function
opaque: User data pointer
Returns:
Media: New media object with custom I/O
"""
...
def set_exit_handler(self, cb, opaque):
"""Register exit event callback. (LibVLC 3.0.0+)
Args:
cb: Callback function to register
opaque: User data pointer
Returns:
int: 0 on success, -1 on error
"""
...
def media_discoverer_new(self, psz_name):
"""Create media discoverer by name. (LibVLC 3.0.0+)
Args:
psz_name (str): Service name for discovery
Returns:
MediaDiscoverer: New media discoverer instance
"""
...
def renderer_discoverer_new(self, psz_name):
"""Create renderer discoverer. (LibVLC 3.0.0+)
Args:
psz_name (str): Service name for renderer discovery
Returns:
RendererDiscoverer: New renderer discoverer instance
"""
...
def release(self):
"""Decrement the reference count of a libvlc instance."""
...Media Player Control
The MediaPlayer class provides complete control over media playback, including play/pause/stop operations and playback state management.
class MediaPlayer:
def __init__(self, *args):
"""Create a media player object.
Args:
*args: Can be Instance, URI string, or Instance and URI
"""
...
def get_instance(self):
"""Get the instance associated with this media player.
Returns:
Instance: The LibVLC instance
"""
...
def set_media(self, media):
"""Set the media that will be used by the media player.
Args:
media (Media): Media object to play
"""
...
def get_media(self):
"""Get the media used by the media player.
Returns:
Media: Current media object or None
"""
...
def play(self):
"""Play the current media.
Returns:
int: 0 if playback started, -1 on error
"""
...
def pause(self):
"""Toggle the pause state of the player.
If player is playing, this pauses it.
If player is paused, this resumes playback.
"""
...
def stop(self):
"""Stop the player."""
...
def set_pause(self, do_pause):
"""Pause or resume the player.
Args:
do_pause (bool): True to pause, False to resume
"""
...
def get_time(self):
"""Get the current playback time in milliseconds.
Returns:
int: Current time in milliseconds, or -1 on error
"""
...
def set_time(self, time):
"""Set the current playback time in milliseconds.
Args:
time (int): Time in milliseconds
"""
...
def get_position(self):
"""Get the current playback position as a float between 0.0 and 1.0.
Returns:
float: Position from 0.0 to 1.0, or -1.0 on error
"""
...
def set_position(self, position):
"""Set the current playback position.
Args:
position (float): Position from 0.0 to 1.0
"""
...
def get_length(self):
"""Get the total length of the media in milliseconds.
Returns:
int: Length in milliseconds, or -1 if unavailable
"""
...
def get_state(self):
"""Get the current player state.
Returns:
State: Current player state (NothingSpecial, Opening, Buffering,
Playing, Paused, Stopped, Ended, Error)
"""
...
def get_rate(self):
"""Get the playback rate (speed).
Returns:
float: Playback rate (1.0 = normal speed)
"""
...
def set_rate(self, rate):
"""Set the playback rate (speed).
Args:
rate (float): Playback rate (1.0 = normal, 2.0 = double speed, etc.)
Returns:
int: 0 on success, -1 on error
"""
...
def is_playing(self):
"""Check if the player is playing.
Returns:
bool: True if playing, False otherwise
"""
...
def will_play(self):
"""Check if the player will play.
Returns:
bool: True if the player will play, False otherwise
"""
...
def is_seekable(self):
"""Check if the current media is seekable.
Returns:
bool: True if seekable, False otherwise
"""
...
def can_pause(self):
"""Check if the current media can be paused.
Returns:
bool: True if can pause, False otherwise
"""
...
def add_slave(self, i_type, psz_uri, b_select):
"""Add external subtitle or audio track. (LibVLC 3.0.0+)
Args:
i_type (int): Slave type (subtitle=0, audio=1)
psz_uri (str): URI of the slave track
b_select (bool): Whether to select this track immediately
Returns:
int: 0 on success, -1 on error
"""
...
def set_renderer(self, p_renderer):
"""Set renderer for casting. (LibVLC 3.0.0+)
Args:
p_renderer (Renderer): Renderer object or None to unset
Returns:
int: 0 on success, -1 on error
"""
...
def get_role(self):
"""Get media player role. (LibVLC 3.0.0+)
Returns:
int: Current player role
"""
...
def set_role(self, role):
"""Set media player role. (LibVLC 3.0.0+)
Args:
role (int): Player role to set
Returns:
int: 0 on success, -1 on error
"""
...Media Object Management
The Media class represents individual media files or streams with metadata and parsing capabilities.
class Media:
def __init__(self, *args):
"""Create a media object.
Args:
*args: Can be Instance and MRL, or just MRL string
"""
...
def get_instance(self):
"""Get the instance associated with this media.
Returns:
Instance: The LibVLC instance
"""
...
def get_mrl(self):
"""Get the media resource locator.
Returns:
str: MRL string of this media
"""
...
def parse(self):
"""Parse the media synchronously. [DEPRECATED]
This fetches metadata and track information.
Use parse_with_options() for LibVLC 3.0+.
"""
...
def parse_async(self):
"""Parse the media asynchronously. [DEPRECATED]
This fetches metadata and track information in the background.
Use parse_with_options() for LibVLC 3.0+.
"""
...
def parse_with_options(self, parse_flag, timeout):
"""Parse the media with specific options. (LibVLC 3.0.0+) [RECOMMENDED]
Args:
parse_flag (int): Combination of ParseFlag values
timeout (int): Timeout in milliseconds (-1 for no timeout)
Returns:
int: -1 on error, 0 otherwise
"""
...
def parse_stop(self):
"""Stop ongoing parsing operation. (LibVLC 3.0.0+)
Stops any running asynchronous parsing.
"""
...
def get_parsed_status(self):
"""Get the current parsed status. (LibVLC 3.0.0+)
Returns:
MediaParsedStatus: Current parsing status
"""
...
def get_meta(self, meta_type):
"""Get metadata for the specified type.
Args:
meta_type (Meta): Type of metadata to retrieve
Returns:
str: Metadata value or None if not available
"""
...
def set_meta(self, meta_type, meta_value):
"""Set metadata for the specified type.
Args:
meta_type (Meta): Type of metadata to set
meta_value (str): Value to set
"""
...
def save_meta(self):
"""Save the previously set metadata to the media file.
Returns:
bool: True on success, False on failure
"""
...
def get_duration(self):
"""Get the duration of the media in milliseconds.
Returns:
int: Duration in milliseconds, or -1 if unknown
"""
...
def get_type(self):
"""Get the media type.
Returns:
MediaType: Type of media (Unknown, File, Directory, Disc, Stream, Playlist)
"""
...
def get_tracks_info(self):
"""Get information about tracks in the media. [DEPRECATED]
Use tracks_get() for LibVLC 2.1.0+.
Returns:
list: List of track information dictionaries
"""
...
def tracks_get(self):
"""Get tracks information as MediaTrack objects. (LibVLC 2.1.0+) [RECOMMENDED]
Returns:
iterator: Iterator of MediaTrack objects or None
"""
...
def subitems(self):
"""Get the subitems media list.
Returns:
MediaList: List of subitems or None
"""
...
def event_manager(self):
"""Get the event manager for this media.
Returns:
EventManager: Event manager for this media
"""
...
def add_option(self, option):
"""Add an option to the media.
Args:
option (str): Option string in format 'key=value'
"""
...
def add_option_flag(self, option, flag):
"""Add an option to the media with specific flags.
Args:
option (str): Option string
flag (int): Option flags
"""
...
def slaves_add(self, i_type, i_priority, psz_uri):
"""Add external subtitle or audio track. (LibVLC 3.0.0+)
Args:
i_type (int): Subtitle (0) or audio (1)
i_priority (int): Priority (0-4)
psz_uri (str): URI of the slave track
Returns:
int: 0 on success, -1 on error
"""
...
def slaves_clear(self):
"""Clear all added slaves. (LibVLC 3.0.0+)
Removes all previously added slave tracks.
"""
...
def duplicate(self):
"""Duplicate the media object.
Returns:
Media: Duplicated media object
"""
...
def release(self):
"""Decrement the reference count of a media object."""
...Usage Examples
Basic Media Player
import vlc
# Simple player with a file
player = vlc.MediaPlayer('/path/to/video.mp4')
player.play()
# Control playback
player.pause()
player.stop()
# Check status
if player.is_playing():
print(f"Current time: {player.get_time()}ms")
print(f"Total length: {player.get_length()}ms")Using Instance for Advanced Control
import vlc
# Create instance with options
instance = vlc.Instance('--no-audio', '--quiet')
# Create media and player
media = instance.media_new('file:///path/to/video.mp4')
player = instance.media_player_new()
player.set_media(media)
# Parse media for metadata (LibVLC 3.0+)
media.parse_with_options(vlc.MediaParseFlag.ParseLocal, -1)
# Wait for parsing to complete
while media.get_parsed_status() == vlc.MediaParsedStatus.Skipped:
pass
title = media.get_meta(vlc.Meta.Title)
duration = media.get_duration()
print(f"Title: {title}")
print(f"Duration: {duration}ms")
# Start playback
player.play()Media Parsing and Metadata
import vlc
# Create media object
media = vlc.Media('/path/to/audio.mp3')
# Parse with modern method (LibVLC 3.0+)
media.parse_with_options(vlc.MediaParseFlag.ParseLocal, -1)
# For older versions, use:
# media.parse()
# Get various metadata
title = media.get_meta(vlc.Meta.Title)
artist = media.get_meta(vlc.Meta.Artist)
album = media.get_meta(vlc.Meta.Album)
duration = media.get_duration()
print(f"Title: {title}")
print(f"Artist: {artist}")
print(f"Album: {album}")
print(f"Duration: {duration}ms")
# Get track information (modern method)
tracks = media.tracks_get()
if tracks:
for track in tracks:
print(f"Track type: {track.type}")
print(f"Codec: {track.codec}")Install with Tessl CLI
npx tessl i tessl/pypi-python-vlc