fix(cli): report transcription language and progress

[miguel-heygen]

Whisper's language probe read stdout even though the native detector logs to stderr, so multilingual transcription could silently use the English default. Decode with automatic language selection and carry the native result into detectedLanguage; explicit language choices and English-only models report null.

transcribe --json now keeps one final result on stdout and emits typed progress JSON lines on stderr. Whisper model downloads report bytes with a nullable total, transcription reports start/completion, and slow stderr readers receive coalesced byte updates. Other diagnostics may still appear on stderr. The transcript file remains a word array, and model reports the resolved model.

Add --no-runtime-install to prevent Homebrew/source installation, including during automatic fallback. Model downloads remain allowed.

Validation: focused test files passed individually three times with one worker; nine deliberate behavioral mutations were rejected. A native Whisper run exercised a real model download and automatic detection through the CLI. A separate doctor-to-transcribe disappearance check confirmed zero installer commands. Typecheck, lint, format, dead-code/complexity checks, and packaged CLI build passed.

Native inference was exercised on Linux. Parakeet's external MLX downloader does not expose byte progress through this interface; its transcription phase remains indeterminate.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
hyperframes	🟢 Ready	View Preview	Oct 6, 2026, 3:11 AM

💡 Tip: Enable Automations to automatically generate PRs for you.

[jrusso1020]

Approve at 366f1acc.

The language fix is correct. whisper.cpp logs auto-detected language through WHISPER_LOG_INFO (stderr) and defaults --language to en. So the old stdout probe never matched, and multilingual models decoded as English. Reading result.language from the full JSON, and only when the language was selected automatically, is the right shape.

The reported model is now the resolved one: small.en --language es reports small.

--no-runtime-install exits non-zero before any brew/git/cmake call, including on the auto fallback. The default path is unchanged.

stdout stays clean. With a stub runtime, stdout carries exactly one result. The in-repo callers (media-use, embedded-captions, tts) read stdout or transcript.json, so they're unaffected.

Tests:

• The whisper, transcribe, models and download suites pass 211/211.
• tsc, oxlint and oxfmt are clean.
• Mutating the install guard, the auto-language gate or the progress writer each fails a test.

Overlap with #5095: the two conflict textually in one hunk, transcribeWithSherpa in whisper/sherpa.ts. Keeping both sides typechecks and passes the suite, so merge order doesn't matter. Whoever lands second resolves that hunk and decides whether started comes before or after the runtime selection.

Non-blocking

1. --json now always streams progress on stderr (commands/transcribe.ts:350).
   • Elsewhere in the CLI, --json means one result and no progress: models --json, cloud render, and the notices suppressed in cli.ts.
   • On a first model download this is hundreds to thousands of lines, and skills that run transcribe --json in an agent shell will surface all of it.
   • Consider an explicit opt-in such as --progress json, or a much coarser interval.
2. With the 100 ms throttle in download.ts, the backpressure coalescing in whisper/progress.ts (and its test) is probably unnecessary. A direct process.stderr.write(JSON.stringify(event) + "\n") would do.
3. Parakeet's started/completed events could be emitted once around run(r) in the command instead of inside sherpa.ts and parakeet.ts. That's less code, and it avoids the conflict with #5095. Whisper's events need to stay where they are so they follow the download.
4. Under --json, stderr can still carry non-JSON lines (the auto fallback warning), and there's no failed status. A consumer therefore sees a Parakeet started followed by a Whisper started. Either state in the contract that parsers must skip non-JSON lines, or add a failed record.
5. An explicit --language auto runs detection but reports detectedLanguage: null, because the gate is options.language === undefined.
6. The whisper_unavailable JSON result doesn't say that installation was disabled, and the new human message drops the install hint from getInstallInstructions().
7. docs/packages/cli.mdx is missing a --no-runtime-install row, a stderr note on --json, and detectedLanguage.

— Rames

[github-actions]

Edit accuracy: accurate 2055 (base branch 2055), smooth 1625 of those

The gate passes.
Smoothness is reported in the artifact, not gated. A case fails only if it fails 2 of 3 runs.

Quarantined, measured but not gated (0)