@drakulavich/kesha-voice-kit 1.19.0-beta.2 → 1.20.0

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="docs/assets/logo.png" alt="Kesha Voice Kit" width="200">
+  <img src="https://raw.githubusercontent.com/drakulavich/kesha-voice-kit/main/docs/assets/logo.png" alt="Kesha Voice Kit" width="200">
 </p>
 
 <h1 align="center">Kesha Voice Kit</h1>
@@ -21,7 +21,7 @@
 See [Product positioning](docs/product-positioning.md) for supported workflows, non-goals, maturity labels, and the platform matrix.
 
 <p align="center">
-  <img src="./demo.gif" alt="kesha demo — English + Russian transcription with automatic language detection" width="800">
+  <img src="https://raw.githubusercontent.com/drakulavich/kesha-voice-kit/main/demo.gif" alt="kesha demo — English + Russian transcription with automatic language detection" width="800">
 </p>
 
 ## Quick Start
@@ -104,6 +104,16 @@ kesha say "Hello, world" > hello.wav
 kesha say "Привет, мир" > privet.wav     # auto-routes (Milena on darwin, ru-vosk-m02 elsewhere)
 ```
 
+**Output formats** (`--format`, or inferred from `--out` extension):
+
+```bash
+kesha say "Hello" --out hi.wav                       # WAV (default, uncompressed)
+kesha say "Hello" --format ogg-opus --out hi.ogg     # OGG/Opus — messenger voice notes (Telegram/WhatsApp/Signal)
+kesha say "Hello" --format flac --out hi.flac        # FLAC — lossless, royalty-free, plays in every browser incl. Safari/iOS
+```
+
+FLAC is the format for web-embeddable samples: it plays natively in all modern browsers (including Safari/iOS, where OGG/Opus does not), stays royalty-free like Opus, and keeps the engine's native sample rate (no resample). `--bitrate` / `--sample-rate` apply only to `--format ogg-opus`.
+
 **Russian abbreviations** (`ru-vosk-*`): all-uppercase Cyrillic 2-5-char tokens auto-expand letter-by-letter when not pronounceable as a Russian syllable (ФСБ → "эф-эс-бэ", ВОЗ → "воз"). Disable with `--no-expand-abbrev`. See [docs/tts.md#russian-abbreviation-auto-expansion](docs/tts.md#russian-abbreviation-auto-expansion).
 
 **English acronyms** (`en-*`, Kokoro): three-table mechanism (letter-spell rule + STOP_LIST + IPA_LEXICON) auto-expands FBI → "ef bee eye" and gives EPAM/JSON/Anthropic the right IPA. Disable letter-spell with `--no-expand-abbrev`. See [docs/tts.md#english-acronym-auto-expansion](docs/tts.md#english-acronym-auto-expansion).
@@ -232,7 +242,7 @@ mandb ~/.local/share/man 2>/dev/null || true
 
 Compared against Whisper `large-v3-turbo` — all engines auto-detect language.
 
-![Benchmark: openai-whisper vs faster-whisper vs Kesha Voice Kit](docs/assets/benchmark.svg)
+![Benchmark: openai-whisper vs faster-whisper vs Kesha Voice Kit](https://raw.githubusercontent.com/drakulavich/kesha-voice-kit/main/docs/assets/benchmark.svg)
 
 See [BENCHMARK.md](BENCHMARK.md) for the full per-file breakdown (Russian + English).
 
@@ -280,6 +290,10 @@ Cache boundary: `kesha install` and opt-in feature installs populate the local
 cache; ordinary transcription and speech commands fail fast if required assets
 are missing.
 
+Contributors: see [`docs/architecture.md`](docs/architecture.md) for the
+code-level map (repo layout, CLI↔engine boundary, backends, model pinning,
+tests, and a "where to change X" table).
+
 ## What's Inside
 
 | Model | Task | Size | Source |

package/SKILL.md

@@ -25,6 +25,7 @@ Local voice toolkit: transcribe voice messages to text, synthesize speech, detec
 - **Need to send a voice note (Telegram, WhatsApp, Signal, Discord)**: synthesize directly into messenger-native OGG/Opus with `kesha say --format ogg-opus --out reply.ogg "<text>"`. Default is mono 24 kHz @ 32 kbps - what Telegram `sendVoice` expects. No WAV redirect and no `ffmpeg` round-trip.
 - **Need local file playback/debug output**: WAV is still available with `kesha say --out reply.wav "<text>"`, but do not use WAV for Telegram voice replies. Auto-routes by detected language (Kokoro-82M for English, Vosk-TTS for Russian). On darwin-arm64, English Kokoro uses FluidAudio CoreML instead of ONNX. For other languages and ~180 more voices use `--voice macos-*` on macOS (zero model download).
 - **Need to detect what language a file is in** before choosing a pipeline: `kesha --json audio.ogg` returns both audio-based and text-based language detection with confidence scores.
+- **Need to capture your own voice** for transcription or as a voice-note source: `kesha record --out clip.wav` records up to 120s (override with `--max-seconds`) of mono 16 kHz WAV from the default microphone. Pipe straight into `kesha --json clip.wav` to close the loop.
 
 ## OpenClaw plugin setup
 
@@ -150,9 +151,12 @@ Each `segment.speaker` is a number (cluster id, stable within one file). On Linu
 - `kesha audio.ogg` — plain transcript on stdout
 - `kesha --format transcript audio.ogg` — transcript + `[lang: ru, confidence: 0.99]` footer
 - `kesha --json --timestamps audio.ogg` — JSON with timestamped `segments`
+- `kesha --toon audio.ogg` — TOON (compact, LLM-friendly JSON encoding); preferred when piping multi-file results to an LLM/agent
 - `kesha --verbose audio.ogg` — human-readable with language info
 - `kesha --lang en audio.ogg` — warn if detected language differs (useful sanity check)
 
+**Long audio:** files ≥ 120 s auto-engage Silero VAD chunking; force on with `--vad` or off with `--no-vad`. Short files use full-file ASR by default.
+
 ## TTS: synthesize speech
 
 ```bash
