Skip to main content

recording

Clock

  • All channels in a recording MUST share one clock. Do not mix time sources, e.g. a camera on host time and a CAN bus on its own counter.
  • Timestamps MUST be non-decreasing within each channel. Messages SHOULD be written in non-decreasing log_time order across the whole file: merge your channels by time before writing.
  • t0_ns MUST be the earliest timestamp in the file.
  • Timestamps SHOULD be absolute Unix epoch nanoseconds. A relative clock is accepted with a warning, but a recording on a relative clock cannot be aligned with another recording. Preflight warns when t0_ns is below 1018 (before 2001), which usually means a relative clock or microseconds that were never scaled.
Write the same nanosecond time to a message’s log_time, its publish_time and its own timestamp field. Signals, keypoints and GPS fixes are timed by their MCAP log_time; the timestamp inside a nomadic.Signal or nomadic.Skeleton is not read. Keeping all three equal removes any ambiguity.

Task

One instruction for the whole recording goes in recording.task:
Every present field MUST be a non-empty string. Text is kept as written. For an instruction that changes during the recording, such as turn-by-turn navigation, use a navigation_instruction signal instead.

Segments

Annotations of spans of the recording, such as the subtasks of its task, go in recording.segments, one entry per span:
  • Segments MAY overlap and need not cover the whole recording.
  • Segments are ground-truth annotations. They are kept with the recording and are never used as input to its analysis.
The JSON Schema cannot compare two fields, so a schema-only check accepts a segment whose end_s is not after its start_s. Preflight and ingest reject it (segment.end_s.invalid). Check with preflight.
To attach ground-truth subtasks to a body part, set part to the exact name of a recording.platform.parts entry and use label: "subtask" (or "subtasks"). For example:
Preflight rejects undeclared part names. Ingest maps the times onto the video clock and derives anatomical left/right from the declared part’s side. Workbench shows these annotations as Ground truth alongside VLM subtasks under each part, including recordings with no predictions. This annotation source is visualization and evaluation data; it is never supplied to indexing inference.