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

package/README.md

@@ -94,7 +94,7 @@ $ kesha freedom.ogg tahiti.ogg
 - **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)).
+- **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
 

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/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.28.0",
   "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,14 @@
     }
   },
   "keshaEngine": {
-    "version": "1.24.9"
+    "version": "1.24.10"
   },
   "scripts": {
     "test": "bun test --timeout 30000",
+    "conveyor": "bun scripts/backlog.ts",
     "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`.

package/src/cli/record.ts

@@ -1,6 +1,12 @@
 import { defineCommand } from "citty";
 import { errorMessage } from "../error-utils";
-import { isEngineInstalled, preflightRecordLive, recordEngine, type RecordTarget } from "../engine";
+import {
+  isEngineInstalled,
+  preflightRecordLive,
+  recordEngine,
+  type LiveAutoStopOptions,
+  type RecordTarget,
+} from "../engine";
 import { installHint } from "../install-hint";
 import { log } from "../log";
 
@@ -8,6 +14,10 @@ export interface RecordArgs {
   out?: string;
   live?: boolean;
   "max-seconds"?: string | number;
+  "auto-stop"?: boolean;
+  "auto-stop-silence-ms"?: string | number;
+  "auto-stop-threshold"?: string | number;
+  "auto-stop-min-speech-ms"?: string | number;
   debug?: boolean;
 }
 
@@ -17,6 +27,9 @@ export type ResolvedRecordArgs =
 
 const DEFAULT_MAX_SECONDS = 120;
 const MAX_RECORD_SECONDS = 3600;
+const DEFAULT_AUTO_STOP_SILENCE_MS = 1000;
+const DEFAULT_AUTO_STOP_THRESHOLD = 0.5;
+const DEFAULT_AUTO_STOP_MIN_SPEECH_MS = 250;
 
 type Rejected = { ok: false; error: string };
 
@@ -57,7 +70,71 @@ export function resolveRecordArgs(args: RecordArgs): ResolvedRecordArgs {
   if (!target.ok) return target;
   const max = resolveMaxSeconds(args["max-seconds"]);
   if (!max.ok) return max;
-  return { ok: true, target: target.target, maxSeconds: max.maxSeconds };
+  const autoStop = resolveAutoStop(args, target.target);
+  if (!autoStop.ok) return autoStop;
+  return {
+    ok: true,
+    target: autoStop.options ? { live: true, autoStop: autoStop.options } : target.target,
+    maxSeconds: max.maxSeconds,
+  };
+}
+
+function resolveAutoStop(
+  args: RecordArgs,
+  target: RecordTarget,
+): { ok: true; options?: LiveAutoStopOptions } | Rejected {
+  const enabled = args["auto-stop"] === true;
+  const hasSettings =
+    args["auto-stop-silence-ms"] !== undefined ||
+    args["auto-stop-threshold"] !== undefined ||
+    args["auto-stop-min-speech-ms"] !== undefined;
+  if (!enabled && hasSettings) {
+    return { ok: false, error: "auto-stop settings require --auto-stop." };
+  }
+  if (enabled && !target.live) {
+    return { ok: false, error: "--auto-stop requires --live." };
+  }
+  if (!enabled) return { ok: true };
+
+  const silenceMs = resolvePositiveInteger(
+    args["auto-stop-silence-ms"],
+    DEFAULT_AUTO_STOP_SILENCE_MS,
+    "--auto-stop-silence-ms",
+  );
+  if (!silenceMs.ok) return silenceMs;
+  const minSpeechMs = resolvePositiveInteger(
+    args["auto-stop-min-speech-ms"],
+    DEFAULT_AUTO_STOP_MIN_SPEECH_MS,
+    "--auto-stop-min-speech-ms",
+  );
+  if (!minSpeechMs.ok) return minSpeechMs;
+  const threshold = resolveThreshold(args["auto-stop-threshold"]);
+  if (!threshold.ok) return threshold;
+  return { ok: true, options: { silenceMs: silenceMs.value, threshold: threshold.value, minSpeechMs: minSpeechMs.value } };
+}
+
+function resolvePositiveInteger(
+  rawValue: string | number | undefined,
+  defaultValue: number,
+  flag: string,
+): { ok: true; value: number } | Rejected {
+  const raw = String(rawValue ?? defaultValue).trim();
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value <= 0) {
+    return { ok: false, error: `${flag} must be a positive integer.` };
+  }
+  return { ok: true, value };
+}
+
+function resolveThreshold(
+  rawValue: string | number | undefined,
+): { ok: true; value: number } | Rejected {
+  const raw = String(rawValue ?? DEFAULT_AUTO_STOP_THRESHOLD).trim();
+  const value = Number(raw);
+  if (!Number.isFinite(value) || value <= 0 || value > 1) {
+    return { ok: false, error: "--auto-stop-threshold must be greater than 0 and at most 1." };
+  }
+  return { ok: true, value };
 }
 
 /** Mirrors `src/transcribe.ts`'s "no transcription backend" guard message, worded for recording. */
