Skip to main content

roboto-mcap-codec

Decodes one channel of an MCAP file into Apache Arrow, and single messages into Python objects. open_mcap_file reads the file through a byte-range reader you supply: its footer and summary, then only the chunks that hold the channel's messages within the requested row range and, for a window on log time, overlap that window. It decodes ROS 1 messages, ROS 2 and OMG IDL messages over CDR, and JSON or MessagePack messages described by a JSON Schema. The rows arrive as pyarrow.RecordBatch values, one per batch, each owning its data, so it stays valid after the file and the cursor that read it are gone.

Each open_mcap_file call opens a cursor over one channel of one file, and cursors on separate threads run in parallel, since each decodes without holding the interpreter lock. With the default limits, one cursor reads messages of up to 64 MiB, such as camera images and lidar point clouds.

The package ships prebuilt wheels for Linux (manylinux2014 and musllinux_1_2, x86-64 and aarch64), macOS (Intel and Apple Silicon) and Windows (x86-64 and ARM64). Each wheel targets CPython's stable ABI, so one wheel per platform serves CPython 3.10 and later. The package is published as these wheels only, so pip cannot install it on any other platform.

Install

pip install "roboto-mcap-codec[pyarrow]"

open_mcap_file needs PyArrow 20 or later, which the pyarrow extra installs. Without it, pip install roboto-mcap-codec installs only the per-message RosCdrCodec, and open_mcap_file raises ImportError naming the extra. PyArrow publishes no Windows ARM64 wheel, so there the extra installs nothing and open_mcap_file needs a PyArrow built separately.

Quick start

import os

import mcap_codec

path = "recording.mcap"
with open(path, "rb") as file:

    # Called for each byte range the cursor reads; return exactly `length` bytes.
    def read_bytes(offset: int, length: int) -> bytes:
        file.seek(offset)
        return file.read(length)

    with mcap_codec.open_mcap_file(
        read_bytes,
        os.path.getsize(path),
        channel=mcap_codec.TopicName("/odometry"),
        projection=mcap_codec.Projection(include=[["speed"], ["pose", "x"]]),
        timestamp=mcap_codec.TimestampSource("message_log_time"),
        time_window=(1_700_000_000_000_000_000, 1_700_000_060_000_000_000),
    ) as cursor:
        for batch in cursor:
            ...  # use the rows of this pyarrow.RecordBatch
  • Column 0 of every batch is the row number: the message's zero-based position among the channel's messages, in the order the file stores them. Column 1 is the timestamp in nanoseconds, from the source the timestamp argument names. The projected fields follow: a Projection's include paths, or every field without include, minus its exclude paths. An open_mcap_file call without projection gets every top-level field, and include=[] gets none.
  • Read each cursor from one thread at a time: a second call on a cursor while the first still runs raises RuntimeError.
  • cursor.to_record_batch_reader() returns a pyarrow.RecordBatchReader over the remaining batches, which PyArrow, DuckDB and Polars accept.
  • Close a cursor you stop reading, so it makes no further read_bytes calls; the with statement closes it when its block ends.
  • A failure raises CodecError, a ValueError whose code names it, such as unknown_channel, corrupt_input or resource_limit. The exceptions: an exception your read_bytes raises propagates unchanged, and a value of the wrong type, including a read_bytes result that is not bytes, raises TypeError.

The docstrings, such as help(mcap_codec.open_mcap_file), document every argument, class and error code.

Decoding single messages

A RosCdrCodec decodes one message at a time, from its bytes, without reading a file. Constructing one parses a schema, so build one per schema and reuse it for every message that schema describes:

from mcap_codec import RosCdrCodec, UnsupportedMessage

# schema_data: the schema's bytes, such as an MCAP Schema record's `data`
codec = RosCdrCodec("ros2msg", "cdr", schema_data, "sensor_msgs/msg/Imu")

# payload: a Message record's `data`; a CDR payload starts with its 4-byte
# encapsulation header
try:
    message = codec.decode(payload)
    partial = codec.decode_fields(
        payload, ["angular_velocity.x", "header.stamp.sec"]
    )
