Doubao Podcast TTS

---

name: doubao-podcast description: | Use when calling Doubao/ByteDance podcast TTS API to generate audio, parsing WebSocket binary frames, handling streaming audio chunks, extracting audio_url from PodcastEnd, troubleshooting podcast generation timeout or stuck issues, or designing podcast playback architecture (streaming vs non-streaming). Also use when: integrating podcast generation into a browser-based app (browser WebSocket cannot set custom headers), designing content caching to avoid redundant generation, or extracting article metadata for podcast titles. Trigger even without explicit mention of "Doubao" — any podcast TTS, ByteDance speech synthesis, or podcast generation task should use this skill.

---

豆包播客 TTS API 集成指南

基于 7 篇微信长文 POC + 线上生产环境的实战经验。覆盖从建连到拿到 mp3 的全流程，以及 11 条踩坑记录。

1. 接口概览

| 项 | 值 | |----|-----| | 协议 | WebSocket 二进制协议 v3 | | 地址 | wss://openspeech.bytedance.com/api/v3/sami/podcasttts | | 鉴权 | 4 个 Header：X-Api-App-Id、X-Api-Access-Key、X-Api-Resource-Id、X-Api-App-Key | | Resource ID | volc.service_type.10050 | | 输出 | MP3, 96kbps, 24kHz mono（固定） |

2. 二进制协议

豆包使用自定义二进制帧，不是标准 JSON WebSocket。

帧头（固定 4 字节）

[0x11, 0x14, 0x10, 0x00]

第 2 字节高 4 位 = message_type（0xF = 错误帧）

第 2 字节低 4 位 = flags（0x04 = 含 session_id）

第 3 字节高 4 位 = serialization（1=JSON, 0=binary audio）

两种帧格式

Pre-connection:  header(4) + event_type(4, big-endian) + payload_size(4) + payload
Post-connection: header(4) + event_type(4) + sid_len(4) + session_id + payload_size(4) + payload

构造/解析代码

Python 版本见 scripts/generate_podcast.py。Node.js 版本：

const HEADER = Buffer.from([0x11, 0x14, 0x10, 0x00]);
function preFrame(event, payload) {
  const p = Buffer.from(JSON.stringify(payload));
  const e = Buffer.alloc(4); e.writeUInt32BE(event);
  const l = Buffer.alloc(4); l.writeUInt32BE(p.length);
  return Buffer.concat([HEADER, e, l, p]);
}
function postFrame(event, sid, payload) {
  const sb = Buffer.from(sid);
  const p = Buffer.from(JSON.stringify(payload));
  const e = Buffer.alloc(4); e.writeUInt32BE(event);
  const sl = Buffer.alloc(4); sl.writeUInt32BE(sb.length);
  const pl = Buffer.alloc(4); pl.writeUInt32BE(p.length);
  return Buffer.concat([HEADER, e, sl, sb, pl, p]);
}
function parseEvent(data) {
  const buf = Buffer.from(data);
  if (buf.length < 8) return { eventType: null, payload: {} };
  const mt = (buf[1] >> 4) & 0xF;
  const fl = buf[1] & 0xF;
  const ser = (buf[2] >> 4) & 0xF;
  if (mt === 0xF) { /* 错误帧 */ return { eventType: -1, payload: {} }; }
  const evt = buf.readUInt32BE(4);
  let off = 8, payload = {};
  if (fl & 0x04) {
    const sl = buf.readUInt32BE(off); off += 4 + sl;  // 跳过 session_id
    const pl = buf.readUInt32BE(off); off += 4;
    if (pl > 0 && ser === 1) try { payload = JSON.parse(buf.slice(off, off + pl).toString()); } catch {}
  }
  return { eventType: evt, payload };
}

3. 握手流程与事件表

客户端                                豆包 API
  │── StartConnection(event=1) ────→│
  │←── ConnectionStarted(event=50) ─│  ← session_id 在二进制帧中
  │── StartSession(event=100) ─────→│  ← 携带播客参数
  │←── SessionStarted(event=150) ───│
  │  ┌── 流式循环 ──────────────────┐
  │←─┤ 360: RoundStart (JSON)      │  ← 文案文本（第1轮为空！见坑10）
  │←─┤ 361: RoundResp (binary)     │  ← 音频块 ~4.6KB/chunk
  │←─┤ 362: RoundEnd (JSON)        │
  │  └─────────────────────────────┘
  │←── 363: PodcastEnd (JSON) ─────│  ← audio_url（⚠️ duration_sec 可能为 0，见坑9）
  │←── 152: SessionFinished ───────│  ← ⚠️ 经常不来，见坑2
  │── FinishConnection(event=2) ──→│

