Getting Started#

From an installed anira to a model running in your audio callback.

Prerequisites#

  • A C++20 compiler for anira/anira.hpp and the examples (the C headers compile as C11 and C++17).

  • CMake 3.18 or later to build anira (3.25 for its presets).

  • A model in a format one of the engines reads:

    • ONNX Runtime: .onnx (and .ort);

    • LibTorch: TorchScript .pt, .pth or .ts;

    • LiteRT or TensorFlow Lite: .tflite;

    • ExecuTorch: .pte programs exported with torch.export.

Installation#

C++ Library#

Anira can be easily integrated into your CMake project. You can either add anira as a submodule, download the pre-built binaries from the releases page, or build from source.

Option 2: Use Pre-built Binaries#

Download pre-built binaries from the releases page.

In your CMakeLists.txt:

# Setup your project and target
project(your_project)
add_executable(your_target main.cpp ...)

# Add the path to the anira library as cmake prefix path and find the package
list(APPEND CMAKE_PREFIX_PATH "path/to/anira")
find_package(anira REQUIRED)

# Link your target to the anira library
target_link_libraries(your_target anira::anira)

# Only if your own code calls an engine: link its anira::<engine> target too
target_link_libraries(your_target anira::onnxruntime)

anira::anira carries anira’s headers but no engine header: the engines are linked privately. Inside anira’s build tree it also carries the USE_<ENGINE> definitions the bundled examples select on; the installed anira::anira does not, and code that needs to know which engines a build compiled in asks anira_enabled_engines (anira::enabled_engines()). A target that calls an engine itself links the matching engine target — anira::onnxruntime, anira::tflite, anira::litert, anira::libtorch or anira::executorch — which exists both in the build tree and in the installed package, carries the engine’s headers, and is the very file anira links, so the process never holds a second copy of the engine.

Option 3: Build from Source#

git clone https://github.com/anira-project/anira.git
cd anira
cmake . -B build -DCMAKE_BUILD_TYPE=Release -DANIRA_WITH_INSTALL=ON
cmake --build build --config Release --target anira
cmake --install build --prefix /path/to/install/directory

Or with the bundled presets (desktop-install-release / desktop-install-debug):

cmake --preset desktop-install-release
cmake --build --preset desktop-install-release
cmake --install build/desktop/Install/Release --prefix /path/to/install/directory

Without --prefix, the tree is installed to <build dir>/anira-<version>.

The Apache-2.0 core component of tanh-lib that backs anira’s buffers is built into the library and installs nothing of its own: find_package(anira) looks up Threads and the engines alone, so consumers only add the anira prefix to CMAKE_PREFIX_PATH.

C++ Build Options#

By default, LibTorch, ONNXRuntime, LiteRT and ExecuTorch are enabled. You can disable specific engines as needed:

  • LibTorch: -DANIRA_WITH_LIBTORCH=OFF

  • OnnxRuntime: -DANIRA_WITH_ONNXRUNTIME=OFF

  • LiteRT (LiteRt* C API): -DANIRA_WITH_LITERT=OFF — runs .tflite models through LiteRT’s native CompiledModel runtime. Enabled by default; it is the modern TensorFlow-Lite-family engine.

  • TensorFlow Lite (legacy TfLite* C API): -DANIRA_WITH_TFLITE=ON — the same runtime as LiteRT exposed through the older C API, so the two are mutually exclusive. To use it, disable LiteRT: -DANIRA_WITH_LITERT=OFF -DANIRA_WITH_TFLITE=ON.

  • ExecuTorch: -DANIRA_WITH_EXECUTORCH=OFF — runs .pte programs exported ahead-of-time with torch.export; PyTorch’s edge/mobile inference stack (CPU execution via XNNPACK). Enabled by default; static-only.

Platform / engine support#

anira builds on the targets below; the pre-built engines it downloads ship per target as shared and/or static. Engine linkage follows BUILD_SHARED_LIBS: a shared anira links shared engines, a static anira links static engines, and an engine that does not ship the required linkage is disabled with a warning:

