### Simple Playback Example

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/DOCUMENTATION_SUMMARY.txt

Demonstrates basic media playback using the python-vlc library. This is a fundamental example for starting with audio or video playback.

```python
import vlc

# Create a VLC instance
instance = vlc.Instance()

# Create a MediaPlayer object
player = instance.media_player_new()

# Create a Media object from a file path
media = instance.media_new('my_media.mp4')

# Set the media for the player
player.set_media(media)

# Play the media
player.play()

# Wait for playback to finish (optional, for simple scripts)
import time
time.sleep(10) # Play for 10 seconds

# Stop the player
player.stop()

```

--------------------------------

### Install Development Dependencies

Source: https://github.com/oaubert/python-vlc/blob/master/README.md

Run this script to install all necessary dependencies for generating bindings, including submodules, virtual environment, and packages.

```shell
python3 dev_setup.sh
```

--------------------------------

### Add VLC User Interface

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/instance.md

Starts a user interface for the VLC instance. Use 'qt' for the Qt interface or None for the default.

```python
result = instance.add_intf('qt')
```

--------------------------------

### Start Playback

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/media_player.md

Initiate media playback. Returns 0 on success and -1 if an error occurs during playback start.

```python
player.set_mrl('video.mp4')
player.play()
```

--------------------------------

### Generate Bindings from Installed VLC Includes

Source: https://github.com/oaubert/python-vlc/blob/master/README.md

Use the 'installed' target with 'make' to generate bindings when VLC include files are installed in the system's default include path (e.g., /usr/include/vlc).

```makefile
make installed
```

--------------------------------

### Install python-vlc

Source: https://github.com/oaubert/python-vlc/blob/master/docs/index.md

Install the python-vlc module using pip. This command fetches and installs the latest version from PyPI.

```default
pip install python-vlc
```

--------------------------------

### Create VLC Instance with No Arguments

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/instance.md

Initializes a new libvlc instance using default configurations. This is the simplest way to start using the VLC library.

```python
import vlc

# No arguments - uses defaults
instance = vlc.Instance()
```

--------------------------------

### Create and Configure VLC Instance

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/instance.md

Demonstrates creating a VLC instance with specific command-line options like '--no-audio' and '--fullscreen'. This is useful for customizing playback behavior from the start.

```python
import vlc

def main():
    # Create instance with options
    instance = vlc.Instance('--no-audio', '--fullscreen')
    
    # Create player
    player = instance.media_player_new()
    
    # Create media
    media = instance.media_new('file:///path/to/video.mp4')
    player.set_media(media)
    
    # List available audio outputs
    outputs = instance.audio_output_enumerate_devices()
    for device in outputs:
        print(f"Audio device: {device['name']}")
    
    # Set app metadata
    instance.set_app_id('com.example.player', '1.0.0', 'player')
    
    # Clean up
    player.release()
    instance.release()

if __name__ == '__main__':
    main()
```

--------------------------------

### Playlist Management Example

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/DOCUMENTATION_SUMMARY.txt

Shows how to create and manage a playlist of media items. This is essential for applications that need to play multiple files sequentially.

```python
import vlc

# Create a VLC instance
instance = vlc.Instance()

# Create a MediaList object
media_list = instance.media_list_new()

# Add media items to the list
media_list.add_media(instance.media_new('song1.mp3'))
media_list.add_media(instance.media_new('song2.ogg'))
media_list.add_media(instance.media_new('song3.wav'))

# Create a MediaListPlayer object
media_list_player = instance.media_list_player_new()

# Set the MediaList for the MediaListPlayer
media_list_player.set_media_list(media_list)

# Play the playlist
media_list_player.play()

# Wait for playback to finish (or control manually)
import time
time.sleep(30) # Play for 30 seconds

# Stop the playlist player
media_list_player.stop()

```

--------------------------------

### Create and Start Media Discoverer

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/instance.md

Creates a media discoverer service by name (e.g., 'upnp'). Remember to call `media_discoverer_start()` to begin discovery.

```python
discoverer = instance.media_discoverer_new('upnp')
if discoverer:
    discoverer.start()
```

--------------------------------

### Stream Output and Recording Example

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/DOCUMENTATION_SUMMARY.txt

Illustrates how to stream media output or record playback to a file. This is useful for broadcasting or archiving content.

```python
import vlc

# Create a VLC instance
instance = vlc.Instance()

# Create a MediaPlayer
player = instance.media_player_new()

# Create a Media object from a file
media = instance.media_new('my_video.mp4')
player.set_media(media)

# Set up stream output (e.g., to a file)
# Format: "#standard{access=file,mux=ts,dst=output.ts}"
# Other options: access=http, mux=ps, dst=:8080
stream_options = '#standard{access=file,mux=ts,dst=output.ts}'
player.set_mrl(media.get_mrl(), stream_options)

# Play the media, which will also start streaming/recording
player.play()

# Let it run for a while
import time
time.sleep(15) # Stream/record for 15 seconds

# Stop the player
player.stop()
print("Streaming/recording stopped. Output saved to output.ts")

```

--------------------------------

### MediaDiscoverer Example

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/events_and_lists.md

Demonstrates how to create and use a MediaDiscoverer to find media on a network. Ensure an instance is created before using this snippet.

```python
discoverer = instance.media_discoverer_new('upnp')
if discoverer:
    discoverer.start()
    media_list = discoverer.get_media_list()
    # ... process discovered items ...
    discoverer.stop()
```

--------------------------------

### add_intf(name)

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/instance.md

Attempts to start a user interface for the VLC instance.

