This guide is currently being overhauled. Sorry if it’s lacking something.

Contents

1. Introduction
   1. Mac OS X
   2. Linux
2. Preperations
3. Basic Usage

Introduction

TODO

Preperations

To make things go as smoothly as possible throughout the remainder of the guide we first need to make sure we have a relatively level field. If you understand the repercussions you can change the paths or skip steps as you see fit, if not follow along as closely as possible.

When you see text like this:

cd ~
echo "Hello World."

you are supposed to type it into the terminal and press return after each line.

Mac OS X

1. Make sure you have 10.3.9 (or newer)
   1. click the Apple icon in the upper left
   2. click “About This Mac”
2. Install the HandBrakeCLI
   1. Download Mac OS X CLI
   2. Double click the downloaded dmg
   3. Drag the HandBrakeCLI file to your Applications directory

Linux

TODO

Basic Usage

First, let’s make sure everybody is ready to start. Open Terminal (it’s in Applications => Utilities => Terminal) and type:

cd /Applications

Now let’s start with the most basic usage:

./HandBrakeCLI --help

HandBrakeCLI --help list all of the available options, their meanings and how to use them. At first it might look confusing but don’t let it slow you down, just ignore all that mumbojumbo. You’ll start to understand how to decipher all that helpful information after you’ve looked at how the commands are setup.

You might not have noticed it if your terminal window is too small, but at the very top of the built-in help it says Syntax: HandBrakeCLI [options] -i <device> -o <file>. This line tells you exactly how to construct your HandBrake command. For example, HandBrakeCLI --help the --help replaces the [options] in the syntax, however, --help is a special option so we don’t specify any -i input device or -o output file name.

If you’re comfortable with the command line or had used the previous version of this guide then, HandBrakeCLI --help is probably all the help you need to get started.

Now let’s move on to something that actually uses a DVD. Since chances are that we’ll all be using a different DVD to test with I’m going to use MY_DVD to represent a generic path, your specific path will be different. Go ahead and insert a DVD, when you see the DVD icon on your desktop you’re ready to go.

Mac users try this, in the terminal type:

./HandBrakeCLI --title 0 --input 

Make sure you put a space after the --input. Then drag and drop the DVD icon from your desktop onto the terminal window, you should see something like:

./HandBrakeCLI --title 0 --input /Volumes/MY_DVD

Linux users will need

TODO

In the previous command --title 0 instructs HandBrakeCLI to scan the DVD and display all kinds of technical information in the Terminal window. This information can be invaluable if you are unsure what exactly is on the DVD. For instance, you may want to add subtitles but are unsure which track contains the French subtitles you want, so ./HandBrakeCLI --title 0 --input /Volumes/MY_DVD will show you the full list of available subtitles and which track contains which language. It will look something like:

+ subtitle tracks:
  + 1, English (iso639-2: eng)
  + 2, Espanol (iso639-2: spa)
  + 3, Francais (iso639-2: fre)

So, now you know the French subtitles are in subtitle track 3 and you’re ready for your first encode.

./HandBrakeCLI --subtitle 3 --input /Volumes/MY_DVD --output ~/Desktop/My_DVD.m4v

And that’s all there is to it. You can see in the [options] section we only have --subtitle 3 this time. For every option that you don’t set HandBrakeCLI automatically inserts the “classic” default value. So the above command is equal to inserting a DVD, picking French subtitles, the Classic preset and clicking Start in the GUI.

If you now run

./HandBrakeCLI --help

and look in the ### Picture Settings sections you’ll see -s, --subtitle <number> and it will make perfect sense how that bit from the built-in help translates into direct use; you’ll also now know that our previous encoding command could have been more succinctly written as:

./HandBrakeCLI -s 1 -i /Volumes/MY_DVD -o ~/Desktop/My_DVD.m4v

I’ll continue using the long commands for clarity but you can feel free to start substituting the short commands as you learn them.

Now lets try to change the encoder to xvid:

./HandBrakeCLI --subtitle 1 --encoder xvid --input /Volumes/MY_DVD --output ~/Desktop/My_DVD.m4v

and now try to guess what the command would look like for using the x264 encoder instead of xvid. Of course, you guessed:

./HandBrakeCLI --subtitle 1 --encoder x264 --input /Volumes/MY_DVD --output ~/Desktop/My_DVD.m4v

Have another look at the built-in help, this time under the ### Video Options at the encoder settings and again you’ll now understand how that help info translates into usage. You can now probably peruse the help and guess correctly how to use nearly, if not all, the commands; and just to prove it to yourself try constructing commands that will:

1. use the the encoder of your choice but constrain the picture to 640×480
2. use the x264 video encoder, passthrough audio and deinterlacing

If you came with commands like:

./HandBrakeCLI --encoder xvid --width 640 --height 480 --input /Volumes/MY_DVD --output ~/Desktop/My_DVD.m4v

and

./HandBrakeCLI --encoder x264 --aencoder ac3 --deinterlace --input /Volumes/MY_DVD --output ~/Desktop/My_DVD.m4v

then you’re probably ready for something a little less basic. Check this command out:

./HandBrakeCLI --preset "Deux Six Quatre" --input /Volumes/MY_DVD --output ~/Desktop/MY_DVD

As you can probably guess it uses the Deux Six Quatre preset just like the GUI.

FIXME…the advanced usage. If not, don’t fret, try re-reading this section; and if that still doesn’t help mail me and let me know where you’re getting hung up and I’ll do my best to help you get untangled. Plus it’ll help me clear up parts of the guide so the next person can breeze right on to the next section.