> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ai-coustics.com/llms.txt
> Use this file to discover all available pages before exploring further.

# C++ models and configuration

> Load model data and inspect audio metadata and configuration values.

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](/reference/sdk/language-bindings/cpp).

All names below are in namespace `aic`. Check [Result and error handling](/reference/sdk/api/cpp/results-and-errors) before extracting a factory result. Ordinary C++ allocation or string operations can still throw; SDK status failures use the declared return values.

<span id="aic-Model" />

## `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.

<span id="aic-Model-destructor-Model" />

<span id="aic-Model-Model-move" />

<span id="aic-Model-operatorassign-move" />

<span id="aic-Model-Model-copy" />

<span id="aic-Model-operatorassign-copy" />

| 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.

<span id="aic-Model-create_from_file" />

### `aic::Model::create_from_file`

```cpp theme={null}
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.

<span id="aic-Model-create_from_buffer" />

### `aic::Model::create_from_buffer`

```cpp theme={null}
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.

<span id="aic-Model-get_id" />

### `aic::Model::get_id`

```cpp theme={null}
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.

<span id="aic-Model-get_optimal_sample_rate" />

### `aic::Model::get_optimal_sample_rate`

```cpp theme={null}
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.

<span id="aic-Model-get_optimal_block_size" />

### `aic::Model::get_optimal_block_size`

```cpp theme={null}
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.

<span id="aic-ProcessorConfig" />

## `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.

<span id="aic-ProcessorConfig-ProcessorConfig" />

### `aic::ProcessorConfig::ProcessorConfig`

```cpp theme={null}
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.

<span id="aic-ProcessorConfig-sample_rate" />

<span id="aic-ProcessorConfig-block_size" />

<span id="aic-ProcessorConfig-variable_block_size" />

| 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. |

<span id="aic-OtelConfig" />

## `aic::OtelConfig`

<span id="aic-OtelConfig-OtelConfig" />

### `aic::OtelConfig::OtelConfig`

```cpp theme={null}
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.

<span id="aic-OtelConfig-enable" />

<span id="aic-OtelConfig-session_id" />

<span id="aic-OtelConfig-export_interval_ms" />

| 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](/models/get-started/opentelemetry) and [SDK telemetry](/reference/concepts/sdk-telemetry).

<span id="aic-get_sdk_version" />

### `aic::get_sdk_version`

```cpp theme={null}
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.

<span id="aic-get_compatible_model_version" />

### `aic::get_compatible_model_version`

```cpp theme={null}
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.

```cpp theme={null}
#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);
}
```