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
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
Performs a conversion. This method immediately begins the
 transcoding process; set all other options first.

 @param [String] filename the desired name for the final output
   file.
 @param [Hash] options additional options to control the behavior
   of the output process. The provided hash will not be modified.
 @option options [Boolean,:ignore] :overwrite (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.
 @option options [Boolean, String] :atomic (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.

 @return [void]