@drakulavich/kesha-voice-kit 1.18.4 → 1.18.6

package/README.md

@@ -15,7 +15,7 @@
 
 - **Transcribe locally** — 25 languages, up to ~19x faster than Whisper on Apple Silicon, ~2.5x on CPU
 - **Speak back** — Kokoro (EN), Vosk-TTS (RU), macOS system voices, and SSML preview
-- **Plug into agents** — ship voice workflows as CLI commands or an <a href="https://github.com/openclaw/openclaw">OpenClaw</a> skill
+- **Plug into agents** — ship voice workflows as CLI commands or an <a href="https://github.com/openclaw/openclaw">OpenClaw</a> skill; setup docs: [OpenClaw](docs/openclaw.md), [Hermes](docs/hermes.md)
 - **Small Rust engine** — single ~20MB binary, no ffmpeg, no Python, no native Node addons
 
 See [Product positioning](docs/product-positioning.md) for supported workflows, non-goals, maturity labels, and the platform matrix.
@@ -51,139 +51,10 @@ kesha audio.ogg     # transcript to stdout
 
 Air-gapped or behind a corporate mirror? See [docs/model-mirror.md](docs/model-mirror.md).
 
-## Shell Completions and Manpage
-
-The npm package includes bash, zsh, and fish completions plus `kesha(1)`.
-The CLI can print the packaged files, so install paths do not depend on the
-Bun global package layout:
-
-```bash
-# bash
-mkdir -p ~/.local/share/bash-completion/completions
-kesha completions bash > ~/.local/share/bash-completion/completions/kesha
-
-# zsh
-mkdir -p ~/.zsh/completions
-kesha completions zsh > ~/.zsh/completions/_kesha
-# add to ~/.zshrc once: fpath=(~/.zsh/completions $fpath); autoload -Uz compinit; compinit
-
-# fish
-mkdir -p ~/.config/fish/completions
-kesha completions fish > ~/.config/fish/completions/kesha.fish
-
-# manpage
-mkdir -p ~/.local/share/man/man1
-kesha manpage > ~/.local/share/man/man1/kesha.1
-mandb ~/.local/share/man 2>/dev/null || true
-```
-
-## Homebrew Install
-
-Homebrew installs the Bun-based CLI wrapper. Engine and model downloads remain
-explicit:
-
-```bash
-brew tap oven-sh/bun
-brew install drakulavich/tap/kesha-voice-kit
-kesha install
-kesha audio.ogg
-```
-
-See [Homebrew install](docs/homebrew.md) for package scope and maintainer
-validation.
-
-## Support diagnostics
-
-Kesha can collect local diagnostics without downloading models or mutating cache state:
-
-```bash
-kesha doctor --json --redact
-kesha support-bundle --output kesha-support.tar.gz
-```
-
-`support-bundle` creates a redacted `.tar.gz` archive for GitHub issues. It includes runtime, engine, cache, optional-component, Stats status, and known Kesha environment settings. It does not include audio, transcripts, model files, or the Stats database.
-
-## Local Stats privacy and lifecycle
-
-Kesha Stats is disabled by default. When you opt in with `kesha stats enable`,
-Kesha writes a local SQLite database only on your machine:
-
-```bash
-kesha stats status
-kesha stats week
-kesha stats errors
-kesha stats export --format json   # or csv
-kesha stats retention 30           # default: 90 days
-kesha stats retention off          # keep until reset
-kesha stats reset                  # delete recorded stats rows
-kesha stats vacuum                 # compact the SQLite file
-```
-
-The database stores content-free operational records only: command name
-(`transcribe` or `say`), timestamps, success/failure status, app version, item
-count, anonymous stage timings, input/output artifact kind, file extension,
-size, optional duration/sample-rate/channel counts, and sanitized error
-class/code/message.
-
-Stats never stores audio bytes, transcripts, input text, generated speech text,
-file names, full file paths, raw stdout/stderr, environment variables, model
-files, API tokens, or cloud identifiers. `support-bundle` reports Stats status
-only; it never includes the Stats SQLite database.
-
-By default, Stats prunes rows older than 90 days before writing or exporting
-data. Use `kesha stats retention <days>` to change the TTL or `kesha stats
-retention off` to disable TTL pruning. `kesha stats reset` deletes recorded
-runs, artifacts, timings, and errors while preserving settings such as enabled
-state and retention.
-
-## Nix Install
-
-Alternative reproducible-build path on `aarch64-darwin` / `x86_64-linux`:
-
-```bash
-nix run github:drakulavich/kesha-voice-kit -- install      # downloads models (engine is bundled)
-nix run github:drakulavich/kesha-voice-kit -- audio.ogg    # transcribe
-```
-
-Full recipes (one-liner, profile install, engine-only, dev shell) live in [docs/nix-install.md](docs/nix-install.md).
-
-## Docker
-
-Linux x64 CLI image, published to GHCR:
-
-```bash
-docker run --rm \
-  -v kesha-cache:/cache/kesha \
-  -v "$PWD:/work" -w /work \
-  ghcr.io/drakulavich/kesha-voice-kit:latest install
-
-docker run --rm \
-  -v kesha-cache:/cache/kesha \
-  -v "$PWD:/work" -w /work \
-  ghcr.io/drakulavich/kesha-voice-kit:latest audio.ogg
-```
-
-The image keeps model downloads and the engine cache under `/cache/kesha`.
-Mount that path as a named volume so `kesha install`, TTS models, VAD, and future
-runs reuse the same cache. `compose.yml` provides the same layout:
-
-```bash
-docker compose run --rm kesha install
-docker compose run --rm kesha audio.ogg
-```
-
-## Linux Packages
-
-Stable engine releases also publish `.deb` and `.rpm` packages for Linux x64.
-They install the standalone CLI wrapper; engine and model downloads remain explicit:
-
-```bash
-kesha install
-kesha audio.ogg
-```
+## Requirements
 
