# HandBrake Web

> Web-based video transcoder.

- Category: Media & Entertainment
- Difficulty: intermediate
- Components: handbrake
- Tags: handbrake, transcoding, video, converter
- Source: https://docker.recipes/media/handbrake

## Overview

HandBrake is a powerful, open-source video transcoder that has been the go-to solution for converting video files between formats since 2003. Originally developed to rip DVDs, HandBrake has evolved into a comprehensive video processing tool that supports virtually every modern codec and container format, including H.264, H.265/HEVC, VP9, AV1, MP4, MKV, and WebM. The software excels at reducing file sizes while maintaining visual quality through advanced encoding algorithms and preset configurations optimized for different devices and streaming platforms.

This Docker configuration wraps HandBrake in a web-accessible VNC interface using jlesage's containerized implementation, transforming the desktop application into a server-based transcoding solution. The setup includes automated batch processing capabilities through a watch folder system, where videos dropped into the monitored directory are automatically converted using predefined settings. The container handles the entire workflow from input detection through final output, eliminating the need for manual intervention in repetitive transcoding tasks.

Media professionals, content creators, and home server enthusiasts will find this stack particularly valuable for building centralized video processing workflows. Unlike desktop HandBrake installations that require direct system access, this web-based approach enables remote transcoding management, batch processing automation, and integration with media server ecosystems like Plex or Jellyfin. The combination of HandBrake's proven transcoding engine with automated folder monitoring creates a hands-off solution for maintaining consistent video formats across large media libraries.

## Features

- VNC-based web interface accessible through any browser without client software installation
- Automated batch transcoding with configurable watch folder monitoring and processing queues
- Support for hardware-accelerated encoding via Intel Quick Sync Video and AMD VAAPI when GPU devices are mounted
- Extensive preset library including device-specific profiles for Apple TV, Roku, Android, and streaming platforms
- Advanced video filters including deinterlacing, denoising, cropping, and subtitle burning capabilities
- Multi-format container support with automatic stream mapping for video, audio, and subtitle tracks
- Queue management system allowing multiple simultaneous transcoding jobs with priority scheduling
- Comprehensive codec support including modern formats like H.265 HEVC, VP9, and AV1 for maximum compression efficiency

## Use cases

- Home media server optimization for converting large video collections to consistent formats and bitrates
- Content creation workflows requiring batch processing of recorded footage or downloaded source material
- Automated video preprocessing for streaming platforms with specific encoding requirements
- Remote transcoding services for teams working with video content across different locations
- Legacy format conversion for digitizing old DVD collections or proprietary video formats
- Bandwidth optimization by creating multiple quality versions of source videos for adaptive streaming
- Archive management for reducing storage requirements while preserving acceptable video quality

## Prerequisites

- Minimum 4GB RAM for HD video processing, 8GB+ recommended for 4K content transcoding
- Sufficient storage space as transcoding typically requires 2-3x the source file size during processing
- Port 5800 available for web interface access and VNC client connections
- Understanding of video codecs, containers, and quality settings for optimal preset configuration
- GPU drivers and device access configured if planning to use hardware acceleration features
- Directory permissions properly set for Docker container access to watch and output folders

## docker-compose.yml

```yaml
services:
  handbrake:
    image: jlesage/handbrake:latest
    container_name: handbrake
    restart: unless-stopped
    ports:
      - "5800:5800"
    environment:
      USER_ID: 1000
      GROUP_ID: 1000
      TZ: UTC
      AUTOMATED_CONVERSION_PRESET: "Very Fast 1080p30"
      AUTOMATED_CONVERSION_FORMAT: mp4
    volumes:
      - handbrake_config:/config
      - /path/to/watch:/watch
      - /path/to/output:/output

volumes:
  handbrake_config:
```

## .env

```bash
# Configure automated conversion settings
```

## Usage notes

- Docs: https://github.com/jlesage/docker-handbrake
- Access web UI at http://localhost:5800 (VNC-based interface)
- Drop files in /watch folder for automatic conversion
- Converted files output to /output, originals in /storage
- Presets: AUTOMATED_CONVERSION_PRESET sets encoding quality
- Hardware encoding: mount /dev/dri for Intel QSV/AMD VAAPI

## Troubleshooting

- Blank web interface or connection refused: Verify port 5800 is properly mapped and not blocked by firewall rules
- Watch folder not detecting new files: Check volume mount paths and ensure Docker container has read permissions on source directories
- Transcoding fails with codec errors: Verify source video format is supported and adjust AUTOMATED_CONVERSION_PRESET to compatible settings
- Hardware encoding not working: Ensure GPU device is mounted with --device=/dev/dri and appropriate drivers are installed on host system
- Out of disk space errors during processing: Monitor available storage as HandBrake requires temporary space equal to output file size during encoding
- Permission denied writing to output folder: Verify USER_ID and GROUP_ID environment variables match host system ownership of mounted volumes