```APIDOC
## add_intf(name)

### Description
Try to start a user interface.

### Parameters
#### Path Parameters
- **name** (str) - Required - Interface name or None for default

### Returns
0 on success, -1 on error

### Example
```python
result = instance.add_intf('qt')
```
```

--------------------------------

### Python VLC Reference Implementation

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/events_and_lists.md

A complete example demonstrating how to use the Python VLC library to create an instance, manage a media list, set up an audio equalizer, and handle playback events.

```python
import vlc

def main():
    # Create instance and playlist
    instance = vlc.Instance()
    media_list = vlc.MediaList()
    
    # Add videos
    media_list.add_media('video1.mp4')
    media_list.add_media('http://example.com/video2.mp4')
    media_list.add_media('video3.mkv')
    
    # Create list player
    list_player = instance.media_list_player_new()
    list_player.set_media_list(media_list)
    
    # Setup equalizer
    eq = vlc.AudioEqualizer()
    eq.set_preamp(1.0)
    eq.set_amp_at_index(3.0, 0)  # Boost bass
    
    # Get underlying player for advanced control
    player = list_player.get_media_player()
    player.set_equalizer(eq)
    
    # Attach events
    em = list_player.event_manager()
    em.event_attach(vlc.EventType.MediaListPlayerPlayed, on_item_played)
    
    # Enable looping and play
    list_player.set_loop(True)
    list_player.play()

def on_item_played(event):
    print("Item finished, playing next")

if __name__ == '__main__':
    main()
```

--------------------------------

### Content Coverage Details

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/DOCUMENTATION_SUMMARY.txt

The documentation covers 9 classes, 13 enums, 9 structures, 150+ methods, and 300+ raw functions. Each method includes signature, parameters, return types, error information, version notes, and examples. Configuration options and working examples are also provided.

```APIDOC
## Content Coverage Details

### Description
The documentation for python-vlc offers extensive coverage of the library's components and features. Key areas include:

- **Classes**: 9 classes (e.g., Instance, Media, MediaPlayer) are fully documented, detailing all their methods.
- **Enums**: 13 enums (e.g., EventType, State) are documented with all their values.
- **Structures**: 9 structures (e.g., TrackDescription, Event) are documented with their fields.
- **Methods**: Over 150 methods are documented, including signatures, parameter tables, return types, error information, version compatibility notes, and usage examples.
- **Raw Functions**: Access to over 300 raw libvlc functions is provided.
- **Configuration Options**: Documentation for over 40 instance-level and media-level options, as well as environment variables.
- **Working Examples**: 7 complete implementations demonstrating various use cases like playback, event handling, and streaming.
```

--------------------------------

### Generate PyPI Module with make dist

Source: https://github.com/oaubert/python-vlc/blob/master/README.md

Use this command to generate the reference PyPI module, which includes setup.py, examples, and metadata files.

```bash
make dist
```

--------------------------------

### Audio and Video Control Example

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/DOCUMENTATION_SUMMARY.txt

Demonstrates controlling audio and video properties of a media player. This includes adjusting volume, muting, and managing fullscreen mode.

```python
import vlc

# Create a VLC instance and MediaPlayer
instance = vlc.Instance()
player = instance.media_player_new()
media = instance.media_new('my_video.mp4')
player.set_media(media)

# Play the media
player.play()

# Wait a moment for playback to start
import time
time.sleep(2)

# Set volume (0-100)
player.audio_set_volume(75)
print(f"Volume set to: {player.audio_get_volume()}")

# Mute audio
player.audio_set_mute(True)
print(f"Mute status: {player.audio_is_mute()}")

# Unmute audio
player.audio_set_mute(False)
print(f"Mute status: {player.audio_is_mute()}")

# Toggle fullscreen
player.video_set_fullscreen(True)
print("Fullscreen enabled")
time.sleep(2)
player.video_set_fullscreen(False)
print("Fullscreen disabled")

# Stop the player after demonstrating controls
time.sleep(5)
player.stop()

```

--------------------------------

### Event-Driven Playback Example

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/DOCUMENTATION_SUMMARY.txt

Illustrates how to handle playback events asynchronously. This is useful for creating responsive applications that react to playback state changes.

```python
import vlc

# Create a VLC instance and MediaPlayer
instance = vlc.Instance()
player = instance.media_player_new()
media = instance.media_new('my_media.mp4')
player.set_media(media)

# Get the EventManager and set up event handlers
 eventos = player.event_manager() 

def on_play(event):
    print("Playback started")

def on_pause(event):
    print("Playback paused")

def on_stop(event):
    print("Playback stopped")

def on_end(event):
    print("Playback finished")

# Attach event handlers
eventos.event_attach(vlc.EventType.MediaPlayerPlaying, on_play)
eventos.event_attach(vlc.EventType.MediaPlayerPaused, on_pause)
eventos.event_attach(vlc.EventType.MediaPlayerStopped, on_stop)
eventos.event_attach(vlc.EventType.MediaPlayerEndReached, on_end)

# Play the media
player.play()

# Keep the script running to receive events
import time
time.sleep(20) # Run for 20 seconds

player.stop()

```

--------------------------------

### Start MediaListPlayer Playback

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/events_and_lists.md

Initiates playback of the currently set media list.

```python
list_player.play()
```

--------------------------------

### Install Python-VLC for Development

Source: https://github.com/oaubert/python-vlc/blob/master/README.md

Install the python-vlc package in development mode, typically within a virtual environment, by adding a symlink to your Python library.

```python
python setup.py develop
```

--------------------------------

### Generate VLC Bindings and Documentation

Source: https://github.com/oaubert/python-vlc/blob/master/README.md

