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.

🌟 Why KoalaSync?

• 🛡️ Security-First: Volatile RAM-based relay with built-in brute-force protection and zero-persistence architecture.
• 📡 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.
• 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.

---

🚀 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! 🍿

---

🛠️ 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
node scripts/build-extension.js

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

For Self-Hosting (Docker)

Deploy your own private relay server using our official image:

# Pull the latest image
docker pull ghcr.io/shik3i/koalasync:latest

# Or use our example compose file
cp docker-compose.example.yml docker-compose.yml
docker-compose up -d

The server will be available at ws://localhost:3000. See docker-compose.example.yml for advanced configuration.

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.

---

📖 Documentation & Links

• PRIVACY.md: Data Handling and Privacy Policy.
• CONTRIBUTING.md: How to help make KoalaSync better.
• 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.
• SECURITY.md: Disclosure policy and security practices.
• Caddyfile.example: Production Caddy configuration for website and relay.

---

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