handbrake 0.0.1

data/handbrake.gemspec

@@ -0,0 +1,25 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "handbrake/version"
+
+Gem::Specification.new do |s|
+  s.name        = "handbrake"
+  s.version     = HandBrake::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Rhett Sutphin"]
+  s.email       = ["rhett@detailedbalance.net"]
+  s.homepage    = "https://github.com/rsutphin/handbrake-ruby"
+  s.summary     = %q{A ruby wrapper for HandBrakeCLI}
+  s.description = %q{A lightweight literate ruby wrapper for HandBrakeCLI, the command-line interface for the HandBrake video transcoder.}
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_dependency 'rubytree', '~> 0.8.1'
+
+  s.add_development_dependency 'rspec', '~> 2.5'
+  s.add_development_dependency 'rake', '~> 0.9.0'
+  s.add_development_dependency 'yard', '~> 0.7.0'
+end

data/hrirb

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+
+######
+# Run irb for interactive fiddling with this library from the source
+
+require 'irb'
+
+$LOAD_PATH << File.expand_path('../lib', __FILE__)
+require 'handbrake'
+
+$cli = HandBrake::CLI.new(:trace => true)
+
+puts "`$cli` is a HandBrake::CLI instance with tracing on"
+
+IRB.start(__FILE__)

data/lib/handbrake/cli.rb

