C errors and types

C SDK 0.24.0, core 0.24.0. The declarations are in aic.h.

Pointer and error contract

Initialize handle output slots to NULL. Creation writes an output only on success; failure does not promise to clear the slot. Check the return code before using outputs. Do not pass an already owned handle as an output slot without first managing its lifetime. Non-null pointers must still point to valid storage of the declared type and size. Null checks do not make dangling, misaligned or undersized pointers safe. Pass only declared enum values. Output storage must be writable and unaliased for the call. Strings are null-terminated; paths and credentials require UTF-8. Audio length is a count of mono float32 samples, not bytes. Do not mutate, destroy or call a mutable processing object concurrently. Shared context parameter reads/writes and reset requests can run alongside processing while both handles remain valid. They do not make destruction concurrent-safe. Use one stateful object per stream. Create, initialize, update credentials and destroy outside the audio callback; run analysis off the callback too.

AicErrorCode

Every member below is prefixed with AIC_ERROR_CODE_ in C. Error-returning functions use this enum, with success equal to zero. A void destroy function and the direct metadata getters do not return it.

Constant	Value	Meaning and recovery
`AIC_ERROR_CODE_SUCCESS`	0	The operation succeeded. Output slots are usable.
`AIC_ERROR_CODE_NULL_POINTER`	1	A required pointer is NULL. Supply valid objects and writable output storage.
`AIC_ERROR_CODE_PARAMETER_OUT_OF_RANGE`	2	A parameter is outside its accepted range or is NaN. Check the parameter table.
`AIC_ERROR_CODE_NOT_INITIALIZED`	3	Initialize the processor, VAD or collector successfully before supplying audio.
`AIC_ERROR_CODE_AUDIO_CONFIG_UNSUPPORTED`	4	The initialization rate or block configuration is unsupported. Use 8,000–192,000 Hz and a positive block size.
`AIC_ERROR_CODE_AUDIO_CONFIG_MISMATCH`	5	The input length violates the fixed block size or variable maximum. Correct the buffer length.
`AIC_ERROR_CODE_PROCESSING_NOT_ALLOWED`	6	The session currently disallows processing. Check credentials, activation and session state; do not treat the output as enhanced audio.
`AIC_ERROR_CODE_INTERNAL_ERROR`	7	The operation could not complete internally. Preserve a safe diagnostic and contact support if a valid configuration reproduces it.
`AIC_ERROR_CODE_LICENSE_FORMAT_INVALID`	50	The credential cannot be parsed. Check the supplied key/token and string encoding without logging it.
`AIC_ERROR_CODE_LICENSE_VERSION_UNSUPPORTED`	51	This SDK does not support the credential version. Check SDK/account compatibility.
`AIC_ERROR_CODE_LICENSE_EXPIRED`	52	The credential has expired. Obtain a valid credential through the approved account flow.
`AIC_ERROR_CODE_TOKEN_UPDATE_UNSUPPORTED`	53	In-place token replacement requires JWT-form original and replacement credentials.
`AIC_ERROR_CODE_MODEL_INVALID`	100	The model data cannot be parsed. Download the complete compatible model again.
`AIC_ERROR_CODE_MODEL_VERSION_UNSUPPORTED`	101	The model file format does not match this SDK. Obtain the matching format.
`AIC_ERROR_CODE_FILE_PATH_INVALID`	102	The model path is not valid UTF-8.
`AIC_ERROR_CODE_FILE_SYSTEM_ERROR`	103	The model file cannot be opened or mapped. Check its path, permissions and integrity.
`AIC_ERROR_CODE_MODEL_DATA_UNALIGNED`	104	The model buffer does not meet 64-byte alignment.
`AIC_ERROR_CODE_MODEL_TYPE_UNSUPPORTED`	105	This object cannot run the selected model type. Match enhancement, VAD or analysis to its dedicated API.

Opaque handles

Do not allocate these structs yourself or read their layout. Each factory returns an owned handle; use the matching destroy function exactly once. A NULL argument to a destroy function is a no-op.

Type	Created by	Released by
`AicModel`	`aic_model_create_from_file`	`aic_model_destroy`
`AicProcessor`	`aic_processor_create`	`aic_processor_destroy`
`AicProcessorContext`	`aic_processor_context_create`	`aic_processor_context_destroy`
`AicVad`	`aic_vad_create`	`aic_vad_destroy`
`AicVadContext`	`aic_vad_context_create`	`aic_vad_context_destroy`
`AicCollector`	`aic_analyzer_pair_create`	`aic_collector_destroy`
`AicAnalyzer`	`aic_analyzer_pair_create`	`aic_analyzer_destroy`

AicModel can also be created from a buffer. Derived objects retain the model data, but the caller must keep any borrowed buffer or mapped file valid. Context handles retain shared controls and can outlive their source object; they do not keep processing audio after its destruction.

AicAnalysisResult

typedef struct AicAnalysisResult {
    float risk_score;
    float speaker_reverb;
    float speaker_loudness;
    float interfering_speech;
    float noise;
    float codec_degradation;
    float packet_loss;
} AicAnalysisResult;

Caller-owned value storage. aic_analyzer_analyze_buffered writes it on success. All fields are float; no field has a C default. Read the Tyto dimension interpretation before setting application thresholds. Scores are model estimates, not a measured word error rate or a guarantee about downstream behavior.

Field	Meaning
`risk_score`	Combined risk score from the model output and its weighting metadata. Lower values indicate less problematic audio.
`speaker_reverb`	Main-speaker distance/reverberation indicator.
`speaker_loudness`	Main-speaker level indicator; a larger value is not automatically worse.
`interfering_speech`	The maximum of background-speaker and background-media interference outputs.
`noise`	Background-noise indicator.
`codec_degradation`	Speech-codec artifact indicator.
`packet_loss`	Dropout/discontinuity indicator.

C API index · OpenTelemetry configuration · Troubleshooting

Example: initialize output handles

This helper leaves the output slot null when loading fails. It is an application convention; the SDK factory itself does not clear an existing slot.

#include "aic.h"

AicErrorCode load_model(const char *path, AicModel **output) {
    if (output == NULL) return AIC_ERROR_CODE_NULL_POINTER;
    *output = NULL;  /* Pass a fresh output slot, not an owned model. */
    return aic_model_create_from_file(output, path);
}

SDK

API reference

Upgrades

LiveKit

AI tools

Historical migrations

Pointer and error contract

AicErrorCode

Opaque handles

AicAnalysisResult

Example: initialize output handles

​Pointer and error contract

​AicErrorCode

​Opaque handles

​AicAnalysisResult

​Related

​Example: initialize output handles

Pointer and error contract

AicErrorCode

Opaque handles

AicAnalysisResult

Related

Example: initialize output handles