kesha-voice-kit

本地语音工具包：将语音消息转录为文本、合成语音、检测音频或文本的语言。执行 kesha install 后完全离线运行，无需 API 密钥，也无按分钟计费模式。

触发该技能的关键词：语音消息、语音备忘录、语音笔记、.ogg、.opus、.wav、.mp3、音频文件、转录、语音识别、speech-to-text、STT、text-to-speech、TTS、合成语音、朗读、Telegram 语音笔记、WhatsApp 语音笔记、ogg-opus、opus、多语言语音、多语言 ASR、语言检测、离线语音、隐私保护、Apple Silicon、CoreML。

适用场景

• 收到语音备忘录时（Telegram、WhatsApp、Slack、Signal 的 .ogg/.opus/.m4a 文件）：使用 kesha --json 进行转录，并依据检测到的语言进行分支处理。
• 需要发送语音笔记（Telegram、WhatsApp、Signal、Discord）时：直接合成为信使原生支持的 OGG/Opus 格式，命令为 kesha say --format ogg-opus --out reply.ogg ""。默认参数为单声道 24 kHz @ 32 kbps —— 正是 Telegram sendVoice 所期望的格式。无需 WAV 中转，也无需 ffmpeg 编码往返。
• 需要本地文件播放或调试输出时：仍可使用 kesha say --out reply.wav "" 输出 WAV，但请勿将 WAV 用于 Telegram 语音回复。系统会根据检测到的语言自动路由（英语使用 Kokoro-82M，俄语使用 Vosk-TTS）。在 darwin-arm64 平台上，英语 Kokoro 使用 FluidAudio CoreML 而非 ONNX。如需其他语言及约 180 种 macOS 系统语音，请在 macOS 上使用 --voice macos-*（零模型下载）。
• 需要在选择处理流程前检测音频文件的语言时：运行 kesha --json audio.ogg，返回基于音频与基于文本的双重语言检测结果，并附带置信度分数。

OpenClaw 插件配置

安装插件后，需显式通过 CLI 模型入口将 OpenClaw 的音频理解能力路由至 Kesha。插件注册使 Kesha 可被发现，但真正的语音消息转录依赖于 tools.media.audio.models 中类型为 type: "cli" 的条目。

bun add -g @drakulavich/kesha-voice-kit
kesha install
openclaw plugins install @drakulavich/kesha-voice-kit
openclaw config patch --stdin <<'JSON5'
{
  tools: {
    media: {
      audio: {
        enabled: true,
        models: [
          {
            type: "cli",
            command: "kesha",
            args: ["{{MediaPath}}"],
            timeoutSeconds: 15,
          },
        ],
        echoTranscript: true,
        echoFormat: '🦜 "{transcript}"',
      },
    },
  },
}
JSON5

使用 Kesha 默认输出作为 OpenClaw 常规语音消息路径的输入：标准输出（stdout）仅包含纯文本转录结果，而进度信息和错误日志则不会混入转录负载中。默认配置会在 Agent 响应前，将每条转录内容以 🦜 "{transcript}" 形式回显至聊天窗口。

若 Agent 需要带时间戳的分段内容，请切换模型条目为 JSON 输出并延长超时时间：

openclaw config set tools.media.audio.models 
  '[{"type":"cli","command":"kesha","args":["--json","--timestamps","{{MediaPath}}"],"timeoutSeconds":30}]'

验证清单：

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

请勿依赖 openclaw.plugin.json 来补丁（patch）tools.media.audio.models；OpenClaw 会忽略 schema 之外的字段（例如 configPatch）。CLI 路由必须保留在用户配置中。

对于 OpenClaw 的 TTS 回复，请将本地 TTS 提供方路由至 Kesha 的 OGG/Opus 输出。这是 Telegram 安全路径：

openclaw config patch --stdin <<'JSON5'
{
  messages: {
    tts: {
      auto: "always",
      provider: "tts-local-cli",
      providers: {
        "tts-local-cli": {
          command: "kesha",
          args: ["say", "--format", "ogg-opus", "--out", "{{OutputPath}}", "{{Text}}"],
          outputFormat: "opus",
          timeoutMs: 120000,
        },
      },
    },
  },
}
JSON5

