HandBrake for Ruby
The intent of this library is to make it a bit easier to script HandBrake. You will still need to be familiar with HandBrake and HandBrakeCLI to make use of it.
handbrake.rb is distributed as a rubygem:
$ gem install handbrake
A brief sample:
require 'handbrake' hb = HandBrake::CLI.new(:bin_path => '/Applications/HandBrakeCLI', :trace => false) project = hb.input('/Volumes/Arcturan Megafreighter/DVDs/L') disc = project.scan disc.titles.number # => 1 disc.titles.main_feature? # => true disc.titles.duration # => "01:21:18" disc.titles.seconds # => 4878 disc.titles.chapters.size # => 23 disc.titles.chapters.seconds # => 208 project.title(1). preset('Normal'). output('/Users/rsutphin/Movies/project.m4v')
In additional detail:
Create a HandBrake::CLI instance
require 'handbrake' hb = HandBrake::CLI.new(:bin_path => handbrake_cli_path, :trace => true)
This object carries the path to the HandBrakeCLI bin and other library configuration options:
:bin_path: the path to the
HandBrakeCLIexecutable. The default is
'HandBrakeCLI'; i.e., by default it will be searched for on the normal executable path.
:trace: if true, all output from
HandBrakeCLIwill be echoed to the project's error stream.
You build up a command string by invoking a chain of methods starting
HandBrake::CLI instance. The methods are named following the
long form of the options for HandBrakeCLI. (The one exception to
this naming scheme is for options that contain a dash; in those cases,
an underscore must be substituted for the dash.)
E.g., the HandBrakeCLI documentation has this command:
$ HandBrakeCLI -i /Volumes/MyBook/VIDEO_TS -o /Volumes/MyBook/movie.m4v -v -P -m -E aac,ac3 -e x264 -q 0.65 -x ref=3:mixed-refs:bframes=6:b-pyramid=1:weightb=1:analyse=all:8x8dct=1:subme=7:me=umh :merange=24:filter=-2,-2:trellis=1:no-fast-pskip=1:no-dct-decimate=1:direct=auto
In handbrake.rb, you could build up this command like so:
vid_opts = 'ref=3:mixed-refs:bframes=6:b-pyramid=1:weightb=1:analyse=all:8x8dct=1:subme=7:me=umh:merange=24:filter=-2,-2:trellis=1:no-fast-pskip=1:no-dct-decimate=1:direct=auto' HandBrake::CLI.new.input('/Volumes/MyBook/VIDEO_TS').verbose. loosePixelratio.markers.aencoder('aac,ac3').encoder('x264'). quality('0.65').x264opts(vid_opts). output('/Volumes/MyBook/movie.m4v')
output option has to go last; see the next section for more details.
While most of the methods you call to build up a handbrake command can come in any order, a few must come last and have particular return values:
output: triggers a transcode using all the options set up to this point. No return value.
scan: triggers a title scan and returns either a (for all titles) or a (for a single title).
update: returns true or false depending on whether the version of HandBrakeCLI in use is up to date.
preset_list: returns a hash containing all the known presets and their options. The structure is
presets[category][name] => args.
Reusing a configuration chain
At any point before invoking one of the execution methods (listed in the previous section), you can save off the chain and continue it along different paths. E.g.:
project = HandBrake::CLI.new.input('VIDEO_TS') # iPhone project.preset('iPhone & iPod Touch').output('project-phone.m4v') # TV project.preset('High Profile').output('project-tv.m4v')
To put it more technically, each intermediate configuration step returns an independent copy of the configuration chain.
By default, the
output execution method behaves just like invoking
handbrake.rb also supports a couple of
additional behaviors, including overwrite detection and atomic output
file creation. See for more details.
- API docs: last release or in development
- Continuous integration (note that right now this link only works when there has been a recent build)
- Versioning policy: Semantic versioning
- Bugs and feature requests
Patches with tests will be happily reviewed. Please submit a pull request from a topic branch in your own fork on GitHub.
handbrake.rb Copyright (C) 2011 Rhett Sutphin. This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.