cohere-transcribe 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8abec88f3e61c6c4ffb5de851d99d670320517511894adab2700c4c4316e7373
-  data.tar.gz: 3d74ecae961ec1ece4559804936e4e5a42737c666a6fad772f36a8d4e03f5eaf
+  metadata.gz: f494c8ad68293a60a51ea1510bd3ce55b81867f9014d4a5dcbd5c8499e970bde
+  data.tar.gz: efe16c2e6c4b0c2e4924716fc4023dffe0480375a075b8138c974b41dddb9115
 SHA512:
-  metadata.gz: e453948e563efdf28964936f21b447c6121c890beb7feb93571bd6fd4cb14665ac6b4dd2d02364a6c6e75c66035d15956bf7763c72de78b628a5f47670b4cd23
-  data.tar.gz: 8c4d4411d200b27a3d16d0a8e20806e7d47f820c16d3a0d9ba730b7e6a411605187015aff1197737b444367af02ccd165e82ec74cdff8d6badad6a0e2f3373af
+  metadata.gz: d43d30ab5c72a800e94148d368475aaf97a8f3a8ca97bd8ea24804783dcfea3450cef86accfdacd487064f6c7636c3811ca054d6f51c75a040dcc050a6634027
+  data.tar.gz: 7e506a692ae9025e4d825f5330a94685a2500f296745dbdf671bdf632799873278d88f21f93e1d36b9a382b8c8e1eae834a82267f7851da2e41b2371b6312f25

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [0.1.2] - 2026-07-16
+
+- Correct macOS creation-mode delivery for descriptor-relative staged files and turn concurrent output replacement during preflight into a normal reprocessing decision.
+- Correct ZIP and ZIP64 boundary handling, verify streamed PyTorch tensor storage checksums before conversion, and make vocabulary validation bounded for malformed declared shapes.
+- Close abandoned and partially constructed native sessions exactly once, release native decoder metadata allocations deterministically, and guarantee decoded FFmpeg buffers are released when interruption arrives at the native return boundary.
+- Make preparation groups size-aware so long files retain the full single-file memory ceiling without overlapping another group, unify stereo downmix energy across audio backends, and return typed public errors for binary-encoded Unix paths.
+- Keep diagnostics and early command-line interruption contained, revalidate symbolic Hub revisions while online with an explicit offline cache mode, require CMake 3.15+, and install and exercise the built source gem on both CI platforms.
+
 ## [0.1.1] - 2026-07-15
 
 - Fix CUDA source-gem installation across Unix Makefiles and Ninja by making NVCC's generated response file available from each compiler working directory, including when the gem is installed beneath a path containing spaces.

data/README.md

@@ -8,7 +8,7 @@ The core Dense path supports the pinned Arabic/English model, compatible Hub fin
 
 - 64-bit Ruby `>= 4.0, < 5.0` (the Dense model exceeds a 32-bit address space)
 - 64-bit Linux or macOS; the packaged native source build does not currently support Windows
-- CMake 3.14+ and a C++20 compiler when installing from source
+- CMake 3.15+ and a C++20 compiler when installing from source
 - FFmpeg 4–8 shared libraries for the full accepted container/codec set
 - `libsndfile` and `libsamplerate` shared libraries for the fallback used when the native FFmpeg adapter is unavailable
 - A Hugging Face token when the selected model requires authentication
@@ -187,7 +187,7 @@ The segment runtime uses CrispASR's padded Cohere encoder and ragged greedy deco
 
 Native inference failures carry a thread-local error kind and diagnostic message across the C ABI. Ruby maps invalid arguments and invariant violations to fatal failures, allocator failures to OOM, and ordinary runtime failures to isolatable errors. Only typed OOM failures teach a smaller adaptive batch cap; fatal failures open the retained session's circuit breaker.
 
