hermes-volcengine-voice
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.
Volcengine Doubao TTS & STT voice provider plugin for Hermes Agent — 60+ Chinese voices, emotion control, speaker diarization
Hermes Volcengine Voice 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: volcengineand 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 ttsis enabled - Discord voice channels — join with
/voice channel, bot speaks through VC
🧠 智能语音纠偏与会话感知 (Smart STT)
原生语音识别在口语交流中常遇到重复语气、口吃结巴,且对特定技术或专业术语缺乏语境判断。本插件支持可选的三层智能后处理:
- 原生流式 ASR:由火山引擎 WebSocket API 极速转写;
- 会话语境感知:自动读取当前会话相邻一轮完整对话(最近一条用户消息+其后的全部可见回复,无锁只读、毫秒级;用户可见内容一字不删,工具调用/大段代码等不可见内容略去),为大模型提供完整语境与人名指代;
- 大模型平滑润色:调用豆包轻量大模型(默认
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)
Sign in to leave a review.
Leave a reviewNo results found