163 lines
3.8 KiB
Markdown
163 lines
3.8 KiB
Markdown
# 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
|
|
- Automatic timecode correction
|
|
- Playback state synchronization
|
|
- Volume 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](https://www.videolan.org/vlc/)
|
|
|
|
2. Install the Python package:
|
|
```bash
|
|
cd vlchan
|
|
poetry install
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Basic Usage
|
|
|
|
```python
|
|
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
|
|
|
|
```python
|
|
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
|
|
|
|
```bash
|
|
# 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_duration() -> float`: Get video duration in seconds
|
|
- `is_playing() -> bool`: Check if playing
|
|
- `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 automatically synchronizes with the synchan server:
|
|
|
|
1. **Playback State**: Play/pause commands are synchronized
|
|
2. **Time Position**: Video seeks to match synchan timecode
|
|
3. **Threshold**: Only seeks if time difference exceeds 100ms
|
|
4. **Reconnection**: Automatically attempts to reconnect on connection loss
|
|
|
|
## 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
|
|
|
|
```bash
|
|
# Install development dependencies
|
|
poetry install --with dev
|
|
|
|
# Run linting
|
|
poetry run ruff check .
|
|
|
|
# Run type checking
|
|
poetry run mypy vlchan/
|
|
```
|