rn-human-motion-extractor

RN Human Motion Extractor

将经授权的参考视频中的选定片段转换为可复用的动作数据。保留动作和时间信息；不要将源人物的外观、声音、字幕或影像打包成可复用的身份资产。

边界

• 仅使用用户获准分析的公开或本地参考视频。
• 将源视频素材和保留身份信息的叠加预览保存在项目私有工作区中。纯骨架视频和关键点数据是可移植的动作资产。
• 此 Skill 用于提取证据；不保证生成式视频模型会遵循每个关键点。
• 如果手指被遮挡、模糊、位于画面外或未达到置信度门槛，不要将结果称为“精确的手部动作”。应报告覆盖情况。
• 将设计卡片、连接线、排版和 UI 动效交由 rn-motion-replica 处理；将全画面复刻声明交由 rn-replica-qc 处理。

工作流

1. 锁定片段和时间基准

确认输入文件和所需片段。使用 ffprobe 探测源视频，并记录宽度、高度、fps、时长、帧数和音频是否存在。只有在片段已经很短且边界明确时，才默认处理整个片段。

2. 创建本地运行环境

捆绑的提取器需要 FFmpeg 和 Python 3.10–3.12。请使用隔离环境；不要修改系统 Python。

uv venv --python 3.12 .venv
uv pip install --python .venv/bin/python -r \
  <skill-dir>/scripts/requirements.txt

3. 提取轨迹

.venv/bin/python <skill-dir>/scripts/extract_motion.py \
  --input <reference.mp4> \
  --output <private-project-dir>/motion-extraction \
  --start 0 \
  --duration 10

省略 --duration 可从 --start 处理到片段结尾。无需保留身份信息的 QC 预览时，使用 --no-overlay。

提取器会记录：

• 33 个 MediaPipe 姿势关键点
• 每只检测到的手各 21 个关键点
• 原始坐标和经置信度感知平滑处理后的坐标
• 归一化图像 x/y、相对 z、可见度、帧索引和时间戳

较短的缺失区间可以插值。较长的间隙会保持缺失；绝不要用编造的手指动作填补较长的遮挡区间。

4. 检查证据

打开叠加预览和纯骨架预览。至少检查开头、每次主要手势变化以及最后一帧。描述保真度之前，请先阅读 qc/extraction-stats.json。

预览中的颜色约定如下：

• 黄色：身体
• 蓝色／红色：左手／右手
• 细灰线：低置信度的身体节点

确认肩部、肘部、手腕和手部关键点簇在肢体交叉过程中仍对应正确的肢体。如果左右手发生互换或跳变，请保留原始数据、标记受影响的时间范围，并在将其用作硬控制信号之前通过手动关键帧进行修正。

5. 按证据支持的程度陈述结果

预期输出为：

motion-extraction/
├── data/
│   ├── motion-keypoints.json
│   └── motion-keypoints.npz
├── qc/
│   ├── extraction-stats.json
│   ├── media-probe.json
│   ├── motion-overlay.mp4
│   ├── motion-skeleton.mp4
│   └── contact-sheet.jpg
└── work/
    └── *.mp4

分别报告身体覆盖率以及左手／右手覆盖率。身体和手腕轨迹可能有用，但手指追踪仍不完整；请明确说明这一点。JSON 规范和左右手规则请参阅 references/keypoint-schema.md。

完成检查项

• 源视频片段、fps 和处理帧数一致。
• JSON 可解析，且每个处理帧都对应一条记录。
• 两个最终 MP4 均可正常解码，不产生 FFmpeg 错误，且时长与提取内容一致。
• 已目视检查联系表。
• 已报告置信度缺口和遮挡情况，而非通过平滑将其掩盖。
• 此提取 Skill 不代表或提交任何付费生成任务。