Class: HandBrake::CLI

Inherits:
Object
  • Object
show all
Defined in:
lib/handbrake/cli.rb

Overview

The main entry point for this API. See README for usage examples.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ CLI

Returns a new instance of CLI.

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :bin_path (String) — default: 'HandBrakeCLI' —

    the full path to the executable to use

  • :trace (Boolean) — default: false —

    whether #trace? is enabled

  • :runner (#run) — default: a PopenRunner instance —

    the class encapsulating the execution method for HandBrakeCLI. You shouldn't usually need to replace this.



30
31
32
33
34
35
36
 
# File 'lib/handbrake/cli.rb', line 30

def initialize(options={})
  @bin_path = options[:bin_path] || 'HandBrakeCLI'
  @trace = options[:trace].nil? ? false : options[:trace]
  @runner = options[:runner] || PopenRunner.new(self)

  @args = []
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(name, *args) ⇒ CLI (private)

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.

Returns:



229
230
231
232
233
 
# File 'lib/handbrake/cli.rb', line 229

def method_missing(name, *args)
  copy = self.dup
  copy.instance_eval { @args << [name, *(args.collect { |a| a.to_s })] }
  copy
end

Instance Attribute Details

#bin_path ⇒ String

The full path (including filename) to the HandBrakeCLI executable to use.

Returns:

  • (String) 


13
14
15
 
# File 'lib/handbrake/cli.rb', line 13

def bin_path
  @bin_path
end

#trace=(value) ⇒ Boolean

Set whether trace is enabled.

Returns:

  • (Boolean) 


19
20
21
 
# File 'lib/handbrake/cli.rb', line 19

def trace=(value)
  @trace = value
end

Instance Method Details

#initialize_copy(original)

This method returns an undefined value.

Ensures that #dup produces a separate copy.



42
43
44
 
# File 'lib/handbrake/cli.rb', line 42

def initialize_copy(original)
  @args = original.instance_eval { @args }.collect { |bit| bit.dup }
end

#output(filename, options = {})

This method returns an undefined value.

Performs a conversion. This method immediately begins the transcoding process; set all other options first.

Parameters:

  • filename (String) —

    the desired name for the final output file

  • options (Hash) (defaults to: {}) —

    additional options to control the behavior of the output process

Options Hash (options):

  • :overwrite (Boolean, :ignore) — default: true —

    determines the behavior if the desired output file already exists. If true, the file is replaced. If false, an exception is thrown. If :ignore, the file is skipped; i.e., HandBrakeCLI is not invoked.

  • :atomic (Boolean) — default: false —

    provides a pseudo-atomic mode for transcoded output. If true, the transcode will go into a temporary file and only be copied to the specified filename if it completes. The temporary filename is the target filename with .handbraking inserted before the extension. Any :overwrite checking will be applied to the target filename both before and after the transcode happens (the temporary file will always be overwritten). This option is intended to aid in writing automatically resumable batch scripts.



83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
 
# File 'lib/handbrake/cli.rb', line 83

def output(filename, options={})
  overwrite = options.delete :overwrite
  case overwrite
  when true, nil
    # no special behavior
  when false
    raise FileExistsError, filename if File.exist?(filename)
  when :ignore
    if File.exist?(filename)
      trace "Ignoring transcode to #{filename.inspect} because it already exists"
      return
    end
  else
    raise "Unsupported value for :overwrite: #{overwrite.inspect}"
  end

  atomic = options.delete :atomic
  interim_filename =
    if atomic
      partial_filename(filename)
    else
      filename
    end

  unless options.empty?
    raise "Unknown options for output: #{options.keys.inspect}"
  end

  run('--output', interim_filename)

  if filename != interim_filename
    replace =
      if File.exist?(filename)
        trace "#{filename.inspect} showed up during transcode"
        case overwrite
        when false
          raise FileExistsError, filename
        when :ignore
          trace "- will leave #{filename.inspect} as is; copy #{interim_filename.inspect} manually if you want to replace it"
          false
        else
          trace '- will replace with new transcode'
          true
        end
      else
        true
      end
    FileUtils.mv interim_filename, filename if replace
  end
end

#preset_list ⇒ Hash

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.)

Returns:

  • (Hash) 


186
187
188
189
190
191
192
193
194
195
 
# File 'lib/handbrake/cli.rb', line 186

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

#scan ⇒ Titles

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.)

Returns:



151
152
153
154
155
156
157
158
 
# File 'lib/handbrake/cli.rb', line 151

def scan
  if arguments.include?('--title')
    result = run('--scan')
    Titles.from_output(result.output)
  else
    title(0).scan
  end
end

#trace? ⇒ Boolean

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.

Returns:

  • (Boolean) 


54
55
56
 
# File 'lib/handbrake/cli.rb', line 54

def trace?
  @trace
end

#update ⇒ Boolean

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.

Returns:

  • (Boolean) 


169
170
171
172
 
# File 'lib/handbrake/cli.rb', line 169

def update
  result = run('--update')
  result.output =~ /Your version of HandBrake is up to date./i
end