@drakulavich/kesha-voice-kit 1.12.0 → 1.14.0

package/README.md

@@ -25,13 +25,53 @@ 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
+bun add -g @drakulavich/kesha-voice-kit
 kesha install       # downloads engine + models
 kesha audio.ogg     # transcript to stdout
 ```
 
 Air-gapped or behind a corporate mirror? See [docs/model-mirror.md](docs/model-mirror.md).
 
+## Nix Install (Recommended)
+
+**Prerequisites:** [Nix](https://nixos.org/download/) with flakes enabled. Supported systems: `aarch64-darwin`, `x86_64-linux`.
+
+### One-liner run (no install)
+```bash
+nix run github:drakulavich/kesha-voice-kit -- install      # downloads models (engine is bundled)
+nix run github:drakulavich/kesha-voice-kit -- audio.ogg    # transcribe
+```
+
+`nix run` resolves to `apps.default` (the `kesha` Bun CLI), which has the engine binary baked in via `KESHA_ENGINE_BIN`, so there's no separate engine download.
+
+### Install to profile (persistent)
+```bash
+nix profile install github:drakulavich/kesha-voice-kit
+kesha install       # downloads models
+kesha audio.ogg     # transcript to stdout
+```
+
+`packages.default` ships the Bun CLI (`kesha`, `parakeet`) wired to the Nix-built engine. After `nix profile install`, both shims are on `PATH` and run transcription, language detection, and TTS (including `macos-*` AVSpeech voices on darwin-arm64) identically to the npm install. Speaker diarization (`kesha install --diarize` / `--speakers`) is not yet wired into the Nix build — the `kesha-diarize` Swift sidecar needs network-fetched FluidAudio at build time, which the Nix sandbox forbids; use the Bun install path (`bun add -g @drakulavich/kesha-voice-kit`) on darwin-arm64 if you need that feature (tracked alongside [#199](https://github.com/drakulavich/kesha-voice-kit/issues/199)).
+
+### Engine only (no Bun, no Node)
+For users who just want the Rust binary:
+```bash
+nix build github:drakulavich/kesha-voice-kit#kesha-engine
+./result/bin/kesha-engine --help
+./result/bin/kesha-engine --capabilities-json   # see which backends compiled in
+```
+
+### Development shell
+```bash
+nix develop github:drakulavich/kesha-voice-kit
+# Now you have: pinned rustc/cargo (via rust-overlay), bun, protoc, cmake, pkg-config, libclang
+```
+
+**Why Nix?**
+- ✅ Reproducible builds across Linux/macOS
+- ✅ All native deps (onnxruntime, protobuf, abseil) handled automatically
+- ✅ No "works on my machine" — same `flake.nix` = identical results everywhere
+
 ## Speech-to-text
 
 ```bash
@@ -98,6 +138,18 @@ kesha say --voice ru-vosk-m02 --ssml \
 
 Vosk-TTS 0.9-multi honors a `+` placed BEFORE the target stressed vowel — but only when the marker shifts stress AWAY from the model's default (first-syllable). `+` agreeing with the default is a no-op. See [#233](https://github.com/drakulavich/kesha-voice-kit/issues/233).
 
