@drakulavich/kesha-voice-kit 2.3.0-beta.2 → 2.3.0-beta.3

package/README.md

@@ -16,7 +16,7 @@
 - **Transcribe locally** — [25 languages](docs/languages.md#speech-to-text-25), up to ~19x faster than Whisper on Apple Silicon, ~10x on an x86 CPU
 - **Speak back** — text-to-speech in [9 languages](docs/languages.md#text-to-speech)
 - **Plug into agents** — ship voice workflows as CLI commands, an MCP server, an <a href="docs/openclaw.md">OpenClaw</a> skill, or a <a href="docs/hermes.md">Hermes</a> agent
-- **Small Rust engine** — single ~65MB binary, no ffmpeg, no Python, no native Node addons
+- **Small Rust engine** — single ~74 MB binary, no ffmpeg, no Python, no native Node addons
 
 <p align="center">
   <img src="https://github.com/drakulavich/kesha-voice-kit/raw/main/docs/assets/demo.webp" alt="kesha demo: an English voice message transcribed, a Russian one as JSON with automatic language detection, then text-to-speech into a wav" width="800">
@@ -127,7 +127,7 @@ kesha say "Hello" --format ogg-opus --out hi.ogg  # OGG/Opus — messenger voice
 kesha say "Hello" --format flac --out hi.flac     # FLAC — lossless, plays in every browser incl. Safari/iOS
 ```
 
-`kesha say --list-voices` lists what's installed. Voices, the full catalogue, macOS system voices, SSML, speaking rate (`--rate`, `<prosody>`), Russian word stress, and Russian/English abbreviation handling are all in **[docs/tts.md](docs/tts.md)**.
+`kesha say --list-voices` lists the voices kesha knows; some need `kesha install --tts <lang>` before they speak. Voices, the full catalogue, macOS system voices, SSML, speaking rate (`--rate`, `<prosody>`), Russian word stress, and Russian/English abbreviation handling are all in **[docs/tts.md](docs/tts.md)**.
 
 ## Languages
 

package/completions/kesha.fish

@@ -78,7 +78,7 @@ complete -c kesha -n '__fish_seen_subcommand_from say' -l voice -r -d 'Voice id,
 complete -c kesha -n '__fish_seen_subcommand_from say' -l lang -r -d 'Language code, e.g. en-us (default en-us; see docs/languages.md). With no --voice, routes to that language\'s default voice and skips text-language detection.'
 complete -c kesha -n '__fish_seen_subcommand_from say' -l out -r -d 'Write audio to file instead of stdout'
 complete -c kesha -n '__fish_seen_subcommand_from say' -l rate -r -d 'Speaking rate 0.5–2.0'
-complete -c kesha -n '__fish_seen_subcommand_from say' -l list-voices -d 'List installed voices and exit'
+complete -c kesha -n '__fish_seen_subcommand_from say' -l list-voices -d 'List the voices kesha knows and exit; some need kesha install --tts <lang> first'
 complete -c kesha -n '__fish_seen_subcommand_from say' -l ssml -d 'Parse input as SSML (supports <speak>, <break>; strips unknown tags)'
 complete -c kesha -n '__fish_seen_subcommand_from say' -l format -r -d 'Output format: wav (default), ogg-opus (Telegram-ready voice note), or flac (lossless, plays in all browsers incl. Safari). Inferred from --out extension when omitted.'
 complete -c kesha -n '__fish_seen_subcommand_from say' -l bitrate -r -d 'Opus bitrate in bits/sec (e.g. 32000). Only with --format ogg-opus.'

package/completions/kesha.zsh

@@ -112,7 +112,7 @@ _kesha() {
         '--lang=[Language code, e.g. en-us (default en-us; see docs/languages.md). With no --voice, routes to that language'\''s default voice and skips text-language detection.]:lang:' \
         '--out=[Write audio to file instead of stdout]:out:' \
         '--rate=[Speaking rate 0.5–2.0]:rate:' \
-        '--list-voices[List installed voices and exit]' \
+        '--list-voices[List the voices kesha knows and exit; some need kesha install --tts <lang> first]' \
         '--ssml[Parse input as SSML (supports <speak>, <break>; strips unknown tags)]' \
         '--format=[Output format: wav (default), ogg-opus (Telegram-ready voice note), or flac (lossless, plays in all browsers incl. Safari). Inferred from --out extension when omitted.]:format:' \
         '--bitrate=[Opus bitrate in bits/sec (e.g. 32000). Only with --format ogg-opus.]:bitrate:' \

package/man/kesha.1

@@ -191,7 +191,7 @@ Write audio to file instead of stdout
 Speaking rate 0.5–2.0
 .TP
 .B \-\-list\-voices
-List installed voices and exit
+List the voices kesha knows and exit; some need kesha install \-\-tts <lang> first
 .TP
 .B \-\-ssml
 Parse input as SSML (supports <speak>, <break>; strips unknown tags)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/kesha-voice-kit",
-  "version": "2.3.0-beta.2",
+  "version": "2.3.0-beta.3",
   "description": "Kesha listens and talks back: local speech to text and text to speech for agents and scripts, fastest on Apple Silicon.",
   "type": "module",
   "bin": {
@@ -109,18 +109,18 @@
   },
   "kesha": {
     "engine": {
-      "version": "2.3.0-beta.2",
+      "version": "2.3.0-beta.3",
       "sha256": {
-        "kesha-engine-darwin-arm64": "febd870e9f857be6452336c74daad161f2cef74dfedb64a21b49b6b1fc2ce94c",
-        "kesha-engine-linux-x64": "9c16e72e5290f774b1d93cbf44b2fc6eca3c4b30659038ccb80f5e98dc748d2a",
-        "kesha-engine-windows-x64.exe": "231bc45eb345ef359ca94685866de8cb4c7c76ae9bef1072c20a60640c458f63",
+        "kesha-engine-darwin-arm64": "db444c1c0ccc368e72068f050807ab54975fb516055480b33c32d5b1f29c4e58",
+        "kesha-engine-linux-x64": "0ac69c63cc8e922aaaea5b6df221dd97f6add02d4d6fb09def2317c331019a89",
+        "kesha-engine-windows-x64.exe": "0ae3063b7d5ff00da7cd0f675cd557374d81ff94087787dc90d7c195f7347194",
         "say-avspeech-darwin-arm64": "6c7e0708f27c1baf3d8013bfbeb6249a6c3acbb718b3d39081707c7a8aa22e5b",
         "kesha-textlang-darwin-arm64": "cbe74ee1aebdb902e21d4c69769c71b6d49e037794a8623db11faa8cf2814420"
       },
       "size": {
-        "kesha-engine-darwin-arm64": 73672800,
-        "kesha-engine-linux-x64": 67418152,
-        "kesha-engine-windows-x64.exe": 66596864,
+        "kesha-engine-darwin-arm64": 73672784,
+        "kesha-engine-linux-x64": 67422216,
+        "kesha-engine-windows-x64.exe": 66576384,
         "say-avspeech-darwin-arm64": 82896,
         "kesha-textlang-darwin-arm64": 57488
       }

package/src/cache-layout.ts

@@ -1,6 +1,9 @@
 import { existsSync, realpathSync, statSync } from "fs";
 import { dirname, join, resolve, sep } from "path";
 import { dirSizeBytes } from "./diagnostic-paths";
+import { isDarwinArm64 } from "./engine-targets";
+
+export const KOKORO_ONNX_UNUSED_NOTE = "not used on darwin-arm64, where Kokoro runs from the TTS (Kokoro ANE) bundle";
 
 /** The sidecar executables the engine spawns from its own directory. */
 const SIDECAR_FILES = ["say-avspeech", "kesha-textlang"] as const;
@@ -10,6 +13,7 @@ export interface CacheComponentSize {
   path: string;
   exists: boolean;
   sizeBytes: number;
+  note?: string;
 }
 
 interface EngineFootprint {
@@ -101,14 +105,33 @@ export function cacheComponents(
     exists: existsSync(engine.path),
     sizeBytes: footprintBytes(engine, engine.members),
   };
+  const coremlRows = [
+    { label: "FluidAudio (in cache)", path: join(cacheRoot, "fluidaudio") },
+    { label: "Diarization (Sortformer)", path: join(cacheRoot, "models/diarize") },
+  ];
+  const onnxRows = [
+    { label: "ASR (Parakeet)", path: join(cacheRoot, "models/parakeet-tdt-v3") },
+    { label: "G2P (CharsiuG2P)", path: join(cacheRoot, "models/g2p") },
+  ];
+  const [usedRows, unusedRows] = coreml ? [coremlRows, onnxRows] : [onnxRows, coremlRows];
+  const sized = (row: { label: string; path: string }) => ({
+    ...row,
+    exists: existsSync(row.path),
+    sizeBytes: dirSizeBytes(row.path),
+  });
   const modelRows = [
-    ...(coreml
-      ? [{ label: "FluidAudio (in cache)", path: join(cacheRoot, "fluidaudio") }]
-      : [{ label: "ASR (Parakeet)", path: join(cacheRoot, "models/parakeet-tdt-v3") }]),
+    ...usedRows,
     { label: "Language ID", path: join(cacheRoot, "models/lang-id-ecapa") },
     { label: "VAD (Silero)", path: join(cacheRoot, "models/silero-vad") },
-    { label: "TTS (Kokoro)", path: join(cacheRoot, "models/kokoro-82m") },
+    {
+      label: "TTS (Kokoro)",
+      path: join(cacheRoot, "models/kokoro-82m"),
+      ...(isDarwinArm64() ? { note: KOKORO_ONNX_UNUSED_NOTE } : {}),
+    },
     { label: "TTS (Vosk)", path: join(cacheRoot, "models/vosk-ru") },
-  ].map((row) => ({ ...row, exists: existsSync(row.path), sizeBytes: dirSizeBytes(row.path) }));
-  return [engineRow, ...modelRows];
+  ].map(sized);
+  const leftoverRows = unusedRows
+    .map((row) => sized({ ...row, label: `${row.label}, unused by this engine, safe to delete` }))
+    .filter((row) => row.exists);
+  return [engineRow, ...modelRows, ...leftoverRows];
 }

package/src/cli/dispatch.ts

@@ -183,6 +183,11 @@ export async function runCli(argv = process.argv.slice(2)): Promise<void> {
         await showUsage(rawArgs.includes("--all") ? command : briefMainUsage(command));
         return;
       }
+      const options = rawArgs.slice(0, rawArgs.includes("--") ? rawArgs.indexOf("--") : undefined);
+      if (options.includes("--version") || options.includes("-v")) {
+        process.stdout.write(`${packageVersion}\n`);
+        return;
+      }
       await runMain(reportThrows(command), { rawArgs, showUsage });
     }
   }

package/src/cli/main.ts

@@ -1,7 +1,15 @@
 import { defineCommand, type ArgsDef, type CommandDef } from "citty";
 import { errorMessage } from "../error-utils";
 import { existsSync } from "fs";
-import { isDirectoryPath, isSpecialFilePath, SPECIAL_FILE_HINT, transcribeWithSegments, validateTranscribeRequest } from "../transcribe";
+import {
+  isDirectoryPath,
+  isSpecialFilePath,
+  missingFileHint,
+  SPECIAL_FILE_HINT,
+  transcribeWithSegments,
+  truncatedWavSeconds,
+  validateTranscribeRequest,
+} from "../transcribe";
 
 export { isDirectoryPath };
 import { detectAudioLanguageEngine, detectTextLanguageEngine, isEngineInstalled } from "../engine";
@@ -81,14 +89,12 @@ export function resolveOutputFormat(input: {
       error: `unknown --format '${input.format}'. supported: ${SUPPORTED_FORMATS.join(", ")}`,
     };
   }
-  if (
-    (input.json && input.toon) ||
-    (input.json && input.format === "toon") ||
-    (input.toon && input.format === "json")
-  ) {
+  const jsonFlag = input.json ? "--json" : input.format === "json" ? "--format json" : null;
+  const toonFlag = input.toon ? "--toon" : input.format === "toon" ? "--format toon" : null;
+  if (jsonFlag && toonFlag) {
     return {
       ok: false,
-      error: "--json and --toon are mutually exclusive (pick one output format).",
+      error: `${jsonFlag} and ${toonFlag} are mutually exclusive (pick one output format).`,
     };
   }
   // `--format transcript` + boolean `--json` / `--toon` was previously
@@ -321,8 +327,19 @@ async function processFile(
   const { vadMode, timestamps, speakers, itn, wantsLangId, expectedLang, reportProgress } = options;
   const { stats, diagnosticLog } = recorders;
 
+  if (file === "-") {
+    const err = new KeshaError("E_INVALID_ARG", "reading audio from stdin is not supported", { hint: SPECIAL_FILE_HINT });
+    stats.recordError("input", err, err.code);
+    diagnosticLog.event("input.invalid", {
+      command: "transcribe",
+      error_code: err.code,
+    });
+    log.error(`${file}: ${errorMessage(err)}`);
+    return { ok: false, error: { file, code: err.code, message: err.message }, exitCode: failureExitCode(err) };
+  }
+
   if (!existsSync(file)) {
-    const err = new KeshaError("E_INPUT_NOT_FOUND", "File not found");
+    const err = new KeshaError("E_INPUT_NOT_FOUND", "File not found", { hint: missingFileHint(file) });
     stats.recordError("input", err, err.code);
     diagnosticLog.event("input.missing", {
       command: "transcribe",
@@ -358,6 +375,13 @@ async function processFile(
     return { ok: false, error: { file, code: err.code, message: err.message }, exitCode: failureExitCode(err) };
   }
 
+  const truncated = truncatedWavSeconds(file);
+  if (truncated) {
+    log.warn(
+      `warning: ${file} is truncated: its header declares ${truncated.declared.toFixed(1)} s of audio but the file holds ${truncated.present.toFixed(1)} s; transcribing the part present`,
+    );
+  }
+
   const inputArtifact = artifactFromFile(file, "input_audio");
   if (inputArtifact) {
     stats.recordArtifact(inputArtifact);
@@ -526,20 +550,25 @@ export function createMainCommand(context: CliContext = { quiet: false, disableC
         "  kesha init               Guided first-time setup.\n" +
         "\n" +
         "Commands:\n" +
-        "  completions  Print shell completion script.\n" +
-        "  doctor     Collect support diagnostics.\n" +
-        "  init       Interactive setup guide for Kesha features.\n" +
-        "  install    Download engine and models.\n" +
-        "  logs       Manage local privacy-safe diagnostic logs.\n" +
-        "  manpage    Print the kesha(1) manpage.\n" +
-        "  mcp        Run an MCP server over stdio.\n" +
-        "  record     Record microphone audio to a WAV file.\n" +
-        "  status     Inspect installed backend.\n" +
-        "  say        Synthesize speech from text.\n" +
-        "  stats      Manage local anonymous performance stats.\n" +
-        "  support-bundle  Create a redacted diagnostics archive.",
+        "  completions     Print shell completion script.\n" +
+        "  doctor          Collect support diagnostics.\n" +
+        "  init            Interactive setup guide for Kesha features.\n" +
+        "  install         Download engine and models.\n" +
+        "  logs            Manage local privacy-safe diagnostic logs.\n" +
+        "  manpage         Print the kesha(1) manpage.\n" +
+        "  mcp             Run an MCP server over stdio.\n" +
+        "  record          Record microphone audio to a WAV file.\n" +
+        "  status          Inspect installed backend.\n" +
+        "  say             Synthesize speech from text.\n" +
+        "  stats           Manage local anonymous performance stats.\n" +
+        "  support-bundle  Create a redacted diagnostics archive.\n",
     },
     args: {
+      audio_file: {
+        type: "positional",
+        required: false,
+        description: "Audio file(s) to transcribe",
+      },
       json: {
         type: "boolean",
         description: "Output results as JSON",

package/src/cli/options.ts

@@ -71,6 +71,11 @@ function scanArgs(rawArgs: string[], argsDef: ArgsDef): { unknown: UnknownOption
   return { unknown: null, positionals };
 }
 
+/** The positionals in `rawArgs` as the user typed them; citty reads `-5 degrees` as a bundle of short flags (#1473 S2-5). */
+export function positionalArgs(rawArgs: string[], argsDef: ArgsDef): string[] {
+  return scanArgs(rawArgs, argsDef).positionals;
+}
+
 /** The coded line for a usage error the CLI refuses before doing anything (S9-F2). */
 export function renderInvalidArg(message: string): string {
   return renderError({ code: "E_INVALID_ARG", message });

package/src/cli/record.ts

@@ -3,14 +3,13 @@ import { errorMessage } from "../error-utils";
 import { exitCodeFor, KeshaError } from "../engine/events";
 import { renderInvalidArg } from "./options";
 import {
-  getEngineBinPath,
+  engineMissingError,
   isEngineInstalled,
   recordEngine,
   validateRecordRequest,
   type LiveAutoStopOptions,
   type RecordTarget,
 } from "../engine";
-import { installHint } from "../install-hint";
 import { log } from "../log";
 import { getPendingSignalExitCode, waitForPendingSignalCleanup } from "../process-tree";
 
@@ -143,11 +142,7 @@ function resolveThreshold(
 
 /** Mirrors `src/transcribe.ts`'s "no transcription backend" guard message, worded for recording. */
 export function noRecordingBackendMessage(): string {
-  return errorMessage(
-    new KeshaError("E_ENGINE_SPAWN", `No recording backend is installed: no kesha-engine at ${getEngineBinPath()}`, {
-      hint: `bun add -g @drakulavich/kesha-voice-kit, then ${installHint()}`,
-    }),
-  );
+  return errorMessage(engineMissingError("recording"));
 }
 
 export const recordCommand = defineCommand({

package/src/cli/say.ts

@@ -1,8 +1,10 @@
-import { defineCommand } from "citty";
+import { defineCommand, type ArgsDef } from "citty";
 import { statSync } from "fs";
+import { extname } from "path";
 import { errorMessage } from "../error-utils";
+import { engineMissingError, isEngineInstalled } from "../engine";
 import { exitCodeFor, KeshaError } from "../engine/events";
-import { renderInvalidArg } from "./options";
+import { positionalArgs, renderInvalidArg } from "./options";
 import { log } from "../log";
 import {
   MAX_TEXT_CHARS,
@@ -130,6 +132,16 @@ function checkOpusOnlyFlags(
   return "--bitrate and --sample-rate are only valid with --format ogg-opus";
 }
 
+const OUT_EXTENSIONS = [".wav", ".ogg", ".opus", ".oga", ".flac"];
+
+/** Mirrors the engine's `format_from_extension`, which writes WAV under any name it does not know (#1473 S2-4). */
+function checkOutExtension(outArg: string | undefined): string | null {
+  if (outArg === undefined) return null;
+  const ext = extname(outArg).toLowerCase();
+  if (ext === "" || OUT_EXTENSIONS.includes(ext)) return null;
+  return `--out ${outArg}: kesha cannot encode ${ext}; use one of ${OUT_EXTENSIONS.join(", ")}, or no extension for WAV`;
+}
+
 export type SayFlagArgs = {
   voice?: unknown;
   lang?: unknown;
@@ -181,6 +193,8 @@ export function resolveSayFlags(args: SayFlagArgs): ResolvedSayFlags {
   const out = typeof args.out === "string" ? args.out : undefined;
   const opusOnlyError = checkOpusOnlyFlags(bitrate.value, sampleRate.value, format.value, out);
   if (opusOnlyError) return { ok: false, error: opusOnlyError };
+  const outExtError = checkOutExtension(out);
+  if (outExtError) return { ok: false, error: outExtError };
 
   return {
     ok: true,
@@ -255,6 +269,7 @@ async function synthesizeAndEmit(
   const { stats } = session;
   try {
     const startedAt = performance.now();
+    if (!isEngineInstalled()) throw engineMissingError("speech synthesis", "--tts");
     if (opts.out) {
       const voiceLabel = opts.voice ?? "default voice";
       log.status(`Synthesizing ${voiceLabel} -> ${opts.out}...`);
@@ -312,7 +327,7 @@ export const sayCommand = defineCommand({
     },
     out: { type: "string", description: "Write audio to file instead of stdout" },
     rate: { type: "string", description: "Speaking rate 0.5–2.0", default: "1.0" },
-    "list-voices": { type: "boolean", description: "List installed voices and exit" },
+    "list-voices": { type: "boolean", description: "List the voices kesha knows and exit; some need kesha install --tts <lang> first" },
     ssml: {
       type: "boolean",
       description: "Parse input as SSML (supports <speak>, <break>; strips unknown tags)",
@@ -376,7 +391,7 @@ export const sayCommand = defineCommand({
       process.exit(2);
     }
 
-    const positionals = (args._ ?? []).map(String);
+    const positionals = positionalArgs(rawArgs, sayCommand.args as ArgsDef);
     const inlineText =
       positionals.length > 0 ? positionals.join(" ") : typeof args.text === "string" ? args.text : undefined;
     const stdinIsTty = (process.stdin as { isTTY?: boolean }).isTTY;

package/src/diagnostic-log.ts

@@ -21,7 +21,7 @@ import { packageVersion } from "./package-info";
 
 const ACTIVE_LOG_FILE = "kesha.ndjson";
 const STATE_FILE = "diagnostic-logs.json";
-const DEFAULT_MAX_BYTES = 10 * 1024 * 1024;
+const DEFAULT_MAX_BYTES = 10_000_000;
 const DEFAULT_RETAIN = 5;
 const DEFAULT_TAIL_BYTES = 64 * 1024;
 const SAFE_FIELD_NAME = /^[A-Za-z][A-Za-z0-9_]{0,63}$/;
@@ -321,12 +321,12 @@ function rotateIfNeeded(activePath: string, nextBytes: number, maxBytes: number,
 }
 
 export function humanBytes(bytes: number): string {
-  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1000) return `${bytes} B`;
   const units = ["KB", "MB", "GB", "TB"];
-  let value = bytes / 1024;
+  let value = bytes / 1000;
   let unit = units[0];
-  for (let i = 1; i < units.length && value >= 1024; i++) {
-    value /= 1024;
+  for (let i = 1; i < units.length && value >= 1000; i++) {
+    value /= 1000;
     unit = units[i];
   }
   return `${value >= 10 ? value.toFixed(0) : value.toFixed(1)} ${unit}`;

package/src/doctor.ts

@@ -1,5 +1,5 @@
 import { existsSync } from "fs";
-import { cacheComponents, cacheTotalBytes } from "./cache-layout";
+import { cacheComponents, cacheTotalBytes, KOKORO_ONNX_UNUSED_NOTE } from "./cache-layout";
 import { errorMessage } from "./error-utils";
 import { humanBytes } from "./format";
 import { dirname, join } from "path";
@@ -17,6 +17,7 @@ import { engineVersion, packageName, packageVersion } from "./package-info";
 import { getStatsStatus, type StatsStatus } from "./stats";
 import { kokoroAneComponents, kokoroTtsLanguages } from "./kokoro-ane";
 import { isCoremlBackend } from "./fluid-asr-cache";
+import { isDarwinArm64 } from "./engine-targets";
 import {
   fluidExternalRoots,
   fluidExternalTotalBytes,
@@ -36,6 +37,7 @@ const KNOWN_ENV_KEYS = [
   "KESHA_CACHE_DIR",
   "KESHA_MODEL_MIRROR",
   "KESHA_STATS_DB",
+  "KESHA_LOG_DIR",
   "KESHA_DEBUG",
   "KESHA_KOKORO_COMPUTE_UNITS",
   "KESHA_DIARIZE_COMPUTE_UNITS",
@@ -58,6 +60,7 @@ interface PathSummary {
 
 interface CacheComponent extends PathSummary {
   label: string;
+  note?: string;
 }
 
 interface OptionalComponent extends PathSummary {
@@ -318,12 +321,12 @@ async function collectOptionalComponents(
     },
     {
       name: "TTS (Kokoro)",
-      note: "enabled with `kesha install --tts`",
+      note: isDarwinArm64() ? KOKORO_ONNX_UNUSED_NOTE : "enabled with `kesha install --tts`",
       ...pathSummary(join(cache, "models/kokoro-82m")),
     },
     {
       name: "TTS (Vosk RU)",
-      note: "enabled with `kesha install --tts`",
+      note: "enabled with `kesha install --tts ru`",
       ...pathSummary(join(cache, "models/vosk-ru")),
     },
     ...kokoroAneComponents({ homeDir, cacheRoot: cache }).map((c) => ({
@@ -395,7 +398,7 @@ function collectDiagnosticLogs(redact: boolean): DoctorReport["diagnosticLogs"]
       rotatedFiles: [],
       totalSizeBytes: 0,
       mode: "retain-on-failure",
-      maxBytes: 10 * 1024 * 1024,
+      maxBytes: 10_000_000,
       retain: 5,
       error:
         redactString("diagnosticLogsError", errorMessage(err), redact) ??
@@ -501,7 +504,7 @@ function formatCapabilities(engine: DoctorReport["engine"]): string {
 function formatCacheSection(cache: DoctorReport["cache"]): string[] {
   const header = `Cache: ${cache.path} (${cache.exists ? humanBytes(cache.totalBytes) : "missing"})`;
   const rows = cache.components.map(
-    (c) => `  ${c.label}: ${c.exists ? humanBytes(c.sizeBytes) : "missing"}`,
+    (c) => `  ${c.label}: ${c.exists ? humanBytes(c.sizeBytes) : "missing"}${c.note ? ` - ${c.note}` : ""}`,
   );
   return [header, ...rows, ...formatExternalRootsSection(cache)];
 }

package/src/engine-install.ts

@@ -1,7 +1,7 @@
 import { dirname, join, resolve, sep } from "path";
 import { errorMessage } from "./error-utils";
 import { homedir, tmpdir } from "os";
-import { existsSync, mkdirSync, chmodSync, accessSync, constants, rmSync } from "fs";
+import { existsSync, mkdirSync, chmodSync, accessSync, constants, readFileSync, rmSync, writeFileSync } from "fs";
 import { getDescribe, getEngineBinPath } from "./engine";
 import { engineFunctionalHealth, probeExecutable, readExecutableVersion } from "./engine-health";
 import {
@@ -159,6 +159,26 @@ async function rejectMismatchedDownload(
   );
 }
 
+/** `<pin> <sha256 after codesign>` for a download that matched its pin before `darwinTrustBinary` rewrote it. */
+function signedShaPath(path: string): string {
+  return `${path}.signed-sha256`;
+}
+
+function readSignedSha(path: string): string | null {
+  try {
+    return readFileSync(signedShaPath(path), "utf8").trim();
+  } catch {
+    return null;
+  }
+}
+
+async function trustVerifiedDownload(path: string, displayName: string, pinnedSha: string): Promise<void> {
+  darwinTrustBinary(path, displayName);
+  if (process.platform !== "darwin") return;
+  rmSync(signedShaPath(path), { recursive: true, force: true });
+  writeFileSync(signedShaPath(path), `${pinnedSha} ${await sha256OfFile(path)}\n`);
+}
+
 /**
  * Whether a cached asset of the pinned release still hashes to its pin; one that does not is
  * deleted so the verified download replaces it, or refused when its directory is read-only.
@@ -180,7 +200,7 @@ async function cachedAssetMatchesPin(
   } catch (e) {
     throw canRepair ? e : unreadableInReadOnlyDir(path, e);
   }
-  if (actual === expected.sha256) return true;
+  if (actual === expected.sha256 || readSignedSha(path) === `${expected.sha256} ${actual}`) return true;
   const mismatch =
     `Installed ${what} ${assetName} at ${path} does not match ${expected.source} ` +
     `(expected sha256 ${expected.sha256}, got ${actual})`;
@@ -369,7 +389,7 @@ async function downloadSidecar(
       return;
     }
     chmodSync(sidecarPath, 0o755);
-    darwinTrustBinary(sidecarPath, spec.displayName);
+    await trustVerifiedDownload(sidecarPath, spec.displayName, expected.sha256);
     log.progress(`${spec.displayName} installed (${spec.availableHint}).`);
   } catch (e) {
     log.warn(
@@ -674,7 +694,7 @@ async function fetchEngineBinary(
     throw new KeshaError("E_CACHE_CORRUPT", refusal, { hint: MISMATCH_HINT });
   }
   chmodSync(binPath, 0o755);
-  darwinTrustBinary(binPath, "kesha-engine binary");
+  await trustVerifiedDownload(binPath, "kesha-engine binary", expected.sha256);
   // Marker last: writing it first sends the retry down the cacheValid branch, which never waits.
   await waitUntilSpawnable(binPath);
   writeInstalledEngineVersion(binPath, version);

package/src/engine.ts

@@ -7,6 +7,7 @@ import { log } from "./log";
 import { createLiveStatus } from "./progress";
 import { defaultEngineBinPath, keshaCacheDir } from "./paths";
 import { engineAbortError, interruptedRun } from "./process-tree";
+import { resolveStatePaths } from "./state-paths";
 import { engineExitCause, engineSignal, runEngineProcess, spawnHint } from "./engine/spawn";
 import { engineFailure, KeshaError, quoteInvalidLine, renderError, SUPPORT_BUNDLE_HINT, type ErrorEvent } from "./engine/events";
 import { MIN_ENGINE_VERSION, predatesMinimumEngine, readInstalledEngineVersion } from "./engine-version-marker";
@@ -76,6 +77,17 @@ export function isEngineInstalled(): boolean {
   return existsSync(getEngineBinPath());
 }
 
+/** The E_ENGINE_SPAWN for a missing engine: it names the path looked at and the variable that chose it. */
+export function engineMissingError(backend: string, ...installFlags: string[]): KeshaError {
+  const cacheSource = resolveStatePaths().cacheDir.source;
+  const hint = process.env.KESHA_ENGINE_BIN
+    ? spawnHint()
+    : cacheSource === "default"
+      ? `bun add -g @drakulavich/kesha-voice-kit, then ${installHint(...installFlags)}`
+      : `${cacheSource} is set; run \`${installHint(...installFlags)}\` to install there, or unset it`;
+  return new KeshaError("E_ENGINE_SPAWN", `No ${backend} backend is installed: no kesha-engine at ${getEngineBinPath()}`, { hint });
+}
+
 export interface RunEngineOptions {
   signal?: AbortSignal;
   /** Text for the subprocess's stdin. Nothing a user typed may become an argv element: a NUL byte or a megabyte of it makes the spawn itself fail (#T1-1). */

package/src/format.ts

@@ -69,14 +69,14 @@ export function formatJsonOutput(
   return JSON.stringify(payload, null, 2) + "\n";
 }
 
-/** Render a byte count as a human-readable size (e.g. "1.5 MB"). */
+/** Render a byte count as a human-readable decimal size (e.g. "1.5 MB" for 1,500,000 bytes). */
 export function humanBytes(bytes: number): string {
-  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1000) return `${bytes} B`;
   const units = ["KB", "MB", "GB", "TB"];
-  let n = bytes / 1024;
+  let n = bytes / 1000;
   let i = 0;
-  while (n >= 1024 && i < units.length - 1) {
-    n /= 1024;
+  while (n >= 1000 && i < units.length - 1) {
+    n /= 1000;
     i++;
   }
   return `${n.toFixed(n >= 100 ? 0 : 1)} ${units[i]}`;

package/src/install-plan.ts

@@ -116,7 +116,7 @@ function releaseAssetSize(assetName: string, version: string): number | null {
 function filesCached(cacheRoot: string, files: PlanFile[]): boolean {
   return files.every((file) => {
     const path = join(cacheRoot, file.relPath);
-    return existsSync(path) && statSync(path).size > 0;
+    return existsSync(path) && statSync(path).size === file.sizeBytes;
   });
 }
 
@@ -467,7 +467,7 @@ function renderBehaviorLines(ttsLangs: string[], wantsAnyKokoro: boolean): strin
     isDarwinArm64()
       ? "  - macOS install signs/unquarantines downloaded binaries for Gatekeeper."
       : "  - No macOS Gatekeeper signing step on this platform.",
-    "  - install warms the ASR backend after downloads; CoreML warm-up is typically 20-30 s, ONNX warm-up is about 500 ms.",
+    "  - install warms the ASR backend after downloads; CoreML warm-up typically takes 1-2 min, ONNX warm-up is about 500 ms.",
   ];
   if (ttsLangs.length > 0 && wantsAnyKokoro && isDarwinArm64()) {
     lines.push(

package/src/mcp/tools.ts

@@ -30,11 +30,11 @@ export function registerTools(server: McpServer): void {
       try {
         bytes = readFileSync(filePath);
       } catch {
-        // The SDK sends only `message`, so the code and hint go inside it.
+        // The SDK sends only `message` and `code`; McpError would prepend "MCP error -32002:" to the message.
         const coded = new KeshaError("E_INPUT_NOT_FOUND", `synthesized-audio: file not found or already swept: ${name}`, {
           hint: "synthesized files are deleted after 24 hours; call synthesize_speech again.",
         });
-        throw new Error(errorMessage(coded));
+        throw Object.assign(new Error(errorMessage(coded)), { code: -32002 });
       }
       return { contents: [{ uri: uri.href, mimeType: mimeForExt(name), blob: bytes.toString("base64") }] };
     },
@@ -46,7 +46,7 @@ export function registerTools(server: McpServer): void {
       title: "Synthesize speech",
       description:
         "Synthesize speech from text into an audio file and return a resource link. " +
-        "Omit voice to auto-route by language (male defaults en-am_michael / ru-vosk-m02).",
+        "Omit voice (or pass an empty string) to auto-route by language (male defaults en-am_michael / ru-vosk-m02).",
       inputSchema: {
         text: z.string().min(1).describe("Text to speak"),
         voice: z.string().optional().describe("Voice id, e.g. en-am_michael"),
@@ -84,7 +84,7 @@ export function registerTools(server: McpServer): void {
       }
       try {
         // An MCP caller has no stderr to read: the voice it is told is its only record (#942).
-        const resolvedVoice = (await resolveSayVoice(voice, undefined, text, { signal: extra.signal })) ?? DEFAULT_VOICE_ID;
+        const resolvedVoice = (await resolveSayVoice(voice || undefined, undefined, text, { signal: extra.signal })) ?? DEFAULT_VOICE_ID;
         await say({ text, voice: resolvedVoice, rate, format: fmt, out: outPath, signal: extra.signal });
         chmodSync(outPath, 0o600);
         const bytes = statSync(outPath).size;
@@ -163,7 +163,7 @@ export function registerTools(server: McpServer): void {
     "list_voices",
     {
       title: "List voices",
-      description: "List installed TTS voices with their engine and language.",
+      description: "List the TTS voices kesha knows, with their engine and language. Some need `kesha install --tts <lang>` before they synthesize.",
       inputSchema: {},
       outputSchema: {
         voices: z.array(
@@ -182,7 +182,7 @@ export function registerTools(server: McpServer): void {
     async () => {
       try {
         const voices = await listVoices();
-        const text = voices.length === 0 ? `0 voices installed. Run: ${installHint("--tts")}` : `${voices.length} voices installed.`;
+        const text = voices.length === 0 ? `0 voices installed. Run: ${installHint("--tts")}` : `${voices.length} voices known; some need kesha install --tts <lang> before use.`;
         return {
           content: [{ type: "text" as const, text }],
           structuredContent: { voices },
@@ -197,7 +197,7 @@ export function registerTools(server: McpServer): void {
     "list_languages",
     {
       title: "List languages",
-      description: "List languages available for synthesis, derived from installed voices.",
+      description: "List languages available for synthesis, derived from the voices list_voices reports.",
       inputSchema: {},
       outputSchema: {
         languages: z.array(

package/src/mcp/voices.ts

@@ -106,6 +106,7 @@ export async function listVoices(): Promise<VoiceInfo[]> {
 export function aggregateLanguages(voices: VoiceInfo[]): LanguageInfo[] {
   const map = new Map<string, LanguageInfo>();
   for (const v of voices) {
+    if (!v.languageCode) continue;
     const existing = map.get(v.languageCode);
     if (existing) existing.voiceCount++;
     else map.set(v.languageCode, { languageCode: v.languageCode, languageName: v.languageName, voiceCount: 1 });

package/src/progress.ts

@@ -8,7 +8,7 @@ const BAR_WIDTH = 20;
 const DEFAULT_ESTIMATED_PROGRESS_MS = 30 * 60 * 1000;
 
 export function formatBytes(bytes: number): string {
-  return `${(bytes / 1024 / 1024).toFixed(1)}MB`;
+  return `${(bytes / 1000 / 1000).toFixed(1)}MB`;
 }
 
 function bar(pct: number): string {

package/src/support-bundle.ts

@@ -110,6 +110,14 @@ function existsAsLink(path: string): boolean {
   }
 }
 
+function isRegularFile(path: string): boolean {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+
 function fileInTheWay(dir: string): string | null {
   for (let d = dir; ; d = dirname(d)) {
     try {
@@ -168,6 +176,11 @@ export async function createSupportBundle(
 ): Promise<SupportBundleResult> {
   const now = options.now ?? new Date();
   const outputPath = resolve(options.output ?? defaultBundlePath(now));
+  if (isRegularFile(outputPath)) {
+    throw new KeshaError("E_INVALID_ARG", `Cannot write the support bundle to ${outputPath}: the file already exists`, {
+      hint: `pass --output a path that does not exist yet, or delete ${outputPath} first.`,
+    });
+  }
   const redact = options.redact ?? true;
   const report = await collectDoctorReport({ redact });
   const root = basename(outputPath).replace(/\.tar\.gz$/, "");

package/src/synth.ts

@@ -1,8 +1,7 @@
-import { getDescribe, getEngineBinPath, isEngineInstalled } from "./engine";
+import { engineMissingError, getDescribe, getEngineBinPath, isEngineInstalled } from "./engine";
 import { engineSignal, runEngineProcess } from "./engine/spawn";
 import { validateArgv } from "./engine/describe";
 import { engineFailure, exitCodeFor, KeshaError, type EventSinks } from "./engine/events";
-import { installHint } from "./install-hint";
 import { log } from "./log";
 import { engineAbortError, interruptedRun } from "./process-tree";
 
@@ -155,10 +154,7 @@ export async function say(opts: SayOptions): Promise<Uint8Array> {
   validateSayText(text);
 
   if (!isEngineInstalled()) {
-    throw new KeshaError("E_ENGINE_SPAWN", `kesha-engine not installed. run: ${installHint("--tts")}`, {
-      exitCode: 1,
-      stderr: "",
-    });
+    throw engineMissingError("speech synthesis", "--tts");
   }
   const { argv: args, warnings } = validateArgv(buildSayArgs({ ...opts, text: undefined }), await getDescribe({ signal: opts.signal }));
   for (const warning of warnings) log.warn(warning);
@@ -195,7 +191,7 @@ export async function say(opts: SayOptions): Promise<Uint8Array> {
 /** Installed voice ids as the engine lists them, one per line; a missing engine, a build without tts or a failed run is a KeshaError. */
 export async function listVoiceIds(sinks: EventSinks = {}, signal?: AbortSignal): Promise<string[]> {
   if (!isEngineInstalled()) {
-    throw new KeshaError("E_ENGINE_SPAWN", `kesha-engine not installed. run: ${installHint()}`);
+    throw engineMissingError("speech synthesis");
   }
   if (signal?.aborted) throw engineAbortError();
   const { argv, warnings } = validateArgv(["say", "--list-voices"], await getDescribe({ signal }));

package/src/transcribe.ts

@@ -1,6 +1,7 @@
 import {
   assertSpeakerModelsInstalled,
   buildTranscribeArgs,
+  engineMissingError,
   getDescribe,
   isEngineInstalled,
   transcribeEngine,
@@ -10,8 +11,8 @@ import {
 } from "./engine";
 import { validateArgv } from "./engine/describe";
 import { KeshaError } from "./engine/events";
-import { installHint } from "./install-hint";
-import { existsSync, statSync } from "fs";
+import { closeSync, existsSync, fstatSync, openSync, readSync, statSync } from "fs";
+import { isAbsolute } from "path";
 
 export type { VadMode };
 
@@ -24,11 +25,18 @@ export function isDirectoryPath(path: string): boolean {
   }
 }
 
+/** The next step for E_INPUT_NOT_FOUND, shared by the CLI and the Core API. */
+export function missingFileHint(path: string): string {
+  return isAbsolute(path) ? "check the path" : `check the path, relative to the current directory ${process.cwd()}`;
+}
+
 export const SPECIAL_FILE_HINT =
   "kesha reads its input more than once, so a named pipe, /dev/stdin or <(...) cannot work; save the audio to a file and pass that.";
 
 /** True when `path` exists and is neither a regular file nor a directory: the engine opens its input more than once, so a FIFO, `/dev/stdin` or `<(...)` hangs it (#1468). */
 export function isSpecialFilePath(path: string): boolean {
+  // stat follows /dev/stdin to whatever stdin holds, so `kesha /dev/stdin < en.wav` would look like a regular file.
+  if (path === "/dev/stdin" || path.startsWith("/dev/fd/")) return true;
   try {
     const st = statSync(path);
     return !st.isFile() && !st.isDirectory();
@@ -37,6 +45,38 @@ export function isSpecialFilePath(path: string): boolean {
   }
 }
 
+/** Seconds a RIFF WAV's data chunk declares and seconds the file holds, when the file is shorter than its header says; null otherwise. */
+export function truncatedWavSeconds(path: string): { declared: number; present: number } | null {
+  let fd: number | undefined;
+  try {
+    fd = openSync(path, "r");
+    const size = fstatSync(fd).size;
+    const buf = Buffer.alloc(20);
+    if (readSync(fd, buf, 0, 12, 0) < 12 || buf.toString("ascii", 0, 4) !== "RIFF" || buf.toString("ascii", 8, 12) !== "WAVE") {
+      return null;
+    }
+    let byteRate = 0;
+    for (let offset = 12; offset + 8 <= size; ) {
+      readSync(fd, buf, 0, 20, offset);
+      const id = buf.toString("ascii", 0, 4);
+      const length = buf.readUInt32LE(4);
+      if (id === "fmt ") byteRate = buf.readUInt32LE(16);
+      if (id === "data") {
+        const present = size - offset - 8;
+        // Streaming writers leave 0xFFFFFFFF in the size field when they cannot seek back to fill it in.
+        if (length === 0xffffffff || byteRate === 0 || length <= present) return null;
+        return { declared: length / byteRate, present: present / byteRate };
+      }
+      offset += 8 + length + (length % 2);
+    }
+    return null;
+  } catch {
+    return null;
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
 export interface TranscribeOptions {
   /** Silero VAD preprocessing selector. Defaults to `"auto"`. */
   vad?: VadMode;
@@ -62,7 +102,7 @@ export interface TranscribeOptions {
 /** The refusals the CLI makes before it spawns anything, so an agent branching on the documented code sees it on every surface. */
 export function assertAudioFileArgument(audioPath: string): void {
   if (!existsSync(audioPath)) {
-    throw new KeshaError("E_INPUT_NOT_FOUND", `File not found: ${audioPath}`);
+    throw new KeshaError("E_INPUT_NOT_FOUND", `File not found: ${audioPath}`, { hint: missingFileHint(audioPath) });
   }
   if (isDirectoryPath(audioPath)) {
     throw new KeshaError("E_INVALID_ARG", `${audioPath}: is a directory (expected an audio file)`);
@@ -75,9 +115,7 @@ export function assertAudioFileArgument(audioPath: string): void {
 /** The CLI's gate before any progress UI: the engine, its describe document, the request's flags, and the model files a request needs; the argv actually sent is validated again at the spawn. */
 export async function validateTranscribeRequest(opts: TranscribeOptions = {}): Promise<void> {
   if (!isEngineInstalled()) {
-    throw new KeshaError("E_ENGINE_SPAWN", "No transcription backend is installed", {
-      hint: `bun add -g @drakulavich/kesha-voice-kit, then ${installHint()}`,
-    });
+    throw engineMissingError("transcription");
   }
   validateArgv(
     buildTranscribeArgs(