MCAP Python Library

1.3.1 · active · verified Sat Apr 11

The `mcap` library provides classes for reading and writing the MCAP file format. MCAP is a modular container format primarily intended for robotics applications, supporting pub/sub messages with arbitrary message serialization, including JSON, Protobuf, ROS 1, and ROS 2. It emphasizes high-performance writing, efficient seeking, and data recoverability. The project maintains an active development pace with frequent releases across its core library and various serialization support packages.

Warnings

gotcha Modules, variables, classes, and attributes prefixed with a single underscore (`_`) are considered internal API and may change between minor or patch releases without prior notice. Relying on them can lead to unexpected breakages.
Fix: Only use documented public API components (those without a leading underscore) to ensure forward compatibility and stability.
gotcha Reading topics from MCAP files that were converted from ROS 1 `.bag` files might exhibit slower performance compared to reading directly from the original `.bag` files using native ROS 1 tools.
Fix: If performance is critical for ROS 1 data, benchmark reading both the original `.bag` and the converted `.mcap` file. Consider using native `rosbag` tools for initial processing if the overhead of MCAP conversion/reading is prohibitive for your use case.
gotcha The `mcap` library provides raw message data (byte streams). Users are responsible for decoding complex or compressed payloads (e.g., images, point clouds) into usable Python objects using appropriate image processing or serialization libraries. The library does not automatically handle this decoding beyond schema registration.
Fix: When consuming messages with complex data types, manually integrate external libraries (e.g., Pillow for images, `struct` for binary data, Protobuf/ROS message definitions for structured data) to parse the `message.data` byte array according to the `schema.encoding` and `channel.message_encoding`.
gotcha The core `mcap` Python library is primarily designed for creating new files or reading existing ones. Direct programmatic appending to an *already closed* MCAP file is not a officially supported operation and can lead to unexpected behavior or data corruption.
Fix: For continuous logging or adding data over time, design your application to either keep the writer stream open or create new MCAP files for each recording session. For post-processing scenarios where merging is needed, consider using the `mcap-cli` tool's `merge` command.

Install

pip install mcap Core library
pip install mcap-protobuf-support Protobuf support (optional)
pip install mcap-ros1-support ROS 1 support (optional)
pip install mcap-ros2-support ROS 2 support (optional)

Imports

make_reader
```
from mcap.reader import make_reader
```
The `mcap.mcap0` path was used in older versions (e.g., 0.0.11) but is now internal; use `mcap.reader` for the public API.
Writer
```
from mcap.writer import Writer
```
The `mcap.mcap0` path was used in older versions but is now internal; use `mcap.writer` for the public API.

read_protobuf_messages

from mcap_protobuf.reader import read_protobuf_messages

DecoderFactory

from mcap_ros1.decoder import DecoderFactory

read_ros2_messages

from mcap_ros2.reader import read_ros2_messages

Writer (ROS2)
```
from mcap_ros2.writer import Writer
```

Quickstart

This quickstart demonstrates how to write a simple MCAP file with JSON-encoded messages and then read it back using the `mcap` library's core reader and writer. It registers a schema and channel, adds a message, and iterates over messages to print their content.

import json
import sys
from time import time_ns
from mcap.writer import Writer
from mcap.reader import make_reader

file_path = "example.mcap"

# --- Writing an MCAP file ---
with open(file_path, "wb") as stream:
    writer = Writer(stream)
    writer.start(profile="x-my-profile", library="my-writer-v1")

    schema_id = writer.register_schema(
        name="sample",
        encoding="jsonschema",
        data=json.dumps({
            "type": "object",
            "properties": {
                "sample": {
                    "type": "string"
                }
            }
        }).encode(),
    )
    channel_id = writer.register_channel(
        schema_id=schema_id,
        topic="/sample_topic",
        message_encoding="json",
    )

    writer.add_message(
        channel_id=channel_id,
        log_time=time_ns(),
        data=json.dumps({"sample": "hello world"}).encode("utf-8"),
        publish_time=time_ns(),
    )
    writer.finish()
print(f"Wrote {file_path}")

# --- Reading an MCAP file ---
with open(file_path, "rb") as f:
    reader = make_reader(f)
    for schema, channel, message in reader.iter_messages(topics=["/sample_topic"]):
        print(f"Read: Topic='{channel.topic}' (Schema='{schema.name}'): {message.data.decode('utf-8')}")

view raw JSON →