MCAP

MCAP (pronounced "em-cap") is an open source container file format for logging and storing multimodal data. It supports multiple channels of timestamped pre-serialized data, and is ideal for use in pub/sub or robotics applications.

Get Started API Reference View on GitHub

Pub/sub logging

Store multiple channels of timestamped log data, such as pub/sub messages or multimodal sensor data.

Serialization-agnostic

Record and replay binary messages in any format – like Protobuf, DDS (CDR), ROS, JSON, and more.

High-performance writing

MCAP uses a row-oriented, append-only design to minimize disk I/O and reduce the risk of data corruption during unclean shutdowns.

Self-contained

MCAP stores message schemas alongside data, so your files remain readable in the future even as your codebase evolves.

Efficient seeking

MCAP files contain an optional index, allowing for fast, efficient reading, even over a low-bandwidth internet connection.

Optional compression

Choose between LZ4 or Zstandard for chunk-based compression, while still supporting efficient indexed reads.

Broad language support

Native reader and writer libraries are available in C++, Go, Python, Rust, Swift, and TypeScript.

Flexible

Configure optional features like chunking, indexing, CRC checksums, and compression to make the right tradeoffs for your application.

Production-grade

MCAP is used in production by a wide range of companies, from autonomous vehicles to drones, and is the default log format in ROS 2.

Why not just use rosbag or SQLite?

MCAP was designed to solve the shortcomings of the recording formats that came before it — see the full design history for the underlying requirements.

	rosbag1 (`.bag`)	rosbag2 default (SQLite `.db3`)	MCAP
Serialization agnostic	No — ROS1 serialization only	Yes	Yes — ROS 1/2, Protobuf, JSON, FlatBuffers, custom
Self-describing (schemas embedded)	Yes	Not by default (ros2/rosbag2#782)	Yes
Append-only / write-optimized	Partial	No — index updated per row insert	Yes — chunked, streaming-safe
Chunk-level compression	No	No (message-level only)	LZ4 or Zstandard
Corruption resilience	Partial (chunk-recoverable, no checksums)	Depends on journal mode	Chunk CRCs + `mcap recover`
Efficient remote / random-access reads	Index-based	Full DB load required in browser (`sql.js`)	Indexed reads over HTTP range, S3, GCS, Azure
Standards-track friendly	Yes	Difficult — SQLite has no independent second implementation	Yes — open spec, multiple implementations
Default in ROS 2	—	Iron and earlier	Jazzy and later (current)

Write your first MCAP file

MCAP libraries are available in six languages. Pick one to see a minimal end-to-end example.

from mcap.writer import Writer

with open("out.mcap", "wb") as f:
    writer = Writer(f)
    writer.start()

    schema_id = writer.register_schema(
        name="ExampleMsg",
        encoding="jsonschema",
        data=b'{"type":"object","properties":{"value":{"type":"number"}}}',
    )
    channel_id = writer.register_channel(
        schema_id=schema_id,
        topic="/example",
        message_encoding="json",
    )

    writer.add_message(
        channel_id,
        log_time=0,
        data=b'{"value": 1.0}',
        publish_time=0,
    )

    writer.finish()

#include <mcap/writer.hpp>

int main() {
  mcap::McapWriter writer;
  mcap::McapWriterOptions options("");
  writer.open("out.mcap", options);

  mcap::Schema schema("ExampleMsg", "jsonschema",
                       R"({"type":"object","properties":{"value":{"type":"number"}}})");
  writer.addSchema(schema);

  mcap::Channel channel("/example", "json", schema.id);
  writer.addChannel(channel);

  mcap::Message msg;
  msg.channelId = channel.id;
  msg.sequence = 0;
  msg.logTime = 0;
  msg.publishTime = 0;
  std::string data = R"({"value": 1.0})";
  msg.data = reinterpret_cast<const std::byte*>(data.data());
  msg.dataSize = data.size();
  writer.write(msg);

  writer.close();
}

package main

import (
    "os"
    "github.com/foxglove/mcap/go/mcap"
)

func main() {
    f, _ := os.Create("out.mcap")
    defer f.Close()

    writer, _ := mcap.NewWriter(f, &mcap.WriterOptions{})
    writer.WriteHeader(&mcap.Header{})

    schema := &mcap.Schema{
        ID:       1,
        Name:     "ExampleMsg",
        Encoding: "jsonschema",
        Data:     []byte(`{"type":"object","properties":{"value":{"type":"number"}}}`),
    }
    writer.WriteSchema(schema)

    channel := &mcap.Channel{
        ID:              1,
        SchemaID:        1,
        Topic:           "/example",
        MessageEncoding: "json",
    }
    writer.WriteChannel(channel)

    writer.WriteMessage(&mcap.Message{
        ChannelID:   1,
        LogTime:     0,
        PublishTime: 0,
        Data:        []byte(`{"value": 1.0}`),
    })

    writer.Close()
}

use mcap::{records::MessageHeader, Writer};
use std::{collections::BTreeMap, fs};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut out = Writer::new(fs::File::create("out.mcap")?)?;
    let schema_id = out.add_schema(
        "ExampleMsg",
        "jsonschema",
        br#"{"type":"object","properties":{"value":{"type":"number"}}}"#,
    )?;
    let channel_id = out.add_channel(schema_id, "/example", "json", &BTreeMap::new())?;
    out.write_to_known_channel(
        &MessageHeader { channel_id, sequence: 0, log_time: 0, publish_time: 0 },
        br#"{"value": 1.0}"#,
    )?;
    out.finish()?;
    Ok(())
}

import { McapWriter } from "@mcap/core";
import { FileHandleWritable } from "@mcap/nodejs";
import { open } from "node:fs/promises";

const writable = new FileHandleWritable(await open("out.mcap", "w"));
const writer = new McapWriter({ writable });
await writer.start({ library: "example", profile: "" });

const schemaId = await writer.registerSchema({
  name: "ExampleMsg",
  encoding: "jsonschema",
  data: new TextEncoder().encode(
    JSON.stringify({ type: "object", properties: { value: { type: "number" } } }),
  ),
});

const channelId = await writer.registerChannel({
  topic: "/example",
  schemaId,
  messageEncoding: "json",
  metadata: new Map(),
});

await writer.addMessage({
  channelId,
  sequence: 0,
  logTime: 0n,
  publishTime: 0n,
  data: new TextEncoder().encode(JSON.stringify({ value: 1.0 })),
});

await writer.end();

import Foundation
import MCAP

final class FileWritable: IWritable {
    private let handle: FileHandle

    init(path: String) throws {
        FileManager.default.createFile(atPath: path, contents: nil)
        handle = try FileHandle(forWritingTo: URL(fileURLWithPath: path))
    }

    func position() -> UInt64 {
        handle.offsetInFile
    }

    func write(_ data: Data) async {
        handle.write(data)
    }

    func close() throws {
        try handle.close()
    }
}

let sink = try FileWritable(path: "out.mcap")
defer { try? sink.close() }

let writer = MCAPWriter(sink)
await writer.start(library: "example", profile: "")

let schemaId = await writer.addSchema(
    name: "ExampleMsg",
    encoding: "jsonschema",
    data: Data(#"{"type":"object","properties":{"value":{"type":"number"}}}"#.utf8)
)

let channelId = await writer.addChannel(
    schemaID: schemaId,
    topic: "/example",
    messageEncoding: "json",
    metadata: [:]
)

await writer.addMessage(
    Message(
        channelID: channelId,
        sequence: 0,
        logTime: 0,
        publishTime: 0,
        data: Data(#"{"value": 1.0}"#.utf8)
    )
)

await writer.end()