HandBrake

-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 enabling -v turns on level 1 logging. 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.

-C or --cpu

while the program can discern how many CPUs your computer has on its own, there are some cases when you might want to force a specific number. This flag has to be followed by a number.

-Z or --preset

enter a preset name to use.

-z or --preset-list

displays all the presets' names and what CLI options they use.

-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.

-L or --longest

automagically selects the longest title on the DVD, which is probably the main feature you want to encode. Mirrors default behavior in the MacGui.

-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.

-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, .mkv, .avi, or .ogm, it will be encoded with that file format container.

-f or --format

forces a particular container file format. Your choices are avi, mp4, mkv, and ogm. If this is omitted, it will try to figure out the format from the output filename.

-m or --markers

only available with the .mp4 and .mkv file formats, this setting includes a chapter index in the video, based on the chapter times used on the DVD. 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 numbers. These make it incompatible with some devices (like the iPod and the PS3) -- 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, HandBrake will crash.

-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 require before they'll allow H.264 video to sync.

-e or --encoder

selects the video encoder. The default is ffmpeg (similar to DivX). The other options are xvid and x264.

-x or --x264opts

permits you to pass through advanced x264 options thot e encoder.

-q or --quality

controls the video quality, which ranges from 0.0 to 1.0. Think of it as a percentage, but don't expect 12% to be the same as 11% +1 (it doesn't work linearly) and don't expect 70% in ffmpeg to be the same as 70% in x264. Each encoder uses a different quality scale. Do not use 1.0, as 100% quality will be quite a bit larger than the source. If you set a quality, it means you cannot set a target size or video bitrate, and there is no way to predict what the output size will be.

-Q or --cqp

when paired with a quality using -q, this flag forces the use of a constant quantizer instead of using the default quality mode for x264, constant rate factor. This means bigger files that won't look much if any better.

-S or --size

allows you to set an output file size in megabytes. Do not use this if you wish to set a particular bitrate or constant quality. If you set a size larger than 4000MB, make sure to enable the --largeFileSize option.

-b or --vb

allows you to set an average output video bitrate in kilobits per second. Do not use this if you wish to set a particular file size or constant quality. 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 or target file size (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 by adding the options: "ref=1:subme=1: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 29.97 for NTSC and 25fps for PAL. (Unless it's an NTSC disc which seems to be mostly progressive -- then HandBrake will use 23.976.)

-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 faac, lame, vorbis, and ac3. Faac encodes AAC, and lame encodes MP3. The defaults are AAC for .mp4, MP3 for .avi, Vorbis for .ogm, and AC3 for .mkv. You can pass-through AC3 (the original Dolby Digital audio from the DVD) when using the .avi, .mkv, and .mp4 file formats. If you pass through AC3 to an .mp4, it will only be recognized by the AppleTV, Perian, and the VLC, and then only when you end the file with the suffix .m4v.

-B or --ab

allows you to set an average audio bitrate in kilobits per second. The default is 160.

-6 or --mixdown

This controls downmixing of the audio. The options are none, mono, stereo, dpl1, dpl2, or 6ch. For example, you could downmix a stereo source to mono, or a 5.1 source to 2-channel Dolby ProLogic 2. Assuming you have not set AC3 pass-through as the audio encoder, the default behavior is for HandBrake to downmix Dolby Digital 5.1 to Dolby ProLogic 2. When encoding audio to AAC, you may use --mixdown 6ch to preserve all of the surround channels in the source audio, creating a 6-channel AAC from a 6-channel (5.1) AC3.

-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 (off) to 4.0 (blow out your speakers from the background sound of elevator doors closing). 1.5 to 2.5 is a useful range.

-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.

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 aac,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 ac3,aac,aac -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 will be the first audio track from the source: once as AC3 passed-through untouched, once as AAC with a bitrate of 160 and a Dolby Pro Logic II mixdown. The third track will use the second audio track from the source, encoded to AAC at a bitrate of 128, 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.

-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.

-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.

-p or --pixelratio

this enables anamorphic encoding (the "p" is for PAR, pixel aspect ratio). It takes no options.

-P or --loosePixelratio

this enables loose anamorphic encoding. Unlike regular old --pixelratio, it will use dimensions that divide cleanly by 16, and allow you to scale down the stored frame by giving HandBrake a --width. It takes an optional argument, that makes it so dimensions divide cleanly by some number other than 16 (8 is popular). That is done like so: --loosePixelratio=8. It also handles ITU pixel aspects, which are applied automatically when the source width after cropping is less than 708.

-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.

-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 using 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".

-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.

-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.

-s or --subtitle

selects a subtitle track to use. Subtitles are selected by number: the first track is 1, the second is 2, etc. HandBrake "hard burns" subtitles onto the video. If you enable them, they will always be visible. You cannot turn them on or off like with a DVD.

-U or --subtitle-scan

This option lets HandBrake scan and detect subtitles that should be enabled. Sometimes, movies will be primarily in one language, but with short sections in foreign tongues, during which subtitles appear in the primary language. Different DVDs do that in different ways. Some only have one main-language subtitle track, that covers the whole film, and the DVD only forces them on in foreign language segments (see --subtitle-forced). Other DVDs will have a separate subtitle track in the primary language, that only has content for the short foreign-language segments. This feature handles those with aplomb.

-F or --subtitle-forced

This option may be used in two ways. When used with --subtitle-scan it will modify the subtitle scan to automatically select subtitle tracks that contain forced subtitles, and then display just the forced subtitles in that track. When used on its own in conjunction with --subtitle only subtitles that have the forced flag set will be displayed for the selected subtitle track.

-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.

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.

• I learned how to use HandBrakeCLI (back when it was called HBTest) thanks to Caenim's guide.
• This little shell script to automate batch (queued) encoding seems nice, though I've never used it myself.
• PineAppleCLI is a preset-oriented bash wrapper
• HBencoder is another bash wrapper