-For multi-file runs, `preprocess_workers` concurrently decodes and segments one ordered preparation group while `pipeline_preparation` permits exactly one next group to overlap current ASR. Each pipelined group is capped at the smaller of half `audio_memory_gb` and 512 MiB of retained mono float PCM, so the current and next groups remain within the configured PCM budget; native codec transients can add short-lived overhead. Disable `pipeline_preparation` to use the full per-file budget on a sequential path, which is the escape hatch for a single file larger than the half-budget pipeline slot. Automatic worker selection uses one worker for one file and at most two otherwise; explicit counts are capped by available processors and the group size. Decode/VAD failures remain isolated per file, and results, progress events, and publication always follow input order. Word alignment does not retain those prepared waveforms across its phase barrier. It re-decodes one file at a time through the concrete backend recorded during ASR (with one look-ahead only when the adjacent PCM pair fits `audio_memory_gb`) and rejects backend or sample-count drift. Resumable ASR checkpoints enter the alignment phase directly without reopening Dense or repeating decode/VAD preparation.
+For multi-file runs, `preprocess_workers` concurrently decodes and segments one ordered preparation group while `pipeline_preparation` permits exactly one next group to overlap current ASR. Each ordinary pipelined group is capped at the smaller of half `audio_memory_gb` and 512 MiB of retained mono float PCM, with metadata-based size estimates assigning per-file ceilings instead of dividing the cap equally. A file whose estimate exceeds the group cap, or whose size cannot be estimated, is prepared alone with the full `audio_memory_gb` ceiling and no adjacent-group overlap. Native codec transients can add short-lived overhead. Disable `pipeline_preparation` for a fully sequential path. Automatic worker selection uses one worker for one file and at most two otherwise; explicit counts are capped by available processors and the group size. Decode/VAD failures remain isolated per file, and results, progress events, and publication always follow input order. Word alignment does not retain those prepared waveforms across its phase barrier. It re-decodes one file at a time through the concrete backend recorded during ASR (with one look-ahead only when the adjacent PCM pair fits `audio_memory_gb`) and rejects backend or sample-count drift. Resumable ASR checkpoints enter the alignment phase directly without reopening Dense or repeating decode/VAD preparation.
 
 `pin_memory` remains accepted for Python API/CLI compatibility, but resolves to `false` in this ggml runtime. Ruby passes float PCM directly through the native session ABI, so there is no PyTorch host tensor to pin and no nonblocking tensor transfer for the option to accelerate.
 
@@ -215,13 +215,13 @@ CohereLabs/cohere-transcribe-arabic-07-2026
 0a8193caa4f3f92131471ab08824e488141cb392
 ```
 
-Hub artifacts reuse the standard Hugging Face cache. Dense Safetensors and `pytorch_model.bin` weights are streamed into a GGUF conversion once and reused from `~/.cache/cohere-transcribe`. PyTorch metadata is decoded by a restricted, allowlist-only Ruby reader; it never imports Python or executes pickle globals. Current `torch.save` ZIP files and the preceding raw-storage stream format are supported, including sharded indexes and strided tensors. Ancient tar-format checkpoints are rejected because they cannot be interpreted with the same restricted weights-only contract; re-save those as Safetensors or a current state dict. The retained-session identity includes the resolved device and dtype as well as the model identity. Each converted artifact has an independent cache key for its output dtype and a SHA-256 source fingerprint over the model ID/revision, relative source paths, sizes, mtimes, and ctimes, so even a same-size, mtime-preserving rewrite invalidates a local fine-tune through its changed ctime. A sidecar completion marker binds that source fingerprint, output dtype, and cache layout to the converted GGUF's device, inode, size, mtime, and ctime. This marker is stored beside the model as `*.complete.json`. The cache accepts only regular, non-symlink GGUF/marker files; conversion locks use no-follow opens where available and verify that the opened descriptor still matches the path's device and inode.
+Hub artifacts reuse the standard Hugging Face cache. Symbolic branches and tags are revalidated while online; set `HF_HUB_OFFLINE=1` to resolve them only from an already complete cached snapshot. Dense Safetensors and `pytorch_model.bin` weights are streamed into a GGUF conversion once and reused from `~/.cache/cohere-transcribe`. PyTorch metadata is decoded by a restricted, allowlist-only Ruby reader; it never imports Python or executes pickle globals. Current `torch.save` ZIP files and the preceding raw-storage stream format are supported, including sharded indexes and strided tensors. Ancient tar-format checkpoints are rejected because they cannot be interpreted with the same restricted weights-only contract; re-save those as Safetensors or a current state dict. The retained-session identity includes the resolved device and dtype as well as the model identity. Each converted artifact has an independent cache key for its output dtype and a SHA-256 source fingerprint over the model ID/revision, relative source paths, sizes, mtimes, and ctimes, so even a same-size, mtime-preserving rewrite invalidates a local fine-tune through its changed ctime. A sidecar completion marker binds that source fingerprint, output dtype, and cache layout to the converted GGUF's device, inode, size, mtime, and ctime. This marker is stored beside the model as `*.complete.json`. The cache accepts only regular, non-symlink GGUF/marker files; conversion locks use no-follow opens where available and verify that the opened descriptor still matches the path's device and inode.
 
 Word mode uses `onnx-community/mms-300m-1130-forced-aligner-ONNX@2100fb247d8e43962eef24491597fbeb8b469531`, an ONNX export of `MahmoudAshraf/mms-300m-1130-forced-aligner@49402e9577b1158620820667c218cd494cc44486`. The default `align_dtype: "fp32"` works with the CPU provider even when Dense ASR runs on CUDA. `align_dtype: "fp16"` requires a CUDA-enabled ONNX Runtime; point `COHERE_TRANSCRIBE_ONNXRUNTIME_LIBRARY` at that runtime when it is not the one supplied by the installed `onnxruntime` gem. The runtime verifies the complete model file against a pinned byte size and SHA-256 before loading it. These downloaded model weights are CC-BY-NC-4.0 and are not distributed inside the gem; see `lib/cohere/transcribe/alignment/ATTRIBUTION.md` for provenance and notices.
 
 Useful environment variables:
 
-- `HF_TOKEN`, `HF_HOME`, `HF_HUB_CACHE`, `HF_ENDPOINT`
+- `HF_TOKEN`, `HF_HOME`, `HF_HUB_CACHE`, `HF_ENDPOINT`, `HF_HUB_OFFLINE`
 - `COHERE_TRANSCRIBE_CACHE`
 - `COHERE_TRANSCRIBE_NATIVE_LIBRARY`
 - `COHERE_TRANSCRIBE_AUDIO_LIBRARY`
@@ -254,7 +254,7 @@ Installed-gem WER measurements use the standalone runner documented in [`benchma
 
 ### Releasing
 
