@drakulavich/kesha-voice-kit 1.6.1 → 1.8.0

package/README.md

@@ -69,6 +69,36 @@ kesha say "Hello, world" > hello.wav
 kesha say "Привет, мир" > privet.wav     # auto-routes (Milena on darwin, ru-vosk-m02 elsewhere)
 ```
 
+**Russian abbreviations** (`ru-vosk-*` voices):
+
+```bash
+# Auto-detect on by default — ФСБ reads as "эф-эс-бэ"
+kesha say --voice ru-vosk-m02 'ФСБ объявила решение.'
+
+# 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).
+
+**Russian word stress** (`ru-vosk-*` voices):
+
+```bash
+# Caller provides `+` before the stressed vowel; engine passes it to Vosk
+kesha say --voice ru-vosk-m02 --ssml \
+  '<speak><emphasis>дом+а</emphasis></speak>'   # genitive до-МА́
+
+# Suppress an inherited <emphasis> with level="none"
+kesha say --voice ru-vosk-m02 --ssml \
+  '<speak><emphasis level="none">дом+а</emphasis></speak>'   # default ДО́ма
+```
+
+Vosk-TTS 0.9-multi honors a `+` placed BEFORE the target stressed vowel — but only when the marker shifts stress AWAY from the model's default (first-syllable). `+` agreeing with the default is a no-op. See [#233](https://github.com/drakulavich/kesha-voice-kit/issues/233).
+
 macOS system voices, SSML, voice listing, and the full voice catalogue: [docs/tts.md](docs/tts.md).
 
 ## Performance

package/SKILL.md

@@ -74,6 +74,10 @@ 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 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
 
 `kesha --json audio.ogg` includes both audio-based (`audioLanguage`) and text-based (`textLanguage`) detection. Use audio detection to identify the language before running language-specific logic.

package/package.json

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

package/src/cli/say.ts

@@ -82,6 +82,12 @@ export const sayCommand = defineCommand({
       description:
         "Opus encoder sample rate (8000/12000/16000/24000/48000). Only with --format ogg-opus.",
     },
+    "no-expand-abbrev": {
+      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.",
+    },
     verbose: {
       type: "boolean",
       description: "Log TTS synthesis time to stderr",
@@ -148,6 +154,7 @@ export const sayCommand = defineCommand({
       format,
       bitrate: args.bitrate ? Number(args.bitrate) : undefined,
       sampleRate: args["sample-rate"] ? Number(args["sample-rate"]) : undefined,
+      noExpandAbbrev: Boolean(args["no-expand-abbrev"]),
     };
 
     try {

package/src/say.ts

@@ -1,4 +1,4 @@
-import { getEngineBinPath, isEngineInstalled } from "./engine";
+import { getEngineBinPath, isEngineInstalled, getEngineCapabilities, type EngineCapabilities } from "./engine";
 import { log } from "./log";
 
 /**
@@ -38,10 +38,17 @@ export interface SayOptions {
    * Must be one of 8000, 12000, 16000, 24000, 48000. Default 24000.
    */
   sampleRate?: number;
+  /**
+   * Disable Russian acronym auto-expansion for `ru-vosk-*` voices.
+   * When true, passes `--no-expand-abbrev` to the engine (requires engine
+   * capability `tts.ru_acronym_expansion`; silently dropped for older engines).
+   * `<say-as interpret-as="characters">` still works regardless of this flag.
+   */
+  noExpandAbbrev?: boolean;
 }
 
 /** Build the argv passed to `kesha-engine say` (pure, unit-testable). */
-export function buildSayArgs(o: SayOptions): string[] {
+export function buildSayArgs(o: SayOptions, capabilities?: EngineCapabilities | null): string[] {
   const args: string[] = ["say"];
   if (o.voice) args.push("--voice", o.voice);
   if (o.lang) args.push("--lang", o.lang);
@@ -51,6 +58,16 @@ export function buildSayArgs(o: SayOptions): string[] {
   if (o.format) args.push("--format", o.format);
   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) {
+      args.push("--no-expand-abbrev");
+    } else {
+      log.debug(
+        "kesha-engine does not advertise tts.ru_acronym_expansion; dropping --no-expand-abbrev",
+      );
+    }
+  }
   if (o.text !== undefined && o.text.length > 0) args.push(o.text);
   return args;
 }
@@ -78,7 +95,8 @@ export async function say(opts: SayOptions): Promise<Uint8Array> {
       "",
     );
   }
-  const args = buildSayArgs({ ...opts, text: undefined });
+  const capabilities = opts.noExpandAbbrev ? await getEngineCapabilities() : null;
+  const args = buildSayArgs({ ...opts, text: undefined }, capabilities);
   const startedAt = performance.now();
   log.debug(`spawn ${getEngineBinPath()} ${args.join(" ")} (text: ${opts.text?.length ?? 0} chars)`);
   const proc = Bun.spawn([getEngineBinPath(), ...args], {