@drakulavich/kesha-voice-kit 1.10.1 → 1.12.0

package/README.md

@@ -60,52 +60,29 @@ Stdout: transcript. Stderr: errors. Pipe-friendly. Also available as `parakeet`
 
 For long / silence-heavy audio, use `--vad` (auto-on past 120 s). Details: [docs/vad.md](docs/vad.md).
 
-## Text-to-speech
-
-Kesha speaks back via Kokoro-82M (English) and Vosk-TTS (Russian) — voice auto-picks from the text's language:
+**Speaker diarization** (darwin-arm64, post-v1.12.0):
 
 ```bash
-kesha install --tts                      # ~990MB (Kokoro + Vosk-TTS RU, opt-in)
-kesha say "Hello, world" > hello.wav
-kesha say "Привет, мир" > privet.wav     # auto-routes (Milena on darwin, ru-vosk-m02 elsewhere)
+kesha install --diarize                        # one-time, ~245MB Sortformer model
+kesha --json --vad --speakers meeting.m4a > out.json
+jq '.[0].segments[] | "\(.speaker)\t\(.text)"' out.json
 ```
 
-**Russian abbreviations** (`ru-vosk-*` voices):
-
-```bash
-# Auto-detect on by default — ФСБ reads as "эф-эс-бэ"
-kesha say --voice ru-vosk-m02 'ФСБ объявила решение.'
+Each segment gets a `speaker` integer (cluster ID, stable within one file). Linux / Windows: `--speakers` returns a clear "currently darwin-arm64 only" error — see [#199](https://github.com/drakulavich/kesha-voice-kit/issues/199).
 
-# Force a literal reading (Vosk reads as "фсб")
-kesha say --voice ru-vosk-m02 --no-expand-abbrev 'ФСБ.'
-
-# Explicit SSML control (overrides the rule and the stop-list)
-kesha say --voice ru-vosk-m02 --ssml \
-  '<speak><say-as interpret-as="characters">КОТ</say-as></speak>'
-```
-
-Detection rule: auto-expand fires when the token cannot be pronounced as a natural Russian syllable — length ≤ 2 (ИП, ЕС), 0 vowels (ФСБ, СНГ), 2+ consecutive vowels (ОАЭ), or 2+ consecutive consonants (США, ЦСКА). Tokens with strict CVC/CVCV alternation pass through (ВОЗ → "воз", НАТО → "нато", ОПЕК → "опек"). Small stop-list for common short words (ОН, МЫ, ВЫ, КАК, ЧТО, …) and Ъ/Ь-containing tokens are always skipped. See [#232](https://github.com/drakulavich/kesha-voice-kit/issues/232).
+## Text-to-speech
 
-**English acronyms** (`en-*` voices, Kokoro-82M):
+Kesha speaks back via Kokoro-82M (English) and Vosk-TTS (Russian) — voice auto-picks from the text's language:
 
 ```bash
-# Auto-expand on by default — FBI reads as "ef bee eye"
-kesha say --voice en-am_michael 'The FBI is investigating.'
-
-# Force a literal reading (Kokoro fuses unknown caps tokens to one syllable)
-kesha say --voice en-am_michael --no-expand-abbrev 'FBI.'
-
-# Explicit SSML control (overrides the rule and the stop-list)
-kesha say --voice en-am_michael --ssml \
-  '<speak><say-as interpret-as="characters">NASA</say-as></speak>'
+kesha install --tts                      # ~990MB (Kokoro + Vosk-TTS RU, opt-in)
+kesha say "Hello, world" > hello.wav
+kesha say "Привет, мир" > privet.wav     # auto-routes (Milena on darwin, ru-vosk-m02 elsewhere)
 ```
 
-Three-table mechanism:
-- **Letter-spell** — uppercase Latin tokens 2–5 chars (no digits, no mixed case) get expanded letter-by-letter (FBI → "ef bee eye"). Disable with `--no-expand-abbrev`.
-- **`STOP_LIST`** (30 entries) — natural-English caps words pass through unchanged: NASA, NATO, AIDS, OPEC, IKEA, ASCII, NAFTA, LASER, RADAR, SCUBA + emphatic length-2 caps (OK, NO, GO, IT, IS, AS, AT, BY, IN, ON, OR, OF, TO, WE, US, MY, ME, HE, BE, DO).
-- **`IPA_LEXICON`** (20 entries) — case-sensitive token → IPA-phoneme map that bypasses G2P entirely. Covers all-caps acronyms with industry pronunciations (EPAM, JSON, JPEG, SQL, ASAP, GIF, CRUD, JWT) AND mixed-case proper nouns (Anthropic, Microsoft, Claude, NVIDIA, Kubernetes, PostgreSQL, GraphQL, Linux, Tokio, macOS, Granola, OAuth). IPA hits fire even with `--no-expand-abbrev` — they're intent-explicit, parallel to `<say-as>`.
+**Russian abbreviations** (`ru-vosk-*`): all-uppercase Cyrillic 2-5-char tokens auto-expand letter-by-letter when not pronounceable as a Russian syllable (ФСБ → "эф-эс-бэ", ВОЗ → "воз"). Disable with `--no-expand-abbrev`. See [docs/tts.md#russian-abbreviation-auto-expansion](docs/tts.md#russian-abbreviation-auto-expansion).
 
-Override per-token via SSML `<say-as interpret-as="characters">…</say-as>` (always letter-spells via the table). See [#244](https://github.com/drakulavich/kesha-voice-kit/issues/244).
+**English acronyms** (`en-*`, Kokoro): three-table mechanism (letter-spell rule + STOP_LIST + IPA_LEXICON) auto-expands FBI → "ef bee eye" and gives EPAM/JSON/Anthropic the right IPA. Disable letter-spell with `--no-expand-abbrev`. See [docs/tts.md#english-acronym-auto-expansion](docs/tts.md#english-acronym-auto-expansion).
 
 **Russian word stress** (`ru-vosk-*` voices):
 

package/SKILL.md

@@ -54,6 +54,16 @@ jq '.[0].segments' voice.timestamps.json
 
 Each segment has `start`, `end`, and `text` fields. `--timestamps` is available for machine-readable output (`--json`, `--toon`, or `--format json`).
 
+**Speaker diarization** (darwin-arm64, post-v1.12.0). Add `--speakers` to label each segment with a cluster ID — useful for transcribing multi-person calls / meetings:
+
+```bash
+kesha install --diarize                                  # one-time, ~245MB
+kesha --json --vad --speakers meeting.m4a > out.json
+jq '.[0].segments[] | "\(.speaker)\t\(.text)"' out.json
+```
+
+Each `segment.speaker` is a number (cluster id, stable within one file). On Linux / Windows the engine returns a clear "currently darwin-arm64 only" error — see [#199](https://github.com/drakulavich/kesha-voice-kit/issues/199).
+
 **Formats:** .ogg, .opus, .mp3, .m4a, .wav, .flac, .webm — decoded via symphonia, no ffmpeg required.
 
 **Other output modes:**
@@ -84,9 +94,9 @@ kesha say "Hi" --format ogg-opus --bitrate 16000 --out tiny.ogg            # tin
 
 Format is also inferred from `--out` extension (`.ogg` / `.opus` / `.oga` → OGG/Opus). `--bitrate` (6 000–510 000 bps) and `--sample-rate` (8 000 / 12 000 / 16 000 / 24 000 / 48 000 Hz) tune the encoder.
 
-**Russian abbreviation handling** (`ru-vosk-*` only): all-uppercase Cyrillic tokens (length 2–5) auto-expand letter-by-letter when the token cannot be pronounced as a natural Russian syllable — `ФСБ объявила` → `эф-эс-бэ объявила`. Tokens with strict CVC/CVCV alternation pass through (ВОЗ → "воз", НАТО → "нато"). Disable per call with `--no-expand-abbrev`. Override per-token via SSML `<say-as interpret-as="characters">…</say-as>` (always wins, even with `--no-expand-abbrev`). Stop-list for common short words (ОН, МЫ, ВЫ, КАК, ЧТО) prevents false positives. Closes [#232](https://github.com/drakulavich/kesha-voice-kit/issues/232).
+**Russian abbreviations** (`ru-vosk-*`): all-uppercase Cyrillic 2-5-char tokens auto-expand letter-by-letter when not pronounceable as a Russian syllable (ФСБ → "эф-эс-бэ", ВОЗ → "воз"). Disable with `--no-expand-abbrev`. See [docs/tts.md#russian-abbreviation-auto-expansion](docs/tts.md#russian-abbreviation-auto-expansion).
 
-**English acronym handling** (`en-*` Kokoro-82M only). Three tables: (1) **letter-spell** for uppercase 2–5-char tokens not on the stop-list (FBI → "ef bee eye", HTTP → "aitch tee tee pee"); (2) **`STOP_LIST`** (30 entries) — natural-English caps words pass through (NASA, NATO, AIDS, OPEC, IKEA, ASCII, NAFTA, LASER, RADAR, SCUBA + 20 emphatic length-2 caps); (3) **`IPA_LEXICON`** (20 entries) — case-sensitive token → IPA-phoneme map that bypasses G2P entirely. Covers industry-pronunciation acronyms (EPAM /ˈiːpæm/, JSON /ˈdʒeɪsən/, JPEG, SQL, ASAP, GIF, CRUD, JWT, OAuth) AND mixed-case proper nouns (Anthropic /ænˈθrɒpɪk/, Microsoft, Claude, NVIDIA, Kubernetes, PostgreSQL, GraphQL, Linux, Tokio, macOS, Granola). Disable letter-spell with `--no-expand-abbrev` — IPA hits still fire (intent-explicit). Override per-token via SSML `<say-as interpret-as="characters">…</say-as>` (always wins). Closes [#244](https://github.com/drakulavich/kesha-voice-kit/issues/244).
+**English acronyms** (`en-*`, Kokoro): three-table mechanism (letter-spell rule + STOP_LIST + IPA_LEXICON) auto-expands FBI → "ef bee eye" and gives EPAM/JSON/Anthropic the right IPA. Disable letter-spell with `--no-expand-abbrev`. See [docs/tts.md#english-acronym-auto-expansion](docs/tts.md#english-acronym-auto-expansion).
 
 **Russian word stress** (`ru-vosk-*` only): `<emphasis>сл+ово</emphasis>` shifts stress to the vowel marked with `+`. `<emphasis level="none">сл+ово</emphasis>` strips the `+` (cancel inherited emphasis). Other voices (`en-*`, `macos-*`) silently strip the `+` and warn once per process. Auto-stress dictionary not provided — caller writes the `+` manually. Closes [#233](https://github.com/drakulavich/kesha-voice-kit/issues/233).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/kesha-voice-kit",
-  "version": "1.10.1",
+  "version": "1.12.0",
   "description": "Open-source voice toolkit. Speech-to-text (25 langs, ~19x faster than Whisper on Apple Silicon, ONNX fallback on CPU), text-to-speech (Kokoro + Vosk-TTS + ~180 macOS system voices, SSML), voice-activity detection, language detection (107 langs). Rust engine, OpenClaw skill.",
   "type": "module",
   "bin": {
@@ -30,7 +30,7 @@
     ]
   },
   "keshaEngine": {
-    "version": "1.10.0"
+    "version": "1.12.0"
   },
   "scripts": {
     "test": "bun test",

package/src/cli/install.ts

@@ -1,7 +1,7 @@
 import { defineCommand } from "citty";
 import { downloadEngine } from "../engine-install";
 import { getEngineBinPath } from "../engine";
-import { readStarSeen, shouldShowStarPrompt, writeStarSeen } from "../star";
+import { maybeAskForStar } from "../star";
 import { log } from "../log";
 
 interface InstallCommandArgs {
@@ -10,6 +10,7 @@ interface InstallCommandArgs {
   "no-cache": boolean;
   tts: boolean;
   vad: boolean;
+  diarize: boolean;
 }
 
 const pkg = await Bun.file(new URL("../../package.json", import.meta.url)).json();
@@ -24,44 +25,24 @@ function resolveBackendFlag(coreml: boolean, onnx: boolean): string | undefined
   return 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:");
-    log.info("  https://github.com/drakulavich/kesha-voice-kit");
-    return;
+async function performInstall(
+  noCache: boolean,
+  backend?: string,
+  tts = false,
+  vad = false,
+  diarize = false,
+) {
+  if (diarize && !(process.platform === "darwin" && process.arch === "arm64")) {
+    log.error(
+      "--diarize is currently darwin-arm64 only " +
+        "(see https://github.com/drakulavich/kesha-voice-kit/issues/199).",
+    );
+    process.exit(1);
   }
-  const authCheck = Bun.spawnSync([gh, "auth", "status"], { stdout: "ignore", stderr: "ignore" });
-  if (authCheck.exitCode !== 0) return;
-  const starred = Bun.spawnSync([gh, "api", "user/starred/drakulavich/kesha-voice-kit"], { stdout: "ignore", stderr: "ignore" });
-  if (starred.exitCode === 0) return; // already starred
-  log.info("\n⭐ If you enjoy Kesha Voice Kit, star it on GitHub:");
-  log.info("  https://github.com/drakulavich/kesha-voice-kit");
-  log.info('  Or run: gh api -X PUT /user/starred/drakulavich/kesha-voice-kit');
-}
-
-async function performInstall(noCache: boolean, backend?: string, tts = false, vad = false) {
   try {
-    await downloadEngine(noCache, backend, { tts, vad });
-    await askForStar();
+    await downloadEngine(noCache, backend, { tts, vad, diarize });
+    const currentVersion = typeof pkg.version === "string" ? pkg.version : null;
+    await maybeAskForStar(getEngineBinPath(), currentVersion, log);
   } catch (err: unknown) {
     const message = err instanceof Error ? err.message : String(err);
     log.error(message);
@@ -100,9 +81,14 @@ export const installCommand = defineCommand({
       description: "Also install Silero VAD (~2.3MB) for long-audio preprocessing",
       default: false,
     },
+    diarize: {
+      type: "boolean",
+      description: "Also install the Sortformer streaming-diarization model (~245MB, darwin-arm64 only — #199)",
+      default: false,
+    },
   },
   async run({ args }: { args: InstallCommandArgs }) {
     const backend = resolveBackendFlag(args.coreml, args.onnx);
-    await performInstall(args["no-cache"], backend, args.tts, args.vad);
+    await performInstall(args["no-cache"], backend, args.tts, args.vad, args.diarize);
   },
 });

package/src/cli/main.ts

@@ -24,6 +24,7 @@ interface MainCommandArgs {
   vad: boolean;
   "no-vad": boolean;
   timestamps: boolean;
+  speakers: boolean;
   format?: string;
   lang?: string;
 }
@@ -63,6 +64,11 @@ export const mainCommand = defineCommand({
       description: "Include timestamped transcript segments in JSON/TOON output",
       default: false,
     },
+    speakers: {
+      type: "boolean",
+      description: "Include speaker labels in transcript segments. Requires --json / --toon / --format json. Implies --timestamps. Currently darwin-arm64 only (#199).",
+      default: false,
+    },
     verbose: {
       type: "boolean",
       description: "Show language detection details",
@@ -109,6 +115,10 @@ export const mainCommand = defineCommand({
       log.error("--timestamps requires --json, --toon, or --format json.");
       process.exit(2);
     }
+    if (args.speakers && !(args.json || args.toon || args.format === "json")) {
+      log.error("--speakers requires --json, --toon, or --format json.");
+      process.exit(2);
+    }
     const vadMode = args.vad ? "on" : args["no-vad"] ? "off" : "auto";
 
     if (files.length === 0) {
@@ -127,7 +137,7 @@ export const mainCommand = defineCommand({
         // Run audio lang-id and transcription concurrently.
         const [audioResult, transcript] = await Promise.all([
           wantsLangId ? detectAudioLanguageEngine(file) : Promise.resolve(null),
-          transcribeWithSegments(file, { vad: vadMode, timestamps: args.timestamps }),
+          transcribeWithSegments(file, { vad: vadMode, timestamps: args.timestamps, speakers: args.speakers }),
         ]);
         const { text, segments } = transcript;
 

package/src/engine-install.ts

@@ -35,36 +35,72 @@ function getEngineBinaryName(): string {
 }
 
 /**
- * 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 +
- * Vosk-TTS.
+ * One sidecar's identity. Each shipped Swift sidecar is described by an
+ * entry in `SIDECARS`; the helper below loops over them. Centralising the
+ * spec keeps the AVSpeech (#141) and diarize (#199) install paths in
+ * lockstep — adding a third sidecar is one entry, not a new function.
  */
-async function downloadAVSpeechSidecar(binPath: string, engineVersion: string): Promise<void> {
+interface SidecarSpec {
+  /** Filename written next to the engine binary. The Rust runtime probes
+   * this exact name (sometimes a list — see diarize::sidecar_path). */
+  fileBasename: string;
+  /** Release asset name. Often equals fileBasename, but AVSpeech writes
+   * `say-avspeech` while the asset is `say-avspeech-darwin-arm64`. */
+  assetName: string;
+  /** Human-readable name in log messages. */
+  displayName: string;
+  /** Trailing hint on success: "AVSpeech sidecar installed (<hint>)." */
+  availableHint: string;
+  /** Trailing hint on any failure path: "...; <hint>." */
+  unavailableHint: string;
+}
+
+const SIDECARS: SidecarSpec[] = [
+  {
+    fileBasename: "say-avspeech",
+    assetName: "say-avspeech-darwin-arm64",
+    displayName: "AVSpeech sidecar",
+    availableHint: "macOS voices available",
+    unavailableHint: "macos-* voices unavailable",
+  },
+  {
+    fileBasename: "kesha-diarize-darwin-arm64",
+    assetName: "kesha-diarize-darwin-arm64",
+    displayName: "Diarization sidecar",
+    availableHint: "--speakers available",
+    unavailableHint: "--speakers unavailable",
+  },
+];
+
+/**
+ * Fetch a single Swift sidecar and place it next to the engine binary on
+ * darwin-arm64. Best-effort: 404s (older engine versions predate this
+ * sidecar) and network errors log a warning and return — the corresponding
+ * feature simply won't be available. The user keeps everything else.
+ */
+async function downloadSidecar(
+  spec: SidecarSpec,
+  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`;
+  const sidecarPath = join(dirname(binPath), spec.fileBasename);
+  const url = `https://github.com/${GITHUB_REPO}/releases/download/v${engineVersion}/${spec.assetName}`;
 
   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.`,
+      `Could not fetch ${spec.displayName} (${e instanceof Error ? e.message : e}); ${spec.unavailableHint}.`,
     );
     return;
   }
 
   if (!res.ok) {
     log.warn(
-      `AVSpeech sidecar not in release v${engineVersion} (HTTP ${res.status}); macos-* voices unavailable.`,
+      `${spec.displayName} not in release v${engineVersion} (HTTP ${res.status}); ${spec.unavailableHint}.`,
     );
     return;
   }
@@ -72,17 +108,17 @@ async function downloadAVSpeechSidecar(binPath: string, engineVersion: string):
   // 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.
+  // `await Promise.all(sidecarPromises)` 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");
+    await streamResponseToFile(res, sidecarPath, spec.displayName);
     chmodSync(sidecarPath, 0o755);
-    log.success("AVSpeech sidecar installed (macOS voices available).");
+    log.success(`${spec.displayName} installed (${spec.availableHint}).`);
   } catch (e) {
     log.warn(
-      `AVSpeech sidecar install failed (${e instanceof Error ? e.message : e}); macos-* voices unavailable.`,
+      `${spec.displayName} install failed (${e instanceof Error ? e.message : e}); ${spec.unavailableHint}.`,
     );
   }
 }
@@ -92,6 +128,9 @@ export interface InstallOptions {
   tts?: boolean;
   /** Also install Silero VAD model for long-audio preprocessing. */
   vad?: boolean;
+  /** Also install the Sortformer streaming-diarization model (~245MB,
+   * darwin-arm64 only — see #199). */
+  diarize?: boolean;
 }
 
 export async function downloadEngine(
@@ -117,13 +156,14 @@ 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);
-    }
+    // Top up any sidecars missing from this cached install. Pre-#141 / pre-#199
+    // engines never shipped them, so a cache-valid binary may still need
+    // fetching. Run independent fetches concurrently — same shape as the
+    // cold path below.
+    const missing = SIDECARS.filter(
+      (s) => !existsSync(join(dirname(binPath), s.fileBasename)),
+    );
+    await Promise.all(missing.map((s) => downloadSidecar(s, binPath, engineVersion)));
   } else {
     // Log why we're downloading — helps diagnose surprising re-downloads.
     if (existsSync(binPath) && installedVersion && installedVersion !== engineVersion) {
@@ -136,32 +176,34 @@ 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);
+    // Kick off all sidecar fetches concurrently with the engine fetch. They
+    // target independent github.com release assets, so overlapping the HTTP
+    // round-trips saves ~15-30s on a cold install. Each sidecar is
+    // best-effort (404 on older engines, warn + continue) so a failure
+    // doesn't cascade into the engine path.
+    const sidecarPromises = SIDECARS.map((s) =>
+      downloadSidecar(s, binPath, engineVersion),
+    );
+    // Defense-in-depth: if the engine fetch throws below, attach no-op
+    // rejection handlers so we don't surface unhandledRejection errors
+    // from sidecar paths whose internal try/catch ever drifts. Logs from
+    // sidecars whose own work is still in flight will print when they
+    // complete; the engine error is what the user needs to see now.
+    const muteSidecarRejections = () =>
+      sidecarPromises.forEach((p) => p.catch(() => {}));
 
     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(() => {});
+      muteSidecarRejections();
       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(() => {});
+      muteSidecarRejections();
       throw new Error(
         `Failed to download engine binary (HTTP ${res.status})\n  Fix: Check https://github.com/${GITHUB_REPO}/releases for available versions`,
       );
@@ -171,7 +213,7 @@ export async function downloadEngine(
     chmodSync(binPath, 0o755);
     writeInstalledEngineVersion(binPath, engineVersion);
     log.success(`Engine binary downloaded (v${engineVersion}).`);
-    await sidecarPromise;
+    await Promise.all(sidecarPromises);
   }
 
   if (backend) {
@@ -189,6 +231,7 @@ export async function downloadEngine(
     ...(noCache ? ["--no-cache"] : []),
     ...(options.tts ? ["--tts"] : []),
     ...(options.vad ? ["--vad"] : []),
+    ...(options.diarize ? ["--diarize"] : []),
   ];
   const proc = Bun.spawnSync([binPath, ...installArgs], {
     stdout: "pipe",

package/src/engine.ts

@@ -1,8 +1,22 @@
 import { join } from "path";
 import { homedir } from "os";
-import { existsSync } from "fs";
+import { existsSync, statSync } from "fs";
 import { log } from "./log";
 
+/**
+ * Capability-flag string surfaced via `kesha-engine --capabilities-json`. Single
+ * source of truth so the engine, the TS CLI gate, and the integration tests
+ * can't drift. Mirrors `rust/src/transcribe/mod.rs::TRANSCRIBE_SEGMENTS_FEATURE`.
+ */
+export const TRANSCRIBE_SEGMENTS_FEATURE = "transcribe.segments";
+
+/**
+ * Capability-flag string for speaker diarization. Engine advertises this only
+ * on darwin-arm64 builds with the `system_diarize` cargo feature (#199).
+ * Mirrors `rust/src/transcribe/mod.rs::TRANSCRIBE_DIARIZE_FEATURE`.
+ */
+export const TRANSCRIBE_DIARIZE_FEATURE = "transcribe.diarize";
+
 export interface LangDetectResult {
   code: string;
   confidence: number;
@@ -12,6 +26,8 @@ export interface TranscriptionSegment {
   start: number;
   end: number;
   text: string;
+  /** Speaker cluster id when `--speakers` was requested (#199). */
+  speaker?: number;
 }
 
 export interface TranscriptionOutput {
@@ -62,6 +78,9 @@ export type VadMode = "auto" | "on" | "off";
 
 export interface TranscribeEngineOptions {
   vad?: VadMode;
+  /** Request speaker labels in transcript segments. Requires the engine to
+   * advertise `transcribe.diarize` (darwin-arm64 only — see #199). */
+  speakers?: boolean;
 }
 
 export async function transcribeEngine(
@@ -93,11 +112,9 @@ function parseTranscriptionOutput(stdout: string): TranscriptionOutput {
     ) {
       throw new Error("Invalid transcription segment returned by kesha-engine");
     }
-    return {
-      start: s.start,
-      end: s.end,
-      text: s.text,
-    };
+    const out: TranscriptionSegment = { start: s.start, end: s.end, text: s.text };
+    if (typeof s.speaker === "number") out.speaker = s.speaker;
+    return out;
   });
 
   return { text: parsed.text, segments };
@@ -108,7 +125,7 @@ export async function transcribeEngineWithSegments(
   opts: TranscribeEngineOptions = {},
 ): Promise<TranscriptionOutput> {
   const caps = await getEngineCapabilities();
-  if (!caps?.features.includes("transcribe.segments")) {
+  if (!caps?.features.includes(TRANSCRIBE_SEGMENTS_FEATURE)) {
     throw new Error(
       "Timestamped segments require a newer kesha-engine. Run `kesha install` after upgrading Kesha Voice Kit.",
     );
@@ -117,6 +134,15 @@ export async function transcribeEngineWithSegments(
   const args = ["transcribe", audioPath, "--json"];
   if (opts.vad === "on") args.push("--vad");
   else if (opts.vad === "off") args.push("--no-vad");
+  if (opts.speakers) {
+    if (!caps.features.includes(TRANSCRIBE_DIARIZE_FEATURE)) {
+      throw new Error(
+        "speaker diarization is currently darwin-arm64 only " +
+          "(see https://github.com/drakulavich/kesha-voice-kit/issues/199)",
+      );
+    }
+    args.push("--speakers");
+  }
   const { stdout, stderr, exitCode } = await runEngine(args);
   if (exitCode !== 0) {
     throw new Error(stderr || `kesha-engine exited with code ${exitCode}`);
@@ -162,20 +188,33 @@ export interface EngineCapabilities {
 }
 
 let cachedEngineCapabilities:
-  | { binPath: string; capabilities: EngineCapabilities }
+  | { binPath: string; mtime: number; capabilities: EngineCapabilities }
   | null = null;
 
 export async function getEngineCapabilities(): Promise<EngineCapabilities | null> {
   const binPath = getEngineBinPath();
-  if (cachedEngineCapabilities?.binPath === binPath) {
+  // Cache key includes `mtimeMs` so the cache invalidates when `kesha
+  // install` overwrites the binary in-place within a single long-lived
+  // process (#248). `statSync` throws on missing-file; the catch returns
+  // `null` — same effect as the previous explicit `isEngineInstalled()`
+  // pre-flight, one fewer redundant fs call.
+  let mtime: number;
+  try {
+    mtime = statSync(binPath).mtimeMs;
+  } catch {
+    return null;
+  }
+  if (
+    cachedEngineCapabilities?.binPath === binPath &&
+    cachedEngineCapabilities.mtime === mtime
+  ) {
     return cachedEngineCapabilities.capabilities;
   }
-  if (!existsSync(binPath)) return null;
   const { stdout, exitCode } = await runEngine(["--capabilities-json"]);
   if (exitCode !== 0) return null;
   try {
     const capabilities = JSON.parse(stdout) as EngineCapabilities;
-    cachedEngineCapabilities = { binPath, capabilities };
+    cachedEngineCapabilities = { binPath, mtime, capabilities };
     return capabilities;
   } catch {
     return null;

package/src/lib.ts

@@ -44,7 +44,7 @@ export async function transcribe(
   return internalTranscribe(audioPath, { ...options, silent: true });
 }
 
-export async function transcribeWithSegments(
+export async function transcribeWithTimestamps(
   audioPath: string,
   options: TranscribeOptions = {},
 ) {
@@ -58,3 +58,10 @@ export async function transcribeWithSegments(
     silent: true,
   });
 }
+
+/**
+ * @deprecated Renamed to {@link transcribeWithTimestamps} (#248). The old
+ * name shipped briefly in v1.9.0; this alias keeps existing imports working
+ * for one minor-version cycle. Will be removed in v1.12.0.
+ */
+export const transcribeWithSegments = transcribeWithTimestamps;

package/src/star.ts

@@ -55,3 +55,79 @@ export function shouldShowStarPrompt(current: string, seen: string | null): bool
 export function hasStarMarker(binPath: string): boolean {
   return existsSync(starSeenPath(binPath));
 }
+
+/**
+ * Prompt the user to star the repo if and only if `shouldShowStarPrompt`
+ * agrees (first install + major-or-minor bumps, never on patch). Records
+ * the prompt against the current version up front so a single run never
+ * prompts twice — failures from the gh subprocess below don't reopen the
+ * gate. Shared by `kesha install` and `kesha status` so opt-in installs
+ * (`--tts`, `--diarize`) and `status` reuse the same marker; a user who
+ * saw the prompt on the base install won't see it again on the opt-in or
+ * the status check.
+ *
+ * No-ops when the gate says skip, when `currentVersion` is null, or when
+ * the user has already starred. When `gh` is missing or unauthenticated,
+ * a basic prompt is still printed (so the marker write isn't a silent
+ * slot consumption).
+ *
+ * `shims` lets tests inject deterministic `which` / `spawn` implementations.
+ * Production callers leave it undefined; the defaults route through Bun's
+ * built-ins. Bun.which() caches PATH at process start so swapping
+ * process.env.PATH in tests doesn't work — the shim is the supported way
+ * to fake gh's presence and authentication state from a unit test.
+ */
+export async function maybeAskForStar(
+  binPath: string,
+  currentVersion: string | null,
+  log: { info: (msg: string) => void },
+  shims?: {
+    which?: (name: string) => string | null;
+    spawn?: (cmd: string[]) => { exitCode: number | null };
+  },
+): Promise<void> {
+  const which = shims?.which ?? ((n: string) => Bun.which(n));
+  const spawn =
+    shims?.spawn ??
+    ((cmd: string[]) =>
+      Bun.spawnSync(cmd, { stdout: "ignore", stderr: "ignore" }));
+  if (!currentVersion) return;
+  const seen = readStarSeen(binPath);
+  if (!shouldShowStarPrompt(currentVersion, seen)) {
+    return;
+  }
+  try {
+    writeStarSeen(binPath, currentVersion);
+  } catch {
+    /* Non-fatal — falling through to the prompt is still OK. */
+  }
+
+  // The marker has been recorded — every path from here that reaches
+  // a `return` without printing would silently consume the user's
+  // once-per-major.minor slot. Only the "already starred" path is
+  // allowed to skip the print, since the consumption is the verification
+  // that they're already supporting the project.
+  const printBasicPrompt = () => {
+    log.info("\nIf you enjoy Kesha Voice Kit, consider starring the repo:");
+    log.info("  https://github.com/drakulavich/kesha-voice-kit");
+  };
+
+  const gh = which("gh");
+  if (!gh) {
+    printBasicPrompt();
+    return;
+  }
+  const authCheck = spawn([gh, "auth", "status"]);
+  if (authCheck.exitCode !== 0) {
+    // gh installed but unauthenticated — we can't check star status, but
+    // we can still nudge with the same basic prompt the no-gh path uses.
+    // Without this, the marker write above silently consumes the slot.
+    printBasicPrompt();
+    return;
+  }
+  const starred = spawn([gh, "api", "user/starred/drakulavich/kesha-voice-kit"]);
+  if (starred.exitCode === 0) return; // already starred — slot consumed by verification
+  log.info("\n⭐ If you enjoy Kesha Voice Kit, star it on GitHub:");
+  log.info("  https://github.com/drakulavich/kesha-voice-kit");
+  log.info('  Or run: gh api -X PUT /user/starred/drakulavich/kesha-voice-kit');
+}

package/src/status.ts

@@ -3,8 +3,11 @@ import { homedir } from "os";
 import { join } from "path";
 import { isEngineInstalled, getEngineBinPath, getEngineCapabilities } from "./engine";
 import { log } from "./log";
+import { maybeAskForStar } from "./star";
 import pc from "picocolors";
 
+const pkg = await Bun.file(new URL("../package.json", import.meta.url)).json();
+
 function humanBytes(bytes: number): string {
   if (bytes < 1024) return `${bytes} B`;
   const units = ["KB", "MB", "GB"];
@@ -86,7 +89,16 @@ export async function showStatus(): Promise<void> {
 
   if (!installed) {
     log.warn('Run "kesha install" to download the engine and models.');
+    return;
   }
+
+  // Star prompt at the very end. Same gate + marker as `kesha install`, so a
+  // user prompted by either path won't be re-prompted by the other within the
+  // same major.minor. Headless `kesha install` (no `gh`, or no tty) leaves no
+  // marker only when the prompt path itself errored out — readStarSeen still
+  // sees the marker in the common case.
+  const currentVersion = typeof pkg.version === "string" ? pkg.version : null;
+  await maybeAskForStar(binPath, currentVersion, log);
 }
 
 function showDiskUsage(binPath: string): void {

package/src/transcribe.ts

@@ -15,6 +15,10 @@ export interface TranscribeOptions {
   vad?: VadMode;
   /** Request timestamped transcript segments from the engine. */
   timestamps?: boolean;
+  /** Request speaker labels in transcript segments (#199). Implies `timestamps`.
+   * Currently darwin-arm64 only — throws when the engine doesn't advertise
+   * `transcribe.diarize`. */
+  speakers?: boolean;
 }
 
 export async function transcribe(audioPath: string, opts: TranscribeOptions = {}): Promise<string> {
@@ -36,8 +40,11 @@ export async function transcribeWithSegments(
     );
   }
 
-  if (opts.timestamps) {
-    return transcribeEngineWithSegments(audioPath, { vad: opts.vad });
+  if (opts.timestamps || opts.speakers) {
+    return transcribeEngineWithSegments(audioPath, {
+      vad: opts.vad,
+      speakers: opts.speakers,
+    });
   }
 
   const text = await transcribeEngine(audioPath, { vad: opts.vad });