抖音语音直播间监控与逐字稿

监控抖音语音（连麦）直播间：用 Playwright 以有头方式打开房间页，持续读取页面文字流
（麦上发言的 ASR 字幕 + 评论区），重建「谁、什么时候、说了什么」的完整逐字稿，
并产出自包含的单文件四板块报告。

什么时候用、什么时候不能用

适用：用户给出抖音直播链接，要求「监控 N 分钟」「看他们在聊什么」「生成逐字稿」「评论区在说什么」。

必须先分清房间类型——这决定产出物的天花板：

视频直播房抓不到「在聊什么」，只能给评论区 + 房间数据。遇到这种情况必须如实告知用户，不要假装产出了逐字稿。

能抓到什么（已实测）

⚠️ 三条硬约束（违反必失败）

1. 必须有头模式（DOUYIN_HEADLESS 不设或 =0）。无头模式抖音只把侧栏渲染成「需先登录，才能开始聊天」占位，
   .webcast-chatroom___item 一个都不生成 —— 整个评论区静默丢失，而日志只显示「评论 0 条」，极易误判成「这场没人说话」。
   - 判据只看 .webcast-chatroom___item 的渲染数量（即 chats.json 条数）。
   - ⚠️ 别拿「需先登录，才能开始聊天」当判据 —— 那是输入框占位符，有头模式同样存在。
   - 启动 60 秒内看一眼日志里的「评论 N 条」，仍为 0 就立刻停掉重跑，别白等。
2. 采集窗口可以最小化，但绝不能关闭。窗口关闭 → 报 Target page, context or browser has been closed，采集立即中断。
3. 采集命令必须前台运行，单段不超过 300s。多数 Agent 工具的前台命令硬上限是 600s；
   而 300s 采集实测约 310s，一次调用只够跑一段。放后台常在一两分钟内被回收。

快速开始

# 0) 环境自检（首次使用先跑；会实启一次浏览器）
node scripts/run_monitor.js doctor

# 1) 开播自检 —— 长任务前必做，房间已下播就直接结束，别空采
node scripts/run_monitor.js check https://live.douyin.com/<房间号> --sec 40

# 2) 登记计划：2 段 × 300s = 10 分钟；--shot 250 表示每 250ms 截一张图
node scripts/run_monitor.js plan <采集目录> --url <房间号或短链> --segments 2 --seg 300 --shot 250 --title "房间名"

# 3) 逐段采集：每段一次调用（约 5 分 10 秒），10 分钟就跑 2 次
node scripts/run_monitor.js next <采集目录>
node scripts/run_monitor.js status <采集目录>          # 随时看段进度 / 截图数 / 产物

# 4) 出交付物（逐字稿 → HTML → 汇总表 xlsx → 打包 + 截图回放页）
node scripts/run_monitor.js finish <采集目录> <交付目录> <标签如 1010-1020>

plan / next 会在采集目录里维护 _plan.json，自动处理两件最容易错的事：
每段截图起始编号自动续号；第 2 段起自动带追加标志（继承评论与统计，不覆盖上一段）。

check 的退出码：0 = 在播，2 = 疑似已结束。

常用环境变量

产出物

finish 会在交付目录生成：

• 抖音直播逐字稿_<标签>.md / .html —— 逐字稿（原文完整、不总结、不删改）+ 评论区完整记录
• 抖音直播监控汇总表_<标签>.xlsx —— 6 个 sheet 的统计汇总（需 Python + openpyxl）
• 截图回放_<间隔>.html + 截图/ —— 按分钟分组的截图回放页（文件名随截图间隔变化，如 截图回放_每250ms一张.html）
• 采集原始数据/ —— raw_samples.jsonl、chats.json、transcript.json、meta.json 等，供复核与重算

用户要「一个 HTML、分几个板块/按钮」时

改用四板块单文件页（这是更常用的交付形态）：

# 1) 生成截图缩略图（需 Python + Pillow）——否则 2000+ 张原图内嵌会让 HTML 涨到几百 MB
python scripts/make_thumbs.py <采集目录> <采集目录>/thumbs_b64.json --every 5 --width 700 --quality 72 --keys 8
# 2) 组装四标签页单文件（先用 ASCII 路径落地）
node scripts/build_console.js <采集目录> <采集目录>/_console.html <标签>
# 3) 打包（中文文件名走 UTF-8 的 _deliver.json，见下）
node scripts/publish_console.js <采集目录>

四个板块：① 对话逐字稿 ② 截图（等距缩略图按分钟分组 + 全尺寸关键帧）③ 智能总结 ④ 数据看板 · 评论区全量。

• ③ 智能总结的内容由你（Agent）读完整逐字稿后写进 <采集目录>/summary.json，脚本只负责渲染。
  字段：headline / topics[].points / topics[].quotes / quotes / leads / audience / limits。
  每一场都要重新读稿再写，不要把上一场的内容留在文件里。缺失时该页显示「未生成」，不会报错。
• 图片必须 base64 内嵌：四板块页常被单独复制或在预览面板打开，./截图/xxx.jpg 相对路径会裂。
  全量原图另放交付目录的 截图_*/，缩略图只作浏览索引。
• 中文文件名不要写进命令行字面量（Windows PowerShell 下会粘连/乱码）：
  写一个 UTF-8 的 _deliver.json，由 publish_console.js 读取。

⏰ 抽帧密度：先纠正不现实的预期

page.screenshot 单次 JPEG 往返实测 150~300ms，DOM 快照（page.evaluate 取 innerText）约 30~80ms。
因此毫秒级抽帧（如 5ms）物理上做不到 —— 强行设置只会让 promise 排队堆积、拖垮页面，
而且不产生更多信息量：字幕是滚动日志且已去重，评论靠 MutationObserver 事件驱动抓取，与轮询频率无关。

正确做法：如实说明后按可稳跑的最高密度执行。--shot 250（4 fps）实测可真实达成
（300s 写出 1159~1164 张）。DOM 采样间隔固定 800ms，300s 约得 370 帧，瓶颈在 page.evaluate 往返。

逐字稿是怎么来的（重要，别对用户说错）

逐字稿不是把截图 OCR 出来的，而是同时段直接读取页面文字流：麦上发言的 ASR 字幕分片 + 评论区 DOM。
截图只是过程留证与复核依据。重建算法（分片提取 → 唯一化 → 前缀收敛 → 近似去重 → 相邻合并）见
references/transcript-algorithm.md。

参考文档

• references/environment.md —— 跨平台环境准备（Node / Playwright / 浏览器 / Python）
• references/troubleshooting.md —— 故障排查手册（所有已知踩坑与判据）
• references/transcript-algorithm.md —— 逐字稿重建算法与时间戳语义
• references/compliance.md —— 合规红线与产出物免责说明

合规红线（必须遵守，并写进产出物）

• ASR 是平台自动识别，同音错字很常见（实测：「to B」→「to be」、「MES」→「麦斯」、「PCIe」→「屁事」）。
  逐字稿保留原始识别结果，不做事实性改写，另附「疑似误识别」对照表供核对。
• 「完整逐字稿」= 不总结、不删改原话；算法只去掉 ASR 的重复副本与中间态，不做内容筛选。
• 不得伪造未采集到的内容。抓不到就写抓不到。
• 只在未登录状态抓取公开可见内容；不尝试绕过登录、不伪造身份、不破解接口。
• 不用于监控特定个人、不用于骚扰或人肉；产出物中不还原平台已脱敏的用户名。
• 提醒用户遵守平台服务条款与著作权规定，转载内容需自行获得授权。

详见 references/compliance.md。