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 v3.0.1 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, extract it, and load the extracted browser package using your browser's developer or manual extension installation process.)

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

Extension ZIPs attached to GitHub Releases and Docker images published to GitHub Container Registry receive signed artifact attestations. These attestations connect an artifact's exact digest to this repository, its release tag and commit, and the public GitHub Actions workflow that built it.

Each new GitHub Release also includes SHA256SUMS for a quick checksum comparison:

sha256sum --check SHA256SUMS

Checksums detect a changed or incomplete download. Signed provenance additionally verifies where the artifact came from and which workflow built it. Neither check guarantees that the software contains no bugs or vulnerabilities. These attestations cover the GitHub release ZIPs and GHCR images; they do not by themselves prove that browser-store packages are byte-for-byte identical.

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