wiki:CLIGuide

Using HandBrakeCLI

HandBrake's CLI is really easy to use. If you get comfortable with it, it can be a lot more efficient than the GUIs.

The Basics

First, simple input and output.

HandBrakeCLI -i source -o destination

That will encode with default values: 1000 Kbps MPEG-4 Visual video and 160 Kbps AAC-LC audio in an MP4 container.

Easy, right? So now you can start customizing those settings. You can pile on all sorts of things, and end up with a monster like:

HandBrakeCLI -i /Volumes/MyBook/BLURAY_DISC -o /Volumes/MyBook/Bluray.mkv -m -E copy --audio-copy-mask ac3,dts,dtshd --audio-fallback ffac3 -e x264 -q 20 -x level=4.1:ref=4:b-adapt=2:direct=auto:me=umh:subq=8:rc-lookahead=50:psy-rd=1.0,0.15:deblock=-1,-1:vbv-bufsize=30000:vbv-maxrate=40000:slices=4

For now, think about less complex stuff:

HandBrakeCLI -i VIDEO_TS -o movie.mp4 -e x264 -q 20 -B 160

That will encode a source video located at the path VIDEO_TS to an output file called movie.mp4. It will use x264 with a CRF (Constant Quality) of 20 to encode the video, and encode the audio as 160 Kbps AAC.

So can you start to see how this works? The most important info for HandBrakeCLI is the location of the DVD, and the location and name where you want to store the encoded video it will output. If you don't specify anything else, it uses fast, low-quality, default values. Each bit of information is preceded by a flag: -i for input, -o for output. To select an encoder, you use -e followed by the encoder name. So -e x264 uses x264 to encode the video. Video bitrate is controlled by -b, and audio bitrate is controlled by -B (yes, the option names are case-sensitive. -b is not -B and -e is not -E).

A few rudimentary hints for using the command line

  • Filepaths are important. I'm on a Mac, and my username is jon. My home directory is:
    /Users/jon/
    
    So the path to my Desktop is:
    /Users/jon/Desktop
    
    And so my Movies folder is at
    /Users/jon/Movies
    
    A common shortcut is to use a tilde (~) to represent your home directory. That means:
    ~/Movies
    
    is the same as:
    /Users/jon/Movies
    

Make sure you remember the right capitalization for everything. At the command line, HandBrakeCLI is not the same as handbrakecli. If you have to type a space in filepath, precede it with a \ backslash so the system knows what's going on.

  • You usually store GUI programs in the /Applications folder. CLI programs are usually stored in places like /usr/bin or /opt/local/bin. You can do that with HandBrake, but the easiest thing to do is just navigate to the directory that stores HandBrakeCLI. To navigate through your file system at the command line, you change directories (folders) by using the "cd" (Change Directories) command. For example, to move to my Movies folder, I would type:
    cd ~/Movies
    
    Then, tell the shell to look for the program in the current working directory. To run a command in the Terminal, you just type its name. But the shell will only look in the places where applications are usually stored (like /usr/bin/). You need to tell it to look in the current directory. To do that, precede the program name with ./ like this:
    ./HandBrakeCLI
    
    Of course, running that won't do much anything useful. If you run HandBrake without telling it what to do, it will just tell you to read the help...

Presets

HandBrake offers hard coded, factory-fresh presets that are exactly the same as the built-in presets in the MacGui. Descriptions of presets and rankings for speed, as well as a web-copy of all the presets' CLI strings are available.

To use a preset, type, for example:

./HandBrakeCLI -i /Volumes/DVD -o movie.mp4 --preset="iPhone & iPod Touch" 

So it's:

--preset="Preset Name"

Be careful -- spelling and spacing and capitalization count. Don't forget the quotation marks, either. You can override most preset settings by specifying other options on the command line. To see a list of all the preset names and settings, type:

./HandBrakeCLI --preset-list

Option by Option

To see everything HandBrakeCLI has to offer, run this:

HandBrakeCLI -h

That should produce this output:

Syntax: HandBrakeCLI [options] -i <device> -o <file>

### General Handbrake Options------------------------------------------------

    -h, --help              Print help
    -u, --update            Check for updates and exit
    -v, --verbose <#>       Be verbose (optional argument: logging level)
    -Z. --preset <string>   Use a built-in preset. Capitalization matters, and
                            if the preset name has spaces, surround it with
                            double quotation marks
    -z, --preset-list       See a list of available built-in presets
        --no-dvdnav         Do not use dvdnav for reading DVDs
    --no-opencl             Disable use of OpenCL

### Source Options-----------------------------------------------------------

    -i, --input <string>    Set input device
    -t, --title <number>    Select a title to encode (0 to scan all titles only,
                            default: 1)
        --min-duration      Set the minimum title duration (in seconds). Shorter
                            titles will not be scanned (default: 10).
        --scan              Scan selected title only.
        --main-feature      Detect and select the main feature title.
    -c, --chapters <string> Select chapters (e.g. "1-3" for chapters
                            1 to 3, or "3" for chapter 3 only,
                            default: all chapters)
        --angle <number>    Select the video angle (DVD or Blu-ray only)
        --previews <#:B>    Select how many preview images are generated,
                            and whether or not they're stored to disk (0 or 1).
                            (default: 10:0)
    --start-at-preview <#>  Start encoding at a given preview.
    --start-at    <unit:#>  Start encoding at a given frame, duration (in seconds),
                            or pts (on a 90kHz clock)
    --stop-at     <unit:#>  Stop encoding at a given frame, duration (in seconds),
                            or pts (on a 90kHz clock)
