#include <cstdarg>
#include <cstdint>
#include <cstdlib>
#include <ostream>
#include <new>
#include <voyant_types_ffi.hpp>

Classes
struct	VoyantRecorderC

Functions
VoyantRecorderC	voyant_recorder_create (const char output_path, bool timestamp_filename, bool overwrite, uint32_t frames_per_file, uint64_t duration_per_file, uint64_t size_per_file_mb, uint32_t max_total_frames, uint64_t max_total_duration, uint64_t max_total_size_mb, char error_buf, uintptr_t error_capacity)
int32_t	voyant_recorder_record_frame (VoyantRecorderC recorder, const VoyantFrameMeta meta, const PointDataV1 *points)
int32_t	voyant_recorder_frames_recorded (const VoyantRecorderC *recorder)
int32_t	voyant_recorder_split_count (const VoyantRecorderC *recorder)
uintptr_t	voyant_recorder_current_file_path (const VoyantRecorderC recorder, char buf, uintptr_t capacity)
int32_t	voyant_recorder_finalize (VoyantRecorderC recorder)

Function Documentation

◆ voyant_recorder_create()

VoyantRecorderC voyant_recorder_create	(	const char *	output_path,
		bool	timestamp_filename,
		bool	overwrite,
		uint32_t	frames_per_file,
		uint64_t	duration_per_file,
		uint64_t	size_per_file_mb,
		uint32_t	max_total_frames,
		uint64_t	max_total_duration,
		uint64_t	max_total_size_mb,
		char *	error_buf,
		uintptr_t	error_capacity )

Creates a new VoyantRecorder instance

Parameters

output_path	C string containing base path to the output recording file(s); must end in .vynt
timestamp_filename	Whether to add timestamp to filename (true/false)
overwrite	Allow overwriting an existing output file (false = fail instead)
frames_per_file	Maximum frames per file before splitting (0 = no limit)
duration_per_file	Maximum duration per file in seconds before splitting (0 = no limit)
size_per_file_mb	Maximum size per file in MB before splitting (0 = no limit)
max_total_frames	Maximum total frames across all files (0 = no limit)
max_total_duration	Maximum total duration in seconds across all files (0 = no limit)
max_total_size_mb	Maximum total size in MB across all files (0 = no limit)
error_buf	Buffer receiving the failure reason (see the string contract in voyant_types_ffi.hpp); untouched on success. Creation opens the first file, so this is where a rejected extension or a refused overwrite is reported
error_capacity	Size of error_buf in bytes

Returns: VoyantRecorderC struct containing the recorder instance

Note: Returns a VoyantRecorderC with null pointer if creation fails

Warning: output_path must be a valid null-terminated C string; error_buf must be null or point to a buffer of at least error_capacity bytes

Note: Using 0 for any limit parameter means "no limit" for that constraint

◆ voyant_recorder_current_file_path()

uintptr_t voyant_recorder_current_file_path	(	const VoyantRecorderC *	recorder,
		char *	buf,
		uintptr_t	capacity )

Copies the path of the file currently being written into buf, with timestamp and split naming resolved

Parameters

recorder	Pointer to VoyantRecorderC instance
buf	Destination buffer, NUL-terminated on return
capacity	Size of buf in bytes

Returns: Full length of the path in bytes, excluding the NUL — a value >= capacity means the copy was truncated. 0 if the recorder is invalid.

Warning: recorder must be a valid VoyantRecorderC instance

◆ voyant_recorder_finalize()

int32_t voyant_recorder_finalize ( VoyantRecorderC recorder )

Finalizes the recording and frees the recorder instance

This function properly closes the file and releases all resources. The recorder should not be used after calling this function.

Parameters

recorder VoyantRecorderC instance to finalize and free

Returns: 1: Successfully finalized; 0: Failed to finalize (I/O error during flush/close); -1: Invalid recorder instance

Warning: After calling this function, the recorder instance should not be used

◆ voyant_recorder_frames_recorded()

int32_t voyant_recorder_frames_recorded ( const VoyantRecorderC * recorder )

Gets the number of frames recorded so far across all files

Parameters

recorder Pointer to VoyantRecorderC instance

Returns: Number of frames recorded, -1 if recorder is invalid

Warning: recorder must be a valid VoyantRecorderC instance

◆ voyant_recorder_record_frame()

int32_t voyant_recorder_record_frame	(	VoyantRecorderC *	recorder,
		const VoyantFrameMeta *	meta,
		const PointDataV1 *	points )

Records a single frame from its transferred fields and point array

The frame is tagged by whether it carries state (meta's state_provenance) — re-recording a stateless frame keeps it stateless.

Parameters

recorder	Pointer to VoyantRecorderC instance
meta	Pointer to the frame's fixed-size fields; meta->n_points is the length of points (VoyantFrame::toMeta() derives it from the vector, so an edited frame carries its own new count)
points	Pointer to meta->n_points points (may be null only when n_points is 0)

Returns: 0: Successfully recorded frame, continue recording; 1: Successfully recorded frame, file was split due to limits; 2: Limits reached - recording should stop (not an error); -1: Failed to record frame (I/O error, etc.); -2: Invalid recorder instance or null input

Warning: recorder must be a valid VoyantRecorderC instance

◆ voyant_recorder_split_count()

int32_t voyant_recorder_split_count ( const VoyantRecorderC * recorder )

Gets the number of files created (split count)

Parameters

recorder Pointer to VoyantRecorderC instance

Returns: Number of files created, -1 if recorder is invalid

Warning: recorder must be a valid VoyantRecorderC instance

Classes

Functions

Function Documentation

◆ voyant_recorder_create()

◆ voyant_recorder_current_file_path()

◆ voyant_recorder_finalize()

◆ voyant_recorder_frames_recorded()

◆ voyant_recorder_record_frame()

◆ voyant_recorder_split_count()