@drakulavich/kesha-voice-kit 1.4.4 → 1.6.0

package/NOTICES.md

@@ -27,19 +27,15 @@ Pinned to the `v6.2.1` tag.
 
 Text-to-speech (English). Apache 2.0. ONNX export by [onnx-community/Kokoro-82M-v1.0-ONNX](https://huggingface.co/onnx-community/Kokoro-82M-v1.0-ONNX).
 
-### Piper voices (Russian: `ru-denis`)
+### Vosk-TTS (Russian, multi-speaker)
 
-Text-to-speech (multilingual, Piper VITS). MIT. Voice packs from [rhasspy/piper-voices](https://huggingface.co/rhasspy/piper-voices).
+Text-to-speech (Russian, 5 baked-in speakers). Apache 2.0. Model: [alphacep/vosk-tts](https://huggingface.co/alphacep/vosk-tts) (`vosk-model-tts-ru-0.9-multi`).
 
-### CharsiuG2P ByT5-tiny (ONNX export)
+**Runtime code:** Originally pulled from `crates.io` as `vosk-tts-rs 0.1.0`. As of #216 the runtime subset is **vendored** under `rust/vendor/vosk-tts/` (Apache 2.0; copied from [`andreytkachenko/vosk-tts-rs`](https://github.com/andreytkachenko/vosk-tts-rs) — see `rust/vendor/vosk-tts/LICENSE` and `rust/vendor/vosk-tts/NOTICE`). The vendored copy drops the upstream gRPC server/CLI/HTTP-model-fetch modules and replaces the `tokenizers` crate with a small inline BERT WordPiece tokenizer, eliminating the `prost`, `tonic`, `tokio`, `axum`, `hyper`, `reqwest`, `tokenizers`, `onig_sys`, `esaxx-rs`, `bzip2-sys`, `lzma-sys`, and `zstd-sys` transitive dependencies that broke Windows MSVC linkage.
 
-Grapheme-to-phoneme conversion for Kokoro and Piper pipelines (#123).
+### misaki-rs (English G2P)
 
-**License: CC-BY 4.0** (declared on the ONNX-export repo). Attribution required.
-
-- ONNX export: [klebster/g2p_multilingual_byT5_tiny_onnx](https://huggingface.co/klebster/g2p_multilingual_byT5_tiny_onnx) by Kleber Noel — CC-BY 4.0.
-- Base checkpoint: [charsiu/g2p_multilingual_byT5_tiny_16_layers_100](https://huggingface.co/charsiu/g2p_multilingual_byT5_tiny_16_layers_100) — **no explicit license declared on HuggingFace**; usage here follows the CC-BY 4.0 declared by the downstream export and the paper's terms.
-- Paper: Zhu, J., Zhang, C., & Jurgens, D. (2022). "ByT5 model for massively multilingual grapheme-to-phoneme conversion." [arXiv:2204.03067](https://arxiv.org/abs/2204.03067) · Interspeech 2022.
+Embedded grapheme-to-phoneme for English (Kokoro pipeline, #207). MIT. Source: [`misaki-rs`](https://github.com/MicheleYin/misaki-rs).
 
 ## System libraries linked by the engine binary
 

package/README.md

@@ -117,8 +117,7 @@ const text = await transcribe("audio.ogg");  // transcribe
 ## Requirements
 
 - [Bun](https://bun.sh) >= 1.3
-- macOS arm64 or Linux x64
-- Windows x64 temporarily unsupported in v1.5.0 — Vosk-TTS native deps trigger MSVC link conflicts. Tracked in [#216](https://github.com/drakulavich/kesha-voice-kit/issues/216).
+- macOS arm64, Linux x64, or Windows x64
 
 ## Contributing
 

package/SKILL.md

@@ -1,15 +1,14 @@
 ---
 name: kesha-voice-kit
-description: Local multilingual voice toolkit — speech-to-text (STT), text-to-speech (TTS), and language detection. Runs entirely offline on Apple Silicon, Linux, and Windows. No API keys, no cloud. NVIDIA Parakeet TDT for STT across 25 European languages, Kokoro-82M + Piper VITS for TTS, plus macOS AVSpeechSynthesizer for ~180 system voices with zero install.
+description: Local multilingual voice toolkit — speech-to-text (STT), text-to-speech (TTS), and language detection. Runs entirely offline on Apple Silicon, Linux, and Windows. No API keys, no cloud. NVIDIA Parakeet TDT for STT across 25 European languages, Kokoro-82M + Vosk-TTS for TTS, plus macOS AVSpeechSynthesizer for ~180 system voices with zero install.
 emoji: 🎙️
 
 requires:
   bins: [kesha]
 
 install:
-  - kind: npm
-    packages: [@drakulavich/kesha-voice-kit]
-    flags: [--global]
+  - kind: bash
+    cmd: bun add -g "@drakulavich/kesha-voice-kit"
   - kind: bash
     cmd: kesha install
 ---
@@ -23,7 +22,7 @@ Local voice toolkit: transcribe voice messages to text, synthesize speech, detec
 ## When to use
 
 - **Voice memo arrived** (Telegram, WhatsApp, Slack, Signal .ogg/.opus/.m4a): transcribe with `kesha --json <path>` and branch on the detected language.
-- **Need to reply with audio**: synthesize with `kesha say "<text>" > reply.wav`. Auto-routes by detected language (Kokoro-82M for English, Piper for Russian). For other languages and ~180 more voices use `--voice macos-*` on macOS (zero model download).
+- **Need to reply with audio**: synthesize with `kesha say "<text>" > reply.wav`. Auto-routes by detected language (Kokoro-82M for English, Vosk-TTS for Russian). For other languages and ~180 more voices use `--voice macos-*` on macOS (zero model download).
 - **Need to detect what language a file is in** before choosing a pipeline: `kesha --json audio.ogg` returns both audio-based and text-based language detection with confidence scores.
 
 ## STT: transcribe audio
@@ -57,9 +56,9 @@ Use `lang` (or the more detailed `audioLanguage`/`textLanguage`) to decide how t
 
 ```bash
 kesha say "Hello, world" > hello.wav               # auto-routes en → Kokoro-82M
-kesha say "Привет, мир" > privet.wav              # auto-routes ru → Piper
+kesha say "Привет, мир" > privet.wav              # auto-routes ru → Vosk-TTS
 kesha say --voice macos-de-DE "Guten Tag" > de.wav # any macOS system voice — German, French, Italian, ...
-kesha say --list-voices                            # Kokoro + Piper + ~180 macos-* voices
+kesha say --list-voices                            # Kokoro + Vosk-TTS + ~180 macos-* voices
 ```
 
 Output: WAV mono float32. `--out <path>` writes to a file instead of stdout.
@@ -71,18 +70,18 @@ Output: WAV mono float32. `--out <path>` writes to a file instead of stdout.
 ## Install
 
 ```bash
-bun add --global @drakulavich/kesha-voice-kit    # or: npm i -g @drakulavich/kesha-voice-kit
+bun add -g @drakulavich/kesha-voice-kit          # global CLI install
 kesha install                                    # downloads engine (~350 MB)
-kesha install --tts                              # adds Kokoro + Piper RU + ONNX G2P (~490 MB more, for TTS)
+kesha install --tts                              # adds Kokoro + Vosk-TTS RU (~990 MB more, for TTS)
 ```
 
-No system deps — G2P runs as ONNX alongside Kokoro/Piper. `macos-*` voices need no install either — they use voices already on the Mac.
+No system deps — English G2P is embedded (`misaki-rs`); Russian G2P is bundled inside Vosk-TTS. `macos-*` voices need no install either — they use voices already on the Mac.
 
 ## Supported languages
 
 **Speech-to-text (25):** Bulgarian, Croatian, Czech, Danish, Dutch, English, Estonian, Finnish, French, German, Greek, Hungarian, Italian, Latvian, Lithuanian, Maltese, Polish, Portuguese, Romanian, Russian, Slovak, Slovenian, Spanish, Swedish, Ukrainian.
 
-**Text-to-speech:** English (Kokoro-82M, ~70 voices), Russian (Piper `ru-denis`), plus any macOS system voice via `--voice macos-*`.
+**Text-to-speech:** English (Kokoro-82M, ~70 voices), Russian (Vosk-TTS, 5 baked-in speakers — default `ru-vosk-m02`), plus any macOS system voice via `--voice macos-*`.
 
 ## Performance
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/kesha-voice-kit",
-  "version": "1.4.4",
+  "version": "1.6.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.4.1"
+    "version": "1.6.0"
   },
   "scripts": {
     "test": "bun test",
@@ -58,7 +58,7 @@
     "type": "git",
     "url": "git+https://github.com/drakulavich/kesha-voice-kit.git"
   },
-  "homepage": "https://github.com/drakulavich/kesha-voice-kit#readme",
+  "homepage": "https://drakulavich.github.io/kesha-voice-kit/",
   "bugs": {
     "url": "https://github.com/drakulavich/kesha-voice-kit/issues"
   },

package/src/cli/say.ts

@@ -1,7 +1,7 @@
 import { defineCommand } from "citty";
 import { detectTextLanguageEngine, getEngineBinPath } from "../engine";
 import { log } from "../log";
-import { say, SayError } from "../say";
+import { say, SayError, type SayFormat } from "../say";
 
 /**
  * Darwin defaults to AVSpeech Milena — zero install, no model download required.
@@ -54,19 +54,34 @@ async function resolveText(inline: string | undefined): Promise<string> {
 export const sayCommand = defineCommand({
   meta: {
     name: "say",
-    description: "Synthesize speech from text (TTS). Writes WAV to stdout (or --out file).",
+    description:
+      "Synthesize speech from text (TTS). Writes audio to stdout (or --out file). Defaults to WAV; use --format ogg-opus for messenger-ready voice notes.",
   },
   args: {
     text: { type: "positional", required: false, description: "Text to speak (stdin if omitted)" },
     voice: { type: "string", description: "Voice id, e.g. en-am_michael" },
     lang: { type: "string", description: "BCP 47 language code (default en-us)" },
-    out: { type: "string", description: "Write WAV to file instead of stdout" },
+    out: { type: "string", description: "Write audio to file instead of stdout" },
     rate: { type: "string", description: "Speaking rate 0.5–2.0", default: "1.0" },
     "list-voices": { type: "boolean", description: "List installed voices and exit" },
     ssml: {
       type: "boolean",
       description: "Parse input as SSML (supports <speak>, <break>; strips unknown tags)",
     },
+    format: {
+      type: "string",
+      description:
+        "Output format: wav (default) or ogg-opus (Telegram-ready voice note). Inferred from --out extension when omitted.",
+    },
+    bitrate: {
+      type: "string",
+      description: "Opus bitrate in bits/sec (e.g. 32000). Only with --format ogg-opus.",
+    },
+    "sample-rate": {
+      type: "string",
+      description:
+        "Opus encoder sample rate (8000/12000/16000/24000/48000). Only with --format ogg-opus.",
+    },
     verbose: {
       type: "boolean",
       description: "Log TTS synthesis time to stderr",
@@ -94,6 +109,35 @@ export const sayCommand = defineCommand({
     const explicitVoice = typeof args.voice === "string" ? args.voice : undefined;
     const voice = explicitVoice ?? (await autoRouteVoice(text));
 
+    // Validate --format up front so we surface a clear error before spawning
+    // the engine subprocess. The engine repeats the check authoritatively, but
+    // catching it here gives the user a faster failure mode in scripts.
+    const fmtArg = typeof args.format === "string" ? args.format.toLowerCase() : undefined;
+    let format: SayFormat | undefined;
+    if (fmtArg) {
+      if (fmtArg === "wav" || fmtArg === "ogg-opus") {
+        format = fmtArg;
+      } else if (fmtArg === "opus" || fmtArg === "ogg") {
+        format = "ogg-opus";
+      } else {
+        log.error(`unknown --format '${args.format}'. supported: wav, ogg-opus`);
+        process.exit(2);
+      }
+    }
+
+    // Reject --bitrate / --sample-rate with WAV up front to surface the error fast.
+    const hasOpusOnlyFlag = Boolean(args.bitrate) || Boolean(args["sample-rate"]);
+    if (hasOpusOnlyFlag) {
+      const outExt = typeof args.out === "string"
+        ? args.out.split(".").pop()?.toLowerCase()
+        : undefined;
+      const impliesOpus = outExt && ["ogg", "opus", "oga"].includes(outExt);
+      if (format === "wav" || (format === undefined && !impliesOpus)) {
+        log.error("--bitrate and --sample-rate are only valid with --format ogg-opus");
+        process.exit(2);
+      }
+    }
+
     const opts = {
       text,
       voice,
@@ -101,18 +145,21 @@ export const sayCommand = defineCommand({
       out: typeof args.out === "string" ? args.out : undefined,
       rate: args.rate ? Number(args.rate) : undefined,
       ssml: Boolean(args.ssml),
+      format,
+      bitrate: args.bitrate ? Number(args.bitrate) : undefined,
+      sampleRate: args["sample-rate"] ? Number(args["sample-rate"]) : undefined,
     };
 
     try {
       const startedAt = performance.now();
-      const wav = await say(opts);
+      const audio = await say(opts);
       const ttsTimeMs = Math.round(performance.now() - startedAt);
       if (args.verbose) {
-        // stderr — stdout may carry raw WAV bytes when --out is omitted.
+        // stderr — stdout may carry raw audio bytes when --out is omitted.
         console.error(`TTS time: ${ttsTimeMs}ms`);
       }
       if (!opts.out) {
-        process.stdout.write(wav);
+        process.stdout.write(audio);
       }
     } catch (err) {
       if (err instanceof SayError) {

package/src/say.ts

@@ -1,6 +1,14 @@
 import { getEngineBinPath, isEngineInstalled } from "./engine";
 import { log } from "./log";
 
+/**
+ * Wire format for the synthesized audio. Matches the engine's `--format` flag.
+ * - `wav` (default): RIFF WAV at the engine's native sample rate.
+ * - `ogg-opus`: OGG-encapsulated Opus, mono. The format Telegram, WhatsApp,
+ *   Signal, and Discord render as native voice messages. See #223.
+ */
+export type SayFormat = "wav" | "ogg-opus";
+
 export interface SayOptions {
   /**
    * Text to synthesize. Required for programmatic callers — `say()` does not
@@ -18,6 +26,18 @@ export interface SayOptions {
   rate?: number;
   /** Parse `text` as SSML (`<speak>…<break time="500ms"/>…</speak>`). See issue #122. */
   ssml?: boolean;
+  /**
+   * Output audio format. Defaults to `wav` (or inferred from the `out`
+   * extension when omitted: `.wav` → wav, `.ogg`/`.opus` → ogg-opus).
+   */
+  format?: SayFormat;
+  /** Opus bitrate in bits/second. Only valid with `format: "ogg-opus"`. Default 32000. */
+  bitrate?: number;
+  /**
+   * Encoder sample rate in Hz. Only valid with `format: "ogg-opus"`.
+   * Must be one of 8000, 12000, 16000, 24000, 48000. Default 24000.
+   */
+  sampleRate?: number;
 }
 
 /** Build the argv passed to `kesha-engine say` (pure, unit-testable). */
@@ -28,6 +48,9 @@ export function buildSayArgs(o: SayOptions): string[] {
   if (o.out) args.push("--out", o.out);
   if (o.rate !== undefined && o.rate !== 1.0) args.push("--rate", String(o.rate));
   if (o.ssml) args.push("--ssml");
+  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.text !== undefined && o.text.length > 0) args.push(o.text);
   return args;
 }