介绍
# ElevenLabs Voice Personas v2.1
使用 ElevenLabs API 的全面语音合成工具包。
## 🚀 首次运行 - 设置向导
当您首次使用此技能（不存在 `config.json`）时，请运行交互式设置向导：
```bash python3 scripts/setup.py ```
向导将引导您完成以下步骤： 1. **API 密钥** - 输入您的 ElevenLabs API 密钥（必填） 2. **默认语音** - 从热门语音中选择（Rachel, Adam, Bella 等） 3. **语言** - 设置您的首选语言（支持 32 种） 4. **音频质量** - 标准或高质量输出 5. **成本追踪** - 启用使用量和成本监控 6. **预算限制** - 可选的每月支出上限
**🔒 隐私：** 您的 API 密钥仅存储在本地 `config.json` 中。它绝不会离开您的机器，并会通过 `.gitignore` 自动从 git 中排除。
如需随时重新配置，只需再次运行设置向导。
---
## ✨ 功能
- **18 种语音角色** - 针对不同用例精心挑选的语音 - **32 种语言** - 支持多语言模型 v2 的多语言合成 - **流式传输模式** - 生成时实时输出音频 - **音效 (SFX)** - 根据文本提示生成 AI 音效 - **批量处理** - 一次性处理多个文本 - **成本追踪** - 监控字符使用量和预估成本 - **语音设计** - 根据描述创建自定义语音 - **发音词典** - 自定义单词发音规则 - **OpenClaw 集成** - 与 OpenClaw 内置的 TTS 配合使用
---
## 🎙️ 可用语音
| Voice | 口音 | 性别 | 角色 | 最适用场景 | |-------|--------|--------|---------|----------| | rachel | 🇺🇸 US | female | 温暖 | 对话、教程 | | adam | 🇺🇸 US | male | 旁白 | 纪录片、有声书 | | bella | 🇺🇸 US | female | 专业 | 商务、演讲 | | brian | 🇺🇸 US | male | 抚慰 | 冥想、平静内容 | | george | 🇬🇧 UK | male | 讲故事的人 | 有声书、故事讲述 | | alice | 🇬🇧 UK | female | 教育者 | 教程、讲解 | | callum | 🇺🇸 US | male | 恶作剧者 | 俏皮、游戏 | | charlie | 🇦🇺 AU | male | 充满活力 | 体育、激励 | | jessica | 🇺🇸 US | female | 俏皮 | 社交媒体、休闲 | | lily | 🇬🇧 UK | female | 女演员 | 戏剧、优雅内容 | | matilda | 🇺🇸 US | female | 专业 | 企业、新闻 | | river | 🇺🇸 US | neutral | 中性 | 包容性、信息丰富 | | roger | 🇺🇸 US | male | 随意 | 播客、轻松 | | daniel | 🇬🇧 UK | male | 播音员 | 新闻、公告 | | eric | 🇺🇸 US | male | 值得信赖 | 商务、企业 | | chris | 🇺🇸 US | male | 友好 | 教程、亲切 | | will | 🇺🇸 US | male | 乐观主义者 | 激励、振奋人心 | | liam | 🇺🇸 US | male | 社交 | YouTube、社交媒体 |
## 🎯 快速预设
- `default` → rachel (温暖、友好) - `narrator` → adam (纪录片) - `professional` → matilda (企业) - `storyteller` → george (有声书) - `educator` → alice (教程) - `calm` → brian (冥想) - `energetic` → liam (社交媒体) - `trustworthy` → eric (商务) - `neutral` → river (包容性) - `british` → george - `australian` → charlie - `broadcaster` → daniel (新闻)
---
## 🌍 支持的语言 (32 种)
多语言 v2 模型支持以下语言：
| Code | 语言 | Code | 语言 | |------|----------|------|----------| | en | 英语 | pl | 波兰语 | | de | 德语 | nl | 荷兰语 | | es | 西班牙语 | sv | 瑞典语 | | fr | 法语 | da | 丹麦语 | | it | 意大利语 | fi | 芬兰语 | | pt | 葡萄牙语 | no | 挪威语 | | ru | 俄语 | tr | 土耳其语 | | uk | 乌克兰语 | cs | 捷克语 | | ja | 日语 | sk | 斯洛伐克语 | | ko | 韩语 | hu | 匈牙利语 | | zh | 中文 | ro | 罗马尼亚语 | | ar | 阿拉伯语 | bg | 保加利亚语 | | hi | 印地语 | hr | 克罗地亚语 | | ta | 泰米尔语 | el | 希腊语 | | id | 印尼语 | ms | 马来语 | | vi | 越南语 | th | 泰语 |
```bash # Synthesize in German python3 tts.py --text "Guten Tag!" --voice rachel --lang de
# Synthesize in French python3 tts.py --text "Bonjour le monde!" --voice adam --lang fr
# List all languages python3 tts.py --languages ```
---
## 💻 CLI 用法
### 基础文本转语音
```bash # List all voices python3 scripts/tts.py --list
# Generate speech python3 scripts/tts.py --text "Hello world" --voice rachel --output hello.mp3
# Use a preset python3 scripts/tts.py --text "Breaking news..." --voice broadcaster --output news.mp3
# Multi-language python3 scripts/tts.py --text "Bonjour!" --voice rachel --lang fr --output french.mp3 ```
### 流式传输模式
使用实时流式传输生成音频（适用于长文本）：
```bash # Stream audio as it generates python3 scripts/tts.py --text "This is a long story..." --voice adam --stream
# Streaming with custom output python3 scripts/tts.py --text "Chapter one..." --voice george --stream --output chapter1.mp3 ```
### 批量处理
从文件处理多个文本：
```bash # From newline-separated text file python3 scripts/tts.py --batch texts.txt --voice rachel --output-dir ./audio
# From JSON file python3 scripts/tts.py --batch batch.json --output-dir ./output ```
**JSON 批量格式：** ```json [ {"text": "First line", "voice": "rachel", "output": "line1.mp3"}, {"text": "Second line", "voice": "adam", "output": "line2.mp3"}, {"text": "Third line"} ] ```
**简单文本格式（每行一个）：** ``` Hello, this is the first sentence. This is the second sentence. And this is the third. ```
### 使用统计
```bash # Show usage stats and cost estimates python3 scripts/tts.py --stats
# Reset statistics python3 scripts/tts.py --reset-stats ```
---
## 🎵 音效 (SFX)
根据文本描述生成 AI 驱动的音效：
```bash # Generate a sound effect python3 scripts/sfx.py --prompt "Thunder rumbling in the distance"
# With specific duration (0.5-22 seconds) python3 scripts/sfx.py --prompt "Cat meowing" --duration 3 --output cat.mp3
# Adjust prompt influence (0.0-1.0) python3 scripts/sfx.py --prompt "Footsteps on gravel" --influence 0.5
# Batch SFX generation python3 scripts/sfx.py --batch sounds.json --output-dir ./sfx
# Show prompt examples python3 scripts/sfx.py --examples ```
**提示词示例：** - "远方雷声隆隆" - "猫咪满足地呼噜" - "在机械键盘上打字" - "飞船引擎嗡嗡作响" - "咖啡店背景嘈杂声"
---
## 🎨 语音设计
根据文本描述创建自定义语音：
```bash # Basic voice design python3 scripts/voice-design.py --gender female --age middle_aged --accent american \ --description "A warm, motherly voice"
# With custom preview text python3 scripts/voice-design.py --gender male --age young --accent british \ --text "Welcome to the adventure!" --output preview.mp3
# Save to your ElevenLabs library python3 scripts/voice-design.py --gender female --age young --accent american \ --description "Energetic podcast host" --save "MyHost"
# List all design options python3 scripts/voice-design.py --options ```
**语音设计选项：**
| Option | Values | |--------|--------| | 性别 | male, female, neutral | | 年龄 | young, middle_aged, old | | 口音 | american, british, african, australian, indian, latin, middle_eastern, scandinavian, eastern_european | | 口音强度 | 0.3-2.0 (subtle to strong) |
---
## 📖 发音词典
自定义单词发音方式：
编辑 `pronunciations.json`： ```json { "rules": [ { "word": "OpenClaw", "replacement": "Open Claw", "comment": "Pronounce as two words" }, { "word": "API", "replacement": "A P I", "comment": "Spell out acronym" } ] } ```
用法： ```bash # Pronunciations are applied automatically python3 scripts/tts.py --text "The OpenClaw API is great" --voice rachel
# Disable pronunciations python3 scripts/tts.py --text "The API is great" --voice rachel --no-pronunciations ```
---
## 💰 成本追踪
该技能会追踪您的字符使用量并预估成本：
```bash python3 scripts/tts.py --stats ```
**输出：** ``` 📊 ElevenLabs Usage Statistics
Total Characters: 15,230 Total Requests: 42 Since: 2024-01-15
💰 Estimated Costs: Starter $4.57 ($0.30/1k chars) Creator $3.66 ($0.24/1k chars) Pro $2.74 ($0.18/1k chars) Scale $1.68 ($0.11/1k chars) ```
---
## 🤖 OpenClaw TTS 集成
### 与 OpenClaw 内置 TTS 配合使用
OpenClaw 具有内置的 TTS 支持，可以使用 ElevenLabs。在 `~/.openclaw/openclaw.json` 中配置：
```json { "tts": { "enabled": true, "provider": "elevenlabs", "elevenlabs": { "apiKey": "your-api-key-here", "voice": "rachel", "model": "eleven_multilingual_v2" } } } ```
### 在聊天中触发 TTS
在 OpenClaw 对话中： - 使用 `/tts on` 启用自动 TTS - 直接使用 `tts` 工具进行一次性语音 - 请求“朗读这个”或“说出来”
### 从 OpenClaw 使用技能脚本
```bash # OpenClaw can run these scripts directly exec python3 /path/to/skills/elevenlabs-voices/scripts/tts.py --text "Hello" --voice rachel ```
---
## ⚙️ 配置
脚本按以下顺序查找 API 密钥：
1. `ELEVEN_API_KEY` 或 `ELEVENLABS_API_KEY` 环境变量 2. OpenClaw 配置 (`~/.openclaw/openclaw.json` → tts.elevenlabs.apiKey) 3. 技能本地 `.env` 文件
**创建 .env 文件：** ```bash echo 'ELEVEN_API_KEY=your-key-here' > .env ```
---
## 🎛️ 语音设置
每个语音都针对最佳输出进行了调整：
| Setting | Range | Description | |---------|-------|-------------| | stability | 0.0-1.0 | 越高 = 一致性越好，越低 = 表现力越强 | | similarity_boost | 0.0-1.0 | 与原声的匹配程度 | | style | 0.0-1.0 | 说话风格的夸张程度 |
---
## 📝 触发器
- "use {voice_name} voice" (使用 {voice_name} 语音) - "speak as {persona}" (以 {persona} 的身份说话) - "list voices" (列出语音) - "voice settings" (语音设置) - "generate sound effect" (生成音效) - "design a voice" (设计语音)
---
## 📁 文件
``` elevenlabs-voices/ ├── SKILL.md # This documentation ├── README.md # Quick start guide ├── config.json # Your local config (created by setup, in .gitignore) ├── voices.json # Voice definitions & settings ├── pronunciations.json # Custom pronunciation rules ├── examples.md # Detailed usage examples ├── scripts/ │ ├── setup.py # Interactive setup wizard │ ├── tts.py # Main TTS script │ ├── sfx.py # Sound effects generator │ └── voice-design.py # Voice design tool └── references/ └── voice-guide.md # Voice selection guide ```
---
## 🔗 链接
- [ElevenLabs](https://elevenlabs.io) - [API 文档](https://docs.elevenlabs.io) - [语音库](https://elevenlabs.io/voice-library) - [音效 API](https://elevenlabs.io/docs/api-reference/sound-generation) - [语音设计 API](https://elevenlabs.io/docs/api-reference/voice-generation)
---
## 📋 更新日志
### v2.1.0 - 新增交互式设置向导 (`scripts/setup.py`) - 引导完成 API 密钥、语音、语言、质量和预算设置的入门指南 - 配置存储在本地 `config.json` 中（已添加到 `.gitignore`） - 专业、注重隐私的设置体验
### v2.0.0 - 新增 `--lang` 参数，支持 32 种语言 - 新增 `--stream` 标志，支持流式传输模式 - 新增音效生成 (`sfx.py`) - 新增 `--batch` 标志，支持批量处理 - 新增 `--stats` 标志，支持成本追踪 - 新增语音设计工具 (`voice-design.py`) - 新增发音词典支持 - 新增 OpenClaw TTS 集成文档 - 改进错误处理和进度输出