### Destination Options------------------------------------------------------

    -o, --output <string>   Set output file name
    -f, --format <string>   Set output container format (av_mp4/av_mkv)
                            (default: autodetected from file name)
    -m, --markers           Add chapter markers
    -4, --large-file        Create 64-bit mp4 files that can hold more than 4 GB
                            of data. Note: breaks pre-iOS iPod compatibility.
    -O, --optimize          Optimize mp4 files for HTTP streaming ("fast start")
    -I, --ipod-atom         Mark mp4 files so 5.5G iPods will accept them
    -P, --use-opencl        Use OpenCL where applicable
    -U, --use-hwd           Use DXVA2 hardware decoding

### Video Options------------------------------------------------------------

    -e, --encoder <string>  Set video library encoder
                            Options: x264/x265/mpeg4/mpeg2/VP8/theora
                            (default: mpeg4)
        --encoder-preset    Adjust video encoding settings for a particular
          <string>          speed/efficiency tradeoff (encoder-specific)
    --encoder-preset-list   List supported --encoder-preset values for the
          <string>          specified video encoder
        --encoder-tune      Adjust video encoding settings for a particular
          <string>          type of souce or situation (encoder-specific)
    --encoder-tune-list     List supported --encoder-tune values for the
          <string>          specified video encoder
    -x, --encopts <string>  Specify advanced encoding options in the same
                            style as mencoder (all encoders except theora):
                            option1=value1:option2=value2
        --encoder-profile   Ensures compliance with the requested codec
          <string>          profile (encoder-specific)
    --encoder-profile-list  List supported --encoder-profile values for the
          <string>          specified video encoder
        --encoder-level     Ensures compliance with the requested codec
          <string>          level (encoder-specific)
    --encoder-level-list    List supported --encoder-level values for the
          <string>          specified video encoder
    -q, --quality <number>  Set video quality
    -b, --vb <kb/s>         Set video bitrate (default: 1000)
    -2, --two-pass          Use two-pass mode
    -T, --turbo             When using 2-pass use "turbo" options on the
                            1st pass to improve speed (only works with x264)
    -r, --rate              Set video framerate (5/10/12/15/23.976/24/25/29.97/30/50/59.94/60)
                            Be aware that not specifying a framerate lets
                            HandBrake preserve a source's time stamps,
                            potentially creating variable framerate video
    --vfr, --cfr, --pfr     Select variable, constant or peak-limited
                            frame rate control. VFR preserves the source
                            timing. CFR makes the output constant rate at
                            the rate given by the -r flag (or the source's
                            average rate if no -r is given). PFR doesn't
                            allow the rate to go over the rate specified
                            with the -r flag but won't change the source
                            timing if it's below that rate.
                            If none of these flags are given, the default
                            is --cfr when -r is given and --vfr otherwise

### Audio Options-----------------------------------------------------------

    -a, --audio <string>    Select audio track(s), separated by commas
                            ("none" for no audio, "1,2,3" for multiple
                             tracks, default: first one).
                            Multiple output tracks can be used for one input.
    -E, --aencoder <string> Audio encoder(s):
                               av_aac
                               fdk_aac
                               fdk_haac
                               copy:aac
                               ac3
                               copy:ac3
                               copy:dts
                               copy:dtshd
                               mp3
                               copy:mp3
                               vorbis
                               flac16
                               flac24
                               copy
                            copy:* will passthrough the corresponding
                            audio unmodified to the muxer if it is a
                            supported passthrough audio type.
                            Separated by commas for more than one audio track.
                            Defaults:
                               av_mp4   av_aac
                               av_mkv   mp3
        --audio-copy-mask   Set audio codecs that are permitted when the
                <string>    "copy" audio encoder option is specified
                            (aac/ac3/dts/dtshd/mp3, default: all).
                            Separated by commas for multiple allowed options.
        --audio-fallback    Set audio codec to use when it is not possible
                <string>    to copy an audio track without re-encoding.
    -B, --ab <kb/s>         Set audio bitrate(s) (default: depends on the
                            selected codec, mixdown and samplerate)
                            Separated by commas for more than one audio track.
    -Q, --aq <quality>      Set audio quality metric (default: depends on the
                            selected codec)
                            Separated by commas for more than one audio track.
    -C, --ac <compression>  Set audio compression metric (default: depends on the
                            selected codec)
                            Separated by commas for more than one audio track.
    -6, --mixdown <string>  Format(s) for audio downmixing/upmixing:
                               mono
                               left_only
                               right_only
                               stereo
                               dpl1
                               dpl2
                               5point1
                               6point1
                               7point1
                               5_2_lfe
                            Separated by commas for more than one audio track.
                            Defaults:
                               av_aac           up to dpl2
                               fdk_aac          up to dpl2
                               fdk_haac         up to dpl2
                               ac3              up to 5point1
                               mp3              up to dpl2
                               vorbis           up to dpl2
                               flac16           up to 7point1
                               flac24           up to 7point1
        --normalize-mix     Normalize audio mix levels to prevent clipping.
               <string>     Separated by commas for more than one audio track.
                            0 = Disable Normalization (default)
                            1 = Enable Normalization
    -R, --arate             Set audio samplerate(s) (8/11.025/12/16/22.05/24/32/44.1/48 kHz)
                            Separated by commas for more than one audio track.
    -D, --drc <float>       Apply extra dynamic range compression to the audio,
                            making soft sounds louder. Range is 1.0 to 4.0
                            (too loud), with 1.5 - 2.5 being a useful range.
                            Separated by commas for more than one audio track.
        --gain <float>      Amplify or attenuate audio before encoding.  Does
                            NOT work with audio passthru (copy). Values are in
                            dB.  Negative values attenuate, positive values
                            amplify. A 1 dB difference is barely audible.
        --adither <string>  Apply dithering to the audio before encoding.
                            Separated by commas for more than one audio track.
                            Only supported by some encoders (fdk_aac/fdk_haac/flac16).
                            Options:
                               auto (default)
                               none
                               rectangular
                               triangular
                               triangular_hp
                               triangular_ns
    -A, --aname <string>    Audio track name(s),
                            Separated by commas for more than one audio track.

