hermes-volcengine-voice

agent
Security Audit
Warn
Health Warn
  • No license — Repository has no license file
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Low visibility — Only 5 GitHub stars
Code Pass
  • Code scan — Scanned 7 files during light audit, no dangerous patterns found
Permissions Pass
  • Permissions — No dangerous permissions requested

No AI report is available for this listing yet.

SUMMARY

Volcengine Doubao TTS & STT voice provider plugin for Hermes Agent — 60+ Chinese voices, emotion control, speaker diarization

README.md

Hermes Volcengine Voice Plugin

License: MIT
Hermes Plugin

🌋 火山引擎豆包语音合成 & 识别插件 for Hermes Agent

Adds Volcengine (火山引擎) Doubao (豆包) TTS and STT as voice providers to Hermes Agent via monkey-patch plugin — 60+ Chinese voices, emotion control, dialect support, speaker diarization.

✨ Features

  • TTS — HTTP Chunked streaming via V3 API (/api/v3/tts/unidirectional)
  • STT — WebSocket streaming ASR via V3 API (/api/v3/sauc/bigmodel)
  • 2.0 voices — Uses Doubao TTS 2.0 model with 5+ Chinese voice presets
  • Short-name aliases — Config uses friendly names like zh_female_conversation, auto-resolved to voice types
  • Seamless integration — Set tts.provider: volcengine and it just works

📦 Installation

# Clone into Hermes plugins directory
git clone https://github.com/linxichen/hermes-volcengine-voice.git ~/.hermes/plugins/volcengine-voice

# Or install straight from GitHub (equivalent)
hermes plugins install linxichen/hermes-volcengine-voice

# Enable in config.yaml
hermes config set plugins.enabled --append volcengine-voice

🔑 Setup

1. Get API Key

Go to 火山引擎语音控制台 → API Key 管理 → create a key.

⚠️ Important: You need a Speech API key, NOT an Ark (LLM) key. Ark keys (prefix ark-) will return 45000010: "Invalid X-Api-Key".

2. Configure

# Add to ~/.hermes/.env
echo 'VOLCENGINE_VOICE_API_KEY=your-api-key-here' >> ~/.hermes/.env

# Set provider
hermes config set tts.provider volcengine
hermes config set stt.provider volcengine

3. Choose a voice (optional)

# Available presets:
#   zh_female_conversation  — 爽快思思 2.0 (default)
#   zh_female_gentle        — Vivi 2.0 温柔女声
#   zh_female_sweet         — 甜美小源 2.0
#   zh_male_ruya            — 儒雅逸辰 2.0
#   zh_male_conversation    — 对话男声

hermes config set tts.volcengine.speaker zh_female_gentle

4. Restart

hermes gateway restart

🎤 Usage

Once configured, Hermes uses Volcengine for all TTS and STT automatically:

  • Discord voice messages — auto-transcribed via Volcengine STT
  • Voice responses — spoken via Volcengine TTS when /voice tts is enabled
  • Discord voice channels — join with /voice channel, bot speaks through VC

🧠 智能语音纠偏与会话感知 (Smart STT)

原生语音识别在口语交流中常遇到重复语气、口吃结巴,且对特定技术或专业术语缺乏语境判断。本插件支持可选的三层智能后处理:

  1. 原生流式 ASR:由火山引擎 WebSocket API 极速转写;
  2. 会话语境感知:自动读取当前会话相邻一轮完整对话(最近一条用户消息+其后的全部可见回复,无锁只读、毫秒级;用户可见内容一字不删,工具调用/大段代码等不可见内容略去),为大模型提供完整语境与人名指代;
  3. 大模型平滑润色:调用豆包轻量大模型(默认 doubao-seed-2.1-lite,关闭思考耗时仅 1~2s)抚平口吃、修正同音错字,同时严守忠实原意、不篡改数字与代码的红线。

配置与开启

在 ~/.hermes/.env 中配置火山方舟 API Key(或 Coding API Key):

echo 'VOLCENGINE_ARK_API_KEY=your-ark-api-key' >> ~/.hermes/.env

在 config.yaml 中可进行细粒度控制(全部可选,默认具备开箱即用的安全退回):

