KoalaSync

KoalaSync is a premium, lightweight Browser Extension and Relay Server for synchronized video playback across any website (YouTube, Twitch, Netflix, and custom HTML5 players).

Latest Release: GitHub Releases

Tip

New Developers & AI Agents: Please read AI_INIT.md before starting work.

Repository Structure

• extension/: Chrome Extension (Manifest V3, Vanilla JS).
• server/: Node.js + Socket.IO Relay Server (Containerized).
• website/: Marketing landing page & Invitation Bridge.
• shared/: Protocol constants and domain blacklist.
• scripts/: Development utilities for protocol synchronization.

Note

For deep technical dives, see ARCHITECTURE.md and SYNC_GUIDE.md.

Key Features

• Global Synchronization: Synchronize Play, Pause, and Seeking on any website with a <video> tag.
• Episode Auto-Sync: Perfectly sync series binges. All peers wait until everyone has loaded the next episode before starting together (v1.2.0+).
• Smart Matching: Automatically highlights and sorts tabs containing matching video titles.
• Noise Filtering: Built-in domain blacklist to hide non-video sites from selection.
• 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.

Installation (For Users)

Browser Extension

The easiest way to install KoalaSync is to download the pre-compiled version from the Releases page.

1. Download the latest koalasync-chrome.zip or koalasync-firefox.zip from the Releases page.
2. Extract the .zip file to a permanent folder on your computer.
3. For Chrome / Edge / Brave:
   • Go to chrome://extensions/
   • Enable Developer mode (top right)
   • Click Load unpacked and select the extracted folder.
4. For Firefox:
   • Go to about:debugging#/runtime/this-firefox
   • Click Load Temporary Add-on
   • Select the manifest.json file inside the extracted folder.

Development (For Contributors)

1. Relay Server (Docker)

The server runs on Node.js using Socket.IO, containerized for easy deployment.

# From the root directory
docker-compose up -d --build

The server will be available at ws://localhost:3000.

2. Building the Extension

If you are developing or modifying the codebase, you must compile the extension locally to ensure protocol constants are synchronized.

1. Install dependencies and build the artifacts:

   npm install
   node scripts/build-extension.js
   

2. The compiled, ready-to-load extensions will be available in the dist/chrome/ and dist/firefox/ directories. Load these folders into your browser using the developer steps above.

Usage

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 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 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 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).