Target

LibTorch

ONNXRuntime

LiteRT

TFLite (legacy)

ExecuTorch

macOS x86_64

shared

shared · static

shared · static

shared · static

static

macOS arm64

shared

shared · static

shared · static

shared · static

static

macOS universal

shared

shared · static

shared · static

shared · static

static

Linux x86_64

shared

shared · static

shared · static

shared · static

static

Linux aarch64

shared

shared · static

shared · static

shared · static

static

Windows x86_64

shared

shared · static

shared · static

shared · static

static

Windows arm64

shared

shared · static

shared · static

shared · static

static

WASM (Emscripten)

—

static

—

—

—

LibTorch is shared-only (disabled in a static anira build); ExecuTorch is static-only (disabled in a shared anira build). iOS and WebAssembly are static-only altogether (-DBUILD_SHARED_LIBS=OFF). LiteRT and TFLite are the same runtime via two C APIs and are mutually exclusive (LiteRT is the default). In a fully static anira build ExecuTorch cannot be combined with LiteRT or TFLite (each bundles its own copy of XNNPACK, whose symbols collide in one static image) — ExecuTorch is then auto-disabled; disable LiteRT/TFLite to build a static anira with ExecuTorch. On WebAssembly only ONNX Runtime is supported. Backends for Android and iOS are also published in the anira-project/backends release for cross-builds. — = not provided.

Pre-built engine binaries are downloaded at configure time from the anira-project/backends release pinned by ANIRA_BACKENDS_VERSION. Integrity is checked live: when GitHub is reachable, anira fetches each asset’s published SHA256 and re-downloads any engine whose archive changed upstream or downloaded incompletely (the download is verified against that hash). Nothing is pinned in-repo. The source is configurable (the linkage is not: it follows BUILD_SHARED_LIBS, see above):

  • Backends release tag: -DANIRA_BACKENDS_VERSION=v2.4.0 (the built-in default).

  • Offline / reproducible builds: -DANIRA_BACKENDS_SKIP_REMOTE_CHECK=ON skips the GitHub query and reuses whatever is already in modules/.

  • Bring your own engine (no fork): -DANIRA_<ENGINE>_ROOTDIR=/path/to/prebuilt (a tree with include/ + lib/), or a custom source via -DANIRA_<ENGINE>_URL=... -DANIRA_<ENGINE>_SHA256=....

Moreover, the following options are available:

  • Build the benchmark examples and their fixture (examples/benchmark/, not part of the library): -DANIRA_WITH_BENCHMARK=ON

  • Build example applications, plugins and populate example neural models: -DANIRA_WITH_EXAMPLES=ON

  • Build anira with tests: -DANIRA_WITH_TESTS=ON

  • Build anira with documentation: -DANIRA_WITH_DOCS=ON

  • Disable the logging system (compiles every anira log call out; anira otherwise logs through tanh-lib’s thl::Logger): -DANIRA_WITH_LOGGING=OFF

Anira Web (Web / JavaScript)#

Anira is available as the @anira-project/anira package for web applications: anira compiled to WebAssembly with a thin typed layer over its C ABI. anira starts the page’s threads from C on one shared memory (the context’s inference threads are Wasm Workers, the audio path a Wasm Audio Worklet node whose render callback is C), processors and inference engines are written in TypeScript without rebuilding the module, and the model and contract files of a native host load unchanged. The 3.x pre-release is on the next dist-tag:

npm install @anira-project/anira@next

See the Anira Web guides.

Building @anira-project/anira from source#

If you want to build the WASM module and JavaScript bindings yourself, you need to provide your own Emscripten SDK (4.0.23, the version CI pins) and TypeScript on the PATH (emcc --emit-tsd runs tsc). The CMake presets expect the EMSDK environment variable to be set to the root of your emsdk installation.

