Skip to main content

MCAP tools

Tools for working with standard MCAP files, built on the official Rust MCAP library. Maintained by Hebbian Robotics. This project does not extend the MCAP format and is not an official Foxglove project.

The hebbian-mcap Rust crate and Python package share one Rust implementation:

  • Independently buffered channel groups, with per-group chunk targets.
  • Indexed zstd or uncompressed chunks, metadata, and attachments.
  • Foxglove CompressedVideo protobuf and ROS 2 JointState CDR encoding.
  • Atomic publication for Python path outputs; caller-owned binary streams stay open.
from hebbian_mcap import GroupedMcapWriter, NO_SCHEMA_ID

with GroupedMcapWriter("recording.mcap") as writer:
    channel = writer.register_channel("/state", "json", NO_SCHEMA_ID, group="telemetry")
    writer.write_message(channel, 123, b'{"position": 1}')

Times are nanoseconds since the Unix epoch. Publish time defaults to log time. Grouping changes physical write order; indexed readers recover time order. Messages retain their original sequence and timestamps. Groups flush in registration order at finish, or when they exceed their configured size. Rust callers can also bound buffer age; age is checked on writes, not by a background timer.

Adding metadata or attachments flushes waiting messages first.

The upstream MCAP writer owns compression, CRCs, indexes, and footer serialization. A small buffering layer isolates groups and can be replaced by upstream grouping support without changing the public API. Upstream may store schema/channel records in chunks with no messages; consumers should use message indexes for selective reads.

Installation and development

Until packages are released, use a Git dependency pinned to a commit. Python source installs require a Rust toolchain; CI builds and smoke-tests native wheels for Linux, macOS, and Windows. See CONTRIBUTING.md.

uv add 'hebbian-mcap @ git+https://github.com/Hebbian-Robotics/mcap-tools@COMMIT'

Packages are not yet published to PyPI or crates.io. A source installation needs Rust 1.92+. Publish the Python wheels before a consumer declares a released PyPI dependency on this package.

The Python module is hebbian_mcap; the Rust library is hebbian_mcap. The official Python mcap reader remains compatible and is not replaced.

Optional camera export

Install hebbian-mcap[video] to export a selected camera to MP4:

from pathlib import Path
from hebbian_mcap.video import export_mcap_camera

result = export_mcap_camera(
    Path("recording.mcap"), Path("front.mp4"), camera_topic="/cameras/front/video"
)
mcap-export recording.mcap front.mp4 --topic /cameras/front/video

The exporter reads standard Foxglove video/image and ROS 2 camera schemas using JSON, protobuf, or CDR messages. H.264 without B-frames is remuxed, with lossless AUD repair when needed. Supported raw RGB/gray and JPEG/PNG frames are encoded as lossless RGB H.264. Original log-time gaps are preserved to microsecond precision; the final frame repeats the preceding interval. At least two frames are required. Select an exact topic when more than one camera is declared. Source recordings and existing destination files are preserved on failure.

CameraExportLimits bounds frame dimensions, duration and average frame rate. Native decoding is synchronous; callers own process isolation when they need a hard deadline. PreparedMcapVideo reports the selected topic, original first log time, exported duration and output path.

Only the [video] extra installs PyAV, NumPy and MCAP message decoders. The Rust crate and default Python writer do not depend on video codecs. The H.264 inspection helpers in hebbian_mcap.h264 use only the Python standard library.

Licensed under Apache-2.0; see NOTICE for schema attribution.

Metadata

Release files for hebbian-mcap 0.1.0

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

Source distribution (sdist)

