Mocap JSONL Recording and Replay

Mocap recordings use UTF-8 JSON Lines. The first line is a header; each later line is a frame or an event. Every file embeds its calibration snapshot, so replay does not depend on a developer-local calibration file.

Header

The current format is 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

Each frame retains both inputs and outputs:

• devices: raw node snapshots including quaternion, sequence number, device sample time, host receive time, sync status, and the Base64 raw UDP payload for live recordings;

• mocap_state: common-timeline solve state including frame_time_ns, node_samples, sync error, and sample age;

• control: the control target emitted for this frame;

• recorded_monotonic_ns: host monotonic time used exclusively for recording order and replay scheduling;

• timestamp: Unix wall time used only for log presentation.

The replay tool uses recorded_monotonic_ns to preserve original frame spacing and supports pause, single-frame stepping, and speeds from 0.25x to 8x. Legacy v1 JSONL files fall back to timestamp deltas when this field is absent.

Event

Event lines record state transitions, for example:

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

The repository ships a sanitized examples/demo_replay.jsonl. After installing the mocap dependencies, run:

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

You can also use generate_demo_replay.py to create a hardware-free demo file. Replay executes the same solver and skeleton display.