渲染 QA
渲染并不是在渲染器退出时就完成了。只有当证据表明它干净时才算完成:自动报告、每一张接触表都检查过、每个转场处的条带都检查过、旁白边缘都听过。在制作这些技能的生产环境中,子代理曾将一些渲染报告为“干净”,但实际存在 0.3 秒的 UI 闪烁(在锁定之前)、一个裁剪过的模态框,以及每隔三帧就消失一次的标题。正是脚本和条带发现了所有这三个问题。
脚本位于此文件旁边。先设置一次工作台:
PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
PY="$PVS_HOME/bin/pvs-py"
S="$PVS_HOME/skills/render-qa/scripts"
将解释器和脚本文件夹放在不同的变量中,并对两者都加引号("$PY" "$S/qa.py"):如果某个变量包含命令和路径,zsh 不会将其拆分,而在 bash 中,一旦路径包含空格,它就会失效。
<video_dir> 是 products/<slug>/videos/<video>/(其中包含 BRIEF.md、audio/、video/)。
门控流程,按顺序
- 在渲染之前。 运行运动检查(
seek-safe-motion技能)、hyperframes check以及每个设置节拍的快照。仅靠check是不够的:它曾经让一个视频通过,其中移动元素在四段展现中有三段都不可见。预渲染步骤在references/checklist.md中。 - 渲染完成后立即进行快速扫描(几秒钟):
"$PY" "$S/scan_render.py" <mp4>。出现WORKER PATTERN行表示存在搜索安全性错误:停止并修复时间线(参见seek-safe-motion),不要继续运行其余步骤。 - 完整报告:
"$PY" "$S/qa.py" <video_dir> <mp4>。它会运行所有自动检查,写入qa/REPORT.json和qa/REPORT.md,在qa/sheets/中创建接触表,在qa/strips/中创建条带(包括每个异常值运行和最后 5 秒),以及在qa/asr.txt中创建转录文本。在新款 Mac 上,对于 2 到 3 分钟 60 fps 的视频,大约需要 15 秒,包括语音转文本。从头到尾阅读REPORT.md,包括警告和所有 ASR 差异。 - 肉眼检查。 报告以脚本无法看到的内容结尾。执行所有操作:
- 查看每张接触表,而不是抽样。
- 在每次模态框打开和关闭、滚动、相机移动、章节更改、此版本中发生变化的节拍以及结尾画面到锁定的交接处,以 5 到 6 fps 的速度制作条带:
"$PY" "$S/strips.py" <mp4> <video_dir>/qa/strips modal:21.0:23.4:8 lockup:57:60。1 fps 的表格每秒采样一帧;0.3 秒的闪烁会夹在两个样本之间。 - 运行
"$PY" "$S/edges.py" <mp4> <video_dir>并听取它标记的每个边缘。 - 如果此版本修改了已批准的版本,请证明其余部分没有移动:
"$PY" "$S/parity.py" <approved.mp4> <new.mp4> --skip 41.0:48.5。 如何阅读接触表、条带和奇偶校验输出:references/reading-sheets-and-strips.md。
- 分类每个失败和警告,使用
references/triage.md:它列出了这些检查发现的真实缺陷和误报,以及如何区分它们。在源头(模板、构建、lines.tsv、音频)修复原因,重建、重新渲染,然后从步骤 2 开始再次运行门控流程。永远不要手动编辑index.html:构建过程会重新生成它。 - 交付不是此技能的决定。
deliver.py仅在用户或用户启动的技能(/video-build、/video-review)要求交付时运行。除非报告通过、不是草稿并且与 MP4 逐字节匹配,否则它会拒绝。
检查项测量什么
| 检查项 | 失败条件 | 为什么是这个阈值 |
|---|---|---|
size, fps | 大小与 video.size 不同;fps 仅发出警告 | 大小错误意味着渲染损坏;不同的 fps 可能是预期的(30 对 60) |
worker_pattern | 连续 4 个或更多异常帧都落在一个帧索引模 3 上 | HyperFrames 使用 3 个交错的工作线程进行渲染;一个失去状态的工作线程会每三帧命中一次 |
outliers | 从不(仅警告) | 全速滚动、模糊调整和相机复位也会产生孤立的异常值;查看每个条带 |
black_frames | 在前 1 秒和后 2 秒之外,平均亮度低于 3 | 渐黑和从黑渐出是预期的;视频中间变黑是一个错误 |
voice_overlap | 两个语音剪辑的口语单词重叠超过 20 毫秒 | 基于单词时间测量,而不是剪辑边界:无声尾部重叠是可以的 |
loudness | 综合响度与 voice.mix_lufs 相差超过 1 LU | 已交付的最终成片测量结果为 -16.8 到 -15.3 LUFS,目标为 -16 |
true_peak | 高于 -1.0 dBFS | 为上传平台的损音频编码器留出余量 |
clipping | 任何真实的通道上的采样值达到 0.995 或更高 | 按通道测量,而不是下混,因此不会隐藏单个通道削波 |
clicks_outside_clips | 在所有音频剪辑之外出现脉冲性咔嗒声 | 在音效内部是预期的;在语音内部几乎总是辅音 |
abrupt_edges | 从不(仅警告) | 一个在 5 毫秒内结束且不在音效内的声音通常是剪辑不当的片段;请倾听 |
asr | 单词匹配率低于 0.93,或跳过 | 最终测量结果在 0.953 到 0.988 之间;脚本按播放顺序比较,而不是文件顺序 |
banned_terms_* | 在音频中听到、在 index.html 中可见或在 lines.tsv 中出现的禁用词汇、禁止短语或旧名称 | 来自 product.yaml;实时 UI 可能仍显示旧名称,但视频不能 |
camera_zoom | 从不(仅警告)高于 video.max_zoom | 全屏截图大约 2 倍两次被拒绝为“超级放大”;缩小的画布容差更大 |
motion_lint | seek-safe-motion 检查报告错误 | 在代价高昂的渲染之前捕获时间线错误 |
--no-asr 会使报告故意失败:偏离脚本的旁白正是评审者最先听到的内容。语音转文本使用 whisper small.en 处理英语,使用多语言 small 模型处理其他任何 lang(如果缺失,会下载一次)。
报告契约
qa/REPORT.json 遵循 docs/contracts.md:mp4(相对于视频文件夹)、sha256、created、draft、checks(name、passed、detail 和 level: warn 用于警告)、passed。它还包含 draft_reason、probe、artifacts 和 ASR 差异。当 BRIEF.md 中的任一签名为空或 video/index.html 包含 <meta name="pvs-draft" content="1">(由 build.py --draft 写入)时,draft 为 true。草稿可以通过所有检查,但永远不会被交付:未签名的覆盖率正是导致视频缺少评审者关心的功能的原因。
交付(仅在要求时)
"$PY" "$S/deliver.py" <video_dir> <mp4> [--archive-previous] [--dry-run]
它会将文件复制到 <product_dir>/deliveries/,命名为 review.naming(默认为 {product} {video} v{version}.mp4,版本来自 BRIEF.md),尽可能使用 APFS 克隆,验证副本逐字节匹配,并在旁边写入 <same name>.BRIEF.md。它从不覆盖:相同的字节再次执行是无操作的,在已交付的名称下出现不同的字节会提升文件名中的版本(然后更新 BRIEF.md 以匹配)。--archive-previous 将视频的旧版本移动到 deliveries/previous/,以便评审者的文件夹中只保留最新版本。交付后,用一张表格告知评审者:视频、版本、时长、更改内容以及最多三个未决决定,每个决定都附带一个推荐的默认值。任何已经上传到某处的副本现在都已过时:请说明这一点。
源于事故的规则
- 自行重新运行证据。 当子代理说渲染干净时,阅读其
REPORT.md,打开接触表和条带,并检查 sha256 是否与您要交付的文件匹配。代理说“干净”只是一个声明,报告才是证据。 - 每个版本在
renders/中都有自己的文件名;永远不要删除旧版本。仅在修复周期中覆盖评审者尚未见过的版本。 - 不要杀死您自己没有启动的进程(Chrome、ffmpeg、node):其他代理在同一台机器上渲染。
- 无需视觉 API 的快照:向
hyperframes snapshot传递--describe false,这样未发布产品的任何帧都不会离开机器。 - 仅拼写错误的 ASR 差异是可以接受的(品牌词被听成两个词,时间以单词形式书写)。在决定之前阅读每个差异;多个单词的差异意味着剪切或线路混乱。
脚本
| 脚本 | 用途 |
|---|---|
qa.py <video_dir> <mp4> [--out DIR] [--no-asr] [--strip name:t0:t1[:fps]] | 完整报告;未通过时退出码为 1 |
scan_render.py <mp4> [--json] | 快速闪烁、黑帧和响度扫描;出现工作线程模式或视频中间黑帧时退出码为 1 |
qa_full.py <video_dir> <mp4> [--out DIR] [--no-asr] | 仅测量结果,以 REPORT.txt 形式输出 |
sheets.py <mp4> <outdir> [--fps 1] | 1 fps 的接触表,4x4 排列 |
strips.py <mp4> <outdir> name:t0:t1[:fps] ... | 在转场周围创建带标签的条带(默认 6 fps) |
edges.py <mp4> <video_dir or index.html> | 每个旁白剪辑前后的电平 |
parity.py <old> <new> [--end T] [--skip A:B] [--threshold 1.0] [--audio] | 帧奇偶校验;超过阈值时退出码为 1 |
banned_terms.py [--product DIR] [--text T] [FILE or DIR ...] | 禁用词汇、禁止短语和旧名称;命中时退出码为 1 |
deliver.py <video_dir> <mp4> [--archive-previous] [--dry-run] | 交付门控 |
banned_terms.find_banned(text, product) 返回 [(term, kind)],供其他技能复用。
参考资料
references/checklist.md:完整的门控流程,从构建到评审者消息,以可勾选的框形式列出。请在首次渲染视频之前以及任何交付之前阅读。references/reading-sheets-and-strips.md:在接触表、条带、裁剪、奇偶校验和数值检查(亮像素计数、差异框)中应查找什么。在执行步骤 4 时阅读。references/triage.md:此 QA 产生的每个失败(真实或误报)以及如何区分和修复。在任何检查失败或发出警告时阅读。