cohere-transcribe 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f494c8ad68293a60a51ea1510bd3ce55b81867f9014d4a5dcbd5c8499e970bde
-  data.tar.gz: efe16c2e6c4b0c2e4924716fc4023dffe0480375a075b8138c974b41dddb9115
+  metadata.gz: edcc763ef9c3c66e41fc508fb3c45fca037623e3fc3be03529c553b78f488a29
+  data.tar.gz: 675bf23b2dd0c1966a434e9e078ca45bcdc86154ae04c03fce72312801eb8f52
 SHA512:
-  metadata.gz: d43d30ab5c72a800e94148d368475aaf97a8f3a8ca97bd8ea24804783dcfea3450cef86accfdacd487064f6c7636c3811ca054d6f51c75a040dcc050a6634027
-  data.tar.gz: 7e506a692ae9025e4d825f5330a94685a2500f296745dbdf671bdf632799873278d88f21f93e1d36b9a382b8c8e1eae834a82267f7851da2e41b2371b6312f25
+  metadata.gz: 627b836b339dde2265e72f8adc73605052eada1a030b24f97b48720b1088b8139905b857a7a796da7e6b608903cc42c05bb50daa3db4b42537057820fc810e8d
+  data.tar.gz: 3f310c45da7aecfa19952b329b6b52bf878e4772491d234029b4a822b2ed79c3efefb6c403b6474f42038c9516e84312c46b59286fa1598bde8b0a4363515654

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## [0.1.3] - 2026-07-18
+
+- Close every libsndfile handle, directory descriptor, decoded buffer, and native session exactly once, defer thread termination through ownership handoffs and durable commit boundaries, cancel and join dedicated native workers before their callers terminate, reject empty native inference rows locally, and consolidate detached session ownership without retaining wrapper objects.
+- Match native FFmpeg mono mixing for standard multichannel and height-channel layouts across supported FFmpeg generations, obtain the FFmpeg version tuple through an optional native ABI symbol while retaining compatible older audio adapters, classify decoded-audio ceiling failures explicitly, prepare unknown sizes concurrently, retain successful grouped decodes across useful ceiling retries, release retained PCM before a full-ceiling retry, and keep lazy metadata probes on the caller's native stack.
+- Restore warm-cache Hub operation for temporary connection, rate-limit, server, malformed-JSON, and missing-or-invalid-commit responses while retaining online branch revalidation, bounded short-lived memoization, independent concurrent refreshes, bounded standard bare-SHA refs published atomically as best-effort hints, role-specific shared-cache modes for directories, immutable downloads, replaceable refs, and download locks, readable-lock fallback with clear remediation for inaccessible older locks, tolerant mode updates, repository-file listings that reject an empty or wholly malformed result, consistent public transient errors, and definitive authentication or missing-repository errors.
+- Reject invalid byte paths before transcription or publication, share byte-to-UTF-8 normalization across public surfaces, treat publication-parent changes during read-only verification as reprocessing decisions, reject inverted segment bounds, and coordinate output publication through output-adjacent locks that remain held across rescue contexts, propagate release failures, support shared directories and verified read-only skips, reject unowned multi-user-writable registries without a sticky bit, revalidate the authoritative lock at checkpoint and output commit boundaries, unify state and output recovery across exceptions, nonlocal exits, and thread termination, report incomplete recovery for ordinary failures and nonlocal exits with retained-backup paths and preserved causes, let pending thread termination remain terminal at every recovery stage, tolerate disappearance of the released 0.1.2 compatibility lock only while the canonical lock remains held, reject replacement even inside rescue contexts, and remove that compatibility path at the final 0.2.0 release while retaining it through prereleases.
+- Combine full-storage tensor checksum validation with conversion, simplify ZIP64 locator and checksum bookkeeping, preserve the discovered CUDA toolkit runtime path, and exclude untracked native build artifacts from locally built gems.
+- Match the pinned Python word-aligner geometry for sub-30-second audio, require exact command-line enum values, and use the public `OUTPUT_FORMATS` constant as the single accepted-format source for types and the CLI.
+
 ## [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.

