Getting Started#
From an installed anira to a model running in your audio callback.
Prerequisites#
A C++20 compiler for
anira/anira.hppand 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,.pthor.ts;LiteRT or TensorFlow Lite:
.tflite;ExecuTorch:
.pteprograms exported withtorch.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 1: Add as Git Submodule (Recommended)#
# Add anira repo as a submodule
git submodule add https://github.com/anira-project/anira.git modules/anira
In your CMakeLists.txt:
# Setup your project and target
project(your_project)
add_executable(your_target main.cpp ...)
# Add anira as a subdirectory
add_subdirectory(modules/anira)
# Link your target to the anira library
target_link_libraries(your_target anira::anira)
# Only if your own code calls an engine (e.g. includes onnxruntime_cxx_api.h): link
# its anira::<engine> target too — the same file anira uses, so the process holds
# one copy of the engine. anira itself never needs this line.
target_link_libraries(your_target anira::onnxruntime)
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=OFFOnnxRuntime:
-DANIRA_WITH_ONNXRUNTIME=OFFLiteRT (
LiteRt*C API):-DANIRA_WITH_LITERT=OFF— runs.tflitemodels 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.pteprograms exported ahead-of-time withtorch.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 |
shared |
shared · static |
shared · static |
shared · static |
static |
macOS |
shared |
shared · static |
shared · static |
shared · static |
static |
macOS |
shared |
shared · static |
shared · static |
shared · static |
static |
Linux |
shared |
shared · static |
shared · static |
shared · static |
static |
Linux |
shared |
shared · static |
shared · static |
shared · static |
static |
Windows |
shared |
shared · static |
shared · static |
shared · static |
static |
Windows |
shared |
shared · static |
shared · static |
shared · static |
static |
|
— |
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=ONskips the GitHub query and reuses whatever is already inmodules/.Bring your own engine (no fork):
-DANIRA_<ENGINE>_ROOTDIR=/path/to/prebuilt(a tree withinclude/+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=ONBuild example applications, plugins and populate example neural models:
-DANIRA_WITH_EXAMPLES=ONBuild anira with tests:
-DANIRA_WITH_TESTS=ONBuild anira with documentation:
-DANIRA_WITH_DOCS=ONDisable 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#
Usage Guide: the model, the contract, the context, the handler and the real-time entries.
Examples: the bundled plugins, benchmarks and web pages.
Benchmarking Guide: measure a model on your machine.
Architecture: how anira runs an inference.