C++ models and configuration

C++ wrapper 0.24.0, core 0.24.0, C++11 or newer. Include aic.hpp and link the matching wrapper/native libraries. Start with the C++ integration guide. All names below are in namespace aic. Check Result and error handling before extracting a factory result. Ordinary C++ allocation or string operations can still throw; SDK status failures use the declared return values.

`aic::Model`

Owns one native handle. Its destructor releases that handle; do not destroy or move the object while another thread uses it. Construction/destruction can allocate or block, so keep them outside the audio callback. The default constructor and raw-handle constructor are private: use the documented factory.

Member	Contract
`~Model()`	Releases the native handle if non-null.
`Model(Model&& other) noexcept`	Transfers the handle and clears the source. Do not call processing/getter methods on the moved-from object.
`Model& operator=(Model&& other) noexcept`	Releases the destination’s old handle, transfers ownership and clears the source. Self-move is guarded; returns `*this`.
`Model(const Model&) = delete`	Copy construction is unavailable.
`Model& operator=(const Model&) = delete`	Copy assignment is unavailable.

Model bytes are shared internally with derived processors, VADs and analyzers. Destroying this wrapper does not release their model reference. Keep a mapped file or borrowed model buffer valid until every derived object has been destroyed.

`aic::Model::create_from_file`

static Result<Model> create_from_file(const std::string& file_path);

Loads and memory-maps the UTF-8 path file_path. Returns an owned model on success. Do not change or delete the file while the model or derived objects remain alive. Errors include FilePathInvalid, FileSystemError, ModelInvalid, ModelVersionUnsupported and ModelDataUnaligned. The factory forwards file_path.c_str() to C; embedded NUL characters terminate the path. Perform file I/O outside the audio callback.

`aic::Model::create_from_buffer`

static Result<Model> create_from_buffer(const uint8_t* buffer, size_t buffer_len);

Borrows buffer_len bytes at buffer, aligned to 64 bytes. It does not copy or own the allocation. Keep it alive and unchanged through the lifetimes of this model and every derived object. Returns a checked model or errors such as NullPointer, ModelInvalid, ModelVersionUnsupported or ModelDataUnaligned. Destroying a model does not free the caller’s buffer.

`aic::Model::get_id`

std::string get_id() const;

Returns a copy of the model ID. Unlike the C pointer getter, this string remains valid independently of the model. A null underlying handle returns an empty string. Copying can allocate.

`aic::Model::get_optimal_sample_rate`

uint32_t get_optimal_sample_rate() const;

Returns the native sample rate in Hz. The wrapper asserts that the C call succeeded; it does not return an error object. Use a valid, successfully created model. In assertion-disabled builds, the initialized fallback value is zero if the C call fails.

`aic::Model::get_optimal_block_size`

size_t get_optimal_block_size(uint32_t sample_rate) const;

Returns the model hop size converted to sample_rate in Hz, in mono samples. The query does not validate supported rates; initialization performs that check. The wrapper asserts on C errors and has a zero fallback in assertion-disabled builds. Keep the model valid.

`aic::ProcessorConfig`

Stores audio configuration values. This is a convenience value type; wrapper 0.24.0 has no initialize(ProcessorConfig) overload. Pass its three fields to the object’s three-argument initialize method.

`aic::ProcessorConfig::ProcessorConfig`

ProcessorConfig(uint32_t sample_rate, size_t block_size, bool variable_block_size = false);

Stores the arguments without validating them. Validation happens when you initialize a processor, VAD or collector. This constructor is not a default constructor: the rate and block size are required.

Field	Type	Meaning
`sample_rate`	`uint32_t`	Input rate in Hz. Initialization supports 8,000–192,000 inclusive.
`block_size`	`size_t`	Positive mono sample count. Fixed size, or maximum when variable sizing is enabled.
`variable_block_size`	`bool`	Defaults to false through the constructor. True allows each call to provide at most `block_size` samples.

`aic::OtelConfig`

`aic::OtelConfig::OtelConfig`

OtelConfig(bool enable = false, const char* session_id = nullptr,
           uint32_t export_interval_ms = 0);

Stores the arguments. Passing no config pointer to a factory preserves environment defaults; passing an OtelConfig{} explicitly disables optional OTel export. This does not disable SDK session telemetry. The struct does not own session_id; keep it valid through the factory call, which copies it.

Field	Type and default	Meaning
`enable`	`bool = false`	Overrides `AIC_SDK_OTEL_ENABLE` when a config is supplied.
`session_id`	`const char* = nullptr`	Optional null-terminated session label; nullptr requests a generated ID.
`export_interval_ms`	`uint32_t = 0`	Positive export interval in milliseconds. Zero keeps the 60,000 ms default.

See OpenTelemetry and SDK telemetry.

`aic::get_sdk_version`

inline std::string get_sdk_version();

Returns a copied core SDK version string. It wraps aic_get_sdk_version; a null C result would produce an empty string. No arguments.

`aic::get_compatible_model_version`

inline uint32_t get_compatible_model_version();

Returns the accepted model file format version, 7 for core 0.24.0. This is not the model product version. No arguments.

Example: pass configuration fields explicitly

Use a successfully created processor. ProcessorConfig stores values; initialize validates them.

#include "aic.hpp"

aic::ErrorCode configure(aic::Processor& processor) {
    aic::ProcessorConfig config(16000, 240);
    return processor.initialize(config.sample_rate, config.block_size,
                                config.variable_block_size);
}

SDK

API reference

Upgrades

LiveKit

AI tools

Historical migrations

`aic::Model`

`aic::Model::create_from_file`

`aic::Model::create_from_buffer`

`aic::Model::get_id`

`aic::Model::get_optimal_sample_rate`

`aic::Model::get_optimal_block_size`

`aic::ProcessorConfig`

`aic::ProcessorConfig::ProcessorConfig`

`aic::OtelConfig`

`aic::OtelConfig::OtelConfig`

`aic::get_sdk_version`

`aic::get_compatible_model_version`

Example: pass configuration fields explicitly

​aic::Model

​aic::Model::create_from_file

​aic::Model::create_from_buffer

​aic::Model::get_id

​aic::Model::get_optimal_sample_rate

​aic::Model::get_optimal_block_size

​aic::ProcessorConfig

​aic::ProcessorConfig::ProcessorConfig

​aic::OtelConfig

​aic::OtelConfig::OtelConfig

​aic::get_sdk_version

​aic::get_compatible_model_version

​Example: pass configuration fields explicitly

`aic::Model`

`aic::Model::create_from_file`

`aic::Model::create_from_buffer`

`aic::Model::get_id`

`aic::Model::get_optimal_sample_rate`

`aic::Model::get_optimal_block_size`

`aic::ProcessorConfig`

`aic::ProcessorConfig::ProcessorConfig`

`aic::OtelConfig`

`aic::OtelConfig::OtelConfig`

`aic::get_sdk_version`

`aic::get_compatible_model_version`

Example: pass configuration fields explicitly