@@ -0,0 +1,206 @@
+require 'handbrake'
+
+module HandBrake
+  ##
+  # The main entry point for this API. See {file:README.md} for usage
+  # examples.
+  class CLI
+    ##
+    # The full path (including filename) to the HandBrakeCLI
+    # executable to use.
+    #
+    # @return [String]
+    attr_accessor :bin_path
+
+    ##
+    # Set whether trace is enabled.
+    #
+    # @return [Boolean]
+    attr_writer :trace
+
+    ##
+    # @param [Hash] options
+    # @option options [String] :bin_path ('HandBrakeCLI') the full
+    #   path to the executable to use
+    # @option options [Boolean] :trace (false) whether {#trace?} is
+    #   enabled
+    # @option options [#run] :runner (a PopenRunner instance) the class
+    #   encapsulating the execution method for HandBrakeCLI. You
+    #   shouldn't usually need to replace this.
+    def initialize(options={})
+      @bin_path = options[:bin_path] || 'HandBrakeCLI'
+      @trace = options[:trace].nil? ? false : options[:trace]
+      @runner = options[:runner] || PopenRunner.new(self)
+
+      @args = []
+    end
+
+    ##
+    # Ensures that `#dup` produces a separate copy.
+    #
+    # @return [void]
+    def initialize_copy(original)
+      @args = original.instance_eval { @args }.collect { |bit| bit.dup }
+    end
+
+    ##
+    # Is trace enabled?
+    #
+    # If it is enabled, all output from HandBrakeCLI will be streamed
+    # to standard error. If not, the output from HandBrakeCLI will
+    # only be printed if there is a detectable error.
+    #
+    # @return [Boolean]
+    def trace?
+      @trace
+    end
+
+    ##
+    # Performs a conversion. This method immediately begins the
+    # transcoding process; set all other options first.
+    #
+    # @return [void]
+    def output(filename)
+      run('--output', filename)
+    end
+
+    ##
+    # Performs a title scan. Unlike HandBrakeCLI, if you do not
+    # specify a title, this method will return information for all
+    # titles. (HandBrakeCLI defaults to only returning information for
+    # title 1.)
+    #
+    # @return [Titles]
+    def scan
+      if arguments.include?('--title')
+        result = run('--scan')
+        Titles.from_output(result.output)
+      else
+        title(0).scan
+      end
+    end
+
+    ##
+    # Checks to see if the `HandBrakeCLI` instance designated by
+    # {#bin_path} is the current version.
+    #
+    # Note that `HandBrakeCLI` will always report that it is up to
+    # date if it can't connect to the update server, so this is not
+    # terribly reliable.
+    #
+    # @return [Boolean]
+    def update
+      result = run('--update')
+      result.output =~ /Your version of HandBrake is up to date./i
+    end
+
+    ##
+    # Returns a structure describing the presets that the current
+    # HandBrake install knows about. The structure is a two-level
+    # hash. The keys in the first level are the preset categories. The
+    # keys in the second level are the preset names and the values are
+    # string representations of the arguments for that preset.
+    #
+    # (This method is included for completeness only. This library does
+    # not provide a mechanism to translate the argument lists returned
+    # here into the configuration for a {HandBrake::CLI} instance.)
+    #
+    # @return [Hash]
+    def preset_list
+      result = run('--preset-list')
+      result.output.scan(%r{\< (.*?)\n(.*?)\>}m).inject({}) { |h1, (cat, block)|
+        h1[cat.strip] = block.scan(/\+(.*?):(.*?)\n/).inject({}) { |h2, (name, args)|
+          h2[name.strip] = args.strip
+          h2
+        }
+        h1
+      }
+    end
+
+    ##
+    # @private
+    def arguments
+      @args.collect { |req, *rest| ["--#{req.to_s.gsub('_', '-')}", *rest] }.flatten
+    end
+
+    private
+
+    def run(*more_args)
+      @runner.run(arguments.push(*more_args)).tap do |result|
+        unless result.status == 0
+          unless trace?
+            $stderr.puts result.output
+          end
+          raise "HandBrakeCLI execution failed (#{result.status.inspect})"
+        end
+      end
+    end
+
+    ##
+    # Copies this CLI instance and appends another command line switch
+    # plus optional arguments.
+    #
+    # This method does not do any validation of the switch name; if
+    # you use an invalid one, HandBrakeCLI will fail when it is
+    # ultimately invoked.
+    #
+    # @return [CLI]
+    def method_missing(name, *args)
+      copy = self.dup
+      copy.instance_eval { @args << [name, *(args.collect { |a| a.to_s })] }
+      copy
+    end
+
+    ##
+    # @private
+    # The default runner. Uses `IO.popen` to spawn
+    # HandBrakeCLI. General use of this library does not require
+    # monkeying with this class.
+    class PopenRunner
+      ##
+      # @param [CLI] cli_instance the {CLI} instance whose configuration to share
+      def initialize(cli_instance)
+        @cli = cli_instance
+      end
+
+      # Some notes on popen options
+      # - IO.popen on 1.9.2 is much more elegant than on 1.8.7
+      #   (it lets you pass spawn args directly instead of using a
+      #   subshell, so you can more cleanly pass args to the
+      #   executable and redirect streams)
+      # - Open3.popen3 does not let you get the status
+      # - Open4.popen4 does not seem to stream the output and error
+      #   and hangs when the child process fills some buffer
+      # Hence, this implementation:
+
+      ##
+      # @param [Array<String>] arguments the arguments to pass to HandBrakeCLI
+      # @return [RunnerResult]
+      def run(arguments)
+        output = ''
+
+        cmd = "'" + arguments.unshift(@cli.bin_path).join("' '") + "' 2>&1"
+
+        $stderr.puts "Spawning HandBrakeCLI using #{cmd.inspect}" if @cli.trace?
+        IO.popen(cmd) do |io|
+          while line = io.gets
+            output << line
+            $stderr.puts(line.chomp) if @cli.trace?
+          end
+        end
+        RunnerResult.new(output, $?)
+      end
+    end
+
+    ##
+    # @private
+    # The raw result of one execution of HandBrakeCLI.
+    #
+    # General use of the library will not require use of this class.
+    #
+    # @attr [String] output a string containing the combined output
+    #   and error streams from the run
+    # @attr [#to_i] status the process exit status for the run
+    RunnerResult = Struct.new(:output, :status)
+  end
+end

data/lib/handbrake/titles.rb

