Reference · Robot data

The MCAP file format, explained

MCAP is the open file format robots and autonomous vehicles use to record their data. This is what an MCAP file is, how it's built, how to read one, and how to search across a whole fleet of them.

What is an MCAP file?

An MCAP file (extension .mcap, pronounced "em-cap," short for message capture) is a container for timestamped, heterogeneous message streams. One file holds many channels at once — camera images, lidar scans, transforms, and numeric telemetry — each message tagged with a log time so the whole recording can be replayed and seeked.

It is the open, modern log format for robotics and autonomous vehicles, and the de facto successor to the ROS bag file.

What MCAP is used for

MCAP records everything a robot sees and does, time-synced, in one place. Teams use it for logging in the field, debugging and replay, and as the source for building training datasets. Crucially, it is not tied to ROS — an MCAP file can store ROS 1, ROS 2, Protobuf, JSON, FlatBuffers, or custom-encoded messages, because the format carries the schema for each channel alongside the data.

How an MCAP file is structured

An MCAP file is a sequence of typed records, wrapped in magic bytes at the start and end:

  • Header — file-level metadata and the profile.
  • Schema & Channel — self-describing definitions of what each stream contains.
  • Message — the actual timestamped data on a channel.
  • Chunk — messages grouped together and optionally compressed (LZ4 or Zstd).
  • Index & Summary — offsets at the end of the file that make seeking to a time range or a single channel fast.

Because the file is self-describing and indexed, a reader can open a large recording and pull one channel or one time window without scanning the whole thing.

How to open and read an MCAP file

There are three common ways:

  • Foxglove Studio — a visual viewer to play back and inspect the data.
  • The mcap CLI — e.g. mcap info file.mcap for a quick summary of channels and message counts.
  • Official libraries — read and write MCAP from Python, C++, Go, Rust, Swift, and TypeScript.

Searching across a whole fleet of MCAP files

MCAP's index helps you seek within one file. But a fleet produces thousands of files and petabytes of data, and the real question is usually "where, across all of it, did this happen?" That needs a separate index over every file — by metadata, by time-series signal, and by image content.

Coldstack, built by Vantar, does exactly this: you point it at your bucket of MCAP logs, it builds a compact index on object storage, and you search the whole fleet in one query — then export the matches as training data. The raw MCAP files never leave your bucket.

See how Coldstack searches MCAPBuilding training datasets from logs

Questions

What is an MCAP file?

An MCAP file (extension .mcap) is an open container format for storing timestamped, heterogeneous message streams — the log format used by robots and autonomous vehicles. A single MCAP file can hold many channels at once (camera images, lidar, transforms, and numeric telemetry), each message tagged with a log time, so the whole recording can be replayed and seeked. MCAP is pronounced 'em-cap' and the name comes from 'message capture'.

What is the MCAP format used for?

MCAP is used to record robot and autonomous-vehicle data — every sensor and topic, time-synced, in one file. It is the de facto successor to the ROS bag format and is not tied to ROS: it can store ROS 1, ROS 2, Protobuf, JSON, FlatBuffers, or custom-encoded messages. Teams use it for logging, debugging, replay, and building training datasets.

How do you open an MCAP file?

You can open an MCAP file in Foxglove Studio (a visual viewer), inspect it with the `mcap` command-line tool (`mcap info file.mcap`), or read it programmatically with the official libraries in Python, C++, Go, Rust, Swift, and TypeScript. Because the format is indexed, readers can jump to a time range or a single channel without scanning the whole file.

How is an MCAP file structured?

An MCAP file is a sequence of records between magic bytes: a header, then schema and channel records that describe the data, message records that carry it, chunk records that group and optionally compress messages, and index and summary records at the end that make seeking fast. This self-describing, indexed layout is what lets a reader open a large file and read one channel or one time window cheaply.

Does MCAP support compression?

Yes. MCAP compresses data at the chunk level, typically with LZ4 or Zstd. Because messages are grouped into chunks and indexed, a reader can decompress only the chunks it needs for a query rather than the whole file.

How do you search across many MCAP files?

The format helps you seek within one file, but finding a moment across a whole fleet of files is a different problem. That needs an index over all of them — by metadata, by signal, and by image content. Coldstack builds that index on object storage and lets you search an entire fleet of MCAP logs in one query, while the raw files stay in your own bucket.