Skip to content

About

Rust and Python tools for standard MCAP files: grouped writing, ROS 2 and Foxglove message encoding, and camera video export to MP4.

Topics

Resources

Contributing

Stars

3 stars

Watchers

0 watching

Forks

Repository files navigation

MCAP Tools: Rust and Python writing and video export

CI PyPI

Write standard MCAP recordings with separate chunk groups for video and telemetry, encode and decode ROS 2/Foxglove messages, and export camera topics from MCAP to MP4. Python and Rust share the official Rust MCAP writer through a small grouping layer. Maintained by Hebbian Robotics; this is an independent Foxglove-compatible project, not an official Foxglove product.

Install

uv add 'hebbian-mcap==0.1.2'

Prebuilt CPython 3.11+ wheels support Linux (glibc 2.17+, x86_64/aarch64), macOS (x86_64/aarch64) and Windows (x86_64), without a Rust installation. Source builds require Rust 1.92+. The Rust crate is available through a pinned Git dependency and is not published to crates.io; see the Rust crate guide.

Write grouped MCAP recordings

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}')

Groups buffer independently, so indexed readers can select camera data without fetching telemetry chunks, or vice versa. Standard MCAP compression, indexes, metadata and attachments are preserved. Python path outputs are published atomically; caller-owned streams stay open.

See the writer behavior reference for timestamps, flush rules and lifecycle. For reading, use the official Python MCAP reader.

Read and rewrite video messages

Read a channel's CompressedVideo messages, or replace a payload and keep every other field:

from hebbian_mcap import CompressedVideoCodec

codec = CompressedVideoCodec(channel.message_encoding, schema.encoding, schema.name, schema.data)
video = codec.decode(message.data)
repaired = codec.replace_data(message.data, new_payload)

Foxglove protobuf and ROS 2 CDR channels are supported. CDR messages are read through the channel's schema, so fields a recorder added are preserved. See standard messages.

Export MCAP camera video to MP4

Install the video extra, then select a camera topic:

uv add 'hebbian-mcap[video]==0.1.2'
mcap-export recording.mcap front.mp4 --topic /cameras/front/video

The equivalent Python API is:

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"
)

Export requires at least two frames and fixed dimensions. It preserves log-time gaps, leaves the source unchanged and refuses to overwrite an existing output. See video export behavior for supported formats, timing and limits.

Only the video extra installs PyAV, NumPy and message decoders. The base Python writer and Rust crate do not need video codecs. hebbian_mcap.h264 provides standard-library-only Annex B inspection and repair helpers.

References and development

Rust/Python code uses Apache-2.0, with MIT exceptions described in NOTICE. Browser utilities use MIT.

Browser playback

The TypeScript library provides HTTP byte-range reading for MCAP, H.264 remuxing to MP4 and a shared playback clock for multiple cameras. It is independent of the Rust/Python writer and any robot application.

About

Rust and Python tools for standard MCAP files: grouped writing, ROS 2 and Foxglove message encoding, and camera video export to MP4.

Topics

Resources

Contributing

Stars

3 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages