动捕 JSONL 录制与回放

动捕录制使用 UTF-8 JSON Lines。第一行是 header，后续每行是一个 frame 或 event。文件必须内嵌校准快照，因此回放默认不依赖开发者本机的校准文件。

Header

当前格式为 version: 2：

{
  "type": "header",
  "version": 2,
  "schema_version": 1,
  "frame": "body_rh",
  "recorded_time_domain": "host_monotonic_ns",
  "wear_side": "right",
  "roles": {"chest": "CHEST"},
  "calibration_snapshot": {},
  "dimensions": {}
}

Frame

每一帧同时保留输入和输出：

• devices：原始节点快照，含四元数、序号、设备采样时间、主机接收时间、同步状态，以及实时录制时的 Base64 原始 UDP 载荷；

• mocap_state：共同时间轴解算状态，含 frame_time_ns、node_samples、同步误差和样本年龄；

• control：该帧导出的控制目标；

• recorded_monotonic_ns：录制顺序和回放调度唯一使用的主机单调时间；

• timestamp：仅用于日志展示的 Unix 墙上时间。

回放工具用 recorded_monotonic_ns 保留原始帧间隔，支持暂停、逐帧和 0.25x 至 8x 倍速。旧的 v1 JSONL 文件没有该字段时，回放退回使用 timestamp 的时间差。

Event

事件行用于录制状态变化，例如：

{
  "type": "event",
  "event": "recording_started",
  "details": {"mode": "live"},
  "recorded_monotonic_ns": 123456789
}

仓库提供脱敏的 examples/demo_replay.jsonl。安装人体动捕依赖后可直接运行：

python SOFTWARE/人体动捕/mocap_viz.py --replay examples/demo_replay.jsonl

也可以用 generate_demo_replay.py 重新生成不依赖硬件的 demo 文件。回放会重跑同一套解算和骨架显示。