@drakulavich/kesha-voice-kit 1.1.3 → 1.2.1

package/README.md

@@ -93,11 +93,45 @@ kesha say --voice en-af_heart "text"    # explicit voice overrides auto-routing
 kesha say --list-voices
 ```
 
-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).
+Output format: WAV mono float32 (24 kHz for Kokoro, 22.05 kHz for Piper). OGG/Opus and MP3 are tracked in follow-up issues. Static-linking of `espeak-ng` to remove the system dep is [#124](https://github.com/drakulavich/kesha-voice-kit/issues/124).
 
 **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.
+- macOS system voices (preview — dev builds only, see below): `macos-<identifier-or-language>` routes to `AVSpeechSynthesizer`. Zero install, any of the 180+ voices already on your Mac.
+
+### macOS system voices (preview)
+
+`kesha say --voice macos-*` routes through `AVSpeechSynthesizer` on macOS, so you get voice synthesis for free — no 390 MB TTS bundle, no `espeak-ng` dep. Currently gated behind the `system_tts` cargo feature; release-binary integration is tracked as part of [#141](https://github.com/drakulavich/kesha-voice-kit/issues/141).
+
+```bash
+# From a dev build: `cargo build --release --features system_tts` in rust/.
+kesha say --voice macos-com.apple.voice.compact.en-US.Samantha "Hello from system TTS" > out.wav
+kesha say --voice macos-ru-RU "Привет, мир" > hello-ru.wav   # language-code fallback
+```
+
+Voice id format: `macos-<id>` where `<id>` is either a full Apple identifier (`com.apple.voice.compact.en-US.Samantha`) or a language code (`en-US`, `ru-RU`) — the Swift helper tries the identifier first and falls back to the language. Output is mono float32 @ 22050 Hz, structurally identical to Piper.
+
+Quality tradeoff is honest: macOS system voices are notification-grade. Use them when you want zero-install TTS on macOS; keep Kokoro/Piper for anything that needs to sound good.
+
+### SSML (preview)
+
+`kesha say --ssml` accepts [SSML](https://www.w3.org/TR/speech-synthesis11/) for pauses and text-structuring. v1 is deliberately small:
+
+```bash
+kesha say --ssml '<speak>Hello <break time="500ms"/> world.</speak>'
+kesha say --ssml --voice ru-denis '<speak>Привет <break time="1s"/> мир.</speak>'
+```
+
+| Tag | Status |
+|---|---|
+| `<speak>` | ✅ required root |
+| `<break time="Nms"\|"Ns"\|default>` | ✅ inserts silence of the given duration |
+| plain text inside `<speak>` | ✅ synthesized via the selected engine |
+| `<emphasis>`, `<prosody>`, `<phoneme>`, `<say-as>` | ⚠️ stripped with a stderr warning (contained text still synthesized); tracked in [#122](https://github.com/drakulavich/kesha-voice-kit/issues/122) |
+| `<!DOCTYPE>` | ❌ rejected (hardening against XXE) |
+
+SSML is opt-in via the explicit `--ssml` flag — inputs that happen to contain `<angle brackets>` aren't misinterpreted as SSML.
 
 ## What's Inside
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/kesha-voice-kit",
-  "version": "1.1.3",
+  "version": "1.2.1",
   "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.1.3"
+    "version": "1.2.0"
   },
   "scripts": {
     "test": "bun test",

package/src/cli.ts

@@ -32,6 +32,7 @@ interface MainCommandArgs {
   _: string[];
   json: boolean;
   verbose: boolean;
+  debug: boolean;
   format?: string;
   lang?: string;
 }
@@ -120,8 +121,23 @@ export const sayCommand = defineCommand({
     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" },
+    ssml: {
+      type: "boolean",
+      description: "Parse input as SSML (supports <speak>, <break>; strips unknown tags)",
+    },
+    verbose: {
+      type: "boolean",
+      description: "Log TTS synthesis time to stderr",
+      default: false,
+    },
+    debug: {
+      type: "boolean",
+      description: "Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)",
+      default: false,
+    },
   },
   async run({ args }) {
+    if (args.debug) log.debugEnabled = true;
     if (args["list-voices"]) {
       // The engine prints the list directly — just relay its stdout + exit code.
       const { getEngineBinPath } = await import("./engine");
@@ -143,10 +159,17 @@ export const sayCommand = defineCommand({
       lang: typeof args.lang === "string" ? args.lang : undefined,
       out: typeof args.out === "string" ? args.out : undefined,
       rate: args.rate ? Number(args.rate) : undefined,
+      ssml: Boolean(args.ssml),
     };
 
     try {
+      const startedAt = performance.now();
       const wav = await say(opts);
+      const ttsTimeMs = Math.round(performance.now() - startedAt);
+      if (args.verbose) {
+        // stderr — stdout may carry raw WAV bytes when --out is omitted.
+        console.error(`TTS time: ${ttsTimeMs}ms`);
+      }
       if (!opts.out) {
         process.stdout.write(wav);
       }
@@ -240,8 +263,14 @@ export const mainCommand = defineCommand({
       type: "string",
       description: "Expected language code (ISO 639-1), warn if mismatch",
     },
+    debug: {
+      type: "boolean",
+      description: "Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)",
+      default: false,
+    },
   },
   async run({ args }: { args: MainCommandArgs }) {
+    if (args.debug) log.debugEnabled = true;
     const files = args._;
 
     if (files.length === 0) {
@@ -255,6 +284,7 @@ export const mainCommand = defineCommand({
     const wantsLangId = !!(args.lang || args.verbose || args.json || args.format === "transcript" || args.format === "json");
 
     for (const file of files) {
+      const startedAt = performance.now();
       try {
         // Run audio lang-id and transcription concurrently
         const [audioResult, text] = await Promise.all([
@@ -293,6 +323,7 @@ export const mainCommand = defineCommand({
           lang,
           audioLanguage,
           textLanguage: textLanguage ?? (tinyldLang ? { code: tinyldLang, confidence: 0 } : undefined),
+          sttTimeMs: Math.round(performance.now() - startedAt),
         });
       } catch (err: unknown) {
         hasError = true;
@@ -354,6 +385,8 @@ export type TranscribeResult = {
   lang: string;
   audioLanguage?: LangDetectResult;
   textLanguage?: LangDetectResult;
+  /** Wall-clock time around the engine subprocess calls for this file, ms. See #139. */
+  sttTimeMs?: number;
 };
 
 export function formatTextOutput(results: TranscribeResult[]): string {
@@ -381,6 +414,9 @@ export function formatVerboseOutput(results: TranscribeResult[]): string {
         const confStr = textLang.confidence > 0 ? ` (confidence: ${textLang.confidence.toFixed(2)})` : "";
         lines.push(`Text language: ${textLang.code}${confStr}`);
       }
+      if (r.sttTimeMs !== undefined) {
+        lines.push(`STT time: ${r.sttTimeMs}ms`);
+      }
       lines.push("---");
       lines.push(r.text);
       return lines.join("\n");

package/src/engine-install.ts

@@ -1,11 +1,35 @@
 import { dirname } from "path";
-import { existsSync, mkdirSync, chmodSync } from "fs";
+import { existsSync, mkdirSync, chmodSync, readFileSync, writeFileSync } from "fs";
 import { getEngineBinPath, getEngineCapabilities } from "./engine";
 import { log } from "./log";
 import { streamResponseToFile } from "./progress";
 
 const GITHUB_REPO = "drakulavich/kesha-voice-kit";
 
+/**
+ * Version-marker file written next to the engine binary on download (#151).
+ * Lets `kesha install` detect a stale cached engine after a CLI upgrade and
+ * re-download without requiring `--no-cache`.
+ */
+export function getVersionMarkerPath(binPath: string): string {
+  return `${binPath}.version`;
+}
+
+/** Read the recorded version for the installed binary, or null if missing / empty. */
+export function readInstalledEngineVersion(binPath: string): string | null {
+  try {
+    const v = readFileSync(getVersionMarkerPath(binPath), "utf-8").trim();
+    return v.length > 0 ? v : null;
+  } catch {
+    // Missing, unreadable, or permission-denied → treat as no marker so we re-download.
+    return null;
+  }
+}
+
+export function writeInstalledEngineVersion(binPath: string, version: string): void {
+  writeFileSync(getVersionMarkerPath(binPath), `${version}\n`);
+}
+
 function getEngineBinaryName(): string {
   const platform = process.platform;
   const arch = process.arch;
@@ -28,21 +52,31 @@ export async function downloadEngine(
   options: InstallOptions = {},
 ): Promise<string> {
   const binPath = getEngineBinPath();
+  const pkg = await Bun.file(new URL("../package.json", import.meta.url)).json();
+  // The engine version is tracked separately from the CLI version so
+  // CLI-only patch releases don't require cutting a new GitHub release
+  // + Rust rebuild. Fall back to the CLI version for backwards compat.
+  const engineVersion =
+    typeof pkg.keshaEngine?.version === "string"
+      ? pkg.keshaEngine.version
+      : typeof pkg.version === "string"
+        ? pkg.version
+        : "unknown";
 
-  if (!noCache && existsSync(binPath)) {
-    log.success("Engine binary already installed.");
+  const installedVersion = readInstalledEngineVersion(binPath);
+  const cacheValid =
+    !noCache && existsSync(binPath) && installedVersion === engineVersion;
+
+  if (cacheValid) {
+    log.success(`Engine binary already installed (v${engineVersion}).`);
   } else {
+    // Log why we're downloading — helps diagnose surprising re-downloads.
+    if (existsSync(binPath) && installedVersion && installedVersion !== engineVersion) {
+      log.progress(
+        `Upgrading engine v${installedVersion} → v${engineVersion}...`,
+      );
+    }
     const binaryName = getEngineBinaryName();
-    const pkg = await Bun.file(new URL("../package.json", import.meta.url)).json();
-    // The engine version is tracked separately from the CLI version so
-    // CLI-only patch releases don't require cutting a new GitHub release
-    // + Rust rebuild. Fall back to the CLI version for backwards compat.
-    const engineVersion =
-      typeof pkg.keshaEngine?.version === "string"
-        ? pkg.keshaEngine.version
-        : typeof pkg.version === "string"
-        ? pkg.version
-        : "unknown";
     const url = `https://github.com/${GITHUB_REPO}/releases/download/v${engineVersion}/${binaryName}`;
 
     mkdirSync(dirname(binPath), { recursive: true });
