按媒体时长给 ASR SDK 传 idle_timeout，修超长音频上传卡 300 秒 (#181)

[zj1123581321]

背景

生产上一个 17502 秒 / 494 MB 的直播录制在 ASR 上传阶段两次同因失败：

AsrError("timeout", "发送音频帧超过 idle_timeout")

对到 capswriter_asr/client.py:367-372，失败点是单次 ws.send 的等待，不是
deadline_total 的总预算超时。idle_timeout 默认 300.0 秒，是一个与媒体长度无关
的常数。

诊断

完整过程见 docs/sessions/261006-issue-triage/181-diagnosis.md。要点：

• 三次带计时的实测（600 / 3600 / 17502 秒本地 ffmpeg 合成音频，打真实生产 ASR）
  里，本地管线一次都没停顿超过 8.67 秒，17502 秒那次最大单帧等待 3.82 秒。
  本地侧不是原因，300 秒级停顿只可能发生在 socket 上。
• ws.send 等的是服务端读 socket；服务端要读完的字节数就是剩余音频，所以单次停顿的
  上界与媒体长度成正比（17502 秒按实测 3.29 倍实时算约 5320 秒）。任何固定值都必然
  在够长的媒体上失效。
• 生产数据佐证：12900 秒及以下的 10 个样本在 300 秒下全部成功，17502 秒这一个两次
  都失败——阈值是被输入规模顶破的，不是某一帧偶发卡住。

改动

src/video_transcript_api/transcriber/capswriter_client.py

• 新增 IDLE_REALTIME_FACTOR = 3.0 / IDLE_OVERHEAD_SECONDS = 300.0 与
  _asr_idle_timeout()，拿得到时长时给 SDK 显式传
  idle_timeout = duration/3 + 300；17502 秒 → 6134 秒。取值是「服务端读完剩余积压
  所需时间」这一可证上界，常数出自 2026-10-03 那次生产实测（93.08898 秒音频耗时
  306.3 秒，3.29 倍实时、约 278 秒固定开销）。
• 拿不到时长时不传该键，SDK 用自己的默认 300.0 秒，行为与修复前逐字一致，并打一行
  可 grep 的 asr_idle_timeout duration=unknown fallback=sdk_default_300。
• 不新增配置项，与 _transcription_deadline 同一层集中计算（LLMConfig 的 dataclass 默认值与 config.example.jsonc 大面积漂移（6 个字段，配置缺键时静默换语义） #147）。
• 顺手修掉 generic/recorder:// 下载路径不写 last_media_duration，时长预算机制对该来源恒失效（静默） #170 留下的过期注释：原注释说「未探测路径上的媒体时长分布未知」，而
  PR fix: 时长探测在 generic/recorder 路径失效——复用准入探测结果供转录预算使用 #173（generic/recorder:// 下载路径不写 last_media_duration，时长预算机制对该来源恒失效（静默） #170）之后 generic / recorder 路径同样能拿到 ffprobe 时长。
• deadline_total 不动，总预算仍在兜底，服务端真挂死照样失败——不是用加大超时掩盖。

测试

tests/unit/test_capswriter_idle_timeout.py（21 个用例，已在 tests/README.md 登记）
全部断言真正传给 transcribe_file_sync 的实参：有时长时键存在且取值正确、与
deadline_total 互不覆盖；无时长（None / 负数 / NaN / ±Inf）时不传该键；降级日志可
grep；上传超时的 code=timeout 与原因仍随通知文案出去（#171 不回归）。

红验（把 sdk_kwargs["idle_timeout"] 那一行改成 and False）：

E       AssertionError: ['deadline_total', 'encoding', 'on_progress', 'seg_duration', 'seg_overlap']
E       assert 'idle_timeout' in {'deadline_total': 2520.0, 'encoding': 'flac', ...}

端到端

• 17502 秒合成音频：12:33:58–12:38:22，失败，但不是发送超时，而是服务端协议错
  code=audio_too_long——服务端解码累计到 14400 秒（4 小时）硬上限就中断读取，
  报上来的样本数 230412800 刚好越过 14400×16000 = 230400000。该尺寸在本服务端上
  无论怎么调客户端超时都转不了，详见诊断文档第 4.1 / 第 6 节（需主脑决策）。
• 14000 秒（服务端能接受的最大尺寸）合成音频：12:40:24–12:44:28，成功，
  capswriter_done ... processed=13971.4s percent=99.8%，最大单帧等待 4.49 秒。

验证

• make test（pytest -q tests）：exit 0
• PYTHONPATH=src uv run --frozen pytest tests -q -k "capswriter or deadline"：exit 0
• python -m compileall：通过（本仓无 mypy/ruff 配置，CI 用外部 gate workflow）

Fixes #181
Refs #170

[github-actions]

Required Gate v2 — 状态面板

当前状态：skipped · 无需动作（主审未跑，绿≠过审）

主审未跑，绿≠过审。draft / fork / hosted 的跳过不代表真实通过。

当前裁决：expected_skip / review_not_expected

历史可能不完整：1 个制品处理失败：URLError；1 个历史重建预算耗尽

Gate 历史（v1；来源为持久化 gate_terminal 制品）

Run	Attempt	Head	状态	收件人动作
37415956130	1	6bfae34	skipped	无需动作（主审未跑，绿≠过审）

历史行按 run_id + run_attempt 去重并只增不删；删除本评论后可由 gate_terminal 制品重建。

[zj1123581321]

暂不合并：根因确认为服务端 14400s 上限，已转 zlxlabs/CapsWriter-ASR-Server#92；本 PR 的 idle_timeout 放宽缺复现证据，等 #92 结论再定去留（详见 #181 最新评论）。

[zj1123581321]

不合并：#181 根因在 ASR 服务端（CapsWriter-ASR-Server#92 抬上限 + #93 修解码中止死锁），部署后 17501.67 s 真实录制端到端成功，见 #181 关闭评论。本 PR 中的 #170 注释修正与 181 诊断文档已由 #188（0550133f）单独合入；放宽 idle_timeout 的代码不再需要（上游同样建议不合并）。

[zj1123581321]

状态更新（2026-10-06）：本 PR 的「注释修正」与「#181 诊断文档」两部分已被 PR #188 取代并合入 main（0550133f）；本 PR 剩余的代码改动（IDLE_REALTIME_FACTOR、idle_timeout 传参、test_capswriter_idle_timeout.py）归属待定——合入前需 rebase 到最新 main（注释部分会冲突）。是否继续此修法（idle_timeout 按媒体时长传参）待 owner 对 #181 的处置拍板后定。