Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

hbencode 1.1

Encodes video files in bulk for playback on an iPhone or iPod Touch (non-retina), optimizing for space.

I have used this program for several years to encode anime, movies, and TV shows for my iPhone so that I can watch them while on the bus, on the plane, or otherwise stuck waiting for long periods of time.


  • Operating System:
    • Mac OS X 10.5.8 (Leopard) or later
    • Linux — probably works, but untested
    • Windows — probably works, but untested
  • Python 2.5.1 or later
    • Already included on Mac OS X.
  • HandBrakeCLI 0.9.5 or later
    • Tested with:
      • HandBrakeCLI svn3563 (2010100201) - Reference implementation
      • HandBrakeCLI svn3567 (2010100301)


Copy to somewhere in your system path.


Encode a file using: INPUT_FILE.avi

Encode all files in the current directory using: *.avi

This will automagically encode the video(s) for iPhone / iPod Touch and save it to your preferred output directory.

Configuration and Options

When run for the first time:

  1. hbencode will try to locate the HandBrakeCLI program in your current PATH.
    • If it cannot be found, you will be prompted to input its location manually.
  2. hbencode will prompt you for a directory to save all output files.

Automatic Mode

If the --auto option is specified, all other configuration options are detected automatically.

The particular heuristic for how these options are computed may change in subsequent versions of hbencode without warning. At present the current heuristic is:

  • Use an output aspect ratio which is as close to the input aspect ratio as possible.
  • Use constant quality encoding.
  • Use the first Japanese audio track if there is one, or the first one otherwise.
  • Use the first Japanese subtitle track if there is one, or the first one otherwise.
  • If there is a subtitle track, burn it in to the video.

Aspect Ratio

The output width, height, and bitrate of the encoded video are determined by the aspect ratio of the input file. By default this is assumed to be --w1 (16:9, widescreen). This be be overridden with other options such as --tv (4:3, traditional TV).

You can get a complete list of supported aspect ratios with the -r list option. Then use that ratio with -r RATIO_NAME

In the future, hbencode will try to automatically guess the aspect ratio of the input file by default.

Increasing Encode Quality

By default, encoding parameters optimize for constant (and small) file size. If you prefer to optimize for constant quality, use the -C option.

Or if you want to multiply the automatically determined bitrate to increase quality (for music videos and similar), you can use the -q 1.5 option to multiply the bitrate by 1.5x (or any value).

Finally, you can use one of the higher quality aspect ratio variants. For example, if you normally use -r w1 (the default), you can also use -r w1-hq. See the "Aspect Ratio" section for more details.


Subtitles in the input file are detected and included in the output file by default. If you want to select a subtitle track other than the first one, use -s SUBTITLE_TRACK_NUMBER.

Subtitles are normally converted to plain text and stored as a native subtitle track for the iPhone. SSA subtitles (common in anime) can alternatively be burned in to the video track using the -B option. Subtitle burn-in is the most accurate way to display SSA subtitles, at the cost of not being able to turn them off during playback.

Other Options

You can use -x "OPTION_1 OPTION_2 ... OPTION_N" to specify custom options to the underlying HandBrakeCLI program.

You can get a complete list of supported options by running hbencode with no parameters:


If you run into problems or have questions, feel free to file a bug or contact me.


Information about earlier releases can be found in the CHANGELOG.


This software is licensed under the MIT License.


Encodes video files in bulk for playback on an iPhone or iPod Touch.








No packages published