{"id":4105,"library":"mcap","title":"MCAP Python Library","description":"The `mcap` library provides classes for reading and writing the MCAP file format. MCAP is a modular container format primarily intended for robotics applications, supporting pub/sub messages with arbitrary message serialization, including JSON, Protobuf, ROS 1, and ROS 2. It emphasizes high-performance writing, efficient seeking, and data recoverability. The project maintains an active development pace with frequent releases across its core library and various serialization support packages.","status":"active","version":"1.3.1","language":"en","source_language":"en","source_url":"https://github.com/foxglove/mcap","tags":["data serialization","robotics","logging","ros","ros1","ros2","protobuf","foxglove"],"install":[{"cmd":"pip install mcap","lang":"bash","label":"Core library"},{"cmd":"pip install mcap-protobuf-support","lang":"bash","label":"Protobuf support (optional)"},{"cmd":"pip install mcap-ros1-support","lang":"bash","label":"ROS 1 support (optional)"},{"cmd":"pip install mcap-ros2-support","lang":"bash","label":"ROS 2 support (optional)"}],"dependencies":[{"reason":"Required for reading and writing Protobuf-encoded messages.","package":"mcap-protobuf-support","optional":true},{"reason":"Required for reading and writing ROS 1 messages.","package":"mcap-ros1-support","optional":true},{"reason":"Required for reading and writing ROS 2 messages.","package":"mcap-ros2-support","optional":true}],"imports":[{"note":"The `mcap.mcap0` path was used in older versions (e.g., 0.0.11) but is now internal; use `mcap.reader` for the public API.","wrong":"from mcap.mcap0.reader import make_reader","symbol":"make_reader","correct":"from mcap.reader import make_reader"},{"note":"The `mcap.mcap0` path was used in older versions but is now internal; use `mcap.writer` for the public API.","wrong":"from mcap.mcap0.writer import Writer","symbol":"Writer","correct":"from mcap.writer import Writer"},{"symbol":"read_protobuf_messages","correct":"from mcap_protobuf.reader import read_protobuf_messages"},{"symbol":"DecoderFactory","correct":"from mcap_ros1.decoder import DecoderFactory"},{"symbol":"read_ros2_messages","correct":"from mcap_ros2.reader import read_ros2_messages"},{"symbol":"Writer (ROS2)","correct":"from mcap_ros2.writer import Writer"}],"quickstart":{"code":"import json\nimport sys\nfrom time import time_ns\nfrom mcap.writer import Writer\nfrom mcap.reader import make_reader\n\nfile_path = \"example.mcap\"\n\n# --- Writing an MCAP file ---\nwith open(file_path, \"wb\") as stream:\n    writer = Writer(stream)\n    writer.start(profile=\"x-my-profile\", library=\"my-writer-v1\")\n\n    schema_id = writer.register_schema(\n        name=\"sample\",\n        encoding=\"jsonschema\",\n        data=json.dumps({\n            \"type\": \"object\",\n            \"properties\": {\n                \"sample\": {\n                    \"type\": \"string\"\n                }\n            }\n        }).encode(),\n    )\n    channel_id = writer.register_channel(\n        schema_id=schema_id,\n        topic=\"/sample_topic\",\n        message_encoding=\"json\",\n    )\n\n    writer.add_message(\n        channel_id=channel_id,\n        log_time=time_ns(),\n        data=json.dumps({\"sample\": \"hello world\"}).encode(\"utf-8\"),\n        publish_time=time_ns(),\n    )\n    writer.finish()\nprint(f\"Wrote {file_path}\")\n\n# --- Reading an MCAP file ---\nwith open(file_path, \"rb\") as f:\n    reader = make_reader(f)\n    for schema, channel, message in reader.iter_messages(topics=[\"/sample_topic\"]):\n        print(f\"Read: Topic='{channel.topic}' (Schema='{schema.name}'): {message.data.decode('utf-8')}\")","lang":"python","description":"This quickstart demonstrates how to write a simple MCAP file with JSON-encoded messages and then read it back using the `mcap` library's core reader and writer. It registers a schema and channel, adds a message, and iterates over messages to print their content."},"warnings":[{"fix":"Only use documented public API components (those without a leading underscore) to ensure forward compatibility and stability.","message":"Modules, variables, classes, and attributes prefixed with a single underscore (`_`) are considered internal API and may change between minor or patch releases without prior notice. Relying on them can lead to unexpected breakages.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If performance is critical for ROS 1 data, benchmark reading both the original `.bag` and the converted `.mcap` file. Consider using native `rosbag` tools for initial processing if the overhead of MCAP conversion/reading is prohibitive for your use case.","message":"Reading topics from MCAP files that were converted from ROS 1 `.bag` files might exhibit slower performance compared to reading directly from the original `.bag` files using native ROS 1 tools.","severity":"gotcha","affected_versions":"All versions when reading converted ROS 1 data"},{"fix":"When consuming messages with complex data types, manually integrate external libraries (e.g., Pillow for images, `struct` for binary data, Protobuf/ROS message definitions for structured data) to parse the `message.data` byte array according to the `schema.encoding` and `channel.message_encoding`.","message":"The `mcap` library provides raw message data (byte streams). Users are responsible for decoding complex or compressed payloads (e.g., images, point clouds) into usable Python objects using appropriate image processing or serialization libraries. The library does not automatically handle this decoding beyond schema registration.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For continuous logging or adding data over time, design your application to either keep the writer stream open or create new MCAP files for each recording session. For post-processing scenarios where merging is needed, consider using the `mcap-cli` tool's `merge` command.","message":"The core `mcap` Python library is primarily designed for creating new files or reading existing ones. Direct programmatic appending to an *already closed* MCAP file is not a officially supported operation and can lead to unexpected behavior or data corruption.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}