CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-python-vlc

VLC bindings for Python providing comprehensive multimedia functionality through LibVLC API.

—

Pending
Overview
Eval results
Files

video-control.mddocs/

Video Control

Video control capabilities including video tracks, aspect ratio, cropping, subtitle management, video effects, and display settings. These features provide comprehensive control over video playback and presentation.

Capabilities

Video Display Control

Basic video display and sizing methods available on MediaPlayer for managing video output and dimensions.

# Video display methods on MediaPlayer
def video_get_width(self):
    """Get the video width in pixels.
    
    Returns:
        int: Video width, or 0 if no video
    """
    ...

def video_get_height(self):
    """Get the video height in pixels.
    
    Returns:
        int: Video height, or 0 if no video
    """
    ...

def video_get_size(self, num=0):
    """Get video dimensions as a tuple.
    
    Args:
        num (int): Video output number (usually 0)
        
    Returns:
        tuple: (width, height) or (0, 0) if no video
    """
    ...

def video_get_cursor(self, num=0):
    """Get cursor coordinates over video.
    
    Args:
        num (int): Video output number (usually 0)
        
    Returns:
        tuple: (x, y) cursor coordinates
    """
    ...

def video_get_scale(self):
    """Get the current video scaling factor.
    
    Returns:
        float: Scaling factor (1.0 = original size)
    """
    ...

def video_set_scale(self, scale):
    """Set the video scaling factor.
    
    Args:
        scale (float): Scaling factor (0 = fit to window, 1.0 = original size)
    """
    ...

def video_get_aspect_ratio(self):
    """Get the current video aspect ratio.
    
    Returns:
        str: Aspect ratio string (e.g., "4:3", "16:9") or None
    """
    ...

def video_set_aspect_ratio(self, ratio):
    """Set the video aspect ratio.
    
    Args:
        ratio (str): Aspect ratio string (e.g., "4:3", "16:9") or None for original
    """
    ...

Video Cropping and Geometry

Methods for controlling video cropping and geometric transformations.

# Video cropping methods on MediaPlayer
def video_get_crop_geometry(self):
    """Get the current video crop geometry.
    
    Returns:
        str: Crop geometry string or None
    """
    ...

def video_set_crop_geometry(self, geometry):
    """Set the video crop geometry.
    
    Args:
        geometry (str): Crop geometry string (e.g., "640x480+10+10") or None
    """
    ...

def video_get_teletext(self):
    """Get the current teletext page.
    
    Returns:
        int: Current teletext page number
    """
    ...

def video_set_teletext(self, page):
    """Set the teletext page.
    
    Args:
        page (int): Teletext page number
    """
    ...

def video_take_snapshot(self, num, filepath, width, height):
    """Take a video snapshot.
    
    Args:
        num (int): Video output number (usually 0)
        filepath (str): Path to save the snapshot
        width (int): Snapshot width (0 for original)
        height (int): Snapshot height (0 for original)
        
    Returns:
        int: 0 on success, -1 on error
    """
    ...

def video_update_viewpoint(self, p_viewpoint, b_absolute):
    """Update viewpoint for 360° video navigation. (LibVLC 3.0.0+)
    
    Args:
        p_viewpoint: Video viewpoint structure (from libvlc_video_new_viewpoint())
        b_absolute (bool): True to replace old viewpoint, False to increase/decrease
        
    Returns:
        int: 0 on success, -1 on error
    """
    ...

360° Video Support

Methods for controlling 360°/VR video playback and viewpoint navigation (LibVLC 3.0.0+).

# 360° video support functions
def libvlc_video_new_viewpoint():
    """Create a video viewpoint structure for 360° video control.
    
    Returns:
        VideoViewpoint: New viewpoint structure (must be freed with libvlc_free)
    """
    ...

def video_update_viewpoint(self, p_viewpoint, b_absolute):
    """Update viewpoint for 360° video navigation.
    
    Args:
        p_viewpoint: Video viewpoint structure
        b_absolute (bool): True to replace old viewpoint, False to modify current
        
    Returns:
        int: 0 on success, -1 on error
    """
    ...

