Method: HandBrake::CLI#output

Defined in:
lib/handbrake/cli.rb

#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