Rust models and configuration

Crate: aic-sdk = "=0.24.0". Core SDK: 0.24.0. Signatures and behavior are based on the released crate source. For installation and a complete audio program, use the Rust guide. Signatures below are declarations. Use the root exports, for example use aic_sdk::{AicError, Model, OtelConfig, ProcessorConfig};. Path and PathBuf refer to std::path types.

Model

pub struct Model<'a> { /* private fields */ }

A native model handle. Choose a model matching the operation: enhancement for Processor, dedicated voice activity detection (VAD) for Vad and Tyto analysis for the analyzers. One model can supply several independent processing instances. File loading creates a Model<'static>. Buffer loading creates a Model<'a> borrowing its input bytes. The backing bytes must remain valid and immutable for all dependent processors, VADs and analyzers, even if you drop the original model handle. Native reference counting keeps model storage alive; it does not extend the Rust lifetime of borrowed bytes. A file-backed model’s file must not be modified or deleted while the model or dependent objects exist. Model implements Drop, Send and Sync. Dropping the handle releases its native reference. It does not implement Clone; share a reference or use Arc<Model<'static>> when appropriate.

Model::from_file

pub fn from_file<P: AsRef<Path>>(path: P) -> Result<Model<'static>, AicError>

Loads a model from path. This is blocking setup work. File and model failures return FileSystemError, ModelInvalid or ModelVersionUnsupported, as applicable. Pass a valid path without embedded NUL characters: this release uses CString::new(...).unwrap(), so a NUL-containing path can panic rather than return AicError.

Model::from_buffer

pub fn from_buffer(buffer: &'a [u8]) -> Result<Self, AicError>

Borrows model bytes without copying the backing buffer. The address must be aligned to 64 bytes; an ordinary Vec<u8> does not guarantee that alignment. Misalignment returns ModelDataUnaligned; invalid contents return model errors. The borrow is carried by the returned model and dependent native objects.

include_model!

include_model!(path_expression)

Embeds a model file using include_bytes! inside a 64-byte-aligned static allocation and evaluates to a reference to its bytes. The path follows include_bytes! resolution relative to the Rust source file. The file must exist at compile time; this macro does not download it. Its static storage can be used by async processing types. This declaration is a compile-time embedding pattern; replace the path with an existing compatible model file:

use aic_sdk::{include_model, AicError, Model};

static MODEL_BYTES: &[u8] = include_model!("path/to/model.aicmodel");

fn load_embedded() -> Result<Model<'static>, AicError> {
    Model::from_buffer(MODEL_BYTES)
}

Model::id

pub fn id(&self) -> &str

Returns the model ID borrowed from the native handle. Returns "unknown" if the native string is null or cannot be decoded as UTF-8. The borrowed string cannot outlive this model handle.

Model::optimal_sample_rate

pub fn optimal_sample_rate(&self) -> u32

Returns the model’s native sample rate in Hz. This query does not configure or validate an input stream.

Model::optimal_block_size

pub fn optimal_block_size(&self, sample_rate: u32) -> usize

Returns the preferred sample count per processing call at sample_rate. Use the stream’s actual rate. Initialization validates support for the rate and block combination. Metadata queries return values directly and assert native success; they do not return Result for internal native failures.

Model::download

Requires feature: download-model. Absent when that feature is disabled.

pub fn download<P: AsRef<Path>>(
    model_id: &str,
    download_dir: P,
) -> Result<std::path::PathBuf, AicError>

Resolves the model ID against a manifest using the core SDK’s compatible model file version, downloads compatible data and returns its path. The result remains relative when download_dir is relative. Creates missing destination directories. The downloader can reuse a fresh manifest in memory or in the download directory according to server cache lifetime. It revalidates stale entries, retries manifest resolution when needed and reuses a model file only when its SHA-256 matches. Replacement data is checked before installation. Failures return AicError::ModelDownload(String) with the underlying detail. This method blocks and has no async Rust counterpart in this release; provision models before processing.

ProcessorConfig

pub struct ProcessorConfig {
    pub sample_rate: u32,
    pub block_size: usize,
    pub variable_block_size: bool,
}

Construct with a struct literal or optimal. Configuration is copied into the processor, detector or collector at initialization; changing the value later does not reconfigure it. There is no Default implementation.

