> ## 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 errors and types

> Look up public error codes, pointer ownership and every analysis field.

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

<span id="pointer-contract" />

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

<span id="AicErrorCode" />

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

<span id="AIC_ERROR_CODE_SUCCESS" />

<span id="AIC_ERROR_CODE_NULL_POINTER" />

<span id="AIC_ERROR_CODE_PARAMETER_OUT_OF_RANGE" />

<span id="AIC_ERROR_CODE_NOT_INITIALIZED" />

<span id="AIC_ERROR_CODE_AUDIO_CONFIG_UNSUPPORTED" />

<span id="AIC_ERROR_CODE_AUDIO_CONFIG_MISMATCH" />

<span id="AIC_ERROR_CODE_PROCESSING_NOT_ALLOWED" />

<span id="AIC_ERROR_CODE_INTERNAL_ERROR" />

<span id="AIC_ERROR_CODE_LICENSE_FORMAT_INVALID" />

<span id="AIC_ERROR_CODE_LICENSE_VERSION_UNSUPPORTED" />

<span id="AIC_ERROR_CODE_LICENSE_EXPIRED" />

<span id="AIC_ERROR_CODE_TOKEN_UPDATE_UNSUPPORTED" />

<span id="AIC_ERROR_CODE_MODEL_INVALID" />

<span id="AIC_ERROR_CODE_MODEL_VERSION_UNSUPPORTED" />

<span id="AIC_ERROR_CODE_FILE_PATH_INVALID" />

<span id="AIC_ERROR_CODE_FILE_SYSTEM_ERROR" />

<span id="AIC_ERROR_CODE_MODEL_DATA_UNALIGNED" />

<span id="AIC_ERROR_CODE_MODEL_TYPE_UNSUPPORTED" />

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

<span id="AicModel" />

<span id="AicProcessor" />

<span id="AicProcessorContext" />

<span id="AicVad" />

<span id="AicVadContext" />

<span id="AicCollector" />

<span id="AicAnalyzer" />

| Type                  | Created by                                                                                        | Released by                                                                                      |
| --------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `AicModel`            | [`aic_model_create_from_file`](/reference/sdk/api/c/models-and-config#aic_model_create_from_file) | [`aic_model_destroy`](/reference/sdk/api/c/models-and-config#aic_model_destroy)                  |
| `AicProcessor`        | [`aic_processor_create`](/reference/sdk/api/c/processing#aic_processor_create)                    | [`aic_processor_destroy`](/reference/sdk/api/c/processing#aic_processor_destroy)                 |
| `AicProcessorContext` | [`aic_processor_context_create`](/reference/sdk/api/c/processing#aic_processor_context_create)    | [`aic_processor_context_destroy`](/reference/sdk/api/c/processing#aic_processor_context_destroy) |
| `AicVad`              | [`aic_vad_create`](/reference/sdk/api/c/vad#aic_vad_create)                                       | [`aic_vad_destroy`](/reference/sdk/api/c/vad#aic_vad_destroy)                                    |
| `AicVadContext`       | [`aic_vad_context_create`](/reference/sdk/api/c/vad#aic_vad_context_create)                       | [`aic_vad_context_destroy`](/reference/sdk/api/c/vad#aic_vad_context_destroy)                    |
| `AicCollector`        | [`aic_analyzer_pair_create`](/reference/sdk/api/c/analysis#aic_analyzer_pair_create)              | [`aic_collector_destroy`](/reference/sdk/api/c/analysis#aic_collector_destroy)                   |
| `AicAnalyzer`         | [`aic_analyzer_pair_create`](/reference/sdk/api/c/analysis#aic_analyzer_pair_create)              | [`aic_analyzer_destroy`](/reference/sdk/api/c/analysis#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.

<span id="AicAnalysisResult" />

## AicAnalysisResult

```c theme={null}
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](/models/audio-insight/tyto#tyto-dimensions) before setting application thresholds. Scores are model estimates, not a measured word error rate or a guarantee about downstream behavior.

<span id="AicAnalysisResult.risk_score" />

<span id="AicAnalysisResult.speaker_reverb" />

<span id="AicAnalysisResult.speaker_loudness" />

<span id="AicAnalysisResult.interfering_speech" />

<span id="AicAnalysisResult.noise" />

<span id="AicAnalysisResult.codec_degradation" />

<span id="AicAnalysisResult.packet_loss" />

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

## Related

[C API index](/reference/sdk/api/c/index) · [OpenTelemetry configuration](/reference/sdk/api/c/models-and-config#AicOtelConfig) · [Troubleshooting](/production/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.

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