mcpField
D
doubao-tts

doubao-tts

github.com/calesthio创意与媒体72.7k1.1k 次安装今天更新
代码仓库

关于 doubao-tts

面向 OpenMontage 音频生成流程的 Doubao TTS 技能指南，说明语音合成配置、输出文件和时间戳处理。还涵盖长篇旁白的异步接口及字幕制作建议。

主要功能

  1. 01配置 Doubao API 密钥与音色
  2. 02生成语音并保存音频文件
  3. 03获取句子和词语时间戳
  4. 04通过异步接口处理长篇旁白
  5. 05提供字幕制作与故障排查建议

适用场景

  1. 01为视频生成中文旁白
  2. 02试听并确认音色和语速
  3. 03依据语音时间戳制作字幕
  4. 04排查授权、配额或时间戳问题

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/calesthio/openmontage --skill doubao-tts

安装后在 Claude Code 中输入/doubao-tts确认已加载。

详细介绍

Doubao TTS

需要在 .env 中设置 DOUBAO_SPEECH_API_KEY。 设置 DOUBAO_SPEECH_VOICE_TYPE 以指定默认语音，或将 voice_id 传给工具。

当前 API

使用新版控制台的 API Key 流程：

X-Api-Key: ${DOUBAO_SPEECH_API_KEY}
X-Api-Resource-Id: seed-tts-2.0

使用新版控制台的 API Key 时，不要使用 X-Api-App-Id 和 X-Api-Access-Key。如果 API 返回 load grant: requested grant not found，则密钥类型或身份验证请求头可能有误。

对于长篇视频旁白，建议使用异步端点：

POST https://openspeech.bytedance.com/api/v3/tts/submit
POST https://openspeech.bytedance.com/api/v3/tts/query

它会返回 audio_url 以及 sentences[].words[] 时间元数据，可用于制作字幕。

OpenMontage 用法

使用 TTS 选择器生成：

from tools.audio.tts_selector import TTSSelector

result = TTSSelector().execute({
    "preferred_provider": "doubao",
    "text": "如果 AI 真的会改变未来，普通人到底该怎么参与？",
    "voice_id": "zh_female_vv_uranus_bigtts",
    "output_path": "projects/my-video/assets/audio/narration.mp3",
    "speech_rate": 0,
    "enable_timestamp": True,
})

或者直接调用提供方：

from tools.audio.doubao_tts import DoubaoTTS

result = DoubaoTTS().execute({
    "text": "短样本试听文本。",
    "voice_id": "zh_female_vv_uranus_bigtts",
    "output_path": "projects/my-video/assets/audio/doubao_sample.mp3",
})

提供方会写入：

  • output_path：下载的音频文件
  • metadata_path：完整的查询响应 JSON，默认为 <output_path>.json

推荐工作流

  1. 在生成完整的付费旁白前，先生成一段 10-15 秒的样例。
  2. 请用户确认语音的自然度、口音和语速。
  3. 仅在用户确认后生成完整旁白。
  4. 保留查询 JSON。它是字幕时间信息的权威来源。
  5. 根据 sentences[].words[] 制作字幕，不要根据文本长度估算。
  6. 在应用时间戳之前，按中文语义短语分组字幕。不要只按固定字数切分；这样可能会拆开“在不押单个公司的情况下”或“可能会被慢慢稀释”这样的短语，影响理解。
  7. 除非用户明确要求匹配先前的时长，否则应让视频时长遵循已确认的语音节奏。

参数

  • voice_id：Doubao 的 speaker／语音类型。默认为 DOUBAO_SPEECH_VOICE_TYPE。
  • resource_id：Doubao Speech 2.0 语音使用 seed-tts-2.0。
  • speech_rate：0 为正常语速，100 为 2 倍速，-50 为 0.5 倍速。
  • sample_rate：默认为 24000。
  • enable_timestamp：默认为 true。
  • return_usage：默认为 true，用于请求可用的用量元数据。

默认情况下不要传入 additions.explicit_language。有些端点／密钥组合会因 zh-cn 而返回 unsupported additions explicit language zh-cn。

对于平和的普通话讲解，建议从 speech_rate: 0 开始。如果结果对于已确认的格式来说太长，可先用 speech_rate: 25 或 50 生成一段简短的对比样例，再重新生成完整旁白。如果用户更喜欢 Doubao 自然的语速，不要仅仅为了匹配先前提供方的时长而加速。

故障排除

  • load grant: requested grant not found：密钥类型或身份验证请求头有误。新版控制台 API Key 请使用 X-Api-Key。
  • speaker permission denied：语音 ID 错误，或未获授权用于所选资源。
  • quota exceeded：超出配额、生命周期字符数限制或并发限制。
  • 缺少时间戳：确认 enable_timestamp: true，保留查询 JSON，并确认所选端点返回了 sentences。

安全

绝不要将 API Key 打印或写入日志、元数据、补丁或项目产物。.env.example 中只能包含变量名，且变量值留空。

评论

支持 Markdown