Ex: Playback

Play back recorded point cloud data with Python.

This example demonstrates how to play back a Voyant recording and process frames using pandas DataFrames. Playback is sensor-agnostic — it reads any Voyant recording, regardless of which sensor produced it.

Requires pip install voyant-api.

What You’ll Learn

How to open and iterate over a .vynt 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 .vynt recording, either recorded from a sensor or downloaded:
- car_parking-v1_0_0.vynt
- people_walking-v1_0_0.vynt

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. The optional keep_invalid_points flag (default False) carries invalid points into the frames — those come from a capture made with the client’s diagnostic mode enabled; an ordinary recording has none:

from voyant_api import VoyantPlayback
from voyant_api.pandas_utils import frame_to_dataframe

with VoyantPlayback(keep_invalid_points=False) as playback:
    playback.open("my_recording.vynt")

    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 one column per recorded point field, in field order:

Column	Description
`range_m`	Distance from the sensor (meters)
`azimuth_rad` / `elevation_rad`	Direction (radians)
`doppler_mps`	Doppler velocity (m/s)
`snr`	Linear (not dB) signal-to-noise ratio
`calibrated_reflectance`	Calibrated surface reflectance
`timestamp_nanosecs`	Time within the frame (ns)
`azimuth_idx` / `elevation_idx`	Position in the scan grid
`drop_reason`	Point validity code (valid points read 1)
`combine_method`	How the DSP combined raw peaks into the point
`user_data`	User-owned bytes, `0` unless your tools stamp them

Pass cartesian=True to swap the geometry trio for x, y, z columns. The frame_to_xyz_dataframe() / frame_to_xyzv_dataframe() helpers return just the Cartesian positions (plus doppler_mps for the latter).

Command Line Options

python playback_example.py --input my_recording.vynt

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

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

Expected Output

#############
VoyantFrame(frame_index=20, n_points=15850, n_valid_points=15850, timestamp=1742330842.722152, device_id=...)
     range_m  azimuth_rad  elevation_rad  doppler_mps        snr  ...  drop_reason  combine_method  user_data
0   5.823360     0.033316       0.000000     1.229850  12.323400  ...          1.0            10.0        0.0
1   5.815240     0.033029       0.001718     1.198000  11.980000  ...          1.0            10.0        0.0
...

Next Steps

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