C++ audio analysis

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

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.

`aic::AnalyzerPair::create`

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.

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

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.

`aic::Collector::initialize`

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.

`aic::Collector::buffer`

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.

`aic::Analyzer`

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.

`aic::Analyzer::reset`

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.

`aic::Analyzer::analyze_buffered`

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.

`aic::Analyzer::terminate_session`

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.

`aic::Analyzer::update_bearer_token`

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.

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

struct AnalysisResult {
    float risk_score;
    float speaker_reverb;
    float speaker_loudness;
    float interfering_speech;
    float noise;
    float codec_degradation;
    float 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 before choosing thresholds. Model scores are estimates, not a measured word error rate. C++ API index · Released analysis example

Example: check before reading a score

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

#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;
}

SDK

API reference

Upgrades

LiveKit

AI tools

Historical migrations

`aic::AnalyzerPair`

`aic::AnalyzerPair::create`

`aic::Collector`

`aic::Collector::initialize`

`aic::Collector::buffer`

`aic::Analyzer`

`aic::Analyzer::reset`

`aic::Analyzer::analyze_buffered`

`aic::Analyzer::terminate_session`

`aic::Analyzer::update_bearer_token`

`aic::AnalysisResult`

Example: check before reading a score

​aic::AnalyzerPair

​aic::AnalyzerPair::create

​aic::Collector

​aic::Collector::initialize

​aic::Collector::buffer

​aic::Analyzer

​aic::Analyzer::reset

​aic::Analyzer::analyze_buffered

​aic::Analyzer::terminate_session

​aic::Analyzer::update_bearer_token

​aic::AnalysisResult

​Example: check before reading a score

`aic::AnalyzerPair`

`aic::AnalyzerPair::create`

`aic::Collector`

`aic::Collector::initialize`

`aic::Collector::buffer`

`aic::Analyzer`

`aic::Analyzer::reset`

`aic::Analyzer::analyze_buffered`

`aic::Analyzer::terminate_session`

`aic::Analyzer::update_bearer_token`

`aic::AnalysisResult`

Example: check before reading a score