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 before starting work.

Repository Structure

• extension/: Chrome Extension (Manifest V3).
• server/: Node.js + Socket.IO Relay Server.
• 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.

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