mirror of
https://github.com/Shik3i/KoalaSync.git
synced 2026-07-26 20:18:14 +00:00
MacBook
f7829bbebb
Server Security (S-1 through S-8): - S-1: Type-check and clamp peerId, protocolVersion, password - S-2: Validate numeric/boolean/enum fields in relay peerData - S-3: Construct explicit relay payload (stop spreading raw data) - S-4: Type-check targetId and actionTimestamp in EVENT_ACK - S-5: Restrict room IDs to [a-zA-Z0-9-] only - S-7: Add eventCounts periodic cleanup alongside connectionCounts - S-8: Guard version parsing against NaN bypass Documentation (P-1, R-1 through R-6): - P-1: Fix PRIVACY.md typo, document all in-memory data maps - R-1/R-5: Fix stale sync-constants.bat references in shared/ - R-2: Fix stale lastTargetState ref in ARCHITECTURE.md - R-3: Extension README title reflects cross-browser support - R-6: Document content injection markers in scripts/README.md
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. Built with a focus on Data Sovereignty and Extreme Performance.
🌟 Why KoalaSync?
- 🛡️ Security-First: Volatile RAM-based relay with built-in brute-force protection and zero-persistence architecture.
- 📡 Direct Logic: Custom wire protocol implementation for frame-perfect 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.
- Zero-Latency Relay: Custom wire protocol implementation for maximum performance.
- Seamless Invitations: Smart links that automatically configure server and room credentials for your friends.
📂 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).
🚀 Quick Start
For Users (Installation)
The easiest way to install KoalaSync is to download the pre-compiled version from the Releases page.
- Download the latest
koalasync-chrome.ziporkoalasync-firefox.zip. - Extract the file and load it as an "Unpacked Extension" in your browser's Developer Mode.
For Developers (Building)
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.
📖 Documentation & Links
- PRIVACY.md: Data Handling and Privacy Policy.
- CONTRIBUTING.md: How to help make KoalaSync better.
- ARCHITECTURE.md: Deep-dive into the two-phase sync and heartbeat logic.
- SECURITY.md: Disclosure policy and security practices.