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

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

Constant Summary collapse

SFM_READ = 
0x10
SFC_GET_CHANNEL_MAP_INFO = 
0x1100
SRC_SINC_FASTEST = 
2
BACKENDS = 
%w[auto ffmpeg torchcodec librosa libsndfile].freeze
SQRT_HALF = 
Math.sqrt(0.5)
DEFAULT_MONO_MIXES = 
{
  1 => [1.0],
  2 => [SQRT_HALF, SQRT_HALF],
  3 => [SQRT_HALF, SQRT_HALF, 0.0], # FFmpeg's unspecified 3-channel default is 2.1, not 3.0
  4 => [SQRT_HALF, SQRT_HALF, 1.0, 0.5],
  5 => [SQRT_HALF, SQRT_HALF, 1.0, 0.5, 0.5],
  6 => [SQRT_HALF, SQRT_HALF, 1.0, 0.0, 0.5, 0.5],
  7 => [SQRT_HALF, SQRT_HALF, 1.0, 0.0, 0.5, 0.5, 0.5],
  8 => [SQRT_HALF, SQRT_HALF, 1.0, 0.0, 0.5, 0.5, 0.5, 0.5],
  10 => [SQRT_HALF, SQRT_HALF, 1.0, 0.0, 0.5, 0.5, SQRT_HALF, SQRT_HALF, 0.0, 0.0],
  12 => [
    SQRT_HALF, SQRT_HALF, 1.0, 0.0, 0.5, 0.5, 0.5, 0.5,
    SQRT_HALF, SQRT_HALF, 0.0, 0.0
  ],
  16 => [
    SQRT_HALF, SQRT_HALF, 1.0, 0.5, 0.5, 0.5, 0.5, 0.5,
    SQRT_HALF, 0.0, SQRT_HALF, 0.0, 0.0, 0.0, 0.0, 0.0
  ],
  24 => [
    SQRT_HALF, SQRT_HALF, 1.0, 0.0, 0.5, 0.5, SQRT_HALF, SQRT_HALF,
    0.5, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0,
    0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0
  ]
}.transform_values(&:freeze).freeze
FFMPEG_7_DEFAULT_MONO_MIXES = 
{
  14 => [
    SQRT_HALF, SQRT_HALF, 1.0, 0.0, 0.5, 0.5, SQRT_HALF, SQRT_HALF,
    0.5, 0.5, SQRT_HALF, SQRT_HALF, 0.0, 0.0
  ]
}.transform_values(&:freeze).freeze
FFMPEG_8_DEFAULT_MONO_MIXES = 
{
  16 => [
    SQRT_HALF, SQRT_HALF, 1.0, 0.0, 0.5, 0.5, SQRT_HALF, SQRT_HALF,
    0.5, 0.5, SQRT_HALF, SQRT_HALF, 0.0, 0.0, 0.0, 0.0
  ]
}.transform_values(&:freeze).freeze
CHANNEL_POSITION_MONO_MIXES = 
{
  1 => 1.0,       # mono
  2 => SQRT_HALF, # left
  3 => SQRT_HALF, # right
  4 => 1.0,       # center
  5 => SQRT_HALF, # front left
  6 => SQRT_HALF, # front right
  7 => 1.0,       # front center
  8 => 0.5,       # rear center
  9 => 0.5,       # rear left
  10 => 0.5,      # rear right
  11 => 0.0,      # low-frequency effects
  12 => SQRT_HALF, # front left of center
  13 => SQRT_HALF, # front right of center
  14 => 0.5,      # side left
  15 => 0.5,      # side right
  16 => 0.0,      # top center
  17 => SQRT_HALF, # top front left
  18 => SQRT_HALF, # top front right
  19 => 0.0,      # top front center
  20 => 0.0,      # top rear left
  21 => 0.0,      # top rear right
  22 => 0.0       # top rear center
}.freeze

Class Method Summary collapse

Class Method Details

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

Raises:

  • (ArgumentError) 


246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
 
# File 'lib/cohere/transcribe/audio/decoder.rb', line 246

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?

  if ffmpeg_backend?(requested)
    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

  with_sound_file(source) do |handle, info|
    raise TranscriptionRuntimeError, "Cannot decode #{source}: #{SoundFileABI.sf_strerror(handle)}" if handle.null?

    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
    projected_bytes = projected_decoded_bytes(frames, channels, source_rate, sample_rate)
    if max_decoded_bytes && projected_bytes > max_decoded_bytes
      raise DecodedAudioLimitError,
            "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)
    channel_map = sound_file_channel_map(handle, channels)
    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 = downmix(interleaved, frames, channels, channel_map)
    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
    )
  end
