HandBrake Web

HandBrake Web is a self‑hosted, browser‑based orchestration layer that exposes the HandBrakeCLI encoder as a distributed service. At its core, it decouples coordination from encoding, allowing a lightweight Node.js server to manage job queues while one or more Go‑based workers perform the CPU‑intensive transcoding. The architecture is intentionally modular: any number of workers can be added or removed behind a simple TCP‑based RPC channel, making the system horizontally scalable and fault tolerant.

Technical Stack & Architecture

• Server – Built with Node.js (v20+) and Express, the server hosts a RESTful API and serves a React/Vite SPA from client/public. It uses SQLite for persistence (job metadata, user settings) and Socket.io for real‑time updates to the dashboard. Workers register over a lightweight JSON‑over‑TCP protocol; the server maintains a Redis‑style in‑memory map of worker health and job assignments.
• Worker – Implemented in Go, each worker is a self‑contained binary that spawns HandBrakeCLI as a child process. It parses JSON job descriptors, translates them into CLI flags, and streams progress back to the server via the same TCP channel. The Go runtime guarantees low memory overhead, making workers suitable for Raspberry Pi or other edge devices.
• Database – SQLite is used on the server side for durability of job queues and user preferences. For larger deployments, a PostgreSQL instance can replace SQLite by toggling the DB_TYPE environment variable.
• Containerization – Docker images are published to GitHub Packages. The docker-compose.yml example shows a single‑node deployment, but the architecture supports multi‑host setups by exposing the worker service on an external port and using a load balancer.

Core Capabilities & APIs

• Job Management – Create, pause, cancel, and reschedule jobs via a REST endpoint (/api/jobs). Each job references a HandBrake preset JSON file, which can be uploaded or edited through the web UI.
• Preset Handling – The server hosts a preset repository; workers pull the relevant JSON file from a shared volume or HTTP endpoint. Presets can be templated with environment variables for dynamic bitrate or resolution.
• Webhooks – On job completion, the server can POST to arbitrary URLs. This is ideal for CI/CD pipelines or media libraries that trigger further processing (e.g., Plex library refresh).
• Health & Metrics – Workers expose a /metrics endpoint compatible with Prometheus. The server aggregates these metrics and forwards them to the UI for real‑time monitoring.

Deployment & Infrastructure

• Self‑Hosting – A single server instance runs on a Raspberry Pi 4 (2 GB RAM) with no noticeable load, while workers can be placed on more powerful GPUs or cloud VMs. The lightweight nature of the server allows it to sit behind a reverse proxy (NGINX/Traefik) with TLS termination.
• Scalability – Adding workers is as simple as spinning up another Docker container and pointing it to the same server address. The server automatically detects new workers, balances load, and reassigns orphaned jobs if a worker dies.
• High Availability – By running multiple server replicas behind a load balancer and using a shared database (PostgreSQL), the system can tolerate server failures. Workers are stateless, so they can be restarted without losing job state.

Integration & Extensibility

• Plugin System – Developers can extend the worker by packaging additional CLI wrappers or custom pre‑processing scripts that run before HandBrakeCLI. The plugin registry is exposed via a /plugins endpoint.
• API SDKs – A minimal TypeScript client is available in the client/src/api folder, providing typed wrappers around all server endpoints. This makes it trivial to build custom dashboards or automate job submission from external services.
• Webhook Customization – The UI allows configuring multiple webhook URLs per job, with payload templates that include job metadata (source path, destination, status). This is useful for integrating with media servers, notification services, or analytics platforms.

Developer Experience

• Configuration – All settings are exposed through environment variables (SERVER_PORT, WORKER_HOST, DB_URL, etc.). The UI provides a JSON editor for preset files, reducing the need to touch configuration files directly.
• Documentation – The README contains a comprehensive API reference, deployment guide, and troubleshooting section. Inline comments in the source code are plentiful, making it easy to understand data flow.
• Community – The project is actively maintained on GitHub with a clear issue tracker and milestone system. Contributions are welcome, and the open‑source license (MIT) allows commercial use without licensing fees.

Use Cases

1. Home Media Automation – A homeowner runs a Pi‑based server that watches an inbox folder on SMB and automatically encodes new media using user‑defined presets, then pushes the output to a Plex library.
2. Edge Video Processing – A security company deploys workers on local cameras to transcode footage in real time before uploading to a central cloud archive.
3. CI/CD for Video Assets – A game studio uses HandBrake Web as part of its build pipeline to generate multiple bitrate assets for distribution, triggering webhooks to update the asset store.

Advantages Over Alternatives