fix(audio): reliable Whisper transcription + long-form + model-agnostic transcribe CLI (#119)

[Pushkinist]

Closes #119.

Problem

POST /v1/audio/transcriptions was unreliable on real speech — mostly empty
transcripts, sometimes wrong-script garbage, only occasionally correct. Model
load + mel front-end were fine; the defect was in greedy_decode's logit
handling (no in-loop suppression, timestamp tokens treated as a hard stop, raw
logits to the sampler). There was also no long-form support (audio >30s
silently truncated), no transcribe CLI, and the referenced smoke test did not
exist.

Root cause (deeper than the issue stated)

whisper-large-v3 has 100 language slots (<|en|>=50259 … <|yue|>=50358),
shifting every special token +1 vs the v1/v2 layout the constants assumed. So
TOK_TRANSCRIBE actually pointed at <|translate|> and the >= TOK_TIMESTAMP_BEGIN
halt fired on <|notimestamps|> → immediate stop (empty/garbage). Fixed the
special-token constants to the large-v3 layout and added faithful in-loop logit
filters.

Changes

• P0 decode correctness — DecodeFilters (SuppressBlank + SuppressTokens
  • faithful ApplyTimestampRules) applied every step on a host f32 logit
    vector; suppress set derived generally from the tokenizer (not a hardcoded id
    list); large-v3 special-token constants corrected; timestamp tokens no longer
    an unconditional halt.
• P1 long-form — new rmlx_audio::transcribe::Transcriber: 30s sliding
  windows, timestamp-driven seek, <|startofprev|> previous-text conditioning,
  real cumulative per-segment timestamps, multi-segment vtt/srt/json/txt,
  trailing-silence hallucination drop. Decode bounds derived from n_text_ctx
  at runtime (prompt cap n/2-1, per-window budget min(n/2, n-prefix), plus a
  decode-loop offset ceiling) so the positional table can never overflow.
• P2 rmlx transcribe CLI — rmlx transcribe <audio> --model <snapshot> [--tokenizer --format vtt|srt|json|txt --language --translate --output],
  arch-dispatched on config.json model_type (clean seam for future ASR;
  Whisper today, not hardcoded). Decodes arbitrary containers to 16kHz mono
  internally (stereo downmix + linear resampler; enabled existing symphonia
isomp4+aac features for m4a/MP4-AAC). HTTP endpoint routed through the same
  long-form engine — one transcription core, not two.
• P3 polish — npz alignment_heads dtype parsing; verbose_json now reports
  real duration + segments.
• Tests / env cleanup — removed the single-purpose RMLX_TEST_MODEL_WHISPER
  env var in favor of RMLX_O_MODELS_ROOT auto-discovery (skips gracefully when
  absent). Added a portable say-generated determinism smoke + a local
  real-recording long-form WER regression that scans a gitignored fixtures dir
  (any user drops their own audio + .transcript.vtt). Model-free regression
  tests prove the positional-table bound across n_text_ctx sweeps.

Proof on real audio

Full 48-minute meeting recording, whisper-large-v3-mlx, temp=0:

• Normalized WER = 0.0792 (684 word-edits / 8636 ref words) — gate ≤ 0.30.
• Full coverage (last cue 48:20.858), run completes cleanly, no positional error.
• Deterministic: two runs byte-identical (diff -q clean).
• Decode ≈ 236–265s for 2900s audio → RTF ≈ 0.08–0.09 (~11× realtime).
• say-clip smoke: WER 0.000, deterministic.

make lint (-D warnings) and make test green. Reviewed by the rust-reviewer
agent; the one HIGH (positional overflow) and nits are fixed in the second commit.

🤖 Generated with Claude Code