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 before ready() is refused; a JavaScript processor’s anira_processor_desc.id is 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_NONE ignores it; processors of one tail field anira_processor_desc.id share it (anira::Processor(std::string id), Processor::id()), else one with before_inference / after_inference measures per registration.

  • C ABI, handler: anira_plan_info tail fields warmup_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, COMFORTABLE at a load (rt_factor / rt_parallel) < 0.75, MARGINAL < 1, NOT_REALTIME), in ANIRA_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); TypeScript PlanInfo.warmupIterations, warmupOutcome, measuredMs, medianMs, rtFactor, rtParallel, rtVerdict and the two enums.

  • The MEASURED budget and the UNTIL_STABLE warm-up: anira_handler_prepare times ordinary inferences of every plan on the inference threads (hooks and engine call, not the wait); MEASURED sets each anira_plan_info.budget_ms to 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 thread ANIRA_ERROR_INVALID_STATE (also for an inference over 10 s); a failed inference ANIRA_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) is ANIRA_ERROR_NOT_SUPPORTED at anira_handler_create; nothing converts: another host type goes in ring_dtypes, with a processor converting in pre_process / post_process.

  • C ABI, handler: anira_plan_slot tail fields dtype (the model tensor’s) and ring_dtype (0 without a ring), logged; TypeScript PlanSlot.dtype, ringDtype.

  • C ABI, handler: anira_plan_slot tail fields window_derived (1 if derived), window (elements along Time per inference, a flexible one as pinned) and hop (window less overlap), 0 on Static and State slots, the same in every plan, logged; TypeScript PlanSlot.windowDerived, window, hop.

  • C ABI, handler and context: the enum anira_mover_flags (ANIRA_MOVER_NONE 0, ANIRA_MOVER_ANIRA 1: anira’s code, an engine adapter’s copy, ANIRA_MOVER_ENGINE 2: 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) in moved_by of anira_plan_slot (tail field) and anira_edge_info, logged; the ANIRA_MOVER_ANIRA rows are exactly anira’s per-inference copies; TypeScript PlanSlot.movedBy.

  • C ABI, handler and context: the enum anira_memory_kind, which a device provider’s edge class follows: ANIRA_MEMORY_UNKNOWN 0 (no probe established it; ANIRA_EDGE_UNKNOWN, refused by every edge-cost limit), ANIRA_MEMORY_UNIFIED 1 (host memory: CPU path, integrated GPU, Apple silicon, lavapipe; ANIRA_EDGE_UNIFIED_TRANSFER), ANIRA_MEMORY_DEDICATED 2 (device memory across a bus; ANIRA_EDGE_DEDICATED_TRANSFER), in memory_kind of anira_edge_info and anira_plan_info (tail field), logged; TypeScript PlanInfo.memoryKind.

  • C ABI, handler and context: the kind is probed with no link dependency through Metal hasUnifiedMemory, Vulkan’s device type and memory, CUDA CU_DEVICE_ATTRIBUTE_INTEGRATED, HIP hipDeviceAttributeIntegrated (5.0+), OpenCL CL_DEVICE_HOST_UNIFIED_MEMORY, D3D12 D3D12_FEATURE_DATA_ARCHITECTURE.UMA, on ONNX Runtime’s device_id (default 0; CUDA, TensorRT, ROCm, MIGraphX, DirectML), the Metal default device (Core ML, MPSBackend) or, for WebGPU, LiteRT gpu and 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) until anira_context_probe, logged at Debug (anira.system); ANIRA_TEST_MEMORY_KINDS asserts 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) from anira_engine_edge_fn in the tail field anira_engine_desc.edge overwrites the provider rule’s (NULL keeps it); the mover follows from the class (the engine whatever moves, none on ANIRA_EDGE_ZERO_COPY); a refusal fails the prepare with its status, an unnamed class with ANIRA_ERROR_ENGINE; C++ anira::EngineEdge, virtual Engine::Loaded::edge(is_input, slot, provider_rule) (base: the rule).

  • Web: HardContractOptions.edgeCost / ContractHandle.edgeCost (anira::Hard::edge_cost, anira::ContractHandle::edge_cost; unset or edgeCost(undefined): no limit); EngineOptions.edge (EngineEdges, { inputs?: EngineEdge; outputs?: EngineEdge }) at Pipeline.addEngine, per direction (unset keeps the provider rule); addEngine(ONNXRUNTIME_WEB_ENGINE_ID) states ANIRA_EDGE_COPY by the engine both ways, ONNXRUNTIME_WEB_ENGINE_EDGES (root, scope and engine entries) for another id; a given edge replaces them.

  • Bundled models: example-models 28e6dd9 (extras/fetch-models.cmake, was d1bc5cf): TypedGainNetwork at int16, 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); in extras/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, LiteRT LiteRtGetQuantizationTypeId, torch, ExecuTorch QInt8, QUInt8, QInt32, QUInt4x2, QUInt2x4) is ANIRA_ERROR_NOT_SUPPORTED at 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) carry dtype and data, a typed array of the dtype over its memory (Uint16Array for float16 and bfloat16, bytes for bool8; f32 stays); 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) and ContractHandle.hardRingDtype (hard_ring_dtype) name a ring dtype per Streamed tensor.

