rn-replica-qc

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Reference Video Replica QC

参考视频复刻质量检查（QC）

Role

角色

Turn reference-video recreation into a red/green evidence loop and, when useful, capture the aligned motion as reusable HyperFrames or Remotion components.

Read replica-levels.md before naming or promising fidelity. A source-stream copy, an exact lossless render frame, an encoded frame-aligned MP4, a visual rebuild, and a style reference are different claims.

将参考视频复刻转化为红/绿证据闭环，并在适用时将已对齐的动效封装为可复用的 HyperFrames 或 Remotion 组件。

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

Canonical Showcase

标准示例

Human display name: Presenton 复刻 Bitexact 成片

File:

assets/showcases/presenton-replica-pixel-aligned-bitexact.mp4

This showcase demonstrates source-stream bit exactness. Do not use it as proof that a hand-authored HTML composition is bit exact.

人类可读名称：Presenton 复刻 Bitexact 成片

文件：

assets/showcases/presenton-replica-pixel-aligned-bitexact.mp4

该示例展示源流位级一致性。不得将其作为手工编写的 HTML 合成内容达到位级一致的证据。

Operating Modes

运行模式

Analysis-only: inspect and report; do not edit implementation code.
Replica-loop: repair the candidate until the declared evidence gate passes.
Component-capture: register a proven motion pattern with inputs and limits.

仅分析：检查并报告；不修改实现代码。
复刻闭环：修复候选版本，直至通过声明的证据门禁。
组件提取：将已验证的运动模式连同输入和限制注册到组件库。

Workflow

工作流

1. Declare The Contract

1. 声明交付契约

Record the reference, exact segment, renderer, fidelity label, deliverables, component-library destination, and evidence required for approval. Use Goal mode when available; otherwise keep

alignment-report.md

and

patch-log.md

beside the project.

Complete when: the segment and every acceptance claim can be tested without relying on chat memory.

记录参考视频、准确片段、渲染器、保真度标签、交付物、组件库目标位置以及审批所需的证据。如果可以使用 Goal 模式，则使用 Goal 模式；否则，将

alignment-report.md

和

patch-log.md

放在项目旁边。

完成标准： 无需依赖聊天记录即可测试目标片段及每项验收声明。

2. Lock The Timebase

2. 锁定时间基准

Probe FPS, duration, start time, pixel format, frame count, and audio presence. For exact work, map timestamps to source frame numbers and extract by frame index. Inclusive segment count is

(end_frame - start_frame) + 1

. When joining adjacent inclusive segments, keep the earlier boundary frame and skip the first frame of the next segment.

Use

extract_halfsec_frames.py

for discovery and

extract_frame_range.py

for full-frame acceptance sequences.

Complete when: reference frame 1, final frame, count, and PTS mapping are explicit and reproducible.

探测 FPS、时长、起始时间、像素格式、帧数和音频存在情况。

进行精确处理时，将时间戳映射到源帧号，并按帧索引提取内容。包含首尾帧的片段数量为

(end_frame - start_frame) + 1

。合并相邻的包含首尾帧片段时，保留前一段的边界帧，并跳过后一段的首帧。

使用

extract_halfsec_frames.py

进行探索，使用

extract_frame_range.py

提取全帧验收序列。

完成标准： 明确记录参考视频的第 1 帧、最后一帧、帧数和 PTS 映射，并确保结果可复现。

3. Choose The Architecture

3. 选择架构

Exact replay: fixed reference content rendered from verified lossless frames or sprite rows. It is not a freely generative component.
Parametric motion: DOM/SVG/GSAP/React/Three.js with replaceable content.
Hybrid: ship exact replay for fidelity and keep a separate parametric implementation for later abstraction.

Never present an exact-replay texture layer as a parameterized AI component.

精确回放：使用已验证的无损帧或精灵图行渲染固定参考内容。它不是可自由生成的组件。
参数化动效：使用 DOM/SVG/GSAP/React/Three.js，并支持替换内容。
混合模式：使用精确回放保证保真度，同时保留独立的参数化实现，以便后续抽象。

绝不将精确回放纹理层描述为参数化 AI 组件。

4. Analyze And Repair

4. 分析与修复

Read alignment-workflow.md. Start with a

0.5s

contact sheet, add

0.1s

windows around fast motion, then repair the earliest or largest mismatch one visible cause at a time. Sampling locates problems; it does not approve pixel or frame-aligned delivery.

For the Presenton failure modes and the dynamic-image decode race, read presenton-lessons.md.

