@drakulavich/kesha-voice-kit 1.8.2 → 1.10.0

package/README.md

@@ -38,6 +38,7 @@ Air-gapped or behind a corporate mirror? See [docs/model-mirror.md](docs/model-m
 kesha audio.ogg                            # transcribe (plain text)
 kesha --format transcript audio.ogg        # text + language/confidence
 kesha --format json audio.ogg              # full JSON with lang fields
+kesha --json --timestamps audio.ogg        # JSON with timestamped segments
 kesha --toon audio.ogg                     # compact LLM-friendly TOON
 kesha --verbose audio.ogg                  # show language detection details
 kesha --lang en audio.ogg                  # warn if detected language differs
@@ -85,6 +86,27 @@ kesha say --voice ru-vosk-m02 --ssml \
 
 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).
 
+**English acronyms** (`en-*` voices, Kokoro-82M):
+
+```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>'
+```
+
+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>`.
+
+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).
+
 **Russian word stress** (`ru-vosk-*` voices):
 
 ```bash

package/SKILL.md

@@ -76,6 +76,8 @@ Format is also inferred from `--out` extension (`.ogg` / `.opus` / `.oga` → OG
 
 **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).
 
+**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).
+
 **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).
 
 ## Language detection standalone

package/package.json

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

package/src/cli/main.ts

@@ -1,6 +1,6 @@
 import { defineCommand } from "citty";
 import { detect } from "tinyld";
-import { transcribe } from "../lib";
+import { transcribeWithSegments } from "../transcribe";
 import { detectAudioLanguageEngine, detectTextLanguageEngine } from "../engine";
 import type { LangDetectResult } from "../engine";
 import { log } from "../log";
@@ -23,6 +23,7 @@ interface MainCommandArgs {
   debug: boolean;
   vad: boolean;
   "no-vad": boolean;
+  timestamps: boolean;
   format?: string;
   lang?: string;
 }
