gsadmin/KoalaSync
1
0
Fork 0
mirror of https://github.com/Shik3i/KoalaSync.git synced 2026-08-27 19:17:11 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: complete repository documentation update for v1.0.0-RC5 features

Browse Source
This commit is contained in:
Timo
2026-04-22 11:54:54 +02:00
parent 830f8c44b1
commit 1d2237aab6
5 changed files with 117 additions and 148 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+25 -29
View File
@@ -1,20 +1,28 @@
# KoalaSync
KoalaSync is a Chrome Extension and Relay Server for synchronized video playback (YouTube, Twitch, HTML5).
KoalaSync is a premium, lightweight Chrome Extension and Relay Server for synchronized video playback across any website (YouTube, Twitch, Netflix, and custom HTML5 players).
> [!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.
- `extension/`: Chrome Extension (Manifest V3, Vanilla JS).
- `server/`: Node.js + Socket.IO Relay Server (Containerized).
- `website/`: Static marketing landing page & tutorials.
- `shared/`: Shared protocol constants.
## Key Features
- **Global Synchronization**: Synchronize Play, Pause, and Seeking on any website with a `<video>` tag.
- **Smart Identity**: Customizable usernames combined with unique hexadecimal peer IDs.
- **Dual Heartbeat Architecture**: Robust session tracking that prevents ghost rooms and stale connections.
- **Zero-Latency Relay**: Custom Socket.IO wire protocol implementation for maximum performance.
- **Integrated Diagnostics**: A dedicated "Dev" tab for real-time video state debugging.
- **Seamless Invitations**: Smart invitation links that automatically configure the server and room credentials for your friends.
## 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.
The server runs on Node.js using Socket.IO, containerized for easy deployment.
```bash
# From the root directory
@@ -29,35 +37,23 @@ The server will be available at `ws://localhost:3000`.
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.
1. Open the extension and go to the **Settings** tab to set your **Username**.
2. Go to the **Room** tab, enter your Server URL (default: `ws://localhost:3000`), and click **Join / Create Room**.
3. In the **Sync** tab, select the tab containing the video you want to sync.
4. Share the **Invite Link** from the Room tab. When your friends click it, they will automatically join your room and server.
5. Use **Force Sync** to perfectly 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.
- **Manifest V3**: Uses a persistent Service Worker with Alarm-based keep-alive.
- **Manual Socket.IO Protocol**: The extension implements the Socket.IO v4 wire protocol natively for extreme performance and zero dependencies.
- **Dead Peer Pruning**: The server automatically prunes peers after 5 minutes of total inactivity (detected via dual heartbeats).
- **Two-Phase Sync**: Ensures all peers are buffered (`readyState >= 3`) before resuming playback.
## 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.
> **Privacy First**: KoalaSync stores no data on disk. All room states exist only in RAM and are purged immediately when empty. There is zero telemetry, tracking, or analytics.
## 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.
- **Logs**: Check the **Dev** tab in the extension popup for live connection logs and video state diagnostics.
- **Handshake**: Verify you see `Joined Namespace /` in the logs.
- **Permissions**: Ensure the target site hasn't blocked script injection (rare for most video sites).