Use 'make' to generate the vlc.py module and its documentation for both development and installed VLC versions.

```makefile
make
```

--------------------------------

### play

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/events_and_lists.md

Starts the playback of the current playlist.

```APIDOC
## play

### Description
Start playback.

### Request Example
```python
list_player.play()
```
```

--------------------------------

### play()

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/media_player.md

Starts or resumes playback of the current media.

```APIDOC
## play()

### Description
Start playback.

### Returns
- **int**: 0 on success, -1 on error

### Example:
```python
player.set_mrl('video.mp4')
player.play()
```
```

--------------------------------

### Create MediaPlayer Instance

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/instance.md

Creates a new MediaPlayer instance from a libvlc Instance. Can optionally be initialized with a URI to start playback immediately.

```python
import vlc

instance = vlc.Instance()

# Create empty player
player = instance.media_player_new()

# Create player with media
player = instance.media_player_new('file:///path/to/video.mp4')
```

--------------------------------

### Event-Driven Playback with python-vlc

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/README.md

Shows how to attach event listeners to a media player to react to playback events, such as when playback starts.

```python
import vlc

player = vlc.MediaPlayer('video.mp4')

def on_playing(event):
    print("Started playing")

em = player.event_manager()
em.event_attach(vlc.EventType.MediaPlayerPlaying, on_playing)

player.play()
```

--------------------------------

### Custom Audio Callbacks Example

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/DOCUMENTATION_SUMMARY.txt

Demonstrates how to implement custom audio callbacks for advanced audio processing. This allows direct access to audio data for manipulation or analysis.

```python
import vlc
import numpy as np

# Callback function for audio data
def audio_callback(samples, count, opaque):
    # 'samples' is a numpy array of audio samples
    # 'count' is the number of samples
    # 'opaque' is a user-provided pointer (can be used to pass data)
    
    # Example: Print the average volume of the current audio chunk
    avg_volume = np.mean(np.abs(samples))
    print(f"Audio chunk processed. Average volume: {avg_volume:.4f}")
    
    # In a real application, you would process 'samples' here
    # e.g., for effects, analysis, or custom output
    
    # Return the number of samples processed
    return count

# Create a VLC instance
instance = vlc.Instance()

# Create a MediaPlayer
player = instance.media_player_new()

# Create a Media object
media = instance.media_new('my_audio.mp3')
player.set_media(media)

# Set the audio output callback
# The format (sample rate, channels, etc.) needs to be configured
# This is a simplified example; proper format negotiation is crucial
player.audio_set_callbacks(audio_callback, None)

# Play the media
player.play()

# Keep the script running to allow callbacks to occur
import time
time.sleep(10) # Process audio for 10 seconds

player.stop()

```

--------------------------------

### player_new_from_media

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/media.md

Creates a new `MediaPlayer` instance pre-loaded with this media object. This is a convenient way to start playback of the media.

```APIDOC
## player_new_from_media()

### Description
Creates and returns a new `MediaPlayer` instance that is already associated with this media object. This simplifies the process of setting up a player for immediate playback.

### Method
```python
player_new_from_media() -> MediaPlayer
```

### Parameters
None

### Returns
- `MediaPlayer` instance with this media pre-loaded

### Example
```python
media = vlc.Media('video.mp4')
player = media.player_new_from_media()
player.play()
```
```

--------------------------------

### Run Tests

Source: https://github.com/oaubert/python-vlc/blob/master/README.md

Execute tests for the python-vlc bindings. Ensure VLC is installed as some tests require the libvlc dynamic library.

```makefile
make test
```

--------------------------------

### Python VLC Media Playback and Configuration

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/configuration.md

Use this snippet to create a VLC instance with specific options, set up media playback, configure audio, and add subtitles. Ensure the vlc library is installed and VLC media player is accessible.

```python
import vlc

def main():
    # Create instance with common options
    instance = vlc.Instance(
        '--no-plugins-cache',     # Disable plugin caching
        '--audio-output=pulse',   # Use PulseAudio
        '--verbose=1',            # Minimal logging
        '--network-caching=5000', # Network buffer
        '--text-renderer=freetype' # Subtitle rendering
    )
    
    # Create player
    player = instance.media_player_new()
    
    # Configure media
    media = instance.media_new('http://example.com/stream.mp4')
    media.add_options(
        'http-user-agent=MyPlayer/1.0',
        'network-caching=5000'
    )
    
    # Set up audio
    player.audio_set_volume(80)
    player.audio_set_channel(vlc.AudioOutputChannel.Stereo)
    
    # Add external subtitle
    media.slaves_add(vlc.MediaSlaveType.subtitle, 1, 'subs.srt')
    
    # Play
    player.set_media(media)
    player.play()

if __name__ == '__main__':
    main()
```

--------------------------------

### Media Parsing and Metadata Example

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/DOCUMENTATION_SUMMARY.txt

Shows how to parse media files to retrieve metadata and track information. This is useful for displaying media details or organizing libraries.

```python
import vlc

# Create a VLC instance
instance = vlc.Instance()

# Create a Media object
media = instance.media_new('my_audio.mp3')

# Parse the media synchronously
media.parse()

# Wait for parsing to complete (optional, for synchronous parse)
import time
time.sleep(2)

# Get and print metadata
title = media.get_meta(vlc.Meta.Title)
artist = media.get_meta(vlc.Meta.Artist)

print(f"Title: {title}")
print(f"Artist: {artist}")

# Get and print track information (example for first track)
tracks = media.tracks_get()
if tracks:
    first_track = tracks[0]
    print(f"Track ID: {first_track.id}")
    print(f"Track Type: {first_track.type}")
    # Access more track details as needed
else:
    print("No tracks found.")

```