@@ -0,0 +1,181 @@
+require 'tree'
+
+require 'handbrake'
+
+module HandBrake
+  ##
+  # And enhanced `Hash` which can self-parse the output from
+  # HandBrakeCLI's `--scan` mode. The keys of this hash will be title
+  # numbers and the values will be {Title} instances.
+  #
+  # @see Title
+  # @see Chapter
+  class Titles < Hash
+    ##
+    # The HandBrakeCLI scan output from which this instance was
+    # parsed, if available.
+    #
+    # @return [String,nil]
+    attr_reader :raw_output
+
+    ##
+    # A tree representing the indented output at the end of the
+    # HandBrakeCLI scan output, if available.
+    #
+    # @return [String,nil]
+    attr_reader :raw_tree
+
+    ##
+    # Builds a new {Titles} instance from the output of `HandBrakeCLI
+    # --scan`.
+    #
+    # @param [String] output the raw contents from the scan
+    # @return [Titles] a new, completely initialized title catalog
+    def self.from_output(output)
+      self.new.tap do |titles|
+        titles.raw_output = output
+        titles.raw_tree.children.
+          collect { |title_node| Title.from_tree(title_node) }.
+          each { |title| titles[title.number] = title }
+      end
+    end
+
+    ##
+    # Initializes the {#raw_output} and {#raw_tree} attributes from
+    # the given HandBrakeCLI output. Does not modify the contents of
+    # the hash.
+    #
+    # @param [String] output raw contents from a HandBrakeCLI title
+    #   scan
+    # @return [void]
+    def raw_output=(output)
+      @raw_output = output
+      @raw_tree = extract_tree
+    end
+
+    private
+
+    def extract_tree
+      split_blocks(
+        raw_output.split("\n").grep(/^\s*\+/), ''
+      ).inject(Tree::TreeNode.new('__root__')) do |root, block|
+        root << read_node(block, '')
+        root
+      end
+    end
+
+    def split_blocks(lines, indent_level)
+      lines.inject([]) do |blocks, line|
+        blocks << [] if line =~ /^#{indent_level}\+/
+
+        blocks.last << line
+        blocks
+      end
+    end
+
+    def read_node(node_lines, indent_level)
+      next_indent = indent_level + '  '
+      split_blocks(
+        node_lines[1..-1], next_indent
+      ).inject(Tree::TreeNode.new(node_lines.first[(2 + indent_level.size)..-1])) do |node, block|
+        node << read_node(block, next_indent)
+        node
+      end
+    end
+  end
+
+  ##
+  # Provides a {#seconds} method for an object which has a `duration`
+  # property whose value is a string of the format "hh:mm:ss"
+  module DurationAsSeconds
+    ##
+    # The number of seconds described by the duration. E.g., if the
+    # duration were `"1:02:42"`, this method would return `3762`.
+    #
+    # @return [Fixnum]
+    def seconds
+      @seconds ||= duration.split(':').collect(&:to_i).reverse.
+        inject([1, 0]) { |(m, sum), i| [m * 60, sum + i * m] }.last
+    end
+  end
+
+  ##
+  # Metadata about a single DVD title.
+  class Title
+    include DurationAsSeconds
+
+    ##
+    # @return [Fixnum] The title number of this title (a positive integer).
+    attr_accessor :number
+
+    ##
+    # @return [String] The duration of the title in the format
+    #   "hh:mm:ss"
+    attr_accessor :duration
+
+    ##
+    # @return [Array<Chapter>] The chapters into which the title is
+    #   divided.
+    attr_writer :chapters
+
+    ##
+    # @return [Boolean] Whether HandBrake considers this title the
+    #   "main feature".
+    attr_writer :main_feature
+
+    ##
+    # Creates a new instance from the given scan subtree.
+    #
+    # @see Titles.from_output
+    # @param [Tree::TreeNode] title_node
+    # @return [Title] a new, fully initialized instance
+    def self.from_tree(title_node)
+      self.new.tap do |title|
+        title.number = title_node.name.scan(/title (\d+)/).first.first.to_i
+        title.duration = title_node.children.
+          detect { |c| c.name =~ /duration/ }.name.
+          scan(/duration: (\d\d:\d\d:\d\d)/).first.first
+        title.chapters = title_node['chapters:'].children.
+          collect { |ch_node| Chapter.from_tree(ch_node) }
+        title.main_feature = title_node.children.detect { |c| c.name =~ /Main Feature/ }
+      end
+    end
+
+    ##
+    # @return [Boolean] Whether HandBrake considers this title the
+    #   "main feature".
+    def main_feature?
+      @main_feature
+    end
+
+    ##
+    # @return [Array<Chapter>] The chapters into which the title is
+    #   divided.
+    def chapters
+      @chapters ||= []
+    end
+  end
+
+  ##
+  # The metadata about a single chapter in a title of a DVD.
+  class Chapter
+    include DurationAsSeconds
+
+    ##
+    # @return [String] The duration of the title in the format
+    #   "hh:mm:ss"
+    attr_accessor :duration
+
+    ##
+    # Creates a new instance from the given title subtree.
+    #
+    # @see Title.from_tree
+    # @param [Tree::TreeNode] chapter_node
+    # @return [Chapter] a new, fully initialized instance
+    def self.from_tree(chapter_node)
+      self.new.tap do |ch|
+        ch.duration = chapter_node.name.scan(/duration (\d\d:\d\d:\d\d)/).first.first
+      end
+    end
+  end
+end

