> ## 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++ audio analysis

> Collect mono audio and compute a checked Tyto analysis result.

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-AnalyzerPair" />

## `aic::AnalyzerPair`

Owns a `Collector` and `Analyzer` created together. The members are move-only, so the pair is move-only too. Its implicit destructor destroys both members. The wrapper supplies a static factory, not a public default factory. Use a [Tyto analysis model](/models/audio-insight/tyto).

<span id="aic-AnalyzerPair-collector" />

<span id="aic-AnalyzerPair-analyzer" />

| Public field | Type        | Ownership                                                                                |
| ------------ | ----------- | ---------------------------------------------------------------------------------------- |
| `collector`  | `Collector` | Owned value. Can be moved to its processing thread; arrange shutdown before destruction. |
| `analyzer`   | `Analyzer`  | Owned value. Can be moved to its processing thread; arrange shutdown before destruction. |

<span id="aic-AnalyzerPair-create" />

### `aic::AnalyzerPair::create`

```cpp theme={null}
static Result<AnalyzerPair> create(const Model& model, const std::string& license_key);
```

Creates the pair from an analysis `model` and SDK key or supported bearer token in `license_key`. The analyzer retains model data. Check the result before taking the pair. Errors include `ModelTypeUnsupported`, license errors and `InternalError`. The collector still needs initialization. There is no `OtelConfig` argument: this creation path disables optional OTel export; SDK session requirements remain separate.

<span id="aic-Collector" />

## `aic::Collector`

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-Collector-destructor-Collector" />

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

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

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

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

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

<span id="aic-Collector-initialize" />

### `aic::Collector::initialize`

```cpp theme={null}
ErrorCode initialize(uint32_t sample_rate, size_t block_size, bool variable_block_size);
```

Sets the host rate (8,000–192,000 Hz), positive mono block size and fixed/variable mode. Fixed input must match the block size; variable input cannot exceed it. Returns `Success`, `AudioConfigUnsupported` or `NullPointer`. Failure leaves the collector uninitialized. Initializes buffers outside the callback; do not reinitialize concurrently with collection.

<span id="aic-Collector-buffer" />

### `aic::Collector::buffer`

```cpp theme={null}
ErrorCode buffer(const float* audio, size_t audio_len);
```

Collects `audio_len` mono float32 samples from `audio`, without modifying caller input. Returns `Success`, `NullPointer`, `NotInitialized` or `AudioConfigMismatch`. Collection updates the analysis window; it does not return scores. One thread may collect while another runs the paired analyzer. Serialize calls on the collector itself.

<span id="aic-Analyzer" />

## `aic::Analyzer`

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-Analyzer-destructor-Analyzer" />

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

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

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

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

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

<span id="aic-Analyzer-reset" />

### `aic::Analyzer::reset`

```cpp theme={null}
ErrorCode reset() const;
```

Requests a reset of the paired collection pipeline. The next collection call clears stream state; analysis while reset is pending uses an empty padded window. Returns `Success` or `NullPointer`. Coordinate boundaries between unrelated recordings; audio configuration remains in place.

<span id="aic-Analyzer-analyze_buffered" />

### `aic::Analyzer::analyze_buffered`

```cpp theme={null}
Result<AnalysisResult> analyze_buffered();
```

Analyzes the latest fixed-size feature snapshot. Early windows are silence-padded; repeated calls without new input can score the same window. On success, returns all seven fields. On failure, `error` identifies `ProcessingNotAllowed`, `InternalError` or `NullPointer` and `value` is zero-initialized; those zeros are not valid scores. Analyze off the audio thread and serialize analyzer calls. The paired collector may continue feeding on another thread.

<span id="aic-Analyzer-terminate_session" />

### `aic::Analyzer::terminate_session`

```cpp theme={null}
ErrorCode terminate_session();
```

Requests asynchronous session termination. Returns `Success` or `NullPointer`; no-op when no session exists. Does not destroy the pair or prove backend acknowledgment. Stop application analysis and destroy both objects when finished. On native targets, terminating the final active session may wait for the shared telemetry tasks to finish. Call it outside the audio callback.

<span id="aic-Analyzer-update_bearer_token" />

### `aic::Analyzer::update_bearer_token`

```cpp theme={null}
ErrorCode update_bearer_token(const std::string& token) const;
```

Uses `token.c_str()` to replace local JWT-form credentials. The original credential must also be JWT-form. Returns `Success`, `LicenseFormatInvalid`, other license errors or `TokenUpdateUnsupported` (and `NullPointer` for an invalid handle). Run on a control thread. Success is local replacement, not backend acknowledgment.

<span id="aic-AnalysisResult" />

## `aic::AnalysisResult`

A value struct returned inside `Result<AnalysisResult>`. Read it only after `ok()` succeeds. All seven fields are `float`. Default initialization does not initialize built-in fields; value initialization with `{}` zeros them. Neither form proves an analysis ran.

```cpp theme={null}
struct AnalysisResult {
    float risk_score;
    float speaker_reverb;
    float speaker_loudness;
    float interfering_speech;
    float noise;
    float codec_degradation;
    float packet_loss;
};
```

<span id="aic-AnalysisResult-risk_score" />

<span id="aic-AnalysisResult-speaker_reverb" />

<span id="aic-AnalysisResult-speaker_loudness" />

<span id="aic-AnalysisResult-interfering_speech" />

<span id="aic-AnalysisResult-noise" />

<span id="aic-AnalysisResult-codec_degradation" />

<span id="aic-AnalysisResult-packet_loss" />

| Field                | Meaning                                                                                       |
| -------------------- | --------------------------------------------------------------------------------------------- |
| `risk_score`         | Combined model risk score weighted by model metadata. Lower indicates less problematic audio. |
| `speaker_reverb`     | Main-speaker distance/reverberation indicator.                                                |
| `speaker_loudness`   | Main-speaker level indicator; a higher value is not automatically worse.                      |
| `interfering_speech` | Maximum of the background-speaker and background-media interference outputs.                  |
| `noise`              | Background-noise indicator.                                                                   |
| `codec_degradation`  | Speech-codec artifact indicator.                                                              |
| `packet_loss`        | Dropout/discontinuity indicator.                                                              |

Read [Tyto dimensions](/models/audio-insight/tyto#tyto-dimensions) before choosing thresholds. Model scores are estimates, not a measured word error rate.

[C++ API index](/reference/sdk/api/cpp/index) · [Released analysis example](https://github.com/ai-coustics/aic-sdk-cpp/blob/e2703b8b54457e1002e1bf84d4e8c841de7e0bca/example/analyzer.cpp)

## Example: check before reading a score

Run this helper off the audio thread with an analyzer whose paired collector has been initialized and fed.

```cpp theme={null}
#include "aic.hpp"

aic::ErrorCode read_risk(aic::Analyzer& analyzer, float& risk) {
    auto result = analyzer.analyze_buffered();
    if (!result.ok()) return result.error;
    risk = result.value.risk_score;
    return aic::ErrorCode::Success;
}
```