data/README.md

@@ -18,7 +18,7 @@ The native extension builds a portable CPU backend by default. Accelerator avail
 
 Dense conversion and inference support F16, BF16, and F32 GGUF weights for the pinned checkpoint and compatible Dense fine-tunes. CPU execution resolves to FP32. CUDA `auto` selects BF16 when the loaded runtime reports hardware support and otherwise selects FP16; MPS `auto` selects FP16. An explicit unsupported BF16 accelerator request fails instead of silently changing precision.
 
-Audio decoding never launches the `ffmpeg` executable. The packaged `libcohere_audio` adapter dynamically binds a compatible libavformat/libavcodec/libavutil/libswresample tuple and decodes the first audio stream directly to mono 16 kHz float PCM. This path covers AAC, AIFF, ALAC, FLAC, M4A, MP3, MP4, Ogg/Vorbis, Opus, WAV, WebM, and WMA. Explicit `torchcodec` and `librosa` compatibility modes use the same FFmpeg codec runtime through that C ABI, preserving the complete accepted-format set while reporting the concrete decoder in result provenance. If the adapter is absent, `auto` and `librosa` can fall back to libsndfile/libsamplerate for the formats those libraries support.
+Audio decoding never launches the `ffmpeg` executable. The packaged `libcohere_audio` adapter dynamically binds a compatible libavformat/libavcodec/libavutil/libswresample tuple and decodes the first audio stream directly to mono 16 kHz float PCM. This path covers AAC, AIFF, ALAC, FLAC, M4A, MP3, MP4, Ogg/Vorbis, Opus, WAV, WebM, and WMA. Explicit `torchcodec` and `librosa` compatibility modes use the same FFmpeg codec runtime through that C ABI, preserving the complete accepted-format set while reporting the concrete decoder in result provenance. If the adapter is absent, `auto` and `librosa` can fall back to libsndfile/libsamplerate for the formats those libraries support. Audio adapters built before version metadata was added remain loadable; without that metadata the Ruby wrapper uses the older channel-layout table, which is identical for common inputs with eight or fewer channels but can differ for unusual 14- or 16-channel layouts.
 
 The FFmpeg adapter gives duration probes and full decodes monotonic deadlines (30 seconds and one hour, respectively) and shares a generation-based cooperative cancellation hook. It supplies FFmpeg's public `AVIOInterruptCB` to input I/O and also checks cancellation between codec and resampler calls. Cancellation therefore takes effect when FFmpeg invokes that callback or returns control; it does not forcibly unwind an uninterruptible codec or system call.
 
