@drakulavich/kesha-voice-kit 1.19.0 → 1.20.0

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="docs/assets/logo.png" alt="Kesha Voice Kit" width="200">
+  <img src="https://raw.githubusercontent.com/drakulavich/kesha-voice-kit/main/docs/assets/logo.png" alt="Kesha Voice Kit" width="200">
 </p>
 
 <h1 align="center">Kesha Voice Kit</h1>
@@ -21,7 +21,7 @@
 See [Product positioning](docs/product-positioning.md) for supported workflows, non-goals, maturity labels, and the platform matrix.
 
 <p align="center">
-  <img src="./demo.gif" alt="kesha demo — English + Russian transcription with automatic language detection" width="800">
+  <img src="https://raw.githubusercontent.com/drakulavich/kesha-voice-kit/main/demo.gif" alt="kesha demo — English + Russian transcription with automatic language detection" width="800">
 </p>
 
 ## Quick Start
@@ -104,6 +104,16 @@ kesha say "Hello, world" > hello.wav
 kesha say "Привет, мир" > privet.wav     # auto-routes (Milena on darwin, ru-vosk-m02 elsewhere)
 ```
 
+**Output formats** (`--format`, or inferred from `--out` extension):
+
+```bash
+kesha say "Hello" --out hi.wav                       # WAV (default, uncompressed)
+kesha say "Hello" --format ogg-opus --out hi.ogg     # OGG/Opus — messenger voice notes (Telegram/WhatsApp/Signal)
+kesha say "Hello" --format flac --out hi.flac        # FLAC — lossless, royalty-free, plays in every browser incl. Safari/iOS
+```
+
+FLAC is the format for web-embeddable samples: it plays natively in all modern browsers (including Safari/iOS, where OGG/Opus does not), stays royalty-free like Opus, and keeps the engine's native sample rate (no resample). `--bitrate` / `--sample-rate` apply only to `--format ogg-opus`.
+
 **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 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).
@@ -232,7 +242,7 @@ mandb ~/.local/share/man 2>/dev/null || true
 
 Compared against Whisper `large-v3-turbo` — all engines auto-detect language.
 
-![Benchmark: openai-whisper vs faster-whisper vs Kesha Voice Kit](docs/assets/benchmark.svg)
+![Benchmark: openai-whisper vs faster-whisper vs Kesha Voice Kit](https://raw.githubusercontent.com/drakulavich/kesha-voice-kit/main/docs/assets/benchmark.svg)
 
 See [BENCHMARK.md](BENCHMARK.md) for the full per-file breakdown (Russian + English).
 
@@ -280,6 +290,10 @@ Cache boundary: `kesha install` and opt-in feature installs populate the local
 cache; ordinary transcription and speech commands fail fast if required assets
 are missing.
 
+Contributors: see [`docs/architecture.md`](docs/architecture.md) for the
+code-level map (repo layout, CLI↔engine boundary, backends, model pinning,
+tests, and a "where to change X" table).
+
 ## What's Inside
 
 | Model | Task | Size | Source |

package/SKILL.md

@@ -168,6 +168,12 @@ kesha say --list-voices                            # Kokoro + Vosk-TTS + ~180 ma
 
 Output: WAV mono float32 by default. `--out <path>` writes to a file instead of stdout. For Telegram/OpenClaw replies, prefer `--format ogg-opus --out reply.ogg` or the OpenClaw-provided `{{OutputPath}}`.
 
+**Output formats** (`--format`, or inferred from the `--out` extension): `wav` (default, uncompressed), `ogg-opus` (messenger voice notes), `flac` (lossless, royalty-free, plays in every browser incl. Safari/iOS — the format for web-embeddable samples). FLAC keeps the engine's native rate; `--bitrate` / `--sample-rate` apply only to `ogg-opus`.
+
+```bash
+kesha say --format flac --out sample.flac "Hello"   # web-embeddable, Safari-safe
+```
+
 **Voice notes (Telegram / WhatsApp / Signal / Discord):** add `--format ogg-opus` to emit OGG/Opus directly — the format messenger APIs render as a native voice message:
 
 ```bash

package/completions/kesha.fish

@@ -69,7 +69,7 @@ complete -c kesha -n '__fish_seen_subcommand_from say' -l out -r -d 'Write audio
 complete -c kesha -n '__fish_seen_subcommand_from say' -l rate -r -d 'Speaking rate 0.5–2.0'
 complete -c kesha -n '__fish_seen_subcommand_from say' -l list-voices -d 'List installed voices and exit'
 complete -c kesha -n '__fish_seen_subcommand_from say' -l ssml -d 'Parse input as SSML (supports <speak>, <break>; strips unknown tags)'
-complete -c kesha -n '__fish_seen_subcommand_from say' -l format -r -d 'Output format: wav (default) or ogg-opus (Telegram-ready voice note). Inferred from --out extension when omitted.'
+complete -c kesha -n '__fish_seen_subcommand_from say' -l format -r -d 'Output format: wav (default), ogg-opus (Telegram-ready voice note), or flac (lossless, plays in all browsers incl. Safari). Inferred from --out extension when omitted.'
 complete -c kesha -n '__fish_seen_subcommand_from say' -l bitrate -r -d 'Opus bitrate in bits/sec (e.g. 32000). Only with --format ogg-opus.'
 complete -c kesha -n '__fish_seen_subcommand_from say' -l sample-rate -r -d 'Opus encoder sample rate (8000/12000/16000/24000/48000). Only with --format ogg-opus.'
 complete -c kesha -n '__fish_seen_subcommand_from say' -l no-expand-abbrev -d 'Disable Russian acronym auto-expansion (ВОЗ → \'вэ о зэ\') for ru-vosk-* voices. <say-as interpret-as=\'characters\'> still works. Applies to Russian (ru-vosk-*) and English (en-*) voices.'

