mirror of
https://github.com/Shik3i/KoalaSync.git
synced 2026-08-07 18:03:15 +00:00
MacBook
64 lines
3.0 KiB
Markdown
64 lines
3.0 KiB
Markdown
# KoalaSync
|
|
|
|
KoalaSync is a Chrome Extension and Relay Server for synchronized video playback (YouTube, Twitch, HTML5).
|
|
|
|
> [!TIP]
|
|
> **New Developers & AI Agents**: Please read [AI_INIT.md](AI_INIT.md) before starting work.
|
|
|
|
## Repository Structure
|
|
- `extension/`: Chrome Extension (Manifest V3).
|
|
- `server/`: Node.js + Socket.IO Relay Server.
|
|
- `website/`: Static marketing landing page & tutorials.
|
|
- `shared/`: Shared protocol constants.
|
|
|
|
## Setup Instructions
|
|
|
|
### 1. Relay Server (Docker)
|
|
The server runs on Node.js using Socket.IO but is restricted to WebSocket transport for compatibility with native clients.
|
|
|
|
```bash
|
|
# From the root directory
|
|
docker-compose up -d --build
|
|
```
|
|
The server will be available at `ws://localhost:3000`.
|
|
|
|
### 2. Chrome Extension
|
|
1. Open Chrome and go to `chrome://extensions/`.
|
|
2. Enable **Developer mode** (top right).
|
|
3. Click **Load unpacked**.
|
|
4. Select the `extension/` folder.
|
|
|
|
## Usage
|
|
1. Open the extension popup.
|
|
2. Enter the Server URL (default: `ws://localhost:3000`).
|
|
3. Click **Join / Create Room**.
|
|
4. In the **Sync** tab, select the tab containing the video you want to sync.
|
|
5. Share the **Invite Link** (RoomID#Password) with your friends.
|
|
6. When they join, your play/pause/seek actions will be synchronized.
|
|
7. Use **Force Sync** to align everyone to your current timestamp.
|
|
|
|
## Technical Details
|
|
- **Manifest V3**: Uses a Service Worker for background tasks.
|
|
- **Native WebSockets**: The extension uses the native `WebSocket` API.
|
|
- > [!IMPORTANT]
|
|
- > **Socket.IO Compatibility**: The server must use **Socket.IO v4**. The extension implements a subset of the Engine.IO/Socket.IO wire protocol.
|
|
- **Keep-Alive**: A `chrome.alarms` mechanism keeps the Service Worker active.
|
|
- **Two-Phase Force Sync**: Uses `pollSeekReady` to ensure all peers are synchronized before resuming.
|
|
|
|
## Security & Privacy
|
|
|
|
> [!IMPORTANT]
|
|
> **Privacy by Design**: KoalaSync is built with extreme data parsimony in mind.
|
|
> - **No Databases**: The server stores absolutely nothing on disk. All room states and peer mappings exist only in RAM and are destroyed as soon as a room is empty or inactive.
|
|
> - **No Tracking**: There is zero telemetry, analytics, or user tracking in both the extension and the server.
|
|
> - **Minimal Logging**: The server logs only technical events (connections, errors, rate-limiting) with no personally identifiable information (PII).
|
|
> - **Extension Permissions**: The `<all_urls>` permission is required solely to detect and synchronize HTML5 video elements on any website you visit. No browsing history is ever transmitted or stored.
|
|
|
|
- > [!WARNING]
|
|
> **Invite Links**: Passwords in invite links (e.g., `RoomID#Password`) are shared in plaintext. This is a trade-off for convenience. For higher security, share the password via a secure channel.
|
|
|
|
## Troubleshooting
|
|
- **Logs**: Check the **Dev** tab in the extension popup for detailed connection logs.
|
|
- **Handshake**: Look for `Socket.IO Handshake: 0{...}` in the logs to verify successful connection.
|
|
- **Permissions**: Ensure you have granted the extension permission to access the video site's tab.
|