handbrakecli

Convert a video file to MKV (AAC 160kbit audio and x264 CRF20 video)

$ handbrakecli [[-i|--input]] [input.avi] [[-o|--output]] [output.mkv] [[-e|--encoder]] x264 [[-q|--quality]] 20 [[-B|--ab]] 160

$ handbrakecli [[-i|--input]] [input.mp4] [[-o|--output]] [output.mp4] [[-w|--width]] 320 [[-l|--height]] 240

$ handbrakecli [[-z|--preset-list]]

$ handbrakecli [[-Z|--preset]] "Android" [[-i|--input]] [input.ext] [[-o|--output]] [output.mp4]

$ handbrakecli [[-i|--input]] [/dev/sr0] [[-t|--title]] 0

$ handbrakecli [[-i|--input]] [/dev/sr0] [[-t|--title]] 1 [[-o|--output]] [out.mkv] [[-f|--format]] av_mkv [[-e|--encoder]] x264 [[-s|--subtitle]] [1,4,5] [[-a|--audio]] [1,2] [[-E|--aencoder]] copy [[-q|--quality]] [23]

handbrakecli [options] -i -o

Common usage examples:
handbrakecli -i input.mkv -o output.mp4 --preset 'Fast 1080p30'
handbrakecli -i /dev/dvd --title 1 -o movie.mp4 --preset 'Fast 720p30'

-i
    Specifies the input video file, device, or URL to be transcoded.

-o
    Defines the output file path for the transcoded video.

-Z
    Applies a built-in preset. Use -Z list to see available presets.

-t
    Selects a specific title from the input (e.g., DVD/Blu-ray). Use -t 0 to scan titles.

-c
    Specifies a specific chapter or range of chapters to encode (e.g., 1, 1-5).

-s
    Selects subtitle track(s) by index or language. Use 'none' for no subtitles.

-a
    Chooses audio track(s) by index or language. Can be 'none' or 'all'.

-e
    Sets the video encoder (e.g., x264, x265, svt_av1).

-q
    Sets the video quality (CRF value for H.264/H.265; 0-51, lower is better).

-r
    Specifies the video framerate (e.g., 30, 29.97, 'auto').

-f
    Sets the output format or container (e.g., mp4, mkv, webm).

--crop
    Manually sets the video crop values (Top:Bottom:Left:Right pixels).

--two-pass
    Enables two-pass encoding for better quality and smaller file sizes.

-v
    Sets the verbosity level of the output messages (0-3; 3 is debug).

handbrakecli is the command-line interface (CLI) version of HandBrake, a popular open-source video transcoder. It enables users to convert video from almost any format to a selection of modern, widely supported codecs. This tool is ideal for scripting, automation, server-side processing, or situations where a graphical user interface (GUI) is not available or desired. It supports a wide range of input sources, including DVD, Blu-ray discs (with necessary libraries), and video files, and offers extensive control over video and audio settings, subtitles, chapters, and more, leveraging its powerful encoding engine.

Video transcoding is a CPU-intensive process and can take significant time depending on input/output settings and hardware. Understanding video codecs, quality settings (e.g., CRF), and audio options is crucial for optimal results. Copy-protection on commercial discs may require additional third-party libraries not included with HandBrake.

To see all available built-in presets, use handbrakecli -Z list. To scan an input source (like a DVD or MKV with multiple titles) and list its available titles, use handbrakecli -i -t 0. This is essential for selecting the correct content before encoding.

While handbrakecli primarily uses CPU for encoding, it can leverage hardware encoders (e.g., Intel Quick Sync Video, NVIDIA NVENC, AMD VCN) if supported by your system and HandBrake's build. Use --encoder to specify a hardware encoder like 'qsv_h264' or 'nvenc_h264'.

HandBrake originated in 2003, initially developed as a tool for ripping DVDs to various formats, primarily for use on Apple devices. Over time, it evolved into a powerful general-purpose video transcoder, supporting a vast array of input and output formats beyond just DVDs and Apple targets. The command-line interface, handbrakecli, has always been a core component, enabling automation and server-side processing, which is crucial for large-scale video encoding tasks.

ffmpeg(1), mencoder(1), vlc(1)