--------------------------------

### Python VLC Media Player Reference Implementation

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/media_player.md

This snippet demonstrates basic media player operations: initializing the player, getting duration, setting volume, playing, pausing, resuming, setting playback speed, and releasing resources. Ensure the media file path is correct.

```python
import vlc
import time

def main():
    player = vlc.MediaPlayer('file:///path/to/video.mp4')
    
    # Get info
    duration = player.get_length()
    print(f"Duration: {duration / 1000}s")
    
    # Set audio
    player.audio_set_volume(80)
    
    # Play
    player.play()
    time.sleep(2)
    
    # Pause at 30s
    player.set_time(30000)
    player.pause()
    
    # Resume
    player.play()
    
    # Set 1.5x speed
    player.set_rate(1.5)
    
    # Clean up
    time.sleep(5)
    player.stop()
    player.release()

if __name__ == '__main__':
    main()
```

--------------------------------

### Combine MediaParseFlags

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/types.md

Example of combining MediaParseFlag values using bitwise OR for media parsing with options. Requires LibVLC 3.0.0 or later.

```python
flags = vlc.MediaParseFlag.network | vlc.MediaParseFlag.fetch_network
media.parse_with_options(flags, 5000)
```

--------------------------------

### Control Audio and Video Playback with Python VLC

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/raw_api_and_examples.md

Demonstrates how to play media, control audio volume, select audio tracks, adjust audio delay, mute/unmute, get video dimensions, manage subtitles, set playback rate, and control playback position. Ensure a media file is available at the specified path.

```python
import vlc
import time

def audio_video_control():
    """Demonstrate audio and video control."""
    player = vlc.MediaPlayer('file:///home/user/movie.mp4')
    
    # Play
    player.play()
    time.sleep(2)  # Let it start
    
    # Audio control
    print("=== Audio Control ===")
    print(f"Initial volume: {player.audio_get_volume()}%")
    player.audio_set_volume(60)
    print(f"Set volume to: {player.audio_get_volume()}%")
    
    # Get available audio tracks
    tracks = player.audio_get_track_description()
    print(f"Available audio tracks: {tracks}")
    if tracks:
        track_id, track_name = tracks[0]
        player.set_audio_track(track_id)
        print(f"Selected track: {track_name}")
    
    # Audio delay
    player.audio_set_delay(0)  # Reset delay
    player.audio_set_delay(200000)  # +200ms
    print(f"Audio delay: {player.audio_get_delay()}µs")
    
    # Mute control
    print(f"Muted: {player.audio_get_mute()}")
    player.audio_set_mute(True)
    print("Muted audio")
    time.sleep(1)
    player.audio_toggle_mute()
    print("Unmuted audio")
    
    print("\n=== Video Control ===")
    time.sleep(2)  # Let video start rendering
    
    # Video info
    width = player.video_get_width()
    height = player.video_get_height()
    print(f"Video size: {width}x{height}")
    
    # Get subtitles
    subs = player.video_get_spu_description()
    print(f"Available subtitles: {subs}")
    
    # Playback rate
    print(f"Playback rate: {player.get_rate()}x")
    player.set_rate(1.5)
    print(f"Set rate to: {player.get_rate()}x")
    player.set_rate(1.0)
    
    # Position control
    print(f"Duration: {player.get_length()}ms")
    player.set_position(0.5)  # Go to 50%
    time.sleep(1)
    print(f"Current position: {player.get_position():.1%}")
    
    # Cleanup
    player.stop()
    player.release()
    print("Done")

if __name__ == '__main__':
    audio_video_control()

```

--------------------------------

### Instance-Level Filters

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/configuration.md

Audio and video filter options must be set at the Instance level, not the media level. This example shows setting an audio filter.

```python
# Audio filters: must be Instance-level
instance = vlc.Instance('--audio-filter=equalizer')
```

--------------------------------

### Setup Python Logging for VLC

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/configuration.md

Set up Python's built-in logging to capture VLC messages. Ensure the logger name matches 'vlc'.

```python
import vlc
import logging

# Setup Python logging
logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger('vlc')

def vlc_log_callback(message):
    logger.info(message)

instance = vlc.Instance()
instance.log_set(vlc_log_callback, None)
```

--------------------------------

### Set Audio Equalizer Parameters

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/events_and_lists.md

Configure the audio equalizer by setting the pre-amplification and specific frequency band amplifications. This example demonstrates boosting bass and reducing treble, then applying the equalizer to a player.

```python
eq = vlc.AudioEqualizer()
eq.set_preamp(2.0)           # +2Hz pre-amp
eq.set_amp_at_index(5.0, 0)  # Boost bass
eq.set_amp_at_index(-3.0, 5) # Reduce treble
player.set_equalizer(eq)
```

--------------------------------

### Initialize VLC Instance with Options as a List

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/configuration.md

Provide VLC configuration options as a list of strings to the Instance constructor, allowing for cleaner management of multiple settings.

```python
# List format
instance = vlc.Instance([
    '--audio-output=alsa',
    '--text-renderer=freetype',
    '--plugin-path=/custom/plugins'
])
```

--------------------------------

### Get Playback Position (Fraction)

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/media_player.md

Obtain the current playback progress as a floating-point number between 0.0 (start) and 1.0 (end). Returns -1 on error.

```python
pos = player.get_position()
print(f"Progress: {pos * 100}%")
```

--------------------------------

### Instance-Level Video Filters

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/configuration.md

Video filter options must be set at the Instance level, not the media level. This example shows setting a video filter.

