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

# Rust errors and features

> Cargo features, runtime loading, complete error variants and trait contracts for aic-sdk 0.24.0.

**Crate:** `aic-sdk = "=0.24.0"`. **Core SDK:** `0.24.0`. The minimum Rust version is 1.88, using edition 2024. Source: the published [aic-sdk](https://docs.rs/crate/aic-sdk/0.24.0/source/) and [aic-sdk-sys](https://docs.rs/crate/aic-sdk-sys/0.24.0/source/) crates.

## Cargo features

No features are enabled by default. Static native linking is the default strategy, but a native library must still be supplied. Cargo features are additive across dependencies.

<a id="rust-feature-async" />

<a id="rust-feature-download-model" />

<a id="rust-feature-download-lib" />

<a id="rust-feature-dynamic-linking" />

<a id="rust-feature-runtime-linking" />

| Feature           | Available API and build behavior                                                                                                                                  |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `async`           | Exposes `ProcessorAsync` and `VadAsync`, using a shared Rayon worker pool and per-instance async mutex                                                            |
| `download-model`  | Adds `Model::download`; otherwise this associated function is absent                                                                                              |
| `download-lib`    | Permits the build script to download the matching native library when `AIC_LIB_PATH` is absent and build-time linking is selected                                 |
| `dynamic-linking` | Uses a shared library with build-time linking; deploy the runtime library as well as the executable                                                               |
| `runtime-linking` | Resolves the shared library at runtime; exposes `load_library`, `is_library_loaded` and `DynamicLoadingError`, and skips the native build-time link/download step |

If both linking features are enabled, runtime linking wins and the build emits a warning. Prefer selecting one explicitly. `AIC_LIB_PATH` identifies the SDK library directory for static/dynamic build-time linking; it is not the runtime `load_library` file path. With no download feature, build-time linking requires a local library. See the [released linking guide](https://docs.rs/aic-sdk/0.24.0/aic_sdk/docs/linking/index.html) for platform deployment details.

For runtime loading and async processing, a minimal dependency declaration is:

```toml theme={null}
[dependencies]
aic-sdk = { version = "=0.24.0", features = ["runtime-linking", "async"] }
```

<a id="rust-aic_sdk-load_library" />

## load\_library

**Requires feature:** `runtime-linking`.

```rust theme={null}
pub unsafe fn load_library<P: AsRef<std::path::Path>>(
    path: P,
) -> Result<(), DynamicLoadingError>
```

Explicitly loads a native shared library before the first SDK operation. **Safety:** the file must be trusted and ABI-compatible with the bundled 0.24.0 header. Loading an incompatible library can cause undefined behavior. Checking a filename or a version string after loading does not establish ABI compatibility.

The loaded library remains for the process lifetime. It cannot be safely replaced. A subsequent valid load returns `AlreadyLoaded`; the implementation attempts opening and resolving the supplied library before storing it, so an invalid subsequent path can return an open/symbol error first.

If you omit this call, the first SDK operation loads the platform default filename through the OS loader search path (`libaic.so`, `libaic.dylib` or `aic.dll`). Automatic loading failure panics. Explicit loading lets you handle `DynamicLoadingError` before SDK use.

<a id="rust-aic_sdk-is_library_loaded" />

## is\_library\_loaded

**Requires feature:** `runtime-linking`.

```rust theme={null}
pub fn is_library_loaded() -> bool
```

Reports whether this process has installed the SDK dynamic library. It does not trigger loading or prove SDK authorization.

<a id="rust-aic_sdk-DynamicLoadingError" />

## DynamicLoadingError

**Requires feature:** `runtime-linking`. Reexported from `aic_sdk_sys`.

```rust theme={null}
pub enum DynamicLoadingError {
    AlreadyLoaded,
    OpenLibrary {
        path: std::path::PathBuf,
        source: libloading::Error,
    },
    LoadSymbol {
        symbol: &'static str,
        source: libloading::Error,
    },
}
```

<a id="rust-aic_sdk-DynamicLoadingError-AlreadyLoaded" />

<a id="rust-aic_sdk-DynamicLoadingError-OpenLibrary" />

<a id="rust-aic_sdk-DynamicLoadingError-LoadSymbol" />

| Variant                         | Meaning and recovery                                                                           |
| ------------------------------- | ---------------------------------------------------------------------------------------------- |
| `AlreadyLoaded`                 | A library was already installed; use the existing library or restart with the intended build   |
| `OpenLibrary { path, source }`  | The loader could not open the file; check the exact path, architecture and dependent libraries |
| `LoadSymbol { symbol, source }` | A required symbol is missing; supply the matching complete native SDK                          |

<a id="rust-aic_sdk-DynamicLoadingError-OpenLibrary-path" />

<a id="rust-aic_sdk-DynamicLoadingError-OpenLibrary-source" />

<a id="rust-aic_sdk-DynamicLoadingError-LoadSymbol-symbol" />

<a id="rust-aic_sdk-DynamicLoadingError-LoadSymbol-source" />

All named variant fields are public pattern-match payloads with the types shown above. `path` identifies the attempted file and `symbol` the missing native function. Both `source` fields preserve the platform loader error. The enum implements `Debug`, `Display` and `std::error::Error`; `Error::source()` returns the underlying loader error for the two payload variants and `None` for `AlreadyLoaded`. It is not `Clone` or `Eq`.

<a id="rust-aic_sdk-AicError" />

## AicError

```rust theme={null}
pub enum AicError {
    ParameterOutOfRange,
    NotInitialized,
    AudioConfigUnsupported,
    AudioConfigMismatch,
    ProcessingNotAllowed,
    Internal,
    LicenseFormatInvalid,
    LicenseVersionUnsupported,
    LicenseExpired,
    TokenUpdateUnsupported,
    ModelInvalid,
    ModelVersionUnsupported,
    ModelTypeUnsupported,
    FilePathInvalid,
    FileSystemError,
    ModelDataUnaligned,
    ModelDownload(String),
    Unknown(aic_sdk_sys::AicErrorCode::Type),
}
```

Returned by fallible wrapper operations. Implements `Debug`, `Clone`, `PartialEq`, `Eq`, `Display` and `std::error::Error`. Display provides diagnostic text; match variants rather than parsing those strings. `ModelDownload` carries text rather than a nested error source.

<a id="rust-aic_sdk-AicError-ParameterOutOfRange" />

<a id="rust-aic_sdk-AicError-NotInitialized" />

<a id="rust-aic_sdk-AicError-AudioConfigUnsupported" />

<a id="rust-aic_sdk-AicError-AudioConfigMismatch" />

<a id="rust-aic_sdk-AicError-ProcessingNotAllowed" />

<a id="rust-aic_sdk-AicError-Internal" />

<a id="rust-aic_sdk-AicError-LicenseFormatInvalid" />

<a id="rust-aic_sdk-AicError-LicenseVersionUnsupported" />

<a id="rust-aic_sdk-AicError-LicenseExpired" />

<a id="rust-aic_sdk-AicError-TokenUpdateUnsupported" />

<a id="rust-aic_sdk-AicError-ModelInvalid" />

<a id="rust-aic_sdk-AicError-ModelVersionUnsupported" />

<a id="rust-aic_sdk-AicError-ModelTypeUnsupported" />

<a id="rust-aic_sdk-AicError-FilePathInvalid" />

<a id="rust-aic_sdk-AicError-FileSystemError" />

<a id="rust-aic_sdk-AicError-ModelDataUnaligned" />

<a id="rust-aic_sdk-AicError-ModelDownload" />

<a id="rust-aic_sdk-AicError-Unknown" />

| Variant                       | Cause and recovery                                                                                                                   |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `ParameterOutOfRange`         | Parameter outside its bounds; use the documented ranges and read the current value                                                   |
| `NotInitialized`              | Processing/buffering before successful initialization; initialize the object first                                                   |
| `AudioConfigUnsupported`      | Invalid rate/block combination, or zero FileAnalyzer rate/step; start with the model's optimal configuration                         |
| `AudioConfigMismatch`         | Slice length violates the initialized block contract; split or buffer samples appropriately                                          |
| `ProcessingNotAllowed`        | Authorization/reporting failed or a termination signal was handled; check credentials/network and apply your explicit audio fallback |
| `Internal`                    | Native internal failure, including a NUL-containing telemetry session ID; correct input or report a minimal reproduction             |
| `LicenseFormatInvalid`        | Malformed credential or embedded NUL; verify the exact SDK key/JWT without logging it                                                |
| `LicenseVersionUnsupported`   | Unsupported credential format; use a compatible SDK and credential                                                                   |
| `LicenseExpired`              | Credential expired; renew it and rotate JWTs before expiry when supported                                                            |
| `TokenUpdateUnsupported`      | Original or replacement credential is not a JWT; start with JWT credentials when rotation is required                                |
| `ModelInvalid`                | Corrupted/invalid model data; obtain a verified model file                                                                           |
| `ModelVersionUnsupported`     | Model file format differs from the core SDK; download compatible data                                                                |
| `ModelTypeUnsupported`        | Wrong model family for processor, VAD or analyzer; select a matching model                                                           |
| `FilePathInvalid`             | Native path invalid; validate paths before loading. Embedded NUL in `Model::from_file` instead panics in this wrapper release        |
| `FileSystemError`             | Model file cannot be read; check existence, type and permissions                                                                     |
| `ModelDataUnaligned`          | Buffer address is not 64-byte aligned; use `include_model!` or a correctly aligned allocation                                        |
| `ModelDownload(String)`       | Manifest/model/file operation failed; inspect the payload and check model ID, connectivity and destination permissions               |
| `Unknown(AicErrorCode::Type)` | Unrecognized native code; record the code and versions for investigation                                                             |

<a id="rust-aic_sdk-AicError-ModelDownload-0" />

<a id="rust-aic_sdk-AicError-Unknown-0" />

The tuple payloads are available through pattern matching. `ModelDownload` exists even with `download-model` disabled, although the public downloader is then absent. There is no `ParameterFixed` variant in this release.

## Panics and Result boundaries

`Result` covers ordinary native errors but is not a promise that no call can panic. Model/query/context functions assert native success. `Model::from_file` panics on an embedded NUL path. Worker initialization or unexpected worker channel loss can panic in async code. Runtime automatic loading can panic before the called SDK operation returns. Explicit loader handling and validated inputs keep these conditions distinct from routine processing errors.

<a id="rust-aic_sdk-traits" />

## Trait and conversion surface

| Types                                                                                                  | Explicit or derived traits                                                                     |
| ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------- |
| `Model<'a>`, `Processor<'a>`, `ProcessorContext`, `Vad<'a>`, `VadContext`, `Collector`, `Analyzer<'a>` | `Drop`, `Send`, `Sync`; native handles are released on drop                                    |
| `ProcessorAsync`, `VadAsync`                                                                           | `Send` and `Sync` through owned synchronized fields; use `Arc` rather than assuming `Clone`    |
| `FileAnalyzer<'model, 'a>`                                                                             | `Send`/`Sync` through its borrowed model and owned fields; field destruction releases the pair |
| `ProcessorConfig`, `OtelConfig`                                                                        | `Debug`, `Clone`, `PartialEq`, `Eq`, `Hash`; no `Default` or `Copy`                            |
| `ProcessorParameter`, `VadParameter`                                                                   | `Debug`, `Clone`, `Copy`, `PartialEq`, `Eq`, `Hash`                                            |
| `AnalysisResult`                                                                                       | `Debug`, `Clone`, `PartialEq`; no `Eq` because it contains floating-point scores               |
| `AicError`                                                                                             | `Debug`, `Clone`, `PartialEq`, `Eq`, `Display`, `Error`                                        |
| `DynamicLoadingError`                                                                                  | `Debug`, `Display`, `Error`, behind `runtime-linking`                                          |

<a id="rust-aic_sdk-ProcessorParameter-From" />

<a id="rust-aic_sdk-VadParameter-From" />

<a id="rust-aic_sdk-AnalysisResult-From" />

<a id="rust-aic_sdk-AicError-From" />

Explicit conversions are:

```rust theme={null}
impl From<ProcessorParameter> for aic_sdk_sys::AicProcessorParameter::Type
impl From<VadParameter> for aic_sdk_sys::AicVadParameter::Type
impl From<aic_sdk_sys::AicAnalysisResult> for AnalysisResult
impl From<aic_sdk_sys::AicErrorCode::Type> for AicError
```

Parameter conversions map the named variant to its C enum value. Result conversion copies all seven fields. Error conversion maps known failure codes and wraps other values in `Unknown`; the null-pointer error code panics as a wrapper invariant failure. Do not convert a native success code into an error: this conversion does not perform the success check used by fallible SDK methods. Naming the `aic_sdk_sys` types in application code requires that crate as a direct dependency; they are not root type reexports of `aic_sdk`.

Rustdoc also lists standard blanket traits and other compiler-derived implementations.

<a id="rust-aic_sdk-set_sdk_id" />

## Reserved integration hook: set\_sdk\_id

```rust theme={null}
pub unsafe fn set_sdk_id(id: u32)
```

This public export is reserved for ai-coustics wrapper integrations, not application setup. Callers must use an ID assigned by ai-coustics. Application constructors already identify the Rust wrapper; do not override it.

See the [symbol index](/reference/sdk/api/rust/index), [authentication](/models/get-started/authenticate-apps) and [troubleshooting](/production/troubleshooting).