aic_sdk/

lib.rs

//! Rust bindings for the ai-coustics SDK.
//!
//! The SDK requires a license key. Generate one at
//! [developers.ai-coustics.com](https://developers.ai-coustics.com).
//!
//! # Installation
//!
//! ```bash
//! cargo add aic-sdk --features download-lib
//! ```
//!
//! `download-lib` fetches the matching native library during the build. See [`docs::linking`] for
//! the alternatives and for how the library is found at run time.
//!
//! # Quick start
//!
//! ```rust,no_run
//! use aic_sdk::{include_model, ProcessorConfig, Model, Processor};
//!
//! // Embed model at compile time (or use Model::from_file to load at runtime)
//! static MODEL: &[u8] = include_model!("path/to/model.aicmodel");
//!
//! fn main() -> Result<(), Box<dyn std::error::Error>> {
//!     // Get your license key from the environment variable
//!     let license_key = std::env::var("AIC_SDK_LICENSE")?;
//!
//!     // Load the embedded model (or download manually at https://artifacts.ai-coustics.io/)
//!     let model = Model::from_buffer(MODEL)?;
//!
//!     // Get optimal configuration based on the selected model
//!     let config = ProcessorConfig::optimal(&model);
//!
//!     // Create a processor and initialize it
//!     let mut processor = Processor::new(&model, &license_key)?.with_config(&config)?;
//!
//!     // Process mono audio
//!     let mut audio_block = vec![0.0f32; config.block_size];
//!     processor.process(&mut audio_block)?;
//!
//!     Ok(())
//! }
//! ```
//!
//! # Where to go next
//!
//! [`docs::guide`] walks through the API, [`docs::examples`] has complete programs, and
//! [`docs::linking`] covers how the native library is linked and found.
//!
//! Models and their IDs are listed at
//! [artifacts.ai-coustics.io](https://artifacts.ai-coustics.io); the product documentation lives at
//! [docs.ai-coustics.com](https://docs.ai-coustics.com).
//!
//! # License
//!
//! This Rust wrapper is distributed under the Apache 2.0 license.
//! The core C SDK is distributed under the proprietary AIC-SDK license.
//!
//! `NOTICE.txt` in this crate lists the third-party software distributed with the SDK.
#![cfg_attr(docsrs, feature(doc_cfg))]

use aic_sdk_sys::{aic_get_compatible_model_version, aic_get_sdk_version, aic_set_sdk_wrapper_id};
use std::ffi::CStr;

#[cfg(feature = "runtime-linking")]
use std::path::Path;

// `test_support` is shared verbatim with the integration tests, which reach the SDK as `aic_sdk`;
// the alias lets the same file resolve inside this crate too.
#[cfg(test)]
extern crate self as aic_sdk;

pub mod docs;

mod analyzer;
mod energy_vad;
mod error;
mod file_analyzer;
mod model;
mod processor;
#[cfg(feature = "async")]
#[cfg_attr(docsrs, doc(cfg(feature = "async")))]
mod processor_async;
#[cfg(test)]
mod test_support;
mod vad;
#[cfg(feature = "async")]
#[cfg_attr(docsrs, doc(cfg(feature = "async")))]
mod vad_async;

pub use analyzer::*;
pub use energy_vad::*;
pub use error::*;
pub use file_analyzer::*;
pub use model::*;
pub use processor::*;
#[cfg(feature = "async")]
#[cfg_attr(docsrs, doc(cfg(feature = "async")))]
pub use processor_async::*;
pub use vad::*;
#[cfg(feature = "async")]
#[cfg_attr(docsrs, doc(cfg(feature = "async")))]
pub use vad_async::*;

#[cfg(feature = "runtime-linking")]
#[cfg_attr(docsrs, doc(cfg(feature = "runtime-linking")))]
pub use aic_sdk_sys::DynamicLoadingError;

/// Loads the AIC dynamic library from `path` when the `runtime-linking` feature is enabled.
///
/// This is optional. With `runtime-linking`, the library is loaded automatically on first use
/// from the platform default name (`libaic.so` / `libaic.dylib` / `aic.dll`) via the OS loader
/// search path. Call this only to pick a specific file, and do so before the first SDK call.
///
/// # Safety
///
/// `path` must point to an AIC dynamic library that is ABI-compatible with this crate's bundled
/// `aic.h` header. Loading an incompatible library can cause undefined behavior when SDK functions
/// are called.
#[cfg(feature = "runtime-linking")]
#[cfg_attr(docsrs, doc(cfg(feature = "runtime-linking")))]
pub unsafe fn load_library<P: AsRef<Path>>(path: P) -> Result<(), DynamicLoadingError> {
    unsafe { aic_sdk_sys::load_library(path) }
}

/// Returns whether an AIC dynamic library has already been loaded.
#[cfg(feature = "runtime-linking")]
#[cfg_attr(docsrs, doc(cfg(feature = "runtime-linking")))]
pub fn is_library_loaded() -> bool {
    aic_sdk_sys::is_library_loaded()
}

/// Returns the version of the SDK.
///
/// # Note
/// This is not necessarily the same as this crate's version.
///
/// # Returns
///
/// Returns the SDK version string, or `"unknown"` if it cannot be decoded.
///
/// # Example
///
/// ```rust
/// let version = aic_sdk::get_sdk_version();
/// println!("ai-coustics SDK version: {version}");
/// ```
pub fn get_sdk_version() -> &'static str {
    // SAFETY:
    // - FFI call returns a pointer to a static C string owned by the SDK.
    // - The pointer can never be null, so no check is necessary.
    // - This function can be called from any thread.
    let version_ptr = unsafe { aic_get_sdk_version() };

    // SAFETY:
    // - SDK returns a null-terminated static string.
    unsafe { CStr::from_ptr(version_ptr).to_str().unwrap_or("unknown") }
}

/// Returns the model version compatible with the SDK.
pub fn get_compatible_model_version() -> u32 {
    // SAFETY:
    // - FFI call takes no arguments and returns a plain integer.
    // - This function can be called from any thread.
    unsafe { aic_get_compatible_model_version() }
}

/// This function is only used to identify SDKs by ai-coustics and should not be called by users of this crate.
///
/// # Safety
///
/// Callers must use the wrapper ID assigned to them by ai-coustics.
pub unsafe fn set_sdk_id(id: u32) {
    // SAFETY:
    // - This FFI call has no safety requirements.
    // - This function can be called from any thread.
    unsafe { aic_set_sdk_wrapper_id(id) }
}