tachy-reader

Zero-service MCAP playback library for ROS2. Rust core (via PyO3) with a pure-Python API.

No DDS services are registered — all playback control happens via in-process method calls, keeping the ROS2 graph clean.

Features

• Rust-powered core: memory-mapped MCAP reading with zero-copy message access
• Zero ROS2 services: no parameter/logger/type-description services polluting the graph
• Simple API: context-manager pattern, blocking or async playback
• Playback control: play, pause, resume, stop, seek, rate adjustment
• Topic filtering: include/exclude specific topics
• QoS overrides: per-topic QoS profile configuration
• Callbacks: on_publish and on_complete hooks

Installation

From source (requires Rust toolchain)

pip install git+https://github.com/tachycode/tachy-reader.git@dev

Local development

git clone https://github.com/tachycode/tachy-reader.git
cd tachy-reader
pip install -e .

Prerequisites: Rust toolchain (rustup), Python ≥ 3.8, maturin ≥ 1.5

Quick Start

from mcap_player import McapPlayer

with McapPlayer("/path/to/recording.mcap") as player:
    # Blocking playback at 2x speed
    player.play(rate=2.0)

Non-blocking playback

with McapPlayer("recording.mcap") as player:
    player.play_async(rate=1.0)

    while player.state != "finished":
        print(f"Progress: {player.progress:.1%}")
        time.sleep(1.0)

Topic filtering

player = McapPlayer(
    "recording.mcap",
    topics=["/camera/image_raw", "/imu/data"],
    topic_prefix="/replay",
)

Playback control

player.play_async()
player.pause()
player.seek(10.5)       # jump to 10.5 seconds
player.set_rate(0.5)    # half speed
player.resume()
player.stop()

API Reference

McapPlayer

Parameter	Type	Description
mcap_path	str	Path to .mcap file
node_name	str	ROS2 node name (default: "mcap_player")
topic_prefix	str	Prefix for published topics
topics	list[str]	Whitelist of topics to publish
exclude_topics	list[str]	Topics to skip
qos_overrides	dict	Per-topic QoS profiles
on_publish	Callable	Called after each message publish
on_complete	Callable	Called when playback finishes
node	Node	Existing rclpy Node (optional)

Properties

Property	Type	Description
current_time	float	Current position in seconds
progress	float	Playback progress (0.0 – 1.0)
state	str	"idle", "playing", "paused", "finished"
duration	float	Total file duration in seconds
topics_info	dict	Topic metadata {name: (msg_type, encoding)}

License

Apache-2.0