事件速查

| event | 名称 | payload | 关键字段 | |-------|------|---------|---------| | 1/2 | Start/FinishConnection | {} | — | | 50 | ConnectionStarted | 二进制 | session_id 在帧中提取 | | 100 | StartSession | JSON | 播客参数 | | 360 | RoundStart | JSON | text（第 1 轮为空） | | 361 | RoundResp | binary | 音频块 | | 363 | PodcastEnd | JSON | meta_info.audio_url |

提取 session_id（ConnectionStarted 帧）

const buf = Buffer.from(data);
let off = 8;
const sidLen = buf.readUInt32BE(off); off += 4;
const sessionId = buf.slice(off, off + sidLen).toString();

4. 两种输入模式

input_url（URL 文章）

{
  input_info: { input_url: "https://...", return_audio_url: true },  // ⚠️ url 在 input_info 内
  use_head_music: true, use_tail_music: false,
  audio_config: { format: "mp3", sample_rate: 24000, speech_rate: 0 },
  speaker_info: { random_order: true, speakers: ["zh_male_dayixiansheng_v2_saturn_bigtts", "zh_female_mizaitongxue_v2_saturn_bigtts"] }
}

input_text（短文本 < 200 字）

{
  input_text: "文本内容...",  // ⚠️ text 在顶层，不是 input_info
  audio_config: { ... },
  speaker_info: { ... }
}

5. 实战踩坑记录（11 条）

坑 1：input_url vs input_text 参数位置

❌ {"input_url": "https://..."}                  → 顶层没这字段，静默失败
✅ {"input_info": {"input_url": "https://..."}}  → URL 模式正确用法
✅ {"input_text": "你好世界"}                     → 短文本模式正确用法

搞反了不会报错，只会得到空结果。

坑 2：PodcastEnd 之后不要等 SessionFinished

SessionFinished(152) 经常不来或等 10 分钟+。PodcastEnd(363) 拿到 audio_url 后立即 break。

if (eventType === 363) {
  const url = payload.meta_info?.audio_url || '';
  ws.close();  // 立即关闭！
  resolve({ audioUrl: url });
}

不加 break，5 分钟播客可能跑 15 分钟。这是最致命的坑。

坑 3：超时设 900s

| 文章长度 | 播客时长 | 生成耗时 | |---------|---------|---------| | ~2000字 | ~5 min | ~2.5 min | | ~5000字 | ~10 min | ~4 min | | ~25000字 | ~30 min | ~10 min |

统一设 TIMEOUT = 900（15 分钟）。

坑 4：WebSocket 连接参数

Python: ping_timeout=120，不设的话长文生成时会心跳超时断开。 Node.js: ws 库默认无 ping，不需要额外设置。

坑 5：连接断开但已有音频块

音频块是完整 MP3 片段，直接拼接就是可播放文件。断连时不要丢弃已收到的块。

坑 6：audio_url 24 小时过期

CDN URL 签名过期后返回 403。生成完成后立即下载 mp3 到自己的存储。

坑 7：Python nohup 输出缓冲

后台运行加 python -u（unbuffered）才能看到实时日志。

坑 8：浏览器 WebSocket 不支持自定义 Header ⭐

浏览器 new WebSocket(url) 无法设置 HTTP Header。豆包需要 4 个鉴权 Header → 必须走服务端代理。

推荐架构：

浏览器 ── POST /api/podcast ──→ 服务端 ── WSS + Header ──→ 豆包
       ← SSE 流式进度 ────────         ← 二进制帧 ──────

服务端用 Node.js ws 库（支持自定义 Header）连接豆包，通过 SSE（Server-Sent Events）把进度推给浏览器。凭证存在服务端，不暴露给前端。

坑 9：duration_sec 经常返回 0 ⭐

PodcastEnd 的 meta_info.duration_sec 实测经常为 0 或不返回。

备用方案：根据音频大小估算（96kbps = 12KB/s）：

const durationSec = meta.duration_sec || Math.round(totalAudioBytes / 12000);

坑 10：RoundStart 第一轮文案为空 ⭐

第 1 轮是片头音乐，text 字段为空字符串。第 2 轮开始才有实际文案内容。

如果需要从文案中提取标题/主题，从 Round 2+ 的文案中取。

坑 11：微信文章标题无法从服务端抓取 ⭐

从中国云服务器 fetch 微信文章会返回"环境异常"页面（反爬）。标题提取备用方案：

1. 优先：fetch 文章页面提取