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 版本成為預設,先前有一個 pull request 把預設儲存從 SQLite 改為 MCAP。SQLite 仍可作為選項使用。許多機器人資料的檢視器與工具都能開啟 MCAP 檔案,包括 Foxglove 自家的應用程式、Lichtblick、BAGEL、PlotJuggler 與 Rerun。
2026 年 11 月 9 日,Foxglove 發表 Measuring and improving MCAP performance,介紹透過 pull request 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 函式庫處理小訊息時比其他函式庫慢得多
- 壓縮與分塊等寫入預設值在各語言之間仍不一致,因此相同資料可能得出不同的檔案大小與速度
- 索引位於檔案結尾的摘要區段,因此在關閉前就中斷的錄製,要等用命令列工具復原後才會有索引