Complete when: the candidate reaches the declared visual state and no known earlier mismatch remains hidden behind a later fix.

请阅读 alignment-workflow.md。先生成

0.5s

帧览表，再在快速运动区域增加

0.1s

采样窗口，然后每次只处理一个可见成因，修复最早出现或偏差最大的不匹配。抽样只能定位问题，不能作为像素级或帧级对齐交付的批准依据。

有关 Presenton 常见失败模式及动态图片解码竞态，请阅读 presenton-lessons.md。

完成标准： 候选版本达到声明的视觉状态，且不存在被后续修复掩盖的已知早期偏差。

5. Pass Three Evidence Gates

5. 通过三重证据门禁

Asset gate: reference extraction count is exact; generated sprite cells or lossless intermediates round-trip to their source frames with zero error.
Runtime gate: the real registered timeline advances sequentially through every required frame. Do not call a test-only setter. Check arbitrary seeks, every dynamic-asset boundary, and previously aligned neighboring segments.
Delivery gate: run the renderer, decode the delivered MP4, compare every frame, check temporal candidates, inspect worst and boundary frames, probe media metadata, and verify archive copies by SHA-256.

For HyperFrames,

npx hyperframes check .

must pass before render. A successful render log is not delivery evidence. For Remotion, use the project's equivalent runtime and decoded-frame checks.

Complete when: all three gates are green and the report states which layer each metric proves.

资产门禁：参考帧提取数量必须准确；生成的精灵图单元或无损中间文件往返转换后，与源帧之间的误差为零。
运行时门禁：实际注册的时间轴必须按顺序推进并覆盖每个必需帧。不要调用仅用于测试的 setter。检查任意跳转、每个动态资产边界，以及此前已对齐的相邻片段。
交付门禁：运行渲染器，解码交付的 MP4，比较每一帧，检查各时间点的候选帧，检查最差帧和边界帧，探测媒体元数据，并通过 SHA-256 验证归档副本。

对于 HyperFrames，渲染前必须通过

npx hyperframes check .

。渲染日志成功不能作为交付证据。对于 Remotion，应使用项目中等效的运行时检查和解码帧检查。

完成标准： 三重门禁全部通过，并且报告明确说明每项指标证明了哪一层。

6. Extend And Join

6. 扩展与拼接

When continuing a replica in segments, rerun the previous segment, render the new segment independently, skip duplicate inclusive boundary frames, and check the frame before, at, and after every join. Then probe the combined frame count and duration.

Complete when: both old and new ranges pass and no join repeats, drops, or rewinds a frame.

以分段方式继续复刻时，重新运行上一片段，独立渲染新片段，跳过重复的包含首尾帧边界帧，并检查每个拼接点之前、当前和之后的帧。随后探测合并后片段的帧数和时长。

完成标准： 新旧两个范围均通过检查，且拼接过程没有重复帧、丢帧或回退帧。

7. Capture Components

7. 提取组件

type:
```
exact-replay
```
or
```
parametric-motion
```
source and timestamp range
intended content pattern
inputs and timing contract
implementation stack and assets
evidence files and acceptance level
known limits

分别注册精确回放和参数化动效。每个条目包括：

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

8. Decide

8. 作出结论

Approve only the fidelity label proved by current evidence. If a gate is red, say

not aligned

, name the first failing frame or timestamp, and continue the replica loop.

仅批准当前证据已经证明的保真度标签。如果任一门禁未通过，请说明

not aligned

，指出首个失败帧或时间戳，并继续执行复刻闭环。

Script Usage

脚本用法

bash

undefined

bash

undefined

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


Use a Python runtime with Pillow for frame and sprite verification. Timeline
capture requires Playwright in the Node runtime.

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。

Required Outputs

必需输出

```
alignment-report.md
```
and
```
patch-log.md
```
source and candidate contact sheets
full-frame runtime and delivery metrics JSON
worst-frame and boundary-frame evidence
side-by-side comparison video or sheet
media probe and checksum evidence
component catalog entry when requested
final pass/fail summary

For content-creation projects, copy final videos into

成片/

and the compact QC evidence into the sibling

质检/

directory.

```
alignment-report.md
```
和
```
patch-log.md
```
参考版本和候选版本的帧览表
全帧运行时指标 JSON 和交付指标 JSON
最差帧和边界帧证据
并排对比视频或对比表
媒体探测和校验和证据
按需提供组件目录条目
最终通过/失败摘要

对于内容创作项目，将最终视频复制到

成片/

，并将精简的 QC 证据复制到同级的

质检/

目录。