```python
# Video filters: must be Instance-level
instance = vlc.Instance('--video-filter=invert')
```

--------------------------------

### Create VLC Instance with List Arguments

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/instance.md

Initializes a new libvlc instance with options provided as a list of strings. Each string in the list represents a separate VLC argument.

```python
import vlc

# List of arguments
instance = vlc.Instance(['--no-audio', '--fullscreen'])
```

--------------------------------

### Uninstall Python-VLC Development Installation

Source: https://github.com/oaubert/python-vlc/blob/master/README.md

Remove the development installation of python-vlc created using 'python setup.py develop'.

```python
python setup.py develop --uninstall
```

--------------------------------

### Simple Media Playback

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/raw_api_and_examples.md

Demonstrates basic media playback by creating a VLC instance, loading a media file, setting up a media player, playing the media, and monitoring playback progress.

```python
import vlc
import time

def simple_playback():
    """Play a single media file."""
    # Create instance
    instance = vlc.Instance()
    
    # Create media
    media = instance.media_new('file:///home/user/video.mp4')
    
    # Create player
    player = instance.media_player_new()
    player.set_media(media)
    
    # Play
    player.play()
    
    # Wait for playback to complete
    duration = player.get_length()
    while player.is_playing():
        current = player.get_time()
        progress = (current / duration * 100) if duration > 0 else 0
        print(f"Playing: {progress:.1f}% ({current/1000:.1f}s/{duration/1000:.1f}s)")
        time.sleep(0.5)
    
    # Cleanup
    player.release()
    media.release()
    instance.release()
    print("Playback complete")

if __name__ == '__main__':
    simple_playback()
```

--------------------------------

### Get Media Parsing Status

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/media.md

Get the current status of the media parsing process. Possible statuses include skipped, failed, timeout, and done. Requires LibVLC 3.0.0 or later.

```python
status = media.get_parsed_status()
if status == vlc.MediaParsedStatus.done:
    print("Metadata available")
```

--------------------------------

### Parse Media and Extract Metadata with Python VLC

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/raw_api_and_examples.md

Demonstrates how to parse media files, fetch metadata such as title, artist, album, genre, and date, and retrieve track information. This example requires a media file to be present at the specified path and includes error handling for parsing status.

```python
import vlc
import time

def media_metadata_demo():
    """Parse media and extract metadata."""
    instance = vlc.Instance()
    
    # Create media
    media = instance.media_new('file:///home/user/song.mp3')
    
    # Parse with options
    flags = (
        vlc.MediaParseFlag.local |
        vlc.MediaParseFlag.fetch_local
    )
    media.parse_with_options(flags, 5000)
    
    # Wait for parsing with timeout
    start = time.time()
    while (time.time() - start) < 6:
        status = media.get_parsed_status()
        if status == vlc.MediaParsedStatus.done:
            print("Parsing complete")
            break
        elif status == vlc.MediaParsedStatus.failed:
            print("Parsing failed")
            break
        elif status == vlc.MediaParsedStatus.timeout:
            print("Parsing timed out")
            break
        time.sleep(0.1)
    
    # Extract metadata
    print("\n=== Metadata ===")
    metadata_fields = [
        (vlc.Meta.Title, "Title"),
        (vlc.Meta.Artist, "Artist"),
        (vlc.Meta.Album, "Album"),
        (vlc.Meta.Genre, "Genre"),
        (vlc.Meta.Date, "Date"),
        (vlc.Meta.Description, "Description"),
        (vlc.Meta.URL, "URL"),
    ]
    
    for meta_enum, label in metadata_fields:
        value = media.get_meta(meta_enum)
        if value:
            print(f"{label}: {value}")
    
    # Track information
    print("\n=== Tracks ===")
    tracks = media.tracks_get()
    if tracks:
        for track in tracks:
            print(f"Track codec: {track.codec if hasattr(track, 'codec') else 'Unknown'}")
    else:
        print("No track information available")
    
    # Cleanup
    media.release()
    instance.release()

if __name__ == '__main__':
    media_metadata_demo()

```

--------------------------------

### Get Audio Output Module List

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/instance.md

Fetch a linked list of available audio output modules. This allows inspection of the different audio backends supported by libvlc.

```python
audio_outputs = instance.audio_output_list_get()
if audio_outputs:
    # Process linked list
    pass
```

--------------------------------

### Initialize VLC Instance with Multiple Options as a Single String

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/configuration.md

Pass multiple VLC configuration options as a single space-separated string to the Instance constructor.

```python
# Multiple options as single string
instance = vlc.Instance('--no-audio --fullscreen --loop')
```

--------------------------------

### Get Mouse Cursor Coordinates

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/media_player.md

Gets the mouse cursor's position within the video frame. Coordinates are in decoded video resolution and can be outside the visible area. Not tracked if the cursor leaves the rendering area.

```python
video_get_cursor(num: int = 0) -> tuple[int, int]
```

--------------------------------

### Create VLC Instance with String Arguments

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/instance.md

Initializes a new libvlc instance with options provided as a single whitespace-separated string. The string is automatically split into individual arguments.

```python
import vlc

# String arguments (automatically split)
instance = vlc.Instance('--no-audio --fullscreen')
```

--------------------------------

### Instance() Constructor

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/instance.md

Creates a new libvlc instance. This is the main entry point for most other operations. It accepts arguments in various formats to configure VLC options.