@@ -64,7 +98,8 @@ export async function downloadEngine(
 
     await streamResponseToFile(res, binPath, "kesha-engine binary");
     chmodSync(binPath, 0o755);
-    log.success("Engine binary downloaded.");
+    writeInstalledEngineVersion(binPath, engineVersion);
+    log.success(`Engine binary downloaded (v${engineVersion}).`);
   }
 
   if (backend) {

package/src/engine.ts

@@ -1,6 +1,7 @@
 import { join } from "path";
 import { homedir } from "os";
 import { existsSync } from "fs";
+import { log } from "./log";
 
 export interface LangDetectResult {
   code: string;
@@ -24,6 +25,8 @@ export function isEngineInstalled(): boolean {
 
 async function runEngine(args: string[]): Promise<{ stdout: string; stderr: string; exitCode: number }> {
   const binPath = getEngineBinPath();
+  const startedAt = performance.now();
+  log.debug(`spawn ${binPath} ${args.join(" ")}`);
   const proc = Bun.spawn([binPath, ...args], {
     stdout: "pipe",
     stderr: "pipe",
@@ -35,6 +38,7 @@ async function runEngine(args: string[]): Promise<{ stdout: string; stderr: stri
     proc.exited,
   ]);
 
+  log.debug(`exit=${exitCode} dt=${Math.round(performance.now() - startedAt)}ms args=${JSON.stringify(args)}`);
   return { stdout: stdout.trim(), stderr: stderr.trim(), exitCode };
 }
 

package/src/log.ts

@@ -1,9 +1,26 @@
 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.
+ */
+function envDebug(): boolean {
+  const v = process.env.KESHA_DEBUG;
+  return !!v && v !== "0" && v.toLowerCase() !== "false";
+}
+
 export const log = {
   info: (msg: string) => console.log(msg),
   success: (msg: string) => console.log(pc.green(msg)),
   progress: (msg: string) => console.log(pc.cyan(msg)),
   warn: (msg: string) => console.error(pc.yellow(msg)),
   error: (msg: string) => console.error(pc.red(msg)),
+
+  debugEnabled: false,
+  debug(msg: string): void {
+    if (this.debugEnabled || envDebug()) {
+      console.error(pc.dim(`[debug] ${msg}`));
+    }
+  },
 };

package/src/say.ts

@@ -1,4 +1,5 @@
 import { getEngineBinPath, isEngineInstalled } from "./engine";
+import { log } from "./log";
 
 export interface SayOptions {
   /**
@@ -15,6 +16,8 @@ export interface SayOptions {
   out?: string;
   /** Speaking rate 0.5–2.0. */
   rate?: number;
+  /** Parse `text` as SSML (`<speak>…<break time="500ms"/>…</speak>`). See issue #122. */
+  ssml?: boolean;
 }
 
 /** Build the argv passed to `kesha-engine say` (pure, unit-testable). */
@@ -24,6 +27,7 @@ export function buildSayArgs(o: SayOptions): string[] {
   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.ssml) args.push("--ssml");
   if (o.text !== undefined && o.text.length > 0) args.push(o.text);
   return args;
 }
@@ -52,6 +56,8 @@ export async function say(opts: SayOptions): Promise<Uint8Array> {
     );
   }
   const args = buildSayArgs({ ...opts, text: undefined });
+  const startedAt = performance.now();
+  log.debug(`spawn ${getEngineBinPath()} ${args.join(" ")} (text: ${opts.text?.length ?? 0} chars)`);
   const proc = Bun.spawn([getEngineBinPath(), ...args], {
     stdin: "pipe",
     stdout: "pipe",
@@ -71,6 +77,7 @@ export async function say(opts: SayOptions): Promise<Uint8Array> {
     proc.exited,
   ]);
 
+  log.debug(`exit=${exitCode} dt=${Math.round(performance.now() - startedAt)}ms bytes=${stdoutBuf.byteLength}`);
   if (exitCode !== 0) {
     throw new SayError(
       stderrText.trim() || `kesha-engine say exited ${exitCode}`,