Processor examples#
Each example is a whole processor; Custom Pre/Post Processing is the reference for what they call. The normaliser is on that page.
An int16 stream into a float32 model#
The host pushes int16 samples (contract.hard_ring_dtype("audio_in", ANIRA_DTYPE_I16)), the
model reads float32. Without a processor prepare refuses the contract; with this one
pre_process pops the hop as int16 and converts, and post_process, left out of
phases(), stays the default push. The scratch is sized per entry in prepare, one per handler.
#include <memory>
#include <span>
#include <vector>
#include <anira/anira.hpp>
class Int16ToFloat : public anira::Processor {
public:
uint32_t phases() const noexcept override { return k_pre_process; } // post_process: the default
uint32_t realtime_phases() const noexcept override { return phases(); }
std::unique_ptr<Prepared> prepare(const anira::PrepareInfo& info) override;
private:
class Converter;
};
class Int16ToFloat::Converter : public anira::Processor::Prepared {
public:
explicit Converter(uint32_t entries) : m_scratch(static_cast<size_t>(entries) * k_hop) {}
anira_status pre_process(anira::ProcessorContext& ctx) noexcept override {
anira::Role role = ANIRA_ROLE_FORCE32; // what slot 0 is
if (const anira_status st = ctx.input_role(0, role); st != ANIRA_OK) { return st; }
if (role != ANIRA_ROLE_STREAMED) { return ANIRA_ERROR_CONFIG; }
anira::RingView ring; // the host's int16 ring
if (const anira_status st = ctx.input_ring(0, ring); st != ANIRA_OK) { return st; }
anira::Tensor model{}; // the float32 model end
if (const anira_status st = ctx.input_tensor(0, model); st != ANIRA_OK) { return st; }
float* samples = model.data_f32();
if (samples == nullptr || ring.dtype() != ANIRA_DTYPE_I16) { return ANIRA_ERROR_CONFIG; }
const std::span<int16_t> scratch(m_scratch.data() + static_cast<size_t>(ctx.entry()) * k_hop, k_hop);
for (uint32_t c = 0; c < ring.num_channels(); ++c) {
if (ring.pop_block(c, scratch) != k_hop) { return ANIRA_ERROR_INTERNAL; }
for (size_t n = 0; n < k_hop; ++n) {
samples[c * k_hop + n] = static_cast<float>(scratch[n]) / 32768.0F;
}
}
return ANIRA_OK;
}
private:
static constexpr size_t k_hop = 512;
std::vector<int16_t> m_scratch;
};
std::unique_ptr<anira::Processor::Prepared> Int16ToFloat::prepare(const anira::PrepareInfo& info) {
return std::make_unique<Converter>(info.num_entries()); // one per handler, its own scratch
}
A float32 host on a float16 model#
Both rings float32, the model tensors float16 (to_half and from_half are the host’s helpers;
HOP is the model’s hop). test/abi/test_Dtypes.cpp runs this processor and its int8 twin.
class HalfPrepared final : public anira::Processor::Prepared {
public:
anira_status pre_process(anira::ProcessorContext& ctx) noexcept override {
anira::Tensor tensor{};
anira::RingView ring;
if (ctx.input_tensor(0, tensor) != ANIRA_OK || ctx.input_ring(0, ring) != ANIRA_OK) {
return ANIRA_ERROR_CONFIG;
}
auto* model = static_cast<uint16_t*>(tensor.data(ANIRA_DTYPE_F16));
if (model == nullptr || ring.pop_block(0, std::span<float>(m_scratch)) != HOP) {
return ANIRA_ERROR_CONFIG;
}
for (size_t n = 0; n < HOP; ++n) { model[n] = to_half(m_scratch[n]); }
return ANIRA_OK;
}
anira_status post_process(anira::ProcessorContext& ctx) noexcept override {
anira::Tensor tensor{};
anira::RingView ring;
if (ctx.output_tensor(0, tensor) != ANIRA_OK || ctx.output_ring(0, ring) != ANIRA_OK) {
return ANIRA_ERROR_CONFIG;
}
const auto* model = static_cast<const uint16_t*>(tensor.data(ANIRA_DTYPE_F16));
if (model == nullptr) { return ANIRA_ERROR_CONFIG; }
for (size_t n = 0; n < HOP; ++n) { m_scratch[n] = from_half(model[n]); }
return ring.push_block(0, std::span<const float>(m_scratch)) == HOP
? ANIRA_OK
: ANIRA_ERROR_CONFIG;
}
private:
std::array<float, HOP> m_scratch{};
};
class HalfProcessor final : public anira::Processor {
public:
uint32_t phases() const noexcept override { return k_pre_process | k_post_process; }
uint32_t realtime_phases() const noexcept override { return phases(); }
std::unique_ptr<Prepared> prepare(const anira::PrepareInfo&) override {
return std::make_unique<HalfPrepared>();
}
};
contract.hard_ring_dtype("audio_in", ANIRA_DTYPE_F32).hard_ring_dtype("audio_out", ANIRA_DTYPE_F32);
pipeline.add_processor(std::make_shared<HalfProcessor>());
A spectrogram model#
The input spec’s window is longer than the hop (window(2048, 2048, 1536): 512 fresh samples and
1536 of history), and the model tensor is the spectrum, so the default fill cannot be used:
pre_process assembles the window (the history through peek_past_block, the hop through
pop_block) and transforms it; post_process transforms back and pushes the hop. The transform
runs on the driving thread, so it is real-time itself (preallocated plans). The windows live in a
per-entry scratch that reset clears, which phases() names with k_reset.
#include <algorithm>
#include <memory>
#include <span>
#include <vector>
#include <anira/anira.hpp>
// Your transform of choice, over preallocated plans: no allocation in the call.
void forward_transform(const float* window, size_t window_size, float* spectrum) noexcept;
void inverse_transform(const float* spectrum, size_t window_size, float* samples) noexcept;
class Spectral : public anira::Processor {
public:
uint32_t phases() const noexcept override {
return k_pre_process | k_post_process | k_reset; // Frames overrides reset
}
uint32_t realtime_phases() const noexcept override { return phases(); }
std::unique_ptr<Prepared> prepare(const anira::PrepareInfo& info) override;
private:
class Frames;
};
class Spectral::Frames : public anira::Processor::Prepared {
public:
explicit Frames(uint32_t entries) : m_windows(static_cast<size_t>(entries) * k_window) {}
void reset(anira::ProcessorContext& /*ctx*/) noexcept override {
std::ranges::fill(m_windows, 0.0F); // a new stream: no history
}
anira_status pre_process(anira::ProcessorContext& ctx) noexcept override {
anira::RingView ring; // the audio input: Streamed, float32
if (const anira_status st = ctx.input_ring(0, ring); st != ANIRA_OK) { return st; }
anira::Tensor spectrum{};
if (const anira_status st = ctx.input_tensor(0, spectrum); st != ANIRA_OK) { return st; }
float* bins = spectrum.data_f32();
if (bins == nullptr) { return ANIRA_ERROR_CONFIG; }
const std::span<float> window = scratch(ctx.entry());
// the window: the history first, then the hop, popped exactly once
ring.peek_past_block(0, window.subspan(0, k_window - k_hop));
if (ring.pop_block(0, window.subspan(k_window - k_hop, k_hop)) != k_hop) {
return ANIRA_ERROR_INTERNAL;
}
forward_transform(window.data(), k_window, bins);
return ANIRA_OK;
}
anira_status post_process(anira::ProcessorContext& ctx) noexcept override {
anira::RingView ring;
if (const anira_status st = ctx.output_ring(0, ring); st != ANIRA_OK) { return st; }
anira::Tensor spectrum{};
if (const anira_status st = ctx.output_tensor(0, spectrum); st != ANIRA_OK) { return st; }
const float* bins = spectrum.data_f32();
if (bins == nullptr) { return ANIRA_ERROR_CONFIG; }
const std::span<float> window = scratch(ctx.entry());
inverse_transform(bins, k_window, window.data());
// the stream advances by one hop: push what this frame contributes to it
if (ring.push_block(0, window.subspan(k_window - k_hop, k_hop)) != k_hop) {
return ANIRA_ERROR_INTERNAL;
}
return ANIRA_OK;
}
private:
std::span<float> scratch(uint32_t entry) noexcept {
return {m_windows.data() + static_cast<size_t>(entry) * k_window, k_window};
}
static constexpr size_t k_window = 2048;
static constexpr size_t k_hop = 512;
std::vector<float> m_windows;
};
std::unique_ptr<anira::Processor::Prepared> Spectral::prepare(const anira::PrepareInfo& info) {
return std::make_unique<Frames>(info.num_entries()); // this handler's windows
}
The example is mono (channel 0); a multi-channel processor loops over ring.num_channels() and
lays the channels out as the model tensor expects. What an overlap-add keeps between frames lives in
a scratch of the prepared object’s own that reset clears; the shape is the point: pop the hop
once, push the hop once, transform in between.
When the transform is heavy: the same in C, split across the hooks#
A transform too heavy for the audio callback moves to the inference thread, keyed by the entry:
pre_process only pops the window into the per-entry scratch, before_inference transforms it
into the model tensor, after_inference transforms the output back into the scratch, and
post_process pushes the hop. The hooks may then use a library that allocates, since
realtime_phases promises pre_process, post_process and reset alone. prepare
allocates this handler’s windows and hands them back through out_prepared; unprepare frees
them; user_data stays NULL, since nothing is shared.
#include <stdlib.h>
#include <string.h>
#include <anira/abi/config.h>
#include <anira/abi/handler.h>
#define WINDOW ((size_t)2048)
#define HOP ((size_t)512)
/* Your transform of choice. */
void forward_transform(const float* window, size_t window_size, float* spectrum);
void inverse_transform(const float* spectrum, size_t window_size, float* samples);
typedef struct spectral { float* windows; uint32_t entries; } spectral; /* one per handler */
static anira_status ANIRA_CALL spectral_prepare(const anira_prepare_info* info,
void* user_data,
void** out_prepared) {
spectral* s = (spectral*)calloc(1, sizeof(spectral));
(void)user_data; /* the registration: nothing shared */
if (s == NULL) { return ANIRA_ERROR_OUT_OF_MEMORY; }
s->entries = info->num_entries;
s->windows = (float*)calloc((size_t)s->entries * WINDOW, sizeof(float));
if (s->windows == NULL) { free(s); return ANIRA_ERROR_OUT_OF_MEMORY; }
*out_prepared = s; /* what every phase of this handler gets */
return ANIRA_OK;
}
/* the first chunk of a new stream, on the thread of pre_process: no history */
static void ANIRA_CALL spectral_reset(const anira_processor_ctx* ctx,
void* prepared,
void* user_data) ANIRA_NONBLOCKING {
spectral* s = (spectral*)prepared;
(void)ctx;
(void)user_data;
memset(s->windows, 0, (size_t)s->entries * WINDOW * sizeof(float));
}
/* driving thread, real-time: the pop alone */
static anira_status ANIRA_CALL spectral_pre_process(const anira_processor_ctx* ctx,
void* prepared,
void* user_data) ANIRA_NONBLOCKING {
float* window = ((spectral*)prepared)->windows + (size_t)ctx->entry * WINDOW;
(void)user_data;
anira_ring* ring = NULL;
anira_status st = anira_processor_input_ring(ctx, 0, &ring); /* slot 0 is Streamed: the model config says so */
if (st != ANIRA_OK) { return st; }
if (anira_ring_peek_past_block(ring, 0, window, ANIRA_DTYPE_F32, WINDOW - HOP) != WINDOW - HOP) {
return ANIRA_ERROR_CONFIG; /* not float32 */
}
if (anira_ring_pop_block(ring, 0, window + (WINDOW - HOP), ANIRA_DTYPE_F32, HOP) != HOP) {
return ANIRA_ERROR_INTERNAL;
}
return ANIRA_OK;
}
/* inference thread: the transform into the model tensor */
static anira_status ANIRA_CALL spectral_before_inference(const anira_processor_ctx* ctx,
void* prepared,
void* user_data) {
const float* window = ((spectral*)prepared)->windows + (size_t)ctx->entry * WINDOW;
(void)user_data;
anira_tensor spectrum;
float* bins;
anira_status st = anira_processor_input_tensor(ctx, 0, &spectrum);
if (st != ANIRA_OK) { return st; }
bins = anira_tensor_data_f32(&spectrum);
if (bins == NULL) { return ANIRA_ERROR_CONFIG; }
forward_transform(window, WINDOW, bins);
return ANIRA_OK;
}
/* inference thread: the inverse transform back into the scratch of the same entry */
static anira_status ANIRA_CALL spectral_after_inference(const anira_processor_ctx* ctx,
void* prepared,
void* user_data) {
float* window = ((spectral*)prepared)->windows + (size_t)ctx->entry * WINDOW;
(void)user_data;
anira_tensor spectrum;
const float* bins;
anira_status st = anira_processor_output_tensor(ctx, 0, &spectrum);
if (st != ANIRA_OK) { return st; }
bins = anira_tensor_data_f32(&spectrum);
if (bins == NULL) { return ANIRA_ERROR_CONFIG; }
inverse_transform(bins, WINDOW, window);
return ANIRA_OK;
}
/* driving thread, real-time: the push alone */
static anira_status ANIRA_CALL spectral_post_process(const anira_processor_ctx* ctx,
void* prepared,
void* user_data) ANIRA_NONBLOCKING {
const float* window = ((spectral*)prepared)->windows + (size_t)ctx->entry * WINDOW;
(void)user_data;
anira_ring* ring = NULL;
anira_status st = anira_processor_output_ring(ctx, 0, &ring);
if (st != ANIRA_OK) { return st; }
if (anira_ring_push_block(ring, 0, window + (WINDOW - HOP), ANIRA_DTYPE_F32, HOP) != HOP) {
return ANIRA_ERROR_INTERNAL;
}
return ANIRA_OK;
}
/* once per successful prepare: the next prepare of the handler, or its destroy */
static void ANIRA_CALL spectral_unprepare(void* prepared, void* user_data) {
spectral* s = (spectral*)prepared;
(void)user_data;
free(s->windows);
free(s);
}
and its descriptor, filled once at setup (init and release stay NULL: nothing is
shared by the handlers of the pipeline):
anira_processor_desc desc = ANIRA_PROCESSOR_DESC_INIT;
desc.realtime_phases = ANIRA_PHASE_BIT(ANIRA_PHASE_PRE_PROCESS) |
ANIRA_PHASE_BIT(ANIRA_PHASE_POST_PROCESS) |
ANIRA_PHASE_BIT(ANIRA_PHASE_RESET); /* the hooks promise nothing */
desc.pre_process = spectral_pre_process;
desc.before_inference = spectral_before_inference;
desc.after_inference = spectral_after_inference;
desc.post_process = spectral_post_process;
desc.reset = spectral_reset;
desc.prepare = spectral_prepare;
desc.unprepare = spectral_unprepare;
anira_pipeline_add_processor(pipe, &desc, &err);
The entry makes the split correct: one handler’s chunks may be in flight on several inference
threads, one entry holds one chunk at a time, and the four phases of a chunk see the same entry. The
entry count is fixed by each prepare, which is why the scratch is sized in prepare, per handler.
Integration#
anira::Pipeline pipeline;
pipeline.add_inference(model) // the default candidate set
.add_processor(std::make_shared<Spectral>());
anira::InferenceHandler handler(context, pipeline); // the pipeline is copied
handler.prepare(contract); // validates the processor, then runs init (once) and prepare
anira_pipeline* pipe = NULL;
anira_pipeline_create(&pipe, &err);
anira_pipeline_add_inference(pipe, variants, 1, NULL, 0, &err); /* NULL: the default candidate set */
anira_pipeline_add_processor(pipe, &desc, &err); /* at most one */
anira_handler* h = NULL;
anira_handler_create(context, pipe, &h, &err); /* copies the pipeline */
anira_pipeline_destroy(pipe); /* the handler keeps its copy */