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:



246
247
248
249
250
 
# File 'lib/handbrake/cli.rb', line 246

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



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
133
134
135
136
137
138
139
140
 
# File 'lib/handbrake/cli.rb', line 86

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 =
    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

  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, :verbose => trace?) 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) 


203
204
205
206
207
208
209
210
211
212
 
# File 'lib/handbrake/cli.rb', line 203

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.



160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
 
# File 'lib/handbrake/cli.rb', line 160

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) 


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) 


186
187
188
189
 
# File 'lib/handbrake/cli.rb', line 186

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