Video Track Management

Methods for managing video tracks in multi-track media.

# Video track methods on MediaPlayer
def video_get_track_count(self):
    """Get the number of available video tracks.
    
    Returns:
        int: Number of video tracks
    """
    ...

def video_get_track(self):
    """Get the current video track.
    
    Returns:
        int: Current video track ID, or -1 if none
    """
    ...

def video_set_track(self, track):
    """Set the current video track.
    
    Args:
        track (int): Video track ID to select
        
    Returns:
        int: 0 on success, -1 on error
    """
    ...

def video_get_track_description(self):
    """Get descriptions of available video tracks.
    
    Returns:
        list: List of (track_id, track_name) tuples
    """
    ...

Subtitle Management

Comprehensive subtitle control including subtitle track selection and subtitle file loading.

# Subtitle methods on MediaPlayer
def video_get_spu_count(self):
    """Get the number of available subtitle tracks.
    
    Returns:
        int: Number of subtitle tracks
    """
    ...

def video_get_spu(self):
    """Get the current subtitle track.
    
    Returns:
        int: Current subtitle track ID, or -1 if none
    """
    ...

def video_set_spu(self, spu):
    """Set the current subtitle track.
    
    Args:
        spu (int): Subtitle track ID to select (-1 to disable)
        
    Returns:
        int: 0 on success, -1 on error
    """
    ...

def video_get_spu_description(self):
    """Get descriptions of available subtitle tracks.
    
    Returns:
        list: List of (spu_id, spu_name) tuples
    """
    ...

def video_set_subtitle_file(self, filename):
    """Load a subtitle file.
    
    Args:
        filename (str): Path to subtitle file
        
    Returns:
        bool: True on success, False on error
    """
    ...

def video_get_spu_delay(self):
    """Get the current subtitle delay in microseconds.
    
    Returns:
        int: Subtitle delay in microseconds
    """
    ...

def video_set_spu_delay(self, delay):
    """Set the subtitle delay.
    
    Args:
        delay (int): Subtitle delay in microseconds
        
    Returns:
        int: 0 on success, -1 on error
    """
    ...

Video Filters and Effects

Methods for applying video filters and effects.

# Video filter methods on MediaPlayer
def video_get_adjust_int(self, option):
    """Get a video adjustment integer value.
    
    Args:
        option (VideoAdjustOption): Adjustment option
        
    Returns:
        int: Current value
    """
    ...

def video_set_adjust_int(self, option, value):
    """Set a video adjustment integer value.
    
    Args:
        option (VideoAdjustOption): Adjustment option
        value (int): Value to set
    """
    ...

def video_get_adjust_float(self, option):
    """Get a video adjustment float value.
    
    Args:
        option (VideoAdjustOption): Adjustment option
        
    Returns:
        float: Current value
    """
    ...

def video_set_adjust_float(self, option, value):
    """Set a video adjustment float value.
    
    Args:
        option (VideoAdjustOption): Adjustment option
        value (float): Value to set
    """
    ...

def video_get_logo_int(self, option):
    """Get a video logo integer option.
    
    Args:
        option (VideoLogoOption): Logo option
        
    Returns:
        int: Current value
    """
    ...

def video_set_logo_int(self, option, value):
    """Set a video logo integer option.
    
    Args:
        option (VideoLogoOption): Logo option
        value (int): Value to set
    """
    ...

def video_set_logo_string(self, option, value):
    """Set a video logo string option.
    
    Args:
        option (VideoLogoOption): Logo option
        value (str): Value to set
    """
    ...

def video_get_marquee_int(self, option):
    """Get a video marquee integer option.
    
    Args:
        option (VideoMarqueeOption): Marquee option
        
    Returns:
        int: Current value
    """
    ...

def video_set_marquee_int(self, option, value):
    """Set a video marquee integer option.
    
    Args:
        option (VideoMarqueeOption): Marquee option
        value (int): Value to set
    """
    ...

def video_set_marquee_string(self, option, value):
    """Set a video marquee string option.
    
    Args:
        option (VideoMarqueeOption): Marquee option
        value (str): Value to set
    """
    ...

