@drakulavich/kesha-voice-kit 1.3.0 → 1.4.2

package/src/engine-install.ts

@@ -76,14 +76,29 @@ async function downloadAVSpeechSidecar(binPath: string, engineVersion: string):
     return;
   }
 
-  await streamResponseToFile(res, sidecarPath, "say-avspeech sidecar");
-  chmodSync(sidecarPath, 0o755);
-  log.success("AVSpeech sidecar installed (macOS voices available).");
+  // 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(
@@ -128,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`,
       );
@@ -147,7 +178,7 @@ export async function downloadEngine(
     chmodSync(binPath, 0o755);
     writeInstalledEngineVersion(binPath, engineVersion);
     log.success(`Engine binary downloaded (v${engineVersion}).`);
-    await downloadAVSpeechSidecar(binPath, engineVersion);
+    await sidecarPromise;
   }
 
   if (backend) {
@@ -164,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

@@ -1,10 +1,37 @@
-import { readdirSync } from "fs";
+import { readdirSync, statSync } from "fs";
 import { homedir } from "os";
 import { join } from "path";
 import { isEngineInstalled, getEngineBinPath, getEngineCapabilities } from "./engine";
 import { log } from "./log";
 import pc from "picocolors";
 
+function humanBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  const units = ["KB", "MB", "GB"];
+  let n = bytes / 1024;
+  let i = 0;
+  while (n >= 1024 && i < units.length - 1) {
+    n /= 1024;
+    i++;
+  }
+  return `${n.toFixed(n >= 100 ? 0 : 1)} ${units[i]}`;
+}
+
+function dirSizeBytes(path: string): number {
+  let total = 0;
+  try {
+    const st = statSync(path);
+    if (st.isFile()) return st.size;
+    for (const entry of readdirSync(path, { withFileTypes: true })) {
+      const p = join(path, entry.name);
+      total += entry.isDirectory() ? dirSizeBytes(p) : statSync(p).size;
+    }
+  } catch {
+    /* missing path — component not installed */
+  }
+  return total;
+}
+
 export function formatStatusLine(
   label: string,
   path: string | null,
@@ -38,6 +65,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) {
@@ -49,6 +80,8 @@ export async function showStatus(): Promise<void> {
       }
       log.info("");
     }
+
+    showDiskUsage(binPath);
   }
 
   if (!installed) {
@@ -56,10 +89,78 @@ export async function showStatus(): Promise<void> {
   }
 }
 
+function showDiskUsage(binPath: string): void {
+  const cache = kesheCacheDir();
+  // Engine binary lives under `<cache>/engine/bin/` (managed by the TS CLI's
+  // engine-install) while all models live under `<cache>/models/` (managed by
+  // the Rust engine). Point at `engine/` (two levels up from the binary) so
+  // any future sibling files under that root (metadata, hooks, etc.) are
+  // counted too.
+  const engineDir = join(binPath, "..", "..");
+
+  const components: Array<{ label: string; path: string }> = [
+    { label: "Engine", path: engineDir },
+    { label: "ASR (Parakeet)", path: join(cache, "models/parakeet-tdt-v3") },
+    { label: "Language ID", path: join(cache, "models/lang-id-ecapa") },
+    { label: "VAD (Silero)", path: join(cache, "models/silero-vad") },
+    { label: "TTS (Kokoro)", path: join(cache, "models/kokoro-82m") },
+    { label: "TTS (Piper)", path: join(cache, "models/piper-ru") },
+    { label: "TTS (G2P)", path: join(cache, "models/g2p") },
+  ];
+
+  const rows: Array<{ label: string; size: number }> = [];
+  for (const c of components) {
+    const size = dirSizeBytes(c.path);
+    if (size > 0) rows.push({ label: c.label, size });
+  }
+
+  if (rows.length === 0) return;
+
+  // Total counts everything under both the model cache root AND the engine
+  // dir (which may live outside the cache when `KESHA_ENGINE_BIN` overrides
+  // the default layout). That way the number matches what the `rm -rf` hint
+  // below would actually free, including any temp downloads or future
+  // components not in the per-row list.
+  const componentTotal = rows.reduce((n, r) => n + r.size, 0);
+  const cacheTotal = dirSizeBytes(cache);
+  const engineOutsideCache = engineDir.startsWith(cache)
+    ? 0
+    : dirSizeBytes(engineDir);
+  const total = cacheTotal + engineOutsideCache;
+
+  log.info(`Disk usage (${cache}):`);
+  const labelWidth = Math.max(...rows.map((r) => r.label.length), "Total".length);
+  for (const r of rows) {
+    const pad = " ".repeat(labelWidth - r.label.length + 2);
+    log.info(`  ${r.label}:${pad}${humanBytes(r.size)}`);
+  }
+  const totalPad = " ".repeat(labelWidth - "Total".length + 2);
+  log.info(`  ${pc.bold("Total")}:${totalPad}${pc.bold(humanBytes(total))}`);
+  if (total > componentTotal) {
+    const other = total - componentTotal;
+    log.info(pc.dim(`  (includes ${humanBytes(other)} of other cache files)`));
+  }
+  log.info("");
+  log.info(pc.dim(`  To reset cache: rm -rf ${cache} — next \`kesha install\` re-downloads.`));
+  log.info("");
+}
+
 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();
-}