@@ -91,6 +168,23 @@ export const recordCommand = defineCommand({
       description: "Maximum recording duration in seconds",
       default: String(DEFAULT_MAX_SECONDS),
     },
+    "auto-stop": {
+      type: "boolean",
+      description: "End a live recording after trailing silence (requires `kesha install --vad`)",
+      default: false,
+    },
+    "auto-stop-silence-ms": {
+      type: "string",
+      description: "Trailing silence before auto-stop (default: 1000)",
+    },
+    "auto-stop-threshold": {
+      type: "string",
+      description: "Silero speech threshold for auto-stop (default: 0.5)",
+    },
+    "auto-stop-min-speech-ms": {
+      type: "string",
+      description: "Minimum speech before auto-stop may end a recording (default: 250)",
+    },
     debug: {
       type: "boolean",
       description: "Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)",
@@ -109,7 +203,7 @@ export const recordCommand = defineCommand({
       process.exit(1);
     }
     try {
-      if (resolved.target.live) await preflightRecordLive();
+      if (resolved.target.live) await preflightRecordLive(resolved.target.autoStop !== undefined);
       await recordEngine(resolved.target, resolved.maxSeconds);
     } catch (err) {
       log.error(errorMessage(err));

package/src/cli/say.ts

@@ -9,7 +9,13 @@ import {
 import { installHint } from "../install-hint";
 import { registerProcessTree } from "../process-tree";
 import { log } from "../log";
-import { say, SayError, type SayFormat } from "../synth";
+import {
+  say,
+  SayError,
+  SUPPORTED_SAMPLE_RATES,
+  type SayFormat,
+  type SayOptions,
+} from "../synth";
 import { artifactFromBytes, artifactFromFile, type StatsRecorder } from "../stats";
 import { resolveSayVoice } from "../voice-routing";
 import { diagnosticCharBucket, diagnosticSizeBucket } from "../diagnostic-events";
@@ -68,12 +74,13 @@ function parseBitrateFlag(value: unknown): Parsed<number> {
   return bitrate;
 }
 
-const SUPPORTED_SAMPLE_RATES = [8000, 12000, 16000, 24000, 48000];
-
 function parseSampleRateFlag(value: unknown): Parsed<number> {
   const sampleRate = parseFiniteNumberFlag("--sample-rate", value);
   if (!sampleRate.ok || sampleRate.value === undefined) return sampleRate;
-  if (!Number.isInteger(sampleRate.value) || !SUPPORTED_SAMPLE_RATES.includes(sampleRate.value)) {
+  if (
+    !Number.isInteger(sampleRate.value) ||
+    !SUPPORTED_SAMPLE_RATES.includes(sampleRate.value as (typeof SUPPORTED_SAMPLE_RATES)[number])
+  ) {
     return {
       ok: false,
       error: `--sample-rate must be one of ${SUPPORTED_SAMPLE_RATES.join(", ")}.`,
@@ -189,7 +196,7 @@ async function synthesizeAndEmit(
       const voiceLabel = opts.voice ?? "default voice";
       log.status(`Synthesizing ${voiceLabel} -> ${opts.out}...`);
     }
-    const audio = await stats.timeStage("tts", () => say(opts));
+    const audio = await stats.timeStage("tts", () => say(opts as SayOptions));
     const ttsTimeMs = Math.round(performance.now() - startedAt);
     if (opts.out) {
       log.status(`Saved ${opts.out} (${ttsTimeMs}ms)`);

package/src/cli.ts

@@ -30,6 +30,7 @@ export {
   createMainCommand,
   mainCommand,
   detectLanguage,
+  detectTextLanguageFallback,
   checkLanguageMismatch,
   estimateTranscriptDurationSeconds,
   isDirectoryPath,

package/src/doctor.ts

@@ -39,6 +39,7 @@ const KNOWN_ENV_KEYS = [
   "KESHA_DIARIZE_COMPUTE_UNITS",
   "KESHA_DIARIZE_TIMEOUT_SECS",
   "KESHA_DIARIZE_LOAD_TIMEOUT_SECS",
+  "KESHA_INSTALL_LOCK_WAIT_SECS",
 ] as const;
 
 interface DoctorOptions {