114 lines
3.8 KiB
Markdown
114 lines
3.8 KiB
Markdown
# 🎬 VideoSync
|
|
|
|
Watch videos together in real-time. Each user loads a local video file — only sync commands and chat messages travel over the network.
|
|
|
|
## Architecture
|
|
|
|
This project consists of three main components:
|
|
|
|
- **Server**: A fast, lightweight WebSocket server built with Bun.
|
|
- **Web Frontend**: A vanilla HTML/CSS/JS single-page application for joining rooms and syncing video playback.
|
|
- **Desktop App**: A Python/PyQt6 application with embedded VLC (`python-vlc`). **Note:** The desktop client was specifically created because web browsers (like Chrome) have issues handling and playing MKV files natively.
|
|
|
|
## Features
|
|
|
|
- **Room system** — create a room, share the 6-character code with friends.
|
|
- **File verification** — joiners must have the exact same file (matched by name + size).
|
|
- **Playback sync** — play, pause, seek, and speed changes broadcast to all clients instantly.
|
|
- **Drift correction** — automatic re-sync every 5 seconds to keep everyone aligned.
|
|
- **Live chat** — YouTube-style chat sidebar with colored usernames.
|
|
- **Local playback** — multi-gigabyte files work fine since nothing is uploaded.
|
|
- **Broad format support** — the desktop app leverages VLC to play MKV and other formats that browsers struggle with.
|
|
|
|
## Quick Start
|
|
|
|
### 1. Start the Server
|
|
|
|
```bash
|
|
# Install Bun (if not already installed)
|
|
curl -fsSL https://bun.sh/install | bash
|
|
|
|
# Start the server
|
|
bun run server.ts
|
|
```
|
|
|
|
### 2. Connect via Web Frontend
|
|
|
|
Once the server is running, open **http://localhost:3000** in your browser to access the web app.
|
|
|
|
1. Enter your name and select a video file → **Create Room**
|
|
2. Share the room code with a friend
|
|
3. Friend enters the code → **Join Room** → selects their copy of the same file
|
|
4. Play/pause/seek in either browser — the other stays in sync
|
|
|
|
### 3. Connect via Desktop App (Recommended for MKV files)
|
|
|
|
If you are playing MKV files or formats not supported by your browser, use the desktop client:
|
|
|
|
```bash
|
|
cd desktop-client
|
|
|
|
# Install dependencies using uv
|
|
uv sync
|
|
|
|
# Run the app
|
|
uv run main.py
|
|
```
|
|
|
|
You can also build a standalone executable for the desktop app using the provided `build.ps1` script (requires PyInstaller).
|
|
|
|
### Quick Run on Linux
|
|
|
|
If you just want to run the desktop client without cloning the repo manually, use the launcher script. Prerequisites: `git` and [`uv`](https://docs.astral.sh/uv/).
|
|
|
|
```bash
|
|
# Download the script
|
|
curl -fsSL https://gitea.peterstockings.com/peterstockings/video-sync/raw/branch/master/desktop-client/run-videosync.sh -o run-videosync.sh
|
|
chmod +x run-videosync.sh
|
|
|
|
# Run (clones on first launch, pulls updates on subsequent runs)
|
|
./run-videosync.sh
|
|
```
|
|
|
|
## Deployment
|
|
|
|
```bash
|
|
# Run on a custom port
|
|
PORT=8080 bun run server.ts
|
|
```
|
|
|
|
For production, put behind **nginx** with WebSocket proxy support:
|
|
|
|
```nginx
|
|
location / {
|
|
proxy_pass http://127.0.0.1:8080;
|
|
proxy_http_version 1.1;
|
|
proxy_set_header Upgrade $http_upgrade;
|
|
proxy_set_header Connection "upgrade";
|
|
proxy_set_header Host $host;
|
|
}
|
|
```
|
|
|
|
## Tech Stack
|
|
|
|
| Component | Technology |
|
|
|-----------|-----------|
|
|
| **Server** | Bun (native HTTP + WebSocket) |
|
|
| **Web Frontend** | Vanilla HTML / CSS / JS |
|
|
| **Desktop App**| Python, PyQt6, python-vlc, websockets |
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
├── server.ts # Bun WebSocket server
|
|
├── package.json
|
|
├── public/
|
|
│ ├── index.html # Single-page web app
|
|
│ ├── style.css # Dark theme
|
|
│ └── app.js # Client sync + chat logic
|
|
└── desktop-client/
|
|
├── main.py # Desktop app entry point
|
|
├── pyproject.toml # Python dependencies (uv)
|
|
└── vlc_player.py # Embedded VLC player
|
|
```
|