@@ -126,7 +126,7 @@ ensure
 end
 ```
 
-Inputs may be a string, a path-like object, or an ordered array of files and directories. Directory expansion is deterministic, recursive by default, and deduplicates canonical paths. A run preserves that expanded order and provides `successful`, `failed`, `skipped`, `single`, and `ok?` helpers.
+Inputs may be a string, a path-like object, or an ordered array of files and directories. Public path and model-reference strings must contain valid UTF-8 bytes; binary-encoded strings containing valid UTF-8 are normalized without changing their bytes, while undecodable byte names are rejected before work begins. Directory expansion is deterministic, recursive by default, and deduplicates canonical paths. A run preserves that expanded order and provides `successful`, `failed`, `skipped`, `single`, and `ok?` helpers.
 
 Per-file media failures are returned as failed results so the rest of a batch can finish. Pass `raise_on_error: true` to raise `BatchTranscriptionError`; its `run` still contains every completed result.
 
@@ -162,7 +162,9 @@ run = Cohere::Transcribe.transcribe("recordings", options: options)
 
 All formats for one source are staged before commit. Existing outputs are preserved if staging fails, and directory-relative structure is retained beneath `output_dir`.
 
-Durable publication binds the planned output root and parent directory inodes, then performs staging, backup, commit, rollback, and cleanup relative to a retained directory descriptor. This prevents a concurrent directory rename or symlink replacement from redirecting transcript, checkpoint, manifest, or profile bytes. Publication fails closed if the planned path identity changes or if the platform lacks `O_NOFOLLOW` and the POSIX `openat`, `renameat`, and `unlinkat` primitives; the supported Linux and macOS targets provide them.
+Concurrent publishers coordinate through a persistent `.cohere-transcribe-locks` directory beside the outputs. Its access mode follows the output directory so collaborators who can publish there can use the same locks. New or current-user-owned shared writable registries receive the sticky bit where the filesystem supports it; an unowned multi-user-writable registry without that bit is rejected with remediation guidance. The authoritative output-adjacent lock is revalidated at checkpoint and output commit boundaries, so replacing its path aborts the commit even on filesystems that cannot retain the sticky bit. A fully verified `existing: "skip"` run does not need to create or modify the lock directory. The 0.1 release series also acquires the released 0.1.2 temporary lock for mixed-version coordination; disappearance of that temporary path is tolerated only while the canonical lock remains held, replacement is rejected even when verification runs inside a rescue handler, compatibility remains enabled through 0.2.0 prereleases, and the path is removed at the final 0.2.0 release. A filesystem that rejects an exclusive lock on an otherwise read-only lock file returns a typed runtime error; it never substitutes a non-exclusive lock.
+
+Durable publication binds the planned output root and parent directory inodes, then performs staging, backup, commit, rollback, and cleanup relative to a retained directory descriptor. A concurrent directory rename or symlink replacement therefore cannot redirect transcript, checkpoint, manifest, or profile bytes. If an exception or nonlocal exit leaves recovery incomplete before commit completion, the typed failure names every retained backup or temporary and preserves the original exception as its cause. Thread termination still attempts rollback and cleanup but remains terminal even when that recovery is incomplete. Ordinary post-commit cleanup failures are also typed; once a commit is durable, post-commit cleanup remains best effort during termination. Publication returns a typed error if the planned path identity changes or if the platform lacks `O_NOFOLLOW` and the POSIX `openat`, `renameat`, and `unlinkat` primitives; the supported Linux and macOS targets provide them.
 
 Publication state records the source's canonical path, device, inode, size, nanosecond mtime, and nanosecond ctime, plus checksums for the state payload and published artifacts. With `existing: "skip"`, a verified manifest is resolved before PCM decode, VAD, or a Dense model session is opened; a best-effort metadata duration probe supplies the skipped result's duration without materializing PCM.
 
@@ -187,7 +189,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 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.
+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. Files without usable estimates initially share the group cap equally. A file whose known estimate exceeds the group cap is prepared alone with the full `audio_memory_gb` ceiling and no adjacent-group overlap. If metadata is missing or underestimates one grouped decode, only that file is retried while successful decoded audio remains retained whenever the remaining configured PCM budget is sufficient. If the retry still needs the complete ceiling, retained audio after that file is released and only those successful entries are prepared again in order; unrelated failures are not repeated. 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.
 
@@ -202,7 +204,7 @@ The packed-Torch tuning options remain effective without Python. For requested `
 The packaged graph has temporal input `[seq_len, 576]` but recurrent h/c inputs fixed at `[1, 1, 128]`; it has no file-batch axis, lengths, or mask. Concatenating files would therefore leak recurrent state between recordings. Ruby instead uses one thread-confined session per active file and makes `vad_batch_size` an upper bound on that independent-file concurrency for requested `auto`/`torch`. The effective count is also bounded by `preprocess_workers`, CPU availability, group size, and the sequential preparation mode. Profiles consequently report `max_files_per_call: 1`, exact temporal model-call/frame counts, and provider options matching ONNX Runtime introspection (`CPUExecutionProvider: {}`), while the configured batch/block values and effective temporal block remain visible.
 - `vad: "auditok"` uses a native Ruby implementation of Auditok's 50 ms PCM16 log-RMS tokenizer.
 - `vad: "none"` creates bounded fixed windows using `max_dur`.
