ElevenLabs 文本转语音

使用带有音频标签的 ElevenLabs v3 生成富有表现力的语音消息。

先决条件

• ElevenLabs API 密钥(ELEVENLABS_API_KEY): 必需。请在elevenlabs.io→ 个人资料 → API 密钥 处获取。在openclaw.json文件中的messages.tts.elevenlabs.apiKey项下进行配置。
• ffmpeg: 音频格式转换（MP3 → Opus，以兼容 WhatsApp）所必需。必须安装并确保在 PATH 环境变量中可用。

快速开始示例

讲故事（情感历程）：

[soft] It started like any other day... [pause] But something felt different. [nervous] My hands were shaking as I opened the envelope. [gasps] I got in! [excited] I actually got in! [laughs] [happy] This changes everything!

恐怖/悬疑（营造恐惧感）：

[whispers] The house has been empty for years... [pause] At least, that's what they told me. [nervous] But I keep hearing footsteps. [scared] They're getting closer. [gasps] [panicking] The door— it's opening by itself!

对话与反应：

[curious] So what happened at the meeting? [pause] [surprised] Wait, they fired him?! [gasps] [sad] That's terrible... [sighs] He had a family. [thoughtful] I wonder what he'll do now.

希伯来语（浪漫时刻）：

[soft] היא עמדה שם, מול השקיעה... [pause] הלב שלי פעם כל כך חזק. [nervous] לא ידעתי מה להגיד. [hesitates] אני... [breathes] [tender] את יודעת שאני אוהב אותך, נכון?

西班牙语（从庆祝到反思）：

[excited] ¡Lo logramos! [laughs] [happy] No puedo creerlo... [pause] [thoughtful] Fueron tantos años de trabajo. [emotional] [soft] Gracias a todos los que creyeron en mí. [sighs] [content] Valió la pena cada momento.

配置（OpenClaw）

在openclaw.json中，于messages.tts下配置TTS：

{
  "messages": {
    "tts": {
      "provider": "elevenlabs",
      "elevenlabs": {
        "apiKey": "sk_your_api_key_here",
        "voiceId": "pNInz6obpgDQGcFmaJgB",
        "modelId": "eleven_v3",
        "languageCode": "en",
        "voiceSettings": {
          "stability": 0.5,
          "similarityBoost": 0.75,
          "style": 0,
          "useSpeakerBoost": true,
          "speed": 1
        }
      }
    }
  }
}

获取您的API密钥：

1. 前往https://elevenlabs.io
2. 注册/登录
3. 点击个人资料 → API密钥
4. 复制您的密钥

v3推荐语音

这些预制语音针对v3进行了优化，并能很好地配合音频标签使用：

寻找更多声音：

• 浏览：https://elevenlabs.io/voice-library
• v3优化合集：https://elevenlabs.io/app/voice-library/collections/aF6JALq9R6tXwCczjhKH
• API：GET https://api.elevenlabs.io/v1/voices

语音选择提示：

• 使用IVC（即时语音克隆）或预制语音 - PVC尚未针对v3版本进行优化
• 根据您的使用场景匹配语音特性（例如，耳语型语音不适合大声喊叫）
• 若要创建富有表现力的IVC语音，请在训练样本中包含多样化的情感语调

模型设置

• 模型：eleven_v3（alpha版） - 唯一支持音频标签的模型
• 语言：支持70多种语言，并具备完整的音频标签控制功能

稳定性模式

对于音频标签，请使用创意（0.5）或自然。较高的稳定性会降低标签响应性。

速度控制

范围：0.7（慢）至1.2（快），默认1.0

极端值会影响质量。对于节奏控制，建议使用音频标签，例如[急促的]或[拖长的]。

关键规则

长度限制

• 最优：每段少于800字符（最佳质量）
• 最大：10,000字符（API硬性限制）
• 质量随文本变长而下降——语音会变得不一致

音频标签 - 实现自然音效的最佳实践

使用多少个标签：

• 每个句子或短语使用1-2个标签（不要更多！）
• 标签会持续生效直到下一个标签出现 - 无需重复
• 过度使用标签会听起来不自然且机械

标签放置位置：

• 在情感转折点
• 关键戏剧性时刻之前
• 当能量/节奏发生变化时

上下文很重要：

• 撰写与标签情感相匹配的文本
• 带有上下文的较长文本 = 更好的演绎效果
• 示例：[紧张地] 我...我不太确定这个。如果行不通怎么办？比[紧张地] 你好。

