@drakulavich/kesha-voice-kit 1.0.9 → 1.1.3

package/README.md

@@ -13,14 +13,18 @@
 
 <p align="center"><b>Open-source voice toolkit.</b> Optimized for Apple Silicon (CoreML), works on any platform (ONNX fallback).<br>A collection of small, fast, open-source audio models — packaged as CLI tools and an <a href="https://github.com/openclaw/openclaw">OpenClaw</a> skill for LLM agents.</p>
 
-- **Speech-to-text** — 25 languages, ~19x faster than Whisper on Apple Silicon, ~2.5x on CPU
+- **Speech-to-text** — 25 languages, ~15x faster than Whisper on Apple Silicon, ~2.5x on CPU
 - **Language detection** — 107 languages from audio, text language via NLLanguageRecognizer
 - **Rust engine** — single 20MB binary, no ffmpeg, no Python, no native Node addons
 - **OpenClaw-ready** — plug into your LLM agent as a voice processing skill
 
 ## Quick Start
 
+Runtime: **[Bun](https://bun.sh)** >= 1.3.0.
+
 ```bash
+curl -fsSL https://bun.sh/install | bash   # skip if Bun is already installed
+
 bun install -g @drakulavich/kesha-voice-kit
 kesha install       # downloads engine + models
 kesha audio.ogg     # transcript to stdout
@@ -30,46 +34,70 @@ kesha audio.ogg     # transcript to stdout
 
 Kesha Voice Kit ships as a plugin for [OpenClaw](https://github.com/openclaw/openclaw) — give your LLM agent ears. No API keys, everything runs locally on your machine.
 
-**Install the `kesha` CLI first** (the plugin shells out to it):
-
 ```bash
-bun add -g @drakulavich/kesha-voice-kit
-kesha install
+bun add -g @drakulavich/kesha-voice-kit && kesha install
+openclaw plugins install @drakulavich/kesha-voice-kit
+openclaw config set tools.media.audio.models \
+  '[{"type":"cli","command":"kesha","args":["--format","transcript","{{MediaPath}}"],"timeoutSeconds":15}]'
 ```
 
-**Then register the OpenClaw plugin:**
+> If audio transcription is not already enabled: `openclaw config set tools.media.audio.enabled true`
+
+Your agent receives a voice message in Telegram/WhatsApp/Slack, Kesha transcribes it locally, and the agent sees enriched context:
 
-```bash
-openclaw plugins install @drakulavich/kesha-voice-kit
+```
+Таити, Таити! Не были мы ни в какой Таити! Нас и тут неплохо кормят.
+[lang: ru, confidence: 1.00]
 ```
 
-OpenClaw will auto-detect [`openclaw.plugin.json`](./openclaw.plugin.json) and load [`openclaw-plugin.cjs`](./openclaw-plugin.cjs), which registers `kesha-voice-kit` as a media-understanding provider with `autoPriority.audio = 50`. Once you enable audio transcription (`tools.media.audio.enabled: true`) in your OpenClaw config, Kesha becomes the default provider — higher priority than cloud providers like Groq (20).
+Manage the plugin with `openclaw plugins list`, `openclaw plugins disable kesha-voice-kit`, or `openclaw plugins uninstall kesha-voice-kit`.
 
-Manage the plugin afterwards with `openclaw plugins list`, `openclaw plugins disable kesha-voice-kit`, or `openclaw plugins uninstall kesha-voice-kit`.
+## CLI Tools
 
-Your agent receives a voice message in Telegram/WhatsApp/Slack, Kesha transcribes it locally, and the transcript flows back into the agent loop:
+```bash
+kesha install                              # download engine and models
+kesha audio.ogg                            # transcribe (plain text)
+kesha --format transcript audio.ogg        # text + language/confidence
+kesha --format json audio.ogg              # full JSON with lang fields
+kesha --json audio.ogg                     # alias for --format json
+kesha --verbose audio.ogg                  # show language detection details
+kesha --lang en audio.ogg                  # warn if detected language differs
+kesha status                               # show installed backend info
+```
+
+Multiple files — headers per file, like `head`:
+
+```bash
+$ kesha freedom.ogg tahiti.ogg
+=== freedom.ogg ===
+Свободу попугаям! Свободу!
 
-```json
-{
-  "text": "Привет, как дела?",
-  "model": "parakeet-tdt-0.6b-v3"
-}
+=== tahiti.ogg ===
+Таити, Таити! Не были мы ни в какой Таити! Нас и тут неплохо кормят.
 ```
 
-## CLI Tools
+Stdout: transcript. Stderr: errors. Pipe-friendly. Also available as `parakeet` command (backward-compatible alias).
+
+## Text-to-Speech
+
+Kesha speaks back via Kokoro-82M (English) and Piper (Russian). Voice is auto-picked from the input text's language — `en` routes to Kokoro, `ru` to Piper. Pass `--voice` to override.
 
 ```bash
-kesha install                    # download engine and models
-kesha audio.ogg                  # transcribe
-kesha --json audio.ogg           # JSON output with language info
-kesha --verbose audio.ogg        # show language detection details
-kesha --lang en audio.ogg        # warn if detected language differs
-kesha status                     # show installed backend info
+brew install espeak-ng              # one-time system dep (macOS — apt/choco elsewhere)
+kesha install --tts                 # ~390MB (Kokoro + Piper RU, opt-in)
+kesha say "Hello, world" > hello.wav
+kesha say "Привет, мир" > privet.wav    # auto-routes to ru-denis
+echo "long text" | kesha say > reply.wav
+kesha say --out reply.wav "text"
+kesha say --voice en-af_heart "text"    # explicit voice overrides auto-routing
+kesha say --list-voices
 ```
 
-Stdout: transcript. Stderr: errors. Pipe-friendly.
+Output format: WAV mono float32 (24 kHz for Kokoro, 22.05 kHz for Piper). OGG/Opus, MP3, and SSML are tracked in follow-up issues ([#122](https://github.com/drakulavich/kesha-voice-kit/issues/122)). Static-linking of `espeak-ng` to remove the system dep is [#124](https://github.com/drakulavich/kesha-voice-kit/issues/124).
 
-**Also available as `parakeet` command** (backward-compatible alias).
+**Supported voices:**
+- English: `en-af_heart` (default), plus any Kokoro voice you download into `~/.cache/kesha/models/kokoro-82m/voices/`
+- Russian: `ru-denis` (default). More speakers (dmitri, irina, ruslan) are ready to drop in once needed.
 
 ## What's Inside
 
@@ -85,7 +113,7 @@ All models run through `kesha-engine` — a Rust binary using [FluidAudio](https
 
 ## Performance
 
-> **~19x faster than Whisper** on Apple Silicon, **~2.5x faster** on CPU
+> **~15x faster than Whisper** on Apple Silicon (M3 Pro), **~2.5x faster** on CPU
 
 Compared against Whisper `large-v3-turbo` — all engines auto-detect language.
 
@@ -146,4 +174,4 @@ See [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## License
 
-Made with 💛🩵 Published under MIT License.
+Made with 💛🩵 and 🥤 energy under MIT License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/kesha-voice-kit",
-  "version": "1.0.9",
+  "version": "1.1.3",
   "description": "Open-source voice toolkit for Apple Silicon. Speech-to-text, language detection. 25 languages.",
   "type": "module",
   "bin": {
@@ -29,7 +29,7 @@
     ]
   },
   "keshaEngine": {
-    "version": "1.0.2"
+    "version": "1.1.3"
   },
   "scripts": {
     "test": "bun test",

package/src/cli.ts

@@ -7,6 +7,7 @@ import { downloadEngine } from "./engine-install";
 import { detectAudioLanguageEngine, detectTextLanguageEngine } from "./engine";
 import type { LangDetectResult } from "./engine";
 import { log } from "./log";
+import { say, SayError } from "./say";
 import { showStatus } from "./status";
 import { suggestCommand } from "./suggest-command";
 
@@ -24,6 +25,7 @@ interface InstallCommandArgs {
   coreml: boolean;
   onnx: boolean;
   "no-cache": boolean;
+  tts: boolean;
 }
 
 interface MainCommandArgs {
@@ -46,9 +48,26 @@ function resolveBackendFlag(coreml: boolean, onnx: boolean): string | undefined
   return undefined;
 }
 
-async function performInstall(noCache: boolean, backend?: string) {
+async function askForStar() {
+  const gh = Bun.which("gh");
+  if (!gh) {
+    log.info("\nIf you enjoy Kesha Voice Kit, consider starring the repo:");
+    log.info("  https://github.com/drakulavich/kesha-voice-kit");
+    return;
+  }
+  const authCheck = Bun.spawnSync([gh, "auth", "status"], { stdout: "ignore", stderr: "ignore" });
+  if (authCheck.exitCode !== 0) return;
+  const starred = Bun.spawnSync([gh, "api", "user/starred/drakulavich/kesha-voice-kit"], { stdout: "ignore", stderr: "ignore" });
+  if (starred.exitCode === 0) return; // already starred
+  log.info("\n⭐ If you enjoy Kesha Voice Kit, star it on GitHub:");
+  log.info("  https://github.com/drakulavich/kesha-voice-kit");
+  log.info('  Or run: gh api -X PUT /user/starred/drakulavich/kesha-voice-kit');
+}
+
+async function performInstall(noCache: boolean, backend?: string, tts = false) {
   try {
-    await downloadEngine(noCache, backend);
+    await downloadEngine(noCache, backend, { tts });
+    await askForStar();
   } catch (err: unknown) {
     const message = err instanceof Error ? err.message : String(err);
     log.error(message);
@@ -77,13 +96,112 @@ export const installCommand = defineCommand({
       description: "Re-download even if cached",
       default: false,
     },
+    tts: {
+      type: "boolean",
+      description: "Also install TTS models (Kokoro EN + Piper RU, ~390MB, requires espeak-ng on PATH)",
+      default: false,
+    },
   },
   async run({ args }: { args: InstallCommandArgs }) {
     const backend = resolveBackendFlag(args.coreml, args.onnx);
-    await performInstall(args["no-cache"], backend);
+    await performInstall(args["no-cache"], backend, args.tts);
   },
 });
 
+export const sayCommand = defineCommand({
+  meta: {
+    name: "say",
+    description: "Synthesize speech from text (TTS). Writes WAV to stdout (or --out file).",
+  },
+  args: {
+    text: { type: "positional", required: false, description: "Text to speak (stdin if omitted)" },
+    voice: { type: "string", description: "Voice id, e.g. en-af_heart" },
+    lang: { type: "string", description: "espeak language code (default en-us)" },
+    out: { type: "string", description: "Write WAV 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" },
+  },
+  async run({ args }) {
+    if (args["list-voices"]) {
+      // The engine prints the list directly — just relay its stdout + exit code.
+      const { getEngineBinPath } = await import("./engine");
+      const proc = Bun.spawn([getEngineBinPath(), "say", "--list-voices"], {
+        stdout: "inherit",
+        stderr: "inherit",
+      });
+      process.exit(await proc.exited);
+    }
+
+    const inlineText = typeof args.text === "string" ? args.text : undefined;
+    const text = await resolveText(inlineText);
+    const explicitVoice = typeof args.voice === "string" ? args.voice : undefined;
+    const voice = explicitVoice ?? (await autoRouteVoice(text));
+
+    const opts = {
+      text,
+      voice,
+      lang: typeof args.lang === "string" ? args.lang : undefined,
+      out: typeof args.out === "string" ? args.out : undefined,
+      rate: args.rate ? Number(args.rate) : undefined,
+    };
+
+    try {
+      const wav = await say(opts);
+      if (!opts.out) {
+        process.stdout.write(wav);
+      }
+    } catch (err) {
+      if (err instanceof SayError) {
+        log.error(err.stderr.trim() || err.message);
+        process.exit(err.exitCode);
+      }
+      const message = err instanceof Error ? err.message : String(err);
+      log.error(message);
+      process.exit(4);
+    }
+  },
+});
+
+/** Resolve the text to synthesize: inline positional, else read from stdin. */
+async function resolveText(inline: string | undefined): Promise<string> {
+  if (inline !== undefined && inline.length > 0) return inline;
+  const chunks: Uint8Array[] = [];
+  for await (const chunk of Bun.stdin.stream()) {
+    chunks.push(chunk);
+  }
+  const total = chunks.reduce((n, c) => n + c.byteLength, 0);
+  const merged = new Uint8Array(total);
+  let offset = 0;
+  for (const c of chunks) {
+    merged.set(c, offset);
+    offset += c.byteLength;
+  }
+  return new TextDecoder().decode(merged).trim();
+}
+
+/** Map a detected language code to a default voice id. Unknown / low-confidence → undefined. */
+export function pickVoiceForLang(
+  code: string | undefined,
+  confidence: number,
+): string | undefined {
+  if (!code || confidence < 0.5) return undefined;
+  switch (code) {
+    case "en":
+      return "en-af_heart";
+    case "ru":
+      return "ru-denis";
+    default:
+      return undefined;
+  }
+}
+
+/** Run NLLanguageRecognizer (via engine) on the text and pick a default voice. */
+async function autoRouteVoice(text: string): Promise<string | undefined> {
+  if (!text) return undefined;
+  const detected = await detectTextLanguageEngine(text);
+  return pickVoiceForLang(detected?.code, detected?.confidence ?? 0);
+}
+
 export const statusCommand = defineCommand({
   meta: {
     name: "status",
@@ -197,7 +315,7 @@ export const mainCommand = defineCommand({
   },
 });
 
-const SUBCOMMANDS = ["install", "status"];
+const SUBCOMMANDS = ["install", "status", "say"];
 
 export async function runCli(rawArgs = process.argv.slice(2)): Promise<void> {
   const [firstArg, ...restArgs] = rawArgs;
@@ -212,6 +330,11 @@ export async function runCli(rawArgs = process.argv.slice(2)): Promise<void> {
     return;
   }
 
+  if (firstArg === "say") {
+    await runMain(sayCommand, { rawArgs: restArgs });
+    return;
+  }
+
   // Check for unknown subcommands (non-flag, non-file-path args)
   if (firstArg && !firstArg.startsWith("-") && !firstArg.includes(".") && !firstArg.includes("/")) {
     const suggestion = suggestCommand(firstArg, SUBCOMMANDS);

package/src/engine-install.ts

@@ -17,7 +17,16 @@ function getEngineBinaryName(): string {
   throw new Error(`Unsupported platform: ${platform} ${arch}`);
 }
 
-export async function downloadEngine(noCache = false, backend?: string): Promise<string> {
+export interface InstallOptions {
+  /** Also install Kokoro TTS models. Requires espeak-ng on PATH. */
+  tts?: boolean;
+}
+
+export async function downloadEngine(
+  noCache = false,
+  backend?: string,
+  options: InstallOptions = {},
+): Promise<string> {
   const binPath = getEngineBinPath();
 
   if (!noCache && existsSync(binPath)) {
@@ -68,7 +77,11 @@ export async function downloadEngine(noCache = false, backend?: string): Promise
   }
 
   log.progress("Installing models...");
-  const installArgs = ["install", ...(noCache ? ["--no-cache"] : [])];
+  const installArgs = [
+    "install",
+    ...(noCache ? ["--no-cache"] : []),
+    ...(options.tts ? ["--tts"] : []),
+  ];
   const proc = Bun.spawnSync([binPath, ...installArgs], {
     stdout: "pipe",
     stderr: "pipe",

package/src/engine.ts

@@ -7,10 +7,15 @@ export interface LangDetectResult {
   confidence: number;
 }
 
-const ENGINE_BIN_PATH = join(homedir(), ".cache", "kesha", "engine", "bin", "kesha-engine");
+const DEFAULT_ENGINE_BIN_PATH = join(homedir(), ".cache", "kesha", "engine", "bin", "kesha-engine");
 
+/**
+ * Path to the `kesha-engine` binary. Defaults to the install location under
+ * `~/.cache/kesha/engine/bin/`. The `KESHA_ENGINE_BIN` env var overrides — useful
+ * for running against a freshly-built engine during development or in e2e tests.
+ */
 export function getEngineBinPath(): string {
-  return ENGINE_BIN_PATH;
+  return process.env.KESHA_ENGINE_BIN ?? DEFAULT_ENGINE_BIN_PATH;
 }
 
 export function isEngineInstalled(): boolean {

package/src/lib.ts

@@ -4,6 +4,12 @@ import { downloadEngine } from "./engine-install";
 
 export type { TranscribeOptions };
 export { downloadEngine as downloadModel };
+export { say, type SayOptions, SayError } from "./say";
+
+/** Install Kokoro TTS models. Shorthand for `downloadModel({ tts: true })`. */
+export async function downloadTts(noCache = false): Promise<void> {
+  await downloadEngine(noCache, undefined, { tts: true });
+}
 
 /** @deprecated Use `downloadModel` instead. */
 export const downloadCoreML = downloadEngine;

package/src/say.ts

@@ -0,0 +1,82 @@
+import { getEngineBinPath, isEngineInstalled } from "./engine";
+
+export interface SayOptions {
+  /**
+   * Text to synthesize. Required for programmatic callers — `say()` does not
+   * forward the host process's stdin. The CLI (`kesha say` with no positional
+   * arg) handles stdin separately before invoking `say()`.
+   */
+  text?: string;
+  /** Voice id, e.g. `en-af_heart`. Defaults to engine default. */
+  voice?: string;
+  /** Override the voice's default espeak language code. */
+  lang?: string;
+  /** Write audio to this path instead of returning bytes. */
+  out?: string;
+  /** Speaking rate 0.5–2.0. */
+  rate?: number;
+}
+
+/** Build the argv passed to `kesha-engine say` (pure, unit-testable). */
+export function buildSayArgs(o: SayOptions): string[] {
+  const args: string[] = ["say"];
+  if (o.voice) args.push("--voice", o.voice);
+  if (o.lang) args.push("--lang", o.lang);
+  if (o.out) args.push("--out", o.out);
+  if (o.rate !== undefined && o.rate !== 1.0) args.push("--rate", String(o.rate));
+  if (o.text !== undefined && o.text.length > 0) args.push(o.text);
+  return args;
+}
+
+export class SayError extends Error {
+  constructor(
+    message: string,
+    public readonly exitCode: number,
+    public readonly stderr: string,
+  ) {
+    super(message);
+    this.name = "SayError";
+  }
+}
+
+/**
+ * Synthesize speech. Returns raw WAV bytes. If `out` is provided in options,
+ * the engine writes to the file and this function returns an empty buffer.
+ */
+export async function say(opts: SayOptions): Promise<Uint8Array> {
+  if (!isEngineInstalled()) {
+    throw new SayError(
+      "kesha-engine not installed. run: kesha install",
+      1,
+      "",
+    );
+  }
+  const args = buildSayArgs({ ...opts, text: undefined });
+  const proc = Bun.spawn([getEngineBinPath(), ...args], {
+    stdin: "pipe",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  if (opts.text !== undefined && opts.text.length > 0) {
+    proc.stdin.write(opts.text);
+    await proc.stdin.end();
+  } else {
+    await proc.stdin.end();
+  }
+
+  const [stdoutBuf, stderrText, exitCode] = await Promise.all([
+    new Response(proc.stdout).arrayBuffer(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+
+  if (exitCode !== 0) {
+    throw new SayError(
+      stderrText.trim() || `kesha-engine say exited ${exitCode}`,
+      exitCode,
+      stderrText,
+    );
+  }
+  return new Uint8Array(stdoutBuf);
+}

package/src/status.ts

@@ -1,3 +1,6 @@
+import { readdirSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
 import { isEngineInstalled, getEngineBinPath, getEngineCapabilities } from "./engine";
 import { log } from "./log";
 import pc from "picocolors";
@@ -37,7 +40,48 @@ export async function showStatus(): Promise<void> {
   log.info(formatStatusLine("Platform", `${process.platform} ${process.arch}`, true));
   log.info("");
 
+  if (installed) {
+    const voices = listInstalledVoices();
+    if (voices.length > 0) {
+      log.info("TTS voices:");
+      for (const v of voices) {
+        log.info(`  ${v}`);
+      }
+      log.info("");
+    }
+  }
+
   if (!installed) {
     log.warn('Run "kesha install" to download the engine and models.');
   }
 }
+
+function kesheCacheDir(): string {
+  return process.env.KESHA_CACHE_DIR ?? join(homedir(), ".cache", "kesha");
+}
+
+function listInstalledVoices(): string[] {
+  const cache = kesheCacheDir();
+  const voices: string[] = [];
+  try {
+    const kokoro = readdirSync(join(cache, "models", "kokoro-82m", "voices"));
+    for (const f of kokoro) {
+      if (f.endsWith(".bin")) voices.push(`en-${f.replace(/\.bin$/, "")}`);
+    }
+  } catch {
+    /* Kokoro not installed */
+  }
+  try {
+    // Piper RU files follow `ru_RU-<name>-<quality>.onnx` — report just `<name>`.
+    const piper = readdirSync(join(cache, "models", "piper-ru"));
+    for (const f of piper) {
+      if (!f.endsWith(".onnx")) continue;
+      const stem = f.replace(/\.onnx$/, "");
+      const name = stem.replace(/^ru_RU-/, "").split("-")[0];
+      if (name) voices.push(`ru-${name}`);
+    }
+  } catch {
+    /* Piper not installed */
+  }
+  return voices.sort();
+}