Field	Contract
`sample_rate: u32`	Actual input rate in Hz; native initialization accepts 8,000–192,000 Hz subject to the model/configuration
`block_size: usize`	Positive mono sample count per fixed call, or maximum call length with variable blocks
`variable_block_size: bool`	`false`: exactly `block_size` samples. `true`: calls up to `block_size`, with additional buffering delay

ProcessorConfig::optimal

pub fn optimal(model: &Model) -> Self

Uses the model native rate, its preferred block size at that rate and variable_block_size: false. Override fields before initialization when the input has a different rate.

ProcessorConfig::with_variable_block_size

pub fn with_variable_block_size(self, variable_block_size: bool) -> Self

Consumes the configuration, sets the flag and returns the updated configuration. Does not initialize an object.

OtelConfig

pub struct OtelConfig {
    pub enable: bool,
    pub session_id: Option<String>,
    pub export_interval_ms: u32,
}

Optional per-instance OpenTelemetry settings for processor and VAD constructors. Without an explicit configuration, native environment defaults apply. These settings control observability separately from mandatory authorization and usage reporting. See telemetry.

Field	Contract
`enable: bool`	Overrides the runtime environment’s enable setting
`session_id: Option<String>`	`None` requests an automatically generated ID; an embedded NUL causes `AicError::Internal` when constructing a processor or detector
`export_interval_ms: u32`	Positive values override the interval in milliseconds; zero uses the SDK default of 60,000 ms

There is no Default implementation. Configuration is copied at construction; subsequent changes do not affect existing sessions.

OtelConfig::disabled

pub fn disabled() -> Self

Returns { enable: false, session_id: None, export_interval_ms: 0 }.

OtelConfig::enabled

pub fn enabled() -> Self

Returns { enable: true, session_id: None, export_interval_ms: 0 }.

OtelConfig::with_session_id

pub fn with_session_id(session_id: impl Into<String>) -> Self

Returns enabled telemetry with the converted session ID and interval zero.

get_sdk_version

pub fn get_sdk_version() -> &'static str

Returns the loaded native SDK version, which is separate from the Cargo package version. Returns "unknown" for an undecodable native string. Under runtime-linking, this is an SDK call that can trigger automatic library loading.

get_compatible_model_version

pub fn get_compatible_model_version() -> u32

Returns the compatible model file format version. This is not the model ID or model release version.

Configuration example

This example needs no model or SDK key:

use aic_sdk::{OtelConfig, ProcessorConfig};

fn main() {
    let config = ProcessorConfig {
        sample_rate: 16_000,
        block_size: 160,
        variable_block_size: false,
    }.with_variable_block_size(true);
    assert!(config.variable_block_size);
    let telemetry = OtelConfig::disabled();
    assert!(!telemetry.enable);
}

See the symbol index and features, errors and traits.

SDK

API reference

Upgrades

LiveKit

AI tools

Historical migrations

Rust models and configuration

Model

Model::from_file

Model::from_buffer

include_model!

Model::id

Model::optimal_sample_rate

Model::optimal_block_size

Model::download

ProcessorConfig

ProcessorConfig::optimal

ProcessorConfig::with_variable_block_size

OtelConfig

OtelConfig::disabled

OtelConfig::enabled

OtelConfig::with_session_id

get_sdk_version

get_compatible_model_version

Configuration example

​Model

​Model::from_file

​Model::from_buffer

​include_model!

​Model::id

​Model::optimal_sample_rate

​Model::optimal_block_size

​Model::download

​ProcessorConfig

​ProcessorConfig::optimal

​ProcessorConfig::with_variable_block_size

​OtelConfig

​OtelConfig::disabled

​OtelConfig::enabled

​OtelConfig::with_session_id

​get_sdk_version

​get_compatible_model_version

​Configuration example

Model

Model::from_file

Model::from_buffer

include_model!

Model::id

Model::optimal_sample_rate

Model::optimal_block_size

Model::download

ProcessorConfig

ProcessorConfig::optimal

ProcessorConfig::with_variable_block_size

OtelConfig

OtelConfig::disabled

OtelConfig::enabled

OtelConfig::with_session_id

get_sdk_version

get_compatible_model_version

Configuration example