效果更好

• 组合标签以表达细微差别：[紧张地][低声说]
• = 紧张地低语=兴奋的笑声
• 标签组合最多2个

重新生成以获得最佳结果：

• v3版本具有非确定性——相同文本=不同输出
• 生成3+个版本，选择最佳
• 细微的文本调整可以改善结果

使标签与声音匹配：

• 请勿在[喊叫]的耳语声音上使用
• 请勿在[耳语]的大声/充满活力的声音上使用
• 用您选择的声音测试标签

不支持SSML

v3版本不支持SSML的break标签。请改用音频标签和标点符号。

标点符号效果（与标签配合使用！）

标点符号增强音频标签：

• 省略号（...）→ 戏剧性的停顿：[紧张] 我...我不知道...
• 大写字母→ 强调：[兴奋地] 这太棒了！
• 破折号（—）→ 用于表示被打断：[解释中] 所以你要做的是——[打断] 等等！
• 问号→ 用于表示不确定：[紧张地] 你确定要这样做吗？
• 感叹号！→ 用于增强活力：[开心地] 我们成功了！

结合标签与标点以达到最佳效果：

[tired] It was a long day... [sighs] Nobody listens anymore.

WhatsApp 语音消息

完整工作流程

1. 生成使用文本转语音工具（返回 MP3 文件）
2. 转换为 Opus 格式（Android 系统必需！）
3. 发送使用消息工具

分步指南

1. 生成TTS（在末尾添加[pause]以防止被截断）：

tts text="[excited] This is amazing! [pause]" channel=whatsapp

返回：MEDIA:/tmp/tts-xxx/voice-123.mp3

2. 将MP3转换为Opus：

ffmpeg -i /tmp/tts-xxx/voice-123.mp3 -c:a libopus -b:a 64k -vbr on -application voip /tmp/tts-xxx/voice-123.ogg

3. 发送Opus文件：

WhatsApp发送语音消息需要一个非空的消息正文。请使用一个空格或点号作为消息：

message action=send channel=whatsapp target="+972..." filePath="/tmp/tts-xxx/voice-123.ogg" asVoice=true message=" "

为什么选择Opus？

始终转换为Opus- 它是唯一一种：

• 在所有设备上都能正常使用的格式（iOS 和 Android）
• 支持WhatsApp的转录按钮

音频截断修复

ElevenLabs有时会截断最后一个词。务必在结尾处添加[停顿]或...：

[excited] This is amazing! [pause]

长篇音频（播客）

对于内容大于800字符的情况：

1. 分割成短片段（每个小于800字符）
2. 使用tts工具
3. 分别生成每个片段

   cat > list.txt << EOF
   file '/path/file1.mp3'
   file '/path/file2.mp3'
   EOF
   ffmpeg -f concat -safe 0 -i list.txt -c copy final.mp3
   

4. 使用ffmpeg拼接：
5. 转换为Opus格式以适配WhatsApp

作为单条语音消息发送重要

：不要提及“第二部分”或“章节”——保持无缝衔接。

多说话人对话

Jessica: [whispers] Did you hear that?
Chris: [interrupting] —I heard it too!
Jessica: [panicking] We need to hide!

v3版本可以在一次生成中处理多个角色：对话标签：[打断]、,[插话],[插嘴]

音频标签速查表

最有效的标签（效果稳定）：

• 情绪：[兴奋]、[紧张]、[悲伤]、[开心]
• 反应：[大笑]、[叹气]、[低语]
• 节奏：[停顿]

效果不稳定（需测试并重新生成）：

• 音效：[爆炸]、[枪声]
• 口音：效果因语音而异

完整标签列表：参见references/audio-tags.md

故障排除

标签会被朗读出来吗？

• 请使用eleven_v3模型
• 使用IVC/预置语音，而非PVC
• 简化标签（不使用“tone”后缀）
• 增加文本长度（250个字符以上）

语音不一致？

• 段落过长 - 请在<800字符处分割
• 重新生成（v3模型具有不确定性）
• 尝试降低稳定性设置

WhatsApp无法播放？

• 转换为Opus格式（参见上文）

尽管使用了标签，但仍无情感表达？

• 语音可能不匹配标签风格
• 尝试创意稳定性模式（0.5）
• 在标签周围添加更多上下文