ai-proj-helper/skills/doubao-voice-plugin/README.md

豆包语音插件 (Doubao Voice Plugin)

火山引擎豆包语音API集成插件，支持文字转语音(TTS)和唱歌功能。

功能特性

• ✅ 语音合成 (TTS): 文字转语音，支持多种音色 - 已测试可用
• 🎵 唱歌: 让豆包唱歌，支持实时语音交互 - 已开通端到端大模型
• 简单易用: 命令行工具，一行命令即可使用
• 多种音色: 支持女声/男声等多种基础音色
• 实时交互: 支持与豆包进行实时对话和唱歌

快速开始

1. 获取API凭证

访问 火山引擎控制台 创建应用并获取：

• App ID (数字)
• Access Token (长字符串)

开通所需服务：

1. 在控制台勾选 "语音合成" 服务 (TTS)

2. 配置环境变量

方式1: 使用配置脚本 (推荐)

cd scripts
source setup_env.sh  # 自动设置环境变量

方式2: 手动设置

export DOUBAO_APP_ID="your_app_id"
export DOUBAO_ACCESS_TOKEN="your_access_token"

3. 安装依赖

pip3 install requests --break-system-packages

4. 检查凭证

# 检查凭证配置
python3 scripts/check_credentials.py

5. 使用示例

TTS 文字转语音（命令行）

cd scripts

# 基础用法 - ✅ 已测试可用
python3 voice_converter.py tts "你好，我是豆包语音助手" -o output.mp3

# 使用不同音色
python3 voice_converter.py tts "测试男声" -o male.mp3 -v BV701_V2_streaming

唱歌（命令行）🎵

cd scripts

# 让豆包唱歌
python3 singing.py sing "请唱一首关于春天的歌" -o spring.mp3

# 交互式唱歌模式（实时对话）
python3 singing.py interactive

Python 代码方式

# TTS - 文字转语音
from scripts.voice_converter import DoubaoVoiceConverter

converter = DoubaoVoiceConverter()
audio_file = converter.text_to_speech("你好，欢迎使用豆包", output_file="hello.mp3")

# 唱歌
import asyncio
from scripts.singing import DoubaoSinging

async def sing():
    singing = DoubaoSinging()
    audio_file = await singing.sing("请唱一首情歌", output_file="love_song.mp3")

asyncio.run(sing())

自然语言调用

在 Claude Code 中可以使用自然语言调用：

TTS 文字转语音:

• "把这段话转成语音：你好世界"
• "用温柔女声合成语音"
• "用男声朗读这段文字"

唱歌:

• "请唱一首关于春天的歌"
• "唱一个温柔的摇篮曲"
• "开启与豆包的实时语音对话模式"

示例：

用户: "帮我把'欢迎使用豆包语音'转成语音"
Claude: 调用TTS服务生成output.mp3

价格说明

TTS (语音合成)

• 大模型并发版: 2000元/并发/月
• 按量付费: 按字符数计费

免费试用

新用户开通服务后可获得免费额度。

支持的音色

音色代码	描述	场景	状态
BV700_V2_streaming	通用女声	通用场景	✅ V1 可用
BV701_V2_streaming	通用男声	通用场景	✅ V1 可用
BV406_streaming	温柔女声	客服、助手	✅ V1 可用
BV158_streaming	活泼女声	教育、娱乐	✅ V1 可用
BV115_streaming	磁性男声	新闻、播音	✅ V1 可用

注意: 豆包2.0高级音色需要使用V3 API，目前正在调试中。

常见问题

TTS 返回 "requested resource not granted"

解决方法: 在控制台勾选"语音合成"服务选项

Authorization 头格式错误

确保使用 Bearer;{token} 格式（注意分号），而不是 Bearer {token}

环境变量未生效

# 检查环境变量
echo $DOUBAO_APP_ID
echo $DOUBAO_ACCESS_TOKEN

# 如果为空，重新设置
source setup_env.sh

API 版本说明

V1 API (当前使用) ✅

• 状态: 已测试，稳定可用
• 认证: Bearer Token
• 音色: 支持基础音色
• 推荐: 日常使用推荐

V3 API (豆包2.0) ⚠️

• 状态: 调试中，存在 "get resource id empty" 问题
• 认证: Bearer Token + Resource-Id
• 音色: 支持豆包2.0高级音色
• 说明: 需要联系火山引擎技术支持获取正确配置

技术支持

• 官方文档
• 控制台
• 计费说明

许可证

本插件遵循 MIT 许可证。

作者

qiudl @ zhiyuncai.com