doubao-speech-mcp

豆包语音云 API 的 stdio MCP server。接口依据官方目录于 2026-10-10 核对。

0.4.0 按用途重组工具：一件事只有一个入口，常用能力全部是具名参数，只剩 speech_raw_request 需要手写官方 JSON。默认暴露 18 个工具（原 29 个）；实时会话和管理接口改为按需启用。这是不兼容变更，旧工具名不保留别名，对照见下方迁移。

按需启用（设 MCP_TOOL_GROUPS 后重启，如 speech,voice,jobs,help,realtime）：

所有具名参数工具都有 parameters：官方请求体里工具没单独列出的字段（SSML、水印、bit_rate、ssd_version 等）深度合并进去，同名以 parameters 为准；TTS 的 req_params.additions 可直接写成对象。提交类调用只提交一次，查询不会重新提交或购买资源。

环境变量

音频生成和播客可能超过300秒，客户端需设置相应超时。异步任务提交前先写本地记录，get_job 完成时自动把官方临时 URL 的结果下载到输出目录。

本地运行与验证：

uv sync --project servers/doubao-speech
uv run --project servers/doubao-speech doubao-speech-mcp
servers/doubao-speech/.venv/bin/python -m unittest discover -s servers/doubao-speech/tests -v

MCP 客户端本地启动命令可指定本项目 .venv/bin/doubao-speech-mcp 的绝对路径。已安装的 GitHub 版本需在发布后升级并重启客户端，本次源码修改不会自动替换已经运行的 server。

调用示例

完整示例与技巧见 使用指南。MCP 内可直接调用 get_speech_usage_examples，返回官方模板分析、工具参数、技巧和来源链接：

{"product": "audio", "category": "timing"}

product 支持 audio、tts、voice、podcast、asr、translation、minutes、realtime；仅 audio 支持 category=text/reference/timing/multilingual。省略分类返回该产品全部示例。示例为根据官方用法改写，文件路径、URL、分配音色 ID、会话 ID 需替换；查询示例不会上传或生成音频。

音频生成 1.0：官方四类用法

2026-10-09 核对官方体验中心的模板分类：文本生成、参考生成、时间控制、多语种。四类均使用 generate_audio，可以组合使用；以下 JSON 是 MCP 工具参数，示例提示词为根据官方用法改写，未做真实云端生成验证。

文本生成：先定义角色和场景，再按发生顺序编排声音；台词用引号，区分台词与表演指令。

{
  "prompt": "雨声持续。青年女子嗓音清亮，紧张地说：‘有人来了。’随后响起三声敲门声，低音弦乐渐强。",
  "model": "seed-audio-1.0",
  "format": "mp3"
}

参考生成：样音列表的第一条对应 @音频1，第二条对应 @音频2。多人对白要明确每个角色的引用关系；下列绝对路径需替换为真实文件，也可以传可访问的音频 URL。最多3段，每段不超过30秒、10MB。

{
  "prompt": "主持人甲参考@音频1的音色，热情地说：‘欢迎。’主持人乙参考@音频2的音色，轻笑着说：‘你好。’随后两人自然地笑起来。",
  "reference_audios": ["/absolute/path/host_a.wav", "/absolute/path/host_b.wav"],
  "format": "mp3"
}

需要指定现有音色时可用 speaker；图片参考用 reference_image（本地绝对路径或URL），不能与 speaker 或 reference_audios 混用。图片参考是 API 支持的另一种输入方式，不是体验中心第五个模板分类。

时间控制：官方输入提示使用 [2s:5s]，音效卡点模板使用 [2.7s:5.7s] 等小数秒区间。将标记写在对应台词或声音事件前，同时描述停顿、情绪递进、转场和声音强弱。

{
  "prompt": "总长10秒，雨声持续。女子轻声说道：[2.7s:5.7s]‘你终于回来了。’[6s:7s]响起敲门声，最后雨声渐弱。",
  "subtitles": true,
  "format": "mp3"
}

区间标记随 prompt 原样传给官方 text_prompt；没有独立的 timeline 参数，也不在 MCP 内做音频裁切或强制对齐。subtitles=true 返回的是生成后的人声字幕，subtitle.sentences 及其 words 的 start_time / end_time 单位为毫秒，不标注所有音效。实际时间落点需核对音频与字幕；不要把提示词控制理解为每次严格命中指定时间。单次最长120秒，台词过长或区间过短可能影响节奏。

多语种：目标语言台词配合角色、口音和表演说明；不需要额外的 language 参数。官方英语模板用英文描述人物声线、标准美式英语、情绪、环境音和配乐。