-Add a repository Actions secret named `RUBYGEMS_AUTH_TOKEN` containing a RubyGems API key with permission to push `cohere-transcribe`. Publishing a GitHub Release tagged `v0.1.1` runs the release workflow, verifies that the tag matches `Cohere::Transcribe::VERSION`, builds the exact `cohere-transcribe-0.1.1.gem` artifact, and pushes it to RubyGems.org.
+Add a repository Actions secret named `RUBYGEMS_AUTH_TOKEN` containing a RubyGems API key with permission to push `cohere-transcribe`. Publishing a GitHub Release tagged `v0.1.2` runs the release workflow, verifies that the tag matches `Cohere::Transcribe::VERSION`, builds the exact `cohere-transcribe-0.1.2.gem` artifact, and pushes it to RubyGems.org.
 
 Normal CI runs the Ruby suite, style checks, signature validation, native CPU build and ABI smoke checks, and source-gem build on Linux and macOS. It does not run the installed-gem WER or performance benchmarks.
 

data/ext/cohere_transcribe_native/CMakeLists.txt

@@ -1,4 +1,4 @@
-cmake_minimum_required(VERSION 3.14...3.31)
+cmake_minimum_required(VERSION 3.15...3.31)
 
 project(cohere_transcribe_native VERSION 0.8.9 LANGUAGES C CXX)
 

data/ext/cohere_transcribe_native/README.md