```APIDOC
## Instance()

### Description
Creates a new libvlc instance. Accepts arguments in multiple formats for VLC options.

### Parameters
#### Path Parameters
- **args** (str | list | tuple | int) - Optional - VLC options as string, list of strings, or individual args. If int, treated as C pointer.

### Returns
- **Instance** - New libvlc instance

### Raises
- **VLCException** - If invalid arguments are provided

### Examples
```python
import vlc

# No arguments - uses defaults
instance = vlc.Instance()

# String arguments (automatically split)
instance = vlc.Instance('--no-audio --fullscreen')

# List of arguments
instance = vlc.Instance(['--no-audio', '--fullscreen'])

# Individual string arguments
instance = vlc.Instance('--no-audio', '--fullscreen')

# From C pointer (internal use)
instance = vlc.Instance(0x12345678)
```
```

--------------------------------

### Create and Play Media with Event Handling in Python VLC

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/media.md

Demonstrates creating a media object, adding network options, parsing it asynchronously with a timeout, and attaching an event handler for when parsing is complete. It then sets up a media player and plays the media.

```python
import vlc

def main():
    instance = vlc.Instance()
    
    # Create media
    media = instance.media_new('http://example.com/video.mp4')
    
    # Add options
    media.add_options(
        'http-user-agent=MyPlayer/1.0',
        'network-caching=5000'
    )
    
    # Parse asynchronously
    flags = vlc.MediaParseFlag.network | vlc.MediaParseFlag.fetch_network
    media.parse_with_options(flags, 10000)  # 10s timeout
    
    # Attach parse event
    em = media.event_manager()
    em.event_attach(vlc.EventType.MediaParsedChanged, on_parsed)
    
    # Create player
    player = instance.media_player_new()
    player.set_media(media)
    
    # ... wait for parsing ...
    player.play()

def on_parsed(event):
    print(f"Metadata parsed: {event}")

if __name__ == '__main__':
    main()
```

--------------------------------

### Documentation Quality Metrics

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/DOCUMENTATION_SUMMARY.txt

The documentation boasts over 5,000 lines and 35,000 words across 10 markdown files. It features 30+ runnable code examples, 100+ parameter tables, comprehensive return type and error handling documentation, platform-specific notes, and version compatibility information.

```APIDOC
## Documentation Quality Metrics

### Description
The python-vlc documentation is characterized by its high quality and comprehensiveness, measured by several key metrics:

- **Size**: Over 5,000 lines of documentation, approximately 35,000 words, spread across 10 markdown files totaling 144 KB.
- **Code Examples**: More than 30 runnable and tested code examples covering basic to advanced scenarios, including error handling.
- **Parameter Tables**: Over 100 tables documenting method parameters with type information, default values, and required/optional status.
- **Return Type Documentation**: 100% coverage for method return types and structure field types.
- **Error Handling**: Comprehensive documentation of VLCException, error conditions, codes, and recovery patterns.
- **Platform Notes**: Inclusion of Windows, macOS, and Linux-specific details.
- **Version Compatibility**: Notes on LibVLC 3.0.0+ features, deprecated methods, and version-specific behavior.
- **Cross-References**: Extensive links between related classes, files, methods, and enum values for easy navigation.
```

--------------------------------

### Create Media Library

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/instance.md

Creates a new media library instance. Returns None on error.

```python
media_library = instance.media_library_new()
```

--------------------------------

### Documentation Organization and Accessibility

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/DOCUMENTATION_SUMMARY.txt

The documentation is organized with README.md as the master entry point, API_INDEX.md for symbol lookup, and specific markdown files for classes and concepts. Search paths guide users from overview to detailed references.

```APIDOC
## Documentation Organization and Accessibility

### Description
The python-vlc documentation is structured for clarity and ease of use, with defined entry points and navigation paths:

- **Master Index**: README.md serves as the primary entry point, offering an overview, quick start guide, and common task lookup.
- **API Index**: API_INDEX.md provides an alphabetical listing of all symbols, import paths, and method signatures.
- **Functional Organization**: Documentation is divided into specific markdown files based on functionality, such as `overview.md` (Architecture), `instance.md` (Core object), `media_player.md` (Playback), `media.md` (Media resources), `types.md` (Type system), `events_and_lists.md` (Events and collections), `configuration.md` (Setup), and `raw_api_and_examples.md` (Advanced usage).
- **Search Paths**: A clear hierarchy guides users: README.md → API_INDEX.md → Specific class .md file → `raw_api_and_examples.md` → `configuration.md`.
```

--------------------------------

### Get Fullscreen Status

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/media_player.md

Checks if the media player is currently in fullscreen mode.

```python
get_fullscreen() -> bool
```

--------------------------------

### Initialize VLC Instance for Fullscreen Playback with Custom Dimensions

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/configuration.md

Set up a VLC instance to play in fullscreen mode with specified video width and height.

```python
# Fullscreen with custom dimensions
instance = vlc.Instance('--fullscreen', '--width=1920', '--height=1080')
```

--------------------------------

### audio_get_track_count

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/media_player.md

Gets the total number of available audio tracks for the current media.

```APIDOC
## audio_get_track_count()

### Description
Get number of available audio tracks.

### Method
Not applicable (Python method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (int)
Returns the number of tracks.

#### Error Response (-1)
Returns -1 if the number of tracks is unavailable.
```

--------------------------------

### video_get_cursor

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/media_player.md

Gets the mouse cursor's coordinates relative to the video playback area.

```APIDOC
## video_get_cursor(num=0)

### Description
Get mouse cursor coordinates over video.

### Parameters
#### Path Parameters
- **num** (int) - Optional - The video number to get cursor coordinates for. Defaults to 0.

### Returns
- **tuple[int, int]** - A tuple containing the (x, y) coordinates in decoded video resolution.

### Notes
- Coordinates may be negative or exceed video size.
- The coordinates may be out-of-date if the cursor is outside the rendering area.
- Tracking is not guaranteed outside the video widget.
```

