@drakulavich/kesha-voice-kit 1.9.0 → 1.10.0

package/README.md

@@ -86,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.9.0",
+  "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.9.0"
+    "version": "1.10.0"
   },
   "scripts": {
     "test": "bun test",

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/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",
       );
     }
   }