{
  "prompt": "A young woman speaks warm, clear American English: ‘Welcome home.’ Soft piano continues underneath. A young man replies quietly: ‘It is good to be back.’",
  "format": "mp3",
  "subtitles": true
}

语言支持清单以官方音频生成 API为准，控制台模板展示与 API 列举可能不同。四类用法及参数示例也已写入 generate_audio 的工具描述，客户端发现工具时即可读取。

长文本、识别与妙记

长文本合成（超过 5000 字自动异步，long_text=true 强制）：

{"text": "长文本……", "voice": "zh_female_vv_uranus_bigtts", "long_text": true}

立即返回 job_id；get_job(job_id=..., wait=30) 查询，完成后 speech.mp3 保存到输出目录。异步模式 format 只能是 mp3 / pcm / ogg_opus，subtitles 输出 sentences.json。

会议录音区分说话人（自动用标准版，音频须是可下载 URL）：

{"audio": "https://example.com/meeting.wav", "speakers": true, "parameters": {"request": {"ssd_version": "300"}}}

妙记：

{"file_url": "https://example.com/meeting.wav", "summary": true, "chapters": true, "todos": true}

bundle_billing（官方 AllActivate）只选择打包计费，不会开启功能。复刻先用 clone_voice 注册已分配的 S_ 音色，get_voice 查训练结果，再 text_to_speech(voice="S_...") 合成。

实时会话（需启用 realtime 组）

最简配置：

{"session":{"audio":{"output":{"voice":"zh_female_vv_jupiter_bigtts"}}}}

1. 使用返回的客户端 session_id，通过 send_realtime_event 发送 input_audio_buffer.append 与 audio_file（16kHz / mono / int16 裸 PCM），或事件里的 Base64 audio。
2. 发送 input_audio_buffer.commit 强制判停，或由服务端判断停顿。
3. receive_realtime_events 接收转写、回复、音频路径、工具调用和用量。音频 delta 自动落盘，附格式和采样率，不返回巨大 Base64。
4. 调用者执行 Function Calling，再通过 conversation.item.create 回传 role=tool 和对应 call_id。可发送 response.cancel 打断、上下文增删查和 session.update。
5. close_realtime_session 等待关闭确认并释放连接；MCP 退出也会清理全部会话。

实时上传20ms一包。MCP 不直接采集麦克风、播放声音或驱动声卡，客户端负责设备输入输出。同传需16kHz / mono / 16bit WAV或PCM；WAV自动去容器。目标 PCM16k 保存有效WAV，PCM24k保留float32原始PCM并返回格式信息。

播客断线保留 .partial.*、task_id 和 last_finished_round_id，可通过 parameters.retry_info 显式续传；返回的是续传片段，不自动和旧文件合并。

从 0.3.x 迁移

clone_voice.language 现在接受 zh、en 等代码并转换为官方整数枚举；旧版示例里的字符串写法不符合官方契约。

官方来源与覆盖边界

新增接口来源包括长文本提交、音色注册、音色设计、实时识别、播客、实时3.0、同传、机器翻译、妙记、热词、替换词及控制台OpenAPI。

Speech SDK的离线模型、端侧VAD / 音频处理和Android / iOS接入需原生应用，不能等同于云MCP。术语词表CRUD官方仅公开控制台流程；翻译 / 同传通过 glossary、glossary_table_id（或 parameters 里的 glossary_table_name）使用术语。同传官方附件的Protobuf尚未声明文档新增的 detected_language，本版不猜字段编号。

历史产品使用独立工具与旧版凭据，返回各操作的精确官方 source 链接。传统 /api/v2/asr 旧 WebSocket 协议未重复实现；一句话和流式识别功能通过现行大模型接口提供。实时对话采用最新3.0，未复制旧1.0/2.0会话协议。所有产品覆盖不等于每个历史 SDK / 协议版本都已适配。

_ast/ 的Protobuf bindings来自同传官方Python示例，生成日期2026-06-12，调整为包内相对import；运行依赖 mcp、websockets、protobuf。

离线测试覆盖HTTP合同、任务状态、签名、Protobuf、二进制帧、模拟WebSocket收发、音频文件、超时 / 取消清理，以及实际stdio MCP初始化、工具发现与调用。未调用付费云接口，因此不能证明账号开通、配额可用或实际生成质量。

参数说明见工具描述（src/doubao_speech_mcp/server.py）。接口细节以官方文档为准：单向流式语音合成、录音文件识别极速版、音频生成、音色列表。

运行时与稳定性

共享连接池、总超时、工具分组、错误语义和迁移说明见 MCP 构建与稳定性。完整工具说明可调用 get_tool_help(tool="工具名")。