git clone https://github.com/anira-project/anira.git
cd anira

export EMSDK=/path/to/your/emsdk

# Configure and build the WASM module (release); wasm-abi adds the node ABI gates
cmake --preset wasm-release
cmake --build --preset wasm-release

# Build the JavaScript package
cd web
npm install
npm run build

For packaging it locally, use

npm pack

in the web folder, which will create a .tgz file that can be installed with npm or yarn.

Then install the package in your project:

npm install path/to/anira/web/anira-project-anira-x.x.x.tgz

A debug preset is also available via cmake --preset wasm-debug / cmake --build --preset wasm-debug.

The installed package#

An installed anira (cmake --install, or a release zip) carries the library and its public headers, and nothing of its private dependencies:

include/anira/anira.h            the C umbrella (every header of anira/abi/)
include/anira/anira_all.h        the C umbrella plus the platform companions
include/anira/anira_em.h         the WebAssembly companion (empty on every other target)
include/anira/anira.hpp          the C++20 face, header-only over the C entries
include/anira/compat/v2.hpp      the 2.x source-compatible face, header-only
include/anira/abi/*.h            the C ABI, one header per area; abi/draft/ the draft entries
lib/libanira.so.0 (libanira.0.dylib, bin/anira-0.dll + lib/anira-0.lib; static: lib/libanira.a, lib/anira.lib)
include/anira-engines/<engine>/  and the engine libraries, for code that calls an engine itself
lib/cmake/anira/                 the CMake package: find_package(anira) → anira::anira

The shared library is named after the ABI major (0 through the 3.0.0 pre-releases, 3 from v3.0.0 on), exports the anira_* C entries and nothing else, and carries tanh-lib’s core inside it; the queue and the JSON library are header-only and private. No C++ header of anira’s core is installed. The engines the build was made with are installed beside it: their libraries (the shared ones anira loads at run time, the static ones a static anira’s consumers link) and their headers, under include/anira-engines/<engine>/, which only the anira::<engine> target carries, for code that calls an engine itself; anira::anira reaches none of them. find_package(anira) looks up nothing but Threads and those engines.

Linking anira from C#

The C ABI is C11. A C project links anira::anira like a C++ one; with a static anira, which is C++ inside, the executable links through the C++ driver:

project(my_host LANGUAGES C CXX)
find_package(anira REQUIRED)
add_executable(my_host main.c)
target_link_libraries(my_host PRIVATE anira::anira)
set_target_properties(my_host PROPERTIES LINKER_LANGUAGE CXX)  # static anira only
#include <anira/anira.h>

int main(void) {
    anira_error err = ANIRA_ERROR_INIT;
    if (ANIRA_FAILED(anira_check_abi(ANIRA_ABI_VERSION))) { return 1; }  /* header == library */
    anira_context_config* config = NULL;
    anira_context* context = NULL;
    anira_context_config_create(&config, &err);
    if (ANIRA_FAILED(anira_context_create(config, &context, &err))) { return 1; }
    /* ... a model config, a pipeline, a handler, prepared with a Hard contract ... */
    anira_context_destroy(context);
    anira_context_config_destroy(config);
    return ANIRA_FAILED(anira_shutdown()) ? 1 : 0;
}

test/contracts/install/main_c.c is a complete one: a registered engine, a handler prepared on the Hard contract’s defaults, every plan’s figure, factor and verdict printed, and one block through anira_handler_process.

Basic Usage Example#

anira takes its configuration from two JSON files that travel with the model: the model file names the model’s exports per inference engine (paths relative to the file) and describes the tensors, the contract file says how it runs: the inference budget and the warm-up. By default the warm-up pass at prepare measures the budget on the machine; "budget": { "ms": 5.33 } pins it for a reproducible latency. The host blocks are patched in at prepare.

