# 🎬 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
```