rn-replica-qc

参考视频复刻质检

角色

将参考视频复刻转化为红绿证据闭环，并在适用时，将对齐后的动作捕捉为可复用的 HyperFrames 或 Remotion 组件。

命名或承诺保真度前，请阅读 replica-levels.md。源流副本、精确无损的渲染帧、编码后帧对齐的 MP4、视觉重建和风格参考，是不同的声明。

标准展示案例

• 人类可读名称：Presenton 复刻 Bitexact 成片
• 文件：assets/showcases/presenton-replica-pixel-aligned-bitexact.mp4
• 此展示案例证明的是源流位精确性。不要用它来证明手工编写的 HTML 合成内容达到了位精确。

操作模式

• 仅分析：检查并报告；不要修改实现代码。
• 复刻闭环：修复候选内容，直到通过声明的证据门槛。
• 组件捕捉：将经过验证的动作模式及其输入和限制注册为组件。

工作流

1. 声明约定

记录参考内容、精确片段、渲染器、保真度标签、交付物、组件库目标位置，以及审批所需的证据。可用时使用 Goal 模式；否则，将 alignment-report.md 和 patch-log.md 放在项目目录中。

完成条件： 无需依赖聊天记录，也能测试片段和每一项验收声明。

2. 锁定时基

探测 FPS、时长、开始时间、像素格式、帧数和音频是否存在。对于精确处理，将时间戳映射到源帧编号，并按帧索引提取。片段的包含式帧数为 (end_frame - start_frame) + 1。拼接相邻的包含式片段时，保留较早片段的边界帧，并跳过下一片段的第一帧。

使用 extract_halfsec_frames.py 进行探查，使用 extract_frame_range.py 提取用于完整帧验收的序列。

完成条件： 明确且可复现地记录参考帧 1、最终帧、帧数和 PTS 映射。

3. 选择架构

• 精确重放：从经过验证的无损帧或精灵图行中渲染固定的参考内容。它不是可自由生成的组件。
• 参数化动作：使用可替换内容的 DOM/SVG/GSAP/React/Three.js。
• 混合方案：为保证保真度，交付精确重放，同时保留单独的参数化实现，以便后续抽象。

切勿将精确重放纹理层呈现为参数化的 AI 组件。

4. 分析并修复

阅读 alignment-workflow.md。先制作 0.5s 联系表，再为快速动作添加 0.1s 时间窗口，然后每次针对一个可见原因，修复最早出现或程度最大的偏差。采样用于定位问题；它不能作为通过像素对齐或帧对齐交付验收的依据。

有关 Presenton 的失败模式和动态图像解码竞态，请阅读 presenton-lessons.md。

完成条件： 候选内容达到声明的视觉状态，且没有已知的较早偏差被后续修复掩盖。

5. 通过三项证据门槛

1. 素材门槛：参考提取的帧数准确；生成的精灵图单元格或无损中间文件往返转换后，与源帧相比误差为零。
2. 运行时门槛：真实注册的时间线按顺序推进，遍历所有必需帧。不要调用仅供测试使用的 setter。检查任意跳转、每个动态素材边界，以及此前对齐的相邻片段。
3. 交付门槛：运行渲染器，解码交付的 MP4，比较每一帧，检查时间候选帧，检查误差最大的帧和边界帧，探测媒体元数据，并通过 SHA-256 验证归档副本。

对于 HyperFrames，渲染前必须通过 npx hyperframes check .。渲染日志显示成功并不能作为交付证据。对于 Remotion，请使用项目对应的运行时检查和解码帧检查。

完成条件： 三项门槛全部通过，且报告说明每项指标证明了哪一层。

6. 扩展并拼接

分段续制副本时，重新运行上一段，独立渲染新段，跳过重复的包含边界帧，并检查每个拼接点之前、拼接点处和之后的帧。然后探测合并后的帧数和时长。

**完成条件：**新旧范围均通过检查，且拼接处没有重复、丢失或回退帧。

7. 记录组件

分别登记精确回放和参数化运动。每个条目包括：

• 类型：exact-replay 或 parametric-motion
• 来源和时间戳范围
• 预期内容模式
• 输入和时间契约
• 实现技术栈和资源
• 证据文件和验收级别
• 已知限制

8. 决策

仅批准当前证据能够证明的保真度标签。如果某项关卡未通过，说明 not aligned，指出第一个失败的帧或时间戳，并继续副本迭代流程。

脚本用法

# Discovery samples and contact sheets
python3 scripts/extract_halfsec_frames.py reference.mp4 --out analysis/sample --contact

# Exact inclusive frame range
python3 scripts/extract_frame_range.py reference.mp4 --start-frame 720 --end-frame 1020 --out analysis/reference-fullfps

# Lossless sprite rows and round-trip proof
python3 scripts/build_frame_sprite_rows.py analysis/reference-fullfps assets/textures --prefix replica-row --frames-per-row 7
python3 scripts/verify_frame_sprite_rows.py analysis/reference-fullfps assets/textures --prefix replica-row --frames-per-row 7

# Real timeline capture, followed by full-frame comparison
node scripts/verify_timeline_playback.cjs --html ./index.html --timeline-id composition_id --start 24 --frames 301 --fps 30 --out analysis/runtime
python3 scripts/verify_frame_sequence.py analysis/reference-fullfps analysis/runtime --output analysis/runtime-metrics.json --boundary-every 7

# Delivered video comparison and decoded-frame gate
python3 scripts/compare_videos.py reference.mp4 candidate.mp4 --out analysis/delivery --reference-start-frame 720 --candidate-start-frame 0 --frame-count 301 --boundary-every 7

使用装有 Pillow 的 Python 运行时进行帧和精灵图验证。时间线采集需要在 Node 运行时中使用 Playwright。

必需输出

• alignment-report.md 和 patch-log.md
• 来源和候选版本的联系表
• 完整的帧级运行时与交付指标 JSON
• 最差帧和边界帧证据
• 并排对比视频或图表
• 媒体探测和校验和证据
• 按要求提供的组件目录条目
• 最终通过/失败摘要

对于内容创作项目，将最终视频复制到 成片/，并将精简的 QC 证据复制到同级的 质检/ 目录。