Anira

Anira provides several key components to integrate real-time audio processing with machine learning models:

• anira::InferenceHandler: The primary interface for interacting with the library. It manages audio processing and inference for the real-time thread, offloading the actual inference to a thread pool and updating real-time thread buffers with the processed audio.
• anira::InferenceConfig: A configuration structure used to define model specifics (e.g., input/output shape, maximum inference time). This must be provided when constructing an InferenceHandler.
• anira::PrePostProcessor: A class used to define processing steps that occur before and after inference. You can use the default implementation or inherit from this class to implement custom logic.
• anira::HostConfig: A structure used to define host-level settings, specifically buffer size and sample rate.
• anira::ContextConfig (Optional): A configuration structure that defines global behavior across all Anira instances. This includes thread pool settings (number of threads and anira::WaitStrategy) and the global anira::LogLevel for Anira and its backends.

anira is a C++ library for real-time audio applications that integrate neural network inference. It provides a high-performance, real-time safe execution environment designed for deterministic runtimes.

Core Architecture:

• Unified Interface: Uses the anira::InferenceHandler class to provide a single interface for multiple industry-standard engines, including LibTorch, ONNXRuntime, and TensorFlow Lite.
• Real-time Safety: Inference is executed outside the audio thread using a static thread pool. This prevents inference execution from blocking the audio thread, ensuring the application remains responsive and deterministic.
• Parallelism: Leverages multiple CPU cores for efficient parallel inference.
• Latency Management: Automatically calculates minimum required latency based on the anira::InferenceConfig struct. If processing exceeds the latency threshold, anira compensates for missing frames to maintain synchronized audio processing.

When creating ModelData, you can provide either an ArrayBuffer (binary) or a URL string. If you provide a URL, your custom backend is responsible for fetching and loading the model.

You can check the format using modelData.isBinary():

• If isBinary() is true: Use modelData.getDataPtr() and modelData.getSize() to access the data in WASM memory.
• If isBinary() is false: The data is a URL string. You must decode it from WASM memory and then fetch the actual model bytes.

if (modelData.isBinary()) {
  const ptr = modelData.getDataPtr()
  const size = modelData.getSize()
  modelBytes = new Uint8Array(wasm.HEAPU32.buffer, ptr, size).slice()
} else {
  const pathBytes = new Uint8Array(
    wasm.HEAPU32.buffer,
    modelData.getDataPtr(),
    modelData.getSize()
  ).slice()
  const modelUrl = new TextDecoder().decode(pathBytes)
  modelBytes = new Uint8Array(await (await fetch(modelUrl)).arrayBuffer())
}

The Anira v3 C ABI uses the ANIRA_API macro to manage symbol visibility and linking. This ensures that only intended functions are exported when building the library and that consumers can correctly import them.

Visibility and Exporting

• On Linux/Unix (GCC/Clang): Symbols are exported using __attribute__((visibility("default"))). A version script (e.g., tanh_set_export_allowlist) is used to restrict exports to the anira_* namespace.
• On Windows (PE/COFF): The macro uses __declspec(dllexport) when building the library and __declspec(dllimport) when being consumed by a client. dllexport acts as the allowlist for exported symbols.
• Internal/Embedding: When used within an embedding plugin, ANIRA_API may be defined as empty to keep symbols hidden.

Linking Behavior

• Static Consumers: Consumers link against the exported symbols defined by the ANIRA_API macro.
• Build Interface: The project uses $<BUILD_INTERFACE> in CMake to manage how objects are absorbed and linked during the build process.

/* Typical macro expansion logic for ANIRA_API */
#if defined(ANIRA_BUILDING)
  define ANIRA_API __attribute__((visibility("default"))) 
  /* or __declspec(dllexport) on Windows */
#else
  define ANIRA_API __attribute__((visibility("default"))) 
  /* or __declspec(dllimport) on Windows */
#endif

Anira v3 categorizes C ABI data into three tiers to balance performance, stability, and extensibility:

1. Tier-1 RT PODs: Fixed-layout, versioned by ABI major only. These are used for high-performance runtime operations (e.g., anira_tensor, anira_sync_token, anira_error). They are designed for lock-free FIFOs or value-initialization and do not support size changes within a major version.
2. Config Objects: Opaque handles managed via scalar setters and getters (e.g., anira_machine_config, anira_model_config). The internal layout is hidden from the ABI, making this the safest model for growth.
3. Tier-2 Descriptors: Handed to setters once or filled by enumerators (e.g., anira_log_desc, anira_backend_desc). These use a uint32_t struct_size field at the start to allow tail growth. The library reads/fills only up to the minimum of the provided struct_size and the library's internal size.