except UnsupportedMessage:
    message = partial = None  # a message the decoder declines; skip it

decode returns the message as dicts, lists and scalars, with each array of a fixed-width numeric type as an array.array. decode_fields returns the fields at the dotted paths it is given, nested as in the whole message, and builds no Python objects for the others. A message the decoder declines, such as one holding a wstring in a ROS 2 message or outside an IDL @mutable struct, raises UnsupportedMessage, a CodecError you can catch to skip it.

Changes from 0.1

  • McapBatchDecoder is removed; use open_mcap_file.
  • UnsupportedMessage derives from CodecError, and so from ValueError, where 0.1 derived it from Exception. Place an except UnsupportedMessage clause before any except ValueError clause, which would otherwise catch it.
  • RosCdrCodec raises CodecError, still a ValueError, with message text that differs from 0.1's; match on code, not on the text.

License

The package is licensed under MPL-2.0; see LICENSE. Versions 0.1.19 and earlier were published under Apache-2.0 and remain under it. NOTICE and THIRD_PARTY_LICENSES/ cover the third-party components compiled into the wheels.

Metadata

Release files for roboto-mcap-codec 0.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for roboto-mcap-codec 0.4.0
File Actions
roboto_mcap_codec-0.4.0-cp310-abi3-win_arm64.whl CPython 3.10 abi3 Windows ARM64 Details for roboto_mcap_codec-0.4.0-cp310-abi3-win_arm64.whl
roboto_mcap_codec-0.4.0-cp310-abi3-win_amd64.whl CPython 3.10 abi3 Windows x86-64 Details for roboto_mcap_codec-0.4.0-cp310-abi3-win_amd64.whl
roboto_mcap_codec-0.4.0-cp310-abi3-musllinux_1_2_x86_64.whl CPython 3.10 abi3 Linux musl 1.2+ x86-64 Details for roboto_mcap_codec-0.4.0-cp310-abi3-musllinux_1_2_x86_64.whl
roboto_mcap_codec-0.4.0-cp310-abi3-musllinux_1_2_aarch64.whl CPython 3.10 abi3 Linux musl 1.2+ ARM64 Details for roboto_mcap_codec-0.4.0-cp310-abi3-musllinux_1_2_aarch64.whl
roboto_mcap_codec-0.4.0-cp310-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl CPython 3.10 abi3 Linux glibc 2.17+ x86-64 Details for roboto_mcap_codec-0.4.0-cp310-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
roboto_mcap_codec-0.4.0-cp310-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl CPython 3.10 abi3 Linux glibc 2.17+ ARM64 Details for roboto_mcap_codec-0.4.0-cp310-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
roboto_mcap_codec-0.4.0-cp310-abi3-macosx_11_0_arm64.whl CPython 3.10 abi3 macOS 11.0+ ARM64 Details for roboto_mcap_codec-0.4.0-cp310-abi3-macosx_11_0_arm64.whl
roboto_mcap_codec-0.4.0-cp310-abi3-macosx_10_12_x86_64.whl CPython 3.10 abi3 macOS 10.12+ x86-64 Details for roboto_mcap_codec-0.4.0-cp310-abi3-macosx_10_12_x86_64.whl

Total release size: 17.8 MB

Release files / roboto_mcap_codec-0.4.0-cp310-abi3-win_arm64.whl

Download URL roboto_mcap_codec-0.4.0-cp310-abi3-win_arm64.whl
Size 2.1 MB
Tags CPython 3.10 Windows ARM64 abi3
SHA-256 checksum
How to use checksums
c5a0b26b2d907fb8a7b82f67704cbf81acaca4e262165b839640baa998d6a10d
BLAKE2b-256 checksum
How to use checksums
1f719c9e6daf43a15ead72599617f225e1d454e7511c274ad0a844ff1e80fce0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.

Transparency log

Release files / roboto_mcap_codec-0.4.0-cp310-abi3-win_amd64.whl