@@ -164,6 +168,12 @@ kesha say --list-voices                            # Kokoro + Vosk-TTS + ~180 ma
 
 Output: WAV mono float32 by default. `--out <path>` writes to a file instead of stdout. For Telegram/OpenClaw replies, prefer `--format ogg-opus --out reply.ogg` or the OpenClaw-provided `{{OutputPath}}`.
 
+**Output formats** (`--format`, or inferred from the `--out` extension): `wav` (default, uncompressed), `ogg-opus` (messenger voice notes), `flac` (lossless, royalty-free, plays in every browser incl. Safari/iOS — the format for web-embeddable samples). FLAC keeps the engine's native rate; `--bitrate` / `--sample-rate` apply only to `ogg-opus`.
+
+```bash
+kesha say --format flac --out sample.flac "Hello"   # web-embeddable, Safari-safe
+```
+
 **Voice notes (Telegram / WhatsApp / Signal / Discord):** add `--format ogg-opus` to emit OGG/Opus directly — the format messenger APIs render as a native voice message:
 
 ```bash
@@ -188,12 +198,25 @@ Format is also inferred from `--out` extension (`.ogg` / `.opus` / `.oga` → OG
 
 ## Install
 
+**Humans use `kesha init` (guided). Agents and scripts use `kesha install` (deterministic).**
+
 ```bash
