Changelog#
All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
Unreleased#
v3.0.0-alpha.3 - 2026-11-06#
The Hard contract’s defaults run: a measured budget and the UNTIL_STABLE warm-up pass, which times every plan at prepare, keeps the model’s figure for later prepares and reports each plan’s real-time factor and verdict (anira_plan_info.rt_verdict) for a host to act on (“Try nonetheless”). Model tensors run in any of the ten dtypes anira names, every built-in engine binds in place where its runtime accepts it, and the plan report states per slot and direction what the edge costs and who moves the bytes (ABI 0.3: 228 promised names, 4 draft, 12 Emscripten-only; anira_check_abi accepts the exact ABI version alone).
Refused at prepare: the Async contract, a Buffer spec under a Hard contract, a host domain other than ANIRA_DOMAIN_HOST, a transposing tensor layout. Not run yet: device blocks (every context is Host-only), model tensors with quantisation parameters at the boundary (refused at load); the GPU and draft tensor factories are field fills. npm: @anira-project/anira 3.0.0-alpha.3 on next.
Added#
TypeScript:
ContractHandle.hardBudget(kind, explicitMs),hardWarmup(mode, iterations)(anira::ContractHandle::hard_budget/hard_warmup),HardContractOptions.warmup; a warm-up beforeready()is refused; a JavaScript processor’sanira_processor_desc.idis its defined name, so pages defining it share the figure.The model’s figure: the core keeps each warm-up measurement per loaded model, engine id (per object for
anira.v2.custom) and processor hooks while it lives, so two instances of the same plugin (same model, processor and engine id) report the same latency; a later prepare reuses it and runs no pass (ANIRA_WARMUP_OUTCOME_REUSED, logged with its age), and one whose every plan reuses its figure needs no running thread; two prepares of one model at once measure it once, a FIXED figure is remeasured under a stronger warm-up,ANIRA_WARMUP_NONEignores it; processors of one tail fieldanira_processor_desc.idshare it (anira::Processor(std::string id),Processor::id()), else one withbefore_inference/after_inferencemeasures per registration.C ABI, handler:
anira_plan_infotail fieldswarmup_iterations,warmup_outcome(anira_warmup_outcome:NONE,FIXED,STABLE,CAPPED,REUSED),measured_ms/median_ms(max and median of the last four inferences),rt_factor(inference time / anchor hop period),rt_parallel,rt_verdict(anira_rt_verdict:UNMEASURED,COMFORTABLEat a load (rt_factor / rt_parallel) < 0.75,MARGINAL< 1,NOT_REALTIME), inANIRA_PLAN_INFO_INIT; logged at prepare (Warning: a marginal or not real-time plan, a pass unsettled after 32, an explicit budget below the measurement, a pool that cannot keep up; the budget marked measured or explicit); TypeScriptPlanInfo.warmupIterations,warmupOutcome,measuredMs,medianMs,rtFactor,rtParallel,rtVerdictand the two enums.The MEASURED budget and the UNTIL_STABLE warm-up:
anira_handler_preparetimes ordinary inferences of every plan on the inference threads (hooks and engine call, not the wait); MEASURED sets eachanira_plan_info.budget_msto the max of the last four and sizes the session for the slowest plan; the session is sized again after the pass (the stream starts over, nothing of the pass reaches it or a State pair; engines and processor re-prepared if the entry count moves); an explicit budget only reports them; UNTIL_STABLE (default) stops when the last four lie within 20 % of their median or one clock step, at most 32; FIXED n runs n; without a running inference threadANIRA_ERROR_INVALID_STATE(also for an inference over 10 s); a failed inferenceANIRA_ERROR_ENGINE.Model tensors of any dtype anira names:
ANIRA_DTYPE_F32,F64,F16,BF16,I8,U8,I16,I32,I64,BOOL8(no longer float32 alone), any role, carried in the spec’s dtype end to end (ring, Static store, State pair, engine calls); another dtype (several lanes, unsigned above 8 bits) isANIRA_ERROR_NOT_SUPPORTEDatanira_handler_create; nothing converts: another host type goes inring_dtypes, with a processor converting inpre_process/post_process.C ABI, handler:
anira_plan_slottail fieldsdtype(the model tensor’s) andring_dtype(0 without a ring), logged; TypeScriptPlanSlot.dtype,ringDtype.C ABI, handler:
anira_plan_slottail fieldswindow_derived(1 if derived),window(elements along Time per inference, a flexible one as pinned) andhop(window less overlap), 0 on Static and State slots, the same in every plan, logged; TypeScriptPlanSlot.windowDerived,window,hop.C ABI, handler and context: the enum
anira_mover_flags(ANIRA_MOVER_NONE0,ANIRA_MOVER_ANIRA1: anira’s code, an engine adapter’s copy,ANIRA_MOVER_ENGINE2: the runtime’s code or API copy, a device provider’s upload and readback, a registered engine; both bits where both move, the class then the worse move’s) inmoved_byofanira_plan_slot(tail field) andanira_edge_info, logged; theANIRA_MOVER_ANIRArows are exactly anira’s per-inference copies; TypeScriptPlanSlot.movedBy.C ABI, handler and context: the enum
anira_memory_kind, which a device provider’s edge class follows:ANIRA_MEMORY_UNKNOWN0 (no probe established it;ANIRA_EDGE_UNKNOWN, refused by every edge-cost limit),ANIRA_MEMORY_UNIFIED1 (host memory: CPU path, integrated GPU, Apple silicon, lavapipe;ANIRA_EDGE_UNIFIED_TRANSFER),ANIRA_MEMORY_DEDICATED2 (device memory across a bus;ANIRA_EDGE_DEDICATED_TRANSFER), inmemory_kindofanira_edge_infoandanira_plan_info(tail field), logged; TypeScriptPlanInfo.memoryKind.C ABI, handler and context: the kind is probed with no link dependency through Metal
hasUnifiedMemory, Vulkan’s device type and memory, CUDACU_DEVICE_ATTRIBUTE_INTEGRATED, HIPhipDeviceAttributeIntegrated(5.0+), OpenCLCL_DEVICE_HOST_UNIFIED_MEMORY, D3D12D3D12_FEATURE_DATA_ARCHITECTURE.UMA, on ONNX Runtime’sdevice_id(default 0; CUDA, TensorRT, ROCm, MIGraphX, DirectML), the Metal default device (Core ML, MPSBackend) or, for WebGPU, LiteRTgpuand Vulkan, every device of the API the runtime picks among (Metal on Apple, D3D12 on Windows, Vulkan elsewhere, OpenCL for LiteRT on Android; unknown unless all agree); the web, NPUs and custom providers are unknown; asked lazily, off the audio thread, once per context (5 s timeout) untilanira_context_probe, logged at Debug (anira.system);ANIRA_TEST_MEMORY_KINDSasserts a known machine’s kinds in the tests.C ABI, engines: a registered engine states each slot’s edge after each load, inputs first:
anira_engine_edge(edge_class,reason) fromanira_engine_edge_fnin the tail fieldanira_engine_desc.edgeoverwrites the provider rule’s (NULL keeps it); the mover follows from the class (the engine whatever moves, none onANIRA_EDGE_ZERO_COPY); a refusal fails the prepare with its status, an unnamed class withANIRA_ERROR_ENGINE; C++anira::EngineEdge, virtualEngine::Loaded::edge(is_input, slot, provider_rule)(base: the rule).Web:
HardContractOptions.edgeCost/ContractHandle.edgeCost(anira::Hard::edge_cost,anira::ContractHandle::edge_cost; unset oredgeCost(undefined): no limit);EngineOptions.edge(EngineEdges,{ inputs?: EngineEdge; outputs?: EngineEdge }) atPipeline.addEngine, per direction (unset keeps the provider rule);addEngine(ONNXRUNTIME_WEB_ENGINE_ID)statesANIRA_EDGE_COPYby the engine both ways,ONNXRUNTIME_WEB_ENGINE_EDGES(root, scope and engine entries) for another id; a givenedgereplaces them.Bundled models: example-models
28e6dd9(extras/fetch-models.cmake, wasd1bc5cf): TypedGainNetwork atint16,int8,float16(cast at the boundary), a row per engine (extras/models/model-pool/typed_gain_<dtype>.model.json) and an ExecuTorch export at a static 512-sample window with caller-owned I/O (typed_gain_<dtype>_unplanned.model.json); an ONNX model per dtype (dtype_matrix_<dtype>.onnx); a fully integer TFLite model (quantized_gain_network_int8.tflite); inextras/models/model_files.h; for ONNX Runtime 1.26.0, TFLite 2.17.0, LibTorch 2.12.0, ExecuTorch 1.3.1.Engines: every built-in engine carries the ten dtypes (ONNX Runtime via the untyped
Ort::Value::CreateTensor); quantised I/O (TFLite, LiteRTLiteRtGetQuantizationTypeId, torch, ExecuTorchQInt8,QUInt8,QInt32,QUInt4x2,QUInt2x4) isANIRA_ERROR_NOT_SUPPORTEDat load, never plain integers; ONNX int8 I/O is plain integers.Docs: the dtype guide (
usage/dtypes, and the engine, processor, getting-started, architecture and web pages);anira_tensor_spec_set_state_source(anira/abi/config.h) no longer calls other tensors float32.Web: a JavaScript engine’s tensor views (
engineTensors,EngineTensorView) carrydtypeanddata, a typed array of the dtype over its memory (Uint16Arrayfor float16 and bfloat16, bytes for bool8;f32stays); a bool8 Static input takes numbers (nonzero is 1); an audio node refuses a model of another dtype.Web: the ONNX Runtime Web engine runs every dtype (was float32 only), copied byte for byte (onnxruntime-web 1.25.1); a dtype unlike the model’s element type is
ANIRA_ERROR_CONFIG; its warm-up uses the model’s types.Web:
HardContractOptions.ringDtypes(anira::Hard::ring_dtypes) andContractHandle.hardRingDtype(hard_ring_dtype) name a ring dtype per Streamed tensor.
Changed#
Breaking: bundled models — every
extras/models/**/*.contract.jsonruns the defaults"budget": "measured", "warmup": "until_stable"(the RAVE encoder and decoder keep"on_miss": "zeros"), so its latency depends on the machine. Migration: pin"budget": {"ms": x}with"warmup": "none"or{"fixed": n}, oranira::ContractHandle::hard_budget/hard_warmupon the loaded file.Examples: the plugins, the benchmark fixture, the C install consumer and the web examples print each plan’s measured budget, warm-up and real-time verdict; the plugins and the web examples hold a plan not real-time here until “Try nonetheless” (JUCE: bypass plan and editor; CLAP: Bypassed plan and parameter; web:
AniraAudioNode.hold), never offline (clap.render,waitMs > 0), and the benchmark and the C install consumer run whatever the verdict; an accepted verdict asks again only for a worse one; the web examples awaitready()before their prepare.Docs: the design document describes the measured budget and the warm-up pass as built.
Breaking: Web — the pool’s Workers start at
Context.create(anira_context_create) and outlive a re-prepare; a prepare that warms up needsawait context.ready()first (elseANIRA_ERROR_INVALID_STATE);Context.ready()without a pool waits for a page thread; the warm-up runs on the pool’s Workers, so JavaScript engines are measured too. Migration: await it, or an explicit budget withwarmup: ANIRA_WARMUP_NONE.Breaking: TypeScript —
ContractHandle.hardmirrorsanira::Hard:budgetMsis optional (the measured budget) and the warm-up defaults toUNTIL_STABLE(was NONE withoutwarmupIterations). Migration:budgetMswithwarmup: ANIRA_WARMUP_NONE, orwarmup: ANIRA_WARMUP_FIXEDbesidewarmupIterations.anira::Budgetdefault-constructs to the measured budget, as a C contract does, soanira::Hard{.host_block_min = 512, .host_block_max = 512, .host_rate = 48000}prepares on the defaults; a duration stays explicit.The “inference pool cannot keep up” Warning moves from the latency calculator into prepare, once per prepare, beside the plans’ verdicts.
Breaking: C ABI — a FIXED warm-up runs per plan at prepare (unless the model’s kept figure answers it), not per executor at load (
0: none); built-in executors run one inference when made, and handlers differing only in the warm-up count share their loaded model. Migration: none (engine and hook calls counted at prepare include the pass).Breaking: C ABI — a MEASURED budget with
ANIRA_WARMUP_NONEor FIXED 0 isANIRA_ERROR_CONFIGat prepare (every MEASURED budget wasANIRA_ERROR_NOT_SUPPORTED); an explicit budget takes any warm-up. Migration: give it a warm-up, or an explicit budget.A too-slow model prepares under a MEASURED budget as under an explicit one the pool cannot keep up with (warned); a Hard prepare never returns
ANIRA_ERROR_BUDGET, now for Async deadlines only.Natively
anira_inference_thread_startreturns once its thread is in its loop (WebAssembly: the Worker enters it after the call).Web: the module’s memory starts at 128 MiB by default and 64 MiB at least (
Anira.create’sinitial; AniraWeb’s-sINITIAL_MEMORY64 MiB), was 256 MiB, as the core’s queue no longer preallocates (Fixed); not breaking; the installation guide sizes a handler (#207).Model config: a Streamed tensor’s window is optional (was
ANIRA_ERROR_CONFIGwithoutanira_tensor_spec_set_window,TensorSpec::windowor"window"): a fixed Time axis is the window, a dynamic one a flexible[1, ANIRA_UNBOUNDED]window pinned by the anchor hop (#198); a declared one wins, an overlap alone isANIRA_ERROR_CONFIG, andanira_tensor_spec_window(SpecView::window) andanira_model_config_to_jsonshow declared windows only, the plan report the one in use.Breaking: C ABI —
anira_edge_classsorts where an edge takes the bytes, by cost:ANIRA_EDGE_ZERO_COPY0, newANIRA_EDGE_COPY1 (within one domain), newANIRA_EDGE_UNIFIED_TRANSFER2 (a CPU-device crossing in unified memory), newANIRA_EDGE_DEDICATED_TRANSFER3 (over a bus), newANIRA_EDGE_UNKNOWN255 (memory kind not probed; above every limit), replacingANIRA_EDGE_DEVICE_COPY1,ANIRA_EDGE_HOST_COPY2,ANIRA_EDGE_UNAVAILABLE3; who moves is the newmoved_by. Migration: a copy readsANIRA_EDGE_COPY, a device row itsmemory_kind’s class; recompile.C ABI, handler: plan slots’
edge_class(andallocate_class) andmoved_byreport what the engine does (all zero-copy before):ANIRA_EDGE_ZERO_COPYin place over host memory (CPU path, XNNPACK, ONNX Runtime’sDnnlExecutionProvider,ACLExecutionProvider,ArmNNExecutionProvider),ANIRA_EDGE_COPYbyANIRA_MOVER_ANIRA(LibTorch outputs, ExecuTorch planned outputs) orANIRA_MOVER_ENGINE(ExecuTorch planned inputs,set_input), a device provider its memory kind’s class, moved by the engine (unknown for an NPU, a custom provider, every web device provider); capability rows likewise (device rows saidANIRA_EDGE_HOST_COPY).Breaking: C ABI — the edge cost is a limit prepare enforces:
anira_contract_set_edge_cost(contract, anira_edge_class worst_allowed)/anira_contract_edge_costtake and return ananira_edge_class(wasanira_edge_cost), default no limit (ANIRA_EDGE_UNKNOWN); a limit admitsclass <= limit;anira_handler_preparedrops plans above it (an Info inanira.capi; the report and plan indices keep the rest), none left isANIRA_ERROR_EDGE_UNREACHABLE; JSON"edge_cost":"zero_copy","copy","unified_transfer","dedicated_transfer"(no key: no limit;"unknown"refused);anira::Hard::edge_cost,anira::Async::edge_cost,anira::ContractHandle::edge_costandContractHandle::hard()usestd::optional<anira_edge_class>(std::nullopt: no limit). Migration:ANIRA_EDGE_COST_STRICT/"strict"isANIRA_EDGE_ZERO_COPY/"zero_copy",ANIRA_EDGE_COST_PERMISSIVE/"permissive"no limit (ANIRA_EDGE_DEDICATED_TRANSFERalso refuses unknown edges).Engines: a model tensor a built-in engine cannot bind is
ANIRA_ERROR_NOT_SUPPORTEDat load (wasANIRA_ERROR_CONFIG).Engines: chunk buffers align to the largest boundary a plan’s engine asks for (
Loaded::buffer_alignment, 64 bytes built in); a descriptor off it is copied.Engines: in place: ONNX Runtime both sides, LibTorch inputs, TFLite every slot (custom allocations; was copied; a result the runtime leaves elsewhere is copied out), ExecuTorch unplanned slots (an output where the slot holds its capacity); copied once: LibTorch outputs, ExecuTorch planned ones (inputs via
set_input, one copy fewer).Engines: LiteRT binds each slot as a kept buffer over its memory, CPU and accelerators alike (was a copy each way); its environment sets
kLiteRtEnvOptionTagRuntimeLibraryDir, so a GPU package’s accelerators register.Breaking: Web —
anira_em_engine_desc_initandanira_em_pipeline_add_js_enginetakeinput_edgeandoutput_edgeafterjs_key,hook_mask,engine_flags: aconst anira_engine_edge*per direction (NULL: the provider rule; an unknownanira_edge_classisANIRA_ERROR_INVALID_ARGUMENT). Migration: passNULL, NULL;Pipeline.addEnginetakesEngineOptions.edge.inputs/.outputs.C ABI, configuration: a ring dtype defaults to its spec’s (was
ANIRA_DTYPE_F32): set one that differs from it (anira_contract_hard_set_ring_dtype,anira::Hard::ring_dtypes,ring_dtypes) only with a converting processor (elseANIRA_ERROR_CONFIGat prepare);anira_contract_hard_num_ring_dtypes/anira_contract_hard_ring_dtyperead what was set,anira_ring_dtypethe resolved one; not breaking (alpha.2 ran float32 only).Build: libanira links
${CMAKE_DL_LIBS}on every ELF build (was LibTorch only) for the memory probe’sdlopen; no device library is linked.CI: clang-tidy covers the memory probe; the iOS simulator leg runs
test_platform.C ABI, handler: dtype refusals (per call into
anira_handler_rt_error, at prepare, inanira_em_audio_node_create) spell dtypes as words and name the remedy (per call: a tensor of the ring dtype, orring_dtypesplus a converting processor; at prepare: the converting processor or dropping the ring dtype); a Static tensor carries its spec’s dtype.Breaking: C ABI — a capability row is a directed edge:
anira_edge_infois{struct_size, from_domain, from_engine, from_provider, to_domain, to_engine, to_provider, available, edge_class, moved_by, memory_kind, rung, reason, from_engine_id, from_provider_id, to_engine_id, to_provider_id}, an end a backend when its engine is set (ANIRA_ENGINE_CUSTOM/ANIRA_PROVIDER_CUSTOMwith ids), else a domain;anira_capabilities_edgesgives two rows peranira_capabilities_backendsrow,2ifromANIRA_DOMAIN_HOSTto backendi,2i + 1back (pipelines too);rungis ananira_probe_rung. Migration: the backend is in even rows’to_*, odd rows’from_*; step by two; recompile.Breaking: C ABI —
anira_capabilities_edge(capabilities, edge)andanira_pipeline_capabilities_edge(pipeline, context, edge)take oneanira_edge_infowith its ends set (a domain end hasANIRA_ENGINE_NONE), were(…, anira_domain from, const anira_backend_id* to, anira_edge_info* out); no row isANIRA_ERROR_EDGE_UNREACHABLE, astruct_sizeshort ofto_provider_idANIRA_ERROR_INVALID_ARGUMENT; C++anira::Capabilities::edge/anira::PipelineCapabilities::edgeaddedge(const BackendId& from, Domain to). Migration: fromANIRA_EDGE_INFO_INITsetto_engine,to_provider,to_engine_id,to_provider_idand pass&edge; existing C++ calls are unchanged.Breaking: C ABI —
ANIRA_EDGE_INFO_INIThas classANIRA_EDGE_UNKNOWN(available0, ends unset), notANIRA_EDGE_ZERO_COPY. Migration: read the class anira returns.Breaking: C ABI —
anira_context_probe(context, err)andanira::Context::probe()loseforce(every probe was and is full, forgetting the kept memory kinds). Migration: drop it (context.probe()).Breaking: C ABI —
anira_plan_slot.domain_in/domain_outarefrom_domain/to_domain(same offsets,ANIRA_PLAN_SLOT_INITunchanged), TypeScriptPlanSlotfromDomain/toDomain(weredomainIn/domainOut). Migration: rename.Breaking: C ABI, C++ and TypeScript — a processor’s real-time promise is per phase, in the phase bits every other processor surface uses:
anira_processor_desc.flagsisrealtime_phases(same offset and type), an OR of the newANIRA_PHASE_BIT(phase)(1u << phase) over the five per-chunk phases (pre_process,post_process,before_inference,after_inference,reset; another bit isANIRA_ERROR_INVALID_ARGUMENTatanira_pipeline_add_processor), andANIRA_PROCESSOR_FLAG_REALTIME_PRE_POST/ANIRA_PROCESSOR_FLAG_REALTIME_HOOKSare gone.anira_handler_preparerequires the bit of every filled phase the contract runs on the driving thread (Hard:pre_process,post_process,reset), elseANIRA_ERROR_CONFIGnaming the phase andrealtime_phases; a promised phase that is not filled is no error, and a processor of the inference hooks alone needs no promise. C++:anira::Processor::flags()isrealtime_phases()in thek_*bits ofphases()(default 0;Pipeline::add_processorrefuses a bit outsidek_all_phases), andPipeline::add_processorfills the reset slot only fork_resetinphases()(new,phase_bit(ANIRA_PHASE_RESET);k_pre_processandk_post_processno longer bring it);anira::v2::LegacyProcessorpromisesk_pre_process | k_post_process | k_reset. Web:ProcessorOptions.flagsisrealtimePhases(default the bits ofpre_process,post_processandreset), and theprocessor_flagsparameter ofanira_em_processor_desc_initandanira_em_pipeline_add_js_processorisrealtime_phases. Migration:desc.flags = ANIRA_PROCESSOR_FLAG_REALTIME_PRE_POSTbecomesdesc.realtime_phases = ANIRA_PHASE_BIT(ANIRA_PHASE_PRE_PROCESS) | ANIRA_PHASE_BIT(ANIRA_PHASE_POST_PROCESS) | ANIRA_PHASE_BIT(ANIRA_PHASE_RESET)(ANIRA_PROCESSOR_FLAG_REALTIME_HOOKSadds the bits ofANIRA_PHASE_BEFORE_INFERENCEandANIRA_PHASE_AFTER_INFERENCE); a C++flags()returningANIRA_PROCESSOR_FLAG_REALTIME_PRE_POSTbecomesrealtime_phases()returningk_pre_process | k_post_process | k_reset(orphases()when every body is real-time); TypeScriptflags: ANIRA_PROCESSOR_FLAG_REALTIME_PRE_POSTbecomesrealtimePhases: ANIRA_PHASE_BIT(anira_phase.ANIRA_PHASE_PRE_PROCESS) | …or is left out; a C++Preparedthat overridesresetaddsk_resettophases(), else its reset is not called.C ABI, handler, context and engines: the provider rule is per direction: same class and mover in this pre-release, but a device provider’s reason names the upload or the readback (slot rows, capability rows,
anira_engine_edge_fn’sout,anira::Engine::Loaded::edge’sprovider_rule,Loaded::provider_edge(is_input)); unknown: “memory kind not probed:”. Docs: the user guides are rewritten for 3.x on short pages: the usage guide on twelve pages (
usage/: models, contracts, the three files, context, handler, processing, state, dtypes, edges, tensors, the C API, teardown), processors on one page with an examples page, custom engines on three, migration from 2.x on four in the names 2.x shipped, contributing on three, and new pages for plugins and hosts, the web memory and the architecture; every numbered section reference is a label now.Examples: the JUCE plugin’s “Backend Type” and the CLAP plugin’s “Backend” list only the engines the build compiled in (
anira::enabled_engines()) that the model file has an entry for, then the bypass (“BYPASS”, “Bypassed”) last; the default is ONNX Runtime where the build has it (JUCE variant 3 defaults to LibTorch: the stateful LSTM’s ONNX export starts every inference from a zero state; variants 6 and 7 have LibTorch only); the CLAP choices are reordered (Bypassed was index 3).Docs: the README’s model file, the usage guide’s processing and state examples and the web
processor-and-engineexample declare no window where the fixed Time extent is the window.Branches: the 3.x line is developed on
main(renamed fromv3), the 2.x line onv2(renamed frommain); the workflows’ pull-request triggers dropv3, and the contributing guide names the new bases. The docs deploy, the cache warmer and coverage already run on pushes tomain.
Removed#
anira_handler_prepare’sANIRA_ERROR_NOT_SUPPORTEDrefusals ofANIRA_BUDGET_MEASUREDandANIRA_WARMUP_UNTIL_STABLE, a fresh contract’s defaults.Breaking: C ABI —
ANIRA_EDGE_DEVICE_COPY(1) andANIRA_EDGE_HOST_COPY(2) ofanira_edge_class: a copy within one domain isANIRA_EDGE_COPY, a CPU–device crossingANIRA_EDGE_UNIFIED_TRANSFER(unified memory) orANIRA_EDGE_DEDICATED_TRANSFER(a bus). Migration:ANIRA_EDGE_COPY; a device provider’s formerANIRA_EDGE_HOST_COPYrow is the transfer itsmemory_kindgives.Breaking: C ABI —
ANIRA_EDGE_UNAVAILABLEofanira_edge_class: a row’savailable(withreason) says whether its edge exists, an unavailable row names the class it would provide, and a pair without a row isANIRA_ERROR_EDGE_UNREACHABLE. Migration: testanira_edge_info.availablewhere code comparededge_classwithANIRA_EDGE_UNAVAILABLE.Breaking: C ABI — the enum
anira_edge_cost(ANIRA_EDGE_COST_PERMISSIVE,ANIRA_EDGE_COST_STRICT) and its words"permissive","strict"; the edge cost is ananira_edge_classthreshold; the migration is under Changed.
Fixed#
Core: the model’s figure keys a model given as bytes by a 64-bit content hash of the bytes (XXH64, computed once per bytes object) and their size, not by their owner, so two configs that borrow or copy the same model bytes (two instances of the JUCE example over its BinaryData) share one figure and latency.
Docs:
anira/abi/draft/tensor_platform.his included byanira/anira_all.h, notanira/anira.h;anira_tensor_spec_create’s name binds a named engine side’s slot the entry’s tensors record leaves unnamed, and a custom engine’s load record carries it.LibTorch: each thread that runs a model sets the engine’s single intra-op thread, not the control thread alone; on Linux x86_64 (OpenMP) a oneDNN primitive (the stateful RNN’s LSTM) spun one thread per core beside the inference threads.
Core: the inference queue no longer preallocates ~329 MiB per process from
anira_context_createon, nor 8 MiB per handler (#200; #207 on the web): each handler reserves room for its struct pool at prepare, off the audio thread, whosetry_enqueuestill never allocates.Core: a handler’s prepare or destroy no longer zero-fills the other handlers’ queued inferences beyond 1,024 (#200); its drain requeues them with the allocating enqueue, on the control thread.
Core: a stateful handler no longer zero-fills a call’s chunks once more than 33 to 64 wait their turn (#199): its pending queue is reserved at prepare for the whole struct pool.
ExecuTorch: the engine’s first init shrinks the runtime’s process-wide thread pool to the calling thread (
ThreadPool::_unsafe_reset_threadpool(1)): a kernel outside the XNNPACK delegate reached it throughparallel_fordespiteNoThreadPoolGuardand started a worker per further core, which outlived every anira object; a statically linked binary that is unloaded (a Windows plugin) joined them in the pool’s static destructor insideFreeLibrary, under the loader lock, and the unload never returned (LibraryUnload.UnloadWithLiveSessionIsJoinedByHookon the static Windows legs, once every executor ran its creation warm-up).C ABI, handler: a chunk a core queue has no room for (the inference queue, an exclusive handler’s pending queue, a drain’s requeue) sets
anira_handler_rt_errortoANIRA_ERROR_CAPACITYlike a dropped hop, notANIRA_OK, and stays zeros at its stream position.Latency: a Static or State output no longer rounds the outputs’ latency up to whole hops (#235): only Streamed outputs are synchronized, one alone keeps its figure, a non-streamed one reports 0;
stateful_accumulator, the stateful RNN and RAVE report and prime less where the inference queue is not whole hops.Latency: several Streamed outputs meet on the grid of 1/g hops (g the gcd of their hops), at the least coherent figure at or above each ⌊P_i Λ⌋, not at whole hops; equal hops keep their figures.
anira_handler_get_latenciesand the rings’ priming only go down; a declared latency (anira_contract_hard_set_latency,"latencies") is untouched.Processor:
anira_processor_default_post_processreads an output asanira_processor_default_pre_processlays out an input,channels × window, and pushes each channel’s newest hop; aschannels × hopit mixed channels or pushed late an output with an overlap (anira_tensor_spec_set_window). A version 2 document whose output exceeds itspostprocess_output_sizegets such an overlap (the 2.xPrePostProcessorkeeps the 2.x push).Web: the ONNX Runtime Web engine’s plan rows (
addEngine(ONNXRUNTIME_WEB_ENGINE_ID)) sayANIRA_EDGE_COPY, moved by the engine, notANIRA_EDGE_ZERO_COPY.C ABI, handler: an ONNX Runtime plan on a device execution provider (CUDA, TensorRT, ROCm, DirectML, CoreML, WebGPU) reports its slots moved by the engine at the class of the device’s memory kind, as its capability row does, not
ANIRA_EDGE_ZERO_COPY.C ABI, configuration:
anira_tensor_spec_createrefuses a dtype of 0 (ANIRA_ERROR_INVALID_ARGUMENT);anira_model_config_to_jsonrefuses a dtype without a model-file word (ANIRA_ERROR_NOT_SUPPORTED), where it wrote"float32".Docs:
anira_model_config_model_pathreturns NULL for an entry without a source too (anira_model_config_add_model_pathwith NULL,ModelConfig::add_model(engine_id));anira::ModelConfig::model_paththrowsANIRA_ERROR_INVALID_STATEfor both pathless kinds andANIRA_ERROR_INVALID_ARGUMENTout of range;anira_em_audio_node_createlists a Streamed slot’s non-float32 ring dtype underANIRA_ERROR_CONFIG.Docs: a chunk’s
entry(anira_processor_ctx.entry,anira_engine_ctx.entry,anira_prepare_info.num_entries,anira::EngineContext::entry) is its position in the handler’s chunk pool, not the core’s job queue.Docs:
anira_handler_preparekeys a registered engine’s figure by its id (anira.v2.customby its engine object), andanira_contract_create_hard/anira_contract_create_asyncname no edge-cost limit (ANIRA_EDGE_UNKNOWN) as their default, not the removedPERMISSIVE;anira/compat/v2.hpp’sanira::v2::ContextConfigandanira::v2::Contextname v2.3.0’s classes alone.Examples: a JUCE or CLAP backend choice without a plan (an engine the build lacks, such as ExecuTorch in a shared build) kept the previous plan running while the parameter showed the choice; the list no longer offers it, and a choice whose engine cannot run the model on the machine runs the bypass plan and says so (#243).
v3.0.0-alpha.2 - 2026-11-01#
The 3.x runtime on the Hard path over the versioned C ABI (anira/abi/*.h, ABI 0.2: 228 promised names, 4 draft, 12 Emscripten-only), with anira/anira.hpp as its C++20 face and anira/compat/v2.hpp as the 2.x one; the 2.x C++ classes are no longer installed. No binary promise before v3.0.0: anira_check_abi accepts the exact ABI version alone (alpha.1’s 0.1 headers are refused). libanira.so.0 (libanira.0.dylib, anira-0.dll) exports the anira_* entries alone. tanh-lib, concurrentqueue and nlohmann_json are private and not installed; anira’s copies of the first two carry names of their own (tanh-lib v0.5.0’s core in thl::anira, the queue as anira_moodycamel), so a host’s own tanh-lib or concurrentqueue shares no code or state with anira’s.
Refused at prepare: the Async contract, and the Hard defaults ANIRA_BUDGET_MEASURED and ANIRA_WARMUP_UNTIL_STABLE (set an explicit budget and a FIXED or NONE warm-up). Not run yet: device blocks (every context is Host-only; the probe and the capabilities report the host domain alone); model tensors other than float32, declared state excepted; the GPU and draft tensor factories are field fills. npm: @anira-project/anira 3.0.0-alpha.2 on next, the typed layer with anira.hpp’s names (Anira, Context, ModelConfig, ContractHandle, Pipeline, InferenceHandler, PlanReport, createAudioNode, defineProcessor, defineEngine) and the ONNX Runtime Web engine at @anira-project/anira/engines/onnxruntime-web.
Added#
C ABI, headers and enums: ABI 0.2 promises 228 names (88 at v3.0.0-alpha.1);
abi/symbols-draft.txtlists 4 draft names andabi/symbols-emscripten.txt12 Emscripten names; the wasm build exports all three lists and_malloc/_free; new headersanira/abi/context.h,core.h,thread.h.C ABI, headers and enums:
<anira/anira_all.h>, the scope-allumbrella, includes every C ABI header, theanira/abi/draft/headers andanira/anira_em.h, and compiles alone as C11 and C++17; Emscripten-only headers ininclude/anira/are empty elsewhere and included by no header of the registry.C ABI, headers and enums: appended
ANIRA_MISSED(5, positive) andANIRA_ERROR_NOT_FOUND(-23, a lookup matching nothing) toanira_status,ANIRA_TENSOR_PLANAR = 8toanira_tensor_flags,ANIRA_STRUCT_ENGINE_CTXandANIRA_STRUCT_PLAN_QUERY(13) toanira_struct_id(id 4 is nowANIRA_STRUCT_PROCESSOR_CTX),ANIRA_ROLE_STATEtoanira_role,ANIRA_ENGINE_CUSTOM,ANIRA_PROVIDER_NONE,ANIRA_PROVIDER_CPU,ANIRA_PROVIDER_CUSTOM(both enums renumbered, Changed below), andANIRA_DTYPE_F64(ANIRA_MAKE_DTYPE(ANIRA_DTYPE_FLOAT, 64, 1), JSON"float64"); new definesANIRA_INSTANCES_AUTO,ANIRA_VARIANT_ANYand the flags ofanira/abi/enums.h(below).C ABI, tensor (
anira/abi/tensor.h,anira/abi/draft/tensor_platform.h):anira/abi/tensor.h, frozen Tier-1 records withoutstruct_size, alike on wasm32, LP64 and LLP64:anira_tensor(216 bytes;shape[8],strides[8]in elements with all-zero = packed,byte_offset,manager_ctx), the unionanira_memory_handle(24 bytes,raw[3]) andanira_sync_token(24 bytes);anira_tensor_release_proc(ANIRA_PTR,[thread-safe, !audio-thread]) never runs on the driver thread.C ABI, tensor: the factories
anira_tensor_init_host,anira_tensor_init_pinnedand the record-onlyanira_tensor_init_cuda,anira_tensor_init_gl_buffer,anira_tensor_init_vulkan,anira_tensor_init_opaque_fd,anira_tensor_init_wgpu_buffer,anira_tensor_init_dmabuf([thread-safe][callback-safe]ANIRA_NONBLOCKING) read their arguments, then zero and fill the record (anira_tensor_init_host(&t, p, t.dtype, t.ndim, t.shape)re-points one); a dtype of 0, a NULL shape with a rank above 0, a negative extent or a rank aboveANIRA_MAX_RANKleaves it all-zero; a NULL fence or a negativesync_fdisANIRA_SYNC_NONE, a passed fd then belongs to the record, and a refused call takes neither the token nor the fd.C ABI, tensor: planar host memory:
ANIRA_TENSOR_PLANAR,anira_tensor_init_host_planar(one pointer per plane of axis 0) andanira_tensor_plane; only the Hard entries take it (elsewhereANIRA_ERROR_NOT_SUPPORTED;anira_tensor_data/anira_tensor_data_f32return NULL).C ABI, tensor:
anira_tensor_init_dlpack(tensor, dl_managed_tensor_versioned, err)([main-thread]) bridges a DLPack 1.x tensor on CPU (ANIRA_DOMAIN_HOST) or CUDA host memory (ANIRA_DOMAIN_HOST_PINNED), elseANIRA_ERROR_NOT_SUPPORTED; read-only setsANIRA_TENSOR_READ_ONLY;releasecalls the deleter once; a refusal leaves*tensoruntouched.C ABI, tensor:
anira_tensor_data_f32(host or pinnedANIRA_DTYPE_F32),anira_tensor_data(NULL unless the dtype matches; never converts),anira_tensor_num_elements,anira_tensor_extent,anira_sizeof(0 for an unknown id),anira_sync_token_reset/anira_sync_token_dup([thread-safe, !audio-thread]: close / duplicate an owning fd or NT handle, a plain zero / copy for any other kind; duplicating an owning kind on WebAssembly isANIRA_ERROR_NOT_SUPPORTED).C ABI, tensor:
anira/abi/draft/tensor_platform.h(of the umbrellas only<anira/anira_all.h>includes it, not<anira/anira.h>):anira_tensor_init_metal,anira_tensor_init_iosurface,anira_tensor_init_ahardwarebuffer,anira_tensor_init_d3d12, record-only and unpromised until measured (promotion keeps the name).C ABI, configuration (
anira/abi/config.h, JSON): the read-back, 32[main-thread]getters afteranira_contract_from_json:anira_tensor_spec_name/_dtype/_role/_ndim/_latency/_state_source/_axis(a hole is{ANIRA_AXIS_ANY, 0}) /_window/_time_ratio;anira_model_config_num_inputs/_num_outputs/_input/_output(valid until the nextadd_input/add_output) /_default_engine/_state/_max_instances/_anchor/_tensor_name(config, model_index, canonical)/_model_ext/_tensor_layout(counts asanira_handler_get_latenciesdoes);anira_contract_hard_host_blocks/_hard_budget/_hard_warmup/_hard_on_miss/_hard_miss_fn/_hard_wait_ratio/_hard_ring_dtype(status getters,ANIRA_ERROR_WRONG_CONTRACTon Async) with the value getter_hard_num_ring_dtypesfor the count,anira_contract_edge_cost;anira_context_config_threads/anira_context_config_log(anira_log_desc); value getters take noanira_error*.C ABI, configuration: providers twin the engines: one
anira_providerdoes not name travels as the stringprovider_id, likeengine_id;anira_backend_idandanira_plan_infogainprovider_id,anira_engine_load_infoprovider,provider_id,option_keys/option_values/num_options(one load per provider; an unservable one isANIRA_ERROR_NOT_SUPPORTED),anira_engine_descproviders/num_providers(the CPU path only if"cpu"is listed or there is no list).C ABI, configuration:
anira_model_config_set_model_provider/anira_model_config_model_providerpin an entry to the provider its file is built for; JSON spells the pair as two keys, likeanira_backend_id,anira_provider_option_setandanira_plan_info:"provider": "xnnpack"beside"engine": "executorch"("coreml","cpu", a custom"com.example.npu";"default"/"none"refused); a:in an engine word is refused.C ABI, configuration:
anira_model_config_set_default_provider/anira_model_config_default_providerand JSON"default_provider"beside"default_engine": the handler starts on the first plan of the default engine (of any engine without one) on that provider; a default provider no entry of that engine can run isANIRA_ERROR_CONFIGatanira_handler_create; unavailable here, it falls back to the default engine’s first plan, else plan 0, with a Warning atanira_handler_prepare;ANIRA_PROVIDER_NONEsets none.C ABI, configuration: the context extension
"provider_options"(version 1;anira_ext_provider_options,ANIRA_EXT_PROVIDER_OPTIONS_INIT; C++anira::ext::ProviderOptionsviaContextConfig::ext): per backend ananira_provider_option_set(ANIRA_PROVIDER_OPTION_SET_INIT,num_optionsstring pairs); JSON{"sets": [{"engine": "onnxruntime", "provider": "cuda", "options": {"device_id": "0"}}]}; a malformed set isANIRA_ERROR_INVALID_ARGUMENTatanira_context_config_set_extand at parse; sets forANIRA_PROVIDER_NONE, the CPU path or an engine not reading"context:provider_options"are refused (a custom one receivesanira_engine_load_info.option_keys/option_values, C++EngineLoadInfo::option_keys()/option_values()); an unserved provider isANIRA_ERROR_NOT_SUPPORTED.C ABI, configuration:
anira_contract_set_host_domain([main-thread], likeanira_contract_set_edge_cost) declares a tensor’s host-end domain (defaultANIRA_DOMAIN_HOST), reported asdomain_in/domain_out; a badanira_domainisANIRA_ERROR_INVALID_ARGUMENT, an unknown name isANIRA_ERROR_CONFIGand a non-host domainANIRA_ERROR_NOT_SUPPORTEDatanira_handler_preparefor now; JSON"host_domains"beside"hard"/"async"("host","host_pinned","cuda", …); C++anira::ContractHandle::host_domain(name, Domain).C ABI, configuration:
anira_contract_hard_set_latencydeclares a Hard output’s stream latency foranira_handler_get_latency/_get_latenciesand its ring priming (the 2.xInferenceHandler::prepare(host_config, custom_latency, ...), unclamped); aboveINT32_MAXisANIRA_ERROR_INVALID_ARGUMENT, AsyncANIRA_ERROR_WRONG_CONTRACT, below the spec’slatencyor on an input, a non-Streamed or an unknown outputANIRA_ERROR_CONFIGatanira_handler_prepare; read-backanira_contract_hard_num_latencies/anira_contract_hard_latency; JSON"latencies"in the hard object.C ABI, configuration: fractional Hard host blocks:
host_block_min/host_block_maxare doubles (the 2.xsamplesPerBlock / 2048.fidiom), read as the rationalLatencyCalculator::rationalizefinds; both 0, or finite and > 0 with min <= max, elseANIRA_ERROR_INVALID_ARGUMENT(anira_contract_create_hard,anira_contract_hard_set_host_blocks;ANIRA_ERROR_JSONin a file); a call carriesfloor(b)orceil(b)samples, an uncovered pop isANIRA_MISSED.C ABI, configuration:
anira_vulkan_descgainsint32_t device_index(besidequeue_index) anduint32_t reserved, also inANIRA_VULKAN_DESC_INITand JSONvulkan.device, so the indexanira_context_config_set_vulkansets survivesanira_context_config_to_json; a positional initializer that spells every member now draws-Wmissing-field-initializers(two members more); the_INITmacro and designated initializers need nothing.C ABI, context, core, thread and log (
anira/abi/context.h,core.h,thread.h,log.h):anira/abi/context.h,anira/abi/core.h,anira/abi/thread.h:anira_context_create/destroy/probe/capabilities; later configs reconcile per field (the most verbose log level; the first wait strategy, drain mode, queue capacity and interval, warned; threads only shrink, never to zero; after the last user the next applies whole); a context keeps its sink,ANIRA_LOG_FLAG_DISABLE_PLATFORM_SINKandANIRA_LOG_FLAG_TRACE_FAILURESwhile it lives; a device block isANIRA_ERROR_NOT_SUPPORTED.C ABI, context:
anira_context_byte_image_bytes(the dense encoding); core-wide, with no per-context twin:anira_num_inference_threads(0 before the first handler) andanira_drain_log(anira/abi/log.h; C++anira::drain_log(),anira::num_inference_threads()inanira/anira.hpp);anira/abi/core.h:anira_now_ms/anira_now_ns([callback-safe],ANIRA_NONBLOCKING),anira_shutdown/anira_release_core_if_idle/anira_has_core(anira_shutdownisANIRA_ERROR_INVALID_STATEwhile a context or handler lives;anira::Core::shutdown()stays internal);anira_enabled_engines(C++anira::enabled_engines()) lists the compiled-in engines without a context.C ABI, context:
anira_inference_thread_create(on ananira_context*) /run_loop/execute/start/stop/has_exited/should_exit/is_running/destroy;startisANIRA_ERROR_INVALID_STATEwhile running,ANIRA_ERROR_OUT_OF_MEMORYwhen the system refuses the thread (InferenceThread::start()abool).C ABI, context: capabilities over the Tier-2
anira_backend_id/anira_edge_info:anira_capabilities_backends/domains/ext_kinds/edges/edge(stride-explicit,ANIRA_INCOMPLETEwhen short, Host rows only), a row per compiled-in engine and provider its runtime reports usable,ANIRA_PROVIDER_CPUfirst (ONNX Runtime’s providers, unknown ones asANIRA_PROVIDER_CUSTOM; LiteRT’s"gpu","npu","webnn"whereANIRA_LITERT_ACCELERATOR_QUERYis set, all but the Windows DLL; ExecuTorch’s delegates; LibTorch and TFLite CPU only);anira_context_probeasks again;anira_handler_createadmits exactly the reported providers.C ABI, context:
anira_edge_infogainsto_provider_idandanira_edge_info.to_engine_id(ANIRA_EDGE_INFO_INIT); a row’s host edge is zero-copyANIRA_RUNG_STATICto the CPU path and XNNPACK, an engine-made copyANIRA_RUNG_IDENTITYto a device;anira_capabilities_edgematches custom providers by name; custom engines’ rows come fromanira_pipeline_capabilities_backends(pipeline, context, element_size, count, out)andanira_pipeline_capabilities_edge(C++Pipeline::capabilities(context),anira::PipelineCapabilities).C ABI, context: an
anira_log_fnon a context config receives the platform sink’s records asanira_log_record(flagswithANIRA_LOG_RECORD_REALTIME/ANIRA_LOG_RECORD_CONTRACT_VIOLATION,dropped_before, …) at the context’s level, over onethl::Logger;anira_context_destroywaits for in-flight sink calls and is refused from inside one.C ABI, lifecycle, processor and engine (
anira/abi/lifecycle.h,processor.h,engine.h):anira/abi/processor.h,anira_pipeline_add_processor(anira/abi/handler.h): one processor per pipeline (a second isANIRA_ERROR_INVALID_STATE), owning the phases it fills;anira_processor_desc(Tier 2,ANIRA_PROCESSOR_DESC_INIT:struct_size,abi_version,user_data,consumed_kindsas"<host>:<kind>",flags, nine slots) lives in a refcounted carrier, soreleasefires once; no name, no domain.C ABI, processor:
ANIRA_PROCESSOR_FLAG_REALTIME_PRE_POST = 1u(pre_process,post_process) andANIRA_PROCESSOR_FLAG_REALTIME_HOOKS = 2u(before_inference,after_inference) promise no allocation, lock or block; under Hard a filledpre_process,post_processorresetneeds PRE_POST (ANIRA_ERROR_CONFIGat prepare); an unknown bit isANIRA_ERROR_INVALID_ARGUMENT.C ABI, processor: slots
pre_process,post_process,before_inference,after_inference(anira_processor_fn,(ctx, prepared, user_data)),reset(anira_processor_reset_fn,ANIRA_PHASE_RESET = 7),prepare(anira_processor_prepare_fn,(info, user_data, out_prepared)),unprepare(anira_processor_unprepare_fn,ANIRA_PHASE_UNPREPARE = 8),init(anira_processor_init_fn,[main-thread], once per registration before any load, retried after a refusal,ANIRA_PHASE_INIT = 9),release(anira_processor_release_fn); a refused prepare or init failsanira_handler_prepare; the engine addsANIRA_PHASE_LOAD = 10/ANIRA_PHASE_UNLOAD = 11; a chunk runspre_process, State feed,before_inference, the engine (ANIRA_PHASE_INFERENCE),after_inference, State capture,post_process; a NULL phase runs the default.C ABI, lifecycle:
anira/abi/lifecycle.h:anira_prepare_info(ANIRA_PREPARE_INFO_INIT: handler, plan report,num_entries, slot templates, names,flagswithANIRA_PREPARE_EXCLUSIVE = 1uwhen anANIRA_MODEL_STATEFULmodel or a declared State pair runs one inference at a time, in order) andanira_init_info(ANIRA_INIT_INFO_INIT:log_level,num_threadsasanira_num_inference_threads, the first preparing handler’scontext).C ABI, processor:
anira_processor_ctx(Tier 1, 64 bytes,ANIRA_STRUCT_PROCESSOR_CTX):phase,engine/providerwithengine_id/provider_id,variant,num_inputs,num_outputs,ticket(ANIRA_TICKET_INVALIDunder Hard),entry(0 .. anira_handler_num_entries(handler) - 1, a per-chunk scratch index),frame;anira_handler_num_entriesis[main-thread & prepared].C ABI, processor: context accessors (
[driver-thread | inference-thread] [callback-safe] ANIRA_NONBLOCKING):anira_processor_input_role/anira_processor_output_role(ANIRA_ROLE_FORCE32on refusal),anira_processor_input_ring/anira_processor_output_ring,anira_processor_input_tensor/anira_processor_output_tensor(borrowed, per callback),anira_processor_engine,anira_processor_provider; what a slot lacks in the phase isANIRA_ERROR_INVALID_STATE, a bad slot or NULL outANIRA_ERROR_INVALID_ARGUMENT, latched intoanira_handler_rt_error.C ABI, processor:
anira_ringwithanira_ring_dtype,anira_ring_num_channels,anira_ring_available,anira_ring_available_past,anira_ring_pop_block,anira_ring_peek_past_block,anira_ring_push_block,anira_ring_push_fill,anira_ring_discard,anira_ring_pop_windows(a wrong dtype moves nothing and latchesANIRA_ERROR_CONFIG); the defaultsanira_processor_default_pre_process(the 2.x receptive-field fill) /anira_processor_default_post_process; a Streamed ring not moved by exactly its hop is repaired and latched (ANIRA_ERROR_CONFIG); a failed phase zeroes its chunk.C ABI, engine:
anira/abi/engine.h,anira_custom_engine_create,anira_custom_engine_destroy,anira_custom_engine_detach,anira_pipeline_add_engine: a refcountedanira_custom_engineunder a reverse-URI id, one more implementation the candidates resolve to, in any number of pipelines (C++Pipeline::add_engine(impl));anira_engine_desc(Tier 2,ANIRA_ENGINE_DESC_INIT):struct_size,abi_version,user_data,consumed_kinds/num_consumed_kinds(model:kinds read its own entries),flags(ANIRA_ENGINE_FLAG_NEEDS_NO_MODEL = 1u,ANIRA_ENGINE_FLAG_REALTIME_SAFE = 2u,ANIRA_ENGINE_FLAG_DYNAMIC_TIME = 4u,ANIRA_ENGINE_FLAG_STATE_ALIAS = 8u), eight slots,providers/num_providers,query.C ABI, engine: per-handler slots:
process(anira_engine_process_fn, required,[inference-thread],ANIRA_PHASE_INFERENCE, on the shared slotctx->instanceor, underANIRA_ENGINE_CALL_EXCLUSIVE, on the handler’s own executor; may block, must not allocate per call),reset(anira_engine_reset_fn, exclusive handlers, a new stream),prepare(anira_engine_prepare_fn,(info, loaded, user_data, out_prepared),[main-thread], building that executor underANIRA_PREPARE_EXCLUSIVE),unprepare(anira_engine_unprepare_fn); the prepares of one loaded model never overlap (Engine::Loaded::prepare,Loaded::prepare_mutex).C ABI, engine: per-object slots:
load(anira_engine_load_fn,(info, user_data, out_loaded),[main-thread]under the lifecycle lock, once per pooled loaded model, overanira_engine_load_info(ANIRA_ENGINE_LOAD_INFO_INIT: variant, row, engine-side templates and names,num_inputs,num_outputs,instances=max_instancesclamped to the pool or 0 when stateful, provider, options)),unload(anira_engine_unload_fn),init(anira_engine_init_fn, once per object before its first load, retried after a refusal),release(anira_engine_release_fn);load,unloadandinitmust not call an entry that takes the lifecycle lock.C ABI, engine:
anira_engine_ctx(Tier 1, 64 bytes,ANIRA_STRUCT_ENGINE_CTX = 12):instance(0 underANIRA_ENGINE_CALL_EXCLUSIVE = 1u),entry,num_inputs,num_outputs,ticket,flags,inputs,outputs,loaded(anira_engine_ctx.loaded,ctx->loaded); extents and handles come from each call’s tensors (anira_engine_ctx.inputs); a failedprocesslatchesANIRA_ERROR_ENGINEand zeroes the chunk; a throw across the boundary is undefined.C ABI, engine:
anira_custom_engine_create([main-thread]) copies id and descriptor;ANIRA_ERROR_INVALID_ARGUMENTfor NULLs, an id without.or startinganira.(exceptanira.v2.custom, the 2.x custom backend’s id, used by"CUSTOM"rows andanira/compat/v2.hpp), a shortstruct_size, an unknown flag or noprocess;ANIRA_ERROR_ABI_VERSIONperanira_check_abi; noreleaseon refusal;anira_pipeline_add_engine(a duplicate id isANIRA_ERROR_INVALID_STATE) holds a reference;anira_custom_engine_detachstops the handle keeping it alive.C ABI, engine: an entry with
ANIRA_ENGINE_CUSTOMand an added id (anira_model_config_add_model_path/_add_model_bytes) is a plan whose file only the engine reads; one engine object on an equal variant is one loaded model (stateful:instances0,ANIRA_PREPARE_EXCLUSIVE); a refused level fails the prepare, naming the engine and the level; several rows are several plans (anira_handler_set_plan); an id not added,anira.v2.customtoo, isANIRA_ERROR_NOT_SUPPORTEDatanira_handler_create; reports gainanira_plan_info.engine_flagsandanira_plan_slot.binding(anira_binding:ANIRA_BINDING_POSITION,ANIRA_BINDING_NAME,ANIRA_BINDING_ENGINE).C ABI, engine:
query(anira_engine_query_fn,(const anira_init_info* info, void* user_data, uint64_t* out_available),ANIRA_PHASE_QUERY = 12, main thread): a bitmask of the declared providers usable here (bit i =providers[i]; NULL: all);anira_handler_createasks once per engine and refuses a cleared provider (ANIRA_ERROR_NOT_SUPPORTED),anira_handler_preparereuses the answer; C++Engine::query(const InitInfo&).C ABI, engine: C++ (
anira/anira.hpp):anira::PrepareInfo(flags(),exclusive()),anira::EngineLoadInfo,anira::InitInfo;Engine::load(const EngineLoadInfo&)returnsstd::unique_ptr<Engine::Loaded>, whoseprepare(const PrepareInfo&)returnsstd::unique_ptr<Engine::Prepared>(process,reset;EngineContext::loaded());Processor::init(const InitInfo&)/Engine::init(const InitInfo&)are empty virtuals;anira::Enginetakes its id (explicit Engine(std::string id)); a bad id throwsANIRA_ERROR_INVALID_ARGUMENTat the first addition; an addition to a pipeline that already has the id throwsANIRA_ERROR_INVALID_STATE.C ABI, handler (
anira/abi/handler.h):anira_pipeline(anira_pipeline_create/add_inference/destroy: one stage and variant;anira_backend_idcandidates or, for NULL, every engine of the build on the CPU path plus the custom engines and pinned providers the entries name) andanira_handler(anira_handler_create,anira_handler_destroy);anira_handler_preparetakes a Hard contract, inits the processor, checks providers, loads, sizes rings, builds the plan report and publishes last (a racing call isANIRA_ERROR_NOT_PREPARED);anira_shutdownis refused while a handler lives; its test oracle matched the 2.xanira::InferenceHandlerbit for bit on the gain model and the CNN while that class lived.C ABI, handler: the plan report: Tier-2
anira_plan_info/anira_plan_slot/anira_plan_extviaanira_handler_plan_reportandanira_plan_report_num_plans/plans/slots/exts;anira_handler_set_plan/get_plan([thread-safe],InferenceManager::set_plan) set and read the dense plan index, not the backend, soanira_handler_get_plannames the running plan; a chunk keeps the plan it was submitted on.C ABI, handler: the Hard entries (
[driver-thread],ANIRA_NONBLOCKING) never wait:ANIRA_OK,ANIRA_MISSED(the miss policy filled the block, every Streamed count 0) or a failure; the_waittwins ([any-thread, blocking]) taketimeout_ms,ANIRA_WAIT_CONTRACT(wait_ratiotimes the block) orANIRA_WAIT_FOREVER, and areANIRA_ERROR_INVALID_STATEwithout an inference thread.C ABI, handler:
anira_handler_get_latency/get_latencies(0 if not Streamed),anira_handler_get_available_samples(a status and asize_t*; Static and State outputs too, as 2.xget_available_samples(0)),anira_handler_reset,anira_handler_rt_error(the last real-time failure, cleared by prepare and reset: contract violations,ANIRA_ERROR_NOT_SUPPORTED(anira::RtKind::NotSupported), processor and ring refusals,ANIRA_ERROR_ENGINE,ANIRA_ERROR_CAPACITYper dropped hop); prepare refuses Async contracts,ANIRA_BUDGET_MEASUREDandANIRA_WARMUP_UNTIL_STABLE(ANIRA_ERROR_NOT_SUPPORTED) and a ring dtype unlike the spec’s unless the processor fills that ring’s phase (ANIRA_ERROR_CONFIG).C ABI, handler: one plan per entry and candidate whose engine and provider the entry accepts (neutral: any; pinned: its pin), in entry, then candidate order (
onnxruntime:coremlplusonnxruntimeis two); entries are unique per (engine, id, pin); the default set puts a neutral entry on its engine’s home provider;anira_pipeline_add_inferencechecks a provider’s syntax (ANIRA_ERROR_INVALID_ARGUMENT),anira_handler_createits availability (ANIRA_ERROR_NOT_SUPPORTED); the provider is part of the loaded model, inanira_engine_load_info.provider/provider_id(C++EngineLoadInfo::provider(),anira::ProviderRef),anira_plan_info.provider/provider_id,anira_processor_ctx.provider;anira::Engine::providers()fills the descriptor’s list.C ABI, handler:
anira_plan_report_find(report, const anira_plan_query* query, uint32_t* plan): the first plan matching ananira_plan_query(Tier 2,ANIRA_STRUCT_PLAN_QUERY,ANIRA_PLAN_QUERY_INIT: a variant,ANIRA_VARIANT_ANY=0xffffffffufor all, and ananira_backend_id,ANIRA_ENGINE_NONE/ANIRA_PROVIDER_NONEfor all);[thread-safe],ANIRA_NONBLOCKING, allocation-free; no match isANIRA_ERROR_NOT_FOUND, a bad argumentANIRA_ERROR_INVALID_ARGUMENT; C++anira::PlanQuery(report.find({.backend = {.engine = ANIRA_ENGINE_ONNXRUNTIME, .provider = ANIRA_PROVIDER_COREML}})),PlanReport::find(const PlanQuery&) const noexceptreturningstd::optional<uint32_t>.C ABI, handler: each successful
anira_handler_preparelogs its plan report at Info (groupanira.capi): a head line, then a record per plan, slot and consumed extension; visible atANIRA_LOG_INFO/ANIRA_LOG_DEBUG, compiled out underANIRA_WITH_LOGGING=OFF.C ABI, handler: the Hard entries over host tensors:
anira_handler_process(handler, in, in_slot, out, out_slot, delivered),anira_handler_process_multi,anira_handler_push_data,anira_handler_push_data_multi,anira_handler_pop_data,anira_handler_pop_data_multiand the_waittwinsanira_handler_process_wait,process_multi_wait,anira_handler_pop_data_wait,pop_data_multi_wait(plusdouble timeout_ms); no float-only family (wrap channel pointers withanira_tensor_init_host_planar), no_inplacevariant (pass one tensor twice).C ABI, handler: one slot space: a slot is the tensor’s position in its model-config list, State included, in every entry,
anira_miss_fn,anira_handler_get_latencies, the plan report andanira_processor_input_role,anira_processor_input_ring,anira_processor_input_tensorand twins; Streamed slots take block calls, Static onesanira_handler_set_static_input/anira_handler_get_static_outputor a_multielement, State ones none, elseANIRA_ERROR_INVALID_ARGUMENT;anira_plan_slot.rolegives the slot’sanira_role.C ABI, handler: host tensors: one
const anira_tensor*per slot, never written; a Streamed slot is[channels, samples], planar (ANIRA_TENSOR_PLANAR), interleaved ({1, channels}) or packed, any channel count, copied straight between host memory and the ring; another dtype isANIRA_ERROR_CONFIG, a malformed descriptor (rank, a domain butANIRA_DOMAIN_HOST/ANIRA_DOMAIN_HOST_PINNED, anANIRA_TENSOR_READ_ONLYoutput,shape[0], memory, strides)ANIRA_ERROR_INVALID_ARGUMENT, an unknown flagANIRA_ERROR_NOT_SUPPORTED; an empty tensor skips its slot (tests: the privateanira::PlanarFloatAdapter).C ABI, handler: the
_multiforms take one tensor per slot (other counts areANIRA_ERROR_INVALID_ARGUMENT; empty at State slots) and meanset_static_inputper non-empty Static input, the streamed call,get_static_outputper non-empty Static output, all validated first;delivered(nullable, always written): a Streamed output’sshape[1]onANIRA_OKand 0 onANIRA_MISSED, a carried Static output’s element count on both (0 for an empty element), 0 for a State slot and everywhere on a refusal; after a_waittwin’sANIRA_ERROR_INVALID_STATE, what the nonblocking entry delivered.C ABI, handler:
ANIRA_MISS_CALLBACK = 3(anira_miss_policy,"on_miss": "callback") withanira_contract_hard_set_miss_fn(anira/abi/config.hnow includesanira/abi/tensor.h;ANIRA_ERROR_WRONG_CONTRACTon Async) andanira_miss_fn(ANIRA_CALL,(handler, inputs, num_inputs, outputs, num_outputs, user_data)toanira_status, the firstANIRA_NONBLOCKINGfunction-pointer typedef): once per missed block or dropped hop over the call’s own arrays, Static outputs prefilled; a non-ANIRA_OKreturn zero-fills; the entry returnsANIRA_MISSED; it must not call the handler’s Hard entries,anira_handler_resetoranira_handler_prepare; a NULLfnclears the pair, which must outlive the prepared handler; a contract parsed from a file cannot carry it, so set it on the parsed contract; without a functionanira_handler_prepareisANIRA_ERROR_CONFIG, and it refusesANIRA_MISS_BYPASSacross differing ring dtypes.C ABI, handler:
anira_handler_set_static_input(handler, slot, tensor)/anira_handler_get_static_output([driver-thread],ANIRA_NONBLOCKING): whole Static tensors in the spec’s shape and dtype (ANIRA_DOMAIN_HOST_PINNEDtoo) in a tear-free store zeroed atanira_handler_create, kept through prepare and reset; inputs reach chunks beforepre_process, outputs are captured afterpost_process(not from zeroed chunks) and hold underANIRA_MISS_ZEROS,ANIRA_MISS_HOLD_LAST,ANIRA_MISS_BYPASS; refusals (ANIRA_ERROR_INVALID_ARGUMENTfor a bad slot, shape, memory or anANIRA_TENSOR_READ_ONLYoutput,ANIRA_ERROR_NOT_SUPPORTEDforANIRA_TENSOR_PLANAR,ANIRA_ERROR_CONFIGfor dtype) latch inanira_handler_rt_error; a Buffer spec under Hard isANIRA_ERROR_NOT_SUPPORTEDatanira_handler_prepare; non-float32 specs stay refused.C ABI, handler: declared state: both halves of a pair carry
ANIRA_ROLE_STATE = 3("role": "state"), and the input names its output ("state_source"oranira_tensor_spec_set_state_source(spec, output_canonical), likeanira_tensor_spec_set_latency:ANIRA_ERROR_INVALID_ARGUMENToff a State spec,ANIRA_ERROR_JSONon an output;anira_model_config_to_jsonwrites it); anira runs the feedback over two handler-owned buffers per pair, zeroed atanira_handler_create,anira_handler_prepareandanira_handler_reset, flipped after each good inference (anira copies nothing; each engine binds the buffers as it binds any slot); the model runs asANIRA_MODEL_STATEFUL; the state survivesanira_handler_set_plan.C ABI, handler:
before_inferencesees the read half (anira_processor_input_tensor),after_inferencethe write half (anira_processor_output_tensor); underANIRA_ENGINE_FLAG_STATE_ALIASone stable buffer is both halves; the buffers are host memory in this pre-release (a non-hostanira_contract_set_host_domaindeclaration staysANIRA_ERROR_NOT_SUPPORTED); a reset zeroes the state at the new stream’s first inference and runs bothresetslots (TFLite resets its variable tensors);ANIRA_ERROR_CONFIGat create and prepare for a bad or missing source, an unpaired State output, unequal halves, or a Time axis, window, time ratio, latency, ring dtype or anchor on a State spec; a transposed layout isANIRA_ERROR_NOT_SUPPORTED; non-float32 pairs run on registered engines only.C ABI, Emscripten companion (
anira/anira_em.h):anira/anira_em.h(empty off Emscripten): JavaScript processors, engines and the log go through the calling scope’s registryglobalThis[Symbol.for('anira.registry')]({ version, processor(Module, key, phase, a, b), engine(Module, key, phase, a, b, idPtr), log(Module, recordPtr), boot(Module) },ANIRA_EM_HOOKS_VERSION2), neverModule.anira;anira_em_processor_desc_init(desc, js_key, hook_mask, processor_flags)fills ananira_processor_descwith a trampoline per hook bit (ANIRA_EM_PROCESSOR_HOOK_*=1u << ANIRA_PHASE_*bystatic_assert:ANIRA_EM_PROCESSOR_HOOK_PRE1,ANIRA_EM_PROCESSOR_HOOK_AFTER16 =anira::Processor::k_after_inference,ANIRA_EM_PROCESSOR_HOOK_PREPARE32, …) andanira_em_pipeline_add_js_processor(pipeline, js_key, hook_mask, processor_flags, err)adds one.C ABI, Emscripten companion:
anira_em_engine_desc_initfills ananira_engine_desc(process, plusreset/querybyANIRA_EM_ENGINE_HOOK_RESET1 /_QUERY2) andanira_em_pipeline_add_js_enginecreates and adds it; a throwing hook is logged withconsole.error(rate-limited) and fails the call (ANIRA_ERROR_UNKNOWNfor a processor,ANIRA_ERROR_ENGINEfor an engine);anira_em_set_log_hookadds the registry’slogas a sink.Engines: ONNX Runtime, LiteRT and ExecuTorch take the plan’s provider; TFLite and LibTorch serve the CPU path alone and say why (
Loaded::serves,Loaded::provider_reason); ONNX Runtime appends a providerOrt::GetAvailableProviders()lists (never Vulkan) ahead of the CPU one, a refused append beingANIRA_ERROR_NOT_SUPPORTED; LiteRT takes an accelerator by hardware name asANIRA_PROVIDER_CUSTOM("gpu","npu", on the web"webnn"); ExecuTorch serves registered delegates that reportis_available, and a pinned export whose method lacks its delegate isANIRA_ERROR_CONFIGat load.Web: the TypeScript layer mirrors
anira.hppin camelCase except where the platform forces it (Anira.create, the worker module,Context.ready, the audio node,measureRenderGeometry,fromUrl, the MANUAL drain and log pump, the per-realm registry,destroy(), a thrownAniraError);InferenceHandler.prepare(contract)/audioNode.prepare(contract)return thePlanReport(numPlans(),plans(),slots(plan, inputs),extensions(plan),native(), asanira::PlanReport; again viaplanReport()), so create, then prepare; newrtError(),setPlan(plan)/getPlan(),numEntries(),handler.getLatencies()besidehandler.getLatency(slot);setStaticInputtakes the spec’s dtype.Extras and examples:
extras/models/hybrid-nn/HybridNNProcessor.h(HybridNNProcessor, ananira::Processorpopping its windows with oneRingView::pop_windows),extras/models/BypassEngine.h(BypassEngine,org.anira.examples.bypass,ANIRA_ENGINE_FLAG_NEEDS_NO_MODEL) andexamples/benchmark/advanced-benchmark/ClearEngine.h(ClearEngine,org.anira.examples.clear, zeros: the advanced benchmark’s baseline); the CNN needs no processor (anira’s default fill replacesCNNPrePostProcessor).ABI tooling and gates: presence gates
anira_abi_link(every promised and draft entry point links againstanira::anira),anira_symbol_baseline(exactly those names exported) and the WebAssembly link; sanitizer legs run in the merge queue.ABI tooling and gates: gate 6, seeded:
anira_abi_rt_contract, oneANIRA_NONBLOCKINGC function calling every[callback-safe]tensor entry under-Werror=function-effects(clang 20+).ABI tooling and gates: generated
layout.ts: size, alignment and member offsets of the Tier-1 records under their C names (anira_tensor.fields.handle.fields.host.fields.ptr.offset),ANIRA_PTRslots marked.C++ (
anira/anira.hpp, not ABI-stable):anira::Context(overanira_context_create, from ananira::ContextConfig;capabilities(),probe(),byte_image_bytes()),anira::Capabilities(edge()throwsANIRA_ERROR_EDGE_UNREACHABLE),anira::BackendId,anira::enabled_engines(),anira::now_ms()/now_ns(), the freeanira::drain_log()/anira::num_inference_threads(),anira::shutdown()/release_core_if_idle()/has_core();anira::Contextwas alpha.1’s 2.x singleton.C++ (
anira/anira.hpp, not ABI-stable):anira::Tensor/anira::SyncToken(aTensor*is ananira_tensor*,static_asserted):noexceptfactoriesTensor::from_host/from_pinned/from_cuda/from_gl_buffer/from_vulkan/from_opaque_fd/from_wgpu_buffer/from_dmabuf(the all-zero record on refusal, also pastANIRA_MAX_RANK),Tensor::from_dlpack(throwsanira::Error),Tensor::from_host_planar<T>(a const element setsANIRA_TENSOR_READ_ONLY),data_f32(),data(DType),num_elements();SyncTokenis not RAII. Draft factories stay C (anira_tensor_init_metalon aTensor); noanira_all.hpp.C++ (
anira/anira.hpp, not ABI-stable):anira::Pipeline(move-only, overanira_pipeline_create, one chaining member per C entry:p.add_engine(e).add_inference(model).add_processor(s);) andanira::PlanReport(rows as vectors, noto_json);add_inference(model, {candidates})takesBackendIds (multi-variant:ANIRA_ERROR_NOT_SUPPORTED),add_processor(std::shared_ptr<Processor>)the one custom processor,add_engine(std::shared_ptr<Engine>)a custom engine.C++ (
anira/anira.hpp, not ABI-stable):anira::InferenceHandler(Context&, const Pipeline&)overanira_handler:prepare(Hard | Async | Contract | ContractHandle)returning thePlanReport,plan_report(),num_entries(), thenoexcept ANIRA_NONBLOCKINGHard forwarders overTensor(process,push_data,pop_data,process_wait,pop_data_wait; planar floats viaTensor::from_host_planar),set_static_input(slot, const Tensor&)/get_static_output,get_latency(slot),get_latencies(),get_available_samples,reset,rt_error,set_plan/get_plan(in place ofset_model/set_backend: select a plan of the report);anira::InferenceThread(Context&)overanira_inference_threadfor a context without pool threads (start,stop,execute,run_loop,should_exit,is_running,has_exited);anira::log_rt. Both names were alpha.1’s 2.x classes.C++ (
anira/anira.hpp, not ABI-stable): custom processors overanira/abi/processor.h:anira::Processor(phases()ofProcessor::k_pre_process,k_post_process,k_before_inference,k_after_inference,Processor::phase_bit(phase)into theanira_processor_desc;flags()intoanira_processor_desc::flags, a Hardpre_process/post_processneedingANIRA_PROCESSOR_FLAG_REALTIME_PRE_POST(elseANIRA_ERROR_CONFIGatanira_handler_prepare), andANIRA_PROCESSOR_FLAG_REALTIME_HOOKS;consumed_kinds(),init(const InitInfo&),Processor::prepare(const PrepareInfo&)to astd::unique_ptr<Processor::Prepared>),anira::Processor::Prepared(noexceptpre_process,post_process,before_inference,after_inferenceon aProcessorContext&to ananira_status, andnoexceptreset(ProcessorContext&); defaultsanira_processor_default_pre_process/anira_processor_default_post_process),anira::PrepareInfo(anira_prepare_info:handler()ananira_handler*,num_entries(),input_names(),output_names(),exclusive()forANIRA_PREPARE_EXCLUSIVE),anira::InitInfo(anira_init_info:log_level()ananira_log_level,num_threads(),context()ananira_context*),anira::ProcessorContext(anira_processor_ctx:phase(),engine(),provider(),variant(),ticket(),num_inputs(),num_outputs(),entry()belowanira_handler_num_entries,input_role(slot, Role&),output_role,input_ring(slot, RingView&),output_ring,input_tensor(slot, Tensor&),output_tensor),anira::RingView(anira_ringoverstd::span<T>byanira_dtype;pop_windows),anira::Pipeline::add_processor(std::make_shared<MyProcessor>())(astd::shared_ptr<Processor>asuser_data, anout_preparedper handler; a second isANIRA_ERROR_INVALID_STATE, bad bits or nullANIRA_ERROR_INVALID_ARGUMENT),anira::TensorSpec::state_source(output_canonical)(anira_tensor_spec_set_state_source). A throw fails the prepare with theanira::Error’s status,ANIRA_ERROR_OUT_OF_MEMORY(std::bad_alloc) orANIRA_ERROR_INTERNAL.C++ (
anira/anira.hpp, not ABI-stable): custom engines overanira/abi/engine.h:anira::Engine(explicit Engine(std::string id),id(), named byModelConfig::add_model_path(id, path), anANIRA_ENGINE_CUSTOMplan with every slotANIRA_BINDING_ENGINE;flags()fromANIRA_ENGINE_FLAG_*intoanira_engine_desc::flagsandanira_plan_info::engine_flags;consumed_kinds(),init(const InitInfo&),load(const EngineLoadInfo&)([main-thread], once per pooled model) to astd::unique_ptr<Engine::Loaded>),anira::Engine::Loaded(prepare(const PrepareInfo&)to astd::unique_ptr<Engine::Prepared>),anira::Engine::Prepared(noexceptprocess(EngineContext&),reset(EngineContext&)),anira::EngineLoadInfo(anira_engine_load_info:model()ananira_model_config*,model_count(),model_engine(i)ananira::EngineRef,model_path(i),model_bytes(i),input_names(),output_names()),anira::EngineContext(anira_engine_ctx:instance(),exclusive()forANIRA_ENGINE_CALL_EXCLUSIVE,outputs()asstd::span<Tensor>), the enumEngineKind,anira::Pipeline::add_engine(std::make_shared<MyEngine>()), whose first call creates the object’sanira_custom_engine(anira_custom_engine_create, thestd::shared_ptr<Engine>asuser_data,out_loadedper pooled model) and later calls reuse it while anything holds it (a detached handle,anira_custom_engine_detach, that keeps nothing alive; after the C engine’s release an addition creates a fresh one). Throws map as for processors;add_enginerefuses a null engine, an id without a.or prefixedanira.and aflags()bit outsideanira/abi/enums.h(ANIRA_ERROR_INVALID_ARGUMENT) and an id the pipeline already has (anira_pipeline_add_engine:ANIRA_ERROR_INVALID_STATE).C++ (
anira/anira.hpp, not ABI-stable): read-back overanira/abi/config.h:anira::SpecView(every spec field,time_ratio(),state_source(),{ANIRA_AXIS_ANY, 0}for a hole) fromTensorSpec::view()andModelConfig::input_spec(i)/output_spec(i);ModelConfig::input_count(),output_count(),default_engine(),max_instances(),tensor_name(i, canonical),tensor_layout(i, canonical),model_ext<Ext>(i)(std::optional<Ext>, by the extension’sk_kind), indexed onesANIRA_ERROR_INVALID_ARGUMENTout of range.anira::Hardgainsanira::Hard::miss_fn/miss_user_dataafteron_miss(anira_contract_hard_set_miss_fn,ANIRA_NONBLOCKING, called on the driver thread; it and whatmiss_user_datapoints at outlive the prepared handler) andring_dtypes(std::map<std::string, DType>) / latencies betweenwait_ratioandedge_cost(anira_contract_hard_set_ring_dtype/anira_contract_hard_set_latency);anira::ContractHandle::hard_miss_fn(fn, user_data),hard_latency(canonical, samples)besidehard_ring_dtype;ContractHandle::hard()reads any Hard handle (take_legacy_contract’s, a loaded one) back, ananira::Budgetrounded to the nanosecond, not a truncatingduration_cast(ANIRA_ERROR_WRONG_CONTRACTon Async).C++ (
anira/anira.hpp, not ABI-stable): the provider beside the engine:ModelConfig::default_provider(provider)/default_provider(name)/default_provider(),ModelConfig::model_provider(i)/model_provider(i, provider)/model_provider(i, name); pair getters returnanira::EngineRef{kind, id}/anira::ProviderRef{kind, id}(idfor CUSTOM only):model_engine(i),default_engine(),EngineLoadInfo::model_engine(i),ProcessorContext::engine()and their provider twins.Compat (
anira/compat/v2.hpp, C++ header-only):namespace anira::v2, the v2.3.0 names overanira/abi(C++20), included in place of<anira/anira.h>, withusing namespace anira::v2;:InferenceBackend(anira_enginevalues;to_engine/to_backend/is_available;CUSTOMisANIRA_ENGINE_CUSTOMwithk_custom_engine_id"anira.v2.custom"),ModelData,TensorShape,ProcessingSpec,InferenceConfig(viaanira::ModelConfig::from_json;model_config(),model_config_copy()),JsonConfigLoader,ContextConfig(to_context_config()),HostConfig,LogConfig,RingBuffer,BufferF,PrePostProcessor,LegacyProcessor(a 2.x processor as ananira::Processor),PassthroughEngine(BackendBase::processas ananira::Engine,anira.v2.custom) andInferenceHandler(every 2.x member over oneanira_handler, on ananira::Engine&or thePassthroughEngine).anira::v2::InferenceHandler::preparetakes a fractionalHostConfig::m_buffer_size(host_block_minhalf the block when smaller blocks come and the block is one sample or less), a non-finite or non-positive one isANIRA_ERROR_CONFIG;InferenceHandler::set_inference_backend/get_inference_backendrun while audio runs, never duringprepare()or the destructor, asanira_handler_set_plan(#202). The migration page lists the differences from 2.x (anira::Error, no load beforeprepare, non-waitingpush_data).Web (module,
anira/anira_em.h): inference threads are Wasm Workers, soanira_context_config_set_threadsandANIRA_THREADS_AUTO(half the cores) size a real pool andanira_inference_thread_startstarts a Worker;anira_em_context_config_set_worker_module(config, url, err)names their module (the first context’s wins) and a page waits foranira_em_inference_threads_in_loop()before waiting on the main thread. Idle Workers park for at most 5 ms instead of spinning; a stop during boot leaks nothing.Web (module,
anira/anira_em.h): the audio path in C:anira_em_audio_node_create(handler, audio_context, input_slots, num_input_slots, output_slots, num_output_slots, param_slots, num_param_slots, tensor_slots, num_tensor_slots, flags, wait_ms, out_status, out_node, err), a Wasm Audio Worklet node of a prepared Hard handler,out_statusANIRA_INCOMPLETEuntil created, input / output k serves the k-th listed slot (NULL for a side: every Streamed slot in slot order), one copy-freeanira_handler_process_multiper quantum (asanira_handler_processadvises);ANIRA_MISSEDkeeps the miss fill. Refused: a block range without the quantum, a non-Streamed or repeated slot, a non-float32 ring, an unserved Streamed slot (unlessANIRA_EM_AUDIO_NODE_FLAG_PARTIAL_STREAMS). Static float32 scalars are AudioParams, other Static tensors go throughanira_em_audio_node_set_static_inputtoanira_handler_set_static_input;anira_em_audio_node_hold,anira_em_audio_node_prepare(while a node streams,anira_handler_prepareisANIRA_ERROR_INVALID_STATE),anira_em_audio_node_destroy; exportsemscriptenGetAudioObject.Web (module, build): the glue runs under Vite’s dev server: a post-link step of
AniraWebroutesnew Worker(new URL("AniraWeb.js", import.meta.url))throughlocateFileand marks the Wasm Workers’ import@vite-ignore.Web (package,
@anira-project/anira): the typed layer, mirroringanira.hppin camelCase:Anira.create({ memory, wasmBinary, abiVersion })(setLogSink,drainLog,startLogPump),Context.create(anira, { threads, workerModule, logLevel, json })(numInferenceThreads(); defaultANIRA_THREADS_AUTO),Pipeline.create(anira).addInference(models).addEngine(id, { flags, hooks }).addProcessor(name, { phases, flags })(ANIRA_EM_PROCESSOR_HOOK_*phases,ANIRA_PROCESSOR_FLAG_*flags),InferenceHandler.create(context, pipeline)(prepare(contract)returning thePlanReport,getLatency,setStaticInput,createAudioNode),ModelConfig,ContractHandle,defineProcessor(Processor,ProcessorFactory,ProcessorOptions,Registry.defineProcessor,Registry.processor,registry.processor),defineEngine,keyOf,engineTensors.Web (package,
@anira-project/anira): generatedAniraBindings, one typed method per module entry point under its C name, throwing a failedanira_statusas anAniraError(viaanira_error), ananira_boolas a boolean;anira.abiis the main instance’s, a scope’s is in itsScopeEnv. The module exportsstringToUTF8OnStack,lengthBytesUTF8,stackAlloc,HEAPU8,HEAP32,HEAPF64,HEAP64,HEAPU64.Web (package,
@anira-project/anira): one model config for native and web:ModelConfig.fromUrl(anira, url)parses a*.model.json(anira_model_config_from_json) and attaches the files of entries whose engine is inanira_enabled_engines(enabledEngines) or custom (anira_model_config_set_model_bytes);fetchModel, aFetcher,fromJson(withbaseUrl),setModelBytes,toJson.ContractHandle.fromUrl/fromJsonread a*.contract.json(anira_contract_from_json),ContractHandle.hard(anira, { hostBlockMin, hostBlockMax, hostRate, budgetMs, warmupIterations })builds one,hardHostBlocksfills open host blocks;extras/models/model-pool/gain.model.json/gain.contract.jsonload unchanged.Web (package,
@anira-project/anira; decision 10.19):PlanReport.find(query?)overanira_plan_report_findwith aPlanQuery({ variant?, engine?, engineId?, provider?, providerId? },anira::PlanQueryflattened, ananira_plan_queryon the stack; an omitted field matches every plan:ANIRA_VARIANT_ANY,ANIRA_ENGINE_NONE,ANIRA_PROVIDER_NONE), returning theInferenceHandler.setPlanindex or null (ANIRA_ERROR_NOT_FOUND), anAniraError(ANIRA_ERROR_INVALID_ARGUMENT) against the pair rule.Pipeline.addEnginecallsanira_em_pipeline_add_js_engine.Web (package,
@anira-project/anira):handler.createAudioNode(audioContext, options)/createAudioNodereturns anAniraAudioNode(node,params,setStaticInput,prepare,hold,destroy) on anyBaseAudioContext; optionsinputSlots/outputSlots(default every Streamed slot of the side, so a single-stream model needs neither),partialStreams,params,staticInputs,waitMs,workletModules,timeoutMs; the per-context setup (emscriptenRegisterAudioObject) is onePromiseshared by concurrent creations.Web (package,
@anira-project/anira):measureRenderGeometry(context, { hold? }): a Hard contract’s geometry behind an audio node, never frombaseLatency:quantum(renderQuantumSize, else 128; a"hardware"context reporting 0 is refused) and the measuredburst(a probeAudioWorkleton anAudioContext, timed withperformance.now()by a Worker woken throughAtomics.wait, not the worklet’sDate.now), holding the listedAniraAudioNodes meanwhile (AniraAudioNode.hold). Nothing re-prepares on its own: after a device change, re-measure and re-prepare through the node (handler.prepareis refused while it streams).Web (package,
@anira-project/anira): a JavaScript engine gets its entry’s model, fetched once:engineModel(env, prepared)returns what the C load read (anira_model_config_model_path, the bytes as aUint8Arrayview), and an optionalload(model)hook runs per Worker before a loaded model’s first call;ModelConfig.fromUrlattaches its bytes.Web (ONNX Runtime Web engine,
@anira-project/anira/engines/onnxruntime-web):defineEngine(ONNXRUNTIME_WEB_ENGINE_ID, onnxRuntimeWeb({ model }))(org.anira.onnxruntime-web), a worker-module factory replacing alpha.1’sONNXRuntimeWebBackend: withoutmodelthe session comes from the entry’s bytes, with it from a fetch at init (fetchModel: () => falseonModelConfig.fromUrlthen);warmupinferences over zeros (default 0; a contract’s warm-up skips JavaScript engines);numThreadsintra-op threads (default 1; one_OrtInit(numThreads)per runtime: an engine asking for another count than its worker module’s fails itsinit, as does a count that is not a whole number of at least 1; native: #222).ONNXRUNTIME_WEB_ENGINE_IDhas its own module, so naming the engine does not bundle onnxruntime-web.Web (tests and CI): the ABI gates on WebAssembly:
ANIRA_WITH_ABI_TESTS(default OFF) adds the ABI tests alone, and the presetwasm-abi(wasm-releaseplus it) builds the header, layout and smoke gates, whichanira_abi_wasm_gatesruns under node (the smoke driven byanira_inference_thread_execute; a user Worker runninganira_inference_thread_run_loopwhile main callsanira_handler_process_wait);build_webalso checks every registry symbol,_mallocand_freeare exported. A throwing JavaScript hook prints at most oneconsole.errorper second per module instance.Web (tests and CI): a browser test of the built package: every feature’s page (
live.htmlin Chromium only) and the examples’ check pages (built; processor-and-engine’s also under Vite’s dev server) in headless Chromium and Firefox (Playwright 1.64.1); a refused load fails a page.Web (tests and CI): the package’s unit tests run under node’s type stripping, no build needed.
Web (docs and examples): two examples, type-checked, built and run in CI and included by the guides:
web/examples/processor-and-engine/(adefineProcessorgain processor with an allocation-freepreProcess, a doublingdefineEngineworker module) andweb/examples/model-file/(extras/models/model-pool/gain.model.jsonand its contract on the built-in ONNX Runtime engine).ABI gates:
anira_abi_namespaces: over every symbol of libanira, local ones included, it fails on athlsymbol outsidethl::anira, a moodycamel one outsideanira_moodycamel, or nothl::anirasymbol at all.ABI gates: gate 5, the installed package from C and beside a host’s tanh-lib:
consumer_c(C11,anira_check_abitoanira_shutdown, anANIRA_ENGINE_FLAG_NEEDS_NO_MODELengine, oneanira_handler_process) andconsumer_tanh_first(a host’s own shared tanh-lib linked first: itsthl::Loggerand anira’s sink never share a record, and a shared libanira exports no thl symbol), on every leg, shared and static; the engine-module export scan forbidsanira_*entries.ABI gates: gate 6’s compile-time half:
-Werror=function-effects(clang 20+) on the C header gate,anira_abi_link,anira_abi_rt_contractandconsumer_c; thedesktop-tests-rtsanpreset is the run-time half.Bundled models: the State fixture
extras/models/model-pool/stateful_accumulator.model.json/.contract.json(also inextras/models/model_files.h;extras/fetch-models.cmakepind1bc5cf): example-models’StatefulAccumulatorNetwork, a stereo 64-sample stream with a declared State pair ("role": "state","state_source": "state_out") and a closed form, also afteranira_handler_resetand warm-up; a row per engine (five).
Changed#
Breaking: C ABI —
<anira/anira.h>is the C11 umbrella ofanira/abi/, not alpha.1’s 2.x C++ classes. Migration: 2.x code includes<anira/compat/v2.hpp>(anira::v2::), 3.x C++<anira/anira.hpp>.Breaking: C ABI —
anira_stage_phase/ANIRA_STAGE_PHASE_FORCE32isanira_phase/ANIRA_PHASE_FORCE32:ANIRA_PHASE_PRE_PROCESS0,ANIRA_PHASE_POST_PROCESS1,ANIRA_PHASE_BEFORE_INFERENCE2, newANIRA_PHASE_INFERENCE3 (the engine call),ANIRA_PHASE_AFTER_INFERENCE4 (was 3),ANIRA_PHASE_PREPARE5 (was 4),ANIRA_PHASE_RELEASE6 (was 5), newANIRA_PHASE_RESET7,ANIRA_PHASE_UNPREPARE8,ANIRA_PHASE_INIT9,ANIRA_PHASE_LOAD10,ANIRA_PHASE_UNLOAD11,ANIRA_PHASE_QUERY12, inanira_processor_ctx.phase(side-neutral likeanira_init_info,anira_prepare_info). Migration: spellanira_phase(anira::ProcessorContext::phase(),anira::Processor::phase_bit), rebuild againstanira/abi/enums.h.Breaking: C ABI —
anira_engineandanira_providershare one order:ANIRA_ENGINE_NONE0,ANIRA_ENGINE_ONNXRUNTIME1,ANIRA_ENGINE_EXECUTORCH2 (was 5),ANIRA_ENGINE_LITERT3 (was 4),ANIRA_ENGINE_LIBTORCH4 (was 2),ANIRA_ENGINE_TFLITE5 (was 3); newANIRA_PROVIDER_NONE0 andANIRA_PROVIDER_CPU1,ANIRA_PROVIDER_CUDA2 (was 1),ANIRA_PROVIDER_WEBGPU3 (was 2),ANIRA_PROVIDER_VULKAN4 (was 6),ANIRA_PROVIDER_DIRECTML5 (was 3),ANIRA_PROVIDER_COREML6 (was 4),ANIRA_PROVIDER_XNNPACK7 (was 5);ANIRA_ENGINE_CUSTOM/ANIRA_PROVIDER_CUSTOMare0x7FFFFFFE;ANIRA_PROVIDER_DEFAULTis removed; the 2.xanira::InferenceBackendkeeps its values. Migration: rebuild; map stored numbers by name.Breaking: C ABI —
ANIRA_PROVIDER_NONEis no provider, the zero ofANIRA_BACKEND_ID_INIT,ANIRA_PLAN_INFO_INIT,ANIRA_EDGE_INFO_INIT,ANIRA_PROVIDER_OPTION_SET_INIT(unpins inanira_model_config_set_model_provider, clears inanira_model_config_set_default_provider,ANIRA_ERROR_INVALID_ARGUMENTas a candidate or in a provider option set);ANIRA_PROVIDER_CPU("cpu") is the plain CPU path, each built-in engine’s first row, asanira_plan_infoandanira_engine_load_inforeport it. Default candidates: every engine on CPU, each named custom engine, every pin (an unservable plan is dropped, a variant without one isANIRA_ERROR_CONFIG); a custom engine serves what it lists (none: CPU);"default"/"none"are refused as"provider"/"default_provider"and in a descriptor’s providers list. Migration:ANIRA_PROVIDER_DEFAULTisANIRA_PROVIDER_CPU, orANIRA_PROVIDER_NONEfor no default (JSON: no key); an_INITor zeroed candidate setsANIRA_PROVIDER_CPU; a custom engine that relied on the default provider lists"cpu";anira::ProviderRef{}andProviderOptions::Set{}start at NONE.Breaking: C ABI — one pair rule: wherever an engine or provider is named (
anira_backend_id,anira_edge_info,anira_provider_option_set, the plan, load and processor records, entries) the id is non-NULL iff the value isANIRA_ENGINE_CUSTOM/ANIRA_PROVIDER_CUSTOM(alpha.1:ANIRA_ENGINE_NONEplus id), elseANIRA_ERROR_INVALID_ARGUMENT, also inanira_pipeline_add_inference;anira_enabled_enginesnever lists CUSTOM.anira_model_config_add_model_path(config, engine, engine_id, path, out_index, err)(wasutf8_path, no id),anira_model_config_add_model_bytesandanira_model_config_set_default_engine(gainsanira_error*) take the pair, replacinganira_model_config_add_model_path_custom,anira_model_config_add_model_bytes_custom,anira_model_config_set_default_engine_custom;anira_model_config_model_engine(absorbinganira_model_config_model_engine_id) and the newanira_model_config_default_engine,anira_model_config_model_provider(config, model_index, &provider, &provider_id),anira_model_config_default_provider,anira_processor_engine,anira_processor_providerreturn a status and write the pair onANIRA_OK. C++: the getters (model_engine,default_engine,model_provider,default_provider,EngineLoadInfo,ProcessorContext) returnanira::EngineRef/anira::ProviderRef,model_engine_idand every*_id()getter go,add_model_path/add_model_byteskeep their overloads. Migration:_custom(cfg, id, ...)is the plain entry withANIRA_ENGINE_CUSTOM, id(built-ins passNULL); a candidate{ANIRA_ENGINE_NONE, NULL}does not stand for every custom entry: name each custom engine by its id; C++ readsmodel_engine(i).id.Breaking: C ABI — the core’s handle is the context:
anira_machine_config/anira_machineareanira_context_config/anira_context, eachanira_machine_config_*entry ofanira/abi/config.h(anira_machine_config_create,anira_machine_config_set_threads,anira_machine_config_set_log_level,anira_machine_config_set_log_drain,anira_machine_config_set_log_queue_capacity,anira_machine_config_set_log_flags,anira_machine_config_set_log_sink,anira_machine_config_set_log,anira_machine_config_set_cuda,anira_machine_config_set_gl,anira_machine_config_set_vulkan,anira_machine_config_set_metal,anira_machine_config_set_d3d12,anira_machine_config_set_webgpu,anira_machine_config_set_ext,anira_machine_config_set_ext_json,anira_machine_config_destroy,anira_machine_config_from_json,anira_machine_config_to_json) its same-parameteranira_context_config_*twin (anira_context_config_create,anira_context_config_destroy,anira_context_config_from_json,anira_context_config_to_json, …),anira_inference_thread_createtakes ananira_context*(new:anira_context_create,byte_image_bytesand the rest ofanira/abi/context.h),anira/anira.hpp’sMachineConfigisContextConfig(runtimeContext), the machine file the context file. Migration:machinebecomescontext.Breaking: C ABI — the Hard geometry is the host blocks (
double, anchor elements peranira_model_config_set_anchor;wait_ratiounchanged):anira_contract_create_hardtakeshost_block_min,host_block_max,host_rate(wereuint32_tblock_min,block_maxanddoublerate),anira_contract_hard_set_geometryisanira_contract_hard_set_host_blocks, the newanira_contract_hard_host_blocksreads them back,anira::Hard::block_min/block_max/rateareanira::Hard::host_block_min/host_block_max/host_rate,anira::ContractHandle::hard_geometryisContractHandle::hard_host_blocks, and the"hard"keys"block_min","block_max","rate"are"host_block_min","host_block_max","host_rate"(old keysANIRA_ERROR_JSON);host_block_min = 0beside a non-zero maximum is refused. Migration: rename (contract.hard_host_blocks(1, samplesPerBlock, sampleRate)); a fixed block setshost_block_min = host_block_max;HostConfigand the web’smeasureRenderGeometrykeep their names.Breaking: C ABI — the elements kept from the previous window are the overlap (alpha.1: context): the model file key
"overlap"replaces"context"(now unknown, failing prepare);anira::TensorSpec::window(min, max, overlap),anira_tensor_spec_set_window(spec, window_min, window_max, overlap)andanira_model_config_set_tensor_name(config, model_index, canonical, export_name)rename a parameter (wascontext,engine_name). Migration: rename the key.Breaking: C ABI — flexible windows follow one anchor hop per model (alpha.1: each from
host_block_max), the largest that fits every window (window_min,window_max) and time ratio at or belowhost_block_max(LatencyCalculator::rationalize, rounded down), else the smallest; a flexible window without a ratio now follows the anchor hop (a fixed anchor of 2048 under a block of 512 ran its flexible output at 512, now at 2048); fractional hops per block are accepted; no fitting hop or a ratio of 0 isANIRA_ERROR_CONFIGatanira_handler_prepare. Migration: a flexible window at another rate than the anchor declares itstime_ratio(anira_tensor_spec_set_time_ratio,anira/abi/config.h).Breaking: C ABI — built-in engines bind by name where their side has names, else by position, checked at prepare: each engine tensor binds once and must match the engine dims (dtype, rank, static extents), else
ANIRA_ERROR_CONFIG;anira_plan_slot.bindingreportsANIRA_BINDING_NAME/ANIRA_BINDING_POSITION(a registered engine’s slotsANIRA_BINDING_ENGINE); a name on a positional side (ExecuTorch, LibTorch outputs), ignored by alpha.1, isANIRA_ERROR_NOT_SUPPORTEDatanira_handler_create. Migration: drop it, keep its layout.Breaking: C ABI — after a miss no late samples are delivered (alpha.1’s
InferenceManager::process_outputkept up to a block): a block is the stream at its latency, a dropped hop’s fill or a miss (ANIRA_MISSED, count 0), and a host ahead of the stream keeps missing. Migration: none for a host that keeps pace.Breaking: C ABI — a Hard call with more than the declared block on a Streamed slot (
ceilat the stream’s hop) isANIRA_ERROR_INVALID_ARGUMENTon every Hard entry (anira_handler_process, the_multi/_waitforms) before anything moves (latched inanira_handler_rt_error), also through theanira/compat/v2.hppshim beyond itsHostConfigsize, where alpha.1 and 2.x’sanira::InferenceHandlertruncated. Migration: declare the largest block ashost_block_max(contract.hard_host_blocks(host_block_min, host_block_max, host_rate); shimHostConfig(largest_block, rate, true)).Breaking: C++ —
anira/anira.hpp’s enum alias ofanira_engineisanira::EngineKind(alpha.1anira::Engine, now a custom engine’s class), inModelConfig::add_model_path,add_model_bytes,model_engine,default_engine,ProcessorContext::engine(). Migration: rename.Breaking: C ABI — libanira exports only the
anira_*C entries (#229): namespace anira’s C++ losesANIRA_API;anira.hppandanira/compat/v2.hppare header-only over the C entries (gatesanira_symbol_baseline,anira_exports; the unload harness usesanira_release_core_if_idle, notanira::Core). Migration: use the C entries,anira.hppor the shim.Breaking: build — no test library is linked into anira (alpha.1 linked
gtest_mainPUBLIC, and installed it, whenever tests or benchmarks were built): test binaries link it viaanira_add_test_binary/anira_benchmark_fixture;ANIRA_WITH_TESTS/ANIRA_WITH_BENCHMARKleave the package config. Migration: linkGTest::gtest_mainyourself, not viaanira::anira.Breaking: C ABI — the custom stage is a processor:
ANIRA_STRUCT_STAGE_CTX(4 inanira_struct_id, foranira_stage_ctx) isANIRA_STRUCT_PROCESSOR_CTX(4,anira_processor_ctxofanira/abi/processor.h), theANIRA_PHASE_*names stay (anira_phaseabove),anira_plan_extrows name the consumer"processor". Migration: spellANIRA_STRUCT_PROCESSOR_CTX.Breaking: C++ —
anira::Hard::budgetis required:anira_budget_kind(defaultANIRA_BUDGET_MEASURED) plusbudget_valueis oneanira::Budgetwithout default (Hard{.host_block_min = 512, .host_block_max = 512, .host_rate = 48000, .budget = std::chrono::milliseconds(5), .warmup = ANIRA_WARMUP_FIXED, .warmup_iterations = 2}), like the web’sbudgetMs; astd::chronoduration is explicit,Budget::measured()and the default UNTIL_STABLE warm-up are refused in this pre-release,Hard::budget_valueis gone,ContractHandle::hard()reads the budget back as aBudget. Migration:.budget = ANIRA_BUDGET_EXPLICIT, .budget_value = dis.budget = d.Breaking: engines — engine replaces backend in the install and the logs: headers in
<includedir>/anira-engines/<engine>/(wasanira-backends/),aniraEngineHelpers.cmake/aniraEngineTargets.cmake(wasaniraBackendHelpers.cmake/aniraBackendTargets.cmake) foranira::<engine>, CPackdeps-engines(wasdeps-backends), log groupanira.engine.<engine>(wasanira.backend.<engine>;anira::log_group::k_engine_libtorchand siblings, werek_backend_*); internallyanira::backendisanira::engine. Migration: spell the new names; anira-project/backends andANIRA_BACKENDS_*keep theirs.Breaking: C++ — alpha.1’s 2.x singleton
anira::Context(anira/scheduler/Context.h) andanira::ContextConfig(anira/ContextConfig.h) are private: the singleton is the all-static coreanira::Core, private like every core header, log groupanira.core(wasanira.context; the JSON keycontext_configstays);anira::Context/anira::ContextConfigareanira.hpp’s classes overanira_context/anira_context_config. Migration: hand the handler ananira::Context(C: ananira_context*fromanira_context_create); 2.x code spellsanira::v2::ContextConfig;Context::shutdown and thread creation areanira_shutdown(anira::shutdown()) andanira_inference_thread_create(anira::InferenceThread).Breaking: C++ — alpha.1’s installed
anira::InferenceThread(anira/scheduler/InferenceThread.h) is the privateanira::scheduler::InferenceThread(anira::Core::make_inference_thread);anira::InferenceThreadisanira.hpp’s class overanira_inference_thread. Migration: useanira_inference_thread_*or that class.Breaking: C++ —
ANIRA_REALTIMEisANIRA_NONBLOCKINGofanira/abi/export.h(clang’snonblocking, no longer gated onANIRA_WITH_RTSAN) onanira.hpp’s Hard entries;ANIRA_BLOCKINGis private;anira_objectsbuilds with-Wno-function-effects. Migration: spellANIRA_NONBLOCKING.Breaking: C++ — alpha.1’s installed
anira::InferenceManager(anira/scheduler/InferenceManager.h, private now) takes host tensors only (its sevenfloat***overloads ofpush_data,pop_data,process_wait,pop_data_wait, … are gone) and moves Streamed slots only (noPrePostProcessor). Migration: drive a handler with oneanira_tensorper slot,anira_tensor_init_host_planar(&t, channels, num_channels, ANIRA_DTYPE_F32, 2, shape)withshape = {num_channels, num_samples}({1, num_values}non-streamable; C++Tensor::from_host_planar),shape[1] == 0for an unused slot.Breaking: install — only the public headers install (
anira.h,anira_all.h,anira_em.h,anira.hpp,compat/v2.hpp, theabi/headers; another header underinclude/anira/fails the configure): alpha.1’s core headers (scheduler/*.hwithInferenceManager.h,SessionElement.h;anira/utils/Logger.h,anira/utils/RealtimeSanitizer.h, the otherutils/*.h) are private,system/*.h(Exports.h, the deprecatedHighPriorityThread) deleted; the C entries takeANIRA_APIfromanira/abi/export.h. Migration: replace<anira/scheduler/...>,<anira/utils/...>,<anira/system/...>withanira.hppor the C ABI.Breaking: install — tanh-lib, concurrentqueue and nlohmann_json are private, not installed (alpha.1 linked them PUBLIC and installed
libtanh_core,include/tanh,include/concurrentqueue,include/nlohmann; itsBuffer/RingBufferaliased tanh-lib’s): tanh-lib’s core (thl::core::Threadamong it) is built into libanira as the hidden staticanira_tanh_core(anira_tanh_libat anira’s pin) in the inline namespacethl::anira, so a host’s own tanh-lib (thl::v<major>_<minor>) coexists in any link. Migration: link them yourself if you used them viaanira::anira.Breaking: build —
USE_<ENGINE>,ENABLE_LOGGING,ANIRA_VERSIONandTORCH_CXX_FLAGSno longer leave the build tree onanira::anira. Migration: askanira_enabled_engines(andANIRA_STATIC) instead ofUSE_*.Breaking: packaging — the static libanira carries tanh-lib’s core (alpha.1 needed
libtanh_core.aand--exclude-libs,libtanh_core.a). Migration: linkanira::aniraalone; droplibtanh_core.afrom hand-written link lines.Breaking: binary name — the soname is the ABI major (
libanira.so.0,libanira.0.dylib,anira-0.dll/anira-0.libthrough the 3.0.0 pre-releases, 3 from v3.0.0; alpha.1libanira.so.3,anira.dll), the file version the ABI pair (libanira.so.0.2; on Mach-O the current and compatibility versions too, so there a client refuses a library of an older ABI minor), a static PE archive staysanira.lib,aniraConfigVersion.cmakeisSameMajorVersion(wasAnyNewerVersion). Migration: none for CMake; hand-written link lines and loader paths name the new file; the Debian package keepslibanira<release major>.C ABI, configuration (
anira/abi/config.h, JSON):max_instancesdefaults to the newANIRA_INSTANCES_AUTO(0xffffffffu, besideANIRA_THREADS_AUTO; alpha.1: 1), one shared instance per inference-pool thread for a stateless model, resolved at prepare, so handlers leaving it share one loaded model;anira_model_config_createstores it,anira_model_config_max_instances/ModelConfig::max_instances()read it,anira_model_config_set_max_instancesaccepts it (0 still refused),to_jsonomits it, and the 2.xnum_parallel_processorsdefault maps to it (InferenceConfig,Defaults::num_parallel_processors(),anira::v3compat::to_inference_config); each instance is a model copy (max_instances(1)keeps one).C ABI, configuration (
anira/abi/config.h, JSON): a custom engine declaringANIRA_ENGINE_FLAG_NEEDS_NO_MODELneeds no source: JSON may omit"path",anira_model_config_add_model_pathtakes NULL (an empty path is still refused), C++ gainsModelConfig::add_model(engine_id),anira_model_config_model_pathreads NULL; another engine’s source-less entry isANIRA_ERROR_CONFIGatanira_handler_create; no"never-opened.bin"or webfetchModel: () => falseforModelConfig.fromUrlis needed (2.xmodel_pathstays required).C ABI, configuration (
anira/abi/config.h, JSON): a version 2 document with a 3.x root key (modelsbesideinference_config,num_threadsbesidecontext_config) isANIRA_ERROR_JSON, not read as 2.x.C ABI, configuration (
anira/abi/config.h, JSON): a Static or Buffer spec may carry a Channel axis of any extent (no longerANIRA_ERROR_CONFIGatanira_handler_create/anira_handler_prepare); only a Streamed tensor maps it onto ring channels;anira_handler_preparestill refuses any Buffer spec under a Hard contract.C ABI, handler (
anira/abi/handler.h): the miss policies work (alpha.1 delivered zeros), so theANIRA_MISS_BYPASSdefault ofanira_contract_create_hardandanira::Hard{}holds:ANIRA_MISS_ZEROSzeros,ANIRA_MISS_HOLD_LASTthe last block,ANIRA_MISS_BYPASSthe anchored input on process calls (else zeros), Static outputs hold, and the call returnsANIRA_MISSED; BYPASS isANIRA_ERROR_CONFIG(on_miss) for an output anchor or unequal channel counts, sorave_funk_drum_encoder.contract.json/rave_funk_drum_decoder.contract.jsonand upgraded version 2 documents useANIRA_MISS_ZEROS.C ABI, handler (
anira/abi/handler.h): a hop dropped for lack of an inference slot gets theon_missfill (alpha.1: zeros),ANIRA_MISS_CALLBACKcallinganira_miss_fnonce per dropped hop on the driver thread (packed[channels, hop]), placed in stream order;anira_handler_rt_errorreports it asANIRA_ERROR_CAPACITY(an entry’s own CAPACITY return still never reachesrt_error).Internal (the core on the 3.x types): no behaviour change; every figure, stream and copy-path golden as before.
Internal (the core on the 3.x types): the processor runs on the chunk; the 2.x
PrePostProcessorandSessionElement::plan_backendleave the core.Internal (the core on the 3.x types): a chunk is one allocation with 64-byte-aligned slot buffers (no 2.x
BufferF).Internal (the core on the 3.x types): a Streamed slot’s ring lives in its stream port (
SessionElement::send_ring); Static and State slots have no placeholder ring.Internal (the core on the 3.x types): the logger takes
anira_log_level(anira::set_log_level);default_log_level()staysANIRA_LOG_ERRORin a release build, elseANIRA_LOG_INFO;ANIRA_THREADS_AUTOisanira::Core::default_num_threads().Internal (the core on the 3.x types): the session,
Core,InferenceManagerandLatencyCalculatorread the 3.x configuration directly (SessionElement::prepare,InferenceManager::preparetake no host configuration), the host blocks stayingdoubledown toLatencyCalculator::block_samples(noHostConfignarrowing).Internal (the core on the 3.x types): a side’s ports never move (no copy, move or resize;
static_asserts pin it);anira_handlergets both counts fromanira_handler_create.Internal (the core on the 3.x types): every tensor with a stream has a stream port, else
anira_handler_create/anira_handler_preparereturnANIRA_ERROR_INTERNAL.Internal (the core on the 3.x types): one host<->ring copy path over
anira_tensor(also under theblocking_ratiodispatcher and thewait_untilpop), which the 2.xanira::InferenceHandler(InferenceHandler::process) ran on bit for bit viaanira::PlanarFloatAdapter: planar (ANIRA_TENSOR_PLANAR,byte_offset), strided or packed blocks, dtype-generic without conversion; overlapping input and output descriptions are undefined on aBYPASSmiss.Internal (the core on the 3.x types): a C-created handler always runs the processor runner (default: the 2.x
PrePostProcessor’s streamed branches);anira_ringknows its hop and owner (anira::RingOwner,SessionElement::prepare),SessionElement::ThreadSafeStructcarries the processor status thatInferenceThread::do_inferencereads, andanira::RtLatchbrings it tort_error.ABI tooling and gates: release: the npm publish first runs the ABI check, the web build and the
.d.tsexport check (plus_malloc,_free), and sends a hyphenated version such as3.0.0-alpha.2to thenextdist-tag.ABI tooling and gates: generator: the 64-bit sentinels
ANIRA_DYNAMICandANIRA_UNBOUNDEDare typedbigint, so TypeDoc can serialize them.Build: anira’s concurrentqueue is renamed
anira_moodycamel, so a static libanira’s queue never merges with a host’smoodycamel::.Build: a static libanira on ELF (Linux, Android) is one prelinked object with only
anira_*global (-m32-style flags unsupported; tanh-lib and the queue kept apart asthl::anira,anira_moodycamel); a multi-config generator or a toolchain withoutreadelf/objcopykeeps a plain archive.Extras and examples: the advanced benchmark’s
model_and_contract(model, buffer_size)returns both (ModelAndContract), replacingmodel_config_of.C++ (
anira/anira.hpp):anira.hpprefusesANIRA_CXX_MANUAL_INITandANIRA_NO_PROTOTYPESfor good (noanira_get_proc_address);ANIRA_CXX_NO_EXCEPTIONSstays unavailable in this pre-release.Built-in engines: one engine object per compiled-in engine lives while a loaded model holds it; its init (
anira_init_info, under the lifecycle lock, before the first load) owns the per-process state (ONNX Runtime and LiteRT environments, ExecuTorch and LibTorch runtime setup) and the last unload frees it (no macOSmutex lock failed: Invalid argumentat exit); a load before init isANIRA_ERROR_INVALID_STATE.Built-in engines: ONNX Runtime runs as an adapter over
anira_tensor(replacingOnnxRuntimeProcessor): one environment per process, one session per executor, tensors bound in place; non-float32 isANIRA_ERROR_CONFIG, a bad descriptorANIRA_ERROR_INVALID_ARGUMENT, a failed runANIRA_ERROR_ENGINE, an unsupported shape fails the warm-up inanira_handler_prepare.Built-in engines: LibTorch runs as an adapter over
anira_tensor(replacingLibtorchProcessor): one module per executor, inputs viewed in place and bound to the entry method’s arguments by name or position (unknown name:ANIRA_ERROR_CONFIG; trailing arguments keep their defaults), outputs by position, checked at load (ANIRA_ERROR_CONFIG) and per call (ANIRA_ERROR_ENGINE), copied once; a missing entry method isANIRA_ERROR_MODEL_LOADat load.Built-in engines: ExecuTorch runs as an adapter over
anira_tensor(replacingExecuTorchProcessor): one program per load, one module per executor with its own XNNPACK workspace and weights, run inline on the inference thread; positional binding is checked against the method metas’ upper bounds (ANIRA_ERROR_CONFIG).Built-in engines: TensorFlow Lite runs as an adapter over
anira_tensor(replacingTFLiteProcessor): one interpreter per executor, the first signature’s keys bound by name or key order (output_0beforeoutput_1), inputs resized to the engine dims, andresetre-initialises variable tensors before an exclusive handler’s new stream.Built-in engines: LiteRT runs as an adapter over
anira_tensor(for alpha.1’sLiteRtProcessor), binding slots to the model’s first signature by name, else by its sorted key order (as TensorFlow Lite does), checked at load; the bundled gain model runs on LiteRT.The core: the core reads the
anira_context_configofanira_context_config_create(anira::Core::register_context), soanira_wait_strategy,anira_log_levelandanira_log_drainarrive unconverted; extensions are walked once, atanira_context_create; while a 3.x handler lives,anira_shutdownandrelease_core_if_idlerefuse; sessions take an optionalanira::RtLatch*; the mismatch warnings no longer name the 2.x config struct.The core: every engine runs behind one adapter of the
anira/abi/engine.hshape (initwithanira_init_info,InferenceThread::inferencepassing ananira_engine_ctxtoPrepared::run), replacing alpha.1’s five processor pools with aPlanSlotper plan; loaded models pool by their record, notInferenceConfig::operator==(different resolved windows never share; budget, blocking ratio and processing spec no longer split equal models), with one claim loop (ANIRA_ERROR_INVALID_STATEwithout a shared slot) and executors warmed up by the record’s FIXEDwarm_up; an exclusive call carriesANIRA_ENGINE_CALL_EXCLUSIVE; a status other thanANIRA_OKfails the chunk (zeros,ANIRA_ERROR_ENGINE, noafter_inference, also for a 2.xPrePostProcessor::after_inference).The core: a session-exclusive model (
ANIRA_MODEL_STATEFULor a State pair) is pooled and loaded once (instances0) and prepared per handler, whose prepared handle owns its executor (a registered engine’s underANIRA_PREPARE_EXCLUSIVE), where alpha.1 loaded it per handler withinstances = 1; one chunk stays in flight, with a reset per new stream.The core: rings (
anira_ring,anira::RingBuffer) hold the slot’s ring dtype as is, one instantiation per ABI scalar dtype (float32 default) chosen at prepare, and nothing in anira converts: block calls (pop_windowsamong them, which holds alpha.1’sPrePostProcessor::pop_samples_from_buffer) return 0 and write nothing on a dtype mismatch, the typed Hard entries ofanira/abi/handler.hfeed them,anira_contract_hard_set_ring_dtype(anira/abi/config.h) andanira::ContractHandle::hard_ring_dtypestate the rule, and a ring dtype other than its spec’s isANIRA_ERROR_CONFIGatanira_handler_prepareunless the processor fills that ring’s phase.The core: an empty candidate set is
ANIRA_ERROR_CONFIG, notNOT_SUPPORTED(none of the N model entries runs on a candidate backend (candidates: ...)); the candidate filter takesanira_backend_idrows.The core: real-time failures are latched: a refused
ANIRA_NONBLOCKINGor_waitentry setsanira_handler_rt_errorand logs one record per kind flaggedANIRA_LOG_RECORD_CONTRACT_VIOLATION, counting repeats until prepare or reset; scheduler sites and failed inferences log once per prepare, the drain (anira-log, oranira_drain_logunderANIRA_LOG_DRAIN_MANUALand on WebAssembly) reports a growing count at most every 10 s; a failed inference (engine, processor,before_inference/after_inference) zero-fills and setsrt_errortoANIRA_ERROR_ENGINE; no exception ends a thread.The core: the log drain runs on the core’s own low-priority
thl::core::Threadanira-logwhile a session or context exists; the last release,anira_context_destroyoranira_shutdownstops and flushes it;anira_context_config_set_log_flagsandanira_log_descadmitANIRA_LOG_FLAG_TRACE_FAILURES.Web (module, build): the module links
-pthread -sWASM_WORKERS -sAUDIO_WORKLETwith-sINCOMING_MODULE_JS_API=wasmMemory,wasmBinary,locateFile,instantiateWasm,print,printErr, exportsemscriptenRegisterAudioObjectand builds Release with-sASSERTIONS=0(wasm-debugkeeps 1); every Wasm object compiles with-pthread. emsdk stays at 4.0.23, the ONNX Runtime WASM archive’s toolchain (anira-project/backends#24); the built-in ONNX Runtime engine starts no thread there. Every WebAssembly link of anira gets-Wl,--undefined=anira_em_runtime_anchor, so a--no-entrymodule’s runtime never exits; AniraWeb links-sEXIT_RUNTIME=0, an app withEXIT_RUNTIME=1owns the runtime’s lifetime.Web (module): the memory grows: AniraWeb links
-sALLOW_MEMORY_GROWTH=1 -sINITIAL_MEMORY=268435456 -sMAXIMUM_MEMORY=2147483648(alpha.1: fixed 512 MiB),Anira.create({ memory: { initial, maximum } })sizes it in bytes (initial === maximumfixes it), below 256 MiB or a maximum below the initial or above 2 GiB is anAniraError(ANIRA_ERROR_INVALID_ARGUMENT), an unreservable oneANIRA_ERROR_OUT_OF_MEMORY; heap access goes throughheap(module), which rebuilds its views after a growth, and Workers and the worklet get thewasmMemory. An AUTO pool of 16 Workers with two RAVE models fits (#218).Web (module):
num_threadsandANIRA_THREADS_AUTO(half ofstd::thread::hardware_concurrency(), at least one) are no longer coerced to 0 on WebAssembly: AUTO is a pool of Wasm Workers,num_threads0 a host that drives inference;ANIRA_WAIT_BLOCKINGstill becomesANIRA_WAIT_SPIN_BACKOFF,ANIRA_LOG_DRAIN_THREADANIRA_LOG_DRAIN_MANUAL.Web (docs): the Anira Web guides describe the typed layer (cross-origin isolation,
optimizeDeps.exclude,web/examples/model-file/main.ts, raw calls viaanira.abi,audio_nodesforcustom_audio_worklets,defineProcessor/addProcessor,defineEngine/addEngine); the migration page maps alpha.1’s 2.x classes and the pre-release runtime (the single-slot options toinputSlots/outputSlotsamong them);Fetchertypes the loaders’ fetch.Web (docs): the architecture page says each Worker and the worklet is its own realm sharing only the memory, so processors and engines are defined where they run,
processis synchronous afterinit(memory.atomic.wait32), and data moves through the heap andAtomics, neverpostMessage; asynchronous engines wait for M3 (Atomics.waitAsync).anira/anira_em.h: a js_key is the FNV-1a hash of the name, a taken key refused. The docs ofInferenceThread,set_non_realtime,v2::ContextConfigand the thread default (Blockingcoerced on WebAssembly) describe the Workers.Build (internal): anira compiles once into one OBJECT library that
libanira, shared or static, links from (white-box tests use it withANIRA_STATIC); no consumer-visible change.Build (WebAssembly): AniraWeb links
anira::aniraalone (no 2.x wrapper archive,--whole-archiveor-sEXPORT_KEEPALIVE);build_webfails on a promised name missing from the module’s exports or an extra export (besides_malloc,_free).Build: tanh-lib is pinned at v0.5.0 (tanh-lab/tanh-lib#84; alpha.1: v0.3.0) and tanh-tooling at v0.3.0 (was v0.2.8) on both sides; anira’s ring forwards v0.4.0’s strided
thl::core::RingBuffer<T>::push_block,pop_blockandpeek_past_block(tanh-lab/tanh-lib#50).Build: every configure preset exports the compile database (
CMAKE_EXPORT_COMPILE_COMMANDSondesktop-base,ci-base,wasm-debug,wasm-release,docs), and the newANIRA_LINK_COMPILE_COMMANDS(default OFF, top-level builds; ON in thedesktop-*and wasm presets, OFF inclang-tidy) linksbuild/compile_commands.json, which.clangdreads, to the last configured tree (desktop-tests-debugfor the tests;--query-driver=**/em++for wasm trees);.vscode/settings.jsonenablescmake.ctest.allowParallelJobs.Build/CI: no job count is pinned: the test presets of
CMakePresets.jsonlostexecution.jobs: 4(locallyCTEST_PARALLEL_LEVELor-japply), CI detects the cores (cmake-build, ci-actionsv0.3.15), the benchmark leg keeps-j 1.Unload (ELF and Mach-O): unloading the library during an inference stops the pool (
InferenceThread::request_stop) and waits up to two seconds for its threads and the inferences in flight; it joins if they finish and otherwise aborts with a message on stderr (destroy every handler, or callanira_shutdown(), before unloading) instead of hanging. A correct host sees no change; process exit still waits (a core first put to work beforemainis not told of the exit); Windows is unchanged; on macOS dyld’s order is unverified, so an unload may be taken for an exit and joined without a bound.Internal: the session ring is typed only: the float face of alpha.1’s installed
anira/utils/RingBuffer.his gone (push_sample,pop_sample, the three-argument block calls,get_available_samples,get_available_past_samples,get_num_channels,get_num_samples); calls name their dtype (push_block,pop_block,peek_past_block,push_fill,available,available_past,num_channels,capacity) asanira::RingViewdoes;push_block,pop_blockandpeek_past_blocktake a lastsize_t stride = 1;element_size()reportssizeof(T);pop_windowsis unchanged;anira::v2::RingBufferkeeps the 2.x names.CI: workflows move from
tanh-lab/ci-actionsv0.3.10 tov0.3.16(tidy inputs, a tolerant coverage export, job-count inputs, the reusable workflows’runs_on).CI: Linux jobs run on
ubuntu-24.04, sinceubuntu-latest(26.04) lacks LLVM 20, the tooling’s pin (setup-cpp-build-toolsfailed).CI: a pull request’s
clang_tidychecks only its changed.cppfiles (clang-tidy-check); the merge queue, manual runs and.clang-tidyor workflow changes sweep all;clang_tidy resultreports on every pull request, so it can be required.ABI gates: gate 4 compiles every public header against
anira::aniraalone under the strict flags on every preset, failing with a named#errorwhen anything private resolves, and<anira/anira.h>as C11 and C++17; the 2.x umbrella’s gates are gone.ABI gates: gate 5’s consumers run on
anira.hpp.ABI tooling:
tools/abi/gen.pymodels unions (rows as C designators,anira_sync_token.u.vk.value), callback typedefs (typedef R (ANIRA_CALL name)(...), soANIRA_PTR(name, slot)is a function pointer), draft headers (ANIRA_ABI_DRAFT_*) and each Tier-1 record’sanira_struct_id(behindanira_sizeof);--checkrefuses a repeated member name (as inanira_vulkan_desc);--diff-againstflags union-arm and callback-type changes and admits draft ones.ABI tooling: the layout check names the broken rule: while the ABI major is 0 the table grows with the registry (
gen.py --write); after the freeze a Tier-1 layout changes only withANIRA_ABI_MAJOR.Tests: the suite is partitioned for 3.x (2.x hosts on
anira/compat/v2.hpp, where an out-of-range custom-latency index expectsanira::ErrorwithANIRA_ERROR_INVALID_ARGUMENT;anira/anira.hppwithlog_rt; white-box); the one-sided suite’s non-realtime and blocking generator cases run under RTSan (its two#ifndef ANIRA_WITH_RTSANregions are gone); the 2.x test documents carry qualifiedtensor_shaperows.Docs:
docs/sphinx/usage.rstcovers 3.x only: Providers ("provider"), the requiredHard::budget,ANIRA_MISS_CALLBACKwith a parsed"callback", “Processors” (anira::Processor,Processor::Prepared,anira_handler_num_entries),anira::InferenceHandlerbeside the C entries over host tensors (anira_tensor_init_host,shape[1]), the host block range’s price (#228),set_plan, and “Teardown and unloading” (handlers, then contexts, before the host unloads the plugin, never from static destructors orDllMain); 2.x code goes toanira/compat/v2.hpp.Docs:
docs/sphinx/custom_engines.rst(“Custom Engines”, alpha.1’s custom-backends guide) is rewritten onanira_engine_descandanira::Engine(anira_init_info,anira_engine_load_info,anira_prepare_info,ANIRA_ENGINE_CALL_EXCLUSIVE,ANIRA_ENGINE_FLAG_STATE_ALIAS,Engine::Prepared); it and the README say theUSE_<ENGINE>definitions left the installedanira::anira:anira_enabled_engineslists the engines.Docs:
docs/sphinx/custom_preprocessing.rstis rewritten onProcessor/Processor::Prepared(alpha.1:PrePostProcessor): a prepared object per handler,anira_prepare_info/PrepareInfo, a spectrogram inpre_processunderANIRA_PROCESSOR_FLAG_REALTIME_PRE_POST, a heavy transform inbefore_inference/after_inference.Docs:
migration.rstis the compat page: 2.x calls →anira::InferenceHandlerand C entries,PrePostProcessor→ the processor,BackendBase→anira::Engine(Engine::load,Loaded::prepare,Prepared::process); what is not source-compatible (an owningBufferF, a storedInferenceBackend,std::invalid_argumentcatches), the[[deprecated]]timing;anira/compat/v2.hpphasContextConfigand a viewBufferF, noBuffer,MemoryBlockorhelperFunctions.h; what eachanira::v3compatcall became.Docs:
contributing.rstcovers local format and tidy runs (LLVM 20 wheels, theclang-tidypreset), the ABI gates, the registry rules (an[inference-thread]callback typedef carries nononblocking) and the descriptor naming (init/release,load/unload,prepare/unprepare,(ctx, prepared, user_data)).Docs: the other guides follow:
logging.rst(rt_error,ANIRA_ERROR_ENGINE),latency.rst(wait_ratioforblocking_ratio, the output spec’slatencyforinternal_model_latency, a Static or State output forpostprocess_output_size == 0),getting_started.rst(linking from C,LINKER_LANGUAGE CXXon a static anira),benchmarking.rst(examples/benchmark/fixture/), troubleshooting and examples (anira.hpp).Docs: the API reference follows the public headers: new
anira::Budget,anira_tensor,anira_sync_token,anira::Tensor,anira::SyncToken,anira_memory_handle,anira::Engine,EngineContext,EngineLoadInfo,anira::PrepareInfo,anira::InitInfo,anira::EngineLoadInfo,anira_provider_option_set,anira_ext_provider_options,anira::ext::ProviderOptions(Set);ANIRA_PTRslots are members (fixinganira_log_record); left out:anira::detail(ExtTraits,KeptExt,ProcessorTrampolines), nested classes (LegacyProcessor::Prepared,PassthroughEngine’s,InferenceConfig::Defaults,anira::SpecView’sAxis,Window,TimeRatio), private classes; gone:anira::Buffer,MemoryBlock,RingBuffer,Processor::Instance, the 2.x engines.Docs: the docs of
anira_shutdown,anira_release_core_if_idle,anira_context_destroy,anira_handler_destroy,anira::Context,anira::shutdown(),anira::v2::InferenceHandlerandanira::Corestate the teardown rule;anira.hppnamesanira::v2::JsonConfigLoader;Engine(std::string id)andPipeline::add_enginestate theanira.v2.customexception to theanira.prefix;ANIRA_ENGINE_FLAG_STATE_ALIASkeeps the pair’s addresses across aliasing plans’ chunks (a flipping plan’s chunk in between moves them; what a failed aliasing call left in the buffer is the engine’s);ANIRA_TIMEOUTandANIRA_MISSEDcross-reference; the doc ofANIRA_PHASE_INFERENCEsays messages name a slot’s phase by itsanira_phaseword (pre_processtounload).Docs: the v3 roadmap (2026-10-29): M2 exits with
alpha.2; the new M2b, exiting withalpha.3, completes the Hard contract (MEASURED / UNTIL_STABLE budgets, inline execution, State initial values) and adds model variants (thl::RCU); M3 exits withalpha.4; M4 ends with emsdk 6.x; M5 folds into M2b and M6 ([[deprecated]]oncompat/v2.hpp, the abidiff baseline).Docs (Web): the
docs/sphinx/web-api/guides cover the 3.x package only (thewasm-abigates, theorg.anira.onnxruntime-webengine); the 2.x reference pages are gone,AniraError’s is new; the READMEs install from thenextdist-tag.Naming: guides, README, configure messages and tests say engine for an inference engine; a backend is an engine on a provider.
Examples: the JUCE plugin (variants 0-7), the CLAP plugin and the benchmarks run on
anira.hpp(aContext, onePipeline().add_engine(...).add_inference(...).add_processor(...), oneanira::InferenceHandler,org.anira.examples.bypass); the JUCE and CLAP plugins choose the backend withPlanReport::findandset_plan(the simple benchmark finds its plan withPlanReport::find, the others run plan 0), and the CLAP plugin checksanira_check_abi.Examples: the JUCE and CLAP plugins declare the host’s block range (JUCE
hard_host_blocks(1, samplesPerBlock, sampleRate), CLAPhard_host_blocks(max(1, minFrameCount), maxFrameCount, sampleRate)) instead of a fixed block, so their reported latency covers every size of it; the benchmarks keep fixed blocks.Examples: the four minimal-inference examples that link anira (ONNX Runtime, LibTorch, LiteRT, TensorFlow Lite) read path and shapes through
examples/minimal-inference/minimal_model.h(anira::ModelConfig,SpecView), notanira/compat/v3_to_v2.h, and hold data instd::vector, notBufferF/MemoryBlock.Examples (Web):
web/examples/model-filepicks its plan per prepare withPlanReport.findandInferenceHandler.setPlan; both examples set theirAudioContextoptions inline.Bundled models: the tflite and litert rows of
gain.model.jsonandstereo_gain.model.jsongive the static gain the export’s rank-3 layout, the litert row the output keysoutput_0/output_1;stateful_accumulator.model.json: above.Pre-release names (no tag carried them):
v3snapshot spellings betweenv3.0.0-alpha.1and this release, old → new. C ABI:anira_processor_phase/ANIRA_PROCESSOR_PHASE_FORCE32(afteranira_stage_phase) →anira_phase/ANIRA_PHASE_FORCE32;anira_processor_prepare_info/ANIRA_PROCESSOR_PREPARE_INFO_INIT→anira_prepare_info/ANIRA_PREPARE_INFO_INIT(anira/abi/lifecycle.h);anira_engine_prepare_info/ANIRA_ENGINE_PREPARE_INFO_INIT→anira_engine_load_info/ANIRA_ENGINE_LOAD_INFO_INIT; the one-levelanira_engine_prepare_fn→anira_engine_load_fn(out_loaded) /anira_engine_unload_fn,anira_engine_prepare_fnper handler (ANIRA_PREPARE_EXCLUSIVEininfo->flags),anira_engine_init_fn/anira_processor_init_fn(by-nameANIRA_ENGINE_DESC_INITinitializers compile unchanged);anira_engine_ctx.reserved_ptr0→anira_engine_ctx.loaded,anira_engine_ctx.flags→ its first bitANIRA_ENGINE_CALL_EXCLUSIVE;anira_processor_ctx.reserved_ptr0/reserved_ptr1→engine_id/provider_id;anira_processor_engine_id/anira_processor_provider_id→anira_processor_engine/anira_processor_provider;anira_model_config_default_engine_id,_model_provider_id,_default_provider_id→anira_model_config_default_engine,anira_model_config_model_provider,anira_model_config_default_provider(C++anira::EngineRef/anira::ProviderRef); customANIRA_PROVIDER_DEFAULT→ANIRA_PROVIDER_CUSTOM,ANIRA_ENGINE_NONE→ANIRA_ENGINE_CUSTOM;prepare(handler, report, user_data)overanira_processor_desc.user_data→anira_processor_prepare_fn(info, user_data, out_prepared); the id atanira_pipeline_add_engine→ atanira_custom_engine_create(one engine added under two ids is now two engines);anira_enabled_backends→anira_enabled_engines;anira/abi/machine.h→anira/abi/context.h;anira_now_ms,anira_now_ns,anira_shutdown,anira_release_core_if_idle,anira_has_core→anira/abi/core.h;anira_context_drain_log/anira_context_num_inference_threads→anira_drain_log(anira/abi/log.h) /anira_num_inference_threads(anira/abi/thread.h);anira_contract_hard_geometry→anira_contract_hard_host_blocks;block_min,block_max,rate→host_block_min,host_block_max,host_rate(anira_contract_hard_set_host_blocks);anira_handler_process_f32,anira_handler_process_f32_inplace,anira_handler_process_f32_multi,anira_handler_push_data_f32,anira_handler_push_data_f32_multi,anira_handler_pop_data_f32,anira_handler_pop_data_f32_multiand the five_waittwins of the process and pop forms (#190) → the tensor entries of the same name (oneanira_tensor_init_host_planarwithANIRA_DTYPE_F32,ANIRA_TENSOR_READ_ONLYinputs;_inplacepasses one tensor as input and output; a_multiform takes one tensor per slot, where the float forms accepted NULL at a request of 0;deliveredreplacesnum_out);anira_handler_process(h, &in, &out, 0, &delivered)→anira_handler_process(h, &in, 0, &out, 0, &delivered),anira_handler_process_wait/anira_handler_pop_data_wait→ an index per side,timeout_mslast (#189);_multiStatic[1, values]slots → the spec’s tensor (the empty element is any extent 0, notshape[1] == 0; a single form naming a Static slot isANIRA_ERROR_INVALID_ARGUMENT; a missed Static output is the stored value, filled first underANIRA_MISS_CALLBACK);anira_em_pipeline_register_js_engine(pipeline, engine_id, js_key, hook_mask, engine_flags, err)→anira_em_pipeline_add_js_engine;ANIRA_EM_PROCESSOR_HOOK_AFTER8 → 16,_PREPARE16 → 32,_RELEASE32 → 64,_RESET64 → 128,_UNPREPARE128 → 256,_INIT256 → 512,ANIRA_EM_HOOKS_VERSION1 → 2;anira_em_alloc_thread_stack,anira_em_free_thread_stack,anira_em_init_instance,anira_em_hooks_version→ removed;engine:provider→"engine"and"provider";provider_optionsper kind → per backend (anira_ext_provider_options.setsbystruct_size, asanira_pipeline_add_inference); theanira.v2.custompass-through (BackendBase::process,ANIRA_BINDING_POSITION) → an engine under the id; the engine query per prepare → once atanira_handler_create; Host-only rows atANIRA_RUNG_STATIC→ the runtimes’ providers; the silent default-engine fallback to plan 0 → the default engine’s first plan on the default provider, with one Warning at prepare naming the request and that plan; the 2.x plan table behindset_inference_backendand the validator’sanchor_of→ gone. C++:Engine::prepare→Engine::loadreturningstd::unique_ptr<Engine::Loaded>, thenLoaded::prepare;anira::ProcessorPrepareInfo/anira::EnginePrepareInfo→anira::PrepareInfo/anira::EngineLoadInfo;Pipeline::add_engine(id, impl)→explicit Engine(std::string id)andPipeline::add_engine(impl);anira::enabled_backends()→anira::enabled_engines();anira::Engine::available→anira::Engine::query;Machine→Context;Context::register_machine→anira::Core::register_context;Context::drain_log()/num_inference_threads()→anira::drain_log()/anira::num_inference_threads();anira::Stage,Stage::Prepared,StageContext→anira::Processor,Processor::Prepared,ProcessorContext;anira::stage(anira::stage::Inference,anira::stage::Custom),Pipeline::AnyStage,Pipeline::add,Pipeline::inference,Pipeline::register_engine→Pipeline::add_inference,Pipeline::add_processor,Pipeline::add_engine(anira::Pipeline p; p.add_engine(e).add_inference(model).add_processor(s););HybridNNStage→HybridNNProcessor(extras/models/hybrid-nn/HybridNNProcessor.h);anira::v2::LegacyProcessorStage→anira::v2::LegacyProcessor;anira/abi/stage.h→anira/abi/processor.h(ANIRA_ABI_PROCESSOR_H),anira_stage_*→anira_processor_*(anira_processor_desc,anira_processor_ctx,anira_processor_fn,anira_processor_input_role,anira_processor_default_pre_process),ANIRA_STAGE_*→ANIRA_PROCESSOR_*(ANIRA_PROCESSOR_DESC_INIT,ANIRA_PROCESSOR_FLAG_REALTIME_PRE_POST,ANIRA_PROCESSOR_FLAG_REALTIME_HOOKS),anira_pipeline_add_stage→anira_pipeline_add_processor; the stage hook bits →ANIRA_EM_PROCESSOR_HOOK_*(engines keepANIRA_EM_ENGINE_HOOK_*),anira_em_stage_desc_init→anira_em_processor_desc_init,anira_em_pipeline_add_js_stage→anira_em_pipeline_add_js_processor;JsonConfigLoader::get_context_config(),to_context_config→ gone;anira::ContextConfig(anira/ContextConfig.h) →anira::CoreConfig(anira/CoreConfig.h:LogConfig,LogDrain,WaitStrategy,LogLevel) → removed (anira::v2::ContextConfig);anira::PlanarFloatAdapter,anira::NonStreamableRouter→ test helpers;anira/utils/RtLatch.h→ private (#229);<anira/compat/v3_to_v2.h>→ removed (withanira::EngineKindoverloads ontoANIRA_PROVIDER_CPUandanira::v3compat::to_inference_configrefusing State withANIRA_ERROR_NOT_SUPPORTED);anira.h→<anira/anira.h>. Web (#210’s runtime → #213’s typed layer):createAniraWasm(abiVersion) →Anira.create;Module.anira,HookRegistry→globalThis[Symbol.for('anira.registry')](Registry);Heap→heap(module);callWithErroroveranira_error,checkStatus→ bindings throwingAniraError;allocInstanceStack(RangeError) → none;JSProcessor,JSEngine,JSBackend,readStageContext,readLogRecord→defineProcessor,defineEngine,engineTensors,layout,logRecordAt;core/InferenceThreadpollinghas_exited,waitForWorkerMessage→ anira’s Wasm Workers;AniraAudioWorkletBase(AudioWorkletProcessor,registerProcessor) →createAudioNode;ONNXRuntimeWebBackend→onnxRuntimeWeb();AniraWeb(AniraWeb.create,AniraWeb.module,AniraWeb.registerJSEngineforJSBackendBase, refusingANIRA_EM_ENGINE_HOOK_QUERYat registration, notANIRA_ERROR_UNKNOWNat prepare,AniraWeb.addJSStageforJSPrePostProcessor,configureAudioWorklet/registerAudioWorkletForContexton aBaseAudioContext) →Anira,Context,Pipeline,InferenceHandler,createAudioNode;spinUpInferenceWorker(contextPtr, workerOrUrl?)→workerModule;getAniraVersion,drainAniraLog,startLogPump→anira.version,anira.drainLog(),anira.startLogPump(); the worklet’s Static input blocks →anira_em_audio_node_set_static_input;AniraWeb.abi,AniraModule.abi,JSBackendEnv.abi,JSProcessorEnv.abi→anira.abi,ScopeEnv.abi;anira_em_audio_node_create(handler, audio_context, input_channels, output_channels, input_slot, output_slot, param_slots, num_param_slots, tensor_slots, num_tensor_slots, wait_ms, out_status, out_node, err)→ slot lists andanira_handler_process_multi;createAudioNode(anira, audioContext, handler, { inputChannels, outputChannels, inputSlot, outputSlot, params, staticInputs, waitMs, workletModules })→inputSlots,outputSlots,partialStreams;Anira.create({ memory })with aWebAssembly.Memory→{ initial, maximum };measureRenderGeometry’sprobe→hold;Handler.createAudioNode’s warning → gone;Context.createwithout threads: 1 →ANIRA_THREADS_AUTO;anira_inference_thread_starton WebAssembly → starts a Wasm Worker;Handler→InferenceHandler,InferenceHandler.create(...).prepare(contract)chaining to the handler → returning thePlanReport,latency→getLatency/getLatencies,Contract(Contract.fromUrl,fromJson) →ContractHandle(ContractHandle.fromUrl),setGeometry/ContractHandle.hardGeometry→hardHostBlocks,ContractHandle.hardkeys →hostBlockMin,hostBlockMax,hostRate,budgetMs,warmup→warmupIterations,attachBytes→setModelBytes,addInference→inference→addInference,x.ptr→x.native(),AniraError.code→AniraError.status,setLogHook→setLogSink(scopeRegistry().logSink),context.threads→context.numInferenceThreads(),ModelEntry { engine, engineId }(fetchModel) →ModelEntry { engine: EngineRef },hooks→phases,setStaticInput→ dtype-generic,defineStage→defineProcessor,StageFactory/StageOptions→ProcessorFactory/ProcessorOptions,Registry.defineStage→Registry.defineProcessor,Registry.stage→Registry.processor(registry.processor),addStage→addProcessor,registerEngine→addEngine(decisions 10.17, #227, and 10.18);web/examples/custom-worklet→web/examples/stage-and-engine→web/examples/processor-and-engine. Build:FetchContent_MakeAvailable(tanh-lib)→anira_tanh_libwithtanh_add_core_library(anira_tanh_core … ABI_NAMESPACE anira …); a static libanira sharing a host’s tanh-lib → separate by name (thl::anira); tanh-lib v0.4.0 →7ae7c69→ v0.5.0; ci-actions v0.3.14 →v0.3.15→v0.3.16;ProcessBlockFixture::plan_of→PlanReport::find; theanira::scheduler::InferenceThreadpage → gone.
Deprecated#
C++ (
anira/compat/v2.hpp):namespace anira::v2, the 2.x source-compatible face, goes one minor release after 3.0.0; its entities get[[deprecated]]before 3.0.0, not in the alphas.
Removed#
Breaking: C++ (2.x classes) — the 2.x
anira::BackendBase(<anira/backends/BackendBase.h>) and the core’s 2.x engine path, with no shim: theInferenceManagerconstructors over aBackendBase*andInferenceManager::set_backend/get_backend. Migration: ananira::Engine(anira.hpp;anira_engine_descin C) on the pipeline (migration.rst); a 2.x custom backend is one underanira::v2::k_custom_engine_id, the 2.x pass-throughanira::v2::PassthroughEngine.Breaking: C++ (2.x classes) — alpha.1’s own 2.x classes and their headers (
<anira/InferenceConfig.h>,<anira/PrePostProcessor.h>,<anira/utils/HostConfig.h>,<anira/utils/InferenceBackend.h>,<anira/utils/Buffer.h>,<anira/utils/MemoryBlock.h>);anira/utils/RingBuffer.handanira/scheduler/InferenceThread.hare private now, withoutBuffer.h. Migration (shim spelling ofanira/compat/v2.hppin parentheses):anira::InferenceConfig,ModelData,TensorShape,TensorShapeList,ProcessingSpec→anira::ModelConfigplus a Hardanira::ContractHandle(anira::v2::InferenceConfig, …);anira::HostConfig,ReferenceStream→ the Hard contract’s host blocks and the model’s anchor (anira::v2::HostConfig);anira::InferenceBackend→anira::EngineKind/anira_engine(anira::v2::InferenceBackend);anira::PrePostProcessor→anira::Processor/anira_processor_desc(anira::v2::PrePostProcessorviaanira::v2::LegacyProcessor);anira::Buffer,BufferF,MemoryBlock→anira_tensor/std::vector(anira::v2::BufferF, a view);anira/utils/helperFunctions.h→ the standard library.Breaking: C++ (2.x classes) — alpha.1’s
anira::ContextConfigof<anira/ContextConfig.h>(anira::CoreConfigin the snapshots) with its fieldsm_anira_version/m_enabled_backends(anira::CoreConfig::m_anira_version) and their cross-session compares,anira::LogConfig, theanira::LogLevel/anira::LogDrain/anira::WaitStrategy(SpinBackoff,Blocking) enums withto_string,default_log_drain(),default_num_threads()and theanira::LogLeveloverload ofdefault_log_level()(the privateanira::default_log_level()returns ananira_log_level). Migration:anira::ContextConfigofanira/anira.hpp(anira_context_config) or the shim’sanira::v2::ContextConfigwith itsLogConfigand enums;ANIRA_THREADS_AUTOfordefault_num_threads();anira_enabled_engines(built) andanira_capabilities_backendson a probed context (usable).Breaking: C++ (2.x classes) — the 2.x
anira::JsonConfigLoader(<anira/utils/JsonConfigLoader.h>). Migration:anira::ModelConfig::from_filewithtake_legacy_contract()andanira::ContextConfig::from_fileread a 2.x document as is; or the strictanira::v2::JsonConfigLoader(what 2.x logged and skipped is ananira::Error).Breaking: C++ (2.x classes) — libanira’s 2.x
anira::InferenceHandler(<anira/InferenceHandler.h>): the name is theanira.hppclass over the C handler, and noaniraclass is defined in both libanira andanira.hpp(the scheduler thread isanira::scheduler::InferenceThread). Migration:anira::v2::InferenceHandler, which behaves like the C handler.Breaking: C++ (transitional) — alpha.1’s
<anira/compat/v3_to_v2.h>(anira::v3compat:to_inference_config,to_context_config,to_host_config,enabled_engines). Migration: ananira::InferenceHandlerfrom aPipeline, prepared with the contract;anira::enabled_engines().Breaking: C++ (benchmark fixture) —
<anira/benchmark.h>and<anira/benchmark/ProcessBlockFixture.h>are not installed; libanira and its package config drop Google Benchmark. The fixture isexamples/benchmark/fixture/(anira_benchmark_fixture, built byANIRA_WITH_BENCHMARKalso withoutANIRA_WITH_EXAMPLES) overanira.hpp, same output:initialize_repetition(ModelConfig, Hard, plan)afterset_plan(PlanReport::find) on ananira::InferenceHandler, thenpush_random_samples_in_buffer()/process_buffer()on one planar tensor;calculate_min/_max/_percentileandrandom_sampleare inanira::benchmark::. Migration: copy the two fixture files (benchmarking.rst).Breaking: Web — alpha.1’s 2.x web layer: the
EMSCRIPTEN_KEEPALIVEwrappers over the 2.x classes (archiveanira::wasm_wrappers), their TypeScript classes (InferenceConfig,InferenceHandler,PrePostProcessor,JSPrePostProcessor,ModelData,ProcessingSpec,TensorShape,HostConfig,BufferF,RingBuffer,Vector*,InferenceBackend,InferenceThread), theAniraWebfactory fields andJSBackendBase. Migration: the typed TypeScript API over the C ABI andanira/anira_em.h(_anira_*exports, JavaScript engines and processors on the pipeline, threads anira starts).Breaking: engines — the processor classes
anira::OnnxRuntimeProcessor,anira::LibtorchProcessor,anira::ExecuTorchProcessor,anira::TFLiteProcessor,anira::LiteRtProcessor(anira/backends/<Engine>Processor.h, theiranira.hlines) are gone; each engine is an internal adapter. Migration: a custom engine (anira::Engine,anira_engine_desc,anira::v2::k_custom_engine_id) that drives a bundled engine links itsanira::<engine>target.Breaking: Web — alpha.1’s 2.x TypeScript runtime:
AniraWeb(AniraWeb.create(config, memory)over aWebAssembly.Memory,spinUpInferenceWorker(workerOrUrl?),registerProcessor/unregisterProcessor,registerPrePostProcessor/unregisterPrePostProcessor,registerAudioWorkletForContext,configureAudioWorklet(audioContext, inferenceHandlerPtr, prePostProcessorPtr, audioWorkletNodeName, { inputChannels, outputChannels, maxBufferSize })),createAniraWasm,setupInferenceWorker,waitForWorkerMessage,InferenceWorker,ONNXRuntimeWebBackend,AniraAudioWorkletBase, theinference-processorworklet,getAniraVersion,drainAniraLog,randomSample,fillBuffer,pushBufferToRingbufferand the./workers/*exports (./workers/inference-worker,./workers/audio-worklet,./workers/worklet-base); the entry points are.,./scope(registry,defineEngine,defineProcessor, bindings, enums),./engines/onnxruntime-weband./wasm/*. Migration (migration.rst):Anira.create({ memory: { initial, maximum } });anira.abi.anira_*for_anira_*,anira.modulefor the heap helpers; a context withthreadsand aworkerModule(defineEnginefor aJSBackendBase) andawait context.ready()for the Workers;defineProcessorin a worklet module (createAudioNode’sworkletModules) andpipeline.addProcessorfor aJSPrePostProcessoror a worklet subclass;handler.createAudioNode(audioContext, { params, staticInputs, waitMs })for the worklet setup,inputSlots/outputSlots(lists of Streamed slots whose channel counts come from the model, default every Streamed slot, so a single-stream model needs neither;partialStreamsleaves one unserved) forinputChannels/outputChannels;onnxRuntimeWeb({ model })of@anira-project/anira/engines/onnxruntime-web;anira.version,anira.drainLog().Extras and examples: the extras’ 2.x processors
CNNPrePostProcessor,CNNBypassProcessor,HybridNNPrePostProcessor,HybridNNBypassProcessorand the advanced benchmark’sClearCustomProcessor, replaced byHybridNNProcessor,BypassEngine,ClearEngineand anira’s default fill.
Fixed#
Runtime: overload: each hop that finds every slot busy is dropped and filled at its own stream position (
SessionElement::owe_fills), in order on the hop grid, not one per call into a send ring (thl::core::RingBuffer) that overflowed.Runtime: a plan switch (
anira_handler_set_plan,anira::v2::InferenceHandler::set_inference_backend) could run two engines on a chunk or none, or switch it betweenpre_process,before_inference/after_inferenceandpost_process; a chunk keeps the plan it was submitted under.Runtime: a released session’s loaded models and prepared handles, and a registered engine’s
unprepare(a C++Engine::Prepared’s deletion), finish beforeanira_handler_prepare/anira_handler_destroyreturns, not later on an inference thread holding itsshared_ptr(InferenceThread::process_dequeued_inference).Runtime: at exit (Linux, macOS) the pool waits up to two seconds for the inferences in flight before engine runtimes tear down, where ONNX Runtime failed (
ANIRA_ERROR_ENGINE) or crashed; the unload hook still joins without a bound, anddlclosekeeps its bounded wait and abort.Runtime: an
exit()in an engine’s init or load (anira_engine_init_fn,anira_engine_load_fn) duringanira_handler_prepareno longer deadlocks (Linux, macOS); the lifecycle lock’stry_lock(release_core_if_idle) refuses its holder, wherestd::mutex’s was undefined.Engines: LibTorch on Linux aarch64 pins OpenBLAS to one thread, process-wide; its spinning workers starved the inference threads.
Engines: TFLite binds the bundled gain model’s outputs by signature key, not position; prepare’s shape check refuses a swapped pair of different shapes on every engine.
Engines: ExecuTorch executors no longer contend on XNNPACK’s process-wide locks or pin its global thread pool.
Engines: the ONNX Runtime web build no longer leaks its threading options.
Extras and examples: JUCE RAVE example: atomics replace
getParameterAsValue(...).getValue(), which allocated on the audio thread; a missed latent frame (ANIRA_MISSEDfrompop_data) reaches the decoder instead of putting it out of step; a re-prepare resets the frame count.Built-in engines: a failing chunk’s text is logged once per run of failures, not once per failed inference.
The core: head-of-line blocking: a job that finds no free instance waits on the model’s list for the holder instead of polling its thread (under
ANIRA_WAIT_SPIN_BACKOFFandANIRA_WAIT_BLOCKINGalike) and stalling other models; a stopped thread fails it (ANIRA_ERROR_ENGINE); the claim loop stays for a shared call made directly (Prepared::run).The core: a shared call waiting for a busy instance backs off (
InferenceThread::exponential_backoff) instead of spinning and gives up withANIRA_ERROR_INVALID_STATEonshould_exit(the chunk:ANIRA_ERROR_ENGINE); a pool stop signals every thread before joining; the audio thread never reaches the claim loop.The core: a preempted worker could free a session on an inference thread and then write into it; a session dies on the control thread that released it.
Web (module):
std::mutexexcludes across the module’s threads (#212): alpha.1 linked shared memory without pthreads, so it locked nothing.Web (module): out of memory, ONNX Runtime’s included (was
ANIRA_ERROR_MODEL_LOAD), isANIRA_ERROR_OUT_OF_MEMORY(anAniraError), notRuntimeError: Aborted(OOM): anira links-sABORTING_MALLOC=0(-sABORTING_MALLOC=1after it keeps the abort), sostd::bad_allocis thrown and caught.Web (module): a record reaches the console once, at its level: on WebAssembly anira’s console sink by level replaces tanh-lib’s stderr sink (a warning as
console.warn, notconsole.error);ANIRA_LOG_FLAG_DISABLE_PLATFORM_SINKoranira_em_set_log_hook(setLogSink) holds the sink off,setLogSink(null)restores it, and the sink links even when onlyanira_logis called.Web (module, build): the wasm build no longer deletes ONNX Runtime’s license files, so the package ships them.
Web (module, build): a warm tree reconfigures and relinks when the export list changes (one kept the names from before the
hard_host_blocksrename), and reconfigures when a docs page is added or deleted.Web (ONNX Runtime Web engine): onnxruntime-web’s binary is fetched once by URL instead of inlined as base64 into every bundle.
Web (package): alpha.1’s runtime bugs go with it: a leaked worklet stack, an
AudioContext-only worklet setup (the audio node takes anyBaseAudioContext),InferenceWorker.stop()freeing a Worker’s stack too early, and a TypeScript worklet failing to type-check againstAniraAudioWorkletBase(itsAudioWorkletProcessorbase was declared only in the unshippedsrc/worklet.d.ts).CI (Windows): the test binaries no longer race copying
ANIRA_SHARED_LIBS_WIN; one target copies them once they are built.Tests: the stateful ordering test checks each inference’s window, so it can fail.
Docs: the contributing guide refers to each branch’s ruleset, not alpha.1’s “ten contexts”.
Docs: troubleshooting: a shared engine library meets a host’s copy by name (soname; Windows module name, with Windows ML’s
onnxruntime.dll; install name); only anira’s ONNX Runtime refuses an older runtime at init (LibTorch, LiteRT and TFLite have no such check); a plugin uses a static anira (LibTorch has no static build), and with a shared anira the engine libraries ship next to the executable you control; separating the shared engine libraries by name is #232.Docs:
anira_context_config_set_log_sink(alpha.1’sanira_machine_config_set_log_sink) no longer claims to be ignored on WebAssembly;anira_drain_logfeeds the C sinks andanira_em_set_log_hookthere alike.Examples (CLAP): activate applies the Backend parameter (the handler ran the default plan under a “Bypassed” display), and the dry path is delayed by the reported latency; varying blocks still miss (#228).
Examples (benchmarks): each backend gets its own run and summary (the run key, beside
host_block_max,host_rateand plan, names the backend); a pathless entry no longer throws (ModelConfig::model_paththrowsANIRA_ERROR_INVALID_STATEfor it): the fixture readsanira_model_config_model_pathand prints the engine id.Bundled models:
extras/fetch-models.cmakerefetches a tree whose.anira-pinstamp (URL, commit) is missing or stale, so a pin bump reaches an existing checkout; offline the old tree stays, the RAVE download is SHA256-checked, and the first configure refetches every tree once.
v3.0.0-alpha.1 - 2026-09-03#
The first 3.x pre-release: the configuration layer of the C ABI (anira/abi/*.h, ABI 0.1) with JSON loaders, the C++20 builders of anira/anira.hpp and a bridge to the 2.x runtime. With ABI major 0 a library accepts only its headers’ exact ABI version; the soname stays 3; npm ships the 2.x API (next tag).
Added#
ABI (unstable): generated
anira/abi/build_info.h:ANIRA_VERSION_MAJOR/MINOR/PATCH,ANIRA_VERSION_STRING,ANIRA_MAKE_VERSION,ANIRA_ABI_MAJOR/ANIRA_ABI_MINORfrom the tag (0.Nfor the N-th v3 pre-release).ABI (unstable): the registry
abi/anira.ymland its generatortools/abi/gen.pygenerateanira/abi/{export,status,version,enums,log}.h(anira_engine,anira_provider), the TypeScript enums and the symbol listsabi/symbols-0.txt/symbols-draft.txt, checking the conventions (ANIRA_NONBLOCKING,struct_size-first records). Implemented:anira_abi_version,anira_check_abi,anira_version,anira_version_string,anira_status_string,anira_drain_log,anira_log_rt,anira_log.anira/system/Exports.hincludesanira/abi/export.h.ABI (unstable):
anira/abi/config.h: opaqueanira_tensor_spec,anira_model_config,anira_machine_config(anira_machine_config_set_log,anira_{cuda,gl,vulkan,metal,d3d12,webgpu}_desc),anira_contract(Hard or Async,edge_cost,ANIRA_ERROR_WRONG_CONTRACT),anira_job_options; argument checks at set time, cross-field at prepare. Extensionsanira_ext_header/anira_ext_entry(ANIRA_EXT_ENTRY_INIT) viaset_ext/set_ext_json,anira_registered_ext_kinds;ANIRA_ERROR_EXTENSION_VERSIONfor an unregistered version, an unknown kind fails prepare.ABI (unstable): per-entry tensor records (
models[].tensors):anira_model_config_set_tensor_name(unset binds positionally) andanira_model_config_set_tensor_layout(ANIRA_AXIS_INSERTadds a unit axis; a transpose is refused at prepare in this pre-release); the anchor is a canonical name (anira_model_config_set_anchor,"anchor"), replacingANIRA_ANCHOR_FIRST_STREAMED.ABI (unstable): JSON:
anira_model_config_from_json/anira_model_config_from_json_file(relative paths againstbase_dir),anira_machine_config_from_json,anira_contract_from_json,anira_model_config_to_json,anira_machine_config_to_json; load errors areANIRA_ERROR_JSONwith the key path, unknown keys fail prepare by name. A v2 document is upgraded (ANIRA_SUCCESS_UPGRADED; oneANIRA_LOG_WARNINGper process):model_datato models (CUSTOMtoanira.v2.custom,model_functiontoentry),tensor_shape/processing_specto specs,max_inference_time/warm_up/blocking_ratioto a Hard contract foranira_model_config_take_legacy_contract.C++ (not ABI-stable; requires C++20):
include/anira/anira.hpp: RAIIanira::TensorSpec,anira::ModelConfig,anira::ContractHandle(fromanira::Hard/anira::Async;anira::Contract=std::variant),anira::MachineConfig,anira::JobOptionsHandle(fromanira::JobOptions); aliasesanira::DType,Engine,Provider,Domain,SyncKind,Role,AxisTag;anira::Result<T>declared. Each chaining method is one C call (ModelConfig::tensor_layout=anira_model_config_set_tensor_layout), failures throwanira::Error(std::runtime_error,anira_statusin.status,anira_errortext),native()exposes the C handle;anira::ext::Entry(model_ext,ext_json).ModelConfig::from_json(text, base_dir)/from_file,MachineConfig::from_json/MachineConfig::from_file,ContractHandle::from_json/ContractHandle::from_file,to_json;upgraded()reports a 2.x document,take_legacy_contractreturnsstd::optional<ContractHandle>. The first handle checksANIRA_ABI_VERSION;ANIRA_CXX_NO_EXCEPTIONS,ANIRA_CXX_MANUAL_INIT,ANIRA_NO_PROTOTYPESare rejected until the handler half lands.MachineConfig::log_sink(anira_log_fn, void*),ModelConfig::anchor(name); noanira::JsonConfigLoaderyet.ABI (unstable):
anira_contract_hard_set_ring_dtype("ring_dtypes",anira::ContractHandle::hard_ring_dtype): one tensor’s host-sample dtype under Hard, float32 by default; the pre- and post-processor convert between it and the spec’s dtype; the bridge accepts float32 only.Transitional:
anira/compat/v3_to_v2.h(anira::v3compat, alpha.1 only) runs 3.x configurations on the 2.x runtime:to_inference_config,to_context_config,to_host_config(from the contract orbuffer_size/sample_rate),enabled_engines()(ANIRA_ENGINE_NONEkeeps custom engines).ANIRA_ERROR_CONFIGfor invalid input,ANIRA_ERROR_NOT_SUPPORTEDfor Async,MEASURED,UNTIL_STABLE, a non-BYPASSmiss policy, non-float32, a transpose, dynamic Time on a Buffer, an engine not built, a custom engine other thananira.v2.custom. Maps ontoModelData,TensorShape,ProcessingSpec,max_instances,HostConfig,ContextConfig.Errors and logging: a returnable failure is returned (
anira_error,anira::Error), not logged; a caller-less one (destroy, anira threads) is logged once; a real-time refusal does both. C entries areANIRA_NOEXCEPT(an escape isstd::terminate);ANIRA_ERROR_INTERNALlogs once; a failing main-thread entry drains the real-time log first.ANIRA_LOG_FLAG_TRACE_FAILURES(machine config) turns every failed status into an Error record once the 3.x runtime applies it (until then an internal process-wide switch);anira.capilog group. Engines fail withANIRA_ERROR_MODEL_LOAD/ANIRA_ERROR_ENGINE(anira::StatusError), a missing model file withANIRA_ERROR_NO_SUCH_FILE.
Changed#
The 3.x line lives on the
v3branch, versioned from v3 tags (0.0.0+g<hash>without one); release artifacts areanira-3.0.0-alpha.1-<leg>.tanh-tooling v0.2.8 (pre-release-aware git version; drift check
tooling-config) and tanh-lib v0.3.0 (tanh-lab/tanh-lib#34, #37, #38) pinned; anira’s export header no longer depends on tanh-lib.WebAssembly:
_anira_drain_logcomes from the library, not the wrapper.Docs: the guides cover the 3.x configuration API only; 2.x material moves to the new
migration.rst; newlogging.rst.Release builds keep Warning and Info records (tanh-lib’s
TANH_LOG_COMPILED_MAX_LEVEL4); the logcat tag and os_log subsystem areanira.The v2 upgrade’s defaults match 2.x: no
warm_up= fixed 0, nonum_parallel_processors=max_instancesof half the hardware threads.InferenceConfigand the backends no longer log what they throw; the message carries the detail.A failing warm-up fails construction on every engine (
ANIRA_ERROR_ENGINE); TensorFlow Lite checks every call.Breaking: bundled models and examples — the
anira::InferenceConfigstatics of the 2.x fixture headers (CNNConfig.hand the other*Config.h) becomeextras/models/**/*.model.json+*.contract.json(extras/models/model_files.h), one processor per engine;SimpleGainConfig.jsonandRaveFunkDrumConfig*.jsonare gone. Migration:ModelConfig::from_file,ContractHandle::from_file,to_inference_config(model, contract, enabled_engines()),hard_geometry+to_host_config; replaceGUITARLSTM_MODELS_PATH_*,STEERABLENAFX_MODELS_PATH_*,STATEFULLSTM_MODELS_PATH_*,SIMPLEGAIN_MODEL_PATH,RAVE_MODEL_DIRand*_JSON_CONFIG_PATHwithANIRA_EXTRAS_MODELS_DIR.JUCE example variants 0 to 7 (
MODEL_TO_USE; variant 1 embeds the CNN viaModelConfig::from_json+set_model_bytes+ANIRA_BYTES_BORROW); benchmarks useto_context_config(MachineConfig{}.log_level(ANIRA_LOG_ERROR)).
Removed#
anira’s test of tanh-lib’s
thl::core::read_wav.
Fixed#
The core no longer starts tanh-lib’s drain thread (
thl::Logger::set_config), which kept plugins mapped after unload.A failed inference outputs zeros on every engine, not stale data.
LibTorch: a
c10::Errorno longer leaves an instance busy forever.
v2.3.0 - 2026-09-02#
anira v2.3.0 is the last release of the 2.x line. Development continues on the v3 branch (the versioned C ABI, docs/anira-v3-architecture.md); 2.x receives fixes only.
Added#
One-sided streaming (#98, #99, #110): generators are driven by output demand, analysers read through
PrePostProcessor::get_output(), and theHostConfigreference stream may be an input or an output (m_tensor_is_input,HostConfig::k_first_streamable). Mirrored in the WebAssembly/TS wrapper.ExecuTorch backend (
ANIRA_WITH_EXECUTORCH, static-only):.pteprograms, named entry points (model_function), prebuilt libraries for desktop, Android and iOS, aminimal-executorchexample.Receptive-field (sliding-window) models in the default
PrePostProcessor: an input tensor larger than itspreprocess_input_sizeis filled with ring-buffer history plus the fresh hop.Contextis immortal and owns the inference thread pool exactly while sessions exist (#104);Context::shutdown()for hosts that unload live,release_core_if_idle()/has_core()reclaim the core.LatencyCalculator(#66) replacesSessionElement’s latency arithmetic: closed forms instead of the LCM loop,is_feasible(), correct struct and ring sizing for fractional and smaller host blocks. Derivation indocs/sphinx/latency.rst.Symbol policy from the shared tanh-tooling CMake modules (
cmake/tanh/): hidden visibility everywhere,libaniraexports namespaceaniraonly, plugins leak no backend runtime symbol; theanira_exportsCTest enforces it.CI on the shared
tanh-lab/ci-actionsworkflows: every backend and both linkages in the PR tier, install, sanitizer (ASan+UBSan, TSan, RTSan) and coverage legs, a preset for every leg inCMakePresets.json, and the npm publish gated behind the same tests as every other release artifact.
Changed#
Breaking: the latency calculation moves out of
SessionElementintoLatencyCalculator;SessionElementloses itscalculate_*,max_num_inferencesand gcd/lcm helpers. Reported latencies are unchanged for whole-sample host blocks; slot counts follow2·S.Breaking: backend linkage follows
BUILD_SHARED_LIBSandANIRA_<ENGINE>_LINKAGEis gone: LibTorch (shared-only) is disabled in static builds, ExecuTorch (static-only) in shared builds.Breaking: no public header includes an engine header, and the engines are explicit imported targets that anira links
PRIVATE(anira::onnxruntime,anira::tflite,anira::litert,anira::libtorch,anira::executorch). Migration: linkanira::<engine>wherever your own code includes an engine header.Breaking (Windows install layout): DLLs install to
bin/, import libraries and archives tolib/.Breaking: logging goes through tanh-lib’s
thl::Loggerwith a real-time queue (#56):ANIRA_LOG_*/ANIRA_LOG_RT_*replace theLOG_*stream macros,ContextConfig::m_log_level->ContextConfig::m_log(anira::LogConfig), and the host owns the sinks.Breaking:
InferenceHandler::reset()is wait-free and safe on the audio thread. Migration: callprepare()where a drain was relied upon.Breaking (containers):
anira::Buffer<T>,anira::RingBufferandanira::MemoryBlock<T>are aliases over tanh-lib’sthl::corecontainers;RingBufferno longer derives fromBuffer<float>, and every real-time ring-buffer access uses the block API (#111).Context::get_instance()takes no arguments and returns aContext&; theContextConfigtravels withContext::create_session()(old two-step API deprecated for one minor release).anira::HighPriorityThreadis deprecated for one release.The active backend defaults to the first model backend that is available instead of the silent
CUSTOMbypass;HostConfig’s default reference tensor is the first streamable tensor.The export header is
anira/system/Exports.h;ANIRA_BUILDING/ANIRA_STATICreplaceANIRA_EXPORTS/ANIRA_STATIC_DEFINE(old spellings honoured).ExecuTorch is consumed as one merged
libexecutorch.aper platform, and the CMake >= 3.24 desktop floor is gone. The test suite builds as per-component binaries (test_utils,test_scheduler,test_backends,test_handler).Pins: tanh-lib
751b2b1, anira-project/backends v2.4.0 (ExecuTorch 1.3.1, pre-isolated static desktop LiteRT).
Removed#
Context::release_instance()andContext::release_thread_pool()(Context::shutdown()is the explicit teardown), the never-releasedreset_non_blocking()variants, the unreachableContextConfig::operator==/!=, and the dead interpolation branch ofanira::calculate_percentile.
Fixed#
Backend runtime symbols are no longer exported from binaries embedding anira, which crashed hosts that ship their own runtime (Ableton Live 12 bundles ONNX Runtime).
One-sided streaming:
SessionElement::prepare()no longer hangs for generators or crashes for analysers, push-only pipelines no longer stall afterm_num_structschunks (#99), latency vectors are index-aligned with the outputs (#98).Session lifecycle:
Context::create_session()no longer leaks the session count when a processor constructor orprepare()throws (#106);create_session()/release_session()/prepare_session()are thread-safe across sessions; a data race inContext::release_session()(found by the TSan leg).LatencyCalculator::least_common_multipleno longer overflowsint, theallow_smaller_bufferssweep no longer stalls for large blocks, and the send ring of a fractional host block reservesP - 1samples.JsonConfigLoaderdrops malformedtensor_shapeentries instead of lettingnlohmann::type_errorescape;LibtorchProcessorthrowsstd::runtime_erroron an unloadable model like the other backends;BackendBase::processno longer reads past the output vector.USE_ANIRA_WEBis defined in Emscripten builds only; installing onlib64hosts works with LibTorch and ExecuTorch;anira::HighPriorityThreadlinks again in a Windows consumer of a shared anira; the JUCE example links under clang on Linux.Tests and CI: the macOS test-discovery race with CMake 4.4.0 (
DISCOVERY_MODE PRE_TEST), the intermittently failing one-sided blocking-deadline tests, downloads retried after transient failures, and compile caching that works for the first time (ACTIONS_CACHE_SERVICE_V2).
v2.2.1 - 2026-07-04#
Added#
Batched overlapping-window extraction: a
pop_samples_from_buffer(...)overload that extractsnum_batcheswindows in one native call (also exposed to WebAssembly/TS), avoiding per-batch JS↔Wasm boundary crossings for batched/windowed models (e.g. HybridNN/GuitarLSTM).PrePostProcessor::before_inference()/after_inference()hooks, run on the inference thread right before/after the backend runs, letting stateful models (e.g. recurrent hidden-state feedback) splice state between consecutive inferences when combined withsession_exclusive_processor = true. Wired up end-to-end in Anira Web (registerPrePostProcessor/beforeInference()/afterInference()on the TS side).Configurable inference-thread wait strategy:
anira::WaitStrategy { SpinBackoff, Blocking }onContextConfig.Blockinglets idle inference threads sleep on a semaphore instead of spin-polling, eliminating idle CPU usage at effectively no throughput cost; coerced toSpinBackoffwith a warning on WebAssembly.Real-time factor and underrun reporting in the benchmark fixture (per-iteration RTF/
[underrun]marker, plus an optional summary line withrtf_mean/rtf_max/underrun count).The
advancedandcnn-sizebenchmarks now also cover theCUSTOM(no-inference) backend, and the benchmark CI workflow builds with tests enabled and runs the benchmark gtest suites.Configurable log level:
anira::LogLevel { Debug, Info, Warning, Error }onContextConfig, gating anira’s own logging and forwarded to the ONNX Runtime, LiteRT and LibTorch backends (TFLite excepted — no runtime logging control in that prebuilt library). Defaults toInfoin debug builds,Errorin release builds.Anira version mismatch reporting in
Context::get_instance: a differing major version between sessions is now reported as an error, a differing minor/patch as a warning.Context::get_num_inference_threads()/InferenceHandler::get_num_inference_threads(): number of inference threads currently active process-wide (also exported to WASM).
Changed#
ContextConfig’s defaultnum_threadsis now platform-dependent: half the available CPU cores (as before) on native builds,0on WebAssembly, since inference threads there are always supplied externally viaAniraWeb.spinUpInferenceWorker().
Fixed#
Stateful in-order dispatch (
session_exclusive_processor = true) no longer allocates on the audio thread —SessionElement’s pending-dispatch queue is now pre-sized and fed through an explicit producer token.Web: the audio worklet now polyfills
performance.now()before the WASM module loads, fixing aReferenceError(observed in Firefox) whenever a blocking-ratio deadline was read from the audio thread.The advanced benchmark no longer instantiates ONNX Runtime for the stateful RNN model, whose fixed 2048-sample ONNX export failed warm-up at other buffer sizes.
Use-after-free when a pooled backend processor outlived the session that created it —
InferenceConfigis now owned per-processor instead of aliasing the originating session’s copy.Windows build failure in
Context::get_instance()caused by<windows.h>’smin/maxmacros mangling an unrelatedstd::min(...)call; fixed by definingNOMINMAX/WIN32_LEAN_AND_MEANbefore the include.Hardened
SessionElement::m_is_non_real_timetostd::atomic<bool>and unified the twonew_data_request()wait paths onto onewait_for_completion()helper — previously a default-blocking_ratiosession in non-real-time mode could free an in-flight buffer while the inference thread was still writing to it. Non-real-time mode also now works on WebAssembly once an inference worker is running.
v2.2.0 - 2026-06-23#
Added#
Android support (
arm64-v8a+x86_64): the library, the prebuilt backends, and the full gtest suite running on a KVM-accelerated emulator, all wired into CI (build_test_mobile.yml). The glibc-onlypthread_*inheritsched/pthread_setattr_default_npcalls are gated behind!__ANDROID__(bionic lacks them) while keeping the portableSCHED_FIFOpath.iOS support (device + simulator): the library and prebuilt backends shipped as an xcframework, with the full gtest suite running on the simulator in CI. Per-SDK xcframework slice selection; TFLite is consumed as a
TensorFlowLiteC.frameworkvia a generated shim so anira’s<tensorflow/lite/...>includes resolve untouched.LiteRT inference backend (
anira::InferenceBackend::LITERT): runs.tflitemodels through Google’s nativeLiteRt*C API / CompiledModel runtime. Enabled by default (ANIRA_WITH_LITERT=ON) as the modern TensorFlow-Lite-family backend; wired into the examples and benchmarks.Data-driven backend downloads: prebuilt backends are fetched at configure time from the
anira-project/backendsrelease, pinned byANIRA_BACKENDS_VERSION.Live backend integrity check: when GitHub is reachable, anira fetches each asset’s published SHA256 and re-downloads any backend whose archive changed upstream or downloaded incompletely, instead of a committed hash lock.
ANIRA_BACKENDS_SKIP_REMOTE_CHECK=ONskips the remote query for offline/reproducible builds.Bring-your-own-backend knobs:
ANIRA_<ENGINE>_ROOTDIR(prebuilt tree),ANIRA_<ENGINE>_URL+ANIRA_<ENGINE>_SHA256(custom source), and per-engineANIRA_<ENGINE>_LINKAGE=shared|static.clang-tidy conformance across the library, tests and benchmark sources, enforced in CI via the
tanh-lab/ci-actions/clang-tidy-checkaction (clang_tidy.yml)InstallConsumersmoke test that builds against the installed package to catch packaging regressions.Release pipeline now publishes every tested arch×linkage artifact with backend-consistent naming: Android (static), iOS (xcframework), and Linux/macOS/Windows ×
shared/static, including macOSuniversal.
Changed#
Breaking: the
InferenceConfig::Defaultscompile-time constants were renamed from them_prefix to thek_prefix to match the constant-naming convention (m_warm_up→k_warm_up,m_session_exclusive_processor→k_session_exclusive_processor,m_blocking_ratio→k_blocking_ratio). The mutableDefaults::m_num_parallel_processorsis unchanged.LiteRT is now the default TensorFlow-Lite-family backend. The legacy TensorFlow Lite backend (the older
TfLite*C API,ANIRA_WITH_TFLITE) is the same runtime exposed through a different C API, so the two are now mutually exclusive — enable the legacy path with-DANIRA_WITH_LITERT=OFF -DANIRA_WITH_TFLITE=ON.nlohmann_jsonis now consumed as a release download instead of a git submodule.CMake options and their validation were consolidated inline into
CMakeLists.txt(AniraOptions.cmakeand the redundant linkage knob were dropped).anira::calculate_min/anira::calculate_maxare nowinlinefree functions instead ofconst autolambdas (source-compatible: existing call sites and uses as a callable are unaffected)The internal logging helper
isLoggingEnabled()was renamed tois_logging_enabled()Migrated the shared clang configs (
.clang-format/.clang-tidy/.clangd) from thetanh-libsubmodule symlinks totanh-tooling(pinnedv0.1.4): committed as real files, kept in sync by theclang_check.ymldrift check, and the now-unusedtanh-libsubmodule was removed (configs are byte-identical, so lint/format results are unchanged)Adopted the default Claude Code config:
.claude/settings.jsonnow enables thetanh-toolsplugin from the tanh-tooling marketplace (its format/lint/type-check hooks supersede the previous bespoke.claude/hooks)CI now covers Windows-
arm64, Linux-aarch64and macOS-universallegs (shared + static) in addition to the mobile workflow.
Fixed#
Potential use-after-free in
Buffer::malloc_channels()when channel-pointer allocation failsInstalled
nlohmann_jsonconfig sofind_package(anira)works against the installed packageDisabled backends now compile to empty translation units (guarded
.cppbodies), andminimal-onnxruntimeis self-sufficient in static buildsValue-initialize the
const InferenceConfigin the install consumerclang-tidy violations and a CLAP static MSVC runtime mismatch; preserve the anira-before-
JuceHeaderinclude order on MSVC; qualifiedmem*calls withstd::and added<cstring>Windows shared-DLL copy, the examples target list, and arm64 LibTorch in CI
v2.1.0 - 2026-06-14#
Added#
anira Web: the C++ library compiled to WebAssembly via Emscripten, published as the
@anira-project/aniranpm packageEmscripten/embind C++ wrappers exposing the core API (InferenceHandler, InferenceConfig, PrePostProcessor, ProcessingSpec, InferenceThread, Buffer, RingBuffer, HostConfig) to JavaScript
TypeScript API layer wrapping these bindings (
AniraWeb, plus typed wrappers for InferenceHandler, InferenceConfig, ModelData, TensorShape, ProcessingSpec, BufferF, RingBuffer, HostConfig and the embind Vector types)New ONNXRuntimeWebBackend (onnxruntime-web), plus
JSBackendBase/JSPrePostProcessorhooks for implementing custom inference backends and pre/post processing in JavaScript/TypeScriptWeb Audio API integration with an AudioWorklet base class and Web Worker–based off-thread inference
WASM build tooling (BuildWasm.cmake, DetectEmscripten.cmake, CMake presets), npm publish workflows, and dedicated Web API documentation (Sphinx + TypeDoc)
anira::Semaphorewrapper for macOS 10.13 supportmacOS universal binary support: anira can now be built as a universal binary (arm64 + x86_64) when no pre-built backends are enabled (e.g. for a custom CoreML backend)
tanh-lib submodule with clang-format and clang-tidy support
Unregistering of pre/post processors and a prePostRegistry
Validation that the maximum inference time must be greater than 0
Function for freeing the stack pointer
Sponsor information in the README
Changed#
Enforce stateful model inference ordering via single-in-flight dispatch instead of spin-wait
MSVC: support static linking via
ANIRA_STATIC_DEFINERefactored processPrePost
Improved GitHub Actions workflows (node24, new workflow versions, no env vars)
Added Prettier formatting
Fixed#
Fixed a Windows build bug
Fixed the documentation build step
Fixed npm version drift (pinned onnxruntime-web to 1.19.2)
v2.0.3 - 2025-11-07#
Added#
JSON configuration loader (JsonConfigLoader) with nlohmann_json dependency, including unit tests
Option to load LibTorch models as binary data
model_functionargument formodel_datain the JsonConfigLoaderJSON gain example config and JUCE plugin example with JSON inference config loading
no_grad options for torch tensors and the inference stage (Fixes #45)
Fixed#
JUCE plugin example failing to compile when MODEL_TO_USE is set to 6
No-inference-engine CI build (JsonConfigLoader excluded from the no_inference_engine build)
Missing preprocessor flag in RaveFunkDrumConfig.h
v2.0.2 - 2025-08-03#
Added#
New pop_data methods with wait_until
Support for TFlite Binary Models
Changed#
Improved latency calculation to take parallel processing into account
All operating systems now use std::steady_clock for benchmarking
Tests for Inference Manager and Session Element now use fixed number of threads 2, which is available on all gh runners
Fixed#
Ringbuffer initialization now initializes the buffer with zero values
Fixed the realtime sanitizer build option
Fixed blocking operation in the InferenceHandler process method
v2.0.1 - 2025-07-31#
Changed#
Updated CI to build anira without inference engines to avoid missing preprocessor flags
Fixed#
Ensure missing preprocessor flags are set for disabled backends
Add virtual destructor to PrePostProcessor to avoid polymorphic cleanup issues
v2.0.0 - 2025-07-28#
Added#
New custom trained RAVE model in examples
Defaults struct inside InferenceConfig
Support for offline audio processing
Option to disable std::cout and std::cerr output
Possibility to load ONNX models as binary files
InferenceHandler reset method with comprehensive tests
Dynamic ring buffer allocation with overflow protection
Test cases for latency calculation, dynamic ring buffer allocation, and inference struct calculation
Custom latency preparation functionality
Jack dependency for Linux JUCE applications
Comprehensive Doxygen documentation with beautiful Shibuya theme
Added ProcessingSpecs to the InferenceConfig class for better handling of input and output tensor specifications
Added changelog documentation page
Changed#
Major update: New shape handling and sizes management
Major update: Support for non-audio input and non-audio output
Major update: Support for multiple streamable and non-streamable tensors
Major update: Input tensor sample rate must not be equal to output tensor sample rate anymore
Refined latency calculation system:
Now supports smaller buffer sizes than host config (with allow_smaller_buffers flag)
Moved calculation logic to SessionElement
Better handling of models with internal latency
Renamed HostAudioConfig to HostConfig
Renamed AudioBuffer to Buffer
Improved catchup and handling of missing samples
Different backends can have different shapes while maintaining consistent processingSpecs
Removed USE_CONTROLLED_BLOCKING preprocessor definition
Removed external host thread possibility
Complete documentation overhaul with new theme and structure
Fixed#
Race condition in InferenceThread where derived class context was destroyed before base class destructor (PR #31)
Project version compatibility when adding as subdirectory (PR #30)
Internal latency management issues (PR #32)
Build bugs and compiler warnings
GitHub workflow issues
Install script for nlohmann library
CMakeLists configuration issues
v1.0.3 - 2025-01-24#
Fixed#
Fixed bug where version could not be detected when imported as a submodule
Added#
Possibility to package as .deb package
New checks and tests
v1.0.2 - 2024-12-06#
Added#
Full support for armv7l platform on Linux
Benchmarks part of test suite when making pull requests
Multiple improvements in CMake build chain
Changed#
Bela examples now in separate repository
Fixed#
Fixed Windows test suite
v1.0.1 - 2024-11-20#
Fixed#
Fixes #11: Issue where the concurrentqueue lib would not be found in the prebuilt binaries or installed lib
v1.0.0 - 2024-11-13#
Added#
Major update with API changes (see anira usage guide or examples for more information)
Multichannel support
Support for input and output of multiple tensors including threadsafe methods to retrieve and pass their state in the anira::PrePostProcessor
New anira::Context that uses the same thread pool independent of the anira::InferenceConfig the anira::InferenceHandler has been initialized with
CLAP plugin example
Enhanced inference job submission
v0.1.3 - 2024-09-23#
Changed#
Updated libtorch to 2.4.1
Fixed#
Fixes issue libomp not bundled with libtorch for macOS arm64
x86_64 macOS stays with 2.2.2 since new version binaries are not built by pytorch
v0.1.2 - 2024-09-14#
Added#
New timestamps via counting inference buffers
Enhanced thread synchronization and data sharing between threads
Windows Ninja generator support
Enhanced Windows dynamic libs
New default values in InferenceConfig
Updated documentation
Changed#
Default threadsafe structs switched to atomic
Port to new organization
Fixed#
Solved debug build issues with Windows
v0.1.1 - 2024-08-28#
Added#
New Bela support and examples
New thread synchronisation option with raw atomics
v0.1.0 - 2024-05-20#
Changed#
New anira::InferenceConfig layout
v0.0.8 - 2024-05-15#
Improved#
Improved latency calculation
v0.0.7 - 2024-04-27#
Changed#
Version 0.0.7 release
v0.0.6 - 2024-04-17#
Changed#
Version 0.0.6 release
v0.0.5 - 2024-04-11#
Changed#
Version 0.0.5 release
v0.0.4 - 2024-04-01#
Changed#
Version 0.0.4 release
v0.0.3 - 2024-03-30#
Changed#
Updated Windows CI workflow
v0.0.2 - 2024-03-27#
Changed#
Version 0.0.2 release
v0.0.1 - 2024-03-23#
Added#
Initial release (Version 0.0.1)