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.

Defined Under Namespace

Classes: PopenRunner, RunnerResult

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

  • :dry_run (Boolean) — default: false —

    if true, nothing will actually be executed. The commands that would have been executed will be printed to standard out.

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

    the object encapsulating the execution method for HandBrakeCLI or a lambda which may be invoked to create the runner. A lambda will receive the HandBrake::CLI instance that's being constructed as its sole argument. You shouldn't usually need to replace this. If you do, look at #runner for more details.



51
52
53
54
55
56
57
58
 
# File 'lib/handbrake/cli.rb', line 51

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

  @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:



303
304
305
306
307
 
# File 'lib/handbrake/cli.rb', line 303

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) 


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

def bin_path
  @bin_path
end

#dry_run=(value) ⇒ Boolean (writeonly)

Set whether dry_run mode is selected.

Returns:

  • (Boolean) 


26
27
28
 
# File 'lib/handbrake/cli.rb', line 26

def dry_run=(value)
  @dry_run = value
end

#runner ⇒ #run

The runner to use to actually invoke HandBrakeCLI. This should be an object following the protocol laid out in the documentation for PopenRunner.

Returns:

  • (#run) 


34
35
36
 
# File 'lib/handbrake/cli.rb', line 34

def runner
  @runner
end

#trace=(value) ⇒ Boolean

Set whether trace is enabled.

Returns:

  • (Boolean) 


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

def trace=(value)
  @trace = value
end

Instance Method Details

#dry_run? ⇒ Boolean

Is this instance in dry_run mode?

If it is, then no commands will actually be executed. The constructed HandBrakeCLI invocations will be printed to standard out, instead.

Returns:

  • (Boolean) 


100
101
102
 
# File 'lib/handbrake/cli.rb', line 100

def dry_run?
  @dry_run
end

#initialize_copy(original)

This method returns an undefined value.

Ensures that #dup produces a separate copy.



78
79
80
 
# File 'lib/handbrake/cli.rb', line 78

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. The provided hash will not be modified.

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, String) — 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. If the value is literally true, the temporary filename is the target filename with .handbraking inserted before the extension. If the value is a string, it is interpreted as a path; the temporary file is written to this path instead of in the ultimate target directory. 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.



140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
 
# File 'lib/handbrake/cli.rb', line 140

def output(filename, options={})
  options = options.dup
  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 =
    case atomic
    when true
      partial_filename(filename)
    when String
      partial_filename(File.join(atomic, File.basename(filename)))
    when false, nil
      filename
    else
      fail "Unsupported value for :atomic: #{atomic.inspect}"
    end

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

  FileUtils.mkdir_p(File.dirname(interim_filename), fileutils_options)
  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.mkdir_p(File.dirname(filename), fileutils_options)
    FileUtils.mv(interim_filename, filename, fileutils_options) 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) 


260
261
262
263
264
265
266
267
268
269
 
# File 'lib/handbrake/cli.rb', line 260

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 ⇒ Disc, Title

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:

  • (Disc, Title) —

    a Disc when scanning for all titles, or a Title when scanning for one title.



217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
 
# File 'lib/handbrake/cli.rb', line 217

def scan
  one_title = arguments.include?('--title')

  args = %w(--scan)
  unless one_title
    args.unshift('--title', '0')
  end

  disc = Disc.from_output(run(*args).output)

  if one_title
    disc.titles.values.first
  else
    disc
  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) 


90
91
92
 
# File 'lib/handbrake/cli.rb', line 90

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) 


243
244
245
246
 
# File 'lib/handbrake/cli.rb', line 243

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