-bun add -g @drakulavich/kesha-voice-kit          # global CLI install
-kesha install                                    # downloads engine (~350 MB)
-kesha install --tts                              # adds Kokoro + Vosk-TTS RU (~990 MB more, for TTS)
+bun add -g @drakulavich/kesha-voice-kit          # global CLI install (always first)
+
+# For humans: interactive setup that prompts for backend / TTS / VAD / diarize
+kesha init
+
+# For agents and CI: explicit, scriptable install commands
+kesha install                                    # engine only (~350 MB)
+kesha install --tts                              # + Kokoro + Vosk-TTS RU (~990 MB more)
+kesha install --tts --vad                        # + Silero VAD (long-audio chunking)
+kesha install --tts --vad --diarize              # + speaker diarization (darwin-arm64 only)
 ```
 
+Kesha's runtime error/warning messages adapt to the same split: when `kesha` is invoked from a TTY, hints suggest `kesha init`; when stderr is piped (CI logs, OpenClaw, agent subprocess), hints suggest the equivalent `kesha install [...flags]`. Both run the same install code under the hood — pick the one your caller is.
+
+For pre-release builds: `bun add -g @drakulavich/kesha-voice-kit@beta` (current `beta` channel; `@latest` stays on the last stable release).
+
 No system deps — English G2P is embedded (`misaki-rs`); Russian G2P is bundled inside Vosk-TTS. `macos-*` voices need no install either — they use voices already on the Mac.
 
 ## Supported languages
@@ -207,6 +230,13 @@ No system deps — English G2P is embedded (`misaki-rs`); Russian G2P is bundled
 - ASR: ~19× faster than OpenAI Whisper on Apple Silicon (CoreML via FluidAudio), ~2.5× on CPU (ONNX via `ort`).
 - TTS: sub-second latency for short utterances on Apple Silicon.
 
+## Troubleshooting
+
+- `kesha doctor` — collect support diagnostics without changing local state. Add `--json` for machine-readable output, `--redact` to scrub secrets and home paths before sharing.
+- `kesha logs` — manage privacy-safe local diagnostic logs. Default mode is `retain-on-failure` (events buffered in memory, flushed to disk only when a command fails). `kesha logs mode on` captures every run, `kesha logs path` prints the NDJSON file, `kesha logs disable` turns it off entirely.
+- `kesha support-bundle --output bundle.tar.gz` — produce a redacted `.tar.gz` for filing an issue. Add `--include-logs` to bundle a bounded tail of diagnostic logs.
+- `kesha stats` — manage local anonymous performance stats (per-command latency percentiles). Actions: `enable | disable | status | week | errors | export | reset | vacuum | retention`. Stays on the machine.
+
 ## Why local
 
 No API keys to manage. No per-minute billing. Voice data never leaves the machine — important for regulated industries, personal messaging, and anything that shouldn't be in a third-party log.

package/completions/kesha.fish

@@ -69,7 +69,7 @@ complete -c kesha -n '__fish_seen_subcommand_from say' -l out -r -d 'Write audio
 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 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) or ogg-opus (Telegram-ready voice note). Inferred from --out extension when omitted.'
+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.'
 complete -c kesha -n '__fish_seen_subcommand_from say' -l sample-rate -r -d 'Opus encoder sample rate (8000/12000/16000/24000/48000). Only with --format ogg-opus.'
 complete -c kesha -n '__fish_seen_subcommand_from say' -l no-expand-abbrev -d 'Disable Russian acronym auto-expansion (ВОЗ → \'вэ о зэ\') for ru-vosk-* voices. <say-as interpret-as=\'characters\'> still works. Applies to Russian (ru-vosk-*) and English (en-*) voices.'

package/completions/kesha.zsh

@@ -99,7 +99,7 @@ _kesha() {
         '--rate=[Speaking rate 0.5–2.0]:rate:' \
         '--list-voices[List installed voices and exit]' \
         '--ssml[Parse input as SSML (supports <speak>, <break>; strips unknown tags)]' \
-        '--format=[Output format: wav (default) or ogg-opus (Telegram-ready voice note). Inferred from --out extension when omitted.]:format:' \
+        '--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:' \
         '--sample-rate=[Opus encoder sample rate (8000/12000/16000/24000/48000). Only with --format ogg-opus.]:sample rate:' \
         '--no-expand-abbrev[Disable Russian acronym auto-expansion (ВОЗ → '\''вэ о зэ'\'') for ru-vosk-* voices. <say-as interpret-as='\''characters'\''> still works. Applies to Russian (ru-vosk-*) and English (en-*) voices.]' \

package/man/kesha.1

@@ -1,4 +1,4 @@
-.TH KESHA 1 "May 2026" "kesha 1.19.0-beta.2" "User Commands"
+.TH KESHA 1 "May 2026" "kesha 1.20.0" "User Commands"
 .SH NAME
 kesha \- open-source local voice toolkit
 .SH SYNOPSIS
@@ -167,7 +167,7 @@ List installed voices and exit
 Parse input as SSML (supports <speak>, <break>; strips unknown tags)
 .TP
 .B \-\-format
-Output format: wav (default) or ogg\-opus (Telegram\-ready voice note). Inferred from \-\-out extension when omitted.
+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.
 .TP
 .B \-\-bitrate
 Opus bitrate in bits/sec (e.g. 32000). Only with \-\-format ogg\-opus.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/kesha-voice-kit",
-  "version": "1.19.0-beta.2",
+  "version": "1.20.0",
   "description": "Give your local tools a voice: fast STT in 25 languages (~19x faster than Whisper on Apple Silicon, ONNX CPU fallback), TTS via Kokoro/Vosk/macOS voices, VAD + 107-language detection. Rust engine, Bun CLI, OpenClaw skill.",
   "type": "module",
   "bin": {
@@ -32,7 +32,7 @@
     ]
   },
   "keshaEngine": {
-    "version": "1.19.0-beta.2"
+    "version": "1.20.0"
   },
   "scripts": {
     "test": "bun test",
@@ -79,7 +79,7 @@
   "devDependencies": {
     "@types/bun": "latest",
     "@typescript/native-preview": "^7.0.0-dev.20260423.1",
-    "fast-xml-parser": "^5.5.10",
+    "fast-xml-parser": "^5.8.0",
     "typescript": "^6.0.2",
     "yaml": "^2.9.0"
   },

package/src/cli/dispatch.ts

@@ -1,4 +1,4 @@
-import { runMain } from "citty";
+import { runMain, type CommandDef } from "citty";
 import { existsSync } from "fs";
 import { log } from "../log";
 import { suggestCommand } from "../suggest-command";
@@ -15,19 +15,23 @@ import { statusCommand } from "./status";
 import { supportBundleCommand } from "./support-bundle";
 import { mainCommand } from "./main";
 
-const SUBCOMMANDS = [
-  "doctor",
-  "init",
-  "install",
-  "logs",
-  "status",
-  "record",
-  "say",
-  "stats",
-  "support-bundle",
-  "completions",
-  "manpage",
-];
+// Single source of truth: keyed lookup also feeds the `did you mean` suggester.
+// `CommandDef<any>` is intentional — citty's generic is invariant in the args
+// shape, and each subcommand has its own arg schema; the value here is only
+// passed back to `runMain`, which re-reads the schema from the def itself.
+const SUBCOMMANDS: Record<string, CommandDef<any>> = {
+  doctor: doctorCommand,
+  init: initCommand,
+  install: installCommand,
+  logs: logsCommand,
+  status: statusCommand,
+  record: recordCommand,
+  say: sayCommand,
+  stats: statsCommand,
+  "support-bundle": supportBundleCommand,
+  completions: completionsCommand,
+  manpage: manpageCommand,
+};
 
 function isPathLike(arg: string): boolean {
   return arg.includes(".") || arg.includes("/") || existsSync(arg);
@@ -36,58 +40,8 @@ function isPathLike(arg: string): boolean {
 export async function runCli(rawArgs = process.argv.slice(2)): Promise<void> {
   const [firstArg, ...restArgs] = rawArgs;
 
-  if (firstArg === "doctor") {
-    await runMain(doctorCommand, { rawArgs: restArgs });
-    return;
-  }
-
-  if (firstArg === "init") {
-    await runMain(initCommand, { rawArgs: restArgs });
-    return;
-  }
-
-  if (firstArg === "completions") {
-    await runMain(completionsCommand, { rawArgs: restArgs });
-    return;
-  }
-
-  if (firstArg === "install") {
-    await runMain(installCommand, { rawArgs: restArgs });
-    return;
-  }
-
-  if (firstArg === "logs") {
-    await runMain(logsCommand, { rawArgs: restArgs });
-    return;
-  }
-
-  if (firstArg === "manpage") {
-    await runMain(manpageCommand, { rawArgs: restArgs });
-    return;
-  }
-
-  if (firstArg === "status") {
-    await runMain(statusCommand, { rawArgs: restArgs });
-    return;
-  }
-
-  if (firstArg === "record") {
-    await runMain(recordCommand, { rawArgs: restArgs });
-    return;
-  }
-
-  if (firstArg === "say") {
-    await runMain(sayCommand, { rawArgs: restArgs });
-    return;
-  }
-
-  if (firstArg === "stats") {
-    await runMain(statsCommand, { rawArgs: restArgs });
-    return;
-  }
-
-  if (firstArg === "support-bundle") {
-    await runMain(supportBundleCommand, { rawArgs: restArgs });
+  if (firstArg && Object.hasOwn(SUBCOMMANDS, firstArg)) {
+    await runMain(SUBCOMMANDS[firstArg], { rawArgs: restArgs });
     return;
   }
 
@@ -95,7 +49,7 @@ export async function runCli(rawArgs = process.argv.slice(2)): Promise<void> {
   // Extensionless existing files remain valid transcription inputs; missing
   // bare tokens are more likely command typos and should not start the engine.
   if (firstArg && !firstArg.startsWith("-") && !isPathLike(firstArg)) {
-    const suggestion = suggestCommand(firstArg, SUBCOMMANDS);
+    const suggestion = suggestCommand(firstArg, Object.keys(SUBCOMMANDS));
     log.error(`unknown command '${firstArg}'`);
     if (suggestion && suggestion !== firstArg) {
       log.warn(`(Did you mean ${suggestion}?)`);

package/src/cli/say.ts

@@ -100,7 +100,7 @@ export const sayCommand = defineCommand({
     format: {
       type: "string",
       description:
-        "Output format: wav (default) or ogg-opus (Telegram-ready voice note). Inferred from --out extension when omitted.",
+        "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.",
     },
     bitrate: {
       type: "string",
@@ -145,12 +145,12 @@ export const sayCommand = defineCommand({
     const fmtArg = typeof args.format === "string" ? args.format.toLowerCase() : undefined;
     let format: SayFormat | undefined;
     if (fmtArg) {
-      if (fmtArg === "wav" || fmtArg === "ogg-opus") {
+      if (fmtArg === "wav" || fmtArg === "ogg-opus" || fmtArg === "flac") {
         format = fmtArg;
       } else if (fmtArg === "opus" || fmtArg === "ogg") {
         format = "ogg-opus";
       } else {
-        log.error(`unknown --format '${args.format}'. supported: wav, ogg-opus`);
+        log.error(`unknown --format '${args.format}'. supported: wav, ogg-opus, flac`);
         process.exit(2);
       }
     }
@@ -166,7 +166,10 @@ export const sayCommand = defineCommand({
         ? args.out.split(".").pop()?.toLowerCase()
         : undefined;
       const impliesOpus = outExt && ["ogg", "opus", "oga"].includes(outExt);
-      if (format === "wav" || (format === undefined && !impliesOpus)) {
+      // --bitrate / --sample-rate are Opus-only. Reject for wav and flac
+      // (both lossless / no encoder knobs) and for any non-Opus extension.
+      const resolvesToOpus = format === "ogg-opus" || (format === undefined && impliesOpus);
+      if (!resolvesToOpus) {
         log.error("--bitrate and --sample-rate are only valid with --format ogg-opus");
         process.exit(2);
       }

package/src/diagnostic-log.ts

@@ -100,9 +100,8 @@ function readConfig(): DiagnosticLogConfig {
   if (!existsSync(statePath)) return defaultConfig();
   try {
     const parsed = JSON.parse(readFileSync(statePath, "utf8")) as Partial<DiagnosticLogConfig>;
-    const parsedMode = parseMode(parsed.mode);
     return {
-      mode: parsedMode ?? defaultConfig().mode,
+      mode: parseDiagnosticLogMode(parsed.mode) ?? defaultConfig().mode,
       maxBytes: positiveInt(parsed.maxBytes, DEFAULT_MAX_BYTES),
       retain: positiveInt(parsed.retain, DEFAULT_RETAIN),
     };
@@ -111,11 +110,7 @@ function readConfig(): DiagnosticLogConfig {
   }
 }
 
-export function parseDiagnosticLogMode(value: string): DiagnosticLogMode | null {
-  return parseMode(value);
-}
-
-function parseMode(value: unknown): DiagnosticLogMode | null {
+export function parseDiagnosticLogMode(value: unknown): DiagnosticLogMode | null {
   return value === "off" || value === "on" || value === "retain-on-failure" ? value : null;
 }
 
@@ -219,9 +214,11 @@ export function resetDiagnosticLogs(): { deleted: number; bytes: number; dir: st
 
 export function createDiagnosticLogSession(): DiagnosticLogSession {
   const status = getDiagnosticLogStatus();
+  if (status.mode === "off") {
+    return { event: () => false, finish: () => false };
+  }
   const buffered: Uint8Array[] = [];
   let finished = false;
-  if (status.mode === "off") return noopSession();
 
   return {
     event(event: string, fields: DiagnosticLogFields = {}): boolean {
@@ -261,13 +258,6 @@ export function createDiagnosticLogSession(): DiagnosticLogSession {
   };
 }
 
-function noopSession(): DiagnosticLogSession {
-  return {
-    event: () => false,
-    finish: () => false,
-  };
-}
-
 function appendDiagnosticLogLine(line: Uint8Array, status: DiagnosticLogStatus): void {
   mkdirSync(status.dir, { recursive: true });
   rotateIfNeeded(status.activePath, line.byteLength, status.maxBytes, status.retain);

package/src/engine.ts

@@ -1,5 +1,6 @@
 import { existsSync, statSync } from "fs";
 import { join } from "path";
+import { installHint } from "./install-hint";
 import { log } from "./log";
 import { defaultEngineBinPath, keshaCacheDir } from "./paths";
 import { engineAbortError, registerProcessTree } from "./process-tree";
@@ -219,17 +220,21 @@ export async function preflightTranscribeEngineWithSegments(
   if (hasDiarizeModelLayout(modelPath)) return;
   throw new Error(
     `speaker diarization requires a model path\n\nCaused by:\n    diarization model not found at ${modelPath}. ` +
-      "Run `kesha install --diarize` (or set KESHA_DIARIZE_MODEL_PATH).",
+      `Run \`${installHint("--diarize")}\` (or set KESHA_DIARIZE_MODEL_PATH).`,
   );
 }
 
