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 from a
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 HandBrakeCLI directly.
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.