feat: init project

2025-10-09 16:31:57 +11:00
commit ca0a880c80
13 changed files with 1262 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,162 @@
+# 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/
+```