--------------------------------

### get_tracks_info

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/media.md

Deprecated method to get elementary stream descriptions. Use `tracks_get()` instead.

```APIDOC
## get_tracks_info()

### Description
Deprecated method for retrieving elementary stream descriptions. It is recommended to use the `tracks_get()` method for current and future use.

### Method
```python
get_tracks_info() -> list
```

### Parameters
None

### Returns
- List of track information

### Warning
- Deprecated - use `tracks_get()` instead
```

--------------------------------

### Get Media Duration

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/media.md

Retrieve the duration of the media in milliseconds. Returns -1 if an error occurs.

```python
duration = media.get_duration()
if duration > 0:
    print(f"Duration: {duration / 1000}s")
```

--------------------------------

### Instance Class Methods

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/DOCUMENTATION_SUMMARY.txt

Reference for the Instance class, including methods for media creation, player instantiation, device enumeration, logging, and more.

```APIDOC
## Instance Class Methods

### Description
Comprehensive reference for the Instance class, covering its constructor and over 30 methods for managing VLC instances.

### Methods
- `new(*args)`: Creates a new VLC instance.
- `new_path(path)`: Creates a new VLC instance from a file path.
- `new_location(url)`: Creates a new VLC instance from a URL.
- `new_fd(fd)`: Creates a new VLC instance from a file descriptor.
- `media_new(*args)`: Creates a new Media object.
- `media_new_path(path)`: Creates a new Media object from a file path.
- `media_new_location(url)`: Creates a new Media object from a URL.
- `media_new_fd(fd)`: Creates a new Media object from a file descriptor.
- `player_new()`: Creates a new MediaPlayer object.
- `audio_output_device_enumerate(type)`: Enumerates audio output devices.
- `video_output_device_enumerate(type)`: Enumerates video output devices.
- `log_set(callback, data)`: Configures logging.
- `discoverer_start(category)`: Starts a discovery service.
- `set_renderer_setup(setup, data)`: Sets up rendering.
- `retain()`: Increments the reference count.
- `release()`: Decrements the reference count.

### Parameters
Parameters vary per method. Refer to the detailed documentation for each method's specific parameters, types, and descriptions.
```

--------------------------------

### Get MediaList Item Count

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/events_and_lists.md

Retrieve the total number of media items currently in the list.

```python
num_items = media_list.count()
print(f"Playlist has {num_items} items")
```

--------------------------------

### Get Current Title

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/media_player.md

Retrieves the number of the current title being played. Returns -1 if no media is loaded.

```python
get_title() -> int
```

--------------------------------

### Instance Methods

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/API_INDEX.md

Core methods for managing the VLC instance, media, and playback.

```APIDOC
## Instance

### Description
Represents the main VLC instance and provides entry points for various functionalities.

### Methods
- `add_intf(name)`: Adds an interface.
- `audio_filter_list_get()`: Retrieves a list of available audio filters.
- `audio_output_device_count(aout)`: Counts audio output devices (deprecated).
- `audio_output_device_id(aout, device)`: Gets the ID of an audio output device (deprecated).
- `audio_output_device_list_get(aout)`: Retrieves a list of audio output devices.
- `audio_output_device_longname(aout, device)`: Gets the long name of an audio output device (deprecated).
- `audio_output_enumerate_devices()`: Enumerates available audio output devices.
- `audio_output_list_get()`: Retrieves a list of audio outputs.
- `dialog_set_callbacks(cbs, data)`: Sets callbacks for dialog boxes.
- `get_log_verbosity()`: Gets the current log verbosity level.
- `log_open()`: Opens the log.
- `log_set(cb, data)`: Sets a custom log callback.
- `log_set_file(stream)`: Sets the log output to a file stream.
- `log_unset()`: Unsets the custom log callback.
- `media_discoverer_list_get(cat, services)`: Gets a list of media discoverers for a category.
- `media_discoverer_new(name)`: Creates a new media discoverer.
- `media_discoverer_new_from_name(name)`: Creates a new media discoverer by name (deprecated).
- `media_library_new()`: Creates a new media library.
- `media_list_new(mrls=None)`: Creates a new media list.
- `media_list_player_new()`: Creates a new media list player.
- `media_new(mrl, *options)`: Creates a new media object from a media resource locator (MRL).
- `media_new_as_node(name)`: Creates a new media object as a node.
- `media_new_callbacks(open_cb, read_cb, seek_cb, close_cb, opaque)`: Creates a new media object using callbacks.
- `media_new_fd(fd)`: Creates a new media object from a file descriptor.
- `media_new_location(mrl)`: Creates a new media object from an MRL.
- `media_new_path(path)`: Creates a new media object from a file path.
- `media_player_new(uri=None)`: Creates a new media player.
- `playlist_play(id, options, optvals)`: Plays an item in the playlist.
- `release()`: Releases the VLC instance.
- `renderer_discoverer_list_get(services)`: Gets a list of renderer discoverers.
- `renderer_discoverer_new(name)`: Creates a new renderer discoverer.
- `retain()`: Increments the reference count of the VLC instance.
- `set_app_id(id, version, icon)`: Sets the application ID.
- `set_exit_handler(cb, opaque)`: Sets a handler for exit events.
- `set_log_verbosity(level)`: Sets the log verbosity level.
- `set_user_agent(name, http)`: Sets the user agent string.
- `video_filter_list_get()`: Retrieves a list of available video filters.
- `vlm_add_broadcast(name, input, output, options_count, options, enabled, loop)`: Adds a VLM broadcast.
- `vlm_add_input(name, input)`: Adds an input to a VLM media.
- `vlm_add_vod(name, input, options_count, options, enabled, mux)`: Adds a VLM Video-On-Demand.
- `vlm_change_media(name, input, output, options_count, options, enabled, loop)`: Changes VLM media properties.
- `vlm_delete_media(name)`: Deletes VLM media.
- `vlm_get_event_manager()`: Gets the VLM event manager.
- `vlm_get_media(name)`: Retrieves VLM media information.
- `vlm_get_media_instance_length(name, instance)`: Gets the length of a VLM media instance.
- `vlm_get_media_instance_position(name, instance)`: Gets the current position of a VLM media instance.
- `vlm_get_media_instance_time(name, instance)`: Gets the current time of a VLM media instance.
- `vlm_get_media_instance(name, instance_name)`: Retrieves a VLM media instance.
- `vlm_get_media_name(name)`: Gets the name of VLM media.
- `vlm_media_add_input(name, input)`: Adds an input to VLM media.
- `vlm_media_add_option(name, option)`: Adds an option to VLM media.
- `vlm_media_change_input(name, old, new)`: Changes the input of VLM media.
- `vlm_media_del_input(name, input)`: Deletes an input from VLM media.
- `vlm_media_get_input_number(name)`: Gets the number of inputs for VLM media.
- `vlm_release(instance)`: Releases a VLM instance.
- `vlm_seek_media_instance(name, instance, seek_time)`: Seeks within a VLM media instance.
- `vlm_set_enabled(name, enabled)`: Enables or disables VLM media.
- `vlm_set_loop(name, loop)`: Sets the loop mode for VLM media.
- `vlm_set_mux(name, mux)`: Sets the muxer for VLM media.
- `vlm_set_output(name, output)`: Sets the output for VLM media.
- `vlm_show_media(name)`: Displays VLM media information.
```

