HandBrake SVT-AV1-PSY Stack

A self-hosted HandBrake Web Server and Worker setup that automatically builds HandBrakeCLI with the SVT-AV1-PSY patch by Nj0be. This stack is ideal for running automated, high-quality AV1 encodes through a browser interface or API.

Features

• HandBrake Web UI + Worker architecture
  • Uses thenickoftime/handbrake-web-server and a patched worker
• SVT-AV1-PSY Encoder Patch
  • Automatically applies the SVT-AV1-PSY tuning improvements to the HandBrake build
• Portable and configurable
  • Easily deploy via Portainer, Docker Compose, or CLI using .env variables
• Persistent media mount
  • Host and containers share the same /video and /data directory for easy access

Repository Structure

handbrake-psy-stack/
├── docker-compose.yml (Stack definition)
├── .env.example (Example environment configuration)
└── handbrake-psy-worker/
    └── Dockerfile (Builds HandBrakeCLI with the SVT-AV1-PSY patch)

Environment Variables

All environment variables can be configured via a .env file or overridden in Portainer.

Variable	Description	Default
USER_ID	UID for container user	1000
GROUP_ID	GID for container user	1000
MEDIA_PATH	Host path to your download/media folder	/mnt/media/downloads
SERVER_PORT	External port for HandBrake Web UI	1519
SERVER_CONTAINER_NAME	Container name for the web server	handbrake-web-server
WORKER_CONTAINER_NAME	Container name for the worker	handbrake-web-worker
WORKER_IMAGE_NAME	Image name for the patched worker	handbrake-web-worker-psy:latest
WORKER_ID	Worker ID (used for multi-worker setups)	worker-1
SERVER_URL	Internal DNS name of the server container	handbrake-server
SERVER_PORT_INTERNAL	Internal port between worker and server	9999

To start quickly, copy .env.example to .env and adjust paths or ports as needed:

cp .env.example .env

Deployment Methods

Portainer

1. Open Portainer → Stacks → Add Stack → Repository
2. Set:
   • Repository URL: https://github.com//handbrake-psy-stack.git
   • Compose path: docker-compose.yml
3. (Optional) Edit environment variables in the UI or push your own .env file
4. Click "Deploy the stack"

Note: The first build may take 20–30 minutes depending on CPU speed, since HandBrake is compiled from source.

Docker Compose / CLI

If you prefer CLI deployment:

git clone https://github.com//handbrake-psy-stack.git
cd handbrake-psy-stack
cp .env.example .env  # edit values if needed
docker compose up -d --build

Stop and remove:

docker compose down

How It Works

• The worker image builds a custom version of HandBrakeCLI using:
  • Official HandBrake source
  • The SVT-AV1-PSY patch script
• The server provides the browser-based UI and job management
• Both containers share a common /video mount, so encoded files appear directly in your host's MEDIA_PATH

Verification

After the first build completes, verify the patched encoder:

docker exec -it handbrake-web-worker HandBrakeCLI --version

You should see output confirming the SVT-AV1-PSY build.

You can also list encoder options:

HandBrakeCLI -e av1 --help

Useful Tips

• Use multiple workers by duplicating the worker service and giving each a unique WORKER_ID
• Change SERVER_PORT if you already use port 1519
• To rebuild the image later, run:

  docker compose build --no-cache handbrake-worker

Credits

• thenickoftime/handbrake-web-server
• Nj0be/HandBrake-SVT-AV1-PSY
• HandBrake Team

License

This project is distributed under the MIT License. HandBrake itself and SVT-AV1-PSY remain under their respective open-source licenses.