SyncTube

SyncTube is a lightweight, self‑hosted video synchronization service that turns any browser into a shared media room. At its core, the application streams videos from a wide variety of sources—YouTube, Streamable, VK, PeerTube, raw MP4/M3U8 files, or even arbitrary iframes—and keeps every participant’s playback state in lockstep. Developers can tap into its real‑time control layer via a simple socket‑based protocol, enabling custom UI overlays, chat bots, or integration with other collaboration tools. The platform is built to run on a single node, yet it scales horizontally by clustering multiple instances behind a load balancer or orchestrator such as Docker Compose, Kubernetes, or an on‑prem VM fleet.

Architecture & Technical Stack

SyncTube is a full‑stack JavaScript/TypeScript application. The server side uses Node.js 14+ with a minimal Express‑style framework, while the client is written in React (Vite) and compiled to a single static bundle. Real‑time communication relies on WebSockets (via the ws library) for low‑latency event propagation, while chat messages and media commands are encoded as JSON objects that the server broadcasts to all connected clients. The only persistent store is an in‑memory map of active rooms; optional persistence can be added by swapping the default MemoryStore for a Redis or MongoDB adapter. The server also exposes a small REST API for administrative tasks (e.g., banning users, resetting rooms), which can be secured with JWT or basic auth.

The media layer is largely delegated to the browser’s native HTML5 <video> element. SyncTube enriches this with support for external subtitle tracks (vtt, srt, ass) and custom audio overlays, both of which are loaded via the <track> element or a secondary <audio> tag. For YouTube, it uses the IFrame Player API and optionally caches videos server‑side by invoking ytdlp-nodejs to download streams and re‑encode them with ffmpeg into a single MP4 file, reducing bandwidth for large groups.

Core Capabilities & APIs

• Leader Mode: A user can press the “Leader” button to gain global control over playback, including play/pause, seek, and playback rate. All other participants receive these commands instantly.
• Chat Commands: Built‑in slash commands (/30, /-21, /1h9m54, etc.) let users manipulate playback without leaving the chat window. Developers can extend this command parser to add custom actions.
• Hotkeys: Global shortcuts (e.g., Alt‑P for pause) are exposed via a keyboard event listener, which can be overridden in user/res.
• Link Masking: URLs like foo.com/bar${1-4}.mp4 automatically generate multiple room items, useful for playlists or batch playback.
• Custom Front‑end: The user/res directory allows overriding any static asset (CSS, JS, images), enabling theme or branding changes without touching the core codebase.
• Native Mobile Client: A companion React Native app (GitHub repo) demonstrates how to consume the same WebSocket protocol on mobile devices.

Deployment & Infrastructure

SyncTube is intentionally minimalistic to ease self‑hosting. A single Docker image (synctube) exposes port 4200 and mounts the user/ directory for persistence. The image runs as a non‑root user, making it safe to deploy in containerized environments. For larger audiences, the server can be scaled horizontally by running multiple instances behind a reverse proxy (NGINX, Traefik) with sticky sessions. Because the application stores room state in memory, a shared cache (Redis) is recommended for true horizontal scaling. The optional YouTube caching feature requires ffmpeg and the ytdlp-nodejs package, which can be installed as a Docker build step or added to an existing image.

Integration & Extensibility

• Webhooks: The server can emit events (e.g., userJoined, leaderChanged) to external services via HTTP POST, allowing integration with Slack, Discord bots, or CI pipelines.
• Plugin System: While not a formal plugin framework, the open‑source nature of the repo means developers can fork and add new media providers (e.g., Twitch, Dailymotion) by extending the player factory.
• API Hooks: The REST endpoints (/api/admin/*) can be authenticated and consumed by custom dashboards or mobile clients.
• Custom Room Logic: By modifying the Room class, developers can enforce rate limits, add moderation tools, or implement scheduled playback.

Developer Experience

SyncTube’s configuration is file‑based and lives in the user/ directory. JSON/YAML files control server settings (port, cache size), room permissions, and admin lists. The codebase follows modern JavaScript conventions, with TypeScript typings for the client and server. Documentation is concise but covers all major features; community support comes from GitHub issues, a dedicated Discord channel, and frequent pull requests. The entire application fits comfortably into a single Git repository, making for quick cloning, building, and iteration.

Use Cases

• Study Groups: Students can watch lecture recordings together while chatting in real time.
• Remote Team Demos: Product teams can showcase video prototypes synchronously across distributed offices.
• Event Streaming: Small events (webinars, watch parties) can be hosted on an internal network without relying on external services.
• **