data/lib/handbrake/version.rb

@@ -0,0 +1,5 @@
+module HandBrake
+  ##
+  # The current version
+  VERSION = "0.0.1"
+end

data/lib/handbrake.rb

@@ -0,0 +1,11 @@
+##
+# @see file:README.md
+# @see CLI The main class
+module HandBrake
+  autoload :VERSION, 'handbrake/version'
+
+  autoload :CLI,     'handbrake/cli'
+  autoload :Titles,  'handbrake/titles'
+  autoload :Title,   'handbrake/titles'
+  autoload :Chapter, 'handbrake/titles'
+end

data/spec/handbrake/cli_spec.rb

@@ -0,0 +1,162 @@
+require File.expand_path('../../spec_helper.rb', __FILE__)
+
+module HandBrake
+  describe CLI do
+    describe "#bin_path" do
+      it "looks on the path by default" do
+        HandBrake::CLI.new.bin_path.should == "HandBrakeCLI"
+      end
+
+      it "is the specified value when specified" do
+        HandBrake::CLI.new(:bin_path => '/Applications/HandBrakeCLI').bin_path.
+          should == '/Applications/HandBrakeCLI'
+      end
+    end
+
+    describe "#trace?" do
+      it "is false by default" do
+        HandBrake::CLI.new.trace?.should == false
+      end
+
+      it "can be set" do
+        HandBrake::CLI.new(:trace => true).trace?.should == true
+      end
+    end
+
+    describe "building a command" do
+      let(:cli) { HandBrake::CLI.new }
+
+      it "works for a parameter without an argument" do
+        cli.markers.arguments.should == %w(--markers)
+      end
+
+      it "works for a parameter with an argument" do
+        cli.quality('0.8').arguments.should == %w(--quality 0.8)
+      end
+
+      it "works with a parameter with a dashed name" do
+        cli.native_language('eng').arguments.should == %w(--native-language eng)
+      end
+
+      it "can chain parameters" do
+        cli.previews('15').format('avi').large_file.title('3').arguments.should ==
+          %w(--previews 15 --format avi --large-file --title 3)
+      end
+
+      it "stringifies arguments" do
+        cli.previews(18).arguments.should == %w(--previews 18)
+      end
+
+      it "can produce separate forks of the command" do
+        base = cli.input('/foo/bar')
+        base.quality('0.53').format('avi').arguments.should ==
+          %w(--input /foo/bar --quality 0.53 --format avi)
+        base.title('6').ipod_atom.arguments.should ==
+          %w(--input /foo/bar --title 6 --ipod-atom)
+      end
+    end
+
+    describe 'execution' do
+      let(:cli) { HandBrake::CLI.new(:runner => runner) }
+      let(:runner) { HandBrake::Spec::StaticRunner.new }
+
+      describe 'default runner' do
+        let(:cli) { HandBrake::CLI.new }
+
+        before do
+          `which HandBrakeCLI`
+          unless $? == 0
+            pending 'HandBrakeCLI is not on the path'
+          end
+        end
+
+        it 'works' do
+          lambda { cli.update }.should_not raise_error
+        end
+      end
+
+      describe '#output' do
+        it 'uses the --output argument' do
+          cli.output('/foo/bar.m4v')
+          runner.actual_arguments.should == %w(--output /foo/bar.m4v)
+        end
+      end
+
+      describe '#scan' do
+        let(:sample_scan) { File.read(File.expand_path('../sample-titles-scan.err', __FILE__)) }
+
+        before do
+          runner.output = sample_scan
+        end
+
+        it 'uses the --scan argument' do
+          cli.scan
+          runner.actual_arguments.last.should == '--scan'
+        end
+
+        it 'defaults to scanning all titles' do
+          cli.scan
+          runner.actual_arguments.should == %w(--title 0 --scan)
+        end
+
+        it 'only scans the specified title if one is specified' do
+          cli.title(3).scan
+          runner.actual_arguments.should == %w(--title 3 --scan)
+        end
+
+        it 'does not permanently modify the argument list when using the default title setting' do
+          cli.scan
+          cli.arguments.should_not include('--title')
+        end
+
+        it 'returns titles from the output' do
+          # The details for this are tested in titles_spec
+          cli.scan.size.should == 5
+        end
+      end
+
+      describe '#update' do
+        it 'uses the --update argument' do
+          cli.update
+          runner.actual_arguments.should == %w(--update)
+        end
+
+        it 'returns true if the thing is up to date' do
+          runner.output = 'Your version of HandBrake is up to date.'
+          cli.update.should be_true
+        end
+
+        it 'returns false if the executable is out of date' do
+          runner.output = 'You are using an old version of HandBrake.'
+          cli.update.should be_false
+        end
+      end
+
+      describe '#preset_list' do
+        let(:sample_presets) { File.read(File.expand_path('../sample-preset-list.out', __FILE__)) }
+
+        before do
+          runner.output = sample_presets
+        end
+
+        it 'uses the --preset-list argument' do
+          cli.preset_list
+          runner.actual_arguments.should == %w(--preset-list)
+        end
+
+        it 'returns a hash containing all the categories' do
+          cli.preset_list.keys.sort.should == %w(Apple Legacy Regular)
+        end
+
+        it 'returns a hash containing the presets in each category' do
+          cli.preset_list['Regular'].keys.sort.should == ['High Profile', 'Normal']
+        end
+
+        it 'returns a hash containing the actual args for a particular preset' do
+          cli.preset_list['Regular']['Normal'].should ==
+            '-e x264  -q 20.0 -a 1 -E faac -B 160 -6 dpl2 -R Auto -D 0.0 -f mp4 --strict-anamorphic -m -x ref=2:bframes=2:subme=6:mixed-refs=0:weightb=0:8x8dct=0:trellis=0'
+        end
+      end
+    end
+  end
+end

