MCAP Decoders Explained

MCAP processing in Rerun uses a decoder architecture where each decoder represents a different way to interpret and extract data from the same MCAP source. By default, when opening a file Rerun analyzes an MCAP file to determine which decoders are active to provide the most comprehensive view of your data, while avoiding duplication. You can specify which decoders to use during conversion, allowing you to extract exactly the information you need for your analysis.

Understanding decoders with an example

File-level decoders (schema, stats, metadata, attachments, recording_info) each run once over the file. Message decoders are tried per channel in priority order (ros2msg, ros2_reflection, protobuf), and each channel is handled by the first enabled one that supports it, with raw as the fallback for channels no other decoder supports.

Consider an MCAP file from a ROS2 robot containing sensor data on the topic /robot/camera/image_raw with ROS2 sensor_msgs/msg/Image messages:

• With only the ros2msg decoder: Creates an Image archetype for direct visualization in Rerun's viewer
• With only the raw decoder: Creates an McapMessage containing the original CDR-encoded message bytes
• With both decoders enabled: ros2msg handles the channel, and raw is only used for channels that ros2msg cannot decode

Schema and statistics decoders

The schema decoder extracts structural information about the MCAP file's organization, creating metadata entities that describe channel definitions, topic names with their message types, and schema definitions. This decoder is particularly useful for understanding unfamiliar MCAP files or getting an overview of available topics and channels before deeper processing.

The stats decoder computes file-level metrics and statistics, creating entities with message counts per channel, temporal ranges, file size information, and data rate analysis. This gives you insight into the scale and characteristics of your dataset for quality assessment and planning storage requirements.

Message interpretation decoders

Semantic interpretation

The ros2msg and foxglove decoders provide semantic interpretation and visualization of standard ROS 2 and Foxglove message types, creating meaningful Rerun visualization archetypes from data. Unlike the protobuf decoder, these decoders understand the semantics of the messages and create appropriate visualizations: images become Image, point clouds become Points3D, IMU messages become Scalars plotted over time, and so on.

See Message Formats for the complete list of supported message types.

Protobuf decoding

The protobuf decoder automatically decodes protobuf-encoded messages using reflection, creating structured component data based on the protobuf schema. Message fields become Rerun components that you can query and analyze.

However, this decoder provides structured access without semantic visualization meaning. While the data becomes queryable, it won't automatically appear as meaningful visualizations like images or point clouds, it gives you the data structure, not the visual interpretation.

The raw decoder

The raw decoder preserves the original message bytes without any interpretation, creating blob entities containing the unprocessed message data. Each message appears as a binary blob that can be accessed programmatically for custom analysis tools.

Recording info

The recording_info decoder extracts metadata about the recording session and capture context, creating metadata entities with information about recording timestamps, source system details, and capture software versions.

The URDF option

The urdf option uses Rerun's built-in URDF loader if there is a ROS 2 string topic named /robot_description, logging the robot model as static 3D geometry. In this MCAP workflow, joint transforms are not loaded from the URDF itself; they are expected to come from TF topics in the MCAP (e.g. /tf or /tf_static).

For general information about how to load URDF files, see here.

Decoder selection and performance

Selecting decoders

By default, all decoders are available and each channel is decoded by the most specific one that supports it. You can control which decoders are used when converting MCAP files via the CLI using the -d flag:

# Use only specific decoders
rerun mcap convert input.mcap -d protobuf -d stats -o output.rrd

# Use multiple decoders for different perspectives
rerun mcap convert input.mcap -d ros2msg -d raw -d recording_info -o output.rrd

# Add robot geometry from ROS robot_description topics
rerun mcap convert input.mcap -d ros2msg -d urdf -o output.rrd

Accessing decoder data

Each decoder creates different types of components on entity paths (derived from MCAP channel topics) that can be accessed through Rerun's SDK:

• Data from the ros2msg decoder and supported Foxglove messages appears as native Rerun visualization archetypes (see here for an overview)
• Other data from the protobuf or ros2_reflection decoders appears as structured components that can be queried by field name or manually added to certain views (example)
• Data from the raw decoder appears as blob components containing the original message bytes
• Data from the urdf option appears as static 3D robot geometry loaded from the ROS 2 /robot_description topic
• Metadata from schema, stats, and recording_info decoders appears as dedicated metadata entities

For more information on querying data and working with archetypes, see the Data Queries documentation.

Each of these decoders contributes their own chunks to the Rerun-native data. Below is a table showing the mapping between MCAP data and Rerun components: