关于 reference-video-replica-qc
Reference Video Replica QC 是用于视频复刻的质量检查 skill，面向需要验证画面和时间轴对齐的制作流程。它通过明确保真度声明、逐帧检查和多重证据门槛，支持修复复刻并将已验证的动态模式记录为组件。
主要功能
- 01定义复刻保真度与验收标准
- 02按帧分析时间轴和片段
- 03逐项修复可见差异
- 04执行素材、运行时和交付检查
- 05记录可复用动态组件
适用场景
- 01检查复刻视频是否逐帧对齐
- 02定位片段边界的丢帧或重复帧
- 03验证导出 MP4 与参考视频
- 04整理已验证的动态模式
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/reference-video-replica-qc确认已加载。
包含的文件
除 SKILL.md 外，安装时一起下载的参考资料和脚本。
agents/openai.yamlreferences/alignment-workflow.mdpresenton-lessons.mdreplica-levels.mdscripts/build_frame_sprite_rows.pycompare_videos.pyextract_frame_range.pyextract_halfsec_frames.pyverify_frame_sequence.pyverify_frame_sprite_rows.pyverify_timeline_playback.cjs详细介绍
参考视频复刻质检
角色
将参考视频复刻转化为红绿证据闭环，并在适用时，将对齐后的动作捕捉为可复用的 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. 通过三项证据门槛
- 素材门槛：参考提取的帧数准确；生成的精灵图单元格或无损中间文件往返转换后，与源帧相比误差为零。
- 运行时门槛：真实注册的时间线按顺序推进，遍历所有必需帧。不要调用仅供测试使用的 setter。检查任意跳转、每个动态素材边界，以及此前对齐的相邻片段。
- 交付门槛：运行渲染器，解码交付的 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 证据复制到同级的 质检/ 目录。