@@ -57,6 +58,11 @@ export const mainCommand = defineCommand({
       description: "Output results as TOON (compact, LLM-friendly encoding of the same data as --json)",
       default: false,
     },
+    timestamps: {
+      type: "boolean",
+      description: "Include timestamped transcript segments in JSON/TOON output",
+      default: false,
+    },
     verbose: {
       type: "boolean",
       description: "Show language detection details",
@@ -99,6 +105,10 @@ export const mainCommand = defineCommand({
       log.error("--vad and --no-vad are mutually exclusive.");
       process.exit(2);
     }
+    if (args.timestamps && !(args.json || args.toon || args.format === "json")) {
+      log.error("--timestamps requires --json, --toon, or --format json.");
+      process.exit(2);
+    }
     const vadMode = args.vad ? "on" : args["no-vad"] ? "off" : "auto";
 
     if (files.length === 0) {
@@ -114,11 +124,12 @@ export const mainCommand = defineCommand({
     for (const file of files) {
       const startedAt = performance.now();
       try {
-        // Run audio lang-id and transcription concurrently
-        const [audioResult, text] = await Promise.all([
+        // Run audio lang-id and transcription concurrently.
+        const [audioResult, transcript] = await Promise.all([
           wantsLangId ? detectAudioLanguageEngine(file) : Promise.resolve(null),
-          transcribe(file, { vad: vadMode }),
+          transcribeWithSegments(file, { vad: vadMode, timestamps: args.timestamps }),
         ]);
+        const { text, segments } = transcript;
 
         let audioLanguage: LangDetectResult | undefined;
         if (audioResult && audioResult.code) {
@@ -145,14 +156,18 @@ export const mainCommand = defineCommand({
         const mismatchWarning = checkLanguageMismatch(args.lang, lang);
         if (mismatchWarning) log.warn(`${file}: ${mismatchWarning}`);
 
-        results.push({
+        const result: TranscribeResult = {
           file,
           text,
           lang,
           audioLanguage,
           textLanguage: textLanguage ?? (tinyldLang ? { code: tinyldLang, confidence: 0 } : undefined),
           sttTimeMs: Math.round(performance.now() - startedAt),
-        });
+        };
+        if (args.timestamps) {
+          result.segments = segments;
+        }
+        results.push(result);
       } catch (err: unknown) {
         hasError = true;
         const message = err instanceof Error ? err.message : String(err);

package/src/cli/say.ts

@@ -86,7 +86,7 @@ export const sayCommand = defineCommand({
       type: "boolean",
       description:
         "Disable Russian acronym auto-expansion (ВОЗ → 'вэ о зэ') for ru-vosk-* voices. " +
-        "<say-as interpret-as='characters'> still works. No effect for non-ru-vosk voices.",
+        "<say-as interpret-as='characters'> still works. Applies to Russian (ru-vosk-*) and English (en-*) voices.",
     },
     verbose: {
       type: "boolean",

package/src/engine.ts

@@ -8,6 +8,17 @@ export interface LangDetectResult {
   confidence: number;
 }
 
+export interface TranscriptionSegment {
+  start: number;
+  end: number;
+  text: string;
+}
+
+export interface TranscriptionOutput {
+  text: string;
+  segments: TranscriptionSegment[];
+}
+
 const DEFAULT_ENGINE_BIN_PATH = join(homedir(), ".cache", "kesha", "engine", "bin", "kesha-engine");
 
 /**
@@ -67,6 +78,57 @@ export async function transcribeEngine(
   return stdout;
 }
 
+function parseTranscriptionOutput(stdout: string): TranscriptionOutput {
+  const parsed = JSON.parse(stdout);
+  if (typeof parsed?.text !== "string" || !Array.isArray(parsed?.segments)) {
+    throw new Error("Invalid transcription JSON returned by kesha-engine");
+  }
+
+  const segments = parsed.segments.map((segment: unknown) => {
+    const s = segment as Record<string, unknown>;
+    if (
+      typeof s.start !== "number" ||
+      typeof s.end !== "number" ||
+      typeof s.text !== "string"
+    ) {
+      throw new Error("Invalid transcription segment returned by kesha-engine");
+    }
+    return {
+      start: s.start,
+      end: s.end,
+      text: s.text,
+    };
+  });
+
+  return { text: parsed.text, segments };
+}
+
+export async function transcribeEngineWithSegments(
+  audioPath: string,
+  opts: TranscribeEngineOptions = {},
+): Promise<TranscriptionOutput> {
+  const caps = await getEngineCapabilities();
+  if (!caps?.features.includes("transcribe.segments")) {
+    throw new Error(
+      "Timestamped segments require a newer kesha-engine. Run `kesha install` after upgrading Kesha Voice Kit.",
+    );
+  }
+
+  const args = ["transcribe", audioPath, "--json"];
+  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}`);
+  }
+  try {
+    return parseTranscriptionOutput(stdout);
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`${message}: ${stdout}`);
+  }
+}
+
 export function parseLangResult(stdout: string): LangDetectResult | null {
   try {
     const parsed = JSON.parse(stdout);
@@ -99,12 +161,22 @@ export interface EngineCapabilities {
   features: string[];
 }
 
+let cachedEngineCapabilities:
+  | { binPath: string; capabilities: EngineCapabilities }
+  | null = null;
+
 export async function getEngineCapabilities(): Promise<EngineCapabilities | null> {
-  if (!isEngineInstalled()) return null;
+  const binPath = getEngineBinPath();
+  if (cachedEngineCapabilities?.binPath === binPath) {
+    return cachedEngineCapabilities.capabilities;
+  }
+  if (!existsSync(binPath)) return null;
   const { stdout, exitCode } = await runEngine(["--capabilities-json"]);
   if (exitCode !== 0) return null;
   try {
-    return JSON.parse(stdout) as EngineCapabilities;
+    const capabilities = JSON.parse(stdout) as EngineCapabilities;
+    cachedEngineCapabilities = { binPath, capabilities };
+    return capabilities;
   } catch {
     return null;
   }

package/src/lib.ts

@@ -1,8 +1,13 @@
 import { existsSync } from "fs";
-import { transcribe as internalTranscribe, type TranscribeOptions } from "./transcribe";
+import {
+  transcribe as internalTranscribe,
+  transcribeWithSegments as internalTranscribeWithSegments,
+  type TranscribeOptions,
+} from "./transcribe";
 import { downloadEngine } from "./engine-install";
 
 export type { TranscribeOptions };
+export type { TranscriptionOutput, TranscriptionSegment } from "./engine";
 export { downloadEngine as downloadModel };
 export { say, type SayOptions, SayError } from "./say";
 
@@ -38,3 +43,18 @@ export async function transcribe(
 
   return internalTranscribe(audioPath, { ...options, silent: true });
 }
+
+export async function transcribeWithSegments(
+  audioPath: string,
+  options: TranscribeOptions = {},
+) {
+  if (!existsSync(audioPath)) {
+    throw new Error(`File not found: ${audioPath}`);
+  }
+
+  return internalTranscribeWithSegments(audioPath, {
+    ...options,
+    timestamps: true,
+    silent: true,
+  });
+}

package/src/say.ts

@@ -39,9 +39,9 @@ export interface SayOptions {
    */
   sampleRate?: number;
   /**
-   * Disable Russian acronym auto-expansion for `ru-vosk-*` voices.
+   * Disable acronym auto-expansion for `ru-vosk-*` and `en-*` voices.
    * When true, passes `--no-expand-abbrev` to the engine (requires engine
-   * capability `tts.ru_acronym_expansion`; silently dropped for older engines).
+   * capability `tts.ru_acronym_expansion` or `tts.en_acronym_expansion`; silently dropped for older engines).
    * `<say-as interpret-as="characters">` still works regardless of this flag.
    */
   noExpandAbbrev?: boolean;
@@ -59,12 +59,14 @@ export function buildSayArgs(o: SayOptions, capabilities?: EngineCapabilities |
   if (o.bitrate !== undefined) args.push("--bitrate", String(o.bitrate));
   if (o.sampleRate !== undefined) args.push("--sample-rate", String(o.sampleRate));
   if (o.noExpandAbbrev) {
-    const supportsRuExpand = capabilities?.features?.includes("tts.ru_acronym_expansion") ?? false;
-    if (supportsRuExpand) {
+    const supportsExpand = capabilities?.features?.some(
+      (f) => f === "tts.ru_acronym_expansion" || f === "tts.en_acronym_expansion",
+    ) ?? false;
+    if (supportsExpand) {
       args.push("--no-expand-abbrev");
     } else {
       log.debug(
-        "kesha-engine does not advertise tts.ru_acronym_expansion; dropping --no-expand-abbrev",
+        "kesha-engine does not advertise tts.ru_acronym_expansion or tts.en_acronym_expansion; dropping --no-expand-abbrev",
       );
     }
   }

package/src/transcribe.ts

@@ -1,14 +1,30 @@
-import { isEngineInstalled, transcribeEngine, type VadMode } from "./engine";
+import {
+  isEngineInstalled,
+  transcribeEngine,
+  transcribeEngineWithSegments,
+  type TranscriptionOutput,
+  type VadMode,
+} from "./engine";
 
 export type { VadMode };
+export type { TranscriptionOutput };
 
 export interface TranscribeOptions {
   silent?: boolean;
   /** Silero VAD preprocessing selector. Defaults to `"auto"`. */
   vad?: VadMode;
+  /** Request timestamped transcript segments from the engine. */
+  timestamps?: boolean;
 }
 
 export async function transcribe(audioPath: string, opts: TranscribeOptions = {}): Promise<string> {
+  return (await transcribeWithSegments(audioPath, opts)).text;
+}
+
+export async function transcribeWithSegments(
+  audioPath: string,
+  opts: TranscribeOptions = {},
+): Promise<TranscriptionOutput> {
   if (!isEngineInstalled()) {
     throw new Error(
       "Error: No transcription backend is installed\n\n" +
@@ -20,5 +36,10 @@ export async function transcribe(audioPath: string, opts: TranscribeOptions = {}
     );
   }
 
-  return transcribeEngine(audioPath, { vad: opts.vad });
+  if (opts.timestamps) {
+    return transcribeEngineWithSegments(audioPath, { vad: opts.vad });
+  }
+
+  const text = await transcribeEngine(audioPath, { vad: opts.vad });
+  return { text, segments: [] };
 }

package/src/types.ts

@@ -1,4 +1,4 @@
-import type { LangDetectResult } from "./engine";
+import type { LangDetectResult, TranscriptionSegment } from "./engine";
 
 /**
  * One row of `kesha --json` / `kesha --toon` output. Canonical output shape
@@ -11,8 +11,10 @@ export type TranscribeResult = {
   lang: string;
   audioLanguage?: LangDetectResult;
   textLanguage?: LangDetectResult;
+  /** Timestamped transcript segments when requested via `--timestamps`. */
+  segments?: TranscriptionSegment[];
   /** Wall-clock time around the engine subprocess calls for this file, ms. See #139. */
   sttTimeMs?: number;
 };
 
-export type { LangDetectResult };
+export type { LangDetectResult, TranscriptionSegment };