data/spec/handbrake/sample-preset-list.out

@@ -0,0 +1,38 @@
+
+< Apple
+
+   + Universal:  -e x264  -q 20.0 -a 1,1 -E faac,copy:ac3 -B 160,160 -6 dpl2,auto -R Auto,Auto -D 0.0,0.0 -f mp4 -X 720 --loose-anamorphic -m -x cabac=0:ref=2:me=umh:bframes=0:weightp=0:8x8dct=0:trellis=0:subme=6
+
+   + iPod:  -e x264  -b 700 -a 1 -E faac -B 160 -6 dpl2 -R Auto -D 0.0 -f mp4 -I -X 320 -m -x level=30:bframes=0:weightp=0:cabac=0:ref=1:vbv-maxrate=768:vbv-bufsize=2000:analyse=all:me=umh:no-fast-pskip=1:subme=6:8x8dct=0:trellis=0
+
+   + iPhone & iPod Touch:  -e x264  -q 20.0 -a 1 -E faac -B 128 -6 dpl2 -R Auto -D 0.0 -f mp4 -X 480 -m -x cabac=0:ref=2:me=umh:bframes=0:weightp=0:subme=6:8x8dct=0:trellis=0
+
+   + iPhone 4:  -e x264  -q 20.0 -r 29.97 --pfr  -a 1 -E faac -B 160 -6 dpl2 -R Auto -D 0.0 -f mp4 -4 -X 960 --loose-anamorphic -m
+
+   + iPad:  -e x264  -q 20.0 -r 29.97 --pfr  -a 1 -E faac -B 160 -6 dpl2 -R Auto -D 0.0 -f mp4 -4 -X 1024 --loose-anamorphic -m
+
+   + AppleTV:  -e x264  -q 20.0 -a 1,1 -E faac,copy:ac3 -B 160,160 -6 dpl2,auto -R Auto,Auto -D 0.0,0.0 -f mp4 -4 -X 960 --loose-anamorphic -m -x cabac=0:ref=2:me=umh:b-pyramid=none:b-adapt=2:weightb=0:trellis=0:weightp=0:vbv-maxrate=9500:vbv-bufsize=9500
+
+   + AppleTV 2:  -e x264  -q 20.0 -r 29.97 --pfr  -a 1,1 -E faac,copy:ac3 -B 160,160 -6 dpl2,auto -R Auto,Auto -D 0.0,0.0 -f mp4 -4 -X 1280 --loose-anamorphic -m
+
+>
+
+< Regular
+
+   + Normal:  -e x264  -q 20.0 -a 1 -E faac -B 160 -6 dpl2 -R Auto -D 0.0 -f mp4 --strict-anamorphic -m -x ref=2:bframes=2:subme=6:mixed-refs=0:weightb=0:8x8dct=0:trellis=0
+
+   + High Profile:  -e x264  -q 20.0 -a 1,1 -E faac,copy:ac3 -B 160,160 -6 dpl2,auto -R Auto,Auto -D 0.0,0.0 -f mp4 --detelecine --decomb --loose-anamorphic -m -x b-adapt=2:rc-lookahead=50
+
+>
+
+< Legacy
+
+   + Classic:  -b 1000 -a 1 -E faac -B 160 -6 dpl2 -R Auto -D 0.0 -f mp4
+
+   + AppleTV Legacy:  -e x264  -b 2500 -a 1,1 -E faac,copy:ac3 -B 160,160 -6 dpl2,auto -R Auto,Auto -D 0.0,0.0 -f mp4 -4 --strict-anamorphic -m -x ref=1:b-pyramid=none:weightp=0:subme=5:me=umh:no-fast-pskip=1:cabac=0:weightb=0:8x8dct=0:trellis=0
+
+   + iPhone Legacy:  -e x264  -b 960 -a 1 -E faac -B 128 -6 dpl2 -R Auto -D 0.0 -f mp4 -I -X 480 -m -x level=30:cabac=0:ref=1:analyse=all:me=umh:no-fast-pskip=1:psy-rd=0,0:bframes=0:weightp=0:subme=6:8x8dct=0:trellis=0
+
+   + iPod Legacy:  -e x264  -b 1500 -a 1 -E faac -B 160 -6 dpl2 -R Auto -D 0.0 -f mp4 -I -X 640 -m -x level=30:bframes=0:weightp=0:cabac=0:ref=1:vbv-maxrate=1500:vbv-bufsize=2000:analyse=all:me=umh:no-fast-pskip=1:psy-rd=0,0:subme=6:8x8dct=0:trellis=0
+
+>