+function vadArg(vad: VadMode | undefined): string[] {
+  if (vad === "on") return ["--vad"];
+  if (vad === "off") return ["--no-vad"];
+  return [];
+}
+
 export async function transcribeEngine(
   audioPath: string,
   opts: TranscribeEngineOptions = {},
 ): Promise<string> {
-  const args = ["transcribe", audioPath];
-  if (opts.vad === "on") args.push("--vad");
-  else if (opts.vad === "off") args.push("--no-vad");
+  const args = ["transcribe", audioPath, ...vadArg(opts.vad)];
   const { stdout, stderr, exitCode } = await runEngine(args, { signal: opts.signal });
   if (exitCode !== 0) {
     throw new Error(stderr || `kesha-engine exited with code ${exitCode}`);
@@ -266,12 +271,8 @@ export async function transcribeEngineWithSegments(
 ): Promise<TranscriptionOutput> {
   await preflightTranscribeEngineWithSegments(opts);
 
-  const args = ["transcribe", audioPath, "--json"];
-  if (opts.vad === "on") args.push("--vad");
-  else if (opts.vad === "off") args.push("--no-vad");
-  if (opts.speakers) {
-    args.push("--speakers");
-  }
+  const args = ["transcribe", audioPath, "--json", ...vadArg(opts.vad)];
+  if (opts.speakers) args.push("--speakers");
   const { stdout, stderr, exitCode } = await runEngine(args, { signal: opts.signal });
   if (exitCode !== 0) {
     throw new Error(stderr || `kesha-engine exited with code ${exitCode}`);

package/src/install-hint.ts

@@ -0,0 +1,12 @@
+// Pick the right setup-command hint for error/warning messages. Humans on an
+// interactive TTY get `kesha init` (guided + idempotent), agents and scripts
+// piping stderr get `kesha install [...flags]` (deterministic + scriptable).
+//
+// Flags forward to BOTH paths. `kesha init` accepts the same module-selection
+// flags as `kesha install` (`--tts`, `--vad`, `--diarize`, `--coreml`, `--onnx`,
+// `--no-cache`) — they preselect modules in the interactive wizard rather than
+// being install-only flags. Source of truth: `src/cli/init.ts::initCommand.args`.
+export function installHint(...flags: string[]): string {
+  const verb = process.stderr.isTTY ? "kesha init" : "kesha install";
+  return [verb, ...flags].join(" ");
+}

package/src/status.ts

@@ -1,6 +1,7 @@
 import { readdirSync, statSync } from "fs";
 import { join } from "path";
 import { isEngineInstalled, getEngineBinPath, getEngineCapabilities } from "./engine";
+import { installHint } from "./install-hint";
 import { log } from "./log";
 import { keshaCacheDir } from "./paths";
 import { fluidKokoroCacheInfo } from "./fluid-kokoro-cache";
@@ -82,7 +83,7 @@ export async function showStatus(options: ShowStatusOptions = {}): Promise<void>
   }
 
   if (!installed) {
-    log.warn('Run "kesha install" to download the engine and models.');
+    log.warn(`Run \`${installHint()}\` to download the engine and models.`);
     return;
   }
 }

package/src/synth.ts

@@ -5,6 +5,7 @@ import {
   spawnStdioWithDebugFd,
   type EngineCapabilities,
 } from "./engine";
+import { installHint } from "./install-hint";
 import { log } from "./log";
 import { registerProcessTree } from "./process-tree";
 
@@ -13,8 +14,10 @@ import { registerProcessTree } from "./process-tree";
  * - `wav` (default): RIFF WAV at the engine's native sample rate.
  * - `ogg-opus`: OGG-encapsulated Opus, mono. The format Telegram, WhatsApp,
  *   Signal, and Discord render as native voice messages. See #223.
+ * - `flac`: lossless, royalty-free, plays in every modern browser including
+ *   Safari/iOS. Keeps the engine's native rate; no bitrate knob.
  */
-export type SayFormat = "wav" | "ogg-opus";
+export type SayFormat = "wav" | "ogg-opus" | "flac";
 export const MAX_TEXT_CHARS = 5000;
 
 export interface SayOptions {
@@ -116,7 +119,7 @@ export async function say(opts: SayOptions): Promise<Uint8Array> {
 
   if (!isEngineInstalled()) {
     throw new SayError(
-      "kesha-engine not installed. run: kesha install",
+      `kesha-engine not installed. run: ${installHint("--tts")}`,
       1,
       "",
     );

package/src/transcribe.ts

@@ -6,6 +6,7 @@ import {
   type TranscriptionOutput,
   type VadMode,
 } from "./engine";
+import { installHint } from "./install-hint";
 
 export type { VadMode };
 export type { TranscriptionOutput };
@@ -31,13 +32,10 @@ export async function transcribe(audioPath: string, opts: TranscribeOptions = {}
 export async function preflightTranscribeWithSegments(opts: TranscribeOptions = {}): Promise<void> {
   if (!isEngineInstalled()) {
     throw new Error(
-      "Error: No transcription backend is installed\n\n" +
-      "╔══════════════════════════════════════════════════════════╗\n" +
-      "║ Please run the following commands to get started:        ║\n" +
-      "║                                                          ║\n" +
-      "║     bun add -g @drakulavich/kesha-voice-kit              ║\n" +
-      "║     kesha install                                        ║\n" +
-      "╚══════════════════════════════════════════════════════════╝",
+      "Error: No transcription backend is installed.\n\n" +
+      "Run the following to get started:\n\n" +
+      "    bun add -g @drakulavich/kesha-voice-kit\n" +
+      `    ${installHint()}`,
     );
   }