Platform-Specific Display Integration

Methods for integrating with platform-specific display systems.

# Platform display methods on MediaPlayer
def set_hwnd(self, hwnd):
    """Set Win32 window handle for video output.
    
    Args:
        hwnd (int): Windows window handle
    """
    ...

def get_hwnd(self):
    """Get the current Win32 window handle.
    
    Returns:
        int: Current window handle or 0
    """
    ...

def set_xwindow(self, xwindow):
    """Set X11 window ID for video output.
    
    Args:
        xwindow (int): X11 window ID
    """
    ...

def get_xwindow(self):
    """Get the current X11 window ID.
    
    Returns:
        int: Current X11 window ID or 0
    """
    ...

def set_nsobject(self, nsobject):
    """Set macOS NSObject for video output.
    
    Args:
        nsobject: macOS NSView or NSWindow object
    """
    ...

def get_nsobject(self):
    """Get the current macOS NSObject.
    
    Returns:
        NSObject or None
    """
    ...

def set_agl(self, agl):
    """Set macOS AGL context for video output.
    
    Args:
        agl: AGL context
    """
    ...

def get_agl(self):
    """Get the current macOS AGL context.
    
    Returns:
        AGL context or 0
    """
    ...

Video Adjustment Options

Enumeration for video adjustment parameters.

class VideoAdjustOption:
    """Video adjustment options for filters."""
    Enable = 0
    Contrast = 1
    Brightness = 2
    Hue = 3
    Saturation = 4
    Gamma = 5

Video Logo Options

Enumeration for video logo overlay parameters.

class VideoLogoOption:
    """Video logo overlay options."""
    Enable = 0
    File = 1
    X = 2
    Y = 3
    Delay = 4
    Repeat = 5
    Opacity = 6
    Position = 7
    Size = 8

Video Marquee Options

Enumeration for video marquee text overlay parameters.

class VideoMarqueeOption:
    """Video marquee text overlay options."""
    Enable = 0
    Text = 1
    Color = 2
    Opacity = 3
    Position = 4
    Refresh = 5
    Size = 6
    Timeout = 7
    X = 8
    Y = 9

Usage Examples

Basic Video Information

import vlc

player = vlc.MediaPlayer('/path/to/video.mp4')
player.play()

# Wait for video to start
import time
time.sleep(1)

# Get video dimensions
width = player.video_get_width()
height = player.video_get_height()
print(f"Video size: {width}x{height}")

# Get video size as tuple
size = player.video_get_size()
print(f"Video size tuple: {size}")

# Get and set aspect ratio
ratio = player.video_get_aspect_ratio()
print(f"Current aspect ratio: {ratio}")
player.video_set_aspect_ratio("16:9")

Video Scaling and Cropping

import vlc

player = vlc.MediaPlayer('/path/to/video.mp4')
player.play()

# Scale video to 150% of original size
player.video_set_scale(1.5)
current_scale = player.video_get_scale()
print(f"Current scale: {current_scale}")

# Set custom crop geometry (width x height + x_offset + y_offset)
player.video_set_crop_geometry("640x480+10+10")
crop = player.video_get_crop_geometry()
print(f"Current crop: {crop}")

# Reset to original size and no cropping
player.video_set_scale(1.0)
player.video_set_crop_geometry(None)

Video Track Selection

import vlc

player = vlc.MediaPlayer('/path/to/multi_video_stream.mkv')
player.play()

# List available video tracks
track_count = player.video_get_track_count()
print(f"Available video tracks: {track_count}")

tracks = player.video_get_track_description()
for track_id, track_name in tracks:
    print(f"Video Track {track_id}: {track_name}")

# Select specific video track
if track_count > 1:
    player.video_set_track(1)
    current_track = player.video_get_track()
    print(f"Current video track: {current_track}")

Subtitle Management

import vlc

player = vlc.MediaPlayer('/path/to/video.mp4')
player.play()

# Load external subtitle file
subtitle_loaded = player.video_set_subtitle_file('/path/to/subtitles.srt')
print(f"Subtitle loaded: {subtitle_loaded}")

