cohere-transcribe 0.1.0

data/lib/cohere/transcribe/audio/LICENSE.auditok

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2015-2026 Mohamed El Amine SEHILI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/lib/cohere/transcribe/audio/decoder.rb

@@ -0,0 +1,315 @@
+# frozen_string_literal: true
+
+require "fiddle/import"
+require "rbconfig"
+
+require_relative "../constants"
+require_relative "../errors"
+require_relative "ffmpeg_native"
+
+module Cohere
+  module Transcribe
+    module Audio
+      Decoded = Data.define(:samples, :sample_rate, :backend, :fallback_reason)
+
+      module SharedLibraryCandidates
+        module_function
+
+        def build(environment_key, names, formula:, host_os: RbConfig::CONFIG.fetch("host_os"))
+          candidates = [ENV.fetch(environment_key, nil), *names].compact
+          return candidates.uniq unless host_os.match?(/darwin/)
+
+          directories = []
+          homebrew_prefix = ENV.fetch("HOMEBREW_PREFIX", nil)
+          directories << File.join(homebrew_prefix, "opt", formula, "lib") if homebrew_prefix && !homebrew_prefix.empty?
+          directories.push(
+            "/opt/homebrew/opt/#{formula}/lib",
+            "/usr/local/opt/#{formula}/lib",
+            "/opt/homebrew/lib",
+            "/usr/local/lib",
+            "/opt/local/lib"
+          )
+          candidates.concat(directories.product(names).map { |directory, name| File.join(directory, name) })
+          candidates.uniq
+        end
+      end
+      private_constant :SharedLibraryCandidates
+
+      module SoundFileABI
+        extend Fiddle::Importer
+
+        begin
+          candidates = SharedLibraryCandidates.build(
+            "COHERE_TRANSCRIBE_SNDFILE_LIBRARY",
+            %w[libsndfile.so.1 libsndfile.so libsndfile.1.dylib libsndfile.dylib],
+            formula: "libsndfile"
+          )
+          library = candidates.find do |candidate|
+            Fiddle.dlopen(candidate)
+            true
+          rescue Fiddle::DLError
+            false
+          end
+          raise Fiddle::DLError, "libsndfile was not found" unless library
+
+          dlload library
+          SFInfo = struct([
+                            "long long frames",
+                            "int samplerate",
+                            "int channels",
+                            "int format",
+                            "int sections",
+                            "int seekable"
+                          ])
+          extern "void* sf_open(const char*, int, void*)"
+          extern "long long sf_readf_float(void*, void*, long long)"
+          extern "int sf_close(void*)"
+          extern "const char* sf_strerror(void*)"
+          AVAILABLE = true
+        rescue Fiddle::DLError => e
+          LOAD_ERROR = e
+          AVAILABLE = false
+        end
+      end
+      private_constant :SoundFileABI
+
+      module SampleRateABI
+        extend Fiddle::Importer
+
+        begin
+          candidates = SharedLibraryCandidates.build(
+            "COHERE_TRANSCRIBE_SAMPLERATE_LIBRARY",
+            %w[libsamplerate.so.0 libsamplerate.so libsamplerate.0.dylib libsamplerate.dylib],
+            formula: "libsamplerate"
+          )
+          library = candidates.find do |candidate|
+            Fiddle.dlopen(candidate)
+            true
+          rescue Fiddle::DLError
+            false
+          end
+          raise Fiddle::DLError, "libsamplerate was not found" unless library
+
+          dlload library
+          SRCData = struct([
+                             "void* data_in",
+                             "void* data_out",
+                             "long input_frames",
+                             "long output_frames",
+                             "long input_frames_used",
+                             "long output_frames_gen",
+                             "int end_of_input",
+                             "double src_ratio"
+                           ])
+          extern "int src_simple(void*, int, int)"
+          extern "const char* src_strerror(int)"
+          AVAILABLE = true
+        rescue Fiddle::DLError => e
+          LOAD_ERROR = e
+          AVAILABLE = false
+        end
+      end
+      private_constant :SampleRateABI
+
+      module Decoder
+        module_function
+
+        SFM_READ = 0x10
+        SRC_SINC_FASTEST = 2
+        BACKENDS = %w[auto ffmpeg torchcodec librosa libsndfile].freeze
+
+        # 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.
+        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
+
+        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
+
+        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 TranscriptionRuntimeError, "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)
+          data = SampleRateABI::SRCData.malloc
+          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
+          Numo::SFloat.from_binary(output_pointer[0, generated * Fiddle::SIZEOF_FLOAT])
+        end
+
+        def validate_finite!(samples)
+          return samples if samples.empty?
+
+          (0...samples.length).step(1_048_576) do |offset|
+            finish = [offset + 1_048_576, samples.length].min
+            raise TranscriptionRuntimeError, "Decoded audio contains NaN or infinite samples" unless samples[offset...finish].isfinite.all?
+          end
+          samples
+        end
+        private_class_method :validate_finite!
+      end
+    end
+  end
+end

