HandBrake Web UI

A web interface for HandBrake CLI — upload a video, pick a preset, encode it, and download the result. Built with Bun and plain HTML/CSS/JS. No frameworks, no build step.

Prerequisites

• Bun — JavaScript runtime

  curl -fsSL https://bun.sh/install | bash

• HandBrake CLI — video encoder

  • macOS: brew install handbrake or brew install --cask handbrake (the CLI is included)
  • Ubuntu/Debian: sudo apt install handbrake-cli
  • Fedora: sudo dnf install HandBrake-cli
  • Windows: download from handbrake.fr and add to PATH

  Verify it's installed:

  HandBrakeCLI --version

Setup

git clone https://github.com/sonigeez/handbrake-webui.git
cd handbrake-webui
bun install

Usage

Development

bun start

Compiled binary (recommended)

bun run build
./handbrake-web

This compiles everything into a single standalone binary — faster startup, no Bun runtime needed on the target machine. Only HandBrakeCLI must be in PATH.

Open http://localhost:9550 in your browser.

1. Drop a video file (or click to browse)
2. Pick a preset from the dropdown
3. Click Encode
4. Watch the progress bar
5. Click Download when done

Both the uploaded original and encoded output are automatically deleted after download.

API

Method	Path	Description
GET	/	Web UI
GET	/api/presets	List available HandBrake presets
POST	/api/upload	Upload a video and start encoding (multipart form: file + preset)
GET	/api/status/:id	Poll encoding progress
GET	/api/download/:id	Download encoded file (auto-cleans up after)

How it works

• Single file server (index.ts) using Bun.serve
• Parses presets from HandBrakeCLI --preset-list at startup
• Spawns HandBrakeCLI as a child process per job
• Parses stdout in real-time for encoding progress and ETA
• Supports multiple concurrent encodes
• Temporary files stored in uploads/ and outputs/ (gitignored)