# List available subtitle tracks
spu_count = player.video_get_spu_count()
print(f"Available subtitle tracks: {spu_count}")

spus = player.video_get_spu_description()
for spu_id, spu_name in spus:
    print(f"Subtitle Track {spu_id}: {spu_name}")

# Select subtitle track
if spu_count > 0:
    player.video_set_spu(1)  # Enable first subtitle track
    current_spu = player.video_get_spu()
    print(f"Current subtitle track: {current_spu}")

# Adjust subtitle delay (100ms forward)
player.video_set_spu_delay(100000)  # 100000 microseconds = 100ms
delay = player.video_get_spu_delay()
print(f"Subtitle delay: {delay} microseconds")

Taking Video Snapshots

import vlc
import time

player = vlc.MediaPlayer('/path/to/video.mp4')
player.play()

# Wait for video to start
time.sleep(2)

# Take snapshot with original dimensions
result = player.video_take_snapshot(0, '/path/to/snapshot.png', 0, 0)
if result == 0:
    print("Snapshot saved successfully")
else:
    print("Failed to take snapshot")

# Take snapshot with custom dimensions
result = player.video_take_snapshot(0, '/path/to/thumbnail.png', 320, 240)
if result == 0:
    print("Thumbnail saved successfully")

Video Filters and Effects

import vlc

player = vlc.MediaPlayer('/path/to/video.mp4')
player.play()

# Enable and adjust video brightness/contrast
player.video_set_adjust_int(vlc.VideoAdjustOption.Enable, 1)
player.video_set_adjust_float(vlc.VideoAdjustOption.Brightness, 1.2)  # 20% brighter
player.video_set_adjust_float(vlc.VideoAdjustOption.Contrast, 1.5)    # 50% more contrast

# Get current adjustment values
brightness = player.video_get_adjust_float(vlc.VideoAdjustOption.Brightness)
contrast = player.video_get_adjust_float(vlc.VideoAdjustOption.Contrast)
print(f"Brightness: {brightness}, Contrast: {contrast}")

# Add logo overlay
player.video_set_logo_int(vlc.VideoLogoOption.Enable, 1)
player.video_set_logo_string(vlc.VideoLogoOption.File, '/path/to/logo.png')
player.video_set_logo_int(vlc.VideoLogoOption.X, 10)
player.video_set_logo_int(vlc.VideoLogoOption.Y, 10)
player.video_set_logo_int(vlc.VideoLogoOption.Opacity, 128)  # 50% opacity

# Add text marquee
player.video_set_marquee_int(vlc.VideoMarqueeOption.Enable, 1)
player.video_set_marquee_string(vlc.VideoMarqueeOption.Text, "Sample Video")
player.video_set_marquee_int(vlc.VideoMarqueeOption.X, 100)
player.video_set_marquee_int(vlc.VideoMarqueeOption.Y, 50)
player.video_set_marquee_int(vlc.VideoMarqueeOption.Opacity, 255)  # Fully opaque

Platform-Specific Display Integration

import vlc

# Windows example
if hasattr(vlc.MediaPlayer, 'set_hwnd'):
    import tkinter as tk
    
    root = tk.Tk()
    root.geometry("640x480")
    
    player = vlc.MediaPlayer('/path/to/video.mp4')
    # Get window handle (Windows specific)
    hwnd = root.winfo_id()
    player.set_hwnd(hwnd)
    player.play()
    
    root.mainloop()

# Linux X11 example  
elif hasattr(vlc.MediaPlayer, 'set_xwindow'):
    import tkinter as tk
    
    root = tk.Tk()
    root.geometry("640x480")
    
    player = vlc.MediaPlayer('/path/to/video.mp4')
    # Get X11 window ID
    xwindow = root.winfo_id()
    player.set_xwindow(xwindow)
    player.play()
    
    root.mainloop()

Install with Tessl CLI

npx tessl i tessl/pypi-python-vlc

docs

audio-control.md

core-playback.md

data-structures.md

discovery-renderers.md

event-system.md

index.md

low-level-functions.md

media-lists.md

video-control.md

tile.json