### Picture Settings---------------------------------------------------------

    -w, --width  <number>   Set picture width
    -l, --height <number>   Set picture height
        --crop  <T:B:L:R>   Set cropping values (default: autocrop)
        --loose-crop  <#>   Always crop to a multiple of the modulus
                            Specifies the maximum number of extra pixels
                            which may be cropped (default: 15)
    -Y, --maxHeight   <#>   Set maximum height
    -X, --maxWidth    <#>   Set maximum width
    --strict-anamorphic     Store pixel aspect ratio in video stream
    --loose-anamorphic      Store pixel aspect ratio with specified width
    --custom-anamorphic     Store pixel aspect ratio in video stream and
                            directly control all parameters.
    --display-width         Set the width to scale the actual pixels to
      <number>              at playback, for custom anamorphic.
    --keep-display-aspect   Preserve the source's display aspect ratio
                            when using custom anamorphic
    --pixel-aspect          Set a custom pixel aspect for custom anamorphic
      <PARX:PARY>
                            (--display-width and --pixel-aspect are mutually
                             exclusive and the former will override the latter)
    --itu-par               Use wider, ITU pixel aspect values for loose and
                            custom anamorphic, useful with underscanned sources
    --modulus               Set the number you want the scaled pixel dimensions
      <number>              to divide cleanly by. Does not affect strict
                            anamorphic mode, which is always mod 2 (default: 16)
    -M, --color-matrix      Set the color space signaled by the output
                            Values: 709, pal, ntsc, 601 (same as ntsc)
                            (default: detected from source)

### Filters---------------------------------------------------------

    -d, --deinterlace       Unconditionally deinterlaces all frames
          <fast/slow/slower/bob> or omitted (default settings)
           or
          <YM:FD>           (default 0:-1)
    -5, --decomb            Selectively deinterlaces when it detects combing
          <fast/bob> or omitted (default settings)
           or
          <MO:ME:MT:ST:BT:BX:BY:MG:VA:LA:DI:ER:NO:MD:PP:FD>
          (default: 7:2:6:9:80:16:16:10:20:20:4:2:50:24:1:-1)
    -9, --detelecine        Detelecine (ivtc) video with pullup filter
                            Note: this filter drops duplicate frames to
                            restore the pre-telecine framerate, unless you
                            specify a constant framerate (--rate 29.97)
          <L:R:T:B:SB:MP:FD> (default 1:1:4:4:0:0:-1)
    -8, --denoise           Denoise video with hqdn3d filter
          <ultralight/light/medium/strong> or omitted (default settings)
           or
          <SL:SCb:SCr:TL:TCb:TCr>
          (default: 4:3:3:6:4.5:4.5)
    --nlmeans               Denoise video with nlmeans filter
          <ultralight/light/medium/strong> or omitted
           or
          <SY:OTY:PSY:RY:FY:PY:Sb:OTb:PSb:Rb:Fb:Pb:Sr:OTr:PSr:Rr:Fr:Pr>
          (default 8:1:7:3:2:0)
    --nlmeans-tune          Tune nlmeans filter to content type
                            Note: only works in conjunction with presets
                            ultralight/light/medium/strong.
          <none/film/grain/highmotion/animation> or omitted (default none)
    -7, --deblock           Deblock video with pp7 filter
          <QP:M>            (default 5:2)
        --rotate     <mode> Rotate image or flip its axes.
                            Modes: (can be combined)
                               1 vertical flip
                               2 horizontal flip
                               4 rotate clockwise 90 degrees
                            Default: 3 (vertical and horizontal flip)
    -g, --grayscale         Grayscale encoding

