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

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
@@ -188,12 +192,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 +224,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/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.19.0" "User Commands"
 .SH NAME
 kesha \- open-source local voice toolkit
 .SH SYNOPSIS

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/kesha-voice-kit",
-  "version": "1.19.0-beta.2",
+  "version": "1.19.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.19.0"
   },
   "scripts": {
     "test": "bun test",

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/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";
 
@@ -116,7 +117,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()}`,
     );
   }