Playback Recording

This example demonstrates how to use the Voyant SDK to play back previously recorded LiDAR data from a file. The recorded data must be in the voyant proto message format.

What You’ll Learn

How to create a VoyantPlayback instance
How to open and read LiDAR data from recording files
How to control playback rates and looping
How to access frame data from recordings

Prerequisites

Voyant API installed (see Installation)
A Voyant *.bin data file, either:
- Recorded from a Voyant LiDAR sensor or simulator using the voyant_logger_binary tool.
- Downloaded from available datasets associated with our latest format:

Example Code

View the complete example on GitHub: voyant_playback_basic.cpp

Key Concepts

This example demonstrates the basic usage of the VoyantPlayback class.

Playback Configuration

The VoyantPlayback constructor takes two parameters:

Playback rate (speed multiplier)
Looping flag (whether to repeat the recording)

// Create playback with 1.0x speed (real-time) and no looping
VoyantPlayback player(1.0, false);

// For double-speed playback with looping
// VoyantPlayback player(2.0, true);

// For maximum speed playback (as fast as possible)
// VoyantPlayback player(0.0, false);

Opening Recording Files

Once a player is created, you can open a recording file:

if(!player.openFile("path/to/recording.bin"))
{
    std::cerr << "Failed to open file: " << player.getLastError() << std::endl;
    return 1;
}

Frame Playback Loop

The main loop:

Calls player.nextFrame() which waits an appropriate amount of time between frames (based on playback rate)
Accesses the current frame’s metadata and content
Processes the frame data as needed

while(player.nextFrame())
{
    // Get frame metadata
    size_t frameIndex = player.currentFrameIndex();
    uint64_t timestamp = player.currentFrameTimestamp();

    // Access the current frame
    const VoyantFrameWrapper &frame = player.currentFrame();

    // Process frame data...
}

The loop exits when there are no more frames (or an error occurs). If looping is enabled, the nextFrame function will continue returning frames until you terminate the program.

Frame Access

You can access the frame data as a mutable reference, a const reference, or by making a copy. Here we access the data as a const reference:

// Access latest frame as a const reference
const VoyantFrameWrapper &frame = player.currentFrame();

Error Handling

Note: This error handling approach is likely to change in an upcoming minor release.

The playback example demonstrates the current error handling approach in the VoyantPlayback class.

if(!player.getLastError().empty())
{
    std::cerr << "Error during playback: " << player.getLastError() << std::endl;
    return 1;
}

Command Line Arguments

The example accepts the following command line arguments:

<recording_file_path>: Path to the recording file (required)
[playback_rate]: Optional playback speed multiplier:
- 0 for as-fast-as-possible
- 1.0 for real-time (default)
- 2.0 for double speed, etc.
[loop]: Optional, specify “loop” to enable looping (default: disabled)

See playback_options.hpp for more details.

Building and Running

You can build and run this example using CMake:

From /workspace/ if building in provided docker container.
From voyant-sdk/ if building on your native system.

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

# Run the playback example
./bin/voyant_playback path/to/my_recording.bin 1.0

Expected Output

When playing back a recording file, you should see output similar to:

Opening file: my_recording.bin
###############
Frame 1 (timestamp: 1742330842.722s)
Header{message type:2, device id:MDL-000, frame idx:133, stamp:1742330842.721523408, proto version:0.1.0, api version:0.1.0}
Config{ len: 0 }
Points[23040] {{idx:0,ts:0,pos:[5.820,0.000,-2.411],v:1.000,snr:0.000,refl:0.000,noise:0.000,min_snr:0.000,drop reason:1},...}
...

Playback complete!
Processed 256 frames

Next Steps

After understanding the playback example, you might want to explore:

How to create your own recordings
Processing and analyzing recorded LiDAR data
Converting recordings to other formats for visualization

See our other examples or refer to the API Documentation for more advanced usage.