Playback (Python)

🚧 These docs are currently out of date. 🚧

They reflect the Meadowlark (Carbon dev kit) API and may not apply to Carbon systems.
Fully updated documentation will be published when Carbon Alpha ships in April 2026.

Questions? Reach out to us at: support@voyantphotonics.com

This example demonstrates how to play back a Voyant .bin recording and process frames using pandas DataFrames.

Available from v0.4.4. Requires pip install voyant-api.

What You’ll Learn

How to open and iterate over a .bin recording in Python
How to convert frames to pandas DataFrames using voyant_api.pandas_utils
How to control playback rate and looping

Prerequisites

Python 3.9 or later
voyant-api installed:
```
pip install voyant-api
```
A Voyant .bin recording file, either recorded from a sensor or downloaded:
- car_parking-v0_2_2.bin
- people_walking-v0_2_2.bin

Example Code

View the complete example on GitHub: playback_example.py

Key Concepts

Opening a Recording

VoyantPlayback supports Python’s context manager and iterator protocols:

from voyant_api import VoyantPlayback
from voyant_api.pandas_utils import frame_to_dataframe

with VoyantPlayback(filter_points=True) as playback:
    playback.open("my_recording.bin")

    for frame in playback:
        if frame is None:
            break

        df = frame_to_dataframe(frame)
        print(df.head())

DataFrame Columns

frame_to_dataframe() returns a DataFrame with 7 columns:

Column	Type	Description
`x`	float32	X position (meters)
`y`	float32	Y position (meters)
`z`	float32	Z position (meters)
`radial_vel`	float32	Doppler velocity (m/s)
`snr_linear`	float32	Signal-to-noise ratio
`nanosecs_since_frame`	float32	Timestamp within frame
`drop_reason`	float32	Point validity code

For all extended fields (reflectance, noise, etc.) use frame_to_extended_dataframe() instead.

Command Line Options

python playback_example.py --input my_recording.bin

# Keep invalid points
python playback_example.py --input my_recording.bin --keep-invalid-points

# Loop continuously
python playback_example.py --input my_recording.bin --loopback

Expected Output

#############
VoyantFrame(frame_index=20, n_points=15850, n_valid=15850, timestamp=1742330842.722)
            x         y         z  radial_vel  snr_linear  nanosecs_since_frame  drop_reason
0    5.820130  0.193966  0.000000    1.229850   12.323400                   0.0          1.0
1    5.812000  0.192000  0.010000    1.198000   11.980000               16384.0          1.0
...

Next Steps

PCD Conversion — export frames to .pcd files for visualization in CloudCompare or Open3D
Recorder — record live data to create your own .bin files