在 OpenClaw 流程中手动调用 Kesha 时，应将 OGG/Opus 写入 OpenClaw 拥有的临时路径，例如 kesha say --format ogg-opus --out /tmp/openclaw/reply.ogg ""，并在执行前确保目录已存在。已配置的 tts-local-cli 提供方应使用 OpenClaw 的 {{OutputPath}} 占位符，而非硬编码路径。

请勿将 OpenClaw Telegram TTS 配置为 kesha say "" > reply.wav；这将生成 WAV 文件，无法在 Telegram 中渲染为原生语音消息。

STT：音频转录

# 推荐用于自动化：JSON 输出并含语言检测
kesha --json voice.ogg

[{
  "file": "voice.ogg",
  "text": "Привет, как дела?",
  "lang": "ru",
  "audioLanguage": { "code": "ru", "confidence": 0.98 },
  "textLanguage": { "code": "ru", "confidence": 0.99 }
}]

使用 lang 字段（或更详细的 audioLanguage/textLanguage）决定响应逻辑。

如需带时间戳的转录分段（用于导航、章节划分或下游编辑）：

kesha --json --timestamps voice.ogg > voice.timestamps.json
jq '.[0].segments' voice.timestamps.json

每个分段均包含 start、end 和 text 字段。--timestamps 仅对机器可读输出生效（即搭配 --json、--toon 或 --format json 使用）。

说话人区分（speaker diarization）（darwin-arm64，v1.12.0 版本后支持）。添加 --speakers 参数可为每个分段标注聚类 ID，适用于多人通话或会议录音转录：

kesha install --diarize                                  # 一次性操作，约 245 MB
kesha --json --vad --speakers meeting.m4a > out.json
jq '.[0].segments[] | "(.speaker)t(.text)"' out.json

每个 segment.speaker 是一个数字（聚类 ID，在单个文件内稳定）。Linux / Windows 平台下引擎会明确报错“currently darwin-arm64 only”——详见 #199。

支持格式：.ogg、.opus、.mp3、.m4a、.wav、.flac、.webm —— 均通过 symphonia 解码，无需 ffmpeg。

其他输出模式：

• kesha audio.ogg —— 标准输出（stdout）显示纯文本转录结果
• kesha --format transcript audio.ogg —— 转录结果 + 底部附加 [lang: ru, confidence: 0.99]
• kesha --json --timestamps audio.ogg —— JSON 格式，含带时间戳的 segments
• kesha --verbose audio.ogg —— 人类可读格式，含语言信息
• kesha --lang en audio.ogg —— 若检测语言与指定不符则发出警告（可用作合理性校验）

TTS：语音合成

kesha say "Hello, world" > hello.wav               # 自动路由：en → Kokoro-82M
kesha say "Привет, мир" > privet.wav              # 自动路由：ru → Vosk-TTS
kesha say --voice macos-de-DE "Guten Tag" > de.wav # 任意 macOS 系统语音 —— 德语、法语、意大利语等
kesha say --list-voices                            # 列出 Kokoro + Vosk-TTS + 约 180 种 macos-* 语音

输出格式：默认为 WAV 单声道 float32。使用 --out 可写入文件而非 stdout。Telegram/OpenClaw 回复推荐使用 --format ogg-opus --out reply.ogg 或 OpenClaw 提供的 {{OutputPath}}。

语音笔记（Telegram / WhatsApp / Signal / Discord）：添加 --format ogg-opus 直接输出 OGG/Opus 格式 —— 即信使 API 渲染为原生语音消息所要求的格式：

kesha say --format ogg-opus --out reply.ogg "Hello there"                  # 24 kHz @ 32 kbps 单声道 —— Telegram 级别质量
kesha say --voice ru-vosk-m02 --format ogg-opus --out reply.ogg "Привет"   # 俄语语音笔记
kesha say --format ogg-opus --bitrate 16000 --out tiny.ogg "Hi"            # 更小体积，可听清但有损

