Ex: Playback

Play back recorded point cloud data with C++.

This example demonstrates how to use the Voyant SDK to play back previously recorded LiDAR data from a file. Playback is sensor-agnostic — it reads any Voyant recording, regardless of which sensor produced it.

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 SDK installed (see Installation)
• A Voyant .vynt recording, either:
  • Recorded from a sensor or simulator with the Data Recording example.
  • Downloaded from our sample datasets:
    • car_parking-v1_0_0.vynt
    • people_walking-v1_0_0.vynt

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 three parameters, all optional:

• Playback rate (speed multiplier, default 1.0)
• Looping flag (whether to repeat the recording, default false)
• keep_invalid_points (default false) — when true, frames keep their invalid points. Those come from a capture made with the client’s diagnostic mode enabled; an ordinary recording has none.

// 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);

// To keep invalid points from a diagnostic-mode capture
// VoyantPlayback player(1.0, false, true);

Opening Recording Files

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

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

Opening a recording made before v1.0.0 fails with an error naming the exact voyant_recording_migrate command to convert it.

Frame Playback Loop

The main loop:

1. Calls player.nextFrame() which waits an appropriate amount of time between frames (based on playback rate)
2. Accesses the current frame’s metadata and content
3. 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 VoyantFrame &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 VoyantFrame &frame = player.currentFrame();

To modify a frame’s points and save the result, see the Edit a Recording example.

Error Handling

The playback example demonstrates the 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_basic path/to/my_recording.vynt 1.0

Expected Output

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

Opening file: my_recording.vynt
###############
Frame 133 (timestamp: 1742330842.722s)
VoyantFrame(frame_index=133, n_points=15850, n_valid_points=15850, timestamp=1742330842.721523, device_id=...)
...

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.