Metadata-Version: 2.4
Name: hebbian-mcap
Version: 0.1.1
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Rust
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Software Development :: Libraries
Requires-Dist: av>=18.1.0 ; extra == 'video'
Requires-Dist: numpy>=2.3.5 ; extra == 'video'
Requires-Dist: mcap>=1.4.0 ; extra == 'video'
Requires-Dist: mcap-protobuf-support>=0.5.4 ; extra == 'video'
Requires-Dist: mcap-ros2-support>=0.5.7 ; extra == 'video'
Provides-Extra: video
License-File: LICENSE
License-File: LICENSE-MIT
License-File: NOTICE
License-File: crates/mcap-tools/schemas/LICENSE
Summary: Rust-backed MCAP writer for Python with grouped chunks, ROS 2/Foxglove encodings, and optional MCAP-to-MP4 video export
Keywords: mcap,robotics,ros2,foxglove,video,rust,pyo3
Author: Hebbian Robotics
License-Expression: Apache-2.0
Requires-Python: >=3.11
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://github.com/Hebbian-Robotics/mcap-tools#readme
Project-URL: Issues, https://github.com/Hebbian-Robotics/mcap-tools/issues
Project-URL: Repository, https://github.com/Hebbian-Robotics/mcap-tools

# MCAP Tools: Rust and Python writing and video export

[![CI](https://github.com/Hebbian-Robotics/mcap-tools/actions/workflows/ci.yml/badge.svg)](https://github.com/Hebbian-Robotics/mcap-tools/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/hebbian-mcap)](https://pypi.org/project/hebbian-mcap/)

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

```sh
uv add 'hebbian-mcap==0.1.1'
```

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](https://github.com/Hebbian-Robotics/mcap-tools/blob/main/crates/mcap-tools/README.md).

## Write grouped MCAP recordings

```python
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](https://github.com/Hebbian-Robotics/mcap-tools/blob/main/docs/behavior.md#grouped-writer) for timestamps,
flush rules and lifecycle. For reading, use the official
[Python MCAP reader](https://mcap.dev/docs/python/mcap-apidoc/mcap.reader).

## Read and rewrite video messages

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

```python
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](https://github.com/Hebbian-Robotics/mcap-tools/blob/main/docs/behavior.md#standard-messages).

## Export MCAP camera video to MP4

Install the video extra, then select a camera topic:

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

The equivalent Python API is:

```python
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](https://github.com/Hebbian-Robotics/mcap-tools/blob/main/docs/behavior.md#video-export) 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

- [MCAP specification](https://mcap.dev/spec): the standard file format.
- [Foxglove CompressedVideo schema](https://docs.foxglove.dev/docs/sdk/schemas/compressed-video): video message layout and codec requirements.
- [Contributing](https://github.com/Hebbian-Robotics/mcap-tools/blob/main/CONTRIBUTING.md): validation, dependency updates and releases.
- [LiveKit Cameras](https://github.com/Hebbian-Robotics/livekit-cameras): browser/native camera streaming and H.264 recording primitives.

Rust/Python code uses [Apache-2.0](https://github.com/Hebbian-Robotics/mcap-tools/blob/main/LICENSE), with MIT exceptions described in
[NOTICE](https://github.com/Hebbian-Robotics/mcap-tools/blob/main/NOTICE). Browser utilities use [MIT](LICENSE-MIT).

## Browser playback

The [TypeScript library](typescript/README.md) 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.