### Subtitle Options------------------------------------------------------------

    -s, --subtitle <string> Select subtitle track(s), separated by commas
                            More than one output track can be used for one
                            input.
                            Example: "1,2,3" for multiple tracks.
                            A special track name "scan" adds an extra 1st pass.
                            This extra pass scans subtitles matching the
                            language of the first audio or the language 
                            selected by --native-language.
                            The one that's only used 10 percent of the time
                            or less is selected. This should locate subtitles
                            for short foreign language segments. Best used in
                            conjunction with --subtitle-forced.
    -F, --subtitle-forced   Only display subtitles from the selected stream if
          <string>          the subtitle has the forced flag set. The values in
                            "string" are indexes into the subtitle list
                            specified with '--subtitle'.
                            Separated by commas for more than one subtitle track.
                            Example: "1,2,3" for multiple tracks.
                            If "string" is omitted, the first track is forced.
        --subtitle-burned   "Burn" the selected subtitle into the video track
          <number>          If "number" is omitted, the first track is burned.
                            "number" is an index into the subtitle list
                            specified with '--subtitle'.
        --subtitle-default  Flag the selected subtitle as the default subtitle
          <number>          to be displayed upon playback.  Setting no default
                            means no subtitle will be automatically displayed
                            If "number" is omitted, the first track is default.
                            "number" is an index into the subtitle list
                            specified with '--subtitle'.
    -N, --native-language   Specifiy your language preference. When the first
          <string>          audio track does not match your native language then
                            select the first subtitle that does. When used in
                            conjunction with --native-dub the audio track is
                            changed in preference to subtitles. Provide the
                            language's iso639-2 code (fre, eng, spa, dut, et cetera)
        --native-dub        Used in conjunction with --native-language
                            requests that if no audio tracks are selected the
                            default selected audio track will be the first one
                            that matches the --native-language. If there are no
                            matching audio tracks then the first matching
                            subtitle track is used instead.
        --srt-file <string> SubRip SRT filename(s), separated by commas.
        --srt-codeset       Character codeset(s) that the SRT file(s) are
          <string>          encoded in, separated by commas.
                            Use 'iconv -l' for a list of valid
                            codesets. If not specified, 'latin1' is assumed
        --srt-offset        Offset (in milliseconds) to apply to the SRT file(s),
          <string>          separated by commas. If not specified, zero is assumed.
                            Offsets may be negative.
        --srt-lang <string> Language as an iso639-2 code fra, eng, spa et cetera)
                            for the SRT file(s), separated by commas. If not specified,
                            then 'und' is used.
        --srt-default       Flag the selected srt as the default subtitle
          <number>          to be displayed upon playback.  Setting no default
                            means no subtitle will be automatically displayed
                            If "number" is omitted, the first srt is default.
                            "number" is an 1 based index into the srt-file list
        --srt-burn          "Burn" the selected srt subtitle into the video track
          <number>          If "number" is omitted, the first srt is burned.
                            "number" is an 1 based index into the srt-file list

Some of the common cli options in more detail...

General Options

  • -u or --update: asks the HandBrake website if there's a new version available
  • -v or --verbose: in verbose mode, extra messages from the core library will appear on screen during the encode. This is useful if you're a developer debugging, or if you can't figure out why an encode isn't working right. There are different levels of verbosity. By default level 1 logging is enabled. This contains anything useful for tech support, and is the "Activity Log" talked about so much on the HandBrake forums. Level 2 adds some memory-related logging, and level 3 is for granular, packet-by-packet analysis for debugging. If you follow -v with a number, like "-v2", it will use that as the verbosity level instead of 1.

  • -Z or --preset: enter a preset name to use.
  • -z or --preset-list: displays all the presets' names and what CLI options they use.
  • --no-dvdnav: Disables the use of libdvdnav. libdvdread will be used instead. This can be useful in situations where libdvdnav struggles to read a DVD source.

Source Options

  • -i or --input: input is all important. You must include it, followed by a filepath (like /Volumes/MOVIE or ~/Movies/VIDEO_TS).
  • -t or --title: selects the title from a DVD to encode. If you don't specify it, this will default to 1. To just scan a DVD, letting you see the titles and their durations (to help pick which is the feature you want) as well as the chapter durations, autodetected cropping, subtitle and audio tracks, etc., give this a value of 0.
  • --scan: scan only the title number. Any other titles are skipped.
  • --min-duration: when scanning all titles, skip titles shorter than the specified duration (in seconds; default: 10).
  • --main-feature: attempt to detect and encode only the main feature of the source.
  • -c or --chapters: tells it to only encode a specified chapter or range of chapters from the title. If you don't specify, it will default to all chapters. Ranges are given with hyphens, like 1-3.
  • --angle: Encode the specified angle from a multi-angle source. Works for Blu-ray sources, and DVD sources (unless dvdnav is disabled).
  • --previews: Increase the number of previews HandBrake generates. Default 10. This can increase the accuracy of the auto cropping feature.
  • --start-at-preview: Start encoding from one of the (up to 30) previews that handbrake generates during the scan
  • --start-at: Start encoding from a set point on the source file. (This can be a frame, duration (in seconds) or pts value)
  • --stop-at: Stop encoding from a set point on the source file. (This can be a frame, duration (in seconds) or pts value)

Destination Options

  • -o or --output: output is all important. You must include it, followed by an output filename with a filepath (like ~/Movies/movie.mp4). If you suffix the file .mp4 or .mkv, it will be encoded with that file format container.
  • -f or --format: forces a particular container file format. Your choices are mp4 and mkv. If this is omitted, it will try to figure out the format from the output filename.
  • -m or --markers: this setting includes a chapter index in the video, based on the chapter times used in the source. In .mp4 files, these chapter markers are in QuickTime's format. They can be read by VLC, QuickTime, iTunes, the AppleTV, the iPod, and the iPhone. In order for QuickTime to see the chapters, you must rename the output file to end with .m4v instead of .mp4.

If you wish to import chapter names from a csv file, you can do so using the following: --markers="/full/path/to/chapters_file.csv" The CSV file should be formatted as follows:

1,Chapter One
2,Chapter Two
3,Chapter Three

Note: Should you use a comma in your chapter name: e.g 1,Chapter, Name you must place a backslash before it like so: 1,Chapter\, Name (This slash will not actually appear in the chapter name)

  • -4 or --large-file: when used with the MP4 file format, this permits creation of files larger than 4GB. But to do so, it uses 64-bit chunk offsets. These make it incompatible with some devices (like the iPod, except the iPod touch and iPhone) -- and that incompatibility happens whenever the feature is enabled, whether or not the output reaches 4 GB. On the other hand, if you do not enable it, and your MP4 is larger than 4 GB, the output will be unplayable and unrecoverable.
  • -O or --optimize: Rearranges MP4 files so they play better over the web as progressive downloads.
  • -I or --ipod-atom: Applies a marker to MP4 files that older iPods (5/5.5G) require before they'll allow H.264 video to sync.

Video Options

  • -e or --encoder: selects the video encoder. The default is ffmpeg4 (similar to DivX). The other options are ffmpeg2, x264, and theora.
  • --x264-preset: use an x264 preset (options: ultrafast, superfast, veryfast, faster, fast, medium, slow, slower, veryslow, placebo; default: medium). Slower presets improve compression efficiency at the expense of encoding speed. Only works with the x264 encoder. Applies before --x264-tune, --encopts and --x264-profile (so the latter override it).
  • --x264-tune: use one or more x264 tunings (options: film, animation, grain, stillimage, psnr, ssim, fastdecode, zerolatency; default: none). Adjust encoding settings for a specific type of source content. Multiple tunings are separated by a comma. Only one "psy" tuning (film, animation, grain, stillimage, psnr, ssim) can be specified. Only works with the x264 encoder. Applies before --encopts and --x264-profile (so the latter override it).
  • -x or --encopts: permits you to pass through advanced encoding options to the encoder (only for x264 and ffmpeg2/ffmpeg4). Applies before and is thus overridden by --x264-profile.
  • --x264-profile: tell x264 to conform to the specified H.264 profile (options: baseline, main, high, high10, high422, high444; default: high). Only works with the x264 encoder. Applies after --x264-preset, --x264-tune and --encopts; overrides them all.
  • -q or --quality: controls the video quality. Read the Constant Quality guide for good values and an understanding of how this works.

  • -b or --vb: allows you to set an average output video bitrate in kilobits per second. Do not use this if you wish to maintain a particular quality across your encodes. Be aware that for video encoders, 1 megabit is equal to 1000 kilobits, not 1024 kilobits.
  • -2 or --two-pass: enables two-pass encoding when using an average bitrate (but not for a constant quality or rate factor). Two-pass encoding takes about twice as long, but conforms better to the average bitrate and improves picture quality. It takes no options.
  • -T or --turbo: use with 2-pass x264 encodes to significantly boost the speed of the first pass - wiith minimal effect on quality - by adding the options: "ref=1:subme=2:me=dia:analyse=none:trellis=0:no-fast-pskip=0:8x8dct=0:weightb=0"
  • -r or --rate: controls the video framerate, or FPS. Your options are 5, 10, 12, 15, 23.976, 24, 25, or 29.97. If you do not specify, HandBrake will default to using the same frame rate as the DVD. It will literally pass through the durations of each frame in the source video. This can mean a variable frame rate, because many sources--such as DVDs and other MPEG-2 streams--are inherently variable framerate. A frame remains on screen until the next frame's time stamp is reached. Those time stamps are not always separated by the same amount of time. Note that the .avi format isn't smart enough to understand this. If you do not specify a rate, HandBrake will, for it, instead set the framerate to a constant 23.976, 25, or 29.97 FPS based on some guesswork about the source video.
  • --vfr, --cfr, --pfr: Variable, Constant or Peak Framerate. (Default is VFR unless -r is specified in which case CFR is default)