Source distribution for hebbian-mcap 0.1.0
File Size Uploaded Provenance Actions
hebbian_mcap-0.1.0.tar.gz 33.6 kB Without provenance Details for hebbian_mcap-0.1.0.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for hebbian-mcap 0.1.0
File Actions
hebbian_mcap-0.1.0-cp311-abi3-win_amd64.whl CPython 3.11 abi3 Windows x86-64 Details for hebbian_mcap-0.1.0-cp311-abi3-win_amd64.whl
hebbian_mcap-0.1.0-cp311-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl CPython 3.11 abi3 Linux glibc 2.17+ x86-64 Details for hebbian_mcap-0.1.0-cp311-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
hebbian_mcap-0.1.0-cp311-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl CPython 3.11 abi3 Linux glibc 2.17+ ARM64 Details for hebbian_mcap-0.1.0-cp311-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
hebbian_mcap-0.1.0-cp311-abi3-macosx_11_0_arm64.whl CPython 3.11 abi3 macOS 11.0+ ARM64 Details for hebbian_mcap-0.1.0-cp311-abi3-macosx_11_0_arm64.whl
hebbian_mcap-0.1.0-cp311-abi3-macosx_10_12_x86_64.whl CPython 3.11 abi3 macOS 10.12+ x86-64 Details for hebbian_mcap-0.1.0-cp311-abi3-macosx_10_12_x86_64.whl

Total release size: 3.1 MB

Release files / hebbian_mcap-0.1.0.tar.gz

Download URL hebbian_mcap-0.1.0.tar.gz
Size 33.6 kB
Tags Source
SHA-256 checksum
How to use checksums
35845094f7d74ba428305c6eed7008cdc491c0f269494760edf0b6b18d561d16
BLAKE2b-256 checksum
How to use checksums
597ee25ba9b4d74999bbf33dc0c989c4324c3b53d6b5393095cc21587fa68ade
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / hebbian_mcap-0.1.0-cp311-abi3-win_amd64.whl

Download URL hebbian_mcap-0.1.0-cp311-abi3-win_amd64.whl
Size 479.3 kB
Tags CPython 3.11 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
65f26d177478a95fe9abf50ec056d8d6d4df3e04c0279469ff50601a417191dd
BLAKE2b-256 checksum
How to use checksums
c8baa573437df2b82a9d001252c2ea8a1e0ab2655a8014c097e9283c0b6ebea7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / hebbian_mcap-0.1.0-cp311-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl

Download URL hebbian_mcap-0.1.0-cp311-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Size 686.0 kB
Tags CPython 3.11 Linux glibc 2.17+ x86-64 abi3
SHA-256 checksum
How to use checksums
238ca2985779bd63bc6344e70dc8a18dcb97906d1bae22ab9f8c6fb2e3982dcd
BLAKE2b-256 checksum
How to use checksums
ad0431861e259dc72c0326db37166cdfd65e46d08da26c5906cec89f45c6a903
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / hebbian_mcap-0.1.0-cp311-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl

Download URL hebbian_mcap-0.1.0-cp311-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
Size 691.7 kB
Tags CPython 3.11 Linux glibc 2.17+ ARM64 abi3
SHA-256 checksum
How to use checksums
1a9bc08328cdc063d22fa972e0930ecd8cb8c02d7c8da6c43c442d1d154af0a5
BLAKE2b-256 checksum
How to use checksums
6e243bdfae9592d0f4ad96bf8f127c831eda429f214a242890a73654717c1062
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / hebbian_mcap-0.1.0-cp311-abi3-macosx_11_0_arm64.whl

Download URL hebbian_mcap-0.1.0-cp311-abi3-macosx_11_0_arm64.whl
Size 560.2 kB
Tags CPython 3.11 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
b823fa90d3a33b00e724af9d49a54870362fb3c52e6fcdc9658ae2be46f5f445
BLAKE2b-256 checksum
How to use checksums
42c73b49a463fe7a55dd5b9ba7ca7f7b23be6b20ae0e225e7f322e73fbd599c0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / hebbian_mcap-0.1.0-cp311-abi3-macosx_10_12_x86_64.whl

Download URL hebbian_mcap-0.1.0-cp311-abi3-macosx_10_12_x86_64.whl
Size 613.2 kB
Tags CPython 3.11 abi3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
65b7cf112de4cf7c0446d912927ad4cfa95c8bfa13e20d69d3da852de7f2e678
BLAKE2b-256 checksum
How to use checksums
f35521c241ef1fecf9788676b525aeaafb905bcd665d690fc06059e0478be40c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Security for hebbian-mcap 0.1.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.

No provenance found

None of the files in this release were uploaded with provenance metadata.

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