@drakulavich/kesha-voice-kit 1.28.0-alpha.1 → 1.29.1

package/README.md

@@ -36,14 +36,14 @@ bun add -g @drakulavich/kesha-voice-kit
 kesha --version                                 # confirms `kesha` resolved on PATH
 
 # 3. Download the engine and models — pick one path
-kesha init                                      # guided: backend, languages, TTS voices
+kesha init                                      # guided: TTS languages and optional VAD / diarization
 kesha install --plan && kesha install           # manual: preview the sizes, then download
 
 # 4. Transcribe
 kesha audio.ogg                                 # transcript to stdout
 ```
 
-`kesha install` pulls ~2.5 GB on Linux/Windows and ~0.6 GB on Apple Silicon, whose CoreML engine reads a smaller model set. It is always explicit — nothing downloads behind your back — and the model step has no progress bar, so expect a few quiet minutes. If `bun --version` fails right after step 1, reload your PATH: `exec $SHELL -l`.
+`kesha install` pulls ~2.5 GB on Linux/Windows and ~0.6 GB on Apple Silicon, whose CoreML engine reads a smaller model set. It is always explicit — nothing downloads behind your back — and reports download progress on stderr. If `bun --version` fails right after step 1, reload your PATH: `exec $SHELL -l`.
 
 Prefer Homebrew or Docker? See [Other install methods](#other-install-methods).
 Air-gapped or behind a corporate mirror? See [docs/model-mirror.md](docs/model-mirror.md).
@@ -90,15 +90,16 @@ $ kesha freedom.ogg tahiti.ogg
 ```
 
 - **Record from the mic (macOS):** `kesha record --out hello.wav` writes microphone audio to a WAV file (`kesha hello.wav` transcribes it). macOS prompts for microphone access on first use — grant it under System Settings → Privacy & Security → Microphone if it was denied. On Linux/Windows or headless boxes, pass any existing audio file straight to `kesha` instead.
