🚧 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 receive and record live Voyant LiDAR data to disk using the Python bindings, with support for automatic file splitting and recording limits.

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

What You’ll Learn

• How to create a VoyantRecorder instance in Python
• How to record frames with file splitting options
• How to handle recording limits and finalize cleanly

Prerequisites

• Python 3.9 or later
• voyant-api installed:

  pip install voyant-api
  

• A Voyant LiDAR sensor (or sensor simulator running in loopback mode)

Example Code

View the complete example on GitHub: recorder_example.py

Key Concepts

Creating the Recorder

from voyant_api import VoyantRecorder

recorder = VoyantRecorder(
    output_path="my_recording.bin",
    timestamp_filename=True,    # Adds timestamp to filename automatically
    frames_per_file=None,       # Split after N frames (None = no limit)
    size_per_file_mb=None,      # Split after N MB (None = no limit)
    max_total_frames=None,      # Stop after N total frames (None = no limit)
)

Use as a context manager to ensure finalize() is always called:

with VoyantRecorder(output_path="recording.bin") as recorder:
    while True:
        frame = client.try_receive_frame()
        if frame:
            status = recorder.record_frame(frame)
            if status == RecordStatus.STOP:
                break

RecordStatus

record_frame() returns a RecordStatus indicating what happened:

Status	Meaning
RecordStatus.OK	Frame recorded, continue
RecordStatus.SPLIT	Frame recorded, new file started
RecordStatus.STOP	Recording limit reached, stop

Command Line Options

python recorder_example.py --output my_recording.bin

# Split files every 100 frames
python recorder_example.py --output my_recording.bin --frames-per-file 100

# Stop after 10 minutes total
python recorder_example.py --output my_recording.bin --max-total-duration 600

# Disable timestamp in filename
python recorder_example.py --output my_recording.bin --no-timestamp-filename

Note: Python-based recording may struggle to keep up with high-frequency data streams. For reliable high-rate capture, use the native binary recorder tool.

Expected Output

Recording to 'my_recording.bin'. Press Ctrl+C to stop.
Recorded 100 frames in 1 files...
Recorded 200 frames in 1 files...
^C
Ctrl+C detected. Finalizing recording...
Finalizing recording after 243 total frames
Recording finalized

Next Steps

• Playback — replay your recording
• PCD Conversion — export frames to .pcd for visualization