# MCAP

Replay MCAP recordings in any schema

- Category: Robotics
- Capabilities: Streams, History, Entities
- Runs on: Linux x64, Linux ARM64, macOS Apple silicon, macOS Intel, Windows x64

Replay an [MCAP](https://mcap.dev) recording, the format Foxglove tools and the
Foxglove SDK write. Its messages become Phloem channels and 3D scene geometry.
Point it at one `.mcap` file or a folder of them; a folder plays in file-name
order.

## What it reads

- **Message encodings** `json`, `protobuf`, `cbor` and `msgpack`, decoded from
  the schemas inside the file. Protobuf needs no generated code or `.proto`
  files. JSON needs no schema.
- **Chunked or not, indexed or not**, with `zstd` or `lz4` compression.
- **Unfinished files**, such as when the robot lost power. Every message before
  the cut is read.
- **Attachments and metadata records** are listed when the replay starts. They
  are not stored yet.

Not read here:

- ROS topics (`cdr` or `ros1` messages). Use the **ROS 2** connector. These
  channels are skipped, named and counted.
- `flatbuffer` and `capnproto` messages. These are counted.

## What you get

- **Scene** — Foxglove's standard schemas draw in the 3D view, in the frame
  the message names: `foxglove.PointCloud` (any field type, with the cloud's
  own pose), `LaserScan`, `FrameTransform` and `FrameTransforms` (as TF
  edges), `CompressedImage` and `RawImage`. A cloud from the Foxglove SDK and
  one from a ROS topic share one scene.
- **Scene, the rest** — Foxglove poses, scene entities (arrows, cubes, spheres,
  cylinders, lines, triangles, text, models), grids, camera calibrations,
  location fixes (on the map) and image annotations draw in the 3D view and
  the camera view.
- **Joints** — `foxglove.JointStates` becomes one channel per joint, named by
  the robot: `/joints/position/left_hip_pitch`,
  `/joints/effort/left_hip_pitch`, with units (rad, rad/s, N·m, rad/s²). A
  limit can watch one joint; a chart can pick the joints it wants.
- **Everything else** — flattened to `topic/nested/field` channels. Numbers
  keep their type, text stays text. Byte fields, such as image pixels, are not
  channels. A message with nothing to plot still records a sample, so the
  topic is never silent.

## Setup

1. Browse to a recording. The table lists its topics: schema, encoding,
   message count, and what each becomes.
2. Tick the topics to bring in.
3. Choose **Time** (below) and **Speed**. Speed `0` loads as fast as the disk
   allows.

## Time

| **Time** | Places each sample at |
|---|---|
| `recorded` (default) | the recorder's `log_time` |
| `published` | the message's `publish_time`, usually the same instant |
| `message` | the message's own timestamp (a Foxglove `timestamp` or a ROS-style `header.stamp`); a zero stamp falls back to `log_time` |

Choose `message` only when you trust the robot's clock.

**Loop** replays over and over, each pass timed from now.

## Missing data

If a channel's sequence counter jumps, the missing messages show as a gap on
that channel. A counter that resets is a recorder restart, not a loss. At the
end, a summary counts skipped channels, messages it could not decode, and
messages read.

## Standards

- MCAP format: <https://mcap.dev/spec> · well-known registry:
  <https://mcap.dev/spec/registry>
- Foxglove schemas: <https://docs.foxglove.dev/docs/visualization/message-schemas/introduction>
- Tested against every reader test file the MCAP project publishes (416 files).

## Supports

- MCAP files and directories of them, chunked or not, indexed or not, zstd and lz4 chunks, files a crashed recorder never finished
- Message encodings json, protobuf, cbor, msgpack — decoded from the file's own schemas, no generated code
- Well-known robotics schemas: PointCloud, LaserScan, FrameTransform(s), CompressedImage, RawImage, JointStates, Log, SceneUpdate, Grid, CameraCalibration, LocationFix
- Sequence gaps stated as gap records per channel; attachments and metadata records listed

## Connection fields

| Field | Type | Required | Notes |
|---|---|---|---|
| Recording | Path | Yes |  |
| Topics | Text | No |  |
| Time | One of | No |  |
| Speed | Number | No |  |
| Loop | On / off | No |  |