rosbag2_storage_mcap

This package provides a storage plugin for rosbag2 which extends it with support for the MCAP file format.

⚠️ Move from ros-tooling organization

This package was recently merged into https://github.com/ros2/rosbag2 from https://github.com/ros-tooling/rosbag2_storage_mcap. To view historical pull requests and git history of this package, check here.

Installation

rosbag2_storage_mcap is available as part of the current ROS 2 distributions. On Ubuntu, after following the ROS 2 installation instructions, you can use:

# Replace "rolling" with your ROS distro (`echo $ROS_DISTRO`)
$ sudo apt install ros-rolling-rosbag2-storage-mcap

Usage

Use MCAP files with regular ros2 bag commands by adding the --storage mcap option (abbreviated as -s mcap):

$ ros2 bag record -s mcap /topic1 /topic2 ...

$ ros2 bag play -s mcap path/to/your_recording.mcap

$ ros2 bag info -s mcap path/to/your_recording.mcap

Writer Configuration

To configure details of the MCAP writer for ros2 bag record, use the --storage-config-file options to provide a YAML file describing mcap::McapWriterOptions. Field descriptions below copied from McapWriterOptions declaration

Example:

# mcap_writer_options.yml
noChunkCRC: false
noChunking: false
noMessageIndex: false
noSummary: false
chunkSize: 786432
compression: "Zstd"
compressionLevel: "Fast"
forceCompression: false

$ ros2 bag record -s mcap -o my_bag --all --storage-config-file mcap_writer_options.yml

Storage Preset Profiles

You can also use one of the preset profiles described below, for example:

$ ros2 bag record -s mcap -o my_bag --all --storage-preset-profile fastwrite

fastwrite

Configures the MCAP writer for the highest possible write throughput and lowest resource utilization. This preset does not calculate CRCs for integrity checking, and does not write a message index. This preset profile is useful for resource-constrained robots.

Equivalent to this storage configuration:

noChunking: true
noSummaryCRC: true

Using MCAPs written with fastwrite as a long-term storage format is not recommended. Some features will not work when reading MCAP files without a message index, such as reading messages from a subset of topics or seeking. When recording MCAPs on your robot with fastwrite, it is a good idea to post-process these files afterwards, to restore the message index and also save storage space:

```bash

Using the MCAP CLI https://github.com/foxglove/mcap/tree/main/go/cli/mcap

$ mcap compress fast.mcap -o compressed.mcap

File truncated at 100 lines see the full file

Changelog for package rosbag2_storage_mcap

0.33.0 (2025-04-25)

0.32.0 (2025-04-18)

• Add message sequence number to the messages write API (#1961)
• Add actions replay feature (#1955)
• Upstream quality changes from Apex.AI part 1 (#1903)
• Contributors: Barry Xu, Michael Orlov

0.31.0 (2025-02-02)

0.30.0 (2024-11-26)

0.29.0 (2024-09-03)

0.28.0 (2024-06-17)

• Add vscode gitignore rule and remove vscode folder (#1698)
• Contributors: methylDragon

0.27.0 (2024-04-30)

0.26.1 (2024-04-17)

0.26.0 (2024-04-16)

• Support service 2/2 --- rosbag2 service play (#1481)
• Use middleware send and receive timestamps from message_info during recording (#1531)
• Update to use yaml-cpp version 0.8.0. (#1605)
• Check existence of a file before passing it to the mcap reader (#1594)
• Contributors: Barry Xu, Chris Lalancette, Christopher Wecht, jmachowinski, Michael Orlov

0.25.0 (2024-03-27)

• Add topic_id returned by storage to the TopicMetadata (#1538)
• Use rw_lock to protect mcap metadata lists. (#1561)
• Remove rcpputils::fs dependencies from rosbag2_storages (#1558)
• remove unused headers (#1544)
• Link and compile against rosbag2_storage_mcap: Fixed issue 1492 (#1496)
• Use enum values for offered_qos_profiles in code and string names in serialized metadata (#1476)
• Store serialized metadata in MCAP file (#1423)
• Contributors: Alejandro Hernández Cordero, Michael Orlov, Patrick Roncagliolo, Roman Sokolkov, Tomoya Fujita, uupks

0.24.0 (2023-07-11)

• Implement storing and loading ROS_DISTRO from metadata.yaml and mcap files (#1241)
• Contributors: Emerson Knapp

0.23.0 (2023-04-28)

0.22.0 (2023-04-18)

• Add type_hash in MessageDefinition struct (#1296)
• Add message definition read API (#1292)
• rosbag2_storage: add type description hash to topic metadata (#1272)
• Contributors: Michael Orlov, james-rms

0.21.0 (2023-04-12)

• rosbag2_cpp: move local message definition source out of MCAP plugin (#1265)
• Update rosbag2 to C++17. (#1238)
• Use target_link_libraries instead of ament_target_dependencies (#1202)
• Contributors: Chris Lalancette, Daisuke Nishimatsu, Michael Orlov, james-rms

0.20.0 (2023-02-14)

• CLI: Get storage-specific values from plugin (#1209)
• Contributors: Emerson Knapp

0.19.0 (2023-01-13)

File truncated at 100 lines see the full file