{
  "models": [ { "engine": "onnxruntime", "path": "model.onnx" } ],
  "inputs":  [ { "name": "audio_in",  "axes": [["time", 256], ["channel", 1], ["any", 1]] } ],
  "outputs": [ { "name": "audio_out", "axes": [["time", 256], ["any", 1]] } ]
}
{ "hard": { "budget": "measured", "warmup": "until_stable" } }

The basic usage of anira is as follows:

#include <anira/anira.hpp>

// The configuration: the model file next to your model, and the contract file
anira::ModelConfig model_config = anira::ModelConfig::from_file("path/to/model.json");
anira::ContractHandle contract = anira::ContractHandle::from_file("path/to/contract.json");

// The context (the inference thread pool) and the handler over the model's inference stage,
// on every engine of this build the model file names
anira::Context context{anira::ContextConfig{}};
anira::Pipeline pipeline;
pipeline.add_inference(model_config);
anira::InferenceHandler inference_handler(context, pipeline);

// Complete the contract with the host blocks; prepare allocates, warms the model up, measures
// it and returns the plans, one per engine the model runs on here
contract.hard_host_blocks(buffer_size, buffer_size, sample_rate);
const anira::PlanReport report = inference_handler.prepare(contract);

// Whether the running plan keeps up on this machine (hold a NOT_REALTIME one and ask the user)
const anira_plan_info row = report.plans()[inference_handler.get_plan()];
const bool realtime = static_cast<anira_rt_verdict>(row.rt_verdict) != ANIRA_RT_NOT_REALTIME;

// Optionally select another plan (the default engine's plan runs first, plan 0 without one) and
// get the latency
inference_handler.set_plan(0);
uint32_t latency_in_samples = inference_handler.get_latency();

// The audio block as a tensor over the host's channel pointers, built once at prepare
std::array<float*, 2> channels{};
anira::Tensor audio = anira::Tensor::from_host_planar<float>(
    std::span<float* const>(channels), std::array<int64_t, 2>{2, buffer_size});

// Real-time safe audio processing in process callback of your application
void process(float* const* audio_data, size_t num_samples) noexcept {
    channels = {audio_data[0], audio_data[1]};
    audio.shape[1] = static_cast<int64_t>(num_samples);
    inference_handler.process(audio, 0, audio, 0);
}
// audio_data now contains the processed audio samples

Choosing an engine#

Which engines a build carries depends on its options (anira::enabled_engines() lists them). prepare returns the plan report, one plan per model entry the build can run here, with what the warm-up measured and whether each plan keeps up (The plan report), and anira::InferenceHandler::set_plan() switches between them at run time, also while audio runs:

 1const anira::PlanReport report = inference_handler.prepare(contract);
 2
 3// The plan on ONNX Runtime; the other engines are ANIRA_ENGINE_LIBTORCH (PyTorch),
 4// ANIRA_ENGINE_LITERT (the default TensorFlow Lite family backend), ANIRA_ENGINE_TFLITE
 5// (the legacy TensorFlow Lite backend, -DANIRA_WITH_TFLITE=ON, mutually exclusive with
 6// LiteRT) and ANIRA_ENGINE_EXECUTORCH (.pte programs exported with torch.export)
 7if (auto plan = report.find({.backend = {.engine = ANIRA_ENGINE_ONNXRUNTIME}})) {
 8    inference_handler.set_plan(*plan);
 9}
10
11// A custom engine is added to the pipeline under its id (see "Custom Engines"), and its
12// plan is found by that id: report.find({.backend = {.engine = ANIRA_ENGINE_CUSTOM,
13// .engine_id = "com.example.engine"}})

Several tensors#

A model may take and produce several tensors: audio and a control vector in, processed audio and a confidence score out, or a hidden state it expects back on its next call. Each tensor of the model file has a role that says how it travels (Tensor specs): Streamed blocks of any size, Static whole values set and read between blocks, a State pair anira feeds back itself. A tensor is addressed by its slot, its position in its list (Slots); Static tensors runs audio with a control vector in and a confidence out.

Next Steps#