VLChan

A Python video player using VLC SDK with synchan server timecode synchronization.

Features

• VLC-based video playback with full media support
• Real-time synchronization with synchan server
• Reactive programming with RxPY
• Advanced synchronization with latency compensation
• Playback rate adjustment for smooth sync
• Automatic timecode correction with smart seeking
• Playback state synchronization
• Volume, playback rate, and fullscreen controls

Installation

1. Install VLC media player on your system:

   • Ubuntu/Debian: sudo apt install vlc
   • macOS: brew install vlc
   • Windows: Download from videolan.org

2. Install the Python package:

   cd vlchan
   poetry install
   

Usage

Basic Usage

from vlchan import VLChanPlayer

# Create player with video file
player = VLChanPlayer(
    synchan_url="http://localhost:3000",
    video_path="/path/to/video.mp4"
)

# Start synchronization
player.start_sync()

# Play video
player.play()

# Clean up when done
player.cleanup()

Advanced Usage

from vlchan import VLChanPlayer

def on_state_change(state):
    print(f"Synchan state: playing={state.playing}, time={state.currentTime:.2f}s")

# Create player
player = VLChanPlayer("http://localhost:3000", "video.mp4")

# Set up state change callback
player.on_state_change = on_state_change

# Start synchronization
player.start_sync()

# Control playback
player.play()
player.pause()
player.seek(120.5)  # Seek to 2 minutes 0.5 seconds

# Adjust settings
player.set_volume(80)
player.set_fullscreen(True)

# Get current state
print(f"Position: {player.get_position():.2f}s")
print(f"Duration: {player.get_duration():.2f}s")
print(f"Playing: {player.is_playing()}")

Command Line Usage

# Play video with synchan sync
poetry run python -m vlchan.player video.mp4

# Use custom synchan server
poetry run python -m vlchan.player video.mp4 http://192.168.1.100:3000

API Reference

VLChanPlayer

Constructor

• VLChanPlayer(synchan_url: str, video_path: Optional[str])
  • synchan_url: URL of the synchan server (default: "http://localhost:3000")
  • video_path: Path to video file to load

Methods

• load_video(video_path: str): Load a video file
• start_sync(): Start synchronization with synchan server
• stop_sync(): Stop synchronization
• play(): Start playback
• pause(): Pause playback
• stop(): Stop playback
• seek(time_seconds: float): Seek to specific time
• set_volume(volume: int): Set volume (0-100)
• get_volume() -> int: Get current volume
• set_fullscreen(fullscreen: bool): Toggle fullscreen
• get_position() -> float: Get current position in seconds
• get_compensated_position(latency: float) -> float: Get latency-compensated position
• get_duration() -> float: Get video duration in seconds
• is_playing() -> bool: Check if playing
• get_rate() -> float: Get current playback rate
• set_rate(rate: float): Set playback rate (1.0 = normal speed)
• cleanup(): Clean up resources

Properties

• on_state_change: Callback for synchan state changes

SynchanState

Data class containing synchronization state:

• playing: bool: Whether video should be playing
• currentTime: float: Current time position in seconds
• duration: float: Total duration in seconds
• loop: bool: Whether video should loop
• latency: float: Network latency in seconds

Synchronization

The player uses advanced synchronization logic similar to the synchan VideoPlayer component:

1. Latency Compensation: Server time is adjusted by network latency
2. Smart Seeking: Large time differences (>1s) trigger immediate seeking
3. Playback Rate Adjustment: Small differences are corrected by adjusting playback speed
4. Rate Formula: rate = 1 + min(max(diff * 0.5, -0.05), 0.05)
5. Playback State: Play/pause commands are synchronized
6. Reconnection: Automatically attempts to reconnect on connection loss

Synchronization Algorithm

# Apply latency compensation
compensated_time = server_time + latency / 1000

# Calculate difference
diff = compensated_time - local_time

# Large difference: seek immediately
if diff > 1.0:
    player.seek(compensated_time)

# Small difference: adjust playback rate
rate = 1 + min(max(diff * 0.5, -0.05), 0.05)
player.set_rate(rate)

Requirements

• Python 3.11+
• VLC media player
• Synchan server running

Dependencies

• python-vlc: VLC Python bindings
• reactivex: Reactive programming
• python-socketio: WebSocket client for synchan
• requests: HTTP client for synchan API

Development

# Install development dependencies
poetry install --with dev

# Run linting
poetry run ruff check .

# Run type checking
poetry run mypy vlchan/