-See [Linux packages](docs/linux-packages.md) for install commands and package
-scope.
+- [Bun](https://bun.sh) >= 1.3
+- macOS arm64, Linux x64, or Windows x64
 
 ## Speech-to-text
 
@@ -265,6 +136,96 @@ Honored when `<prosody rate>` wraps the whole utterance. Mid-utterance prosody w
 
 macOS system voices, SSML, voice listing, and the full voice catalogue: [docs/tts.md](docs/tts.md).
 
+## Homebrew Install
+
+Homebrew installs the Bun-based CLI wrapper. Engine and model downloads remain
+explicit:
+
+```bash
+brew tap oven-sh/bun
+brew install drakulavich/tap/kesha-voice-kit
+kesha install
+kesha audio.ogg
+```
+
+See [Homebrew install](docs/homebrew.md) for package scope and maintainer
+validation.
+
+## Linux Packages
+
+Stable engine releases also publish `.deb` and `.rpm` packages for Linux x64.
+They install the standalone CLI wrapper; engine and model downloads remain explicit:
+
+```bash
+kesha install
+kesha audio.ogg
+```
+
+See [Linux packages](docs/linux-packages.md) for install commands and package
+scope.
+
+## Docker
+
+Linux x64 CLI image, published to GHCR:
+
+```bash
+docker run --rm \
+  -v kesha-cache:/cache/kesha \
+  -v "$PWD:/work" -w /work \
+  ghcr.io/drakulavich/kesha-voice-kit:latest install
+
+docker run --rm \
+  -v kesha-cache:/cache/kesha \
+  -v "$PWD:/work" -w /work \
+  ghcr.io/drakulavich/kesha-voice-kit:latest audio.ogg
+```
+
+The image keeps model downloads and the engine cache under `/cache/kesha`.
+Mount that path as a named volume so `kesha install`, TTS models, VAD, and future
+runs reuse the same cache. `compose.yml` provides the same layout:
+
+```bash
+docker compose run --rm kesha install
+docker compose run --rm kesha audio.ogg
+```
+
+## Nix Install
+
+Alternative reproducible-build path on `aarch64-darwin` / `x86_64-linux`:
+
+```bash
+nix run github:drakulavich/kesha-voice-kit -- install      # downloads models (engine is bundled)
+nix run github:drakulavich/kesha-voice-kit -- audio.ogg    # transcribe
+```
+
+Full recipes (one-liner, profile install, engine-only, dev shell) live in [docs/nix-install.md](docs/nix-install.md).
+
+## Shell Completions and Manpage
+
+The npm package includes bash, zsh, and fish completions plus `kesha(1)`.
+The CLI can print the packaged files, so install paths do not depend on the
+Bun global package layout:
+
+```bash
+# bash
+mkdir -p ~/.local/share/bash-completion/completions
+kesha completions bash > ~/.local/share/bash-completion/completions/kesha
+
+# zsh
+mkdir -p ~/.zsh/completions
+kesha completions zsh > ~/.zsh/completions/_kesha
+# add to ~/.zshrc once: fpath=(~/.zsh/completions $fpath); autoload -Uz compinit; compinit
+
+# fish
+mkdir -p ~/.config/fish/completions
+kesha completions fish > ~/.config/fish/completions/kesha.fish
+
+# manpage
+mkdir -p ~/.local/share/man/man1
+kesha manpage > ~/.local/share/man/man1/kesha.1
+mandb ~/.local/share/man 2>/dev/null || true
+```
+
 ## Performance
 
 > **Up to ~19x faster than Whisper** on Apple Silicon (M2), **~2.5x faster** on CPU
@@ -309,10 +270,49 @@ await downloadModel();                       // install engine + models
 const text = await transcribe("audio.ogg");  // transcribe
 ```
 
-## Requirements
+## Support diagnostics
 
-- [Bun](https://bun.sh) >= 1.3
-- macOS arm64, Linux x64, or Windows x64
+Kesha can collect local diagnostics without downloading models or mutating cache state:
+
+```bash
+kesha doctor --json --redact
+kesha support-bundle --output kesha-support.tar.gz
+```
+
+`support-bundle` creates a redacted `.tar.gz` archive for GitHub issues. It includes runtime, engine, cache, optional-component, Stats status, and known Kesha environment settings. It does not include audio, transcripts, model files, or the Stats database.
+
+## Local Stats privacy and lifecycle
+
+Kesha Stats is disabled by default. When you opt in with `kesha stats enable`,
+Kesha writes a local SQLite database only on your machine:
+
+```bash
+kesha stats status
+kesha stats week
+kesha stats errors
+kesha stats export --format json   # or csv
+kesha stats retention 30           # default: 90 days
+kesha stats retention off          # keep until reset
+kesha stats reset                  # delete recorded stats rows
+kesha stats vacuum                 # compact the SQLite file
+```
+
+The database stores content-free operational records only: command name
+(`transcribe` or `say`), timestamps, success/failure status, app version, item
+count, anonymous stage timings, input/output artifact kind, file extension,
+size, optional duration/sample-rate/channel counts, and sanitized error
+class/code/message.
+
+Stats never stores audio bytes, transcripts, input text, generated speech text,
+file names, full file paths, raw stdout/stderr, environment variables, model
+files, API tokens, or cloud identifiers. `support-bundle` reports Stats status
+only; it never includes the Stats SQLite database.
+
+By default, Stats prunes rows older than 90 days before writing or exporting
+data. Use `kesha stats retention <days>` to change the TTL or `kesha stats
+retention off` to disable TTL pruning. `kesha stats reset` deletes recorded
+runs, artifacts, timings, and errors while preserving settings such as enabled
+state and retention.
 
 ## Contributing
 

package/SKILL.md

@@ -34,12 +34,30 @@ Install the plugin, then explicitly route OpenClaw audio understanding through t
 bun add -g @drakulavich/kesha-voice-kit
 kesha install
 openclaw plugins install @drakulavich/kesha-voice-kit
-openclaw config set tools.media.audio.enabled true
-openclaw config set tools.media.audio.models \
-  '[{"type":"cli","command":"kesha","args":["--format","transcript","{{MediaPath}}"],"timeoutSeconds":15}]'
+openclaw config patch --stdin <<'JSON5'
+{
+  tools: {
+    media: {
+      audio: {
+        enabled: true,
+        models: [
+          {
+            type: "cli",
+            command: "kesha",
+            args: ["{{MediaPath}}"],
+            timeoutSeconds: 15,
+          },
+        ],
+        echoTranscript: true,
+        echoFormat: '🦜 "{transcript}"',
+      },
+    },
+  },
+}
+JSON5
 ```
 
-Use `--format transcript` for OpenClaw's normal voice-message path: stdout is compact text plus language metadata, while progress and errors stay off the transcript payload.
+Use Kesha's default output for OpenClaw's normal voice-message path: stdout is the bare transcript text, while progress and errors stay off the transcript payload. The default setup echoes each transcript back to chat as `🦜 "{transcript}"` before the agent responds.
 
 For agents that need timestamped segments, switch the model entry to JSON output and allow a longer timeout:
 
@@ -55,6 +73,8 @@ which kesha
 kesha status
 openclaw plugins list
 openclaw config get tools.media.audio.models
+openclaw config get tools.media.audio.echoTranscript
+openclaw config get tools.media.audio.echoFormat
 ```
 
 Do not rely on `openclaw.plugin.json` to patch `tools.media.audio.models`; OpenClaw ignores non-schema fields such as `configPatch`. Keep the CLI route in user config.

package/man/kesha.1

@@ -1,4 +1,4 @@
-.TH KESHA 1 "May 2026" "kesha 1.18.4" "User Commands"
+.TH KESHA 1 "May 2026" "kesha 1.18.6" "User Commands"
 .SH NAME
 kesha \- open-source local voice toolkit
 .SH SYNOPSIS

package/package.json

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

package/src/cli/main.ts

@@ -17,6 +17,7 @@ import { formatToonOutput } from "../toon";
 import { artifactFromFile, createStatsRecorder } from "../stats";
 import { createPercentProgress } from "../progress";
 import { getPendingSignalExitCode, waitForPendingSignalCleanup } from "../process-tree";
+import type { TranscriptionSegment } from "../types";
 
 interface MainCommandArgs {
   _: string[];
@@ -117,6 +118,25 @@ export function shouldReportTranscribeProgress(input: {
   return input.stderrIsTty || !input.stdoutIsTty;
 }
 
+const AUDIO_LANG_ID_LONG_AUDIO_THRESHOLD_SECONDS = 10 * 60;
+
+export function estimateTranscriptDurationSeconds(segments: TranscriptionSegment[]): number | null {
+  const duration = segments.reduce((max, segment) => {
+    const end = Number(segment.end);
+    return Number.isFinite(end) && end > max ? end : max;
+  }, 0);
+  return duration > 0 ? duration : null;
+}
+
+export function shouldRunAudioLanguageDetection(input: {
+  wantsLangId: boolean;
+  transcriptDurationSeconds: number | null;
+}): boolean {
+  if (!input.wantsLangId) return false;
+  if (input.transcriptDurationSeconds === null) return true;
+  return input.transcriptDurationSeconds <= AUDIO_LANG_ID_LONG_AUDIO_THRESHOLD_SECONDS;
+}
+
 export const mainCommand = defineCommand({
   meta: {
     name: "kesha",
@@ -285,32 +305,25 @@ export const mainCommand = defineCommand({
               estimatedTotalMs: args.speakers ? 60 * 60 * 1000 : 30 * 60 * 1000,
             })
           : null;
-        // Run audio lang-id and transcription concurrently, but do not leave
-        // the sibling engine process alive if one side fails first.
-        const engineAbort = new AbortController();
-        const audioPromise = wantsLangId
-          ? stats.timeStage("lang_id_audio", () =>
-              detectAudioLanguageEngine(file, { signal: engineAbort.signal })
-            )
-          : Promise.resolve(null);
-        const transcriptPromise = stats.timeStage("transcribe", () =>
+        const transcript = await stats.timeStage("transcribe", () =>
           transcribeWithSegments(file, {
             vad: vadMode,
-            signal: engineAbort.signal,
             timestamps: args.timestamps,
             speakers: args.speakers,
           })
         );
-        let audioResult: LangDetectResult | null;
-        let transcript: Awaited<ReturnType<typeof transcribeWithSegments>>;
-        try {
-          [audioResult, transcript] = await Promise.all([audioPromise, transcriptPromise]);
-        } catch (err) {
-          engineAbort.abort();
-          await Promise.allSettled([audioPromise, transcriptPromise]);
-          throw err;
-        }
         const { text, segments } = transcript;
+        const transcriptDurationSeconds = estimateTranscriptDurationSeconds(segments);
+
+        let audioResult: LangDetectResult | null = null;
+        if (shouldRunAudioLanguageDetection({ wantsLangId, transcriptDurationSeconds })) {
+          audioResult = await stats.timeStage("lang_id_audio", () => detectAudioLanguageEngine(file));
+        } else if (wantsLangId) {
+          log.debug(
+            `skip lang_id_audio for ${file}: transcript duration ${transcriptDurationSeconds?.toFixed(1)}s exceeds ` +
+              `${AUDIO_LANG_ID_LONG_AUDIO_THRESHOLD_SECONDS}s`,
+          );
+        }
 
         let audioLanguage: LangDetectResult | undefined;
         if (audioResult && audioResult.code) {

package/src/cli.ts

@@ -18,7 +18,9 @@ export {
   mainCommand,
   detectLanguage,
   checkLanguageMismatch,
+  estimateTranscriptDurationSeconds,
   resolveOutputFormat,
+  shouldRunAudioLanguageDetection,
   shouldReportTranscribeProgress,
 } from "./cli/main";
 export type { ResolvedOutputFormat } from "./cli/main";