MCAP
开放的机器人日志文件格式与程序库,ROS 2 录制包的默认格式
许可证
MIT
代码:MIT,依据 GitHub 仓库根目录的 LICENSE 文件。软件包:C++ 库、TypeScript 包、Python 包和 Rust crate 也都声明为 MIT。规范:格式规范和文档位于同一仓库,适用同一许可证。名称与标志:MCAP 及其标志归 Foxglove 所有,代码许可证并未授予相关权利。已于 2026-11-10 核对 LICENSE、cpp/mcap/LICENSE、各 TypeScript 包的 LICENSE 文件、Python 的 setup.cfg 文件和 Rust 的 Cargo.toml 文件。
概述
MCAP 是一种开放的容器文件格式,用于记录带时间戳的多通道发布-订阅数据,也就是机器人运行时写下的那类日志。一个文件可以同时容纳多种序列化方式的消息,例如 ROS 1、ROS 2、Protobuf、FlatBuffers 或 JSON,并把每种消息的模式一并存入文件,因此无需原始代码即可解码。数据只以追加方式按块写入,块可用 zstd 或 LZ4 压缩,文件末尾的索引让读取方无需扫描整个文件就能直接跳到某个话题或时间范围。Foxglove 以 MIT 许可证公开开发 MCAP,提供 C++、Go、Python、Rust、Swift 和 TypeScript 程序库,以及用于检查、过滤、合并和修复文件的命令行工具。自 2023 年 5 月 23 日发布的 ROS 2 Iron Irwini 起,它一直是 ROS 2 录制工具 rosbag2 的默认存储格式。2026 年 11 月,Foxglove 介绍了为其程序库建立的共享基准测试框架,以及借此测得的写入提速。
MCAP(读作“em-cap”)是一种用于记录机器人数据的文件格式和一组程序库,由 Foxglove 公开开发;这家公司另外还销售一个商业化的机器人数据平台。在此之前,团队用什么格式录制取决于所用的框架:ROS 1 使用 .bag 文件,离开 ROS 就很难使用;ROS 2 写入的 SQLite 数据库不携带自身的消息定义;还有许多团队自建二进制格式。Foxglove 对现有格式的评估没有找到真正适合机器人领域的方案,MCAP 正是为填补这一空白而设计的。它的规范、文档和源代码全部公开,格式还拥有自己注册的媒体类型 application/vnd.mcap。
MCAP 文件由一连串记录组成。消息按通道分组,例如一个传感器话题,每个通道都指向一个描述其消息的模式。格式本身不关心消息如何序列化:常用编码登记表涵盖 ROS 1 和 ROS 2 消息、Protobuf、FlatBuffers、JSON Schema、CBOR 和 Cap'n Proto,同一个文件可以混用。由于模式存放在文件里,即使多年以后,在从未装过原始消息包的机器上也能解码录制内容。写入方只做追加,这让录制保持高速,也能在机器人断电时恢复写了一半的文件。消息可以分块并用 zstd 或 LZ4 压缩,每块可附带校验和;文件末尾可选的摘要部分为块、通道、元数据和附件建立索引。借助这个索引,读取方无需读取文件其余部分就能取出某个话题或某段时间窗口的数据,通过网络读取时也是如此。
程序库覆盖 C++、Go、Python、Rust、Swift 和 TypeScript,均依照规范测试,不过支持矩阵显示它们提供的读取功能并不完全相同。Python 包还提供处理 ROS 1、ROS 2 和 Protobuf 数据的辅助工具。MCAP 命令行工具可用 Homebrew 安装,也可下载发布版二进制文件,能显示文件统计信息,对文件进行过滤、合并、排序、压缩和恢复,并把 ROS 1 .bag 与 ROS 2 .db3 录制文件转换为 MCAP。2026 年,Foxglove 将它从 Go 改用 Rust 重写,界面保持不变。
在 ROS 2 中,rosbag2 通过存储插件进行录制,其 MCAP 插件随 2023 年 5 月 23 日发布的 Iron Irwini 版本成为默认插件,此前一个拉取请求把默认存储从 SQLite 换成了 MCAP。SQLite 仍可作为选项使用。许多机器人数据查看器和工具都能打开 MCAP 文件,包括 Foxglove 自己的应用、Lichtblick、BAGEL、PlotJuggler 和 Rerun。
2026 年 11 月 9 日,Foxglove 发表了 Measuring and improving MCAP performance,介绍通过拉取请求 1611 加入的共享基准测试框架。它用逐字节相同的数据让 C++、Rust、Go、Python 和 TypeScript 程序库跑三个场景:在每种存储模式(不分块、分块、zstd 和 LZ4)下向单个通道写入一百万条 100 字节的消息;一段模拟的 10 秒机器人录制,含 5 个通道,从 200 Hz 的惯性传感器到 512 KB 的相机帧,总计约 102 MB;以及按话题、按时间范围或两者同时过滤读取这段录制。每次运行都会校验写入的字节和读回的消息数量,并记录耗时、文件大小和峰值内存。根据 Foxglove 自己的测量,在一台锁定在 3.0 GHz 的 AMD Ryzen AI MAX+ 395 上写入基于内存的文件系统时,一百万条消息测试中的 C++ LZ4 写入速度约为 2026 年 1 月的 8 倍,Rust 在该测试中的写入时间降到原来的一半以下。部分提升来自新的默认设置,而不是更快的代码:Go 和 C++ 现在使用最快的 LZ4 设置,文件会大 15% 到 30%;C++ 的 zstd 则改为 3 级,文件缩小约 31%,代价是写入变慢。公布的结果只涉及写入,Foxglove 也指出 Python 程序库在处理小消息时比其他程序库慢得多。
为何重要
录制是机器人团队调试、调查事故和收集训练数据的方式,而日志只有在周边工具能读取时才有用。在当前版本上运行 ros2 bag record 时,ROS 2 写出的就是 MCAP 文件;Lichtblick、PlotJuggler 和 Rerun 等查看器也都支持这一格式,因此无论在 ROS 内外,它都被广泛用于机器人日志。它以 MIT 许可证开放,有成文的规范和注册的媒体类型,并且自带模式,今天录制的数据日后无需原始代码也能解码。维护它的是商业公司 Foxglove;代码仓库中共享的基准测试框架让任何人都能用同一方法在自己的硬件上检验这些程序库的性能,而不必依赖 Foxglove 的数据。对于更看重查询和可视化、而非录制速度的团队,Rerun 的 RRD 格式 rosbag2 插件是另一种选择。
解决的问题
机器人日志混合了许多速率和大小各异的数据流,而在 MCAP 出现之前,团队录制成什么文件取决于所用框架:ROS 1 的 bag 文件离开 ROS 就难以读取,ROS 2 的 SQLite 数据库不携带自身的消息定义,自建格式则需要每个工具单独适配。MCAP 提供一个开放、自描述的容器:写入快,能经受录制中断,同一文件可容纳任何序列化方式,并可通过索引按话题和时间检索;它还有六种语言的程序库,工具无需各自编写解析器即可读写。
要点
- 一种开放的容器文件格式,用于机器人日志等带时间戳的发布-订阅数据,规范公开,媒体类型为 application/vnd.mcap
- 与序列化方式无关:ROS 1、ROS 2、Protobuf、FlatBuffers、JSON 等可放在同一文件中,每个模式都存于文件内
- 只追加写入,可恢复中断的文件,按块用 zstd 或 LZ4 压缩,并有索引支持按话题或时间范围读取
- 提供 C++、Go、Python、Rust、Swift 和 TypeScript 程序库,以及现已用 Rust 编写的命令行工具
- 自 2023 年 5 月 23 日发布的 ROS 2 Iron Irwini 起成为 rosbag2 的默认存储格式
- 为其中五个程序库建立的共享基准测试框架,Foxglove 于 2026 年 11 月 9 日公布了自己的写入测试结果
- MIT 许可证,由 Foxglove 公开开发
适用人群
- 录制、回放和转换录制包的 ROS 2 开发者
- 不使用 ROS、需要用同一种日志格式存放 Protobuf、JSON 或 FlatBuffers 混合数据的机器人团队
- 需要读写机器人日志的数据工具、查看器和数据管道开发者
- 为机器学习收集机器人数据、希望录制文件自描述且带索引的团队
局限
- 该格式和大部分程序库由商业公司 Foxglove 维护,其自家的机器人数据平台是商业产品
- 各程序库的功能并不一致:例如支持矩阵显示 Rust 不支持按时间戳顺序读取,Swift 不支持带索引的无序读取
- 2026 年 11 月文章中的性能数据来自 Foxglove 自己,是在一台 AMD Ryzen AI MAX+ 395 机器上写入基于内存的文件系统时测得的
- 这些结果只涉及写入;读取速度不在公布的比较之内
- 据 Foxglove 自己说明,Python 程序库处理小消息时比其他程序库慢得多
- 压缩和分块等写入默认设置在不同语言之间仍不一致,因此同样的数据可能得到不同的文件大小和速度
- 索引位于文件末尾的摘要部分,因此在关闭前中断的录制在用命令行工具恢复之前没有索引