end

.estimate_decoded_bytes(path, backend: "auto", sample_rate: SAMPLE_RATE) ⇒ Object

Best-effort upper bound for the buffers governed by max_decoded_bytes. The preparation scheduler uses it only for grouping; decode performs the authoritative check again against the per-file ceiling.



216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
 
# File 'lib/cohere/transcribe/audio/decoder.rb', line 216

def estimate_decoded_bytes(path, backend: "auto", sample_rate: SAMPLE_RATE)
  requested = backend
  return unless requested.is_a?(String) && BACKENDS.include?(requested)
  return unless sample_rate.is_a?(Integer) && sample_rate.positive?

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

  if ffmpeg_backend?(requested)
    duration = FFmpegNative.duration(source)
    return unless duration&.finite? && duration >= 0.0

    return ((duration * sample_rate).ceil + 1) * Fiddle::SIZEOF_FLOAT
  end
  return unless SoundFileABI::AVAILABLE

  with_sound_file(source) do |handle, info|
    next if handle.null?

    frames = Integer(info.frames)
    channels = Integer(info.channels)
    source_rate = Integer(info.samplerate)
    next unless frames >= 0 && channels.positive? && source_rate.positive?

    projected_decoded_bytes(frames, channels, source_rate, sample_rate)
  end
rescue Fiddle::DLError, SystemCallError, TranscriptionRuntimeError
  nil
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.



187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
 
# File 'lib/cohere/transcribe/audio/decoder.rb', line 187

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

  with_sound_file(source) do |handle, info|
    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)
    return seconds if seconds.finite? && seconds >= 0.0

    nil
  end
rescue Fiddle::DLError, SystemCallError, TranscriptionRuntimeError
  nil
end

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



342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
 
# File 'lib/cohere/transcribe/audio/decoder.rb', line 342

def resample(samples, source_rate, target_rate, max_decoded_bytes)
  unless source_rate.is_a?(Integer) && source_rate.positive? &&
         target_rate.is_a?(Integer) && target_rate.positive?
    raise ArgumentError, "source_rate and target_rate must be positive integers"
  end
  return Numo::SFloat.zeros(0) if samples.empty?

  unless SampleRateABI::AVAILABLE
    error = SampleRateABI.const_defined?(:LOAD_ERROR, false) ? SampleRateABI::LOAD_ERROR.message : "not found"
    raise TranscriptionRuntimeError, "libsamplerate is required to resample audio: #{error}"
  end
  ratio = target_rate.fdiv(source_rate)
  output_capacity = (samples.length * ratio).ceil + 64
  bytes = output_capacity * Fiddle::SIZEOF_FLOAT
  if max_decoded_bytes && bytes > max_decoded_bytes
    raise DecodedAudioLimitError, "Resampled audio exceeds the configured memory limit"
  end

  input_string = samples.to_binary
  input_pointer = Fiddle::Pointer[input_string]
  output_pointer = Fiddle::Pointer.malloc([bytes, 1].max, Fiddle::RUBY_FREE)
  SampleRateABI::SRCData.malloc(Fiddle::RUBY_FREE) do |data|
    data.data_in = input_pointer
    data.data_out = output_pointer
    data.input_frames = samples.length
    data.output_frames = output_capacity
    data.input_frames_used = 0
    data.output_frames_gen = 0
    data.end_of_input = 1
    data.src_ratio = ratio
    error_code = SampleRateABI.src_simple(data.to_ptr, SRC_SINC_FASTEST, 1)
    raise TranscriptionRuntimeError, "Audio resampling failed: #{SampleRateABI.src_strerror(error_code)}" unless error_code.zero?

    generated = Integer(data.output_frames_gen)
    consumed = Integer(data.input_frames_used)
    unless consumed == samples.length && generated.between?(0, output_capacity)
      raise TranscriptionRuntimeError,
            "Audio resampling returned invalid frame counts " \
            "(consumed #{consumed}/#{samples.length}, generated #{generated}/#{output_capacity})"
    end
    return Numo::SFloat.from_binary(output_pointer[0, generated * Fiddle::SIZEOF_FLOAT])
  end
end