Download URL roboto_mcap_codec-0.4.0-cp310-abi3-win_amd64.whl
Size 2.2 MB
Tags CPython 3.10 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
2ff63c345d0815969bd03b9612c5ca12a1560ff62f7597f597ffd30639f4e4fb
BLAKE2b-256 checksum
How to use checksums
21bbf3f76c8c5a13f667ce6cedeeee255016e7e187902dde1360dbdf7255ef79
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.

Transparency log

Release files / roboto_mcap_codec-0.4.0-cp310-abi3-musllinux_1_2_x86_64.whl

Download URL roboto_mcap_codec-0.4.0-cp310-abi3-musllinux_1_2_x86_64.whl
Size 2.5 MB
Tags CPython 3.10 Linux musl 1.2+ x86-64 abi3
SHA-256 checksum
How to use checksums
13634b01b1ed60d5ac007706eb75ec5d67b996feab817ffaf941c066f31677fe
BLAKE2b-256 checksum
How to use checksums
535a37255c401e14dfedd580316b6f65416b609418c56e5aa9a3394ae9f12311
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.

Transparency log

Release files / roboto_mcap_codec-0.4.0-cp310-abi3-musllinux_1_2_aarch64.whl

Download URL roboto_mcap_codec-0.4.0-cp310-abi3-musllinux_1_2_aarch64.whl
Size 2.3 MB
Tags CPython 3.10 Linux musl 1.2+ ARM64 abi3
SHA-256 checksum
How to use checksums
45a6e7be2bc32d62f938eea5a3ef1dce6a71a5368660ef815dffb7dd478f77a7
BLAKE2b-256 checksum
How to use checksums
be14d3a530543d0c7c42e267e7e9e9b51928172a4a23b280078cec2ec9a74744
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.

Transparency log

Release files / roboto_mcap_codec-0.4.0-cp310-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl

Download URL roboto_mcap_codec-0.4.0-cp310-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Size 2.3 MB
Tags CPython 3.10 Linux glibc 2.17+ x86-64 abi3
SHA-256 checksum
How to use checksums
75e4efb6f58a9c252e55fa619188890b4bcd571f007e15230f4781ac18f5db6a
BLAKE2b-256 checksum
How to use checksums
7b34528b6f0facbed60ba03fc267677c32676ef0bbe33fecb16b8bb7090a3c56
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.

Transparency log

Release files / roboto_mcap_codec-0.4.0-cp310-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl

Download URL roboto_mcap_codec-0.4.0-cp310-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
Size 2.1 MB
Tags CPython 3.10 Linux glibc 2.17+ ARM64 abi3
SHA-256 checksum
How to use checksums
fb4b8a3873292551232d8ae9fea109d7c76914af0983090801c4e363e190a510
BLAKE2b-256 checksum
How to use checksums
6320d625a48889503ca7072ec6d5edbbd461577e06b9a19cfe79116e081e1b65
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.

Transparency log

Release files / roboto_mcap_codec-0.4.0-cp310-abi3-macosx_11_0_arm64.whl

Download URL roboto_mcap_codec-0.4.0-cp310-abi3-macosx_11_0_arm64.whl
Size 2.1 MB
Tags CPython 3.10 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
867a84d95a5281b97ae79acab3433691ad02ac1a10015e258dc405acd5d12b87
BLAKE2b-256 checksum
How to use checksums
1ea37aa6d6b9744290c817e57337e1fef2fb47dc301a0c9c1f296c21c340b534
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.

Transparency log

Release files / roboto_mcap_codec-0.4.0-cp310-abi3-macosx_10_12_x86_64.whl

Download URL roboto_mcap_codec-0.4.0-cp310-abi3-macosx_10_12_x86_64.whl
Size 2.2 MB
Tags CPython 3.10 abi3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
50bf7d165c837bb8161596d957ea13a7c9f3120a991f7bf9dac18e966b785d91
BLAKE2b-256 checksum
How to use checksums
3747caa88a6e32d4d53b7f117437d32fff2fac7b6222d70ba903e785670b8342
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.

Transparency log

Security for roboto-mcap-codec 0.4.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 8 files in this release have been uploaded with provenance metadata.

Select from 8 files

Attestation for roboto_mcap_codec-0.4.0-cp310-abi3-win_arm64.whl

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page