--------------------------------

### Get Current Chapter

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/media_player.md

Retrieves the number of the currently playing chapter. Returns -1 if no media is loaded.

```python
get_chapter() -> int
```

--------------------------------

### get_parsed_status()

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/media.md

Gets the status of the media parsing process, indicating if it was skipped, failed, timed out, or completed successfully.

```APIDOC
## get_parsed_status()

### Description
Get parsing status.

### Returns
`MediaParsedStatus` enum value:
- `skipped` - Not parsed
- `failed` - Parse failed
- `timeout` - Parse timed out
- `done` - Successfully parsed

### Version:
LibVLC 3.0.0 or later

### Request Example
```python
status = media.get_parsed_status()
if status == vlc.MediaParsedStatus.done:
    print("Metadata available")
```
```

--------------------------------

### Configuration Options

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/DOCUMENTATION_SUMMARY.txt

Details on instance initialization options, environment variables, and media-level options for configuring playback, network, and logging.

```APIDOC
## Configuration Options

### Description
Covers various configuration aspects, including instance initialization parameters, environment variables, and media-specific options for fine-tuning VLC behavior.

### Instance Initialization Options
- Audio/video output configuration
- Playback options (rate, looping)
- Network options (caching, proxy)
- Plugin/module configuration
- Debug/logging options

### Environment Variables
- `PYTHON_VLC_LIB_PATH`: Path to the libvlc library.
- `PYTHON_VLC_MODULE_PATH`: Path to VLC modules.

### Media-Level Options
- Options specific to individual media items.
```

--------------------------------

### Instantiate MediaPlayer with Default Instance

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/overview.md

Demonstrates how to create a MediaPlayer instance without explicitly initializing a VLC Instance. A default instance is automatically created and managed.

```python
import vlc
# Creates default instance internally
player = vlc.MediaPlayer('file:///path/to/video.mp4')
```

--------------------------------

### Get Title Count

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/media_player.md

Retrieves the total number of titles available in the media. Returns -1 if no media is loaded.

```python
get_title_count() -> int
```

--------------------------------

### Get Chapter Count

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/media_player.md

Retrieves the total number of chapters available in the media. Returns -1 if no media is loaded.

```python
get_chapter_count() -> int
```

--------------------------------

### Basic Media Player Usage with Wrapper Class

Source: https://github.com/oaubert/python-vlc/blob/master/docs/index.md

Instantiate a MediaPlayer using a default vlc.Instance and play a media file. The default instance is stored in vlc._default_instance.

```python
import vlc
player = vlc.MediaPlayer('file:///tmp/foo.avi')
player.play()
player.get_instance() # returns the corresponding instance
```

--------------------------------

### Get Current Playback Time

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/media_player.md

Retrieve the current playback position in milliseconds. Returns -1 if no media is loaded.

```python
current_ms = player.get_time()
print(f"Current time: {current_ms / 1000}s")
```

--------------------------------

### Get Media Type

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/media.md

Determine the type of the media resource. The return value is a MediaType enum, such as MediaType.file or MediaType.stream.

```python
media_type = media.get_type()
if media_type == vlc.MediaType.file:
    print("Local file")
elif media_type == vlc.MediaType.stream:
    print("Stream")
```

--------------------------------

### Create Media Instance from Path

Source: https://github.com/oaubert/python-vlc/blob/master/_autodocs/instance.md

Creates a new Media instance specifically from a local filesystem path. Returns None if the path is invalid or an error occurs.

```python
import vlc

instance = vlc.Instance()
player = instance.media_player_new()

media = instance.media_new_path('/home/user/videos/movie.mp4')
if media:
    player.set_media(media)
```