Self-Hosted HandBrake Web: Queue Transcodes Across Headless Workers

You ripped a box set to your NAS at 60 GB per season, your laptop fan sounds like a jet, and the spare mini PC in the closet has HandBrake installed but no monitor. You could RDP in and click through presets, or you could queue everything once and let whatever CPU or GPU you already own chew through the list while you sleep.

HandBrake Web (TheNickOfTime/handbrake-web, ~800 GitHub stars, AGPL-3.0, TypeScript/React) is a self-hosted control plane around HandBrakeCLI. It is not an official HandBrake project; it wraps the CLI you already trust. A lightweight server hosts the web UI and coordinates work. One or more workers on other machines run the actual encodes. Everyone pulls from the same job queue, so a Raspberry Pi-class box can sit in front while a desktop with NVENC or an Intel box with QSV does the heavy lifting.

What you get today

• Browser queue — add jobs, reorder them, and watch workers pick up the next file without sitting at each host.
• Bulk jobs — batch-encode everything in a folder instead of hand-building twenty identical queues.
• Presets from desktop HandBrake — export JSON presets from the GUI app, upload them in the Presets section, and reuse them on headless workers.
• Directory watchers — drop files into a watched folder and let the system spawn jobs against your rules.
• Distributed workers — register multiple nodes; the server hands out jobs so encode throughput scales with hardware you already own.
• Hardware encode paths — wiki docs cover Intel QSV and NVIDIA NVENC inside workers; AMD VCN is listed as planned.
• Bonus CLI image — upstream also publishes ghcr.io/thenickoftime/handbrake-cli if you just want containerized HandBrakeCLI in a shell.

Upstream is honest that the app is still evolving. Built-in login is on the roadmap but not shipped yet, and some polish items (web upload, in-browser preset editor) are still open. Treat the UI like ops tooling behind your firewall until authentication lands.

Why self-host?

Cloud transcoding bills by minute and ships your raw footage through someone else's pipeline. HandBrake Web keeps paths on your NAS or ZFS pool, uses your electricity and GPUs, and avoids upload bandwidth caps that hurt Canadian home connections on large libraries. AGPL-3.0 means internal homelab use is straightforward; if you expose HandBrake Web as a multi-tenant service to customers, understand copyleft and network interaction rules before you productize it.

The server role is cheap: coordinators can run on a small VPS or an old SBC. Workers need cores or GPU encode support. Run one worker container per physical machine, mount the same /video path everywhere, and match UID/GID so workers can read source files and write outputs.

Quick start

services:
  handbrake-server:
    image: ghcr.io/thenickoftime/handbrake-web-server:latest
    ports:
      - 9999:9999
    volumes:
      - ./data:/data
      - /srv/media:/video

  handbrake-worker:
    image: ghcr.io/thenickoftime/handbrake-web-worker:latest
    environment:
      WORKER_ID: worker-1
      SERVER_URL: handbrake-server
      SERVER_PORT: 9999
    volumes:
      - /srv/media:/video

The Setup Guide wiki is the authoritative walkthrough. Set user: 1000:1000 (or your media owner) instead of root. Put the server behind HTTPS and a reverse proxy with auth you trust, because the app itself may still be wide open. For GPU encode, follow the Hardware Acceleration wiki page so devices pass through to workers correctly.

Who it is for

Good fit: Plex or Jellyfin admins standardizing on H.265; families with one beefy tower and a quiet NAS; creators who already obsess over HandBrake presets and want them centralized; anyone who would rather queue rips from a tablet than VNC into a transcode box.

Skip it: if you need a fully polished SaaS with accounts and billing; if your library is tiny and manual HandBrake once a month is fine; if you cannot align network mounts so every worker sees identical paths.

Hosting in Canada

You rarely want to upload terabytes to a cloud encoder, but a Canadian VPS can still host the coordinator while workers stay on hardware at home or in your office, with SSH or VPN between sites. Keep the media on Canadian storage you control; use the server only for queue state and the UI. Size worker machines for sustained encode load (CPU watts or GPU VRAM), not the lightweight server container.

Bottom line

HandBrake Web is homelab pragmatism: familiar encoding engine, modern queue UI, and a path to spread work across machines you already paid for. Read the AGPL terms, lock down the web port until proper sessions arrive, and let the queue run overnight.

Talk with Swift Host if you want help splitting roles across a Canadian VPS and on-prem workers, TLS, and backup of queue metadata. We are in St. Albert and actually answer the phone.