stt:
  provider: volcengine
  volcengine:
    enable_llm_postprocess: true   # 检测到 Key 时默认开启,设为 false 可完全禁用
    enable_context: true           # 是否读取相邻一轮完整对话作为语境
    llm_model: doubao-seed-2.1-lite
    hotwords:                      # 可选自定义高频专有词
      - "变式"
      - "情境"
      - "架构"

注:若未配置 Ark Key 或大模型调用遇到网络异常,系统会自动平滑降级返回原生识别文本,绝不阻断正常使用。

🎭 情绪指令([情绪] 文本)

✍️ 情绪指令功能由社区贡献者 @BartmossW 开发并提交(PR #1),感谢贡献!

在 TTS 文本开头加 [情绪] 标记即可控制朗读风格,开箱即用(插件已把该格式声明注入到语音回复的模型上下文里):

[开心] 今天天气真好
[开心][快速] 你好
  • 语法:一个或多个方括号标记必须位于文本开头;正文中的方括号(引用编号、markdown 链接、list[str] 等)会原样朗读,不受影响。
  • 不计费:标记内容通过 context_texts 字段传给火山引擎,该字段不计费——只有 text 的字符数计费。
  • 需要 2.0 音色:context_texts 仅在 seed-tts-2.0(_uranus_ 系列 + seed-tts-2.0)上生效;1.0 音色(如 zh_male_conversation)会忽略标记,按原文本朗读。
  • 效果差异:不同音色对情绪指令的响应差异较大(Vivi 响应明显,有些音色几乎没反应),请按需尝试。

🎧 试听 Demo(情绪指令 + 音色)

所有片段朗读同一句话,只换 [情绪] 标记和音色,方便对比效果。也可以运行 docs/demo/generate_demo.py 用你的 API Key 重新生成:

片段 音色 情绪标记
sisi-happy.mp3 爽快思思 2.0(默认) [开心]
sisi-sad.mp3 爽快思思 2.0 [伤心]
sisi-angry.mp3 爽快思思 2.0 [生气]
sisi-fast.mp3 爽快思思 2.0 [快速]
vivi-happy.mp3 Vivi 2.0 温柔女声 [开心]
vivi-gentle.mp3 Vivi 2.0 温柔女声 [温柔]
xiaoyuan-happy.mp3 甜美小源 2.0 [开心]
xiaoyuan-angry.mp3 甜美小源 2.0 [生气]
yichen-serious.mp3 儒雅逸辰 2.0(男声) [严肃]
yichen-happy.mp3 儒雅逸辰 2.0(男声) [开心]

🎵 Voice List

Short Name Voice Type Description
zh_female_conversation zh_female_shuangkuaisisi_uranus_bigtts 爽快思思 2.0
zh_female_gentle zh_female_vv_uranus_bigtts Vivi 2.0 温柔女声
zh_female_sweet zh_female_tianmeixiaoyuan_uranus_bigtts 甜美小源 2.0
zh_male_ruya zh_male_ruyayichen_uranus_bigtts 儒雅逸辰 2.0
zh_male_conversation zh_male_M392_conversation_wvae_bigtts 对话男声 (1.0)

Full list: 火山引擎音色列表

🏗️ Architecture

volcengine-voice/
├── plugin.yaml          # Plugin metadata
├── __init__.py          # Monkey-patch dispatch for TTS + STT
├── tts.py               # HTTP Chunked TTS (V3 API)
└── stt.py               # WebSocket binary STT (V3 API)

The plugin intercepts Hermes' TTS/STT dispatch and routes provider: volcengine calls to the Doubao API:

# From __init__.py — register()
import tools.tts_tool as tts_module
original_tts = tts_module.text_to_speech_tool

def patched_tts(text, output_path=None):
    config = tts_module._load_tts_config()
    if tts_module._get_provider(config) == "volcengine":
        from hermes_plugins.volcengine_voice.tts import _volcengine_tts
        return _volcengine_tts(text, output_path, config)
    return original_tts(text, output_path)

tts_module.text_to_speech_tool = patched_tts

📄 License

MIT — feel free to use, modify, and share.

🔗 Links

Reviews (0)

No results found