格式也可通过 --out 后缀自动推断（.ogg / .opus / .oga → OGG/Opus）。--bitrate（6 000–510 000 bps）与 --sample-rate（8 000 / 12 000 / 16 000 / 24 000 / 48 000 Hz）用于调节编码器参数。

俄语缩略词处理（ru-vosk-*）：所有全大写的西里尔字母 2–5 字符标记，若无法按俄语音节发音，则自动逐字母展开（如 ФСБ → “эф-эс-бэ”，ВОЗ → “воз”）。可通过 --no-expand-abbrev 禁用。详见 docs/tts.md#russian-abbreviation-auto-expansion。

英语首字母缩略词处理（en-*, Kokoro）：采用三表机制（字母拼读规则 + STOP_LIST + IPA_LEXICON），自动展开 FBI → “ef bee eye”，并为 EPAM/JSON/Anthropic 等提供正确 IPA。可通过 --no-expand-abbrev 禁用字母拼读。详见 docs/tts.md#english-acronym-auto-expansion。

俄语单词重音标记（仅 ru-vosk-* 支持）：使用 сл+ово 将重音移至标有 + 的元音上。сл+ово 则移除 +（取消继承的重音）。其他语音（en-*, macos-*）会静默丢弃 + 并在进程内仅警告一次。未提供自动重音词典 —— 调用方需手动插入 +。关闭 #233。

通过 SSML 控制语速（ru-vosk-* 与 en-* 语音）：将整段话语包裹在 中，即可减慢或加快合成速度。支持 SSML 命名值（x-slow/slow/medium/fast/x-fast）、绝对百分比（如 120%）及相对百分比（+N%/-N%）。仅当 包裹整段话语时才生效；句中嵌入 prosody 将触发警告并以默认速率合成。--rate 与 效果叠加计算，最终结果限定在 0.5×–2.0× 范围内。AVSpeech（macos-* 语音）暂不支持 SSML —— 详见 #236。

独立语言检测

kesha --json audio.ogg 同时包含基于音频（audioLanguage）与基于文本（textLanguage）的语言检测。建议先使用音频检测确定语言，再执行语言特定逻辑。

安装

bun add -g @drakulavich/kesha-voice-kit          # 全局 CLI 安装
kesha install                                    # 下载引擎（约 350 MB）
kesha install --tts                              # 额外下载 Kokoro + Vosk-TTS RU（约 990 MB，用于 TTS）

无系统依赖 —— 英语 G2P 内置于 misaki-rs；俄语 G2P 已打包进 Vosk-TTS。macos-* 语音亦无需额外安装 —— 直接调用 Mac 系统已预装语音。

支持语言

语音识别（25 种）：保加利亚语、克罗地亚语、捷克语、丹麦语、荷兰语、英语、爱沙尼亚语、芬兰语、法语、德语、希腊语、匈牙利语、意大利语、拉脱维亚语、立陶宛语、马耳他语、波兰语、葡萄牙语、罗马尼亚语、俄语、斯洛伐克语、斯洛文尼亚语、西班牙语、瑞典语、乌克兰语。

语音合成：英语（Kokoro-82M；darwin-arm64 平台使用 FluidAudio CoreML，其余平台使用 ONNX）、俄语（Vosk-TTS，内置 5 种说话人 —— 默认为 ru-vosk-m02），以及通过 --voice macos-* 调用的任意 macOS 系统语音。

性能

• ASR：在 Apple Silicon 上约为 OpenAI Whisper 的 19 倍速度（通过 FluidAudio CoreML 加速），CPU 上约为 2.5 倍（通过 ort 的 ONNX 加速）。
• TTS：在 Apple Silicon 上短语合成延迟低于 1 秒。

为何选择本地化方案

无需管理 API 密钥，无按分钟计费模式。语音数据永不离开本地设备 —— 对受监管行业、私人通信，以及任何不应记录于第三方日志中的场景至关重要。

相关链接

• 源码：https://github.com/drakulavich/kesha-voice-kit
• npm：https://www.npmjs.com/package/@drakulavich/kesha-voice-kit
• 发布版本：https://github.com/drakulavich/kesha-voice-kit/releases