Update readme

README.md

@@ -2,17 +2,28 @@
 
 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
+- **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)
+- **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
+- **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
+- **Drift correction** — automatic re-sync every 5 seconds to keep everyone aligned.
-- **Live chat** — YouTube-style chat sidebar with colored usernames
+- **Live chat** — YouTube-style chat sidebar with colored usernames.
-- **Local playback** — multi-gigabyte files work fine since nothing is uploaded
+- **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
@@ -21,15 +32,31 @@ curl -fsSL https://bun.sh/install | bash
 bun run server.ts
 ```
 
-Open **http://localhost:3000** in your browser.
+### 2. Connect via Web Frontend
 
-## How It Works
+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).
+
 ## Deployment
 
 ```bash
@@ -53,17 +80,21 @@ location / {
 
 | Component | Technology |
 |-----------|-----------|
-| Server | Bun (native HTTP + WebSocket) |
+| **Server** | Bun (native HTTP + WebSocket) |
-| Frontend | Vanilla HTML / CSS / JS |
+| **Web Frontend** | Vanilla HTML / CSS / JS |
-| Dependencies | None |
+| **Desktop App**| Python, PyQt6, python-vlc, websockets |
 
 ## Project Structure
 
 ```
 ├── server.ts          # Bun WebSocket server
 ├── package.json
-└── public/
+├── public/
-    ├── index.html     # Single-page app
+│   ├── index.html     # Single-page web app
-    ├── style.css      # Dark theme
+│   ├── style.css      # Dark theme
-    └── app.js         # Client sync + chat logic
+│   └── 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
 ```