@drakulavich/kesha-voice-kit 1.2.1 → 1.3.0

package/README.md

@@ -83,7 +83,9 @@ Stdout: transcript. Stderr: errors. Pipe-friendly. Also available as `parakeet`
 Kesha speaks back via Kokoro-82M (English) and Piper (Russian). Voice is auto-picked from the input text's language — `en` routes to Kokoro, `ru` to Piper. Pass `--voice` to override.
 
 ```bash
-brew install espeak-ng              # one-time system dep (macOS — apt/choco elsewhere)
+brew install espeak-ng              # one-time system dep — macOS
+# Linux:   sudo apt install espeak-ng
+# Windows: choco install espeak-ng  (puts libespeak-ng.dll on PATH)
 kesha install --tts                 # ~390MB (Kokoro + Piper RU, opt-in)
 kesha say "Hello, world" > hello.wav
 kesha say "Привет, мир" > privet.wav    # auto-routes to ru-denis
@@ -98,16 +100,16 @@ Output format: WAV mono float32 (24 kHz for Kokoro, 22.05 kHz for Piper). OGG/Op
 **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: `macos-<identifier-or-language>` routes to `AVSpeechSynthesizer`. Zero install, any of the 180+ voices already on your Mac.
 
-### macOS system voices (preview)
+### macOS system voices
 
-`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).
+`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. The sidecar binary ships alongside `kesha-engine` on darwin-arm64 releases (#141); `kesha install` places both in `~/.cache/kesha/bin/`.
 
 ```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
+kesha say --list-voices | grep ^macos-                                       # discover installed voices
+kesha say --voice macos-com.apple.voice.compact.en-US.Samantha "Hello" > 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.

package/package.json

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

package/src/cli.ts

@@ -4,7 +4,8 @@ import { defineCommand, runMain } from "citty";
 import { detect } from "tinyld";
 import { transcribe } from "./lib";
 import { downloadEngine } from "./engine-install";
-import { detectAudioLanguageEngine, detectTextLanguageEngine } from "./engine";
+import { detectAudioLanguageEngine, detectTextLanguageEngine, getEngineBinPath } from "./engine";
+import { readStarSeen, shouldShowStarPrompt, writeStarSeen } from "./star";
 import type { LangDetectResult } from "./engine";
 import { log } from "./log";
 import { say, SayError } from "./say";
@@ -50,6 +51,24 @@ function resolveBackendFlag(coreml: boolean, onnx: boolean): string | undefined
 }
 
 async function askForStar() {
+  // Gate on major-or-minor bump only — patch releases and re-installs of the
+  // same version shouldn't nag. First-ever install (no marker) still prompts.
+  const currentVersion = typeof pkg.version === "string" ? pkg.version : null;
+  if (!currentVersion) return;
+  const binPath = getEngineBinPath();
+  const seen = readStarSeen(binPath);
+  if (!shouldShowStarPrompt(currentVersion, seen)) {
+    return;
+  }
+  // Record the version up front so a single run never prompts twice, even
+  // if the gh subprocess below throws.
+  try {
+    writeStarSeen(binPath, currentVersion);
+  } catch {
+    // Non-fatal — falling through to the prompt is still OK, just means we
+    // may nag again on the next install if the write failed for IO reasons.
+  }
+
   const gh = Bun.which("gh");
   if (!gh) {
     log.info("\nIf you enjoy Kesha Voice Kit, consider starring the repo:");

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,6 +41,46 @@ 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;
+  }
+
+  await streamResponseToFile(res, sidecarPath, "say-avspeech sidecar");
+  chmodSync(sidecarPath, 0o755);
+  log.success("AVSpeech sidecar installed (macOS voices available).");
+}
+
 export interface InstallOptions {
   /** Also install Kokoro TTS models. Requires espeak-ng on PATH. */
   tts?: boolean;
@@ -69,6 +109,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) {
@@ -100,6 +147,7 @@ export async function downloadEngine(
     chmodSync(binPath, 0o755);
     writeInstalledEngineVersion(binPath, engineVersion);
     log.success(`Engine binary downloaded (v${engineVersion}).`);
+    await downloadAVSpeechSidecar(binPath, engineVersion);
   }
 
   if (backend) {

package/src/star.ts

@@ -0,0 +1,57 @@
+import { existsSync, readFileSync, writeFileSync } from "fs";
+
+/**
+ * Version-bump gate for the "star the repo" prompt in `kesha install`.
+ *
+ * Prompts are valuable on first install and on meaningful upgrades (new
+ * features) but annoying on patch-only bumps. This module persists the
+ * last-seen version to a marker file next to the engine binary and only
+ * returns true on a major-or-minor bump.
+ */
+export function starSeenPath(binPath: string): string {
+  return `${binPath}.star-seen`;
+}
+
+export function readStarSeen(binPath: string): string | null {
+  try {
+    const v = readFileSync(starSeenPath(binPath), "utf-8").trim();
+    return v.length > 0 ? v : null;
+  } catch {
+    return null;
+  }
+}
+
+export function writeStarSeen(binPath: string, version: string): void {
+  writeFileSync(starSeenPath(binPath), `${version}\n`);
+}
+
+function parseMajorMinor(v: string): [number, number] | null {
+  const parts = v.split(".");
+  if (parts.length < 2) return null;
+  const major = Number(parts[0]);
+  const minor = Number(parts[1]);
+  if (!Number.isFinite(major) || !Number.isFinite(minor)) return null;
+  return [major, minor];
+}
+
+/**
+ * Returns true iff `current` represents a major-or-minor bump over `seen`.
+ * - `seen === null` → true (first install, always prompt once).
+ * - Same or downgraded version → false.
+ * - Patch-only bump → false (annoying on every install).
+ * - Unparseable either side → false (don't nag when we can't reason).
+ */
+export function shouldShowStarPrompt(current: string, seen: string | null): boolean {
+  if (seen === null) return true;
+  const c = parseMajorMinor(current);
+  const s = parseMajorMinor(seen);
+  if (!c || !s) return false;
+  if (c[0] > s[0]) return true;
+  if (c[0] === s[0] && c[1] > s[1]) return true;
+  return false;
+}
+
+/** True when a star-seen marker already exists for this install. */
+export function hasStarMarker(binPath: string): boolean {
+  return existsSync(starSeenPath(binPath));
+}