-- **Dictate straight to text (darwin-arm64):** `kesha record --live` transcribes the mic as it captures and prints the transcript to stdout — no WAV in between, so it pipes (`kesha record --live | pbcopy`). Progress goes to stderr. Other platforms keep the two-step `record --out` + transcribe flow. An interruption is recoverable: Ctrl-C (or SIGTERM) stops the session, still prints what you dictated, and exits 130/143, and the audio is spilled to a recovery WAV under `~/.cache/kesha/recordings/` — named on stderr when the session starts, deleted once the transcript has actually been delivered, kept if anything — a signal, a crash, a closed terminal, a dead pipe — got in the way first ([#962](https://github.com/drakulavich/kesha-voice-kit/issues/962)).
+- **Dictate straight to text (darwin-arm64):** `kesha record --live` transcribes the mic as it captures and prints the transcript to stdout — no WAV in between, so it pipes (`kesha record --live | pbcopy`). To end after trailing silence, explicitly install VAD then opt in: `kesha install --vad && kesha record --live --auto-stop`. The defaults are 1,000 ms of silence after 250 ms of speech; tune them with `--auto-stop-silence-ms`, `--auto-stop-min-speech-ms`, and `--auto-stop-threshold`. Progress goes to stderr. Linux and Windows do not capture the microphone; pass an existing audio file to `kesha` to transcribe it. An interruption is recoverable: Ctrl-C (or SIGTERM) stops the session, still prints what you dictated, and exits 130/143, and the audio is spilled to a recovery WAV under `~/.cache/kesha/recordings/` — named on stderr when the session starts, deleted once the transcript has actually been delivered, kept if anything — a signal, a crash, a closed terminal, a dead pipe — got in the way first ([#962](https://github.com/drakulavich/kesha-voice-kit/issues/962)).
 - **Long / silence-heavy audio:** install VAD (`kesha install --vad`); Kesha auto-uses it past 120 s. Without VAD, long audio falls back to fixed ASR chunks. See [docs/vad.md](docs/vad.md).
 - **Speaker diarization** (darwin-arm64): `kesha install --diarize` (which installs VAD too), then `kesha --json --speakers meeting.m4a` stamps each segment with a `speaker` id. `--speakers` engages VAD windowing itself at any duration, so it cannot be combined with `--no-vad`. Linux/Windows return a clear "darwin-arm64 only" error ([#199](https://github.com/drakulavich/kesha-voice-kit/issues/199)).
 - **Word-level timestamps** (every platform): `kesha --json --timestamps audio.ogg` adds a `words` array to each segment — `{ "word": "email", "start": 0.72, "end": 1.12 }` — on the same file-relative clock as the segment, so a word always lies inside the segment carrying it. Read them off the decoder's own frame grid, so: times are quantised to 0.08 s, consecutive spans may overlap (each `end` is a per-word duration prediction, not the next word's `start`), `end >= start` rather than strictly greater, and punctuation stays attached to its word. The key is simply absent where a segment has none — any segment `--itn` rewrote, for one — so check the `transcribe.words` capability rather than expecting an empty array ([#720](https://github.com/drakulavich/kesha-voice-kit/issues/720)).
-- **Written-form numbers:** `--itn` rewrites what the model spells out — `"two hundred thirty two"` → `"232"`, `"five dollars and fifty cents"` → `"$5.50"`. Opt-in, every platform, timestamps untouched. English-only in practice; Russian and the rest pass through unchanged. Spoken punctuation names stay words (`"dot"`, `"comma"`, `"the period of growth"`) because Kesha transcribes speech rather than dictation — so `"example dot com"` keeps its words too ([#822](https://github.com/drakulavich/kesha-voice-kit/issues/822)).
+- **Text-language detection:** JSON and TOON results include `textLanguage` with a language code, confidence, and its `source`. On macOS Kesha uses Apple `NLLanguageRecognizer`; elsewhere it uses the bundled `tinyld` fallback, whose confidence scale is different. This is separate from `audioLanguage`, which identifies the spoken audio when available.
+- **Written-form numbers:** `--itn` rewrites what the model spells out — `"two hundred thirty two"` → `"232"`, `"five dollars and fifty cents"` → `"$5.50"`. Opt-in, every platform, timestamps untouched. English-only in practice; Russian and the rest pass through unchanged. Spoken punctuation names stay words (`"dot"`, `"comma"`, `"the period of growth"`) because Kesha transcribes speech rather than dictation — so `"example dot com"` keeps its words too ([#822](https://github.com/drakulavich/kesha-voice-kit/issues/822)). A sentence `"and"` survives the number that follows it (`"cats and three dogs"` → `"cats and 3 dogs"`), while an `"and"` the number owns still joins it (`"three hundred and five"` → `"305"`) ([#1000](https://github.com/drakulavich/kesha-voice-kit/issues/1000)) — and no longer splits the number around it (`"two hundred and thirty two"` → `"232"`, not `"230 2"`) ([#1006](https://github.com/drakulavich/kesha-voice-kit/issues/1006)). A hyphenated number reads the same as the spaced form (`"twenty-five apples"` → `"25 apples"`), while a hyphen between ordinary words is left alone (`"well-known"`, `"state-of-the-art"`, `"twenty-something"`) ([#1004](https://github.com/drakulavich/kesha-voice-kit/issues/1004)).
 
 ## Text-to-speech
 
-Kesha speaks back in [9 languages](docs/languages.md#text-to-speech). On macOS it picks the voice from the text's own language; on Linux and Windows text detection needs Apple frameworks, so state the language with `--lang <code>` (or the voice with `--voice <id>`) — otherwise the engine default speaks.
+Kesha speaks back in [9 languages](docs/languages.md#text-to-speech). Kokoro runs natively through FluidAudio CoreML/ANE on Apple Silicon and through ONNX on Linux and Windows; Russian uses Vosk-TTS, while `macos-*` system voices need no model download. On macOS Kesha picks the voice from the text's own language; on Linux and Windows, state the language with `--lang <code>` (or the voice with `--voice <id>`) — otherwise the engine default speaks.
 
 ```bash
 kesha install --tts                              # English voices; sizes differ per platform — preview: kesha install --plan

package/SKILL.md

@@ -130,12 +130,14 @@ kesha --json voice.ogg
   "text": "Привет, как дела?",
   "lang": "ru",
   "audioLanguage": { "code": "ru", "confidence": 0.98 },
-  "textLanguage": { "code": "ru", "confidence": 0.99 }
+  "textLanguage": { "code": "ru", "confidence": 0.99, "source": "engine" }
 }]
 ```
 
 Use `lang` (or the more detailed `audioLanguage`/`textLanguage`) to decide how to respond.
 
+**Read `textLanguage.source` before you compare its `confidence` to a threshold.** `"engine"` (macOS `NLLanguageRecognizer`) and `"tinyld"` (the CLI fallback used on Linux/Windows) score on different scales — the same correct detection reads ~0.98 from the engine and ~0.2 from `tinyld`, so a fixed `> 0.5` gate discards every correct fallback result. `audioLanguage` has one detector and carries no `source`.
+
 Need timestamped transcript segments for navigation, chapters, or downstream editing:
 
 ```bash
@@ -204,7 +206,7 @@ Format is also inferred from `--out` extension (`.ogg` / `.opus` / `.oga` → OG
 
 ## Language detection standalone
 
-`kesha --json audio.ogg` includes both audio-based (`audioLanguage`) and text-based (`textLanguage`) detection. Use audio detection to identify the language before running language-specific logic.
+`kesha --json audio.ogg` includes both audio-based (`audioLanguage`) and text-based (`textLanguage`) detection. Use audio detection to identify the language before running language-specific logic. `textLanguage` also names its detector in `source` — see the threshold rule under [STT](#stt-transcribe-audio).
 
 ## Install
 

package/completions/kesha.bash

@@ -25,7 +25,7 @@ _kesha_completion() {
     logs) opts="--help -h --json" ;;
     manpage) opts="--help -h" ;;
     mcp) opts="--help -h" ;;
-    record) opts="--help -h --out --live --max-seconds --debug" ;;
+    record) opts="--help -h --out --live --max-seconds --auto-stop --auto-stop-silence-ms --auto-stop-threshold --auto-stop-min-speech-ms --debug" ;;
     say) opts="--help -h --voice --lang --out --rate --list-voices --ssml --format --bitrate --sample-rate --no-expand-abbrev --verbose --debug" ;;
     stats) opts="--help -h --format" ;;
     status) opts="--help -h --disk --json" ;;

package/completions/kesha.fish

@@ -68,6 +68,10 @@ complete -c kesha -n '__fish_seen_subcommand_from record' -s h -d 'Show help'
 complete -c kesha -n '__fish_seen_subcommand_from record' -l out -r -d 'Write recorded WAV audio to this path'
 complete -c kesha -n '__fish_seen_subcommand_from record' -l live -d 'Transcribe the microphone live and print the transcript to stdout (CoreML on Apple Silicon only)'
 complete -c kesha -n '__fish_seen_subcommand_from record' -l max-seconds -r -d 'Maximum recording duration in seconds'
+complete -c kesha -n '__fish_seen_subcommand_from record' -l auto-stop -d 'End a live recording after trailing silence (requires `kesha install --vad`)'
+complete -c kesha -n '__fish_seen_subcommand_from record' -l auto-stop-silence-ms -r -d 'Trailing silence before auto-stop (default: 1000)'
+complete -c kesha -n '__fish_seen_subcommand_from record' -l auto-stop-threshold -r -d 'Silero speech threshold for auto-stop (default: 0.5)'
+complete -c kesha -n '__fish_seen_subcommand_from record' -l auto-stop-min-speech-ms -r -d 'Minimum speech before auto-stop may end a recording (default: 250)'
 complete -c kesha -n '__fish_seen_subcommand_from record' -l debug -d 'Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)'
 complete -c kesha -n '__fish_seen_subcommand_from say' -l help -d 'Show help'
 complete -c kesha -n '__fish_seen_subcommand_from say' -s h -d 'Show help'

package/completions/kesha.zsh

@@ -98,6 +98,10 @@ _kesha() {
         '--out=[Write recorded WAV audio to this path]:out:' \
         '--live[Transcribe the microphone live and print the transcript to stdout (CoreML on Apple Silicon only)]' \
         '--max-seconds=[Maximum recording duration in seconds]:max seconds:' \
+        '--auto-stop[End a live recording after trailing silence (requires `kesha install --vad`)]' \
+        '--auto-stop-silence-ms=[Trailing silence before auto-stop (default: 1000)]:auto stop silence ms:' \
+        '--auto-stop-threshold=[Silero speech threshold for auto-stop (default: 0.5)]:auto stop threshold:' \
+        '--auto-stop-min-speech-ms=[Minimum speech before auto-stop may end a recording (default: 250)]:auto stop min speech ms:' \
         '--debug[Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)]'
       ;;
     say)

package/docs/product-positioning.md

@@ -21,7 +21,7 @@ The product promise is not "one model for every audio problem." The promise is a
 | Transcribe to structured output for scripts or agents | Stable | `kesha --json audio.ogg`, `kesha --toon audio.ogg`, `kesha --format transcript audio.ogg` |
 | Detect likely audio/text language during transcription | Stable | `--lang`, `--verbose`, JSON/TOON language fields |
 | Skip silence in long audio | Beta | `kesha --vad meeting.m4a`, auto-on for long audio when VAD is installed |
-| Synthesize English or Russian speech locally | Beta | `kesha say "text"`, `kesha install --tts` |
+| Synthesize supported languages locally | Beta | `kesha say "text"`, `kesha install --tts` |
 | Use macOS system voices without model downloads | Stable on macOS | `kesha say --voice macos-*` |
 | Label speakers in meeting transcripts | Preview, darwin-arm64 only | `kesha --json --vad --speakers meeting.m4a` |
 | Integrate with OpenClaw as a local voice model | Stable integration surface, user-configured route | `docs/openclaw.md` |
@@ -35,7 +35,7 @@ The product promise is not "one model for every audio problem." The promise is a
 - Streaming phone-call transcription or real-time conversation infrastructure.
 - Speaker identity across files. Diarization emits per-file cluster IDs, not names or persistent voice profiles.
 - Full SSML coverage. Kesha supports a practical subset for current TTS engines; unsupported tags should fail or warn clearly.
-- Universal TTS across all 25 STT languages. TTS is intentionally scoped to English, Russian, and macOS system voices.
+- Universal TTS across all 25 STT languages. TTS is intentionally scoped to its documented nine-language set and macOS system voices.
 - Model training, fine-tuning, or benchmark leadership on every dataset.
 - Browser/mobile SDKs. The supported product surface is CLI-first, with thin integrations around it.
 
@@ -47,7 +47,7 @@ The product promise is not "one model for every audio problem." The promise is a
 | JSON / TOON / transcript output formats | Stable | Intended for scripts, agents, and downstream tooling. |
 | Audio language detection | Stable | Used for warnings and structured metadata. |
 | VAD preprocessing | Beta | Useful for long or silence-heavy audio; short voice messages stay on the fast path. |
-| English/Russian TTS | Beta | Requires `kesha install --tts`; model cache and first-run cost are expected. |
+| Kokoro and Vosk TTS | Beta | Nine documented languages; requires `kesha install --tts`, so model cache and first-run cost are expected. |
 | macOS AVSpeech voices | Stable on macOS | Zero-install system voices; quality is OS voice quality, not neural TTS. |
 | SSML subset | Preview | `<prosody rate>`, Russian stress markers, and IPA support are engine-specific. |
 | Speaker diarization | Preview | darwin-arm64 only; cluster IDs are stable within one file only. |
@@ -63,8 +63,9 @@ The product promise is not "one model for every audio problem." The promise is a
 | STT | Supported, CoreML path | Not shipped | Supported, ONNX CPU path | Supported, ONNX CPU path | `aarch64-darwin`, `x86_64-linux` |
 | Audio language detection | Supported | Not shipped | Supported | Supported | Supported where the flake builds |
 | VAD | Supported with `kesha install --vad` | Not shipped | Supported with `kesha install --vad` | Supported with `kesha install --vad` | Supported where the engine path includes VAD assets |
-| TTS: English Kokoro | Supported, FluidAudio/CoreML in release builds | Not shipped | Supported, ONNX path | Supported, ONNX path | Supported except where noted in `docs/nix-install.md` |
+| TTS: Kokoro (`en` `es` `fr` `it` `pt`) | Supported, FluidAudio/CoreML in release builds | Not shipped | Supported, ONNX path | Supported, ONNX path | Supported except where noted in `docs/nix-install.md` |
 | TTS: Russian Vosk-TTS | Supported | Not shipped | Supported | Supported | Supported except where noted in `docs/nix-install.md` |
+| TTS: Kokoro (`hi` `ja` `zh`) | Supported, darwin-arm64 only | Not shipped | Not supported | Not supported | `aarch64-darwin` only |
 | macOS system voices | Supported | Not shipped | Not applicable | Not applicable | Supported on `aarch64-darwin` |
 | Speaker diarization | Preview, darwin-arm64 only | Not supported | Not supported | Not supported | Not wired into the Nix build yet |
 | Raycast extension | Supported | Not shipped | Not applicable | Not applicable | Not applicable |

package/man/kesha.1

@@ -162,6 +162,18 @@ Transcribe the microphone live and print the transcript to stdout (CoreML on App
 .B \-\-max\-seconds
 Maximum recording duration in seconds
 .TP
+.B \-\-auto\-stop
+End a live recording after trailing silence (requires `kesha install \-\-vad`)
+.TP
+.B \-\-auto\-stop\-silence\-ms
+Trailing silence before auto\-stop (default: 1000)
+.TP
+.B \-\-auto\-stop\-threshold
+Silero speech threshold for auto\-stop (default: 0.5)
+.TP
+.B \-\-auto\-stop\-min\-speech\-ms
+Minimum speech before auto\-stop may end a recording (default: 250)
+.TP
 .B \-\-debug
 Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)
 .SS say

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/kesha-voice-kit",
-  "version": "1.28.0-alpha.1",
+  "version": "1.29.1",
   "description": "Give your tools a voice — speech to text and back, 25 languages, up to ~19× faster than Whisper. On your machine.",
   "type": "module",
   "bin": {
@@ -40,13 +40,13 @@
     }
   },
   "keshaEngine": {
-    "version": "1.24.9"
+    "version": "1.24.11"
   },
   "scripts": {
     "test": "bun test --timeout 30000",
     "test:watch": "bun test --timeout 30000 --watch",
     "test:unit": "bun test --timeout 30000 tests/unit/",
-    "test:cli-fast": "bun test --timeout 30000 tests/unit/ tests/integration/cli-contracts.test.ts tests/integration/say.test.ts",
+    "test:cli-fast": "bun test --timeout 30000 tests/unit/ tests/integration/cli-contracts.test.ts tests/integration/error-codes-cli.test.ts tests/integration/say.test.ts",
     "test:integration": "bun test --timeout 30000 tests/integration/",
     "coverage:ts": "bun run test:cli-fast --coverage --coverage-reporter=text --coverage-reporter=lcov --coverage-dir=coverage/ts",
     "coverage:check:ts": "bun .github/scripts/check-coverage.ts --preset=ts --lcov=coverage/ts/lcov.info --summary=coverage/ts/summary.md",

package/src/cli/dispatch.ts

@@ -1,6 +1,7 @@
 import { runMain, type CommandDef } from "citty";
 import { existsSync } from "fs";
 import { log } from "../log";
+import { guardStdoutWrites } from "../stdout-pipe";
 import { suggestCommand } from "../suggest-command";
 import { applyCliContext, resolveCliContext } from "./context";
 
@@ -89,6 +90,7 @@ export function unknownCommandMessages(token: string, subcommandKeys: string[]):
 }
 
 export async function runCli(argv = process.argv.slice(2)): Promise<void> {
+  guardStdoutWrites();
   const context = resolveCliContext(argv);
   applyCliContext(context);
 

package/src/cli/install.ts

@@ -9,6 +9,7 @@ import { log } from "../log";
 import { packageVersion } from "../package-info";
 import { isSemver } from "../semver.mjs";
 import { createDiagnosticLogSession, type DiagnosticLogSession } from "../diagnostic-log";
+import { getPendingSignalExitCode, waitForPendingSignalCleanup } from "../process-tree";
 import type { SharedInstallArgs } from "./types";
 
 export interface InstallCommandArgs extends SharedInstallArgs {
@@ -239,6 +240,11 @@ export async function performInstall(options: PerformInstallOptions) {
     await maybeAskForStar(getEngineBinPath(), packageVersion, log);
     finishInstallDiagnostic(diagnosticLog, startedAt, "success");
   } catch (err: unknown) {
+    const signalExitCode = getPendingSignalExitCode();
+    if (signalExitCode !== null) {
+      await waitForPendingSignalCleanup();
+      process.exit(signalExitCode);
+    }
     const message = errorMessage(err);
     finishInstallDiagnostic(diagnosticLog, startedAt, "failed", errorKind);
     log.error(message);

package/src/cli/main.ts

@@ -1,12 +1,12 @@
 import { defineCommand } from "citty";
 import { errorMessage } from "../error-utils";
 import { existsSync, statSync } from "fs";
-import { detect } from "tinyld";
+import { detectAll } from "tinyld";
 import { preflightTranscribeWithSegments, transcribeWithSegments } from "../transcribe";
 import { detectAudioLanguageEngine, detectTextLanguageEngine } from "../engine";
 import type { LangDetectResult } from "../engine";
 import { log } from "../log";
-import type { TranscribeErrorRecord, TranscribeResult } from "../types";
+import type { TextLangDetectResult, TranscribeErrorRecord, TranscribeResult } from "../types";
 import {
   formatJsonOutput,
   formatTextOutput,
@@ -33,8 +33,6 @@ interface MainCommandArgs {
   debug: boolean;
   vad: boolean;
   "no-vad": boolean;
-  noVad?: boolean;
-  no_vad?: boolean;
   timestamps: boolean;
   speakers: boolean;
   itn: boolean;
@@ -45,9 +43,21 @@ interface MainCommandArgs {
   "no-color": boolean;
 }
 
+/**
+ * The CLI-side `tinyld` fallback, tagged `source: "tinyld"` so a consumer can
+ * tell it apart from an Engine detection instead of reading the placeholder
+ * `confidence: 0` it used to carry as a genuine zero (#941). The score is
+ * tinyld's own and is not on the Engine's scale.
+ */
+export function detectTextLanguageFallback(text: string): TextLangDetectResult | undefined {
+  if (!text) return undefined;
+  const [best] = detectAll(text);
+  if (!best) return undefined;
+  return { code: best.lang, confidence: best.accuracy, source: "tinyld" };
+}
+
 export function detectLanguage(text: string): string {
-  if (!text) return "";
-  return detect(text);
+  return detectTextLanguageFallback(text)?.code ?? "";
 }
 
 /** True when `path` exists and is a directory. Used to reject directory positionals before any progress/engine spawn. */
@@ -65,31 +75,31 @@ export function isDirectoryPath(path: string): boolean {
  * with its own clearer error first.
  */
 export type ResolvedOutputFormat =
-  | {
-      ok: true;
-      wantsJson: boolean;
-      wantsToon: boolean;
-      wantsTranscript: boolean;
-    }
+  | { ok: true; format: "json" | "toon" | "transcript" | "text" }
   | { ok: false; error: string };
 
 const SUPPORTED_FORMATS = ["transcript", "json", "toon"] as const;
 
+function isSupportedFormat(format: string): format is (typeof SUPPORTED_FORMATS)[number] {
+  return SUPPORTED_FORMATS.some((supported) => supported === format);
+}
+
 export function resolveOutputFormat(input: {
   json?: boolean;
   toon?: boolean;
   format?: string;
 }): ResolvedOutputFormat {
-  if (input.format !== undefined && !SUPPORTED_FORMATS.includes(input.format as never)) {
+  if (input.format !== undefined && !isSupportedFormat(input.format)) {
     return {
       ok: false,
       error: `unknown --format '${input.format}'. supported: ${SUPPORTED_FORMATS.join(", ")}`,
     };
   }
-  const wantsJson = !!input.json || input.format === "json";
-  const wantsToon = !!input.toon || input.format === "toon";
-  const wantsTranscript = input.format === "transcript";
-  if (wantsJson && wantsToon) {
+  if (
+    (input.json && input.toon) ||
+    (input.json && input.format === "toon") ||
+    (input.toon && input.format === "json")
+  ) {
     return {
       ok: false,
       error: "--json and --toon are mutually exclusive (pick one output format).",
@@ -100,7 +110,7 @@ export function resolveOutputFormat(input: {
   // dispatch checked wantsJson/wantsToon first). Greptile P2 on #300
   // flagged the silent override. Fail loudly with the same shape as
   // the json/toon mutex — symmetric across all three formats.
-  if (wantsTranscript && (wantsJson || wantsToon)) {
+  if (input.format === "transcript" && (input.json || input.toon)) {
     return {
       ok: false,
       error:
@@ -108,7 +118,7 @@ export function resolveOutputFormat(input: {
         "(pick one output format).",
     };
   }
-  return { ok: true, wantsJson, wantsToon, wantsTranscript };
+  return { ok: true, format: input.json ? "json" : input.toon ? "toon" : (input.format ?? "text") };
 }
 
 export function checkLanguageMismatch(expected: string | undefined, detected: string): string | null {
@@ -151,6 +161,19 @@ export type ValidatedTranscribeArgs = {
   outputFormat: "json" | "toon" | "transcript" | "text";
 };
 
+type MainVadArgs = Pick<MainCommandArgs, "vad" | "no-vad">;
+
+export function normalizeMainCommandArgs<T extends MainVadArgs>(
+  args: T,
+  rawArgs: string[],
+): T & { noVad: boolean } {
+  return {
+    ...args,
+    vad: rawArgs.includes("--vad") || args.vad,
+    noVad: rawArgs.includes("--no-vad") || args["no-vad"] === true,
+  };
+}
+
 export type TranscribeArgsValidation =
   | ({ ok: true } & ValidatedTranscribeArgs)
   | { ok: false; error: string };
@@ -161,20 +184,16 @@ export function validateTranscribeArgs(
   rawArgs: string[],
   fmt: ResolvedOutputFormat & { ok: true },
 ): TranscribeArgsValidation {
-  const { wantsJson, wantsToon, wantsTranscript } = fmt;
-
-  // citty treats --no-vad as the negated form of --vad, so read rawArgs
-  // to distinguish "off" from the default auto mode and to catch both flags.
-  const vad = rawArgs.includes("--vad") || Boolean(args.vad);
-  const noVad = rawArgs.includes("--no-vad") || Boolean(args["no-vad"] ?? args.noVad ?? args.no_vad);
+  const normalizedArgs = normalizeMainCommandArgs(args, rawArgs);
+  const { vad, noVad } = normalizedArgs;
 
   if (vad && noVad) {
     return { ok: false, error: "--vad and --no-vad are mutually exclusive." };
   }
-  if (args.timestamps && !(wantsJson || wantsToon)) {
+  if (args.timestamps && fmt.format !== "json" && fmt.format !== "toon") {
     return { ok: false, error: "--timestamps requires --json, --toon, or --format {json,toon}." };
   }
-  if (args.speakers && !(wantsJson || wantsToon)) {
+  if (args.speakers && fmt.format !== "json" && fmt.format !== "toon") {
     return { ok: false, error: "--speakers requires --json, --toon, or --format {json,toon}." };
   }
   // #768: diarization labels VAD-windowed segments, so --no-vad leaves nothing to label.
@@ -187,20 +206,12 @@ export function validateTranscribeArgs(
         "(VAD engages automatically for --speakers), or drop --speakers.",
     };
   }
-  if (args["include-errors"] && !(wantsJson || wantsToon)) {
+  if (args["include-errors"] && fmt.format !== "json" && fmt.format !== "toon") {
     return { ok: false, error: "--include-errors requires --json, --toon, or --format {json,toon}." };
   }
 
   const vadMode: ValidatedTranscribeArgs["vadMode"] = vad ? "on" : noVad ? "off" : "auto";
-  const outputFormat: ValidatedTranscribeArgs["outputFormat"] = wantsJson
-    ? "json"
-    : wantsToon
-      ? "toon"
-      : wantsTranscript
-        ? "transcript"
-        : "text";
-
-  return { ok: true, vadMode, outputFormat };
+  return { ok: true, vadMode, outputFormat: fmt.format };
 }
 
 async function detectLanguages(
@@ -215,7 +226,7 @@ async function detectLanguages(
   },
 ): Promise<{
   audioLanguage: LangDetectResult | undefined;
-  textLanguage: LangDetectResult | undefined;
+  textLanguage: TextLangDetectResult | undefined;
   lang: string;
   ranAudioLangId: boolean;
 }> {
@@ -243,17 +254,17 @@ async function detectLanguages(
     }
   }
 
-  const tinyldLang = wantsLangId ? detectLanguage(text) : "";
-  let textLanguage: LangDetectResult | undefined;
+  const tinyldResult = wantsLangId ? detectTextLanguageFallback(text) : undefined;
+  let textLanguage: TextLangDetectResult | undefined;
 
   if (wantsLangId) {
     const engineTextResult = await stats.timeStage("lang_id_text", () => detectTextLanguageEngine(text));
     if (engineTextResult && engineTextResult.code) {
-      textLanguage = engineTextResult;
+      textLanguage = { ...engineTextResult, source: "engine" };
     }
   }
 
-  const lang = textLanguage?.code || tinyldLang;
+  const lang = textLanguage?.code || tinyldResult?.code || "";
 
   const mismatchWarning = checkLanguageMismatch(expectedLang, lang);
   if (mismatchWarning) {
@@ -262,7 +273,7 @@ async function detectLanguages(
 
   return {
     audioLanguage,
-    textLanguage: textLanguage ?? (tinyldLang ? { code: tinyldLang, confidence: 0 } : undefined),
+    textLanguage: textLanguage ?? tinyldResult,
     lang,
     ranAudioLangId: audioResult !== null,
   };
@@ -295,20 +306,20 @@ async function processFile(
       command: "transcribe",
       error_code: TS_NATIVE_CODES.INPUT_NOT_FOUND,
     });
-    log.error(`${file}: File not found`);
+    log.error(`${file}: error [${TS_NATIVE_CODES.INPUT_NOT_FOUND}]: File not found`);
     return { ok: false, error: { file, code: TS_NATIVE_CODES.INPUT_NOT_FOUND, message: "File not found" } };
   }
 
   if (isDirectoryPath(file)) {
-    stats.recordError("input", new Error("is a directory"), ENGINE_CODES.BAD_AUDIO);
+    stats.recordError("input", new Error("is a directory"), TS_NATIVE_CODES.INVALID_ARG);
     diagnosticLog.event("input.invalid", {
       command: "transcribe",
-      error_code: ENGINE_CODES.BAD_AUDIO,
+      error_code: TS_NATIVE_CODES.INVALID_ARG,
     });
-    log.error(`${file}: is a directory (expected an audio file)`);
+    log.error(`${file}: error [${TS_NATIVE_CODES.INVALID_ARG}]: is a directory (expected an audio file)`);
     return {
       ok: false,
-      error: { file, code: ENGINE_CODES.BAD_AUDIO, message: "is a directory (expected an audio file)" },
+      error: { file, code: TS_NATIVE_CODES.INVALID_ARG, message: "is a directory (expected an audio file)" },
     };
   }
 
@@ -324,6 +335,13 @@ async function processFile(
 
   const startedAt = performance.now();
   let progress: ReturnType<typeof createPercentProgress> | null = null;
+  // #1002: the bar sitting at 0% through a ~100 s diarization model load reads as a hang,
+  // so the engine's progress has to land while it happens, not once the run is over.
+  const showProgressLine = (line: string) => {
+    const write = () => process.stderr.write(`${line}\n`);
+    if (progress) progress.interrupt(write);
+    else write();
+  };
   try {
     await preflightTranscribeWithSegments({ vad: vadMode, timestamps, speakers, itn });
     progress = reportProgress
@@ -332,7 +350,13 @@ async function processFile(
         })
       : null;
     const transcript = await stats.timeStage("transcribe", () =>
-      transcribeWithSegments(file, { vad: vadMode, timestamps, speakers, itn }),
+      transcribeWithSegments(file, {
+        vad: vadMode,
+        timestamps,
+        speakers,
+        itn,
+        onProgressLine: showProgressLine,
+      }),
     );
     const { text, segments } = transcript;
     const transcriptDurationSeconds = estimateTranscriptDurationSeconds(segments);
@@ -409,6 +433,21 @@ function writeOutput(
 }
 
 /** The transcribe command, bound to the global flags dispatch resolved before citty. */
+export const MAIN_VAD_ARGS = {
+  vad: {
+    type: "boolean",
+    description:
+      "Force Silero VAD preprocessing (kesha install --vad first). Without this, VAD auto-engages on audio ≥ 120s.",
+    default: false,
+  },
+  "no-vad": {
+    type: "boolean",
+    description:
+      "Force full-file ASR for short/medium files; long audio fails early. Incompatible with --speakers",
+    default: false,
+  },
+} as const;
+
 export function createMainCommand(context: CliContext = { quiet: false, disableColor: false }) {
   return defineCommand({
     meta: {
@@ -486,16 +525,7 @@ export function createMainCommand(context: CliContext = { quiet: false, disableC
         description: "Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)",
         default: false,
       },
-      vad: {
-        type: "boolean",
-        description: "Force Silero VAD preprocessing (kesha install --vad first). Without this, VAD auto-engages on audio ≥ 120s.",
-        default: false,
-      },
-      "no-vad": {
-        type: "boolean",
-        description: "Force full-file ASR for short/medium files; long audio fails early. Incompatible with --speakers",
-        default: false,
-      },
+      ...MAIN_VAD_ARGS,
       // quiet and no-color are resolved before citty in dispatch.ts (so they
       // apply to every command, not just transcribe); declared here only so they
       // appear in `kesha --help`.