Audio Options

  • -a or --audio: selects the audio track or tracks to encode. You can include an unlimited number of audio tracks, separated by commas. The first track is 1, the second is 2, etc. Each track can use different output settings, and the same input track can be encoded multiple times with different settings.
  • -E or --aencoder: selects the audio encoder. Choices are av_aac, fdk_aac (Windows/Linux? only), ca_aac (Mac OS X only), fdk_haac (Windows/Linux? only), ca_haac (Mac OS X only), copy:aac, ac3, copy:ac3, copy:dts, copy:dtshd, mp3, copy:mp3, vorbis, flac16, flac24 and copy. av_aac, fdk_aac and ca_aac encode AAC-LC audio, fdk_haac and ca_haac encode HE-AAC audio, mp3 encodes MP3 audio using lame, vorbis encodes Vorbis audio, flac16 encodes 16-bit FLAC audio, and flac24 encodes 24-bit FLAC audio. The defaults are: av_aac AAC for .mp4, mp3 for .mkv - except under OS X where ca_aac AAC is default for both containers. The copy:* encoders pass the specified codec through to the output, or fallback on the corresponding encoder if the source codec doesn't match (except for dts/dtshd, for which case the track is dropped). copy will pass any supported passthrough codec to the output, and use the fallback encoder specified via --audio-fallback if the source codec can't be passed through. Note: if you pass AC3 through to .mp4, it will only be recognized by the AppleTV and QuickTime Player if the file extension is .m4v.
  • --audio-copy-mask: sets the codecs allowed to be passed through when the 'copy' audio encoder is used. Options are aac, ac3, dts, dtshd and mp3. Multiple options can be specified, separated by commas. By default all options are enabled; use --audio-copy-mask none to disable them all.
  • --audio-fallback: set the fallback encoder used when using the 'copy' audio encoder and passthrough is not possible. All non-passthrough encoders are supported. No fallback is specified by default. Note: if no valid fallback is specified and passthrough is not possible, the track is dropped.
  • -B or --ab: allows you to set an average audio bitrate in kilobits per second. The default depends on the codec, mixdown and samplerate.
  • -Q or --aq: controls the audio quality (VBR). Only ca_aac, lame and vorbis support this option. The scale is encoder-specific, from lowest to highest quality: 0 to 127 (ca_aac), 10 to 0 (lame), -2 to 10 (vorbis).
  • -C or --ac: set audio compression efficiency vs. speed. Corresponds to -compression_level (ffflac), -q (lame). Encoder-specific.
  • -6 or --mixdown: This controls downmixing of the audio. The options are auto, mono, stereo, dpl1 (Dolby Surround), dpl2 (Dolby ProLogic? 2), or 6ch (5.1). For example, you could downmix a stereo source to mono, or a 5.1 source to 2-channel Dolby ProLogic? 2. The default behavior is for HandBrake to downmix to Dolby ProLogic? 2 (except when the encoder is ffac3 or ffflac, for which the default mixdown is 6ch. You may use --mixdown 6ch to preserve all of the surround channels in the source audio, creating a 6-channel (5.1) output track from a 6-channel (5.1) source.
  • -R or --arate: sets the sample rate for the audio in kilohertz. The default, auto, uses the same sample rate as the source audio track, unless it's not compatible with the audio encoder.
  • -D or --drc: if your audio isn't loud enough, you can try applying extra dynamic range compression when encoding from AC3 sources. This will boost up the volume of soft audio samples while leaving loud samples as is. This reduces the dynamic range, but should help for catching quiet audio in noisy listening environments. It takes a floating point number as its value, from 1.0 (use the compression hints embedded in the AC3 track) to 4.0 (blow out your speakers from the background sound of elevator doors closing). 1.0 to 2.5 is a useful range. The default is 0.0 (off). Doesn't work with AC3 passthrough.
  • --gain: increase (positive values) or decrease (negative values) audio volume. Values are in dB. Does not work with audio passthrough.
  • -A or --aname: sets an audio track's name. Only available in .mp4 files. This is useful for the AppleTV, which otherwise gets confused when more than one track is in the same language and codec.

Multiple Audio Tracks

HandBrake can encode more than one audio track at a time, or the same track multiple times, and use different settings for each encode. It is common for AppleTV users to make one file that includes the main audio track from the source encoded once to AAC for playback on iPods, and also pass it through as a secondary track.

This is achieved by using the command:

-E faac,copy:ac3

If you do not specify which audio tracks to encode with the -a option, then HandBrake uses the first track in the source. When you include more than setting for an audio option, separated by a comma, it implicitly tells HandBrake: "The output should have two audio tracks." And without a source audio track specified, it will just use the first track for both.

You can also do complete settings for multiple tracks:

-a 1,1,2 -A "Main Audio","Downmixed Audio","Director's Commentary"-E copy:ac3,faac,ffaac -B auto,160,128 -R auto,auto,44100 -6 auto,dpl2,stereo 

There will be 3 audio tracks in the output, named "Main Audio", "Downmixed Audio", and "Director's Commentary" in turn. The first 2 output tracks will be the first audio track from the source: once as AC3 passed-through untouched, once as faac AAC-LC with a bitrate of 160 Kbps and a Dolby Pro Logic II mixdown. The third output track will use the second audio track from the source, encoded to ffaac AAC-LC at a bitrate of 128 Kbps, with a samplerate of 44.1kHz, and a stereo mixdown.

When you don't want to specify any particular setting for one of the tracks, use "auto" as a placeholder.

Picture Settings

  • -w or --width: Enter your desired output width here in pixels. The default is 720 for widescreen, 640 for fullscreen. If you do not specify a height as well, it will calculate one that will preserve the film's aspect ratio.
  • -l or --height: Enter your desired output height here in pixels. If you do not specify a width as well, it will calculate one that will preserve the film's aspect ratio. The default behavior is to use a height that preserves the film's aspect ratio, given the width. If you specify neither -w nor -l, by default your output will be approximately 720*400 for 1.78:1, 720*386 for 1.85:1, 720*304 for 2.35:1, and 640*480 for 1.33:1.
  • --crop: controls the cropping values. The cropping has to be in the form Top:Bottom:Left:Right, so to crop 60pixels from the top, 58 from the bottom, 2 from the left, and 6 from the right, use --crop 60:58:2:6 ... do note that this is different from cropping in some other programs, like MEncoder. If you don't enter this setting, HandBrake will automatically detect how many pixels to crop to remove black borders.
  • --loose-crop: always crop to a multiple of the modulus, removing at most # extra pixels (default: 15). For example, if autocrop detects 2:2:2:2 but the modulus is 16 and --loose-crop is set, HandBrake will crop 8:8:8:8 instead.
  • -Y or --maxHeight: sets an upper boundary on the height. Smaller values will be permitted, but anything larger will be scaled down and the width adjusted to match the film's aspect ratio. For example, the iPhone display is 480*320. While it can accept resolutions up to 640*480, some people prefer to go "dot-by-dot" and encode exactly the number of pixels the device can display, to save space or increase bits per pixel. If you just use -w 480, then with 4:3 content, HandBrake will encode to dimensions of 480*360 (too tall!). If you just use -l 320, then with 16:9 content, HandBrake will encode to dimensions of 570*320 (too wide!). But if you use -w 480 -Y 320, HandBrake will encode to dimensions of 416*320 for 4:3 content and 480*272 for 16:9 content (just right!).
  • -X or --maxWidth: sets an upper boundary on the width. Smaller values will be permitted, but anything larger will be scaled down and the height adjusted to match the film's aspect ratio.
  • --strict-anamorphic: enables anamorphic encoding. Uses dimensions that divide cleanly by 2 and disables any scaling.
  • --loose-anamorphic: enables anamorphic encoding. Ensures dimensions that divide cleanly by the modulus (default: 16), scaling the video if necessary.
  • --display-width: set the display width in custom anamorphic mode. The width will be scaled to this value at playback, regardless of the storage width.
  • --keep-display-aspect: in custom anamorphic mode, automatically preserve the source's display aspect.
  • --pixel-aspect: in custom anamorphic mode, set the pixel aspect ratio (PAR). Mutually exclusive with --display-width, which overrides --pixel-aspect.
  • --modulus: set the number by which storage dimensions should divide cleanly (default: 16). Affects all modes except strict anamorphic (which always uses a modulus of 2).
  • -M or --color-matrix: tells video players to use either Bt.601 or Bt.709 color to display the encoded output, with the required option of 601 or 709. Only effective with .mp4 files and/or x264 video. Bt.601 is what standard definition video like DVDs is supposed to use, and Bt.709 is supposed to be for high definition, so that's what HandBrake signals by default if you do not include this setting.

Filters

  • -d or --deinterlace: turns on deinterlacing filtering. It accepts parameters in the form --deinterlace="1:-1:1". The first parameter controls yadif and ffmpeg. "-1" means ffmpeg, HandBrake's fast, quick'n'dirty, traditional deinterlacer. "0" means yadif with 1-pass and spatial deinterlacing. "2" means yadif with 1-pass without spatial deinterlacing. "1" means yadif with 2-pass and spatial deinterlacing. The second parameter is the field dominance. "-1" means "assume top field first" and it should generally be left that way. The third parameter controls mcdeint, which is currently broken, so leave it set to "-1". There are also short names for commonly used parameters: "fast" is --deinterlacer="-1", "slow" is --deinterlace="2", and "slower" is --deinterlace="0". So you can also just do: --deinterlace="slow".
  • -5 or --decomb: selective deinterlacer -- it only deinterlaces frames that show visible interlacing artifacts. Much more information on decomb is available, but using it with its default options should work out well most of the time.
  • -9 or --detelecine: stateless inverse telecine (the pullup filter from MPlayer). When 24fps content is hard-telecined to 30fps by interpolating extra, interlaced fields, detelecine will restore the video to progressive. Bewarned that when used with a constant frame rate, HandBrake will drop or dupe frames as necessary to reach that constant rate. You can avoid this by not specifying a video framerate. By default, HandBrake will use the "Same as source" FPS, which permits a variable frame rate.
  • -8 or --denoise: high quality temporal and spatial denoising. Denoising softens the image (removing detail) but can significantly reduce bitrate. The parameters, in order, control filter strength for spatial luma, spatial chroma, temporal luma, and temporal chroma. Take guidance from the MacGui. You can also use some short names to commonly used parameters. A good "weak" setting for general use is --denoise="2:1:2:3", a good "medium" strength setting that will leave minor visual artifacts is --denoise="3:2:2:3", and for simple animation, consider "strong" settings of --denoise="7:7:5:5". You can just type them in like that: --denoise="weak". The default setting is the same as in MPlayer: 4:3:6:4.5.
  • -7 or --deblock: pp7, a post processing filter from MPlayer, removes blocks from video. You're probably best off using its defaults and not specifying parameters. If you do, know that the default is 5, 1 is very little deblocking, and by 10 things get quite blurry.
  • --rotate: A filter to rotate the video by a number of axes. (Default 3)
  • -g or -grayscale: lets HandBrake know the movie is black and white, so it doesn't bother keeping track of color information. This can reduce green tinge or rainbow shimmering in black and white encodes. It takes no options.

Subtitle Options

  • -s or --subtitle: selects a subtitle track to use. Subtitles are selected by number: the first track is 1, the second is 2, etc. Multiple subtitles tracks are separated by commas. A special subtitle track named 'scan' will add a Foreign Audio Search pass that attempts to detect and select the track which contains subtitles for foreign audio segments (if any) matching the language of the first audio track or the language defined via --native-language. Best used in conjunction with --subtitle-forced.
  • -F or --subtitle-forced: only subtitles that have the forced flag set will be displayed for the selected subtitle tracks. Multiple subtitles tracks are separated by commas. Works with DVD VobSub? subtitles from DVD, MKV and MP4 sources. The values are indexes into the subtitle list defined via --subtitle, so --subtitle scan,3,2,1 --subtitle-forced 2,4 will set the forced option for the source subtitle tracks 3 and 1.
  • --subtitle-burn: burn the selected subtitles into the video track. Only one subtitle track can be burned-in. Only works with DVD VobSub? subtitles (from DVD, MP4 and MKV sources) and ASS/SSA subtitles (from MKV sources). The values is an index into the subtitle list defined via --subtitle, so --subtitle scan,3,2,1 --subtitle-burn 3 will burn-in the source subtitle track 2.
  • --subtitle-default: flag the selected subtitle as the default subtitle to be displayed during playback. The values is an index into the subtitle list defined via --subtitle, so --subtitle scan,3,2,1 --subtitle-default 1 will display the foreign audio segment track ('scan') by default.
  • -N or --native-language: follow this flag with a language code (eng, fre, spa, dut, et cetera) and it will use that language's subtitles if the selected or default audio language differs from your native language. This way, you don't have to run a -t 0 scan first to see what subtitles are in what languages. Just tell HandBrake what language you want, and it will find the correct track if available. For example, if you select "fre" and you encode a title with French audio, you will not get any subtitles, however if you encode the same title with English audio you will get the French subtitles enabled.
  • --native-dub: when used in conjunction with --native-language it will change the audio language to match the selected language. If no match is found, the first matching subtitle will be used.
  • --srt-file: define a set of SRT file paths which HandBrake should import. Multiple file paths are separated by commas.
  • --srt-codeset: tell HandBrake which character set each defined SRT file uses. Multiple codesets are separated by commas.
  • --srt-offset: offset the the time where the SRT file starts in the encode (in milliseconds). This can be positive or negative. Multiple offsets are separated by commas.
  • --srt-lang: an iso669-2 language code (e.g fra, eng, spa) can be specified for each SRT track which you have added (default: und). Multiple language codes are separated by commas.
  • --srt-default: set the default SRT track to be displayed upon playback (default: first SRT file).

Scripting and Automation

Where's the queue?

In the CLI, there is no queue. You can use a semi-colon:

HandBrakeCLI -i VIDEO_TS -o movie1.mp4 -t 1 ; HandBrakeCLI -i VIDEO_TS -o movie2.mp4 -t 2

Or, you can write a simple shell script.

Users

There are a good number of examples of scripts on our forums. Check out the CLI sections to see what other users have done.

Script Writers

HandBrakeCLI is designed as a test tool, and as such, is not optimised for anything more than moderate scripting. Things you should note:

HandBrake has 2 exit codes:

0 = HandBrake exited cleanly. This does NOT indicate a complete or error-free encode. It only indicates that HandBrake has exited cleanly and that the file was properly muxed. CTRL-C will cause HandBrake to exit cleanly.

1 = HandBrake encountered a crash condition it could not recover from.

If you want to monitor HandBrake's process, you should monitor the standard pipes.

  • Standard Output: Contains encode progress information.
  • Standard Error: Contains all the logging data.
  • The CLI Forum is full of good advise and scripts that people have created.
Last modified 21 months ago Last modified on 11/24/14 16:07:08