用途与实际影响
这项功能怎样使用
为什么需要它
渲染可能中断，也可能遇到编码退出正常却少帧的异常。只看文件存在或帧数都识别不了同样长度的旧内容；现在既核对分片来源与输出字节，也数帧，局部场景更新不必令完全无关的正确分片全部报废。
举个实际例子
我可以说：“昨晚完成了前 20 个分片，今天继续；但我换了 hero.png，用过旧图的分片必须重做。”系统会识别素材变化，不把新旧画面拼进同一成片。
最后我会得到什么
得到核对过长度与来源的无声画面轨。每个可继续使用的片段保留到本人明确清理；有缺帧或来源不明就不拼成成片。
正常时
全部片段属于当前脚本与素材，帧数完整，再组成无声画面轨。
发现问题时
一片失败可重试；某场变化只重做受影响片段，公共背景或模板变化会影响更多片段。
入口不可用或证据不足时
场景素材、背景、浏览器或编码器不可用，或旧错误片段无法处理时停止，不拼不可信画面。
从哪里开始
预览确认后在视频工程运行 run.ps1 render，使用当前场景、背景、音频时长和已配置的 Playwright/FFmpeg 环境。
需要准备什么
- 已确认可渲染的工程与画面
- 输出目标
从开始到拿到结果
- 1
锁定本次输入
按场景、素材和时长计算身份、帧数与分片。
- 2
逐片生成和复用
只复用身份及输出字节均匹配的片段；中断后重做缺片或受影响片段。
- 3
核对整轨
拼接后比对总帧与来源；没有完整跑过本片时不声称成片已通过。
技术实现与依据
这里保留实现、关键条件、精确入口、历史记录和验证结果。
分片来源、输出哈希与少帧保护已实现；本轮未做生产编码探针关键规则与设计选择
video_track.mp4 设计上无声，声音在 merge 后的 final_output.mp4。
静态 doctor 不证明编码可用；显式本地或 GPU smoke 才取得相应证据，单次短片仍不证明所有长渲染稳定。
分片身份保护同一项目续作，不是跨项目缓存或通用媒体数据库。
本模块用到的名词
- chunk（渲染分片）
- 一段固定帧范围的临时视频；该片覆盖的输入、输出字节与帧数都匹配才可复用。
- deterministic（确定性）
- 同一场景在同一 t 秒按同一规则求状态，不依赖当时浏览器跑了多久。
- AV1（视频编码格式）
- 当前硬件编码的视频格式；4K60 单帧可用不等于整条长视频已验收。
专业定义
渲染速度不改动画时间；只重做受影响画面，但每片都必须证明来源正确。
解决什么
防止渲染速度影响动画时间、显卡少帧造成持续音画漂移，以及中断恢复把旧内容混进新版本。
当前怎样实现
- build_timeline 按 durations 累加全局起止时间，seekTime 接收当前场景内相对秒数。
- 每 worker 使用无头 Chromium，最多缓存 6 个场景页面；透明 PNG 通过管道送给 FFmpeg。
- 背景以 stream_loop 循环并按当前起点裁切，前景 overlay 后可加 vignette 与 grain，再用 av1_nvenc 编码。
- 总帧按 60fps 计算；默认最多 300 帧一片、4 workers、失败重试 2 次。
- _render_identity.json 绑定场景 HTML、其中 file:/// 素材、时长、背景 SHA、画布、转场、成片效果、编码参数与实际分片边界。
- 复用前逐片回验来源和输出哈希，再用 ffprobe 核对帧数；局部变化只淘汰受影响分片，陈旧受管片删不掉则停止，最终轨再次核对总帧和来源。
执行流程
- 1
读取场景、时长与背景。
- 2
计算总帧、分片边界和完整输入身份。
- 3
逐片核对覆盖输入、输出哈希和帧数，不因同名或同长度就复用。
- 4
多个 worker 只处理缺失或错误分片。
- 5
全部正确后无损拼接并核对整轨总帧。
- 6
保留已验证分片与视频轨，直到明确清理；不是成功后立即丢掉全部可复用成果。
边界
- 本轮没有完整 render，不公布整片速度、显存峰值或稳定时长。
- 背景文件可循环覆盖任意时长，但接缝是否视觉无痕仍需实际看。
- 同一路径素材字节受身份保护；未通过 file:/// 引入的外部运行依赖不属于当前场景合同。
失败与恢复
- 分片少帧或 FFmpeg 非零退出
- 删除该片并有界重试；仍失败则停止整轨拼接。
- 输入身份变化
- 只废弃受该输入影响的分片，公共背景或编码变更可能影响全部；不把陈旧内容拼进新成片。
- 陈旧分片无法删除或素材缺失
- 硬失败并列出问题文件，不先写入新身份掩盖旧文件。
真实入口
E:\Projects\Archives\video-scaffold\pipeline\render.py时间线、逐帧抓取、分片、身份、重试与帧数验证
E:\Projects\Archives\video-scaffold\templates\scene_base.htmlseekTime(t) 画面状态
E:\Projects\Archives\video-scaffold\background\background_4k.mp4当前 4K60 AV1 背景资产
如何验证
- 2026-09-03 历史回归验证旧身份保护；当前源码扩展分片输出哈希与局部增量测试，本轮没有重新运行源回归或整轨制作。
- 本轮静态 doctor 只确认协调登记，不调用 NVENC；2026-09-03 单帧编码结果保留历史日期，不升级为当前 PASS。
- 本轮没有跑完整视频轨；历史 README 的速度与无缝描述不作为当前实测。
与其他模块的关系
本模块只产出无声视频轨；交付模块把旁白、音乐、封面和章节合入，并执行结构验收。