Module: Cohere::Transcribe::Audio::Decoder

Defined in:: lib/cohere/transcribe/audio/decoder.rb

Constant Summary collapse

SFM_READ =

0x10

SRC_SINC_FASTEST =

BACKENDS =

%w[auto ffmpeg torchcodec librosa libsndfile].freeze

Class Method Summary collapse

.decode(path, backend: "auto", sample_rate: SAMPLE_RATE, max_decoded_bytes: 4 * (1024**3)) ⇒ Object
.probe_duration(path) ⇒ Object
Best-effort metadata probe used for public skipped-result parity.
.resample(samples, source_rate, target_rate, max_decoded_bytes) ⇒ Object

Class Method Details

.decode(path, backend: "auto", sample_rate: SAMPLE_RATE, max_decoded_bytes: 4 * (1024**3)) ⇒ `Object`

Raises:

(ArgumentError)

# File 'lib/cohere/transcribe/audio/decoder.rb', line 150

def decode(path, backend: "auto", sample_rate: SAMPLE_RATE, max_decoded_bytes: 4 * (1024**3))
  requested = backend
  unless requested.is_a?(String) && BACKENDS.include?(requested)
    raise ArgumentError, "Unsupported audio backend: #{backend.inspect}"
  end
  raise ArgumentError, "sample_rate must be a positive integer" unless sample_rate.is_a?(Integer) && sample_rate.positive?
  unless max_decoded_bytes.nil? || (max_decoded_bytes.is_a?(Integer) && max_decoded_bytes.positive?)
    raise ArgumentError, "max_decoded_bytes must be a positive integer or nil"
  end

  source = Pathname(path).expand_path
  raise TranscriptionInputError, "Input does not exist: #{source}" unless source.exist?
  raise TranscriptionInputError, "Input is not a regular file: #{source}" unless source.file?

  native_ffmpeg_available = %w[auto librosa].include?(requested) && FFmpegNative.available?
  use_ffmpeg = requested == "ffmpeg" || requested == "torchcodec" ||
               (%w[auto librosa].include?(requested) && native_ffmpeg_available)
  if use_ffmpeg
    samples = FFmpegNative.decode(
      source,
      sample_rate: sample_rate,
      max_decoded_bytes: max_decoded_bytes
    )
    validate_finite!(samples)
    return Decoded.new(
      samples: samples.freeze,
      sample_rate: sample_rate,
      backend: "ffmpeg",
      fallback_reason: if %w[torchcodec librosa].include?(requested)
                         "Ruby #{requested} compatibility mode uses FFmpeg through the native C ABI"
                       end
    )
  end

  unless SoundFileABI::AVAILABLE
    sound_file_error = if SoundFileABI.const_defined?(:LOAD_ERROR, false)
                         SoundFileABI::LOAD_ERROR.message
                       else
                         "not found"
                       end
    if requested == "auto"
      raise TranscriptionRuntimeError,
            "Automatic audio decoding requires the native FFmpeg adapter or libsndfile " \
            "(FFmpeg: #{FFmpegNative.diagnostic}; libsndfile: #{sound_file_error})"
    end
    raise TranscriptionRuntimeError, "libsndfile is required for native audio decoding: #{sound_file_error}"
  end

  info = SoundFileABI::SFInfo.malloc
  handle = SoundFileABI.sf_open(source.to_s, SFM_READ, info.to_ptr)
  raise TranscriptionRuntimeError, "Cannot decode #{source}: #{SoundFileABI.sf_strerror(handle)}" if handle.null?

  begin
    frames = Integer(info.frames)
    channels = Integer(info.channels)
    source_rate = Integer(info.samplerate)
    unless frames >= 0 && channels.positive? && source_rate.positive?
      raise TranscriptionRuntimeError, "Decoder returned invalid audio metadata for #{source}"
    end

    input_bytes = frames * channels * Fiddle::SIZEOF_FLOAT
    output_frames = (frames * sample_rate.fdiv(source_rate)).ceil + 64
    projected_bytes = [input_bytes, output_frames * Fiddle::SIZEOF_FLOAT].max
    if max_decoded_bytes && projected_bytes > max_decoded_bytes
      raise TranscriptionRuntimeError,
            "Decoded audio exceeds the configured memory limit for #{source} " \
            "(#{projected_bytes} > #{max_decoded_bytes} bytes)"
    end

    raw = Fiddle::Pointer.malloc([input_bytes, 1].max, Fiddle::RUBY_FREE)
    read_frames = SoundFileABI.sf_readf_float(handle, raw, frames)
    raise TranscriptionRuntimeError, "Cannot decode #{source}: #{SoundFileABI.sf_strerror(handle)}" if read_frames.negative?
    raise TranscriptionRuntimeError, "Decoder returned more frames than allocated for #{source}" if read_frames > frames

    frames = read_frames
    begin
      require "numo/narray"
    rescue LoadError => e
      raise TranscriptionRuntimeError, "numo-narray is required for decoded audio: #{e.message}"
    end
    interleaved = if frames.zero?
                    nil
                  else
                    Numo::SFloat.from_binary(raw[0, frames * channels * Fiddle::SIZEOF_FLOAT])
                  end
    mono = if frames.zero?
             Numo::SFloat.zeros(0)
           elsif channels == 1
             interleaved
           else
             interleaved.reshape(frames, channels).mean(1).cast_to(Numo::SFloat)
           end
    samples = source_rate == sample_rate ? mono : resample(mono, source_rate, sample_rate, max_decoded_bytes)
    validate_finite!(samples)
    Decoded.new(
      samples: samples.freeze,
      sample_rate: sample_rate,
      backend: "libsndfile",
      fallback_reason: if %w[auto libsndfile].include?(requested)
                         nil
                       else
                         "Ruby #{requested} compatibility mode uses the native libsndfile ABI"
                       end
    )
  ensure
    SoundFileABI.sf_close(handle)
  end
end

.probe_duration(path) ⇒ `Object`

Best-effort metadata probe used for public skipped-result parity. It may inspect container headers and demuxer probe packets but never launches ffprobe or materializes decoded PCM in Ruby.

# File 'lib/cohere/transcribe/audio/decoder.rb', line 124

def probe_duration(path)
  source = Pathname(path).expand_path
  return nil unless source.file?

  if FFmpegNative.available?
    duration = FFmpegNative.duration(source)
    return duration if duration
  end
  return nil unless SoundFileABI::AVAILABLE

  info = SoundFileABI::SFInfo.malloc
  handle = SoundFileABI.sf_open(source.to_s, SFM_READ, info.to_ptr)
  return nil if handle.null?

  frames = Integer(info.frames)
  sample_rate = Integer(info.samplerate)
  return nil unless frames >= 0 && sample_rate.positive?

  seconds = frames.fdiv(sample_rate)
  seconds if seconds.finite? && seconds >= 0.0
rescue Fiddle::DLError, SystemCallError, TranscriptionRuntimeError
  nil
ensure
  SoundFileABI.sf_close(handle) if defined?(handle) && handle && !handle.null?
end

.resample(samples, source_rate, target_rate, max_decoded_bytes) ⇒ `Object`