@@ -12,7 +12,7 @@ The gemspec should register `ext/cohere_transcribe_native/extconf.rb` in `spec.e
 
 Packaged builds define `GGML_BACKTRACE_NO_DEBUGGER`: fatal ggml diagnostics use the platform's in-process backtrace implementation and never fork or execute `gdb`/`lldb`. The upstream debugger-attaching behavior remains unchanged when the vendored ggml snapshot is built outside this gem's CMake project.
 
-CPU is the default. Optional build flags are:
+CPU is the default. Source builds require CMake 3.15 or newer and a C++20 compiler. CUDA builds require CMake 3.18 or newer. Optional build flags are:
 
 - `COHERE_TRANSCRIBE_NATIVE=1`: tune CPU code for the build machine.
 - `COHERE_TRANSCRIBE_OPENMP=1`: enable OpenMP.

data/ext/cohere_transcribe_native/extconf.rb

@@ -2,7 +2,9 @@
 
 require "fileutils"
 require "rbconfig"
+require "rubygems/version"
 require "shellwords"
+require "open3"
 
 EXTENSION_DIR = File.expand_path(__dir__)
 GEM_ROOT = File.expand_path("../..", EXTENSION_DIR)
@@ -22,8 +24,16 @@ abort "COHERE_TRANSCRIBE_CUDA=1 is only supported on Linux" if cuda && !host_os.
 abort "enable either CUDA or Metal, not both" if cuda && metal
 
 cmake = ENV.fetch("CMAKE", "cmake")
-unless system(cmake, "--version", out: File::NULL, err: File::NULL)
-  abort "cmake 3.14 or newer is required to build cohere-transcribe's native runtime"
+begin
+  cmake_output, cmake_status = Open3.capture2e(cmake, "--version")
+rescue SystemCallError
+  cmake_output = nil
+  cmake_status = nil
+end
+cmake_version_match = cmake_output&.match(/cmake version (\d+(?:\.\d+)+)/i)
+cmake_version = cmake_version_match && cmake_version_match[1]
+unless cmake_status&.success? && cmake_version && Gem::Version.new(cmake_version) >= Gem::Version.new("3.15")
+  abort "cmake 3.15 or newer is required to build cohere-transcribe's native runtime"
 end
 
 build_dir = File.expand_path(

data/lib/cohere/transcribe/asr/native.rb

@@ -297,6 +297,50 @@ module Cohere
           4 => :error
         }.freeze
 
+        # Keeps the native pointer independently of the Ruby session wrapper so
+        # ObjectSpace cleanup never retains the object it is meant to collect.
+        # Taking the pointer before calling the foreign close function makes
+        # explicit close, constructor rollback, and finalization idempotent.
+        class SessionOwnership
+          def initialize(library)
+            @library = library
+            @mutex = Mutex.new
+            @session = nil
+          end
+
+          def install(session)
+            @mutex.synchronize do
+              raise TranscriptionRuntimeError, "Native session ownership is already installed" if @session
+
+              @session = session
+            end
+          end
+
+          def close
+            session = @mutex.synchronize do
+              current = @session
+              @session = nil
+              current
+            end
+            return unless session
+
+            @library.call(:session_close, session)
+            nil
+          end
+
+          def finalize
+            close
+          rescue Exception # rubocop:disable Lint/RescueException -- finalizers must not escape during GC or shutdown
+            nil
+          end
+        end
+        private_constant :SessionOwnership
+
+        def self.finalizer_for(ownership)
+          proc { |_object_id| ownership.finalize }
+        end
+        private_class_method :finalizer_for
+
         attr_reader :backend, :batch_capacity, :compute_backend, :device, :last_batch_metrics, :model_path
 
         def initialize(model_path, options, threads: nil, library: NativeLibrary.load)
@@ -306,12 +350,24 @@ module Cohere
 
           @mutex = Mutex.new
           @closed = false
-          thread_count = normalize_threads(threads)
-          @session = @library.open_session(
-            model_path: @model_path,
-            device: options.device.to_s,
-            threads: thread_count
+          @session_ownership = SessionOwnership.new(@library)
+          ObjectSpace.define_finalizer(
+            self,
+            self.class.send(:finalizer_for, @session_ownership)
           )
+          thread_count = normalize_threads(threads)
+          # An asynchronous exception may become deliverable immediately after
+          # the foreign open returns. Defer it until the pointer belongs to the
+          # independent cleanup state, then let the constructor rescue close it.
+          Thread.handle_interrupt(Exception => :never) do
+            session = @library.open_session(
+              model_path: @model_path,
+              device: options.device.to_s,
+              threads: thread_count
+            )
+            @session_ownership.install(session)
+            @session = session
+          end
           @default_max_new_tokens = Integer(options.max_new_tokens)
           @library.call(:session_set_max_new_tokens, @session, @default_max_new_tokens)
           @library.call(:session_set_beam_size, @session, 1)
@@ -341,8 +397,12 @@ module Cohere
             close
             raise TranscriptionRuntimeError, "Native runtime reported an invalid Cohere batch capacity"
           end
-        rescue StandardError
-          close if defined?(@session) && @session
+        rescue Exception # rubocop:disable Lint/RescueException -- native ownership must roll back on Interrupt too
+          begin
+            close if defined?(@session_ownership)
+          rescue Exception # rubocop:disable Lint/RescueException -- preserve the constructor failure
+            nil
+          end
           raise
         end
 
@@ -449,9 +509,13 @@ module Cohere
           @mutex.synchronize do
             return if @closed
 
-            @library.call(:session_close, @session) if @library && @session
             @session = nil
             @closed = true
+            begin
+              @session_ownership&.close
+            ensure
+              ObjectSpace.undefine_finalizer(self)
+            end
           end
           nil
         end

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

@@ -131,16 +131,60 @@ module Cohere
           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?
+          SoundFileABI::SFInfo.malloc(Fiddle::RUBY_FREE) do |info|
+            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?
+            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
+        ensure
+          SoundFileABI.sf_close(handle) if defined?(handle) && handle && !handle.null?
+        end
+
+        # 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.
+        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?
+
+          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
+            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
+
+          SoundFileABI::SFInfo.malloc(Fiddle::RUBY_FREE) do |info|
+            handle = SoundFileABI.sf_open(source.to_s, SFM_READ, info.to_ptr)
+            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?
 
-          seconds = frames.fdiv(sample_rate)
-          seconds if seconds.finite? && seconds >= 0.0
+            input_bytes = frames * channels * Fiddle::SIZEOF_FLOAT
+            output_frames = (frames * sample_rate.fdiv(source_rate)).ceil + 64
+            [input_bytes, output_frames * Fiddle::SIZEOF_FLOAT].max
+          end
         rescue Fiddle::DLError, SystemCallError, TranscriptionRuntimeError
           nil
         ensure
@@ -195,64 +239,67 @@ module Cohere
             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
+          SoundFileABI::SFInfo.malloc(Fiddle::RUBY_FREE) do |info|
+            handle = SoundFileABI.sf_open(source.to_s, SFM_READ, info.to_ptr)
+            raise TranscriptionRuntimeError, "Cannot decode #{source}: #{SoundFileABI.sf_strerror(handle)}" if handle.null?
 
-            frames = read_frames
             begin
-              require "numo/narray"
-            rescue LoadError => e
-              raise TranscriptionRuntimeError, "numo-narray is required for decoded audio: #{e.message}"
+              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
+                     elsif channels == 2
+                       (interleaved.reshape(frames, channels).sum(1) * Math.sqrt(0.5)).cast_to(Numo::SFloat)
+                     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
-            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
 
@@ -277,26 +324,27 @@ module Cohere
           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})"
+          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
-          Numo::SFloat.from_binary(output_pointer[0, generated * Fiddle::SIZEOF_FLOAT])
         end
 
         def validate_finite!(samples)

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

@@ -111,6 +111,28 @@ module Cohere
           end
 
           def decode(path, sample_rate:, max_decoded_bytes:)
+            worker = Thread.new do
+              decode_owned(path, sample_rate: sample_rate, max_decoded_bytes: max_decoded_bytes)
+            end
+            worker.name = "cohere-ffmpeg-decode" if worker.respond_to?(:name=)
+            worker.report_on_exception = false
+            completed = false
+            result = worker.value
+            completed = true
+            result
+          ensure
+            if defined?(worker) && worker && !completed
+              Thread.handle_interrupt(Exception => :never) do
+                @functions.fetch(:cancel).call if worker.alive?
+              rescue StandardError
+                nil
+              ensure
+                worker.join
+              end
+            end
+          end
+
+          def decode_owned(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)
@@ -119,46 +141,51 @@ module Cohere
             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])
+            address = 0
+            Thread.handle_interrupt(Exception => :never) do
+              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")
+              begin
+                Thread.handle_interrupt(Exception => :immediate) do
+                  count = count_slot[0, Fiddle::SIZEOF_INT64_T].unpack1("q")
+                  detail = message.to_s.force_encoding(Encoding::UTF_8).scrub
+                  unless status.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?)
+                    raise TranscriptionRuntimeError, "Native FFmpeg returned invalid output metadata for #{path}"
+                  end
+
+                  bytes = count * Fiddle::SIZEOF_FLOAT
+                  if max_decoded_bytes && bytes > max_decoded_bytes
+                    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}"
+                  end
+                end
+              ensure
+                @functions.fetch(:free).call(address) unless address.zero?
               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
 
@@ -194,6 +221,8 @@ module Cohere
 
           private
 
+          private :decode_owned
+
           def c_string(value)
             Fiddle::Pointer["#{value}\0"]
           end

data/lib/cohere/transcribe/cli.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "optparse"
+require_relative "errors"
 require_relative "version"
 
 module Cohere

data/lib/cohere/transcribe/configuration.rb

@@ -207,6 +207,8 @@ module Cohere
 
         valid = valid_repository_id?(text)
         invalid!("#{option} must be a valid Hugging Face repository ID or local directory") unless valid
+      rescue EncodingError
+        invalid!("#{option} must be a valid Hugging Face repository ID or local directory")
       rescue ArgumentError => e
         invalid!(e.message)
       end