Data Recording (C++)

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

What You’ll Learn

How to configure and create a VoyantRecorder instance
How to record frames from a live VoyantClient
How to handle file splitting and recording limits
How to finalize a recording cleanly on exit

Prerequisites

Voyant API installed (see Installation)
A Voyant LiDAR sensor (or sensor simulator running in loopback mode)

Example Code

View the complete example on GitHub: voyant_recorder_basic.cpp

Key Concepts

Recorder Configuration

The VoyantRecorderConfig struct controls all recording behavior. Only the output path is required — all limits are optional.

VoyantRecorderConfig config("test_recording/recording.bin");

// Optional: split files after 50 frames or 20 MB, whichever comes first
config.framesPerFile = 50;
config.sizePerFileMb = 20;

// Optional: stop recording after 200 total frames
config.maxTotalFrames = 200;

VoyantRecorder recorder(config);

Recording Loop

Each call to recorder.recordFrame(frame) returns a RecordResult indicating what happened:

RecordResult result = recorder.recordFrame(frame);

switch (result)
{
    case RecordResult::Ok:       // Frame recorded, continue
    case RecordResult::Split:    // Frame recorded, new file started
    case RecordResult::Finished: // Limit reached, stop recording
    case RecordResult::Error:    // Something went wrong
}

Finalizing

Always call recorder.finalize() before exit to ensure all data is flushed and files are properly closed:

recorder.finalize();

Building and Running

# Build the examples
mkdir build && cd build
cmake ..
make

# Run the recorder example
./bin/voyant_recorder_basic

Expected Output

Starting Voyant recording example...
Listening for frames (press Ctrl+C to stop)...
Recorded 100 frames
Recorded 200 frames across 4 files

Finalizing recording...
Recording complete!

Next Steps

Use Playback (C++) to read back your recording
Use the Python PCD Conversion example to export frames to .pcd files for visualization