Changed#

  • Breaking: bundled models — every extras/models/**/*.contract.json runs 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}, or anira::ContractHandle::hard_budget / hard_warmup on 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 await ready() 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 needs await context.ready() first (else ANIRA_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 with warmup: ANIRA_WARMUP_NONE.

  • Breaking: TypeScript — ContractHandle.hard mirrors anira::Hard: budgetMs is optional (the measured budget) and the warm-up defaults to UNTIL_STABLE (was NONE without warmupIterations). Migration: budgetMs with warmup: ANIRA_WARMUP_NONE, or warmup: ANIRA_WARMUP_FIXED beside warmupIterations.

  • anira::Budget default-constructs to the measured budget, as a C contract does, so anira::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_NONE or FIXED 0 is ANIRA_ERROR_CONFIG at prepare (every MEASURED budget was ANIRA_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_start returns 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’s initial; AniraWeb’s -sINITIAL_MEMORY 64 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_CONFIG without anira_tensor_spec_set_window, TensorSpec::window or "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 is ANIRA_ERROR_CONFIG, and anira_tensor_spec_window (SpecView::window) and anira_model_config_to_json show declared windows only, the plan report the one in use.

  • Breaking: C ABI — anira_edge_class sorts where an edge takes the bytes, by cost: ANIRA_EDGE_ZERO_COPY 0, new ANIRA_EDGE_COPY 1 (within one domain), new ANIRA_EDGE_UNIFIED_TRANSFER 2 (a CPU-device crossing in unified memory), new ANIRA_EDGE_DEDICATED_TRANSFER 3 (over a bus), new ANIRA_EDGE_UNKNOWN 255 (memory kind not probed; above every limit), replacing ANIRA_EDGE_DEVICE_COPY 1, ANIRA_EDGE_HOST_COPY 2, ANIRA_EDGE_UNAVAILABLE 3; who moves is the new moved_by. Migration: a copy reads ANIRA_EDGE_COPY, a device row its memory_kind’s class; recompile.

  • C ABI, handler: plan slots’ edge_class (and allocate_class) and moved_by report what the engine does (all zero-copy before): ANIRA_EDGE_ZERO_COPY in place over host memory (CPU path, XNNPACK, ONNX Runtime’s DnnlExecutionProvider, ACLExecutionProvider, ArmNNExecutionProvider), ANIRA_EDGE_COPY by ANIRA_MOVER_ANIRA (LibTorch outputs, ExecuTorch planned outputs) or ANIRA_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 said ANIRA_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_cost take and return an anira_edge_class (was anira_edge_cost), default no limit (ANIRA_EDGE_UNKNOWN); a limit admits class <= limit; anira_handler_prepare drops plans above it (an Info in anira.capi; the report and plan indices keep the rest), none left is ANIRA_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_cost and ContractHandle::hard() use std::optional<anira_edge_class> (std::nullopt: no limit). Migration: ANIRA_EDGE_COST_STRICT / "strict" is ANIRA_EDGE_ZERO_COPY / "zero_copy", ANIRA_EDGE_COST_PERMISSIVE / "permissive" no limit (ANIRA_EDGE_DEDICATED_TRANSFER also refuses unknown edges).

  • Engines: a model tensor a built-in engine cannot bind is ANIRA_ERROR_NOT_SUPPORTED at load (was ANIRA_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_init and anira_em_pipeline_add_js_engine take input_edge and output_edge after js_key, hook_mask, engine_flags: a const anira_engine_edge* per direction (NULL: the provider rule; an unknown anira_edge_class is ANIRA_ERROR_INVALID_ARGUMENT). Migration: pass NULL, NULL; Pipeline.addEngine takes EngineOptions.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 (else ANIRA_ERROR_CONFIG at prepare); anira_contract_hard_num_ring_dtypes / anira_contract_hard_ring_dtype read what was set, anira_ring_dtype the 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’s dlopen; 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, in anira_em_audio_node_create) spell dtypes as words and name the remedy (per call: a tensor of the ring dtype, or ring_dtypes plus 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_info is {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_CUSTOM with ids), else a domain; anira_capabilities_edges gives two rows per anira_capabilities_backends row, 2i from ANIRA_DOMAIN_HOST to backend i, 2i + 1 back (pipelines too); rung is an anira_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) and anira_pipeline_capabilities_edge(pipeline, context, edge) take one anira_edge_info with its ends set (a domain end has ANIRA_ENGINE_NONE), were (…, anira_domain from, const anira_backend_id* to, anira_edge_info* out); no row is ANIRA_ERROR_EDGE_UNREACHABLE, a struct_size short of to_provider_id ANIRA_ERROR_INVALID_ARGUMENT; C++ anira::Capabilities::edge / anira::PipelineCapabilities::edge add edge(const BackendId& from, Domain to). Migration: from ANIRA_EDGE_INFO_INIT set to_engine, to_provider, to_engine_id, to_provider_id and pass &edge; existing C++ calls are unchanged.

  • Breaking: C ABI — ANIRA_EDGE_INFO_INIT has class ANIRA_EDGE_UNKNOWN (available 0, ends unset), not ANIRA_EDGE_ZERO_COPY. Migration: read the class anira returns.

  • Breaking: C ABI — anira_context_probe(context, err) and anira::Context::probe() lose force (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_out are from_domain / to_domain (same offsets, ANIRA_PLAN_SLOT_INIT unchanged), TypeScript PlanSlot fromDomain / toDomain (were domainIn / 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.flags is realtime_phases (same offset and type), an OR of the new ANIRA_PHASE_BIT(phase) (1u << phase) over the five per-chunk phases (pre_process, post_process, before_inference, after_inference, reset; another bit is ANIRA_ERROR_INVALID_ARGUMENT at anira_pipeline_add_processor), and ANIRA_PROCESSOR_FLAG_REALTIME_PRE_POST / ANIRA_PROCESSOR_FLAG_REALTIME_HOOKS are gone. anira_handler_prepare requires the bit of every filled phase the contract runs on the driving thread (Hard: pre_process, post_process, reset), else ANIRA_ERROR_CONFIG naming the phase and realtime_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() is realtime_phases() in the k_* bits of phases() (default 0; Pipeline::add_processor refuses a bit outside k_all_phases), and Pipeline::add_processor fills the reset slot only for k_reset in phases() (new, phase_bit(ANIRA_PHASE_RESET); k_pre_process and k_post_process no longer bring it); anira::v2::LegacyProcessor promises k_pre_process | k_post_process | k_reset. Web: ProcessorOptions.flags is realtimePhases (default the bits of pre_process, post_process and reset), and the processor_flags parameter of anira_em_processor_desc_init and anira_em_pipeline_add_js_processor is realtime_phases. Migration: desc.flags = ANIRA_PROCESSOR_FLAG_REALTIME_PRE_POST becomes desc.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_HOOKS adds the bits of ANIRA_PHASE_BEFORE_INFERENCE and ANIRA_PHASE_AFTER_INFERENCE); a C++ flags() returning ANIRA_PROCESSOR_FLAG_REALTIME_PRE_POST becomes realtime_phases() returning k_pre_process | k_post_process | k_reset (or phases() when every body is real-time); TypeScript flags: ANIRA_PROCESSOR_FLAG_REALTIME_PRE_POST becomes realtimePhases: ANIRA_PHASE_BIT(anira_phase.ANIRA_PHASE_PRE_PROCESS) | … or is left out; a C++ Prepared that overrides reset adds k_reset to phases(), 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’s out, anira::Engine::Loaded::edge’s provider_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-engine example declare no window where the fixed Time extent is the window.

  • Branches: the 3.x line is developed on main (renamed from v3), the 2.x line on v2 (renamed from main); the workflows’ pull-request triggers drop v3, and the contributing guide names the new bases. The docs deploy, the cache warmer and coverage already run on pushes to main.

Removed#

  • anira_handler_prepare’s ANIRA_ERROR_NOT_SUPPORTED refusals of ANIRA_BUDGET_MEASURED and ANIRA_WARMUP_UNTIL_STABLE, a fresh contract’s defaults.

  • Breaking: C ABI — ANIRA_EDGE_DEVICE_COPY (1) and ANIRA_EDGE_HOST_COPY (2) of anira_edge_class: a copy within one domain is ANIRA_EDGE_COPY, a CPU–device crossing ANIRA_EDGE_UNIFIED_TRANSFER (unified memory) or ANIRA_EDGE_DEDICATED_TRANSFER (a bus). Migration: ANIRA_EDGE_COPY; a device provider’s former ANIRA_EDGE_HOST_COPY row is the transfer its memory_kind gives.

  • Breaking: C ABI — ANIRA_EDGE_UNAVAILABLE of anira_edge_class: a row’s available (with reason) says whether its edge exists, an unavailable row names the class it would provide, and a pair without a row is ANIRA_ERROR_EDGE_UNREACHABLE. Migration: test anira_edge_info.available where code compared edge_class with ANIRA_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 an anira_edge_class threshold; 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.h is included by anira/anira_all.h, not anira/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_create on, nor 8 MiB per handler (#200; #207 on the web): each handler reserves room for its struct pool at prepare, off the audio thread, whose try_enqueue still 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 through parallel_for despite NoThreadPoolGuard and 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 inside FreeLibrary, under the loader lock, and the unload never returned (LibraryUnload.UnloadWithLiveSessionIsJoinedByHook on 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_error to ANIRA_ERROR_CAPACITY like a dropped hop, not ANIRA_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_latencies and the rings’ priming only go down; a declared latency (anira_contract_hard_set_latency, "latencies") is untouched.

  • Processor: anira_processor_default_post_process reads an output as anira_processor_default_pre_process lays out an input, channels × window, and pushes each channel’s newest hop; as channels × hop it mixed channels or pushed late an output with an overlap (anira_tensor_spec_set_window). A version 2 document whose output exceeds its postprocess_output_size gets such an overlap (the 2.x PrePostProcessor keeps the 2.x push).

  • Web: the ONNX Runtime Web engine’s plan rows (addEngine(ONNXRUNTIME_WEB_ENGINE_ID)) say ANIRA_EDGE_COPY, moved by the engine, not ANIRA_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_create refuses a dtype of 0 (ANIRA_ERROR_INVALID_ARGUMENT); anira_model_config_to_json refuses a dtype without a model-file word (ANIRA_ERROR_NOT_SUPPORTED), where it wrote "float32".

  • Docs: anira_model_config_model_path returns NULL for an entry without a source too (anira_model_config_add_model_path with NULL, ModelConfig::add_model(engine_id)); anira::ModelConfig::model_path throws ANIRA_ERROR_INVALID_STATE for both pathless kinds and ANIRA_ERROR_INVALID_ARGUMENT out of range; anira_em_audio_node_create lists a Streamed slot’s non-float32 ring dtype under ANIRA_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_prepare keys a registered engine’s figure by its id (anira.v2.custom by its engine object), and anira_contract_create_hard / anira_contract_create_async name no edge-cost limit (ANIRA_EDGE_UNKNOWN) as their default, not the removed PERMISSIVE; anira/compat/v2.hpp’s anira::v2::ContextConfig and anira::v2::Context name 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.txt lists 4 draft names and abi/symbols-emscripten.txt 12 Emscripten names; the wasm build exports all three lists and _malloc / _free; new headers anira/abi/context.h, core.h, thread.h.

  • C ABI, headers and enums: <anira/anira_all.h>, the scope-all umbrella, includes every C ABI header, the anira/abi/draft/ headers and anira/anira_em.h, and compiles alone as C11 and C++17; Emscripten-only headers in include/anira/ are empty elsewhere and included by no header of the registry.

  • C ABI, headers and enums: appended ANIRA_MISSED (5, positive) and ANIRA_ERROR_NOT_FOUND (-23, a lookup matching nothing) to anira_status, ANIRA_TENSOR_PLANAR = 8 to anira_tensor_flags, ANIRA_STRUCT_ENGINE_CTX and ANIRA_STRUCT_PLAN_QUERY (13) to anira_struct_id (id 4 is now ANIRA_STRUCT_PROCESSOR_CTX), ANIRA_ROLE_STATE to anira_role, ANIRA_ENGINE_CUSTOM, ANIRA_PROVIDER_NONE, ANIRA_PROVIDER_CPU, ANIRA_PROVIDER_CUSTOM (both enums renumbered, Changed below), and ANIRA_DTYPE_F64 (ANIRA_MAKE_DTYPE(ANIRA_DTYPE_FLOAT, 64, 1), JSON "float64"); new defines ANIRA_INSTANCES_AUTO, ANIRA_VARIANT_ANY and the flags of anira/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 without struct_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 union anira_memory_handle (24 bytes, raw[3]) and anira_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_pinned and the record-only anira_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 above ANIRA_MAX_RANK leaves it all-zero; a NULL fence or a negative sync_fd is ANIRA_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) and anira_tensor_plane; only the Hard entries take it (elsewhere ANIRA_ERROR_NOT_SUPPORTED; anira_tensor_data / anira_tensor_data_f32 return 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), else ANIRA_ERROR_NOT_SUPPORTED; read-only sets ANIRA_TENSOR_READ_ONLY; release calls the deleter once; a refusal leaves *tensor untouched.

  • C ABI, tensor: anira_tensor_data_f32 (host or pinned ANIRA_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 is ANIRA_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 after anira_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 next add_input / add_output) / _default_engine / _state / _max_instances / _anchor / _tensor_name(config, model_index, canonical) / _model_ext / _tensor_layout (counts as anira_handler_get_latencies does); 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_CONTRACT on Async) with the value getter _hard_num_ring_dtypes for the count, anira_contract_edge_cost; anira_context_config_threads / anira_context_config_log (anira_log_desc); value getters take no anira_error*.

  • C ABI, configuration: providers twin the engines: one anira_provider does not name travels as the string provider_id, like engine_id; anira_backend_id and anira_plan_info gain provider_id, anira_engine_load_info provider, provider_id, option_keys / option_values / num_options (one load per provider; an unservable one is ANIRA_ERROR_NOT_SUPPORTED), anira_engine_desc providers / 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_provider pin an entry to the provider its file is built for; JSON spells the pair as two keys, like anira_backend_id, anira_provider_option_set and anira_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_provider and 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 is ANIRA_ERROR_CONFIG at anira_handler_create; unavailable here, it falls back to the default engine’s first plan, else plan 0, with a Warning at anira_handler_prepare; ANIRA_PROVIDER_NONE sets none.

  • C ABI, configuration: the context extension "provider_options" (version 1; anira_ext_provider_options, ANIRA_EXT_PROVIDER_OPTIONS_INIT; C++ anira::ext::ProviderOptions via ContextConfig::ext): per backend an anira_provider_option_set (ANIRA_PROVIDER_OPTION_SET_INIT, num_options string pairs); JSON {"sets": [{"engine": "onnxruntime", "provider": "cuda", "options": {"device_id": "0"}}]}; a malformed set is ANIRA_ERROR_INVALID_ARGUMENT at anira_context_config_set_ext and at parse; sets for ANIRA_PROVIDER_NONE, the CPU path or an engine not reading "context:provider_options" are refused (a custom one receives anira_engine_load_info.option_keys / option_values, C++ EngineLoadInfo::option_keys() / option_values()); an unserved provider is ANIRA_ERROR_NOT_SUPPORTED.

  • C ABI, configuration: anira_contract_set_host_domain ([main-thread], like anira_contract_set_edge_cost) declares a tensor’s host-end domain (default ANIRA_DOMAIN_HOST), reported as domain_in / domain_out; a bad anira_domain is ANIRA_ERROR_INVALID_ARGUMENT, an unknown name is ANIRA_ERROR_CONFIG and a non-host domain ANIRA_ERROR_NOT_SUPPORTED at anira_handler_prepare for 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_latency declares a Hard output’s stream latency for anira_handler_get_latency / _get_latencies and its ring priming (the 2.x InferenceHandler::prepare(host_config, custom_latency, ...), unclamped); above INT32_MAX is ANIRA_ERROR_INVALID_ARGUMENT, Async ANIRA_ERROR_WRONG_CONTRACT, below the spec’s latency or on an input, a non-Streamed or an unknown output ANIRA_ERROR_CONFIG at anira_handler_prepare; read-back anira_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_max are doubles (the 2.x samplesPerBlock / 2048.f idiom), read as the rational LatencyCalculator::rationalize finds; both 0, or finite and > 0 with min <= max, else ANIRA_ERROR_INVALID_ARGUMENT (anira_contract_create_hard, anira_contract_hard_set_host_blocks; ANIRA_ERROR_JSON in a file); a call carries floor(b) or ceil(b) samples, an uncovered pop is ANIRA_MISSED.

  • C ABI, configuration: anira_vulkan_desc gains int32_t device_index (beside queue_index) and uint32_t reserved, also in ANIRA_VULKAN_DESC_INIT and JSON vulkan.device, so the index anira_context_config_set_vulkan sets survives anira_context_config_to_json; a positional initializer that spells every member now draws -Wmissing-field-initializers (two members more); the _INIT macro 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_SINK and ANIRA_LOG_FLAG_TRACE_FAILURES while it lives; a device block is ANIRA_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) and anira_drain_log (anira/abi/log.h; C++ anira::drain_log(), anira::num_inference_threads() in anira/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_shutdown is ANIRA_ERROR_INVALID_STATE while 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 an anira_context*) / run_loop / execute / start / stop / has_exited / should_exit / is_running / destroy; start is ANIRA_ERROR_INVALID_STATE while running, ANIRA_ERROR_OUT_OF_MEMORY when the system refuses the thread (InferenceThread::start() a bool).

  • 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_INCOMPLETE when short, Host rows only), a row per compiled-in engine and provider its runtime reports usable, ANIRA_PROVIDER_CPU first (ONNX Runtime’s providers, unknown ones as ANIRA_PROVIDER_CUSTOM; LiteRT’s "gpu", "npu", "webnn" where ANIRA_LITERT_ACCELERATOR_QUERY is set, all but the Windows DLL; ExecuTorch’s delegates; LibTorch and TFLite CPU only); anira_context_probe asks again; anira_handler_create admits exactly the reported providers.

  • C ABI, context: anira_edge_info gains to_provider_id and anira_edge_info.to_engine_id (ANIRA_EDGE_INFO_INIT); a row’s host edge is zero-copy ANIRA_RUNG_STATIC to the CPU path and XNNPACK, an engine-made copy ANIRA_RUNG_IDENTITY to a device; anira_capabilities_edge matches custom providers by name; custom engines’ rows come from anira_pipeline_capabilities_backends(pipeline, context, element_size, count, out) and anira_pipeline_capabilities_edge (C++ Pipeline::capabilities(context), anira::PipelineCapabilities).

  • C ABI, context: an anira_log_fn on a context config receives the platform sink’s records as anira_log_record (flags with ANIRA_LOG_RECORD_REALTIME / ANIRA_LOG_RECORD_CONTRACT_VIOLATION, dropped_before, …) at the context’s level, over one thl::Logger; anira_context_destroy waits 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 is ANIRA_ERROR_INVALID_STATE), owning the phases it fills; anira_processor_desc (Tier 2, ANIRA_PROCESSOR_DESC_INIT: struct_size, abi_version, user_data, consumed_kinds as "<host>:<kind>", flags, nine slots) lives in a refcounted carrier, so release fires once; no name, no domain.

  • C ABI, processor: ANIRA_PROCESSOR_FLAG_REALTIME_PRE_POST = 1u (pre_process, post_process) and ANIRA_PROCESSOR_FLAG_REALTIME_HOOKS = 2u (before_inference, after_inference) promise no allocation, lock or block; under Hard a filled pre_process, post_process or reset needs PRE_POST (ANIRA_ERROR_CONFIG at prepare); an unknown bit is ANIRA_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 fails anira_handler_prepare; the engine adds ANIRA_PHASE_LOAD = 10 / ANIRA_PHASE_UNLOAD = 11; a chunk runs pre_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, flags with ANIRA_PREPARE_EXCLUSIVE = 1u when an ANIRA_MODEL_STATEFUL model or a declared State pair runs one inference at a time, in order) and anira_init_info (ANIRA_INIT_INFO_INIT: log_level, num_threads as anira_num_inference_threads, the first preparing handler’s context).

  • C ABI, processor: anira_processor_ctx (Tier 1, 64 bytes, ANIRA_STRUCT_PROCESSOR_CTX): phase, engine / provider with engine_id / provider_id, variant, num_inputs, num_outputs, ticket (ANIRA_TICKET_INVALID under Hard), entry (0 .. anira_handler_num_entries(handler) - 1, a per-chunk scratch index), frame; anira_handler_num_entries is [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_FORCE32 on 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 is ANIRA_ERROR_INVALID_STATE, a bad slot or NULL out ANIRA_ERROR_INVALID_ARGUMENT, latched into anira_handler_rt_error.

  • C ABI, processor: anira_ring with anira_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 latches ANIRA_ERROR_CONFIG); the defaults anira_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 refcounted anira_custom_engine under 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 slot ctx->instance or, under ANIRA_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 under ANIRA_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, over anira_engine_load_info (ANIRA_ENGINE_LOAD_INFO_INIT: variant, row, engine-side templates and names, num_inputs, num_outputs, instances = max_instances clamped 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, unload and init must 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 under ANIRA_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 failed process latches ANIRA_ERROR_ENGINE and 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_ARGUMENT for NULLs, an id without . or starting anira. (except anira.v2.custom, the 2.x custom backend’s id, used by "CUSTOM" rows and anira/compat/v2.hpp), a short struct_size, an unknown flag or no process; ANIRA_ERROR_ABI_VERSION per anira_check_abi; no release on refusal; anira_pipeline_add_engine (a duplicate id is ANIRA_ERROR_INVALID_STATE) holds a reference; anira_custom_engine_detach stops the handle keeping it alive.

  • C ABI, engine: an entry with ANIRA_ENGINE_CUSTOM and 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: instances 0, 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.custom too, is ANIRA_ERROR_NOT_SUPPORTED at anira_handler_create; reports gain anira_plan_info.engine_flags and anira_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_create asks once per engine and refuses a cleared provider (ANIRA_ERROR_NOT_SUPPORTED), anira_handler_prepare reuses 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&) returns std::unique_ptr<Engine::Loaded>, whose prepare(const PrepareInfo&) returns std::unique_ptr<Engine::Prepared> (process, reset; EngineContext::loaded()); Processor::init(const InitInfo&) / Engine::init(const InitInfo&) are empty virtuals; anira::Engine takes its id (explicit Engine(std::string id)); a bad id throws ANIRA_ERROR_INVALID_ARGUMENT at the first addition; an addition to a pipeline that already has the id throws ANIRA_ERROR_INVALID_STATE.

  • C ABI, handler (anira/abi/handler.h): anira_pipeline (anira_pipeline_create / add_inference / destroy: one stage and variant; anira_backend_id candidates or, for NULL, every engine of the build on the CPU path plus the custom engines and pinned providers the entries name) and anira_handler (anira_handler_create, anira_handler_destroy); anira_handler_prepare takes a Hard contract, inits the processor, checks providers, loads, sizes rings, builds the plan report and publishes last (a racing call is ANIRA_ERROR_NOT_PREPARED); anira_shutdown is refused while a handler lives; its test oracle matched the 2.x anira::InferenceHandler bit 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_ext via anira_handler_plan_report and anira_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, so anira_handler_get_plan names 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 _wait twins ([any-thread, blocking]) take timeout_ms, ANIRA_WAIT_CONTRACT (wait_ratio times the block) or ANIRA_WAIT_FOREVER, and are ANIRA_ERROR_INVALID_STATE without an inference thread.

  • C ABI, handler: anira_handler_get_latency / get_latencies (0 if not Streamed), anira_handler_get_available_samples (a status and a size_t*; Static and State outputs too, as 2.x get_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_CAPACITY per dropped hop); prepare refuses Async contracts, ANIRA_BUDGET_MEASURED and ANIRA_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:coreml plus onnxruntime is two); entries are unique per (engine, id, pin); the default set puts a neutral entry on its engine’s home provider; anira_pipeline_add_inference checks a provider’s syntax (ANIRA_ERROR_INVALID_ARGUMENT), anira_handler_create its availability (ANIRA_ERROR_NOT_SUPPORTED); the provider is part of the loaded model, in anira_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 an anira_plan_query (Tier 2, ANIRA_STRUCT_PLAN_QUERY, ANIRA_PLAN_QUERY_INIT: a variant, ANIRA_VARIANT_ANY = 0xffffffffu for all, and an anira_backend_id, ANIRA_ENGINE_NONE / ANIRA_PROVIDER_NONE for all); [thread-safe], ANIRA_NONBLOCKING, allocation-free; no match is ANIRA_ERROR_NOT_FOUND, a bad argument ANIRA_ERROR_INVALID_ARGUMENT; C++ anira::PlanQuery (report.find({.backend = {.engine = ANIRA_ENGINE_ONNXRUNTIME, .provider = ANIRA_PROVIDER_COREML}})), PlanReport::find(const PlanQuery&) const noexcept returning std::optional<uint32_t>.

  • C ABI, handler: each successful anira_handler_prepare logs its plan report at Info (group anira.capi): a head line, then a record per plan, slot and consumed extension; visible at ANIRA_LOG_INFO / ANIRA_LOG_DEBUG, compiled out under ANIRA_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_multi and the _wait twins anira_handler_process_wait, process_multi_wait, anira_handler_pop_data_wait, pop_data_multi_wait (plus double timeout_ms); no float-only family (wrap channel pointers with anira_tensor_init_host_planar), no _inplace variant (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 and anira_processor_input_role, anira_processor_input_ring, anira_processor_input_tensor and twins; Streamed slots take block calls, Static ones anira_handler_set_static_input / anira_handler_get_static_output or a _multi element, State ones none, else ANIRA_ERROR_INVALID_ARGUMENT; anira_plan_slot.role gives the slot’s anira_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 is ANIRA_ERROR_CONFIG, a malformed descriptor (rank, a domain but ANIRA_DOMAIN_HOST / ANIRA_DOMAIN_HOST_PINNED, an ANIRA_TENSOR_READ_ONLY output, shape[0], memory, strides) ANIRA_ERROR_INVALID_ARGUMENT, an unknown flag ANIRA_ERROR_NOT_SUPPORTED; an empty tensor skips its slot (tests: the private anira::PlanarFloatAdapter).

  • C ABI, handler: the _multi forms take one tensor per slot (other counts are ANIRA_ERROR_INVALID_ARGUMENT; empty at State slots) and mean set_static_input per non-empty Static input, the streamed call, get_static_output per non-empty Static output, all validated first; delivered (nullable, always written): a Streamed output’s shape[1] on ANIRA_OK and 0 on ANIRA_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 _wait twin’s ANIRA_ERROR_INVALID_STATE, what the nonblocking entry delivered.

  • C ABI, handler: ANIRA_MISS_CALLBACK = 3 (anira_miss_policy, "on_miss": "callback") with anira_contract_hard_set_miss_fn (anira/abi/config.h now includes anira/abi/tensor.h; ANIRA_ERROR_WRONG_CONTRACT on Async) and anira_miss_fn (ANIRA_CALL, (handler, inputs, num_inputs, outputs, num_outputs, user_data) to anira_status, the first ANIRA_NONBLOCKING function-pointer typedef): once per missed block or dropped hop over the call’s own arrays, Static outputs prefilled; a non-ANIRA_OK return zero-fills; the entry returns ANIRA_MISSED; it must not call the handler’s Hard entries, anira_handler_reset or anira_handler_prepare; a NULL fn clears 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 function anira_handler_prepare is ANIRA_ERROR_CONFIG, and it refuses ANIRA_MISS_BYPASS across 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_PINNED too) in a tear-free store zeroed at anira_handler_create, kept through prepare and reset; inputs reach chunks before pre_process, outputs are captured after post_process (not from zeroed chunks) and hold under ANIRA_MISS_ZEROS, ANIRA_MISS_HOLD_LAST, ANIRA_MISS_BYPASS; refusals (ANIRA_ERROR_INVALID_ARGUMENT for a bad slot, shape, memory or an ANIRA_TENSOR_READ_ONLY output, ANIRA_ERROR_NOT_SUPPORTED for ANIRA_TENSOR_PLANAR, ANIRA_ERROR_CONFIG for dtype) latch in anira_handler_rt_error; a Buffer spec under Hard is ANIRA_ERROR_NOT_SUPPORTED at anira_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" or anira_tensor_spec_set_state_source(spec, output_canonical), like anira_tensor_spec_set_latency: ANIRA_ERROR_INVALID_ARGUMENT off a State spec, ANIRA_ERROR_JSON on an output; anira_model_config_to_json writes it); anira runs the feedback over two handler-owned buffers per pair, zeroed at anira_handler_create, anira_handler_prepare and anira_handler_reset, flipped after each good inference (anira copies nothing; each engine binds the buffers as it binds any slot); the model runs as ANIRA_MODEL_STATEFUL; the state survives anira_handler_set_plan.

  • C ABI, handler: before_inference sees the read half (anira_processor_input_tensor), after_inference the write half (anira_processor_output_tensor); under ANIRA_ENGINE_FLAG_STATE_ALIAS one stable buffer is both halves; the buffers are host memory in this pre-release (a non-host anira_contract_set_host_domain declaration stays ANIRA_ERROR_NOT_SUPPORTED); a reset zeroes the state at the new stream’s first inference and runs both reset slots (TFLite resets its variable tensors); ANIRA_ERROR_CONFIG at 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 is ANIRA_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 registry globalThis[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_VERSION 2), never Module.anira; anira_em_processor_desc_init(desc, js_key, hook_mask, processor_flags) fills an anira_processor_desc with a trampoline per hook bit (ANIRA_EM_PROCESSOR_HOOK_* = 1u << ANIRA_PHASE_* by static_assert: ANIRA_EM_PROCESSOR_HOOK_PRE 1, ANIRA_EM_PROCESSOR_HOOK_AFTER 16 = anira::Processor::k_after_inference, ANIRA_EM_PROCESSOR_HOOK_PREPARE 32, …) and anira_em_pipeline_add_js_processor(pipeline, js_key, hook_mask, processor_flags, err) adds one.

  • C ABI, Emscripten companion: anira_em_engine_desc_init fills an anira_engine_desc (process, plus reset / query by ANIRA_EM_ENGINE_HOOK_RESET 1 / _QUERY 2) and anira_em_pipeline_add_js_engine creates and adds it; a throwing hook is logged with console.error (rate-limited) and fails the call (ANIRA_ERROR_UNKNOWN for a processor, ANIRA_ERROR_ENGINE for an engine); anira_em_set_log_hook adds the registry’s log as 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 provider Ort::GetAvailableProviders() lists (never Vulkan) ahead of the CPU one, a refused append being ANIRA_ERROR_NOT_SUPPORTED; LiteRT takes an accelerator by hardware name as ANIRA_PROVIDER_CUSTOM ("gpu", "npu", on the web "webnn"); ExecuTorch serves registered delegates that report is_available, and a pinned export whose method lacks its delegate is ANIRA_ERROR_CONFIG at load.

  • Web: the TypeScript layer mirrors anira.hpp in 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 thrown AniraError); InferenceHandler.prepare(contract) / audioNode.prepare(contract) return the PlanReport (numPlans(), plans(), slots(plan, inputs), extensions(plan), native(), as anira::PlanReport; again via planReport()), so create, then prepare; new rtError(), setPlan(plan) / getPlan(), numEntries(), handler.getLatencies() beside handler.getLatency(slot); setStaticInput takes the spec’s dtype.

  • Extras and examples: extras/models/hybrid-nn/HybridNNProcessor.h (HybridNNProcessor, an anira::Processor popping its windows with one RingView::pop_windows), extras/models/BypassEngine.h (BypassEngine, org.anira.examples.bypass, ANIRA_ENGINE_FLAG_NEEDS_NO_MODEL) and examples/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 replaces CNNPrePostProcessor).

  • ABI tooling and gates: presence gates anira_abi_link (every promised and draft entry point links against anira::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, one ANIRA_NONBLOCKING C 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_PTR slots marked.

  • C++ (anira/anira.hpp, not ABI-stable): anira::Context (over anira_context_create, from an anira::ContextConfig; capabilities(), probe(), byte_image_bytes()), anira::Capabilities (edge() throws ANIRA_ERROR_EDGE_UNREACHABLE), anira::BackendId, anira::enabled_engines(), anira::now_ms() / now_ns(), the free anira::drain_log() / anira::num_inference_threads(), anira::shutdown() / release_core_if_idle() / has_core(); anira::Context was alpha.1’s 2.x singleton.

  • C++ (anira/anira.hpp, not ABI-stable): anira::Tensor / anira::SyncToken (a Tensor* is an anira_tensor*, static_asserted): noexcept factories Tensor::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 past ANIRA_MAX_RANK), Tensor::from_dlpack (throws anira::Error), Tensor::from_host_planar<T> (a const element sets ANIRA_TENSOR_READ_ONLY), data_f32(), data(DType), num_elements(); SyncToken is not RAII. Draft factories stay C (anira_tensor_init_metal on a Tensor); no anira_all.hpp.

  • C++ (anira/anira.hpp, not ABI-stable): anira::Pipeline (move-only, over anira_pipeline_create, one chaining member per C entry: p.add_engine(e).add_inference(model).add_processor(s);) and anira::PlanReport (rows as vectors, no to_json); add_inference(model, {candidates}) takes BackendIds (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&) over anira_handler: prepare(Hard | Async | Contract | ContractHandle) returning the PlanReport, plan_report(), num_entries(), the noexcept ANIRA_NONBLOCKING Hard forwarders over Tensor (process, push_data, pop_data, process_wait, pop_data_wait; planar floats via Tensor::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 of set_model / set_backend: select a plan of the report); anira::InferenceThread(Context&) over anira_inference_thread for 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 over anira/abi/processor.h: anira::Processor (phases() of Processor::k_pre_process, k_post_process, k_before_inference, k_after_inference, Processor::phase_bit(phase) into the anira_processor_desc; flags() into anira_processor_desc::flags, a Hard pre_process / post_process needing ANIRA_PROCESSOR_FLAG_REALTIME_PRE_POST (else ANIRA_ERROR_CONFIG at anira_handler_prepare), and ANIRA_PROCESSOR_FLAG_REALTIME_HOOKS; consumed_kinds(), init(const InitInfo&), Processor::prepare(const PrepareInfo&) to a std::unique_ptr<Processor::Prepared>), anira::Processor::Prepared (noexcept pre_process, post_process, before_inference, after_inference on a ProcessorContext& to an anira_status, and noexcept reset(ProcessorContext&); defaults anira_processor_default_pre_process / anira_processor_default_post_process), anira::PrepareInfo (anira_prepare_info: handler() an anira_handler*, num_entries(), input_names(), output_names(), exclusive() for ANIRA_PREPARE_EXCLUSIVE), anira::InitInfo (anira_init_info: log_level() an anira_log_level, num_threads(), context() an anira_context*), anira::ProcessorContext (anira_processor_ctx: phase(), engine(), provider(), variant(), ticket(), num_inputs(), num_outputs(), entry() below anira_handler_num_entries, input_role(slot, Role&), output_role, input_ring(slot, RingView&), output_ring, input_tensor(slot, Tensor&), output_tensor), anira::RingView (anira_ring over std::span<T> by anira_dtype; pop_windows), anira::Pipeline::add_processor(std::make_shared<MyProcessor>()) (a std::shared_ptr<Processor> as user_data, an out_prepared per handler; a second is ANIRA_ERROR_INVALID_STATE, bad bits or null ANIRA_ERROR_INVALID_ARGUMENT), anira::TensorSpec::state_source(output_canonical) (anira_tensor_spec_set_state_source). A throw fails the prepare with the anira::Error’s status, ANIRA_ERROR_OUT_OF_MEMORY (std::bad_alloc) or ANIRA_ERROR_INTERNAL.

  • C++ (anira/anira.hpp, not ABI-stable): custom engines over anira/abi/engine.h: anira::Engine (explicit Engine(std::string id), id(), named by ModelConfig::add_model_path(id, path), an ANIRA_ENGINE_CUSTOM plan with every slot ANIRA_BINDING_ENGINE; flags() from ANIRA_ENGINE_FLAG_* into anira_engine_desc::flags and anira_plan_info::engine_flags; consumed_kinds(), init(const InitInfo&), load(const EngineLoadInfo&) ([main-thread], once per pooled model) to a std::unique_ptr<Engine::Loaded>), anira::Engine::Loaded (prepare(const PrepareInfo&) to a std::unique_ptr<Engine::Prepared>), anira::Engine::Prepared (noexcept process(EngineContext&), reset(EngineContext&)), anira::EngineLoadInfo (anira_engine_load_info: model() an anira_model_config*, model_count(), model_engine(i) an anira::EngineRef, model_path(i), model_bytes(i), input_names(), output_names()), anira::EngineContext (anira_engine_ctx: instance(), exclusive() for ANIRA_ENGINE_CALL_EXCLUSIVE, outputs() as std::span<Tensor>), the enum EngineKind, anira::Pipeline::add_engine(std::make_shared<MyEngine>()), whose first call creates the object’s anira_custom_engine (anira_custom_engine_create, the std::shared_ptr<Engine> as user_data, out_loaded per 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_engine refuses a null engine, an id without a . or prefixed anira. and a flags() bit outside anira/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 over anira/abi/config.h: anira::SpecView (every spec field, time_ratio(), state_source(), {ANIRA_AXIS_ANY, 0} for a hole) from TensorSpec::view() and ModelConfig::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’s k_kind), indexed ones ANIRA_ERROR_INVALID_ARGUMENT out of range. anira::Hard gains anira::Hard::miss_fn / miss_user_data after on_miss (anira_contract_hard_set_miss_fn, ANIRA_NONBLOCKING, called on the driver thread; it and what miss_user_data points at outlive the prepared handler) and ring_dtypes (std::map<std::string, DType>) / latencies between wait_ratio and edge_cost (anira_contract_hard_set_ring_dtype / anira_contract_hard_set_latency); anira::ContractHandle::hard_miss_fn(fn, user_data), hard_latency(canonical, samples) beside hard_ring_dtype; ContractHandle::hard() reads any Hard handle (take_legacy_contract’s, a loaded one) back, an anira::Budget rounded to the nanosecond, not a truncating duration_cast (ANIRA_ERROR_WRONG_CONTRACT on 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 return anira::EngineRef{kind, id} / anira::ProviderRef{kind, id} (id for 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 over anira/abi (C++20), included in place of <anira/anira.h>, with using namespace anira::v2;: InferenceBackend (anira_engine values; to_engine / to_backend / is_available; CUSTOM is ANIRA_ENGINE_CUSTOM with k_custom_engine_id "anira.v2.custom"), ModelData, TensorShape, ProcessingSpec, InferenceConfig (via anira::ModelConfig::from_json; model_config(), model_config_copy()), JsonConfigLoader, ContextConfig (to_context_config()), HostConfig, LogConfig, RingBuffer, BufferF, PrePostProcessor, LegacyProcessor (a 2.x processor as an anira::Processor), PassthroughEngine (BackendBase::process as an anira::Engine, anira.v2.custom) and InferenceHandler (every 2.x member over one anira_handler, on an anira::Engine& or the PassthroughEngine). anira::v2::InferenceHandler::prepare takes a fractional HostConfig::m_buffer_size (host_block_min half the block when smaller blocks come and the block is one sample or less), a non-finite or non-positive one is ANIRA_ERROR_CONFIG; InferenceHandler::set_inference_backend / get_inference_backend run while audio runs, never during prepare() or the destructor, as anira_handler_set_plan (#202). The migration page lists the differences from 2.x (anira::Error, no load before prepare, non-waiting push_data).

  • Web (module, anira/anira_em.h): inference threads are Wasm Workers, so anira_context_config_set_threads and ANIRA_THREADS_AUTO (half the cores) size a real pool and anira_inference_thread_start starts a Worker; anira_em_context_config_set_worker_module(config, url, err) names their module (the first context’s wins) and a page waits for anira_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_status ANIRA_INCOMPLETE until created, input / output k serves the k-th listed slot (NULL for a side: every Streamed slot in slot order), one copy-free anira_handler_process_multi per quantum (as anira_handler_process advises); ANIRA_MISSED keeps the miss fill. Refused: a block range without the quantum, a non-Streamed or repeated slot, a non-float32 ring, an unserved Streamed slot (unless ANIRA_EM_AUDIO_NODE_FLAG_PARTIAL_STREAMS). Static float32 scalars are AudioParams, other Static tensors go through anira_em_audio_node_set_static_input to anira_handler_set_static_input; anira_em_audio_node_hold, anira_em_audio_node_prepare (while a node streams, anira_handler_prepare is ANIRA_ERROR_INVALID_STATE), anira_em_audio_node_destroy; exports emscriptenGetAudioObject.

  • Web (module, build): the glue runs under Vite’s dev server: a post-link step of AniraWeb routes new Worker(new URL("AniraWeb.js", import.meta.url)) through locateFile and marks the Wasm Workers’ import @vite-ignore.

  • Web (package, @anira-project/anira): the typed layer, mirroring anira.hpp in camelCase: Anira.create({ memory, wasmBinary, abiVersion }) (setLogSink, drainLog, startLogPump), Context.create(anira, { threads, workerModule, logLevel, json }) (numInferenceThreads(); default ANIRA_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 the PlanReport, getLatency, setStaticInput, createAudioNode), ModelConfig, ContractHandle, defineProcessor (Processor, ProcessorFactory, ProcessorOptions, Registry.defineProcessor, Registry.processor, registry.processor), defineEngine, keyOf, engineTensors.

  • Web (package, @anira-project/anira): generated AniraBindings, one typed method per module entry point under its C name, throwing a failed anira_status as an AniraError (via anira_error), an anira_bool as a boolean; anira.abi is the main instance’s, a scope’s is in its ScopeEnv. The module exports stringToUTF8OnStack, 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 in anira_enabled_engines (enabledEngines) or custom (anira_model_config_set_model_bytes); fetchModel, a Fetcher, fromJson (with baseUrl), setModelBytes, toJson. ContractHandle.fromUrl / fromJson read a *.contract.json (anira_contract_from_json), ContractHandle.hard(anira, { hostBlockMin, hostBlockMax, hostRate, budgetMs, warmupIterations }) builds one, hardHostBlocks fills open host blocks; extras/models/model-pool/gain.model.json / gain.contract.json load unchanged.

  • Web (package, @anira-project/anira; decision 10.19): PlanReport.find(query?) over anira_plan_report_find with a PlanQuery ({ variant?, engine?, engineId?, provider?, providerId? }, anira::PlanQuery flattened, an anira_plan_query on the stack; an omitted field matches every plan: ANIRA_VARIANT_ANY, ANIRA_ENGINE_NONE, ANIRA_PROVIDER_NONE), returning the InferenceHandler.setPlan index or null (ANIRA_ERROR_NOT_FOUND), an AniraError (ANIRA_ERROR_INVALID_ARGUMENT) against the pair rule. Pipeline.addEngine calls anira_em_pipeline_add_js_engine.

  • Web (package, @anira-project/anira): handler.createAudioNode(audioContext, options) / createAudioNode returns an AniraAudioNode (node, params, setStaticInput, prepare, hold, destroy) on any BaseAudioContext; options inputSlots / 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 one Promise shared by concurrent creations.

  • Web (package, @anira-project/anira): measureRenderGeometry(context, { hold? }): a Hard contract’s geometry behind an audio node, never from baseLatency: quantum (renderQuantumSize, else 128; a "hardware" context reporting 0 is refused) and the measured burst (a probe AudioWorklet on an AudioContext, timed with performance.now() by a Worker woken through Atomics.wait, not the worklet’s Date.now), holding the listed AniraAudioNodes meanwhile (AniraAudioNode.hold). Nothing re-prepares on its own: after a device change, re-measure and re-prepare through the node (handler.prepare is 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 a Uint8Array view), and an optional load(model) hook runs per Worker before a loaded model’s first call; ModelConfig.fromUrl attaches 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’s ONNXRuntimeWebBackend: without model the session comes from the entry’s bytes, with it from a fetch at init (fetchModel: () => false on ModelConfig.fromUrl then); warmup inferences over zeros (default 0; a contract’s warm-up skips JavaScript engines); numThreads intra-op threads (default 1; one _OrtInit(numThreads) per runtime: an engine asking for another count than its worker module’s fails its init, as does a count that is not a whole number of at least 1; native: #222). ONNXRUNTIME_WEB_ENGINE_ID has 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 preset wasm-abi (wasm-release plus it) builds the header, layout and smoke gates, which anira_abi_wasm_gates runs under node (the smoke driven by anira_inference_thread_execute; a user Worker running anira_inference_thread_run_loop while main calls anira_handler_process_wait); build_web also checks every registry symbol, _malloc and _free are exported. A throwing JavaScript hook prints at most one console.error per second per module instance.

  • Web (tests and CI): a browser test of the built package: every feature’s page (live.html in 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/ (a defineProcessor gain processor with an allocation-free preProcess, a doubling defineEngine worker module) and web/examples/model-file/ (extras/models/model-pool/gain.model.json and 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 a thl symbol outside thl::anira, a moodycamel one outside anira_moodycamel, or no thl::anira symbol at all.

  • ABI gates: gate 5, the installed package from C and beside a host’s tanh-lib: consumer_c (C11, anira_check_abi to anira_shutdown, an ANIRA_ENGINE_FLAG_NEEDS_NO_MODEL engine, one anira_handler_process) and consumer_tanh_first (a host’s own shared tanh-lib linked first: its thl::Logger and 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 forbids anira_* 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_contract and consumer_c; the desktop-tests-rtsan preset is the run-time half.

  • Bundled models: the State fixture extras/models/model-pool/stateful_accumulator.model.json / .contract.json (also in extras/models/model_files.h; extras/fetch-models.cmake pin d1bc5cf): example-models’ StatefulAccumulatorNetwork, a stereo 64-sample stream with a declared State pair ("role": "state", "state_source": "state_out") and a closed form, also after anira_handler_reset and warm-up; a row per engine (five).

Changed#

  • Breaking: C ABI — <anira/anira.h> is the C11 umbrella of anira/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_FORCE32 is anira_phase / ANIRA_PHASE_FORCE32: ANIRA_PHASE_PRE_PROCESS 0, ANIRA_PHASE_POST_PROCESS 1, ANIRA_PHASE_BEFORE_INFERENCE 2, new ANIRA_PHASE_INFERENCE 3 (the engine call), ANIRA_PHASE_AFTER_INFERENCE 4 (was 3), ANIRA_PHASE_PREPARE 5 (was 4), ANIRA_PHASE_RELEASE 6 (was 5), new ANIRA_PHASE_RESET 7, ANIRA_PHASE_UNPREPARE 8, ANIRA_PHASE_INIT 9, ANIRA_PHASE_LOAD 10, ANIRA_PHASE_UNLOAD 11, ANIRA_PHASE_QUERY 12, in anira_processor_ctx.phase (side-neutral like anira_init_info, anira_prepare_info). Migration: spell anira_phase (anira::ProcessorContext::phase(), anira::Processor::phase_bit), rebuild against anira/abi/enums.h.

  • Breaking: C ABI — anira_engine and anira_provider share one order: ANIRA_ENGINE_NONE 0, ANIRA_ENGINE_ONNXRUNTIME 1, ANIRA_ENGINE_EXECUTORCH 2 (was 5), ANIRA_ENGINE_LITERT 3 (was 4), ANIRA_ENGINE_LIBTORCH 4 (was 2), ANIRA_ENGINE_TFLITE 5 (was 3); new ANIRA_PROVIDER_NONE 0 and ANIRA_PROVIDER_CPU 1, ANIRA_PROVIDER_CUDA 2 (was 1), ANIRA_PROVIDER_WEBGPU 3 (was 2), ANIRA_PROVIDER_VULKAN 4 (was 6), ANIRA_PROVIDER_DIRECTML 5 (was 3), ANIRA_PROVIDER_COREML 6 (was 4), ANIRA_PROVIDER_XNNPACK 7 (was 5); ANIRA_ENGINE_CUSTOM / ANIRA_PROVIDER_CUSTOM are 0x7FFFFFFE; ANIRA_PROVIDER_DEFAULT is removed; the 2.x anira::InferenceBackend keeps its values. Migration: rebuild; map stored numbers by name.

  • Breaking: C ABI — ANIRA_PROVIDER_NONE is no provider, the zero of ANIRA_BACKEND_ID_INIT, ANIRA_PLAN_INFO_INIT, ANIRA_EDGE_INFO_INIT, ANIRA_PROVIDER_OPTION_SET_INIT (unpins in anira_model_config_set_model_provider, clears in anira_model_config_set_default_provider, ANIRA_ERROR_INVALID_ARGUMENT as a candidate or in a provider option set); ANIRA_PROVIDER_CPU ("cpu") is the plain CPU path, each built-in engine’s first row, as anira_plan_info and anira_engine_load_info report it. Default candidates: every engine on CPU, each named custom engine, every pin (an unservable plan is dropped, a variant without one is ANIRA_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_DEFAULT is ANIRA_PROVIDER_CPU, or ANIRA_PROVIDER_NONE for no default (JSON: no key); an _INIT or zeroed candidate sets ANIRA_PROVIDER_CPU; a custom engine that relied on the default provider lists "cpu"; anira::ProviderRef{} and ProviderOptions::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 is ANIRA_ENGINE_CUSTOM / ANIRA_PROVIDER_CUSTOM (alpha.1: ANIRA_ENGINE_NONE plus id), else ANIRA_ERROR_INVALID_ARGUMENT, also in anira_pipeline_add_inference; anira_enabled_engines never lists CUSTOM. anira_model_config_add_model_path(config, engine, engine_id, path, out_index, err) (was utf8_path, no id), anira_model_config_add_model_bytes and anira_model_config_set_default_engine (gains anira_error*) take the pair, replacing anira_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 (absorbing anira_model_config_model_engine_id) and the new anira_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_provider return a status and write the pair on ANIRA_OK. C++: the getters (model_engine, default_engine, model_provider, default_provider, EngineLoadInfo, ProcessorContext) return anira::EngineRef / anira::ProviderRef, model_engine_id and every *_id() getter go, add_model_path / add_model_bytes keep their overloads. Migration: _custom(cfg, id, ...) is the plain entry with ANIRA_ENGINE_CUSTOM, id (built-ins pass NULL); a candidate {ANIRA_ENGINE_NONE, NULL} does not stand for every custom entry: name each custom engine by its id; C++ reads model_engine(i).id.

  • Breaking: C ABI — the core’s handle is the context: anira_machine_config / anira_machine are anira_context_config / anira_context, each anira_machine_config_* entry of anira/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-parameter anira_context_config_* twin (anira_context_config_create, anira_context_config_destroy, anira_context_config_from_json, anira_context_config_to_json, …), anira_inference_thread_create takes an anira_context* (new: anira_context_create, byte_image_bytes and the rest of anira/abi/context.h), anira/anira.hpp’s MachineConfig is ContextConfig (runtime Context), the machine file the context file. Migration: machine becomes context.

  • Breaking: C ABI — the Hard geometry is the host blocks (double, anchor elements per anira_model_config_set_anchor; wait_ratio unchanged): anira_contract_create_hard takes host_block_min, host_block_max, host_rate (were uint32_t block_min, block_max and double rate), anira_contract_hard_set_geometry is anira_contract_hard_set_host_blocks, the new anira_contract_hard_host_blocks reads them back, anira::Hard::block_min / block_max / rate are anira::Hard::host_block_min / host_block_max / host_rate, anira::ContractHandle::hard_geometry is ContractHandle::hard_host_blocks, and the "hard" keys "block_min", "block_max", "rate" are "host_block_min", "host_block_max", "host_rate" (old keys ANIRA_ERROR_JSON); host_block_min = 0 beside a non-zero maximum is refused. Migration: rename (contract.hard_host_blocks(1, samplesPerBlock, sampleRate)); a fixed block sets host_block_min = host_block_max; HostConfig and the web’s measureRenderGeometry keep 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) and anira_model_config_set_tensor_name(config, model_index, canonical, export_name) rename a parameter (was context, 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 below host_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 is ANIRA_ERROR_CONFIG at anira_handler_prepare. Migration: a flexible window at another rate than the anchor declares its time_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.binding reports ANIRA_BINDING_NAME / ANIRA_BINDING_POSITION (a registered engine’s slots ANIRA_BINDING_ENGINE); a name on a positional side (ExecuTorch, LibTorch outputs), ignored by alpha.1, is ANIRA_ERROR_NOT_SUPPORTED at anira_handler_create. Migration: drop it, keep its layout.

  • Breaking: C ABI — after a miss no late samples are delivered (alpha.1’s InferenceManager::process_output kept 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 (ceil at the stream’s hop) is ANIRA_ERROR_INVALID_ARGUMENT on every Hard entry (anira_handler_process, the _multi / _wait forms) before anything moves (latched in anira_handler_rt_error), also through the anira/compat/v2.hpp shim beyond its HostConfig size, where alpha.1 and 2.x’s anira::InferenceHandler truncated. Migration: declare the largest block as host_block_max (contract.hard_host_blocks(host_block_min, host_block_max, host_rate); shim HostConfig(largest_block, rate, true)).

  • Breaking: C++ — anira/anira.hpp’s enum alias of anira_engine is anira::EngineKind (alpha.1 anira::Engine, now a custom engine’s class), in ModelConfig::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++ loses ANIRA_API; anira.hpp and anira/compat/v2.hpp are header-only over the C entries (gates anira_symbol_baseline, anira_exports; the unload harness uses anira_release_core_if_idle, not anira::Core). Migration: use the C entries, anira.hpp or the shim.

  • Breaking: build — no test library is linked into anira (alpha.1 linked gtest_main PUBLIC, and installed it, whenever tests or benchmarks were built): test binaries link it via anira_add_test_binary / anira_benchmark_fixture; ANIRA_WITH_TESTS / ANIRA_WITH_BENCHMARK leave the package config. Migration: link GTest::gtest_main yourself, not via anira::anira.

  • Breaking: C ABI — the custom stage is a processor: ANIRA_STRUCT_STAGE_CTX (4 in anira_struct_id, for anira_stage_ctx) is ANIRA_STRUCT_PROCESSOR_CTX (4, anira_processor_ctx of anira/abi/processor.h), the ANIRA_PHASE_* names stay (anira_phase above), anira_plan_ext rows name the consumer "processor". Migration: spell ANIRA_STRUCT_PROCESSOR_CTX.

  • Breaking: C++ — anira::Hard::budget is required: anira_budget_kind (default ANIRA_BUDGET_MEASURED) plus budget_value is one anira::Budget without 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’s budgetMs; a std::chrono duration is explicit, Budget::measured() and the default UNTIL_STABLE warm-up are refused in this pre-release, Hard::budget_value is gone, ContractHandle::hard() reads the budget back as a Budget. Migration: .budget = ANIRA_BUDGET_EXPLICIT, .budget_value = d is .budget = d.

  • Breaking: engines — engine replaces backend in the install and the logs: headers in <includedir>/anira-engines/<engine>/ (was anira-backends/), aniraEngineHelpers.cmake / aniraEngineTargets.cmake (was aniraBackendHelpers.cmake / aniraBackendTargets.cmake) for anira::<engine>, CPack deps-engines (was deps-backends), log group anira.engine.<engine> (was anira.backend.<engine>; anira::log_group::k_engine_libtorch and siblings, were k_backend_*); internally anira::backend is anira::engine. Migration: spell the new names; anira-project/backends and ANIRA_BACKENDS_* keep theirs.

  • Breaking: C++ — alpha.1’s 2.x singleton anira::Context (anira/scheduler/Context.h) and anira::ContextConfig (anira/ContextConfig.h) are private: the singleton is the all-static core anira::Core, private like every core header, log group anira.core (was anira.context; the JSON key context_config stays); anira::Context / anira::ContextConfig are anira.hpp’s classes over anira_context / anira_context_config. Migration: hand the handler an anira::Context (C: an anira_context* from anira_context_create); 2.x code spells anira::v2::ContextConfig; Context:: shutdown and thread creation are anira_shutdown (anira::shutdown()) and anira_inference_thread_create (anira::InferenceThread).

  • Breaking: C++ — alpha.1’s installed anira::InferenceThread (anira/scheduler/InferenceThread.h) is the private anira::scheduler::InferenceThread (anira::Core::make_inference_thread); anira::InferenceThread is anira.hpp’s class over anira_inference_thread. Migration: use anira_inference_thread_* or that class.

  • Breaking: C++ — ANIRA_REALTIME is ANIRA_NONBLOCKING of anira/abi/export.h (clang’s nonblocking, no longer gated on ANIRA_WITH_RTSAN) on anira.hpp’s Hard entries; ANIRA_BLOCKING is private; anira_objects builds with -Wno-function-effects. Migration: spell ANIRA_NONBLOCKING.

  • Breaking: C++ — alpha.1’s installed anira::InferenceManager (anira/scheduler/InferenceManager.h, private now) takes host tensors only (its seven float*** overloads of push_data, pop_data, process_wait, pop_data_wait, … are gone) and moves Streamed slots only (no PrePostProcessor). Migration: drive a handler with one anira_tensor per slot, anira_tensor_init_host_planar(&t, channels, num_channels, ANIRA_DTYPE_F32, 2, shape) with shape = {num_channels, num_samples} ({1, num_values} non-streamable; C++ Tensor::from_host_planar), shape[1] == 0 for an unused slot.

  • Breaking: install — only the public headers install (anira.h, anira_all.h, anira_em.h, anira.hpp, compat/v2.hpp, the abi/ headers; another header under include/anira/ fails the configure): alpha.1’s core headers (scheduler/*.h with InferenceManager.h, SessionElement.h; anira/utils/Logger.h, anira/utils/RealtimeSanitizer.h, the other utils/*.h) are private, system/*.h (Exports.h, the deprecated HighPriorityThread) deleted; the C entries take ANIRA_API from anira/abi/export.h. Migration: replace <anira/scheduler/...>, <anira/utils/...>, <anira/system/...> with anira.hpp or 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; its Buffer / RingBuffer aliased tanh-lib’s): tanh-lib’s core (thl::core::Thread among it) is built into libanira as the hidden static anira_tanh_core (anira_tanh_lib at anira’s pin) in the inline namespace thl::anira, so a host’s own tanh-lib (thl::v<major>_<minor>) coexists in any link. Migration: link them yourself if you used them via anira::anira.

  • Breaking: build — USE_<ENGINE>, ENABLE_LOGGING, ANIRA_VERSION and TORCH_CXX_FLAGS no longer leave the build tree on anira::anira. Migration: ask anira_enabled_engines (and ANIRA_STATIC) instead of USE_*.

  • Breaking: packaging — the static libanira carries tanh-lib’s core (alpha.1 needed libtanh_core.a and --exclude-libs,libtanh_core.a). Migration: link anira::anira alone; drop libtanh_core.a from hand-written link lines.

  • Breaking: binary name — the soname is the ABI major (libanira.so.0, libanira.0.dylib, anira-0.dll / anira-0.lib through the 3.0.0 pre-releases, 3 from v3.0.0; alpha.1 libanira.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 stays anira.lib, aniraConfigVersion.cmake is SameMajorVersion (was AnyNewerVersion). Migration: none for CMake; hand-written link lines and loader paths name the new file; the Debian package keeps libanira<release major>.

  • C ABI, configuration (anira/abi/config.h, JSON): max_instances defaults to the new ANIRA_INSTANCES_AUTO (0xffffffffu, beside ANIRA_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_create stores it, anira_model_config_max_instances / ModelConfig::max_instances() read it, anira_model_config_set_max_instances accepts it (0 still refused), to_json omits it, and the 2.x num_parallel_processors default 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 declaring ANIRA_ENGINE_FLAG_NEEDS_NO_MODEL needs no source: JSON may omit "path", anira_model_config_add_model_path takes NULL (an empty path is still refused), C++ gains ModelConfig::add_model(engine_id), anira_model_config_model_path reads NULL; another engine’s source-less entry is ANIRA_ERROR_CONFIG at anira_handler_create; no "never-opened.bin" or web fetchModel: () => false for ModelConfig.fromUrl is needed (2.x model_path stays required).

  • C ABI, configuration (anira/abi/config.h, JSON): a version 2 document with a 3.x root key (models beside inference_config, num_threads beside context_config) is ANIRA_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 longer ANIRA_ERROR_CONFIG at anira_handler_create / anira_handler_prepare); only a Streamed tensor maps it onto ring channels; anira_handler_prepare still refuses any Buffer spec under a Hard contract.

  • C ABI, handler (anira/abi/handler.h): the miss policies work (alpha.1 delivered zeros), so the ANIRA_MISS_BYPASS default of anira_contract_create_hard and anira::Hard{} holds: ANIRA_MISS_ZEROS zeros, ANIRA_MISS_HOLD_LAST the last block, ANIRA_MISS_BYPASS the anchored input on process calls (else zeros), Static outputs hold, and the call returns ANIRA_MISSED; BYPASS is ANIRA_ERROR_CONFIG (on_miss) for an output anchor or unequal channel counts, so rave_funk_drum_encoder.contract.json / rave_funk_drum_decoder.contract.json and upgraded version 2 documents use ANIRA_MISS_ZEROS.

  • C ABI, handler (anira/abi/handler.h): a hop dropped for lack of an inference slot gets the on_miss fill (alpha.1: zeros), ANIRA_MISS_CALLBACK calling anira_miss_fn once per dropped hop on the driver thread (packed [channels, hop]), placed in stream order; anira_handler_rt_error reports it as ANIRA_ERROR_CAPACITY (an entry’s own CAPACITY return still never reaches rt_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 PrePostProcessor and SessionElement::plan_backend leave 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() stays ANIRA_LOG_ERROR in a release build, else ANIRA_LOG_INFO; ANIRA_THREADS_AUTO is anira::Core::default_num_threads().

  • Internal (the core on the 3.x types): the session, Core, InferenceManager and LatencyCalculator read the 3.x configuration directly (SessionElement::prepare, InferenceManager::prepare take no host configuration), the host blocks staying double down to LatencyCalculator::block_samples (no HostConfig narrowing).

  • Internal (the core on the 3.x types): a side’s ports never move (no copy, move or resize; static_asserts pin it); anira_handler gets both counts from anira_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_prepare return ANIRA_ERROR_INTERNAL.

  • Internal (the core on the 3.x types): one host<->ring copy path over anira_tensor (also under the blocking_ratio dispatcher and the wait_until pop), which the 2.x anira::InferenceHandler (InferenceHandler::process) ran on bit for bit via anira::PlanarFloatAdapter: planar (ANIRA_TENSOR_PLANAR, byte_offset), strided or packed blocks, dtype-generic without conversion; overlapping input and output descriptions are undefined on a BYPASS miss.

  • 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_ring knows its hop and owner (anira::RingOwner, SessionElement::prepare), SessionElement::ThreadSafeStruct carries the processor status that InferenceThread::do_inference reads, and anira::RtLatch brings it to rt_error.

  • ABI tooling and gates: release: the npm publish first runs the ABI check, the web build and the .d.ts export check (plus _malloc, _free), and sends a hyphenated version such as 3.0.0-alpha.2 to the next dist-tag.

  • ABI tooling and gates: generator: the 64-bit sentinels ANIRA_DYNAMIC and ANIRA_UNBOUNDED are typed bigint, so TypeDoc can serialize them.

  • Build: anira’s concurrentqueue is renamed anira_moodycamel, so a static libanira’s queue never merges with a host’s moodycamel::.

  • 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 as thl::anira, anira_moodycamel); a multi-config generator or a toolchain without readelf / objcopy keeps a plain archive.

  • Extras and examples: the advanced benchmark’s model_and_contract(model, buffer_size) returns both (ModelAndContract), replacing model_config_of.

  • C++ (anira/anira.hpp): anira.hpp refuses ANIRA_CXX_MANUAL_INIT and ANIRA_NO_PROTOTYPES for good (no anira_get_proc_address); ANIRA_CXX_NO_EXCEPTIONS stays 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 macOS mutex lock failed: Invalid argument at exit); a load before init is ANIRA_ERROR_INVALID_STATE.

  • Built-in engines: ONNX Runtime runs as an adapter over anira_tensor (replacing OnnxRuntimeProcessor): one environment per process, one session per executor, tensors bound in place; non-float32 is ANIRA_ERROR_CONFIG, a bad descriptor ANIRA_ERROR_INVALID_ARGUMENT, a failed run ANIRA_ERROR_ENGINE, an unsupported shape fails the warm-up in anira_handler_prepare.

  • Built-in engines: LibTorch runs as an adapter over anira_tensor (replacing LibtorchProcessor): 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 is ANIRA_ERROR_MODEL_LOAD at load.

  • Built-in engines: ExecuTorch runs as an adapter over anira_tensor (replacing ExecuTorchProcessor): 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 (replacing TFLiteProcessor): one interpreter per executor, the first signature’s keys bound by name or key order (output_0 before output_1), inputs resized to the engine dims, and reset re-initialises variable tensors before an exclusive handler’s new stream.

  • Built-in engines: LiteRT runs as an adapter over anira_tensor (for alpha.1’s LiteRtProcessor), 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_config of anira_context_config_create (anira::Core::register_context), so anira_wait_strategy, anira_log_level and anira_log_drain arrive unconverted; extensions are walked once, at anira_context_create; while a 3.x handler lives, anira_shutdown and release_core_if_idle refuse; sessions take an optional anira::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.h shape (init with anira_init_info, InferenceThread::inference passing an anira_engine_ctx to Prepared::run), replacing alpha.1’s five processor pools with a PlanSlot per plan; loaded models pool by their record, not InferenceConfig::operator== (different resolved windows never share; budget, blocking ratio and processing spec no longer split equal models), with one claim loop (ANIRA_ERROR_INVALID_STATE without a shared slot) and executors warmed up by the record’s FIXED warm_up; an exclusive call carries ANIRA_ENGINE_CALL_EXCLUSIVE; a status other than ANIRA_OK fails the chunk (zeros, ANIRA_ERROR_ENGINE, no after_inference, also for a 2.x PrePostProcessor::after_inference).

  • The core: a session-exclusive model (ANIRA_MODEL_STATEFUL or a State pair) is pooled and loaded once (instances 0) and prepared per handler, whose prepared handle owns its executor (a registered engine’s under ANIRA_PREPARE_EXCLUSIVE), where alpha.1 loaded it per handler with instances = 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_windows among them, which holds alpha.1’s PrePostProcessor::pop_samples_from_buffer) return 0 and write nothing on a dtype mismatch, the typed Hard entries of anira/abi/handler.h feed them, anira_contract_hard_set_ring_dtype (anira/abi/config.h) and anira::ContractHandle::hard_ring_dtype state the rule, and a ring dtype other than its spec’s is ANIRA_ERROR_CONFIG at anira_handler_prepare unless the processor fills that ring’s phase.

  • The core: an empty candidate set is ANIRA_ERROR_CONFIG, not NOT_SUPPORTED (none of the N model entries runs on a candidate backend (candidates: ...)); the candidate filter takes anira_backend_id rows.

  • The core: real-time failures are latched: a refused ANIRA_NONBLOCKING or _wait entry sets anira_handler_rt_error and logs one record per kind flagged ANIRA_LOG_RECORD_CONTRACT_VIOLATION, counting repeats until prepare or reset; scheduler sites and failed inferences log once per prepare, the drain (anira-log, or anira_drain_log under ANIRA_LOG_DRAIN_MANUAL and on WebAssembly) reports a growing count at most every 10 s; a failed inference (engine, processor, before_inference / after_inference) zero-fills and sets rt_error to ANIRA_ERROR_ENGINE; no exception ends a thread.

  • The core: the log drain runs on the core’s own low-priority thl::core::Thread anira-log while a session or context exists; the last release, anira_context_destroy or anira_shutdown stops and flushes it; anira_context_config_set_log_flags and anira_log_desc admit ANIRA_LOG_FLAG_TRACE_FAILURES.

  • Web (module, build): the module links -pthread -sWASM_WORKERS -sAUDIO_WORKLET with -sINCOMING_MODULE_JS_API=wasmMemory,wasmBinary,locateFile,instantiateWasm,print,printErr, exports emscriptenRegisterAudioObject and builds Release with -sASSERTIONS=0 (wasm-debug keeps 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-entry module’s runtime never exits; AniraWeb links -sEXIT_RUNTIME=0, an app with EXIT_RUNTIME=1 owns 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 === maximum fixes it), below 256 MiB or a maximum below the initial or above 2 GiB is an AniraError (ANIRA_ERROR_INVALID_ARGUMENT), an unreservable one ANIRA_ERROR_OUT_OF_MEMORY; heap access goes through heap(module), which rebuilds its views after a growth, and Workers and the worklet get the wasmMemory. An AUTO pool of 16 Workers with two RAVE models fits (#218).

  • Web (module): num_threads and ANIRA_THREADS_AUTO (half of std::thread::hardware_concurrency(), at least one) are no longer coerced to 0 on WebAssembly: AUTO is a pool of Wasm Workers, num_threads 0 a host that drives inference; ANIRA_WAIT_BLOCKING still becomes ANIRA_WAIT_SPIN_BACKOFF, ANIRA_LOG_DRAIN_THREAD ANIRA_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 via anira.abi, audio_nodes for custom_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 to inputSlots / outputSlots among them); Fetcher types 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, process is synchronous after init (memory.atomic.wait32), and data moves through the heap and Atomics, never postMessage; 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 of InferenceThread, set_non_realtime, v2::ContextConfig and the thread default (Blocking coerced 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 with ANIRA_STATIC); no consumer-visible change.

  • Build (WebAssembly): AniraWeb links anira::anira alone (no 2.x wrapper archive, --whole-archive or -sEXPORT_KEEPALIVE); build_web fails 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_block and peek_past_block (tanh-lab/tanh-lib#50).

  • Build: every configure preset exports the compile database (CMAKE_EXPORT_COMPILE_COMMANDS on desktop-base, ci-base, wasm-debug, wasm-release, docs), and the new ANIRA_LINK_COMPILE_COMMANDS (default OFF, top-level builds; ON in the desktop-* and wasm presets, OFF in clang-tidy) links build/compile_commands.json, which .clangd reads, to the last configured tree (desktop-tests-debug for the tests; --query-driver=**/em++ for wasm trees); .vscode/settings.json enables cmake.ctest.allowParallelJobs.

  • Build/CI: no job count is pinned: the test presets of CMakePresets.json lost execution.jobs: 4 (locally CTEST_PARALLEL_LEVEL or -j apply), CI detects the cores (cmake-build, ci-actions v0.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 call anira_shutdown(), before unloading) instead of hanging. A correct host sees no change; process exit still waits (a core first put to work before main is 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.h is 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) as anira::RingView does; push_block, pop_block and peek_past_block take a last size_t stride = 1; element_size() reports sizeof(T); pop_windows is unchanged; anira::v2::RingBuffer keeps the 2.x names.

  • CI: workflows move from tanh-lab/ci-actions v0.3.10 to v0.3.16 (tidy inputs, a tolerant coverage export, job-count inputs, the reusable workflows’ runs_on).

  • CI: Linux jobs run on ubuntu-24.04, since ubuntu-latest (26.04) lacks LLVM 20, the tooling’s pin (setup-cpp-build-tools failed).

  • CI: a pull request’s clang_tidy checks only its changed .cpp files (clang-tidy-check); the merge queue, manual runs and .clang-tidy or workflow changes sweep all; clang_tidy result reports on every pull request, so it can be required.

  • ABI gates: gate 4 compiles every public header against anira::anira alone under the strict flags on every preset, failing with a named #error when 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.py models unions (rows as C designators, anira_sync_token.u.vk.value), callback typedefs (typedef R (ANIRA_CALL name)(...), so ANIRA_PTR(name, slot) is a function pointer), draft headers (ANIRA_ABI_DRAFT_*) and each Tier-1 record’s anira_struct_id (behind anira_sizeof); --check refuses a repeated member name (as in anira_vulkan_desc); --diff-against flags 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 with ANIRA_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 expects anira::Error with ANIRA_ERROR_INVALID_ARGUMENT; anira/anira.hpp with log_rt; white-box); the one-sided suite’s non-realtime and blocking generator cases run under RTSan (its two #ifndef ANIRA_WITH_RTSAN regions are gone); the 2.x test documents carry qualified tensor_shape rows.

  • Docs: docs/sphinx/usage.rst covers 3.x only: Providers ("provider"), the required Hard::budget, ANIRA_MISS_CALLBACK with a parsed "callback", “Processors” (anira::Processor, Processor::Prepared, anira_handler_num_entries), anira::InferenceHandler beside 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 or DllMain); 2.x code goes to anira/compat/v2.hpp.

  • Docs: docs/sphinx/custom_engines.rst (“Custom Engines”, alpha.1’s custom-backends guide) is rewritten on anira_engine_desc and anira::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 the USE_<ENGINE> definitions left the installed anira::anira: anira_enabled_engines lists the engines.

  • Docs: docs/sphinx/custom_preprocessing.rst is rewritten on Processor / Processor::Prepared (alpha.1: PrePostProcessor): a prepared object per handler, anira_prepare_info / PrepareInfo, a spectrogram in pre_process under ANIRA_PROCESSOR_FLAG_REALTIME_PRE_POST, a heavy transform in before_inference / after_inference.

  • Docs: migration.rst is the compat page: 2.x calls → anira::InferenceHandler and C entries, PrePostProcessor → the processor, BackendBase → anira::Engine (Engine::load, Loaded::prepare, Prepared::process); what is not source-compatible (an owning BufferF, a stored InferenceBackend, std::invalid_argument catches), the [[deprecated]] timing; anira/compat/v2.hpp has ContextConfig and a view BufferF, no Buffer, MemoryBlock or helperFunctions.h; what each anira::v3compat call became.

  • Docs: contributing.rst covers local format and tidy runs (LLVM 20 wheels, the clang-tidy preset), the ABI gates, the registry rules (an [inference-thread] callback typedef carries no nonblocking) 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_ratio for blocking_ratio, the output spec’s latency for internal_model_latency, a Static or State output for postprocess_output_size == 0), getting_started.rst (linking from C, LINKER_LANGUAGE CXX on 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_PTR slots are members (fixing anira_log_record); left out: anira::detail (ExtTraits, KeptExt, ProcessorTrampolines), nested classes (LegacyProcessor::Prepared, PassthroughEngine’s, InferenceConfig::Defaults, anira::SpecView’s Axis, 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::InferenceHandler and anira::Core state the teardown rule; anira.hpp names anira::v2::JsonConfigLoader; Engine(std::string id) and Pipeline::add_engine state the anira.v2.custom exception to the anira. prefix; ANIRA_ENGINE_FLAG_STATE_ALIAS keeps 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_TIMEOUT and ANIRA_MISSED cross-reference; the doc of ANIRA_PHASE_INFERENCE says messages name a slot’s phase by its anira_phase word (pre_process to unload).

  • Docs: the v3 roadmap (2026-10-29): M2 exits with alpha.2; the new M2b, exiting with alpha.3, completes the Hard contract (MEASURED / UNTIL_STABLE budgets, inline execution, State initial values) and adds model variants (thl::RCU); M3 exits with alpha.4; M4 ends with emsdk 6.x; M5 folds into M2b and M6 ([[deprecated]] on compat/v2.hpp, the abidiff baseline).

  • Docs (Web): the docs/sphinx/web-api/ guides cover the 3.x package only (the wasm-abi gates, the org.anira.onnxruntime-web engine); the 2.x reference pages are gone, AniraError’s is new; the READMEs install from the next dist-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 (a Context, one Pipeline().add_engine(...).add_inference(...).add_processor(...), one anira::InferenceHandler, org.anira.examples.bypass); the JUCE and CLAP plugins choose the backend with PlanReport::find and set_plan (the simple benchmark finds its plan with PlanReport::find, the others run plan 0), and the CLAP plugin checks anira_check_abi.

  • Examples: the JUCE and CLAP plugins declare the host’s block range (JUCE hard_host_blocks(1, samplesPerBlock, sampleRate), CLAP hard_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), not anira/compat/v3_to_v2.h, and hold data in std::vector, not BufferF / MemoryBlock.

  • Examples (Web): web/examples/model-file picks its plan per prepare with PlanReport.find and InferenceHandler.setPlan; both examples set their AudioContext options inline.

  • Bundled models: the tflite and litert rows of gain.model.json and stereo_gain.model.json give the static gain the export’s rank-3 layout, the litert row the output keys output_0 / output_1; stateful_accumulator.model.json: above.

  • Pre-release names (no tag carried them): v3 snapshot spellings between v3.0.0-alpha.1 and this release, old → new. C ABI: anira_processor_phase / ANIRA_PROCESSOR_PHASE_FORCE32 (after anira_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-level anira_engine_prepare_fn → anira_engine_load_fn (out_loaded) / anira_engine_unload_fn, anira_engine_prepare_fn per handler (ANIRA_PREPARE_EXCLUSIVE in info->flags), anira_engine_init_fn / anira_processor_init_fn (by-name ANIRA_ENGINE_DESC_INIT initializers compile unchanged); anira_engine_ctx.reserved_ptr0 → anira_engine_ctx.loaded, anira_engine_ctx.flags → its first bit ANIRA_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); custom ANIRA_PROVIDER_DEFAULT → ANIRA_PROVIDER_CUSTOM, ANIRA_ENGINE_NONE → ANIRA_ENGINE_CUSTOM; prepare(handler, report, user_data) over anira_processor_desc.user_data → anira_processor_prepare_fn(info, user_data, out_prepared); the id at anira_pipeline_add_engine → at anira_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_multi and the five _wait twins of the process and pop forms (#190) → the tensor entries of the same name (one anira_tensor_init_host_planar with ANIRA_DTYPE_F32, ANIRA_TENSOR_READ_ONLY inputs; _inplace passes one tensor as input and output; a _multi form takes one tensor per slot, where the float forms accepted NULL at a request of 0; delivered replaces num_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_ms last (#189); _multi Static [1, values] slots → the spec’s tensor (the empty element is any extent 0, not shape[1] == 0; a single form naming a Static slot is ANIRA_ERROR_INVALID_ARGUMENT; a missed Static output is the stored value, filled first under ANIRA_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_AFTER 8 → 16, _PREPARE 16 → 32, _RELEASE 32 → 64, _RESET 64 → 128, _UNPREPARE 128 → 256, _INIT 256 → 512, ANIRA_EM_HOOKS_VERSION 1 → 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_options per kind → per backend (anira_ext_provider_options.sets by struct_size, as anira_pipeline_add_inference); the anira.v2.custom pass-through (BackendBase::process, ANIRA_BINDING_POSITION) → an engine under the id; the engine query per prepare → once at anira_handler_create; Host-only rows at ANIRA_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 behind set_inference_backend and the validator’s anchor_of → gone. C++: Engine::prepare → Engine::load returning std::unique_ptr<Engine::Loaded>, then Loaded::prepare; anira::ProcessorPrepareInfo / anira::EnginePrepareInfo → anira::PrepareInfo / anira::EngineLoadInfo; Pipeline::add_engine(id, impl) → explicit Engine(std::string id) and Pipeline::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 keep ANIRA_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 (with anira::EngineKind overloads onto ANIRA_PROVIDER_CPU and anira::v3compat::to_inference_config refusing State with ANIRA_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); callWithError over anira_error, checkStatus → bindings throwing AniraError; allocInstanceStack (RangeError) → none; JSProcessor, JSEngine, JSBackend, readStageContext, readLogRecord → defineProcessor, defineEngine, engineTensors, layout, logRecordAt; core/InferenceThread polling has_exited, waitForWorkerMessage → anira’s Wasm Workers; AniraAudioWorkletBase (AudioWorkletProcessor, registerProcessor) → createAudioNode; ONNXRuntimeWebBackend → onnxRuntimeWeb(); AniraWeb (AniraWeb.create, AniraWeb.module, AniraWeb.registerJSEngine for JSBackendBase, refusing ANIRA_EM_ENGINE_HOOK_QUERY at registration, not ANIRA_ERROR_UNKNOWN at prepare, AniraWeb.addJSStage for JSPrePostProcessor, configureAudioWorklet / registerAudioWorkletForContext on a BaseAudioContext) → 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 and anira_handler_process_multi; createAudioNode(anira, audioContext, handler, { inputChannels, outputChannels, inputSlot, outputSlot, params, staticInputs, waitMs, workletModules }) → inputSlots, outputSlots, partialStreams; Anira.create({ memory }) with a WebAssembly.Memory → { initial, maximum }; measureRenderGeometry’s probe → hold; Handler.createAudioNode’s warning → gone; Context.create without threads: 1 → ANIRA_THREADS_AUTO; anira_inference_thread_start on WebAssembly → starts a Wasm Worker; Handler → InferenceHandler, InferenceHandler.create(...).prepare(contract) chaining to the handler → returning the PlanReport, latency → getLatency / getLatencies, Contract (Contract.fromUrl, fromJson) → ContractHandle (ContractHandle.fromUrl), setGeometry / ContractHandle.hardGeometry → hardHostBlocks, ContractHandle.hard keys → 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_lib with tanh_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; the anira::scheduler::InferenceThread page → 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: the InferenceManager constructors over a BackendBase* and InferenceManager::set_backend / get_backend. Migration: an anira::Engine (anira.hpp; anira_engine_desc in C) on the pipeline (migration.rst); a 2.x custom backend is one under anira::v2::k_custom_engine_id, the 2.x pass-through anira::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.h and anira/scheduler/InferenceThread.h are private now, without Buffer.h. Migration (shim spelling of anira/compat/v2.hpp in parentheses): anira::InferenceConfig, ModelData, TensorShape, TensorShapeList, ProcessingSpec → anira::ModelConfig plus a Hard anira::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::PrePostProcessor via anira::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::ContextConfig of <anira/ContextConfig.h> (anira::CoreConfig in the snapshots) with its fields m_anira_version / m_enabled_backends (anira::CoreConfig::m_anira_version) and their cross-session compares, anira::LogConfig, the anira::LogLevel / anira::LogDrain / anira::WaitStrategy (SpinBackoff, Blocking) enums with to_string, default_log_drain(), default_num_threads() and the anira::LogLevel overload of default_log_level() (the private anira::default_log_level() returns an anira_log_level). Migration: anira::ContextConfig of anira/anira.hpp (anira_context_config) or the shim’s anira::v2::ContextConfig with its LogConfig and enums; ANIRA_THREADS_AUTO for default_num_threads(); anira_enabled_engines (built) and anira_capabilities_backends on a probed context (usable).

  • Breaking: C++ (2.x classes) — the 2.x anira::JsonConfigLoader (<anira/utils/JsonConfigLoader.h>). Migration: anira::ModelConfig::from_file with take_legacy_contract() and anira::ContextConfig::from_file read a 2.x document as is; or the strict anira::v2::JsonConfigLoader (what 2.x logged and skipped is an anira::Error).

  • Breaking: C++ (2.x classes) — libanira’s 2.x anira::InferenceHandler (<anira/InferenceHandler.h>): the name is the anira.hpp class over the C handler, and no anira class is defined in both libanira and anira.hpp (the scheduler thread is anira::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: an anira::InferenceHandler from a Pipeline, 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 is examples/benchmark/fixture/ (anira_benchmark_fixture, built by ANIRA_WITH_BENCHMARK also without ANIRA_WITH_EXAMPLES) over anira.hpp, same output: initialize_repetition(ModelConfig, Hard, plan) after set_plan (PlanReport::find) on an anira::InferenceHandler, then push_random_samples_in_buffer() / process_buffer() on one planar tensor; calculate_min / _max / _percentile and random_sample are in anira::benchmark::. Migration: copy the two fixture files (benchmarking.rst).

  • Breaking: Web — alpha.1’s 2.x web layer: the EMSCRIPTEN_KEEPALIVE wrappers over the 2.x classes (archive anira::wasm_wrappers), their TypeScript classes (InferenceConfig, InferenceHandler, PrePostProcessor, JSPrePostProcessor, ModelData, ProcessingSpec, TensorShape, HostConfig, BufferF, RingBuffer, Vector*, InferenceBackend, InferenceThread), the AniraWeb factory fields and JSBackendBase. Migration: the typed TypeScript API over the C ABI and anira/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, their anira.h lines) 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 its anira::<engine> target.

  • Breaking: Web — alpha.1’s 2.x TypeScript runtime: AniraWeb (AniraWeb.create(config, memory) over a WebAssembly.Memory, spinUpInferenceWorker(workerOrUrl?), registerProcessor / unregisterProcessor, registerPrePostProcessor / unregisterPrePostProcessor, registerAudioWorkletForContext, configureAudioWorklet(audioContext, inferenceHandlerPtr, prePostProcessorPtr, audioWorkletNodeName, { inputChannels, outputChannels, maxBufferSize })), createAniraWasm, setupInferenceWorker, waitForWorkerMessage, InferenceWorker, ONNXRuntimeWebBackend, AniraAudioWorkletBase, the inference-processor worklet, getAniraVersion, drainAniraLog, randomSample, fillBuffer, pushBufferToRingbuffer and the ./workers/* exports (./workers/inference-worker, ./workers/audio-worklet, ./workers/worklet-base); the entry points are ., ./scope (registry, defineEngine, defineProcessor, bindings, enums), ./engines/onnxruntime-web and ./wasm/*. Migration (migration.rst): Anira.create({ memory: { initial, maximum } }); anira.abi.anira_* for _anira_*, anira.module for the heap helpers; a context with threads and a workerModule (defineEngine for a JSBackendBase) and await context.ready() for the Workers; defineProcessor in a worklet module (createAudioNode’s workletModules) and pipeline.addProcessor for a JSPrePostProcessor or 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; partialStreams leaves one unserved) for inputChannels / 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, HybridNNBypassProcessor and the advanced benchmark’s ClearCustomProcessor, replaced by HybridNNProcessor, BypassEngine, ClearEngine and 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 between pre_process, before_inference / after_inference and post_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 before anira_handler_prepare / anira_handler_destroy returns, not later on an inference thread holding its shared_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, and dlclose keeps its bounded wait and abort.

  • Runtime: an exit() in an engine’s init or load (anira_engine_init_fn, anira_engine_load_fn) during anira_handler_prepare no longer deadlocks (Linux, macOS); the lifecycle lock’s try_lock (release_core_if_idle) refuses its holder, where std::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_MISSED from pop_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_BACKOFF and ANIRA_WAIT_BLOCKING alike) 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 with ANIRA_ERROR_INVALID_STATE on should_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::mutex excludes 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), is ANIRA_ERROR_OUT_OF_MEMORY (an AniraError), not RuntimeError: Aborted(OOM): anira links -sABORTING_MALLOC=0 (-sABORTING_MALLOC=1 after it keeps the abort), so std::bad_alloc is 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, not console.error); ANIRA_LOG_FLAG_DISABLE_PLATFORM_SINK or anira_em_set_log_hook (setLogSink) holds the sink off, setLogSink(null) restores it, and the sink links even when only anira_log is 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_blocks rename), 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 any BaseAudioContext), InferenceWorker.stop() freeing a Worker’s stack too early, and a TypeScript worklet failing to type-check against AniraAudioWorkletBase (its AudioWorkletProcessor base was declared only in the unshipped src/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’s anira_machine_config_set_log_sink) no longer claims to be ignored on WebAssembly; anira_drain_log feeds the C sinks and anira_em_set_log_hook there 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_rate and plan, names the backend); a pathless entry no longer throws (ModelConfig::model_path throws ANIRA_ERROR_INVALID_STATE for it): the fixture reads anira_model_config_model_path and prints the engine id.

  • Bundled models: extras/fetch-models.cmake refetches a tree whose .anira-pin stamp (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_MINOR from the tag (0.N for the N-th v3 pre-release).

  • ABI (unstable): the registry abi/anira.yml and its generator tools/abi/gen.py generate anira/abi/{export,status,version,enums,log}.h (anira_engine, anira_provider), the TypeScript enums and the symbol lists abi/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.h includes anira/abi/export.h.

  • ABI (unstable): anira/abi/config.h: opaque anira_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. Extensions anira_ext_header / anira_ext_entry (ANIRA_EXT_ENTRY_INIT) via set_ext / set_ext_json, anira_registered_ext_kinds; ANIRA_ERROR_EXTENSION_VERSION for 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) and anira_model_config_set_tensor_layout (ANIRA_AXIS_INSERT adds 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"), replacing ANIRA_ANCHOR_FIRST_STREAMED.

  • ABI (unstable): JSON: anira_model_config_from_json / anira_model_config_from_json_file (relative paths against base_dir), anira_machine_config_from_json, anira_contract_from_json, anira_model_config_to_json, anira_machine_config_to_json; load errors are ANIRA_ERROR_JSON with the key path, unknown keys fail prepare by name. A v2 document is upgraded (ANIRA_SUCCESS_UPGRADED; one ANIRA_LOG_WARNING per process): model_data to models (CUSTOM to anira.v2.custom, model_function to entry), tensor_shape / processing_spec to specs, max_inference_time / warm_up / blocking_ratio to a Hard contract for anira_model_config_take_legacy_contract.

  • C++ (not ABI-stable; requires C++20): include/anira/anira.hpp: RAII anira::TensorSpec, anira::ModelConfig, anira::ContractHandle (from anira::Hard / anira::Async; anira::Contract = std::variant), anira::MachineConfig, anira::JobOptionsHandle (from anira::JobOptions); aliases anira::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 throw anira::Error (std::runtime_error, anira_status in .status, anira_error text), 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_contract returns std::optional<ContractHandle>. The first handle checks ANIRA_ABI_VERSION; ANIRA_CXX_NO_EXCEPTIONS, ANIRA_CXX_MANUAL_INIT, ANIRA_NO_PROTOTYPES are rejected until the handler half lands. MachineConfig::log_sink(anira_log_fn, void*), ModelConfig::anchor(name); no anira::JsonConfigLoader yet.

  • 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 or buffer_size / sample_rate), enabled_engines() (ANIRA_ENGINE_NONE keeps custom engines). ANIRA_ERROR_CONFIG for invalid input, ANIRA_ERROR_NOT_SUPPORTED for Async, MEASURED, UNTIL_STABLE, a non-BYPASS miss policy, non-float32, a transpose, dynamic Time on a Buffer, an engine not built, a custom engine other than anira.v2.custom. Maps onto ModelData, 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 are ANIRA_NOEXCEPT (an escape is std::terminate); ANIRA_ERROR_INTERNAL logs 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.capi log group. Engines fail with ANIRA_ERROR_MODEL_LOAD / ANIRA_ERROR_ENGINE (anira::StatusError), a missing model file with ANIRA_ERROR_NO_SUCH_FILE.

Changed#

  • The 3.x line lives on the v3 branch, versioned from v3 tags (0.0.0+g<hash> without one); release artifacts are anira-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_log comes 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; new logging.rst.

  • Release builds keep Warning and Info records (tanh-lib’s TANH_LOG_COMPILED_MAX_LEVEL 4); the logcat tag and os_log subsystem are anira.

  • The v2 upgrade’s defaults match 2.x: no warm_up = fixed 0, no num_parallel_processors = max_instances of half the hardware threads.

  • InferenceConfig and 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::InferenceConfig statics of the 2.x fixture headers (CNNConfig.h and the other *Config.h) become extras/models/**/*.model.json + *.contract.json (extras/models/model_files.h), one processor per engine; SimpleGainConfig.json and RaveFunkDrumConfig*.json are gone. Migration: ModelConfig::from_file, ContractHandle::from_file, to_inference_config(model, contract, enabled_engines()), hard_geometry + to_host_config; replace GUITARLSTM_MODELS_PATH_*, STEERABLENAFX_MODELS_PATH_*, STATEFULLSTM_MODELS_PATH_*, SIMPLEGAIN_MODEL_PATH, RAVE_MODEL_DIR and *_JSON_CONFIG_PATH with ANIRA_EXTRAS_MODELS_DIR.

  • JUCE example variants 0 to 7 (MODEL_TO_USE; variant 1 embeds the CNN via ModelConfig::from_json + set_model_bytes + ANIRA_BYTES_BORROW); benchmarks use to_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::Error no 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 the HostConfig reference 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): .pte programs, named entry points (model_function), prebuilt libraries for desktop, Android and iOS, a minimal-executorch example.

  • Receptive-field (sliding-window) models in the default PrePostProcessor: an input tensor larger than its preprocess_input_size is filled with ring-buffer history plus the fresh hop.

  • Context is 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) replaces SessionElement’s latency arithmetic: closed forms instead of the LCM loop, is_feasible(), correct struct and ring sizing for fractional and smaller host blocks. Derivation in docs/sphinx/latency.rst.

  • Symbol policy from the shared tanh-tooling CMake modules (cmake/tanh/): hidden visibility everywhere, libanira exports namespace anira only, plugins leak no backend runtime symbol; the anira_exports CTest enforces it.

  • CI on the shared tanh-lab/ci-actions workflows: every backend and both linkages in the PR tier, install, sanitizer (ASan+UBSan, TSan, RTSan) and coverage legs, a preset for every leg in CMakePresets.json, and the npm publish gated behind the same tests as every other release artifact.

Changed#

  • Breaking: the latency calculation moves out of SessionElement into LatencyCalculator; SessionElement loses its calculate_*, max_num_inferences and gcd/lcm helpers. Reported latencies are unchanged for whole-sample host blocks; slot counts follow 2·S.

  • Breaking: backend linkage follows BUILD_SHARED_LIBS and ANIRA_<ENGINE>_LINKAGE is 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: link anira::<engine> wherever your own code includes an engine header.

  • Breaking (Windows install layout): DLLs install to bin/, import libraries and archives to lib/.

  • Breaking: logging goes through tanh-lib’s thl::Logger with a real-time queue (#56): ANIRA_LOG_*/ANIRA_LOG_RT_* replace the LOG_* 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: call prepare() where a drain was relied upon.

  • Breaking (containers): anira::Buffer<T>, anira::RingBuffer and anira::MemoryBlock<T> are aliases over tanh-lib’s thl::core containers; RingBuffer no longer derives from Buffer<float>, and every real-time ring-buffer access uses the block API (#111).

  • Context::get_instance() takes no arguments and returns a Context&; the ContextConfig travels with Context::create_session() (old two-step API deprecated for one minor release). anira::HighPriorityThread is deprecated for one release.

  • The active backend defaults to the first model backend that is available instead of the silent CUSTOM bypass; HostConfig’s default reference tensor is the first streamable tensor.

  • The export header is anira/system/Exports.h; ANIRA_BUILDING/ANIRA_STATIC replace ANIRA_EXPORTS/ANIRA_STATIC_DEFINE (old spellings honoured).

  • ExecuTorch is consumed as one merged libexecutorch.a per 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() and Context::release_thread_pool() (Context::shutdown() is the explicit teardown), the never-released reset_non_blocking() variants, the unreachable ContextConfig::operator==/!=, and the dead interpolation branch of anira::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 after m_num_structs chunks (#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 or prepare() throws (#106); create_session()/release_session()/prepare_session() are thread-safe across sessions; a data race in Context::release_session() (found by the TSan leg).

  • LatencyCalculator::least_common_multiple no longer overflows int, the allow_smaller_buffers sweep no longer stalls for large blocks, and the send ring of a fractional host block reserves P - 1 samples.

  • JsonConfigLoader drops malformed tensor_shape entries instead of letting nlohmann::type_error escape; LibtorchProcessor throws std::runtime_error on an unloadable model like the other backends; BackendBase::process no longer reads past the output vector.

  • USE_ANIRA_WEB is defined in Emscripten builds only; installing on lib64 hosts works with LibTorch and ExecuTorch; anira::HighPriorityThread links 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 extracts num_batches windows 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 with session_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 } on ContextConfig. Blocking lets idle inference threads sleep on a semaphore instead of spin-polling, eliminating idle CPU usage at effectively no throughput cost; coerced to SpinBackoff with a warning on WebAssembly.

  • Real-time factor and underrun reporting in the benchmark fixture (per-iteration RTF/[underrun] marker, plus an optional summary line with rtf_mean/rtf_max/underrun count).

  • The advanced and cnn-size benchmarks now also cover the CUSTOM (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 } on ContextConfig, 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 to Info in debug builds, Error in 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 default num_threads is now platform-dependent: half the available CPU cores (as before) on native builds, 0 on WebAssembly, since inference threads there are always supplied externally via AniraWeb.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 a ReferenceError (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 — InferenceConfig is now owned per-processor instead of aliasing the originating session’s copy.

  • Windows build failure in Context::get_instance() caused by <windows.h>’s min/max macros mangling an unrelated std::min(...) call; fixed by defining NOMINMAX/WIN32_LEAN_AND_MEAN before the include.

  • Hardened SessionElement::m_is_non_real_time to std::atomic<bool> and unified the two new_data_request() wait paths onto one wait_for_completion() helper — previously a default-blocking_ratio session 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-only pthread_*inheritsched / pthread_setattr_default_np calls are gated behind !__ANDROID__ (bionic lacks them) while keeping the portable SCHED_FIFO path.

  • 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.framework via a generated shim so anira’s <tensorflow/lite/...> includes resolve untouched.

  • LiteRT inference backend (anira::InferenceBackend::LITERT): runs .tflite models through Google’s native LiteRt* 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/backends release, pinned by ANIRA_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=ON skips 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-engine ANIRA_<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-check action (clang_tidy.yml)

  • InstallConsumer smoke 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 macOS universal.

Changed#

  • Breaking: the InferenceConfig::Defaults compile-time constants were renamed from the m_ prefix to the k_ 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 mutable Defaults::m_num_parallel_processors is 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_json is now consumed as a release download instead of a git submodule.

  • CMake options and their validation were consolidated inline into CMakeLists.txt (AniraOptions.cmake and the redundant linkage knob were dropped).

  • anira::calculate_min / anira::calculate_max are now inline free functions instead of const auto lambdas (source-compatible: existing call sites and uses as a callable are unaffected)

  • The internal logging helper isLoggingEnabled() was renamed to is_logging_enabled()

  • Migrated the shared clang configs (.clang-format/.clang-tidy/.clangd) from the tanh-lib submodule symlinks to tanh-tooling (pinned v0.1.4): committed as real files, kept in sync by the clang_check.yml drift check, and the now-unused tanh-lib submodule was removed (configs are byte-identical, so lint/format results are unchanged)

  • Adopted the default Claude Code config: .claude/settings.json now enables the tanh-tools plugin from the tanh-tooling marketplace (its format/lint/type-check hooks supersede the previous bespoke .claude/hooks)

  • CI now covers Windows-arm64, Linux-aarch64 and macOS-universal legs (shared + static) in addition to the mobile workflow.

Fixed#

  • Potential use-after-free in Buffer::malloc_channels() when channel-pointer allocation fails

  • Installed nlohmann_json config so find_package(anira) works against the installed package

  • Disabled backends now compile to empty translation units (guarded .cpp bodies), and minimal-onnxruntime is self-sufficient in static builds

  • Value-initialize the const InferenceConfig in the install consumer

  • clang-tidy violations and a CLAP static MSVC runtime mismatch; preserve the anira-before-JuceHeader include order on MSVC; qualified mem* calls with std:: 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/anira npm package

    • Emscripten/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/JSPrePostProcessor hooks for implementing custom inference backends and pre/post processing in JavaScript/TypeScript

    • Web 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::Semaphore wrapper for macOS 10.13 support

  • macOS 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_DEFINE

  • Refactored 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_function argument for model_data in the JsonConfigLoader

  • JSON 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)