+**Speech rate via SSML** (`ru-vosk-*` and `en-*` voices):
+
+```bash
+kesha say --voice ru-vosk-m02 --ssml \
+  '<speak><prosody rate="slow">Привет, как дела.</prosody></speak>' --out slow.wav
+
+kesha say --voice en-am_michael --ssml \
+  '<speak><prosody rate="x-fast">Read this fast.</prosody></speak>' --out fast.wav
+```
+
+Honored when `<prosody rate>` wraps the whole utterance. Mid-utterance prosody warns and synthesizes at default rate (whole-segment-only is a v1 limitation; mid-utterance support tracked in [#236](https://github.com/drakulavich/kesha-voice-kit/issues/236)). `--rate` and `<prosody rate>` compose multiplicatively. Range clamped to 0.5×–2.0×.
+
 macOS system voices, SSML, voice listing, and the full voice catalogue: [docs/tts.md](docs/tts.md).
 
 ## Performance

package/SKILL.md

@@ -100,6 +100,8 @@ Format is also inferred from `--out` extension (`.ogg` / `.opus` / `.oga` → OG
 
 **Russian word stress** (`ru-vosk-*` only): `<emphasis>сл+ово</emphasis>` shifts stress to the vowel marked with `+`. `<emphasis level="none">сл+ово</emphasis>` strips the `+` (cancel inherited emphasis). Other voices (`en-*`, `macos-*`) silently strip the `+` and warn once per process. Auto-stress dictionary not provided — caller writes the `+` manually. Closes [#233](https://github.com/drakulavich/kesha-voice-kit/issues/233).
 
+**Speech rate via SSML** (`ru-vosk-*` and `en-*` voices): wrap the utterance in `<prosody rate="…">` to slow down or speed up synthesis. Supports SSML named values (`x-slow`/`slow`/`medium`/`fast`/`x-fast`), absolute `N%` (e.g. `120%`), and relative `+N%`/`-N%`. Honored only when `<prosody>` wraps the whole utterance — mid-utterance prosody warns and synthesizes at default rate. `--rate` and `<prosody rate>` compose multiplicatively; result is clamped to 0.5×–2.0×. AVSpeech (`macos-*` voices) does not yet accept SSML — see [#236](https://github.com/drakulavich/kesha-voice-kit/issues/236).
+
 ## Language detection standalone
 
 `kesha --json audio.ogg` includes both audio-based (`audioLanguage`) and text-based (`textLanguage`) detection. Use audio detection to identify the language before running language-specific logic.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/kesha-voice-kit",
-  "version": "1.12.0",
+  "version": "1.14.0",
   "description": "Open-source voice toolkit. Speech-to-text (25 langs, ~19x faster than Whisper on Apple Silicon, ONNX fallback on CPU), text-to-speech (Kokoro + Vosk-TTS + ~180 macOS system voices, SSML), voice-activity detection, language detection (107 langs). Rust engine, OpenClaw skill.",
   "type": "module",
   "bin": {
@@ -30,7 +30,7 @@
     ]
   },
   "keshaEngine": {
-    "version": "1.12.0"
+    "version": "1.14.0"
   },
   "scripts": {
     "test": "bun test",

package/src/cli/say.ts

@@ -1,31 +1,8 @@
 import { defineCommand } from "citty";
 import { detectTextLanguageEngine, getEngineBinPath } from "../engine";
 import { log } from "../log";
-import { say, SayError, type SayFormat } from "../say";
-
-/**
- * Darwin defaults to AVSpeech Milena — zero install, no model download required.
- * Linux/Windows fall through to Vosk-TTS `ru-vosk-m02` (male, per CLAUDE.md
- * "DEFAULT TTS VOICES MUST BE MALE"; replaces Piper-ruslan as of #213).
- */
-const RU_DARWIN_FALLBACK_VOICE = "macos-com.apple.voice.compact.ru-RU.Milena";
-
-/** Map a detected language code to a default voice id. Unknown / low-confidence → undefined. */
-export function pickVoiceForLang(
-  code: string | undefined,
-  confidence: number,
-  platform: NodeJS.Platform = process.platform,
-): string | undefined {
-  if (!code || confidence < 0.5) return undefined;
-  switch (code) {
-    case "en":
-      return "en-am_michael";
-    case "ru":
-      return platform === "darwin" ? RU_DARWIN_FALLBACK_VOICE : "ru-vosk-m02";
-    default:
-      return undefined;
-  }
-}
+import { say, SayError, type SayFormat } from "../synth";
+import { pickVoiceForLang } from "../voice-routing";
 
 /** Run NLLanguageRecognizer (via engine) on the text and pick a default voice. */
 async function autoRouteVoice(text: string): Promise<string | undefined> {

package/src/cli.ts

@@ -4,7 +4,8 @@
 // tests and lib.ts keep importing from "./cli" via these re-exports so the
 // public surface is unchanged.
 export { installCommand } from "./cli/install";
-export { sayCommand, pickVoiceForLang } from "./cli/say";
+export { sayCommand } from "./cli/say";
+export { pickVoiceForLang } from "./voice-routing";
 export { statusCommand } from "./cli/status";
 export { mainCommand, detectLanguage, checkLanguageMismatch } from "./cli/main";
 export { runCli } from "./cli/dispatch";

package/src/engine-install.ts

@@ -1,6 +1,10 @@
 import { dirname, join } from "path";
-import { existsSync, mkdirSync, chmodSync } from "fs";
-import { getEngineBinPath, getEngineCapabilities } from "./engine";
+import { existsSync, mkdirSync, chmodSync, accessSync, constants } from "fs";
+import {
+  getEngineBinPath,
+  getEngineCapabilities,
+  TRANSCRIBE_DIARIZE_FEATURE,
+} from "./engine";
 import { log } from "./log";
 import { streamResponseToFile } from "./progress";
 import {
@@ -151,19 +155,56 @@ export async function downloadEngine(
         : "unknown";
 
   const installedVersion = readInstalledEngineVersion(binPath);
-  const cacheValid =
-    !noCache && existsSync(binPath) && installedVersion === engineVersion;
+  const engineDir = dirname(binPath);
+
+  // Detect a read-only engine directory (e.g., a Nix-store install —
+  // `KESHA_ENGINE_BIN` points into `/nix/store/.../bin/`). Used twice
+  // below: to honor `--no-cache` only when the engine is writable, and
+  // to skip the sidecar top-up that would otherwise emit confusing
+  // "install failed" warnings for paths we physically can't write to.
+  let canWriteEngineDir = true;
+  if (existsSync(engineDir)) {
+    try {
+      accessSync(engineDir, constants.W_OK);
+    } catch {
+      canWriteEngineDir = false;
+    }
+  }
+
+  const versionMatches =
+    existsSync(binPath) && installedVersion === engineVersion;
+  // When the engine sits on a read-only filesystem at the matching
+  // version, `--no-cache` can't re-download it without an EROFS crash
+  // and there's nothing to refresh anyway — treat as cache-valid and
+  // forward `--no-cache` to the model install step below.
+  const cacheValid = versionMatches && (!noCache || !canWriteEngineDir);
 
   if (cacheValid) {
-    log.success(`Engine binary already installed (v${engineVersion}).`);
+    if (noCache && !canWriteEngineDir) {
+      log.info(
+        `Engine binary at v${engineVersion} is on a read-only filesystem; --no-cache skipped for engine (still forwarded to model installs).`,
+      );
+    } else {
+      log.success(`Engine binary already installed (v${engineVersion}).`);
+    }
     // Top up any sidecars missing from this cached install. Pre-#141 / pre-#199
     // engines never shipped them, so a cache-valid binary may still need
     // fetching. Run independent fetches concurrently — same shape as the
     // cold path below.
-    const missing = SIDECARS.filter(
-      (s) => !existsSync(join(dirname(binPath), s.fileBasename)),
-    );
-    await Promise.all(missing.map((s) => downloadSidecar(s, binPath, engineVersion)));
+    //
+    // Skip the top-up entirely when the engine sits in a read-only
+    // filesystem (e.g., a Nix-store install). Those installs stage the
+    // supported sidecars at build time; writing more is impossible, and
+    // attempting it would emit a confusing "install failed" warning for
+    // a feature the Nix README explicitly documents as unsupported
+    // (diarize on Nix needs network access at build time, which the
+    // sandbox forbids).
+    if (canWriteEngineDir) {
+      const missing = SIDECARS.filter(
+        (s) => !existsSync(join(engineDir, s.fileBasename)),
+      );
+      await Promise.all(missing.map((s) => downloadSidecar(s, binPath, engineVersion)));
+    }
   } else {
     // Log why we're downloading — helps diagnose surprising re-downloads.
     if (existsSync(binPath) && installedVersion && installedVersion !== engineVersion) {
@@ -225,6 +266,29 @@ export async function downloadEngine(
     }
   }
 
+  // Catch the case where the platform check passed (darwin-arm64) but the
+  // engine itself was built without `system_diarize` — e.g., the Nix build,
+  // which compiles `coreml,tts,system_tts` and intentionally omits diarize
+  // because the FluidAudio CoreML weights need network at build time and the
+  // Nix sandbox forbids it. Without this guard, `kesha-engine install
+  // --diarize` would fail with clap's generic "unexpected argument" error.
+  if (options.diarize) {
+    const caps = await getEngineCapabilities();
+    // Treat null (pre-capabilities-JSON engine, or capability probe failed)
+    // the same as an engine that advertised features but omitted ours —
+    // forwarding `--diarize` to a binary that doesn't understand it would
+    // surface as clap's generic "unexpected argument" error.
+    if (!caps || !caps.features.includes(TRANSCRIBE_DIARIZE_FEATURE)) {
+      throw new Error(
+        "--diarize is not supported by the installed engine: it was built " +
+          "without the 'system_diarize' feature (the Nix build is one such " +
+          "case — see README's Nix Install section).\n" +
+          "  Fix: install via the npm release with `bun add -g @drakulavich/kesha-voice-kit`, " +
+          "which ships the diarize-enabled engine on darwin-arm64.",
+      );
+    }
+  }
+
   log.progress("Installing models...");
   const installArgs = [
     "install",

package/src/engine.ts

@@ -66,6 +66,15 @@ async function runEngine(args: string[]): Promise<{ stdout: string; stderr: stri
   ]);
 
   log.debug(`exit=${exitCode} dt=${Math.round(performance.now() - startedAt)}ms args=${JSON.stringify(args)}`);
+
+  // #275 D4: surface engine stderr on the success path so warnings like
+  // `hint: audio is 180s`, `Model mirror active:`, and the dtrace lines
+  // emitted under KESHA_DEBUG=1 reach the user. On non-zero exit we leave
+  // the buffer for callers to fold into a thrown Error — otherwise the
+  // user would see the warning AND a duplicate inside the error message.
+  if (exitCode === 0 && stderr.length > 0) {
+    process.stderr.write(stderr.endsWith("\n") ? stderr : stderr + "\n");
+  }
   return { stdout: stdout.trim(), stderr: stderr.trim(), exitCode };
 }
 

package/src/lib.ts

@@ -9,7 +9,7 @@ import { downloadEngine } from "./engine-install";
 export type { TranscribeOptions };
 export type { TranscriptionOutput, TranscriptionSegment } from "./engine";
 export { downloadEngine as downloadModel };
-export { say, type SayOptions, SayError } from "./say";
+export { say, type SayOptions, SayError } from "./synth";
 
 /**
  * Encode a `TranscribeResult[]` as TOON (#138). Same data shape as the

package/src/log.ts

@@ -4,10 +4,19 @@ import pc from "picocolors";
  * Debug mode (#148): when `KESHA_DEBUG` is truthy OR the caller has flipped
  * `log.debugEnabled = true` (via `--debug`), `log.debug()` writes structured
  * trace lines to stderr. Otherwise it's a no-op. Stdout is never touched.
+ *
+ * Grammar (#275 D9): values that turn debug OFF — empty, `"0"`, `"false"`,
+ * `"no"`, `"off"`, all matched **case-insensitively** after trimming. Any
+ * other non-empty value turns debug ON. The Rust engine mirrors this list
+ * verbatim in `rust/src/debug.rs` so `KESHA_DEBUG=False` flips both sides
+ * the same direction.
  */
+const KESHA_DEBUG_OFF_VALUES = new Set(["", "0", "false", "no", "off"]);
+
 function envDebug(): boolean {
   const v = process.env.KESHA_DEBUG;
-  return !!v && v !== "0" && v.toLowerCase() !== "false";
+  if (v === undefined) return false;
+  return !KESHA_DEBUG_OFF_VALUES.has(v.trim().toLowerCase());
 }
 
 export const log = {

package/src/{say.ts → synth.ts}

@@ -41,8 +41,11 @@ export interface SayOptions {
   /**
    * Disable acronym auto-expansion for `ru-vosk-*` and `en-*` voices.
    * When true, passes `--no-expand-abbrev` to the engine (requires engine
-   * capability `tts.ru_acronym_expansion` or `tts.en_acronym_expansion`; silently dropped for older engines).
-   * `<say-as interpret-as="characters">` still works regardless of this flag.
+   * capability `tts.ru_acronym_expansion` or `tts.en_acronym_expansion`).
+   * On older engines that don't advertise the capability, the flag is
+   * dropped from argv and `log.warn` surfaces the drop on every
+   * invocation (post-#275 D3). `<say-as interpret-as="characters">`
+   * still works regardless of this flag.
    */
   noExpandAbbrev?: boolean;
 }
@@ -65,8 +68,12 @@ export function buildSayArgs(o: SayOptions, capabilities?: EngineCapabilities |
     if (supportsExpand) {
       args.push("--no-expand-abbrev");
     } else {
-      log.debug(
-        "kesha-engine does not advertise tts.ru_acronym_expansion or tts.en_acronym_expansion; dropping --no-expand-abbrev",
+      // CLAUDE.md "NEVER SWALLOW ERRORS": the user explicitly passed the flag.
+      // Silent drop with only `log.debug` made the flag look effective on old
+      // engines (#275 D3). Surface it as a warning so a CI script or human
+      // user sees the mismatch on every invocation, not only with --debug.
+      log.warn(
+        "--no-expand-abbrev requires kesha-engine ≥ 1.10.0 (advertises no tts.ru_acronym_expansion / tts.en_acronym_expansion capability); flag ignored",
       );
     }
   }
@@ -121,6 +128,14 @@ export async function say(opts: SayOptions): Promise<Uint8Array> {
   ]);
 
   log.debug(`exit=${exitCode} dt=${Math.round(performance.now() - startedAt)}ms bytes=${stdoutBuf.byteLength}`);
+
+  // #275 D4: surface engine stderr on the success path so warnings like
+  // `Model mirror active:` and the dtrace lines emitted under
+  // KESHA_DEBUG=1 reach the user. Errors keep their existing path
+  // through `SayError.stderr` so we don't double-print.
+  if (exitCode === 0 && stderrText.length > 0) {
+    process.stderr.write(stderrText.endsWith("\n") ? stderrText : stderrText + "\n");
+  }
   if (exitCode !== 0) {
     throw new SayError(
       stderrText.trim() || `kesha-engine say exited ${exitCode}`,

package/src/voice-routing.ts

@@ -0,0 +1,23 @@
+/**
+ * Darwin defaults to AVSpeech Milena — zero install, no model download required.
+ * Linux/Windows fall through to Vosk-TTS `ru-vosk-m02` (male, per CLAUDE.md
+ * "DEFAULT TTS VOICES MUST BE MALE"; replaces Piper-ruslan as of #213).
+ */
+const RU_DARWIN_FALLBACK_VOICE = "macos-com.apple.voice.compact.ru-RU.Milena";
+
+/** Map a detected language code to a default voice id. Unknown / low-confidence → undefined. */
+export function pickVoiceForLang(
+  code: string | undefined,
+  confidence: number,
+  platform: NodeJS.Platform = process.platform,
+): string | undefined {
+  if (!code || confidence < 0.5) return undefined;
+  switch (code) {
+    case "en":
+      return "en-am_michael";
+    case "ru":
+      return platform === "darwin" ? RU_DARWIN_FALLBACK_VOICE : "ru-vosk-m02";
+    default:
+      return undefined;
+  }
+}