package/completions/kesha.zsh

@@ -99,7 +99,7 @@ _kesha() {
         '--rate=[Speaking rate 0.5–2.0]:rate:' \
         '--list-voices[List installed voices and exit]' \
         '--ssml[Parse input as SSML (supports <speak>, <break>; strips unknown tags)]' \
-        '--format=[Output format: wav (default) or ogg-opus (Telegram-ready voice note). Inferred from --out extension when omitted.]:format:' \
+        '--format=[Output format: wav (default), ogg-opus (Telegram-ready voice note), or flac (lossless, plays in all browsers incl. Safari). Inferred from --out extension when omitted.]:format:' \
         '--bitrate=[Opus bitrate in bits/sec (e.g. 32000). Only with --format ogg-opus.]:bitrate:' \
         '--sample-rate=[Opus encoder sample rate (8000/12000/16000/24000/48000). Only with --format ogg-opus.]:sample rate:' \
         '--no-expand-abbrev[Disable Russian acronym auto-expansion (ВОЗ → '\''вэ о зэ'\'') for ru-vosk-* voices. <say-as interpret-as='\''characters'\''> still works. Applies to Russian (ru-vosk-*) and English (en-*) voices.]' \

package/man/kesha.1

@@ -1,4 +1,4 @@
-.TH KESHA 1 "May 2026" "kesha 1.19.0" "User Commands"
+.TH KESHA 1 "May 2026" "kesha 1.20.0" "User Commands"
 .SH NAME
 kesha \- open-source local voice toolkit
 .SH SYNOPSIS
@@ -167,7 +167,7 @@ List installed voices and exit
 Parse input as SSML (supports <speak>, <break>; strips unknown tags)
 .TP
 .B \-\-format
-Output format: wav (default) or ogg\-opus (Telegram\-ready voice note). Inferred from \-\-out extension when omitted.
+Output format: wav (default), ogg\-opus (Telegram\-ready voice note), or flac (lossless, plays in all browsers incl. Safari). Inferred from \-\-out extension when omitted.
 .TP
 .B \-\-bitrate
 Opus bitrate in bits/sec (e.g. 32000). Only with \-\-format ogg\-opus.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/kesha-voice-kit",
-  "version": "1.19.0",
+  "version": "1.20.0",
   "description": "Give your local tools a voice: fast STT in 25 languages (~19x faster than Whisper on Apple Silicon, ONNX CPU fallback), TTS via Kokoro/Vosk/macOS voices, VAD + 107-language detection. Rust engine, Bun CLI, OpenClaw skill.",
   "type": "module",
   "bin": {
@@ -32,7 +32,7 @@
     ]
   },
   "keshaEngine": {
-    "version": "1.19.0"
+    "version": "1.20.0"
   },
   "scripts": {
     "test": "bun test",
@@ -79,7 +79,7 @@
   "devDependencies": {
     "@types/bun": "latest",
     "@typescript/native-preview": "^7.0.0-dev.20260423.1",
-    "fast-xml-parser": "^5.5.10",
+    "fast-xml-parser": "^5.8.0",
     "typescript": "^6.0.2",
     "yaml": "^2.9.0"
   },

package/src/cli/say.ts

@@ -100,7 +100,7 @@ export const sayCommand = defineCommand({
     format: {
       type: "string",
       description:
-        "Output format: wav (default) or ogg-opus (Telegram-ready voice note). Inferred from --out extension when omitted.",
+        "Output format: wav (default), ogg-opus (Telegram-ready voice note), or flac (lossless, plays in all browsers incl. Safari). Inferred from --out extension when omitted.",
     },
     bitrate: {
       type: "string",
@@ -145,12 +145,12 @@ export const sayCommand = defineCommand({
     const fmtArg = typeof args.format === "string" ? args.format.toLowerCase() : undefined;
     let format: SayFormat | undefined;
     if (fmtArg) {
-      if (fmtArg === "wav" || fmtArg === "ogg-opus") {
+      if (fmtArg === "wav" || fmtArg === "ogg-opus" || fmtArg === "flac") {
         format = fmtArg;
       } else if (fmtArg === "opus" || fmtArg === "ogg") {
         format = "ogg-opus";
       } else {
-        log.error(`unknown --format '${args.format}'. supported: wav, ogg-opus`);
+        log.error(`unknown --format '${args.format}'. supported: wav, ogg-opus, flac`);
         process.exit(2);
       }
     }
@@ -166,7 +166,10 @@ export const sayCommand = defineCommand({
         ? args.out.split(".").pop()?.toLowerCase()
         : undefined;
       const impliesOpus = outExt && ["ogg", "opus", "oga"].includes(outExt);
-      if (format === "wav" || (format === undefined && !impliesOpus)) {
+      // --bitrate / --sample-rate are Opus-only. Reject for wav and flac
+      // (both lossless / no encoder knobs) and for any non-Opus extension.
+      const resolvesToOpus = format === "ogg-opus" || (format === undefined && impliesOpus);
+      if (!resolvesToOpus) {
         log.error("--bitrate and --sample-rate are only valid with --format ogg-opus");
         process.exit(2);
       }

package/src/synth.ts

@@ -14,8 +14,10 @@ import { registerProcessTree } from "./process-tree";
  * - `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.
+ * - `flac`: lossless, royalty-free, plays in every modern browser including
+ *   Safari/iOS. Keeps the engine's native rate; no bitrate knob.
  */
-export type SayFormat = "wav" | "ogg-opus";
+export type SayFormat = "wav" | "ogg-opus" | "flac";
 export const MAX_TEXT_CHARS = 5000;
 
 export interface SayOptions {