data/lib/cohere/transcribe/audio/ffmpeg_native.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+require "fiddle"
+require "rbconfig"
+
+require_relative "../errors"
+
+module Cohere
+  module Transcribe
+    module Audio
+      # Lazy binding for the gem's subprocess-free libav decoder adapter. The
+      # adapter itself dynamically selects a compatible FFmpeg 4-8 runtime;
+      # Ruby never launches ffmpeg and does not retain a Python codec runtime.
+      module FFmpegNative
+        ERROR_CAPACITY = 1_024
+        CANCELLED_STATUS = 6
+
+        class Library
+          FUNCTIONS = {
+            probe: [%i[voidp size_t], :int],
+            decode: [%i[voidp int uint64 voidp voidp voidp size_t], :int],
+            duration: [%i[voidp voidp voidp size_t], :int],
+            cancel: [[], :void],
+            free: [[:voidp], :void]
+          }.freeze
+
+          TYPE_MAP = {
+            void: Fiddle::TYPE_VOID,
+            voidp: Fiddle::TYPE_VOIDP,
+            int: Fiddle::TYPE_INT,
+            size_t: Fiddle::TYPE_SIZE_T,
+            uint64: Fiddle::TYPE_UINT64_T
+          }.freeze
+
+          class << self
+            def load
+              @mutex ||= Mutex.new
+              @mutex.synchronize { @instance ||= load_uncached }
+            end
+
+            def loaded
+              mutex = @mutex
+              mutex&.synchronize { @instance }
+            end
+
+            def candidate_paths
+              explicit = ENV.fetch("COHERE_TRANSCRIBE_AUDIO_LIBRARY", nil)
+              return [explicit] if explicit && !explicit.empty?
+
+              packaged = File.expand_path("../native", __dir__)
+              patterns = case RbConfig::CONFIG.fetch("host_os")
+                         when /darwin/ then ["libcohere_audio*.dylib"]
+                         when /mswin|mingw|cygwin/ then ["cohere_audio*.dll", "libcohere_audio*.dll"]
+                         else ["libcohere_audio.so", "libcohere_audio.so.*"]
+                         end
+              paths = patterns.flat_map { |pattern| Dir.glob(File.join(packaged, pattern)) }.sort
+              paths.concat(system_library_names)
+              paths.uniq
+            end
+
+            private
+
+            def load_uncached
+              failures = []
+              candidate_paths.each do |candidate|
+                library = new(candidate)
+                library.probe!
+                return library
+              rescue Fiddle::DLError, LoadError, TranscriptionRuntimeError => e
+                failures << "#{candidate}: #{e.message}"
+              end
+              detail = failures.empty? ? "no candidate adapter libraries were found" : failures.join("; ")
+              raise TranscriptionRuntimeError,
+                    "The native FFmpeg audio adapter could not be loaded (#{detail}). " \
+                    "Set COHERE_TRANSCRIBE_AUDIO_LIBRARY to libcohere_audio."
+            end
+
+            def system_library_names
+              case RbConfig::CONFIG.fetch("host_os")
+              when /darwin/ then ["libcohere_audio.1.dylib", "libcohere_audio.dylib"]
+              when /mswin|mingw|cygwin/ then ["cohere_audio.dll", "libcohere_audio.dll"]
+              else ["libcohere_audio.so.1", "libcohere_audio.so"]
+              end
+            end
+          end
+
+          attr_reader :path, :diagnostic
+
+          def initialize(path)
+            @path = path
+            @handle = Fiddle::Handle.new(path, Fiddle::RTLD_NOW)
+            @functions = FUNCTIONS.to_h do |name, (arguments, result)|
+              address = @handle["cohere_audio_ffmpeg_#{name}"]
+              function = Fiddle::Function.new(
+                address,
+                arguments.map { |type| TYPE_MAP.fetch(type) },
+                TYPE_MAP.fetch(result)
+              )
+              [name, function]
+            end.freeze
+          end
+
+          def probe!
+            message = Fiddle::Pointer.malloc(ERROR_CAPACITY, Fiddle::RUBY_FREE)
+            message[0, ERROR_CAPACITY] = "\0" * ERROR_CAPACITY
+            status = @functions.fetch(:probe).call(message, ERROR_CAPACITY)
+            @diagnostic = message.to_s.force_encoding(Encoding::UTF_8).scrub.freeze
+            return self if status.zero?
+
+            raise TranscriptionRuntimeError, "Native FFmpeg libraries are unavailable: #{@diagnostic}"
+          end
+
+          def decode(path, sample_rate:, max_decoded_bytes:)
+            output_slot = Fiddle::Pointer.malloc(Fiddle::SIZEOF_VOIDP, Fiddle::RUBY_FREE)
+            output_slot[0, Fiddle::SIZEOF_VOIDP] = [0].pack("J")
+            count_slot = Fiddle::Pointer.malloc(Fiddle::SIZEOF_INT64_T, Fiddle::RUBY_FREE)
+            count_slot[0, Fiddle::SIZEOF_INT64_T] = [0].pack("q")
+            message = Fiddle::Pointer.malloc(ERROR_CAPACITY, Fiddle::RUBY_FREE)
+            message[0, ERROR_CAPACITY] = "\0" * ERROR_CAPACITY
+            maximum = max_decoded_bytes || 0
+
+            status = @functions.fetch(:decode).call(
+              c_string(path.to_s),
+              sample_rate,
+              maximum,
+              output_slot,
+              count_slot,
+              message,
+              ERROR_CAPACITY
+            )
+            address = output_slot[0, Fiddle::SIZEOF_VOIDP].unpack1("J")
+            count = count_slot[0, Fiddle::SIZEOF_INT64_T].unpack1("q")
+            detail = message.to_s.force_encoding(Encoding::UTF_8).scrub
+            unless status.zero?
+              @functions.fetch(:free).call(address) unless address.zero?
+              raise Interrupt, "Native FFmpeg decode was cancelled for #{path}: #{detail}" if status == CANCELLED_STATUS
+
+              raise TranscriptionRuntimeError, "Cannot decode #{path} through native FFmpeg: #{detail}"
+            end
+            if count.negative? || (count.positive? && address.zero?)
+              @functions.fetch(:free).call(address) unless address.zero?
+              raise TranscriptionRuntimeError, "Native FFmpeg returned invalid output metadata for #{path}"
+            end
+            bytes = count * Fiddle::SIZEOF_FLOAT
+            if max_decoded_bytes && bytes > max_decoded_bytes
+              @functions.fetch(:free).call(address) unless address.zero?
+              raise TranscriptionRuntimeError,
+                    "Native FFmpeg exceeded the configured decoded-audio memory limit for #{path}"
+            end
+
+            begin
+              require "numo/narray"
+              if count.zero?
+                Numo::SFloat.zeros(0)
+              else
+                Numo::SFloat.from_binary(Fiddle::Pointer.new(address)[0, bytes])
+              end
+            rescue LoadError => e
+              raise TranscriptionRuntimeError, "numo-narray is required for decoded audio: #{e.message}"
+            ensure
+              @functions.fetch(:free).call(address) unless address.zero?
+            end
+          end
+
+          def duration(path)
+            duration_slot = Fiddle::Pointer.malloc(Fiddle::SIZEOF_DOUBLE, Fiddle::RUBY_FREE)
+            duration_slot[0, Fiddle::SIZEOF_DOUBLE] = [-1.0].pack("d")
+            message = Fiddle::Pointer.malloc(ERROR_CAPACITY, Fiddle::RUBY_FREE)
+            message[0, ERROR_CAPACITY] = "\0" * ERROR_CAPACITY
+            status = @functions.fetch(:duration).call(
+              c_string(path.to_s),
+              duration_slot,
+              message,
+              ERROR_CAPACITY
+            )
+            detail = message.to_s.force_encoding(Encoding::UTF_8).scrub
+            unless status.zero?
+              raise Interrupt, "Native FFmpeg duration probe was cancelled for #{path}: #{detail}" if status == CANCELLED_STATUS
+
+              raise TranscriptionRuntimeError,
+                    "Cannot inspect #{path} through native FFmpeg: #{detail}"
+            end
+
+            seconds = duration_slot[0, Fiddle::SIZEOF_DOUBLE].unpack1("d")
+            return nil unless seconds.finite? && seconds >= 0.0
+
+            seconds
+          end
+
+          def cancel_all!
+            @functions.fetch(:cancel).call
+            nil
+          end
+
+          private
+
+          def c_string(value)
+            Fiddle::Pointer["#{value}\0"]
+          end
+        end
+
+        module_function
+
+        def library
+          Library.load
+        end
+
+        def available?
+          library
+          true
+        rescue TranscriptionRuntimeError
+          false
+        end
+
+        def diagnostic
+          library.diagnostic
+        rescue TranscriptionRuntimeError => e
+          e.message
+        end
+
+        def decode(path, sample_rate:, max_decoded_bytes:)
+          library.decode(path, sample_rate: sample_rate, max_decoded_bytes: max_decoded_bytes)
+        end
+
+        def duration(path)
+          library.duration(path)
+        end
+
+        def cancel_all!
+          library.cancel_all!
+        rescue TranscriptionRuntimeError
+          nil
+        end
+
+        # Pipeline cleanup must not load FFmpeg merely to discover that no
+        # native decode has ever started. If the adapter is already resident,
+        # this wakes every operation that captured an older cancellation
+        # generation while preserving later independent calls.
+        def cancel_active!
+          Library.loaded&.cancel_all!
+          nil
+        rescue Fiddle::DLError, TranscriptionRuntimeError
+          nil
+        end
+      end
+    end
+  end
+end