LeRobot Dataset v3 stores low-dimensional time-series data in Parquet, camera streams in MP4 and schema plus episode boundaries in metadata. The format is only valid when these shards agree on episode offsets, timestamps, tasks and statistics.
The design reduces file-system pressure and enables Hub-native streaming, but it makes offsets, timestamps and finalization critical. A dataset is not valid merely because each Parquet or video file opens independently.
The official LeRobotDataset v3 documentation evolves with the codebase. Pin the installed release and documentation revision, then use this guide with the robot action-data guide and data-quality audit and robot data factory guide.
How Parquet, MP4 and metadata form one LeRobot v3 dataset
Version 3 moves from one-file-per-episode storage toward larger shared Parquet and MP4 shards. Episode boundaries are recovered from metadata rather than inferred from filenames. Training code can still request samples and temporal windows without manually opening every shard.
This separation improves scale but increases dependence on relational consistency. Copying only data files or renaming a shard without updating metadata can make complete episodes unreachable or misaligned.
Put tabular time series in Parquet
Robot state, action, timestamps and other low-dimensional high-rate features belong in Parquet with declared names, dtypes and shapes. Units, frames and control meaning are not created by the container and must remain documented.
Check row order, timestamp monotonicity, missing values and feature ranges per episode and per robot. A readable table can still contain an action shifted by one frame or a silently changed unit.
| Component | Stores | Critical relationship | Failure example |
|---|---|---|---|
| meta/info.json | Schema, FPS, version, paths | Describes every feature and shard | Wrong dtype |
| data/*.parquet | State, action, timestamps | Rows map to episodes | Offset shift |
| videos/*.mp4 | Camera frames | Frames align to time | Dropped frame |
| meta/episodes | Length, task, offsets | Reconstructs boundaries | Crossed episode |
| meta/stats | Feature statistics | Matches units and split | Leakage or stale stats |
Keep camera streams in MP4 shards
Frames are encoded per camera into video shards instead of stored as arrays in Parquet. Codec, frame rate, keyframes and camera identity affect random access and streaming cost. Preserve original timing rather than assuming frame index alone is universal time.
Decode sampled intervals from every camera and compare frame count and timestamps with tabular observations. Test missing, frozen and variable-rate video behavior before training.
Use info.json as the schema entry point
The official v3 documentation describes meta/info.json as the canonical schema location for features, shapes, dtypes, FPS, codebase version and path templates. Treat it as a contract between recording, conversion and training.
Validate required keys and reject incompatible schema changes early. Preserve custom feature definitions and processing code because a name such as observation.state does not identify joint order, units or frame by itself.
Reconstruct episodes from relational metadata
Per-episode records provide lengths, tasks and offsets into shared data and video files. Validate first, last and random episodes, including those that cross shard boundaries or sit near file transitions.
Do not trust aggregate row counts alone. Reconstruct each sampled episode and confirm that start and end observations, task label, action sequence and camera clips belong to the same trial.
Treat tasks and statistics as derived metadata
Task records connect natural-language descriptions to identifiers used by conditioned policies. Statistics support normalization, but neither replaces raw semantics. The same numeric range can mean joint radians, Cartesian meters or a normalized gripper command.
Compute statistics on the intended training split and preserve per-dataset or per-embodiment versions when needed. Avoid leaking validation or test information through global statistics.
Finalize writers before publishing
The current main documentation says finalize closes Parquet writers, flushes buffered episode metadata and writes required footer information. Skipping it can leave incomplete files that fail to load even when some bytes are present.
After finalization, reopen the dataset in a fresh process and run structural plus semantic checks. Treat a recording interruption as a recovery case with explicit salvage or quarantine, not as an implicit successful finalize.
Validate v2.1 to v3 migration by meaning
Migration aggregates episode-level Parquet and MP4 files into larger shards and writes new episode offsets. Compare episode count, frame count, task, timestamps, feature values, camera clips and success labels between source and destination.
Use the official large-dataset porting guide for the installed version. A converter completing without an exception is not enough evidence that action and video semantics were preserved.
Test streaming and random access separately
Streaming avoids full local download and can improve access to large Hub datasets. Its performance depends on shard size, seek pattern, cache, network and temporal-window requests. Sequential throughput does not predict random episode access.
Benchmark representative training workers and failure recovery. Verify that network retries or truncated ranges do not return a plausible but incomplete episode.
Pin code and documentation versions
The current documentation page identifies main as a source-install branch and points to a stable release. APIs and examples can differ across releases. Record the LeRobot package version, commit, datasets dependency and converter revision.
Do not copy a command from main into an older installed package without checking compatibility. Keep the dataset codebase version and migration history with the artifact.
Run structural, temporal and semantic integrity tests
Structural tests verify files, schemas, offsets and decodability. Temporal tests check monotonic time, aligned windows and frame coverage. Semantic tests replay episodes and verify that the observed action, motion and task agree physically.
Connect failures to the record and replay guide when data originated from ROS 2. Maintain checksums and an immutable manifest for source, conversion and published revisions.
| Test layer | Operation | Pass condition | Failure exposed |
|---|---|---|---|
| Schema | Load metadata | Expected names, shapes, dtypes | Incompatible feature |
| Index | Sample boundaries | Correct shard and offsets | Crossed episodes |
| Time | Compare modalities | Bounded skew and coverage | Action shift |
| Replay | Render state, action, video | Physical sequence agrees | Wrong camera or task |
| Training | Load temporal batches | Stable access and masks | Seek or padding bug |
Release with a dataset acceptance checklist
Document version, schema, units, frames, tasks, episode index, video encoding, finalization, conversion, checksums and split statistics. Preserve a source-to-published lineage record and a reproducible verifier.
Close validation with the following checklist.
- Pin LeRobot code, docs and dataset version.
- Validate Parquet, MP4 and metadata relationships.
- Reconstruct random episodes across shard boundaries.
- Compare v2.1 and v3 semantics after migration.
- Finalize, reopen, stream and train from a clean environment.
Frequently asked questions
Does v3 create one Parquet file per episode?
No. Multiple episodes can share larger Parquet and MP4 shards, with metadata restoring episode boundaries.
Are camera images stored in Parquet?
The standard v3 design stores camera frames in MP4 shards and low-dimensional signals in Parquet.
Does fewer files guarantee less corruption risk?
No. It reduces file-system pressure, but shared shards make metadata, offsets and finalization more important.
Why must finalize be called?
It flushes buffered metadata and closes Parquet writers so required file information is complete and loadable.
What should be compared after v2.1 migration?
Compare episode and frame counts, tasks, timestamps, features, videos, statistics and physically meaningful replay.
Episode-Semantics and Shard-Integrity Boundary
LeRobotDataset v3 preserves episode access through metadata, not file boundaries. Validate offsets, timing and semantics after every recording, conversion or interrupted finalization.