@drakulavich/kesha-voice-kit 1.30.0 → 2.0.0

package/src/engine.ts

@@ -1,12 +1,13 @@
-import { existsSync, statSync } from "fs";
+import { existsSync, statSync, type Stats } from "fs";
 import { errorMessage } from "./error-utils";
 import { join } from "path";
 import { installHint } from "./install-hint";
 import { log } from "./log";
 import { createLiveStatus } from "./progress";
 import { defaultEngineBinPath, keshaCacheDir } from "./paths";
-import { engineAbortError, registerProcessTree } from "./process-tree";
-import { engineFailure, KeshaError, readEvents, type ErrorEvent } from "./engine/events";
+import { engineAbortError, interruptedRun } from "./process-tree";
+import { runEngineProcess, spawnHint } from "./engine/spawn";
+import { engineFailure, KeshaError, renderError, type ErrorEvent } from "./engine/events";
 import {
   describeToCapabilities,
   parseDescribe,
@@ -15,7 +16,6 @@ import {
   type DescribeDocument,
   type EngineCapabilities,
   type TtsLanguageCapability,
-  PROTOCOL_VERSION,
 } from "./engine/describe";
 
 export type { EngineCapabilities, TtsLanguageCapability };
@@ -74,39 +74,10 @@ export function isEngineInstalled(): boolean {
   return existsSync(getEngineBinPath());
 }
 
-type SpawnStdioEntry = "inherit" | "pipe" | "ignore";
-export type SpawnStdio = [SpawnStdioEntry, SpawnStdioEntry, SpawnStdioEntry];
-
-/** The env for a spawn whose stderr is parsed as protocol 4 events. */
-export function protocolEnv(): Record<string, string | undefined> {
-  return { ...process.env, KESHA_PROTOCOL: String(PROTOCOL_VERSION) };
-}
-
-function spawnHint(): string {
-  return process.env.KESHA_ENGINE_BIN
-    ? "KESHA_ENGINE_BIN points at it; fix the path or unset it and run `kesha install`"
-    : "run `kesha install`";
-}
-
-/** `Bun.spawn` throws synchronously on ENOENT/EACCES; every launch failure becomes `E_ENGINE_SPAWN`. */
-export function spawnEngineProcess(
-  binPath: string,
-  args: string[],
-  stdio: SpawnStdio,
-  env: Record<string, string | undefined> = process.env,
-): ReturnType<typeof Bun.spawn> {
-  try {
-    // `env` is passed explicitly: Bun snapshots process.env at startup otherwise (#874).
-    return Bun.spawn([binPath, ...args], { detached: true, stdio, env });
-  } catch (err) {
-    throw new KeshaError("E_ENGINE_SPAWN", `failed to launch kesha-engine at ${binPath}: ${errorMessage(err)}`, {
-      hint: spawnHint(),
-    });
-  }
-}
-
 export interface RunEngineOptions {
   signal?: AbortSignal;
+  /** Text for the subprocess's stdin. Nothing a user typed may become an argv element: a NUL byte or a megabyte of it makes the spawn itself fail (#T1-1). */
+  stdin?: string;
   /** Receives each progress line as the engine writes it, rather than once the run is
    *  over (#1002). Progress the caller takes delivery of this way is dropped from the
    *  returned `stderr`, so it is never shown a second time in the failure report. */
@@ -122,44 +93,25 @@ interface EngineRun {
 }
 
 async function runEngine(args: string[], opts: RunEngineOptions = {}): Promise<EngineRun> {
-  if (opts.signal?.aborted) throw engineAbortError();
-  const binPath = getEngineBinPath();
-  const startedAt = performance.now();
-  log.debug(`spawn ${binPath} ${args.join(" ")}`);
-  const proc = spawnEngineProcess(binPath, args, ["ignore", "pipe", "pipe"], protocolEnv());
-  const tree = registerProcessTree(proc);
-  let aborted = false;
-  let forceKillTimer: Timer | undefined;
-  const abort = () => {
-    aborted = true;
-    tree.terminate("SIGTERM");
-    forceKillTimer ??= tree.forceKillAfterGrace();
-  };
-  opts.signal?.addEventListener("abort", abort, { once: true });
-  let stdout: string;
-  let events: Awaited<ReturnType<typeof readEvents>>;
-  let exitCode: number;
-  try {
-    [stdout, events, exitCode] = await Promise.all([
-      new Response(proc.stdout as ReadableStream<Uint8Array>).text(),
-      readEvents(proc.stderr as ReadableStream<Uint8Array>, { onProgress: opts.onProgressLine }),
-      proc.exited,
-    ]);
-  } finally {
-    opts.signal?.removeEventListener("abort", abort);
-    tree.dispose();
-    if (!aborted && forceKillTimer) clearTimeout(forceKillTimer);
-  }
-  log.debug(`exit=${exitCode} dt=${Math.round(performance.now() - startedAt)}ms args=${JSON.stringify(args)}`);
-  if (aborted) {
+  const run = await runEngineProcess(getEngineBinPath(), args, {
+    stdio: [opts.stdin === undefined ? "ignore" : "pipe", "pipe", "pipe"],
+    stdin: opts.stdin,
+    readStdout: (stream) => new Response(stream).text(),
+    sinks: { onProgress: opts.onProgressLine },
+    signal: opts.signal,
+  });
+  if (run.aborted) {
     log.debug(`aborted args=${JSON.stringify(args)}`);
     throw engineAbortError();
   }
+  const interrupted = interruptedRun(run.exitCode);
+  if (interrupted) throw interrupted;
+  const { events } = run;
   const stderr = events.stderr.trim();
   // #275 D4: warnings reach the user on success; on failure they travel inside the KeshaError.
-  if (exitCode === 0 && events.invalid.length === 0 && events.error === null && stderr.length > 0)
+  if (run.exitCode === 0 && events.invalid.length === 0 && events.error === null && stderr.length > 0)
     process.stderr.write(`${stderr}\n`);
-  return { stdout: stdout.trim(), stderr, exitCode, error: events.error, invalid: events.invalid };
+  return { stdout: run.stdout.trim(), stderr, exitCode: run.exitCode, error: events.error, invalid: events.invalid };
 }
 
 /** The run failed and said so: a non-zero status, or an error event whatever the status. */
@@ -172,20 +124,25 @@ function failed(run: EngineRun): boolean {
   return reportedFailure(run) || run.invalid.length > 0;
 }
 
-let cachedDescribe: { binPath: string; mtime: number; doc: DescribeDocument } | null = null;
+let cachedDescribe: { identity: string; doc: DescribeDocument } | null = null;
+
+/** ctime is part of it because utimes cannot set it back after a replacement that restores mtime (#1256, #1258). */
+function fileIdentity(binPath: string, st: Stats): string {
+  return `${binPath}:${st.ino}:${st.size}:${st.ctimeMs}`;
+}
 
 /** The describe document of the installed engine, cached until the binary changes (#248). */
 export async function getDescribe(opts: RunEngineOptions = {}): Promise<DescribeDocument> {
   const binPath = getEngineBinPath();
-  let mtime: number;
+  let identity: string;
   try {
-    mtime = statSync(binPath).mtimeMs;
+    identity = fileIdentity(binPath, statSync(binPath));
   } catch (err) {
     throw new KeshaError("E_ENGINE_SPAWN", `kesha-engine not found at ${binPath}: ${errorMessage(err)}`, {
       hint: spawnHint(),
     });
   }
-  if (cachedDescribe?.binPath === binPath && cachedDescribe.mtime === mtime) return cachedDescribe.doc;
+  if (cachedDescribe?.identity === identity) return cachedDescribe.doc;
   const run = await runEngine(["describe"], opts);
   let doc: DescribeDocument | null = null;
   if (run.exitCode === 0) {
@@ -205,17 +162,42 @@ export async function getDescribe(opts: RunEngineOptions = {}): Promise<Describe
   const mismatch = protocolMismatch(doc, binPath);
   if (mismatch) throw mismatch;
   if (run.invalid.length > 0) throw engineFailure("describe", run, undefined);
-  cachedDescribe = { binPath, mtime, doc };
+  cachedDescribe = { identity, doc };
   return doc;
 }
 
-/** Capabilities view for the screens that predate `describe`; null when the engine cannot be read. */
-export async function getEngineCapabilities(opts: RunEngineOptions = {}): Promise<EngineCapabilities | null> {
+/** Generous because macOS Gatekeeper can take several seconds to scan a freshly written binary on its first run. */
+export const ENGINE_PROBE_TIMEOUT_MS = 15_000;
+
+let unansweredDescribe: string | null = null;
+
+function binaryIdentity(binPath: string): string {
+  const st = statSync(binPath, { throwIfNoEntry: false });
+  return st ? fileIdentity(binPath, st) : `${binPath}:missing`;
+}
+
+/** Capabilities view for the screens that predate `describe`; null when the engine cannot be read within the deadline. */
+export async function getEngineCapabilities(timeoutMs = ENGINE_PROBE_TIMEOUT_MS): Promise<EngineCapabilities | null> {
+  const binPath = getEngineBinPath();
+  const identity = binaryIdentity(binPath);
+  // `install --plan` probes twice; a binary that already let one deadline pass is not waited on again.
+  if (unansweredDescribe === identity) return null;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
   try {
-    return describeToCapabilities(await getDescribe(opts));
+    return describeToCapabilities(await getDescribe({ signal: controller.signal }));
   } catch (err) {
-    if (err instanceof KeshaError) return null;
-    throw err;
+    if (!(err instanceof KeshaError)) throw err;
+    if (controller.signal.aborted) {
+      unansweredDescribe = identity;
+      log.warn(
+        `kesha-engine at ${binPath} did not answer \`describe\` within ${timeoutMs / 1000}s; ` +
+          "continuing without its capabilities — re-run `kesha install` to replace it",
+      );
+    }
+    return null;
+  } finally {
+    clearTimeout(timer);
   }
 }
 
@@ -454,47 +436,43 @@ async function forwardStdout(stream: ReadableStream<Uint8Array>, status: { clear
  * reworded ticker degrades to one line per second rather than breaking (`recordTicksInPlace`).
  */
 const RECORD_TICK = /^Listening\.\.\. \d+s$/;
+/** The recording's outcome arrives as progress too; it is the result, so `--quiet` must not drop it (Exploratory S3-F2). */
+const RECORD_OUTCOME = /^(Recorded .+ \(\d+ Hz, \d+ channels?, \d+ frames\)|No speech detected\.)$/;
 
 export async function recordEngine(target: RecordTarget, maxSeconds: number): Promise<void> {
-  const binPath = getEngineBinPath();
-  const args = buildRecordArgs(target, maxSeconds);
-  const startedAt = performance.now();
-  log.debug(`spawn ${binPath} ${args.join(" ")}`);
-  // stdout is piped rather than inherited so the row can be closed before the engine's transcript
-  // lands: the engine owned both streams and closed its own row until #1181 deleted the painter.
-  const proc = spawnEngineProcess(binPath, args, ["inherit", "pipe", "pipe"], protocolEnv());
-  const tree = registerProcessTree(proc);
   const status = createLiveStatus();
-  let events: Awaited<ReturnType<typeof readEvents>>;
-  let exitCode: number;
+  let run: Awaited<ReturnType<typeof runEngineProcess>>;
   try {
-    [, events, exitCode] = await Promise.all([
-      forwardStdout(proc.stdout as ReadableStream<Uint8Array>, status, () => {
-        // Nobody is reading the transcript any more, so the microphone has no reason to stay open (#1187).
-        log.debug("stdout closed by the reader; stopping the recording");
-        proc.kill("SIGTERM");
-      }),
-      readEvents(proc.stderr as ReadableStream<Uint8Array>, {
+    // stdout is piped rather than inherited so the row can be closed before the engine's transcript
+    // lands: the engine owned both streams and closed its own row until #1181 deleted the painter.
+    run = await runEngineProcess(getEngineBinPath(), buildRecordArgs(target, maxSeconds), {
+      stdio: ["inherit", "pipe", "pipe"],
+      readStdout: (stream, proc) =>
+        forwardStdout(stream, status, () => {
+          // Nobody is reading the transcript any more, so the microphone has no reason to stay open (#1187).
+          log.debug("stdout closed by the reader; stopping the recording");
+          proc.kill("SIGTERM");
+        }),
+      sinks: {
         onProgress: (line) => {
           if (RECORD_TICK.test(line)) {
             status.update(line);
             return;
           }
           status.clear();
-          log.progress(line);
+          if (RECORD_OUTCOME.test(line)) log.notice(line);
+          else log.progress(line);
         },
         onWarn: (line) => {
           status.clear();
           log.warn(line);
         },
-      }),
-      proc.exited,
-    ]);
+      },
+    });
   } finally {
     status.clear();
-    tree.dispose();
   }
-  log.debug(`exit=${exitCode} dt=${Math.round(performance.now() - startedAt)}ms args=${JSON.stringify(args)}`);
+  const { exitCode, events } = run;
   // An interrupt is how a live recording normally ends, so its status is success and its stderr is not a failure.
   const signalled = target.live && SIGNALLED_LIVE_EXIT_CODES.has(exitCode);
   // A clean interrupt delivers the transcript and exits 128+signal saying nothing (rust/src/cli/record.rs:82),
@@ -523,7 +501,14 @@ export async function detectAudioLanguageEngine(
   if (!isEngineInstalled()) return null;
   const run = await runEngine(["detect-lang", audioPath], opts);
   // The tolerant form: a noisy onnxruntime warning must not blind a best-effort guess.
-  if (reportedFailure(run)) return null;
+  if (reportedFailure(run)) {
+    const cause = run.error ? renderError(run.error) : `kesha-engine detect-lang exited with code ${run.exitCode}`;
+    log.warn(
+      `Audio language detection failed: ${cause}\n` +
+        "  Fix: run `kesha install` to reinstall the engine and its language-ID model.",
+    );
+    return null;
+  }
   return parseLangResult(run.stdout);
 }
 
@@ -533,7 +518,7 @@ export async function detectTextLanguageEngine(
 ): Promise<LangDetectResult | null> {
   if (text.trim().length === 0) return null;
   if (!isEngineInstalled()) return null;
-  const run = await runEngine(["detect-text-lang", text], opts);
+  const run = await runEngine(["detect-text-lang"], { ...opts, stdin: text });
   if (reportedFailure(run)) {
     const warning = textLangFailureWarning(run.stderr);
     if (warning) log.warn(warning);

package/src/fluid-roots.ts

@@ -71,6 +71,11 @@ export function kokoroAneDir(options: FluidRootsOptions = {}): string {
   return join(kokoroBundleRoot(options), "ANE");
 }
 
+/** The Mandarin sibling bundle; mirrors `models/paths.rs::fluidaudio_ane_zh_kokoro_dir`. */
+export function kokoroAneZhDir(options: FluidRootsOptions = {}): string {
+  return join(kokoroBundleRoot(options), "ANE-zh");
+}
+
 /**
  * FluidAudio's own VAD copy, distinct from the Silero model Kesha pins under `<cache>/models`.
  * The bridge passes no directory for VAD, so this stays put whatever the models root is —

package/src/format.ts

@@ -1,5 +1,8 @@
+import { LANG_CONFIDENCE_FLOOR, routeLanguage } from "./language-routing";
 import type { TranscribeErrorRecord, TranscribeJsonOutput, TranscribeResult } from "./types";
 
+const BELOW_FLOOR_NOTE = `below the ${LANG_CONFIDENCE_FLOOR} floor, ignored for lang`;
+
 export function formatTextOutput(results: TranscribeResult[]): string {
   const [first] = results;
   if (first && results.length === 1) {
@@ -10,7 +13,9 @@ export function formatTextOutput(results: TranscribeResult[]): string {
     .join("");
 }
 
-export function formatVerboseOutput(results: TranscribeResult[]): string {
+/** The `--verbose` block for stderr: detection details and timing, never the transcript (that is stdout's). */
+export function formatVerboseDiagnostics(results: TranscribeResult[]): string {
+  if (results.length === 0) return "";
   return results
     .map((r, i) => {
       const lines: string[] = [];
@@ -18,19 +23,20 @@ export function formatVerboseOutput(results: TranscribeResult[]): string {
         if (i > 0) lines.push("");
         lines.push(`=== ${r.file} ===`);
       }
+      const route = routeLanguage({ audioLanguage: r.audioLanguage, textLanguage: r.textLanguage });
       if (r.audioLanguage) {
-        lines.push(`Audio language: ${r.audioLanguage.code} (confidence: ${r.audioLanguage.confidence.toFixed(2)})`);
+        const note = route.belowFloor.audio ? `, ${BELOW_FLOOR_NOTE}` : "";
+        lines.push(`Audio language: ${r.audioLanguage.code} (confidence: ${r.audioLanguage.confidence.toFixed(2)}${note})`);
       }
       const textLang = r.textLanguage ?? (r.lang ? { code: r.lang, confidence: 0 } : null);
       if (textLang) {
-        const confStr = textLang.confidence > 0 ? ` (confidence: ${textLang.confidence.toFixed(2)})` : "";
+        const note = route.belowFloor.text ? `, ${BELOW_FLOOR_NOTE}` : "";
+        const confStr = textLang.confidence > 0 ? ` (confidence: ${textLang.confidence.toFixed(2)}${note})` : "";
         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";

package/src/install-lock.ts

@@ -41,6 +41,16 @@ interface LockOwner {
   startedAt: number;
 }
 
+/**
+ * An owner file by name. `live` carries its record; `corrupt` read but does not parse and is still
+ * a name to unlink; `unreadable` is one the read itself refused (EACCES, EIO) — nothing to judge,
+ * so it counts as held rather than as a corrupt owner to clear.
+ */
+type LockHolder =
+  | { kind: "live"; token: string; owner: LockOwner }
+  | { kind: "corrupt"; token: string }
+  | { kind: "unreadable"; token: string };
+
 /**
  * The owner is named by its file rather than identified by a field inside one: unlinking that
  * exact name is what makes both release and stale-lock takeover exclusive. Of two waiters
@@ -51,7 +61,7 @@ function ownerPath(lockDir: string, token: string): string {
   return join(lockDir, `${OWNER_PREFIX}${token}${OWNER_SUFFIX}`);
 }
 
-function readOwner(lockDir: string): LockOwner | null {
+function readOwner(lockDir: string): LockHolder | null {
   let entries: string[];
   try {
     entries = readdirSync(lockDir);
@@ -60,10 +70,21 @@ function readOwner(lockDir: string): LockOwner | null {
   }
   const name = entries.find((e) => e.startsWith(OWNER_PREFIX) && e.endsWith(OWNER_SUFFIX));
   if (!name) return null;
+  const token = name.slice(OWNER_PREFIX.length, -OWNER_SUFFIX.length);
+  let raw: string;
   try {
-    return JSON.parse(readFileSync(join(lockDir, name), "utf8")) as LockOwner;
-  } catch {
-    return null;
+    raw = readFileSync(join(lockDir, name), "utf8");
+  } catch (e) {
+    // The owner released between the listing and the read: no owner file, not a holder we cannot read.
+    if ((e as NodeJS.ErrnoException).code === "ENOENT") return null;
+    log.debug(`install lock owner ${join(lockDir, name)} cannot be read (${errorMessage(e)}); treating it as held.`);
+    return { kind: "unreadable", token };
+  }
+  try {
+    return { kind: "live", token, owner: JSON.parse(raw) as LockOwner };
+  } catch (e) {
+    log.debug(`install lock owner ${join(lockDir, name)} does not parse (${errorMessage(e)}); treating it as stale.`);
+    return { kind: "corrupt", token };
   }
 }
 
@@ -77,9 +98,19 @@ function pidAlive(pid: number): boolean {
   }
 }
 
-function lockIsStale(owner: LockOwner): boolean {
-  if (owner.host === hostname() && !pidAlive(owner.pid)) return true;
-  return Date.now() - owner.startedAt > STALE_LOCK_MS;
+function lockIsStale(holder: LockHolder | null): boolean {
+  if (holder === null) return true;
+  switch (holder.kind) {
+    case "corrupt":
+      return true;
+    case "unreadable":
+      return false;
+    case "live": {
+      const { owner } = holder;
+      if (owner.host === hostname() && !pidAlive(owner.pid)) return true;
+      return Date.now() - owner.startedAt > STALE_LOCK_MS;
+    }
+  }
 }
 
 /**
@@ -244,18 +275,21 @@ export async function acquireInstallLock(
     if (outcome === "impossible") return () => {};
 
     const holder = readOwner(lockDir);
-    if ((holder === null || lockIsStale(holder)) && clearLock(lockDir, holder?.token ?? null)) {
+    if (lockIsStale(holder) && clearLock(lockDir, holder?.token ?? null)) {
       continue;
     }
+    const held = holder?.kind === "live" ? holder.owner : null;
 
     if (!announced) {
       announced = true;
+      // The default wait is hours long, so the way out is stated up front rather than after the timeout (S4-F2).
       log.warn(
-        `Another \`kesha install\`${holder ? ` (pid ${holder.pid})` : ""} is using ` +
-          `${dirname(binPath)}; waiting for it to finish...`,
+        `Another \`kesha install\`${held ? ` (pid ${held.pid} on ${held.host})` : ""} is using ` +
+          `${dirname(binPath)}; waiting for it to finish... If no install is running, delete ` +
+          `${lockDir} and re-run.`,
       );
     }
-    if (Date.now() + delay >= deadline) throw waitTimedOut(binPath, holder, maxWaitMs);
+    if (Date.now() + delay >= deadline) throw waitTimedOut(binPath, held, maxWaitMs);
     await Bun.sleep(delay);
     delay = Math.min(delay * 2, POLL_MAX_MS);
   }