@drakulavich/kesha-voice-kit 1.2.2 → 1.4.1

package/src/engine-install.ts

@@ -1,4 +1,4 @@
-import { dirname } from "path";
+import { dirname, join } from "path";
 import { existsSync, mkdirSync, chmodSync, readFileSync, writeFileSync } from "fs";
 import { getEngineBinPath, getEngineCapabilities } from "./engine";
 import { log } from "./log";
@@ -41,9 +41,64 @@ function getEngineBinaryName(): string {
   throw new Error(`Unsupported platform: ${platform} ${arch}`);
 }
 
+/**
+ * Fetch the AVSpeechSynthesizer sidecar (#141) and place it next to the
+ * engine binary on darwin-arm64. The Rust side (`avspeech::helper_path`)
+ * looks for a `say-avspeech` file adjacent to the running executable, so
+ * the filename on disk is always `say-avspeech` regardless of the release
+ * asset name.
+ *
+ * Best-effort: 404s (older engine versions predate the sidecar) and
+ * network errors log a warning and return — macos-* voices simply won't
+ * be available, which is a graceful degradation. The user keeps Kokoro +
+ * Piper.
+ */
+async function downloadAVSpeechSidecar(binPath: string, engineVersion: string): Promise<void> {
+  if (process.platform !== "darwin" || process.arch !== "arm64") return;
+
+  const sidecarPath = join(dirname(binPath), "say-avspeech");
+  const url = `https://github.com/${GITHUB_REPO}/releases/download/v${engineVersion}/say-avspeech-darwin-arm64`;
+
+  let res: Response;
+  try {
+    res = await fetch(url, { redirect: "follow" });
+  } catch (e) {
+    log.warn(
+      `Could not fetch AVSpeech sidecar (${e instanceof Error ? e.message : e}); macos-* voices unavailable.`,
+    );
+    return;
+  }
+
+  if (!res.ok) {
+    log.warn(
+      `AVSpeech sidecar not in release v${engineVersion} (HTTP ${res.status}); macos-* voices unavailable.`,
+    );
+    return;
+  }
+
+  // Keep the best-effort contract: streamResponseToFile throws on an empty
+  // body and can fail mid-stream, and chmodSync can throw EPERM. Without
+  // this catch a stream/chmod failure would propagate through the tail
+  // `await sidecarPromise` in downloadEngine — converting a successful
+  // engine install into a thrown exception after log.success already
+  // announced it, which is exactly the regression the fetch/404 branches
+  // above protect against.
+  try {
+    await streamResponseToFile(res, sidecarPath, "say-avspeech sidecar");
+    chmodSync(sidecarPath, 0o755);
+    log.success("AVSpeech sidecar installed (macOS voices available).");
+  } catch (e) {
+    log.warn(
+      `AVSpeech sidecar install failed (${e instanceof Error ? e.message : e}); macos-* voices unavailable.`,
+    );
+  }
+}
+
 export interface InstallOptions {
-  /** Also install Kokoro TTS models. Requires espeak-ng on PATH. */
+  /** Also install Kokoro + Piper + ONNX G2P TTS models. */
   tts?: boolean;
+  /** Also install Silero VAD model for long-audio preprocessing. */
+  vad?: boolean;
 }
 
 export async function downloadEngine(
@@ -69,6 +124,13 @@ export async function downloadEngine(
 
   if (cacheValid) {
     log.success(`Engine binary already installed (v${engineVersion}).`);
+    // Cover the upgrade path from pre-#141 engines that never had a
+    // sidecar: if the cached engine is current but the sibling sidecar
+    // is missing, fetch it now so macos-* voices start working.
+    const sidecarPath = join(dirname(binPath), "say-avspeech");
+    if (!existsSync(sidecarPath)) {
+      await downloadAVSpeechSidecar(binPath, engineVersion);
+    }
   } else {
     // Log why we're downloading — helps diagnose surprising re-downloads.
     if (existsSync(binPath) && installedVersion && installedVersion !== engineVersion) {
@@ -81,16 +143,32 @@ export async function downloadEngine(
 
     mkdirSync(dirname(binPath), { recursive: true });
 
+    // Kick off the sidecar fetch concurrently with the engine fetch. Both
+    // target github.com release assets on independent paths with no data
+    // dependency, so overlapping the HTTP round-trips saves ~15-30s on a
+    // cold install. Sidecar is best-effort (404 on older engines, warn +
+    // continue) so a failure doesn't cascade into the engine path.
+    const sidecarPromise = downloadAVSpeechSidecar(binPath, engineVersion);
+
     let res: Response;
     try {
       res = await fetch(url, { redirect: "follow" });
     } catch (e) {
+      // Attach a no-op rejection handler to the sidecar promise as
+      // defense-in-depth. Today it can't reject (downloadAVSpeechSidecar
+      // catches all of its own errors), but if that contract ever drifts
+      // a bare dangling promise would surface as an unhandledRejection
+      // while we're throwing the engine error. Not waiting — the engine
+      // error is what the user needs to see now; sidecar's own logs
+      // will print whenever they finish.
+      sidecarPromise.catch(() => {});
       throw new Error(
         `Failed to fetch engine binary: ${e instanceof Error ? e.message : e}\n  Fix: Check your network connection and try again`,
       );
     }
 
     if (!res.ok) {
+      sidecarPromise.catch(() => {});
       throw new Error(
         `Failed to download engine binary (HTTP ${res.status})\n  Fix: Check https://github.com/${GITHUB_REPO}/releases for available versions`,
       );
@@ -100,6 +178,7 @@ export async function downloadEngine(
     chmodSync(binPath, 0o755);
     writeInstalledEngineVersion(binPath, engineVersion);
     log.success(`Engine binary downloaded (v${engineVersion}).`);
+    await sidecarPromise;
   }
 
   if (backend) {
@@ -116,6 +195,7 @@ export async function downloadEngine(
     "install",
     ...(noCache ? ["--no-cache"] : []),
     ...(options.tts ? ["--tts"] : []),
+    ...(options.vad ? ["--vad"] : []),
   ];
   const proc = Bun.spawnSync([binPath, ...installArgs], {
     stdout: "pipe",

package/src/engine.ts

@@ -42,8 +42,25 @@ async function runEngine(args: string[]): Promise<{ stdout: string; stderr: stri
   return { stdout: stdout.trim(), stderr: stderr.trim(), exitCode };
 }
 
-export async function transcribeEngine(audioPath: string): Promise<string> {
-  const { stdout, stderr, exitCode } = await runEngine(["transcribe", audioPath]);
+/** VAD preprocessing selector.
+ *  - `"auto"` (default): engine decides — VAD when audio ≥ 120 s and model installed
+ *  - `"on"`: force VAD (requires `kesha install --vad`)
+ *  - `"off"`: force full-file pass regardless of duration or install state
+ */
+export type VadMode = "auto" | "on" | "off";
+
+export interface TranscribeEngineOptions {
+  vad?: VadMode;
+}
+
+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 { stdout, stderr, exitCode } = await runEngine(args);
   if (exitCode !== 0) {
     throw new Error(stderr || `kesha-engine exited with code ${exitCode}`);
   }

package/src/format.ts

@@ -0,0 +1,57 @@
+import type { TranscribeResult } from "./types";
+
+export function formatTextOutput(results: TranscribeResult[]): string {
+  if (results.length === 1) {
+    return results[0].text + "\n";
+  }
+  return results
+    .map((r, i) => (i > 0 ? "\n" : "") + `=== ${r.file} ===\n${r.text}\n`)
+    .join("");
+}
+
+export function formatVerboseOutput(results: TranscribeResult[]): string {
+  return results
+    .map((r, i) => {
+      const lines: string[] = [];
+      if (results.length > 1) {
+        if (i > 0) lines.push("");
+        lines.push(`=== ${r.file} ===`);
+      }
+      if (r.audioLanguage) {
+        lines.push(`Audio language: ${r.audioLanguage.code} (confidence: ${r.audioLanguage.confidence.toFixed(2)})`);
+      }
+      const textLang = r.textLanguage ?? (r.lang ? { code: r.lang, confidence: 0 } : null);
+      if (textLang) {
+        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");
+    })
+    .join("\n") + "\n";
+}
+
+export function formatTranscriptOutput(results: TranscribeResult[]): string {
+  return results
+    .map((r, i) => {
+      const lines: string[] = [];
+      if (results.length > 1) {
+        if (i > 0) lines.push("");
+        lines.push(`=== ${r.file} ===`);
+      }
+      lines.push(r.text);
+      const lang = r.textLanguage?.code || r.audioLanguage?.code || r.lang;
+      const confidence = r.textLanguage?.confidence ?? r.audioLanguage?.confidence;
+      if (lang) lines.push(`[lang: ${lang}${confidence != null ? `, confidence: ${confidence.toFixed(2)}` : ""}]`);
+      return lines.join("\n");
+    })
+    .join("\n") + "\n";
+}
+
+export function formatJsonOutput(results: TranscribeResult[]): string {
+  return JSON.stringify(results, null, 2) + "\n";
+}

package/src/lib.ts

@@ -6,6 +6,20 @@ export type { TranscribeOptions };
 export { downloadEngine as downloadModel };
 export { say, type SayOptions, SayError } from "./say";
 
+/**
+ * Encode a `TranscribeResult[]` as TOON (#138). Same data shape as the
+ * `--json` / `--toon` CLI output; the CLI reads from stdin of a transcribe
+ * run, this helper is for programmatic callers that already have the array.
+ */
+export { formatToonOutput as toToon } from "./toon";
+
+/**
+ * Output shape returned by `kesha --json` and the input shape expected by
+ * `toToon`. Lives in `./types` (since #179) so the public API stops
+ * reaching into the CLI-layer file.
+ */
+export type { TranscribeResult } from "./types";
+
 /** Install Kokoro TTS models. Shorthand for `downloadModel({ tts: true })`. */
 export async function downloadTts(noCache = false): Promise<void> {
   await downloadEngine(noCache, undefined, { tts: true });

package/src/say.ts

@@ -10,7 +10,7 @@ export interface SayOptions {
   text?: string;
   /** Voice id, e.g. `en-af_heart`. Defaults to engine default. */
   voice?: string;
-  /** Override the voice's default espeak language code. */
+  /** Override the voice's default BCP 47 language code (e.g. `en-us`, `ru`). */
   lang?: string;
   /** Write audio to this path instead of returning bytes. */
   out?: string;

package/src/status.ts

@@ -38,6 +38,10 @@ export async function showStatus(): Promise<void> {
 
   log.info(formatStatusLine("Runtime", `Bun ${Bun.version}`, true));
   log.info(formatStatusLine("Platform", `${process.platform} ${process.arch}`, true));
+  const mirror = activeModelMirror();
+  if (mirror) {
+    log.info(formatStatusLine("Mirror", mirror, true));
+  }
   log.info("");
 
   if (installed) {
@@ -60,6 +64,18 @@ function kesheCacheDir(): string {
   return process.env.KESHA_CACHE_DIR ?? join(homedir(), ".cache", "kesha");
 }
 
+/**
+ * Read the effective `KESHA_MODEL_MIRROR` base URL (#121). Returns null when
+ * unset, empty, or whitespace. Matches the Rust side's `model_mirror()` in
+ * `rust/src/models.rs` — keeping them in lockstep lets `kesha status`
+ * surface the exact URL the engine will hit on the next `kesha install`.
+ */
+export function activeModelMirror(): string | null {
+  const raw = process.env.KESHA_MODEL_MIRROR ?? "";
+  const trimmed = raw.trim().replace(/\/+$/, "");
+  return trimmed.length > 0 ? trimmed : null;
+}
+
 function listInstalledVoices(): string[] {
   const cache = kesheCacheDir();
   const voices: string[] = [];

package/src/toon.ts

@@ -0,0 +1,15 @@
+import { encode as encodeToon } from "@toon-format/toon";
+
+/**
+ * TOON (#138) encoding of an array of transcription results. Same data shape
+ * as `formatJsonOutput`; lossless round-trip through `@toon-format/toon`'s
+ * `decode()`.
+ *
+ * Generic so this module stays independent of `TranscribeResult` (defined in
+ * `cli.ts`) and doesn't introduce a runtime cycle between `lib.ts` and
+ * `cli.ts`. Callers that have the concrete `TranscribeResult[]` type will
+ * still get a type-checked call via structural compatibility.
+ */
+export function formatToonOutput<T extends object>(results: T[]): string {
+  return encodeToon(results) + "\n";
+}

package/src/transcribe.ts

@@ -1,10 +1,14 @@
-import { isEngineInstalled, transcribeEngine } from "./engine";
+import { isEngineInstalled, transcribeEngine, type VadMode } from "./engine";
+
+export type { VadMode };
 
 export interface TranscribeOptions {
   silent?: boolean;
+  /** Silero VAD preprocessing selector. Defaults to `"auto"`. */
+  vad?: VadMode;
 }
 
-export async function transcribe(audioPath: string, _opts: TranscribeOptions = {}): Promise<string> {
+export async function transcribe(audioPath: string, opts: TranscribeOptions = {}): Promise<string> {
   if (!isEngineInstalled()) {
     throw new Error(
       "Error: No transcription backend is installed\n\n" +
@@ -16,5 +20,5 @@ export async function transcribe(audioPath: string, _opts: TranscribeOptions = {
     );
   }
 
-  return transcribeEngine(audioPath);
+  return transcribeEngine(audioPath, { vad: opts.vad });
 }

package/src/types.ts

@@ -0,0 +1,18 @@
+import type { LangDetectResult } from "./engine";
+
+/**
+ * One row of `kesha --json` / `kesha --toon` output. Canonical output shape
+ * for programmatic callers of `transcribe(...)` + `toToon(...)` in the
+ * public API (`@drakulavich/kesha-voice-kit/core`).
+ */
+export type TranscribeResult = {
+  file: string;
+  text: string;
+  lang: string;
+  audioLanguage?: LangDetectResult;
+  textLanguage?: LangDetectResult;
+  /** Wall-clock time around the engine subprocess calls for this file, ms. See #139. */
+  sttTimeMs?: number;
+};
+
+export type { LangDetectResult };

package/src/models.ts

@@ -1,6 +0,0 @@
-import { isEngineInstalled } from "./engine";
-export { downloadEngine } from "./engine-install";
-
-export function isModelInstalled(): boolean {
-  return isEngineInstalled();
-}