Ex: Playback

Play back recorded point cloud data with Python.

🚧 These docs are out of date as of May, 2026. 🚧

They reflect the Meadowlark (Carbon dev kit) API and may not apply to Carbon systems.

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