Voiceforge

命令参考

voiceforge synthesize

单文本 TTS 合成（绕过 LLM，直接合成已有文本）。

voiceforge synthesize --source "待合成文本" -o output.mp3 [OPTIONS]

OPTIONS:
  --engine {minimax|qwen_tts|qwen_omni|qwen}  引擎，默认 minimax
  --voice VOICE_ID                                   音色 ID
  --speed 0.5-2.0                                   语速，默认 1.0
  --emotion {neutral|happy|sad|angry|calm|surprised|fearful|disgusted|fluent}
  --format {mp3|wav}                                 默认 mp3

示例：

# MiniMax 指定音色
voiceforge synthesize --source "欢迎收听本期节目" --voice female-tianmei --speed 1.2 -o intro.mp3

# Qwen Omni
voiceforge synthesize --source "这是一段测试音频" --engine qwen_omni --voice cherry -o test.mp3

voiceforge dialogue

对话脚本解析 + 多角色 TTS 合成。自动分配立体声声道（不同角色左右分离）。

voiceforge dialogue --source DIALOGUE.txt -o output.mp3 [OPTIONS]

OPTIONS:
  --source FILE                   对话脚本文件（支持文件路径或直接文本）
  --engine {minimax|qwen_tts|...} TTS 引擎
  --roles ROLES.json              角色音色映射（可选）
  --bgm MUSIC.mp3                  背景音乐（可选）

对话脚本格式：

[Speaker]: 文本内容
[Speaker, emotion]: 带情感标记的文本

支持同行多角色（无换行分隔）：

[Alex]: 你好[Sam]: 你好 Alex

• Speaker — 角色名，自动映射到音色
• emotion — 可选，MiniMax 支持情感参数

示例：

# 自动音色分配（轮询 cherry/ethan/chelsie）
voiceforge dialogue --source podcast.txt -o podcast.mp3

# 自定义角色音色
voiceforge dialogue --source podcast.txt --roles roles.json -o podcast.mp3

# 加背景音乐
voiceforge dialogue --source podcast.txt --bgm ambient.mp3 -o podcast_bgm.mp3

roles.json 示例：

{
  "Alex": {"voice": "cherry", "speed": 1.1},
  "Sam": {"voice": "ethan", "speed": 0.95}
}

voiceforge studio

LLM 生成播客脚本 → TTS 合成 → FFmpeg 混音，全自动一条龙。

voiceforge studio --topic "播客主题" -o output.mp3 [OPTIONS]

OPTIONS:
  --llm {minimax|qwen}           LLM 引擎（生成脚本），默认 minimax
  --tts {minimax|qwen_tts|...}  TTS 引擎（合成语音），默认 minimax
  --roles ROLES.json             角色音色映射
  --bgm MUSIC.mp3                背景音乐

示例：

# 最常用：MiniMax 全套
voiceforge studio --topic "人工智能的未来" -o ai_podcast.mp3

# Qwen LLM + MiniMax TTS
voiceforge studio --topic "量子计算原理" --llm qwen --tts minimax -o quantum.mp3

# 加背景音乐
voiceforge studio --topic "产品发布会" --bgm ambient.mp3 -o launch.mp3

voiceforge batch

批量文本片段 TTS + FFmpeg 自动合并为单一音频文件。

voiceforge batch --segments "文本1|音色1,文本2|音色2,..." -o output.mp3 [OPTIONS]

OPTIONS:
  --engine {minimax|qwen_tts|...}  TTS 引擎

片段之间自动插入 0.5s 静音间隔。

示例：

voiceforge batch \
  --segments "开头语|cherry,主要内容|ethan,结束语|chelsie" \
  -o episode.mp3

API 配置

优先级：环境变量 > ~/.config/opencode/opencode.json（向后兼容）

MiniMax 配置

# 必需：API Key
export MINIMAX_API_KEY="your-minimax-api-key"

# 可选：Group ID（不设置时使用默认值 "default"）
export MINIMAX_GROUP_ID="your-group-id"

注意：

• MINIMAX_GROUP_ID 现在支持默认值，不设置时自动使用 "default"
• 某些 Anthropic 兼容代理可能不需要 Group ID

Qwen / DashScope 配置

# 方式 1: 使用 QWEN_API_KEY
export QWEN_API_KEY="your-qwen-api-key"

# 方式 2: 使用 DASHSCOPE_API_KEY（等效，推荐）
export DASHSCOPE_API_KEY="your-dashscope-api-key"

# 可选：自定义 Base URL
export DASHSCOPE_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"

重要：

• DASHSCOPE_API_KEY 现已完全支持（TTS 侧和 LLM 侧均支持 fallback）
• Qwen TTS 使用 OpenAI 兼容接口（/chat/completions），而非 /audio/speech 端点
• Qwen Omni 必须使用流式 API（stream=True），已自动处理

从 opencode.json 读取（向后兼容）

opencode.json 结构：

{
  "provider": {
    "minimax": {
      "options": {
        "apiKey": "your-minimax-api-key",
        "groupId": "your-group-id"
      }
    },
    "bailian": {
      "options": {
        "apiKey": "your-dashscope-api-key",
        "baseURL": "https://dashscope.aliyuncs.com/compatible-mode/v1"
      }
    }
  }
}

配置验证

# 验证环境变量
echo $MINIMAX_API_KEY
echo $DASHSCOPE_API_KEY

# 测试 API 连接
python3 -c "
import os
from voiceforge.clients import MiniMaxClient
client = MiniMaxClient(api_key=os.getenv('MINIMAX_API_KEY'))
result = client.text_to_speech('测试', voice_id='male-qn-qingse')
print('✓ MiniMax API 连接成功' if result else '✗ MiniMax API 连接失败')
"

故障排查

常见问题

速率限制处理

当遇到 2056 错误（usage limit exceeded）时：

• ✅ 自动重试：最多 5 次
• ✅ 指数退避：2秒 → 4秒 → 8秒 → 16秒 → 32秒（最大 60 秒）
• ✅ 详细日志：显示重试次数和等待时间

音色测试

部分音色 ID 可能不可用，使用测试工具验证：

# 测试所有音色
python3 scripts/test_voices.py

# 输出示例：
# ✓ 可用音色: male-qn-qingse, female-yujie, presenter_male
# ✗ 不可用音色: male-qn-K, female-tianmei_v2
# 建议替换: male-qn-K → presenter_male

详细故障排查

查阅 完整故障排查指南 了解：

• 安装问题（ffmpeg sudo 权限、apt update hook 报错）
• 运行时问题（CLI 未安装、API Key 缺失、端点 404）
• 性能优化建议
• 问题提交流程

性能优化建议

速率限制处理

• 自动重试：遇到速率限制（1001/1013/1021/2056）时自动重试最多 5 次
• 指数退避：每次重试等待时间翻倍（最大 60 秒）
• 建议：批量合成时建议每段之间间隔 0.5-1 秒，避免触发速率限制

批量处理建议

• 并发控制：批量合成时建议限制并发数（3-5 个并发）
• 内存优化：大批量音频处理时建议分批进行，避免内存溢出
• 缓存策略：重复文本可考虑缓存已合成的音频片段

参考文档

安装与维护

# 安装 / 更新
bash scripts/install.sh

# 卸载
bash scripts/install.sh --uninstall

# 运行测试
python -m pytest tests/ -v

安装后 voiceforge 命令全局可用。