KoalaSync

KoalaSync is a lightweight Browser Extension and Relay Server for synchronized video playback on almost any website with a video element—YouTube, Twitch, Netflix, Emby, Jellyfin, and beyond. Built with a focus on Data Sovereignty and Performance.

New v2.5.4 Release! — See what's changed

🌟 Why KoalaSync?

• 🛡️ Security-First: Volatile RAM-based relay with built-in brute-force protection and zero-persistence architecture. We keep no logs of your sessions or synchronizations. We don't track you. We only track our server (relying on the aggregated, anonymous, non-personal metrics provided under /health).
• 📡 Direct Logic: Manual Socket.IO wire implementation for reliable synchronization.
• 🛠️ Clean Build: Dependency-free extension runtime with no library overhead.
• 🌐 Universal: Works on any website with a <video> tag.

---

✨ 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.
• Host Control & Co-Hosts: Room hosts can lock playback control to trusted controllers while guests keep watching in sync.
• Smart Matching: Automatically highlights tabs containing matching video titles.
• Dual Heartbeat Architecture: Robust session tracking that prevents ghost rooms and stale connections.
• Efficient Relay: Minimal overhead WebSocket message forwarding.
• Seamless Invitations: Smart links that automatically configure server and room credentials for your friends.
• Smart Audio Compressor: Tired of constantly riding the volume? Automatically balance out whispering dialogue and deafening explosions with simple presets, or fully customize the audio to your liking.

---

🚀 Quick Start

For Users (Installation & Usage)

The easiest and safest way to install KoalaSync is directly through the official browser stores:

(For manual offline installation: Download the latest .zip from the Releases page and load it as an "Unpacked Extension" in Developer Mode).

How to use:

1. Create a Room: Click the Koala icon in your browser and hit + Create New Room.
2. Invite Friends: Share the auto-copied invite link. Once they click it, they automatically join.
3. Pick a Video: Navigate to the Sync Tab, select the tab playing your video, and grab some popcorn! 🍿

---

🌐 Localization & Translations

Both the official KoalaSync website and the browser extension feature dynamic localization:

• Available Languages: Support is included for 15 languages: English (en), German (de), French (fr), Spanish (es), Portuguese (Brazil) (pt-BR), Russian (ru), Italian (it), Polish (pl), Turkish (tr), Dutch (nl), Japanese (ja), Korean (ko), Chinese (Simplified) (zh), Ukrainian (uk), and European Portuguese (pt).
• Real-Time Extension Localization: Inside the extension Settings panel, users can swap languages instantly. The entire interface, notifications, Empty States, and onboarding guides re-translate dynamically in real-time.
• Contributing: We welcome community translations for both the website and the extension! Please refer directly to the TRANSLATION.md guide for step-by-step instructions on how to audit, refine, or add new languages.

---

🛠️ For Developers & Self-Hosters

📂 Repository Structure

• extension/: Browser Extension (Chrome & Firefox).
• server/: Node.js + Socket.IO Relay Server (Containerized).
• website/: Marketing landing page & Invitation Bridge.
• shared/: Single Source of Truth for protocol constants.
• scripts/: Automated build and synchronization utilities.
• docs/: Technical deep-dives (Architecture, Sync Guide).

Building from Source

To build the extension from source and synchronize protocol constants:

npm install
npm run build:extension

The compiled artifacts will be available in the dist/ directory.

For Self-Hosting (Docker)

For local development or a simple private relay, use the root Compose file:

cp server/.env.example server/.env
# Edit server/.env and set SERVER_SALT to a unique random value:
# openssl rand -base64 32
docker compose up -d --build

The local relay will be available at ws://localhost:3000.

For production, use the official image and one of the ready-to-edit examples:

• Docker network compose: for a Caddy or reverse-proxy network. This file does not publish localhost:3000; Caddy routes traffic to the container.
• Static IP compose: for a pre-existing Docker network with a fixed container IP.

In every real deployment, set a unique SERVER_SALT. Without it the relay still starts, but it warns that room-password hashes are using the public fallback salt from the repository.

To connect your extension to a self-hosted server, open the popup → Room tab → select Custom Server → enter your server's WebSocket URL (e.g., ws://localhost:3000).

⚠️ Note: ws:// only works for localhost. If you deploy to a real domain, you must use wss:// (e.g., wss://sync.yourdomain.com). This requires a TLS-terminating reverse proxy (e.g., Caddy, Nginx, or Traefik) in front of the relay server. See Caddyfile.example for a production-ready template.

To verify your relay is reachable from outside, visit https://your-domain.com in a browser — it should return {"status":"online","service":"KoalaSync Relay"}.

Supply Chain Security (v2.2.2+)

All official release artifacts (Docker images and extension binaries) are published with signed artifact attestations to prove they were built from this repository's source code.

Verify a Docker image:

gh attestation verify oci://ghcr.io/shik3i/koalasync:latest \
  -R Shik3i/KoalaSync

Verify an extension binary:

gh attestation verify dist/koalasync-chrome.zip \
  -R Shik3i/KoalaSync

---

📖 Documentation & Links

• CHANGELOG.md: Full version history for the extension and relay server.
• TESTED_SERVICES.md: Detailed compatibility matrix of tested streaming platforms and known limitations.
• TRANSLATION.md: Translation and localization guide for contributors.
• PRIVACY.md: Data Handling and Privacy Policy.
• CONTRIBUTING.md: How to help make KoalaSync better.
• CODE_OF_CONDUCT.md: Our community standards and expectations.
• HOW_IT_WORKS.md: Step-by-step walkthrough of the complete user flow.
• ARCHITECTURE.md: Deep-dive into the two-phase sync and heartbeat logic.
• PROTOCOL.md: WebSocket protocol specification and event reference.
• ROADMAP.md: Planned features, backlog, and rejected ideas.
• SECURITY.md: Disclosure policy and security practices.
• AI_INIT.md: Maintainer and agent onboarding notes for safe code changes.
• Caddyfile.example: Production Caddy configuration for website and relay.

---

_{Built with ❤️ by Shik3i. KoalaSync is Open Source under the MIT License.}