-- `alignment: "word"` computes full-file emissions with the exact pinned MMS-300M forced-aligner ONNX export, then runs a pure-Ruby float32 CTC Viterbi kernel. An unalignable segment alone falls back to bounded uniform timing without dropping transcript words.
+- `alignment: "word"` computes full-file emissions with the exact pinned MMS-300M forced-aligner ONNX export, then runs a pure-Ruby float32 CTC Viterbi kernel. Audio shorter than 30 seconds follows the pinned aligner's direct waveform geometry; inputs shorter than its 400-sample receptive field receive only the minimum right padding. An unalignable segment alone falls back to bounded uniform timing without dropping transcript words.
 - `alignment: "segment"` distributes words uniformly over the segment's speech spans.
 - `alignment: "none"` returns plain text without words or cues.
 
@@ -215,7 +217,7 @@ CohereLabs/cohere-transcribe-arabic-07-2026
 0a8193caa4f3f92131471ab08824e488141cb392
 ```
 
-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.
+Hub artifacts reuse the standard Hugging Face cache. Symbolic branches and tags are revalidated while online with a bounded per-client memo of at most five seconds; concurrent misses refresh independently and each caller uses its own fetched commit. Standard bare-SHA ref reads are capped at 41 bytes, and ref files are atomically replaced as best-effort cache hints without invalidating a valid online result when the cache is unreadable or read-only. Shared-cache directories preserve setgid and execute-gated access; snapshot directories receive a sticky bit where supported, ref directories remain replaceable for atomic collaborator updates, immutable payloads and refs inherit collaborator read access without write access, and download locks inherit the read/write access needed for coordination. Mode updates that the filesystem cannot represent are tolerated, current-user-owned older cache entries are upgraded when possible, readable non-writable locks can still coordinate where the filesystem permits an exclusive lock, and an inaccessible older lock returns a typed error with remediation instead of being replaced while it may still be held. Temporary connection, rate-limit, server, malformed-JSON, or missing-or-invalid-commit responses can reuse a complete cached file snapshot, while authentication and missing-repository responses remain definitive errors. Malformed individual repository-file entries are ignored when valid siblings remain, but an empty or wholly malformed listing is reported directly. Set `HF_HUB_OFFLINE=1` to resolve symbolic revisions only from an already complete cached snapshot; an offline symbolic revision remains at its last successfully cached commit until a later online refresh succeeds. 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. Cross-process output locks use an output-adjacent `.cohere-transcribe-locks/` registry derived from the canonical output set and also acquire the released 0.1.2 temporary lock during this transition.
 
 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.
 
@@ -254,7 +256,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.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.
+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 `0.1.3` runs the release workflow, verifies that the tag matches `Cohere::Transcribe::VERSION`, builds the exact `cohere-transcribe-0.1.3.gem` artifact, and pushes it to RubyGems.org. A leading `v` is also accepted by the release check.
 
 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/.gitignore

@@ -0,0 +1,6 @@
+/Makefile
+/build/
+/cuda-build/
+/stage/
+/cuda-stage/
+/mkmf.log

data/ext/cohere_transcribe_native/CMakeLists.txt

@@ -200,6 +200,14 @@ endif()
 if(COHERE_TRANSCRIBE_CUDA)
     target_compile_definitions(crispasr PRIVATE GGML_USE_CUDA)
     target_link_libraries(crispasr PRIVATE ggml-cuda)
+    # Source gems are compiled on the destination machine. Preserve the exact
+    # toolkit library directory found by CMake so non-system CUDA installs
+    # (including tarball and environment-managed toolkits) remain loadable after
+    # RubyGems moves libcrispasr out of the build tree.
+    set_property(TARGET crispasr APPEND PROPERTY
+        BUILD_RPATH "${CUDAToolkit_LIBRARY_DIR}")
+    set_property(TARGET crispasr APPEND PROPERTY
+        INSTALL_RPATH "${CUDAToolkit_LIBRARY_DIR}")
 endif()
 
 if(MSVC)

data/ext/cohere_transcribe_native/audio_abi.cpp

@@ -1338,6 +1338,26 @@ COHERE_AUDIO_EXPORT int cohere_audio_ffmpeg_probe(char* diagnostic, std::size_t
     }
 }
 
+COHERE_AUDIO_EXPORT int cohere_audio_ffmpeg_versions(int* versions, std::size_t count) {
+    if (versions && count > 0)
+        std::fill_n(versions, std::min<std::size_t>(count, 4), 0);
+    if (!versions || count < 4)
+        return 2;
+
+    try {
+        Runtime& api = runtime();
+        if (!api.available)
+            return 1;
+        versions[0] = api.format_major;
+        versions[1] = api.codec_major;
+        versions[2] = api.util_major;
+        versions[3] = api.resample_major;
+        return 0;
+    } catch (...) {
+        return 1;
+    }
+}
+
 COHERE_AUDIO_EXPORT int cohere_audio_ffmpeg_decode(
     const char* path,
     int target_rate,

data/ext/cohere_transcribe_native/audio_exports.macos

@@ -1,4 +1,5 @@
 _cohere_audio_ffmpeg_probe
+_cohere_audio_ffmpeg_versions
 _cohere_audio_ffmpeg_decode
 _cohere_audio_ffmpeg_duration
 _cohere_audio_ffmpeg_cancel

data/ext/cohere_transcribe_native/audio_exports.map

@@ -1,6 +1,7 @@
 {
     global:
         cohere_audio_ffmpeg_probe;
+        cohere_audio_ffmpeg_versions;
         cohere_audio_ffmpeg_decode;
         cohere_audio_ffmpeg_duration;
         cohere_audio_ffmpeg_cancel;

data/ext/cohere_transcribe_native/test/abi_smoke.rb

@@ -154,6 +154,7 @@ abort "no packaged libcohere_audio found in #{directory}" unless audio_library
 audio_handle = Fiddle::Handle.new(audio_library, Fiddle::RTLD_NOW)
 audio_symbols = %w[
   cohere_audio_ffmpeg_probe
+  cohere_audio_ffmpeg_versions
   cohere_audio_ffmpeg_decode
   cohere_audio_ffmpeg_duration
   cohere_audio_ffmpeg_cancel
@@ -171,7 +172,32 @@ probe_status = probe.call(diagnostic, 1_024)
 raise "audio probe returned an invalid status" unless [0, 1].include?(probe_status)
 raise "audio probe returned no diagnostic" if diagnostic.to_s.empty?
 
+versions = Fiddle::Function.new(
+  audio_handle["cohere_audio_ffmpeg_versions"],
+  [Fiddle::TYPE_VOIDP, Fiddle::TYPE_SIZE_T],
+  Fiddle::TYPE_INT
+)
+raise "audio versions accepted a null output" unless versions.call(0, 0) == 2
+
 if probe_status.zero?
+  tuple_bytes = 4 * Fiddle::SIZEOF_INT
+  tuple = Fiddle::Pointer.malloc(tuple_bytes, Fiddle::RUBY_FREE)
+  tuple[0, tuple_bytes] = [0, 0, 0, 0].pack("i!*")
+  raise "audio versions call failed" unless versions.call(tuple, 4).zero?
+
+  format_major, codec_major, util_major, resample_major = tuple[0, tuple_bytes].unpack("i!4")
+  raise "audio versions returned an incompatible format/codec tuple" unless format_major == codec_major
+  raise "audio versions returned an incompatible avutil major" unless util_major == format_major - 2
+
+  expected_resample = if format_major == 58
+                        3
+                      elsif format_major <= 60
+                        4
+                      else
+                        format_major - 56
+                      end
+  raise "audio versions returned an incompatible swresample major" unless resample_major == expected_resample
+
   duration = Fiddle::Function.new(
     audio_handle["cohere_audio_ffmpeg_duration"],
     [Fiddle::TYPE_VOIDP, Fiddle::TYPE_VOIDP, Fiddle::TYPE_VOIDP, Fiddle::TYPE_SIZE_T],

data/lib/cohere/transcribe/alignment/aligner.rb

@@ -231,6 +231,7 @@ module Cohere
         WINDOW_SAMPLES = WINDOW_SECONDS * SAMPLE_RATE
         CONTEXT_SAMPLES = CONTEXT_SECONDS * SAMPLE_RATE
         INPUT_SAMPLES = WINDOW_SAMPLES + (2 * CONTEXT_SAMPLES)
+        MINIMUM_INPUT_SAMPLES = 400
         WINDOW_FRAMES = WINDOW_SAMPLES / INPUTS_TO_LOGITS_RATIO
         CONTEXT_FRAMES = CONTEXT_SAMPLES / INPUTS_TO_LOGITS_RATIO
         STRIDE_MS = INPUTS_TO_LOGITS_RATIO * 1_000.0 / SAMPLE_RATE
@@ -289,6 +290,7 @@ module Cohere
           started = monotonic
           samples = mono_float32(audio)
           raise ArgumentError, "Cannot compute CTC emissions for empty audio" if samples.empty?
+          return [compute_direct_emissions(samples), STRIDE_MS] if samples.length < WINDOW_SAMPLES
 
           total_windows = (samples.length + WINDOW_SAMPLES - 1) / WINDOW_SAMPLES
           extension_samples = (total_windows * WINDOW_SAMPLES) - samples.length
@@ -320,10 +322,7 @@ module Cohere
             end
 
             class_count = batch_log_probs.shape[1]
-            unless class_count == VOCABULARY.length
-              raise TranscriptionRuntimeError,
-                    "MMS aligner returned #{class_count} classes; expected #{VOCABULARY.length}"
-            end
+            validate_class_count!(class_count)
             emissions ||= Numo::SFloat.zeros(frame_count, class_count + 1)
             if first_window + window_count == total_windows && extension_frames.positive?
               kept = batch_log_probs.shape[0] - extension_frames
@@ -440,6 +439,29 @@ module Cohere
           batch
         end
 
+        # The pinned ctc-forced-aligner passes sub-30-second waveforms to MMS
+        # directly, without window context or tail padding. Its Wav2Vec2 feature
+        # extractor needs at least its 400-sample convolutional receptive field,
+        # so only shorter inputs receive the minimum right padding needed to run.
+        def compute_direct_emissions(audio)
+          input_samples = [audio.length, MINIMUM_INPUT_SAMPLES].max
+          input = Numo::SFloat.zeros(1, input_samples)
+          input[0, 0...audio.length] = audio
+          logits = session.run(input)
+          logits = Numo::SFloat.cast(logits) unless logits.is_a?(Numo::NArray)
+          unless logits.ndim == 3 && logits.shape[0] == 1 && logits.shape[1].positive?
+            raise TranscriptionRuntimeError,
+                  "MMS aligner returned invalid direct logits shape #{logits.shape.inspect}"
+          end
+
+          class_count = logits.shape[2]
+          validate_class_count!(class_count)
+          log_probs = log_softmax(logits.reshape(logits.shape[1], class_count))
+          emissions = Numo::SFloat.zeros(log_probs.shape[0], class_count + 1)
+          emissions[true, 0...class_count] = log_probs
+          emissions
+        end
+
         def crop_and_normalize(logits, expected_batch)
           logits = Numo::SFloat.cast(logits) unless logits.is_a?(Numo::NArray)
           unless logits.ndim == 3 && logits.shape[0] == expected_batch &&
@@ -451,12 +473,23 @@ module Cohere
           classes = logits.shape[2]
           cropped = logits[true, CONTEXT_FRAMES...(CONTEXT_FRAMES + WINDOW_FRAMES), true]
                     .reshape(expected_batch * WINDOW_FRAMES, classes)
-          maxima = cropped.max(1).reshape(cropped.shape[0], 1)
-          shifted = cropped - maxima
-          denominators = Numo::NMath.log(Numo::NMath.exp(shifted).sum(1)).reshape(cropped.shape[0], 1)
+          log_softmax(cropped)
+        end
+
+        def log_softmax(logits)
+          maxima = logits.max(1).reshape(logits.shape[0], 1)
+          shifted = logits - maxima
+          denominators = Numo::NMath.log(Numo::NMath.exp(shifted).sum(1)).reshape(logits.shape[0], 1)
           (shifted - denominators).cast_to(Numo::SFloat)
         end
 
+        def validate_class_count!(class_count)
+          return if class_count == VOCABULARY.length
+
+          raise TranscriptionRuntimeError,
+                "MMS aligner returned #{class_count} classes; expected #{VOCABULARY.length}"
+        end
+
         def uniform_fallback(text, start_time, end_time, segment_index)
           Output::Timing.uniform_words(
             text, start_time, end_time, segment_index, "uniform_fallback"

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

@@ -4,6 +4,8 @@ require "etc"
 require "fiddle"
 require "rbconfig"
 require_relative "../errors"
+require_relative "../internal/interruptible_native_call"
+require_relative "../internal/session_ownership"
 require_relative "../python_text"
 require_relative "failure_policy"
 
@@ -297,69 +299,38 @@ 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
+        # A callable retained by detached ownership state. It keeps the native
+        # library alive, but never captures the NativeSession being finalized.
+        NativeSessionCloser = Data.define(:library) do
+          def call(session)
+            library.call(:session_close, session)
           end
         end
-        private_constant :SessionOwnership
-
-        def self.finalizer_for(ownership)
-          proc { |_object_id| ownership.finalize }
-        end
-        private_class_method :finalizer_for
+        private_constant :NativeSessionCloser
 
         attr_reader :backend, :batch_capacity, :compute_backend, :device, :last_batch_metrics, :model_path
 
         def initialize(model_path, options, threads: nil, library: NativeLibrary.load)
+          initialized = false
           @library = library
           @model_path = Pathname.new(model_path).expand_path.freeze
           raise TranscriptionRuntimeError, "Native Dense model does not exist: #{@model_path}" unless @model_path.file?
 
           @mutex = Mutex.new
           @closed = false
-          @session_ownership = SessionOwnership.new(@library)
+          @session_ownership = Internal::SessionOwnership.new(
+            close: NativeSessionCloser.new(@library),
+            installed_error: "Native session ownership is already installed"
+          )
           ObjectSpace.define_finalizer(
             self,
-            self.class.send(:finalizer_for, @session_ownership)
+            Internal::SessionOwnership.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
+          # independent cleanup state, then let constructor teardown close it.
+          Thread.handle_interrupt(Object => :never) do
             session = @library.open_session(
               model_path: @model_path,
               device: options.device.to_s,
@@ -397,25 +368,29 @@ module Cohere
             close
             raise TranscriptionRuntimeError, "Native runtime reported an invalid Cohere batch capacity"
           end
-        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
+          initialized = true
+        ensure
+          unless initialized
+            Thread.handle_interrupt(Object => :never) do
+              close if defined?(@session_ownership)
+            rescue Exception # rubocop:disable Lint/RescueException -- preserve constructor termination
+              nil
+            end
           end
-          raise
         end
 
         def transcribe(samples, language:, offset: 0.0, max_new_tokens: nil)
           @mutex.synchronize do
             ensure_open!
             @last_batch_metrics = nil
-            generation_limit = max_new_tokens.nil? ? @default_max_new_tokens : Integer(max_new_tokens)
-            set_generation_limit!(generation_limit)
             binary, sample_count = float_samples(samples)
+            raise ArgumentError, "Audio segment must not be empty" if sample_count.zero?
             raise TranscriptionRuntimeError, "Audio segment is too large for the native ABI" \
               if sample_count > MAX_NATIVE_SAMPLE_COUNT
 
+            generation_limit = max_new_tokens.nil? ? @default_max_new_tokens : Integer(max_new_tokens)
+            set_generation_limit!(generation_limit)
+
             run_native_inference do
               result = @library.call(
                 :session_transcribe_lang,
@@ -452,16 +427,19 @@ module Cohere
           @mutex.synchronize do
             ensure_open!
             @last_batch_metrics = nil
-            generation_limit = max_new_tokens.nil? ? @default_max_new_tokens : Integer(max_new_tokens)
-            set_generation_limit!(generation_limit)
-
             buffers_and_counts = sample_batches.map { |samples| float_samples(samples) }
+            empty_lane = buffers_and_counts.index { |_binary, count| count.zero? }
+            raise ArgumentError, "Audio batch row #{empty_lane} must not be empty" if empty_lane
+
             oversized_lane = buffers_and_counts.index { |_binary, count| count > MAX_NATIVE_SAMPLE_COUNT }
             if oversized_lane
               raise TranscriptionRuntimeError,
                     "Audio batch row #{oversized_lane} is too large for the native ABI"
             end
 
+            generation_limit = max_new_tokens.nil? ? @default_max_new_tokens : Integer(max_new_tokens)
+            set_generation_limit!(generation_limit)
+
             run_native_inference do
               pointers = buffers_and_counts.map { |binary, _count| Fiddle::Pointer[binary] }
               pointer_table = pointers.map(&:to_i).pack("J*")
@@ -558,51 +536,19 @@ module Cohere
 
         # Ruby cannot deliver Thread#raise (including SIGINT's Interrupt) while
         # the receiving thread is blocked inside Fiddle. Keep the caller at an
-        # interruptible join while a private worker owns the foreign call. The
+        # interruptible join while a dedicated worker owns the foreign call. The
         # caller still holds @mutex, so close and another inference cannot race
         # the session; cancellation is the only concurrent C ABI operation.
-        def run_native_inference
-          outcome = Queue.new
-          worker = nil
-          Thread.handle_interrupt(Exception => :on_blocking) do
-            worker = Thread.new do
-              outcome << [:returned, yield]
-            rescue Exception => e # rubocop:disable Lint/RescueException -- transfer native cancellation intact
-              outcome << [:raised, e]
-            end
-            worker.report_on_exception = false
-
-            begin
-              worker.join
-            rescue Exception => e # rubocop:disable Lint/RescueException -- caller cancellation must win
-              cancel_and_hard_join(worker)
-              raise e
-            end
-          end
-
-          status, value = begin
-            outcome.pop(true)
-          rescue ThreadError
-            raise ExecutionError.new(
+        def run_native_inference(&)
+          Internal::InterruptibleNativeCall.run(
+            cancel: -> { @library.call(:session_cancel, @session) },
+            join_interval: CANCELLATION_JOIN_INTERVAL,
+            missing_outcome: ExecutionError.new(
               "Native Cohere inference worker exited without reporting an outcome",
               failure_kind: :fatal
-            )
-          end
-          raise value if status == :raised
-
-          value
-        end
-
-        # A cancellation can arrive after Thread.new but before the worker has
-        # entered the C function. Retry the non-poisoning session cancel until
-        # the worker exits; never kill a thread that may still own ggml state.
-        def cancel_and_hard_join(worker)
-          loop do
-            @library.call(:session_cancel, @session)
-            return if worker.join(CANCELLATION_JOIN_INTERVAL)
-          rescue Exception # rubocop:disable Lint/RescueException -- preserve the first caller exception
-            next
-          end
+            ),
+            &
+          )
         end
 
         def canonical_device(name)