ivon_audio_types.h File Reference

#include <stddef.h>
#include <stdint.h>

Classes
struct	ivon_audio_stats
	Aggregate audio processor statistics. More...
struct	ivon_speaking_event
	Speaking state transition event. More...
struct	ivon_pre_dsp_context
	Context for pre-DSP callbacks (mono per-sender). More...
struct	ivon_post_spatial_context
	Context for post-spatial callbacks (expanded per-sender). More...
struct	ivon_post_mix_context
	Context for post-mix callbacks (final mixed stream). More...
struct	ivon_audio_output_frame
	Mixed audio output frame (copy-out). More...

Macros
#define	IVON_AUDIO_SAMPLE_RATE   48000
	Default sample rate (48 kHz).
#define	IVON_AUDIO_FRAME_DURATION_MS   20
	Frame duration in milliseconds (20 ms).
#define	IVON_AUDIO_FRAME_SIZE   (IVON_AUDIO_SAMPLE_RATE * IVON_AUDIO_FRAME_DURATION_MS / 1000)
	Samples per channel per frame (960).
#define	IVON_AUDIO_MAX_CHANNELS   8
	Maximum supported output channels (7.1 surround).

Typedefs
typedef struct ivon_audio *	ivon_audio_t
	C ABI types for the libivon audio processor.
typedef struct ivon_packet_buffer *	ivon_packet_buffer_t
	Opaque handle to a packet buffer from the audio processor's pool.
typedef enum ivon_speaking_mode	ivon_speaking_mode_t
	How the local user is transmitting audio.
typedef enum ivon_frame_type	ivon_frame_type_t
	How a decoded PCM frame was produced.
typedef enum ivon_dsp_action	ivon_dsp_action_t
	DSP callback return value — controls pipeline continuation.
typedef enum ivon_frame_duration	ivon_frame_duration_t
	Supported frame durations for audio codecs.
typedef enum ivon_codec_sample_rate	ivon_codec_sample_rate_t
	Supported codec-internal sample rates.
typedef struct ivon_audio_config *	ivon_audio_config_t
	Opaque audio processor configuration handle.
typedef struct ivon_audio_stats	ivon_audio_stats_t
	Aggregate audio processor statistics.
typedef struct ivon_speaking_event	ivon_speaking_event_t
	Speaking state transition event.
typedef struct ivon_pre_dsp_context	ivon_pre_dsp_context_t
	Context for pre-DSP callbacks (mono per-sender).
typedef struct ivon_post_spatial_context	ivon_post_spatial_context_t
	Context for post-spatial callbacks (expanded per-sender).
typedef struct ivon_post_mix_context	ivon_post_mix_context_t
	Context for post-mix callbacks (final mixed stream).
typedef struct ivon_audio_output_frame	ivon_audio_output_frame_t
	Mixed audio output frame (copy-out).
typedef int(*	ivon_audio_pcm_source_fn) (float *pcm_out, int frame_size, void *user_data)
	PCM source callback — pull mono float PCM from the user.
typedef void(*	ivon_audio_speaking_event_fn) (const ivon_speaking_event_t *event, void *user_data)
	Speaking state change callback.
typedef ivon_dsp_action_t(*	ivon_audio_pre_dsp_fn) (ivon_pre_dsp_context_t *ctx, void *user_data)
	Pre-DSP callback (mono per-sender, after decode).
typedef ivon_dsp_action_t(*	ivon_audio_post_spatial_fn) (ivon_post_spatial_context_t *ctx, void *user_data)
	Post-spatial callback (expanded per-sender, after channel expansion).
typedef ivon_dsp_action_t(*	ivon_audio_post_mix_fn) (ivon_post_mix_context_t *ctx, void *user_data)
	Post-mix callback (final mixed output).

Enumerations
enum	ivon_speaking_mode { IVON_SPEAKING_MODE_PTT = 0 , IVON_SPEAKING_MODE_VAD = 1 , IVON_SPEAKING_MODE_PTT_VAD = 2 , IVON_SPEAKING_MODE_CONTINUOUS = 3 }
	How the local user is transmitting audio. More...
enum	ivon_frame_type { IVON_FRAME_TYPE_DECODED = 0 , IVON_FRAME_TYPE_FEC = 1 , IVON_FRAME_TYPE_PLC = 2 , IVON_FRAME_TYPE_SILENCE = 3 }
	How a decoded PCM frame was produced. More...
enum	ivon_dsp_action { IVON_DSP_ACTION_CONTINUE = 0 , IVON_DSP_ACTION_STOP = 1 }
	DSP callback return value — controls pipeline continuation. More...
enum	ivon_frame_duration {   IVON_FRAME_DURATION_2_5_MS = 0 , IVON_FRAME_DURATION_5_MS = 1 , IVON_FRAME_DURATION_10_MS = 2 , IVON_FRAME_DURATION_20_MS = 3 ,   IVON_FRAME_DURATION_40_MS = 4 }
	Supported frame durations for audio codecs. More...
enum	ivon_codec_sample_rate {   IVON_CODEC_SAMPLE_RATE_8000 = 0 , IVON_CODEC_SAMPLE_RATE_12000 = 1 , IVON_CODEC_SAMPLE_RATE_16000 = 2 , IVON_CODEC_SAMPLE_RATE_24000 = 3 ,   IVON_CODEC_SAMPLE_RATE_48000 = 4 }
	Supported codec-internal sample rates. More...

Macro Definition Documentation

IVON_AUDIO_FRAME_DURATION_MS

#define IVON_AUDIO_FRAME_DURATION_MS   20

Frame duration in milliseconds (20 ms).

IVON_AUDIO_FRAME_SIZE

#define IVON_AUDIO_FRAME_SIZE   (IVON_AUDIO_SAMPLE_RATE * IVON_AUDIO_FRAME_DURATION_MS / 1000)

Samples per channel per frame (960).

IVON_AUDIO_MAX_CHANNELS

#define IVON_AUDIO_MAX_CHANNELS   8

Maximum supported output channels (7.1 surround).

IVON_AUDIO_SAMPLE_RATE

#define IVON_AUDIO_SAMPLE_RATE   48000

Default sample rate (48 kHz).

Typedef Documentation

ivon_audio_config_t

typedef struct ivon_audio_config* ivon_audio_config_t

Opaque audio processor configuration handle.

Create with ivon_audio_config_create(), set fields with the ivon_audio_config_set_*() functions, pass to ivon_audio_create(), then destroy with ivon_audio_config_destroy().

ivon_audio_output_frame_t

typedef struct ivon_audio_output_frame ivon_audio_output_frame_t

Mixed audio output frame (copy-out).

Returned by ivon_audio_try_read_output().

ivon_audio_pcm_source_fn

typedef int(* ivon_audio_pcm_source_fn) (float *pcm_out, int frame_size, void *user_data)

PCM source callback — pull mono float PCM from the user.

Called every tick (20 ms) while speaking. Fill pcm_out with frame_size samples.

Returns

Non-zero if audio was provided, zero for silence.

ivon_audio_post_mix_fn

typedef ivon_dsp_action_t(* ivon_audio_post_mix_fn) (ivon_post_mix_context_t *ctx, void *user_data)

Post-mix callback (final mixed output).

Returns

IVON_DSP_ACTION_CONTINUE or IVON_DSP_ACTION_STOP.

ivon_audio_post_spatial_fn

typedef ivon_dsp_action_t(* ivon_audio_post_spatial_fn) (ivon_post_spatial_context_t *ctx, void *user_data)

Post-spatial callback (expanded per-sender, after channel expansion).

Returns

IVON_DSP_ACTION_CONTINUE or IVON_DSP_ACTION_STOP.

ivon_audio_pre_dsp_fn

typedef ivon_dsp_action_t(* ivon_audio_pre_dsp_fn) (ivon_pre_dsp_context_t *ctx, void *user_data)

Pre-DSP callback (mono per-sender, after decode).

Returns

IVON_DSP_ACTION_CONTINUE or IVON_DSP_ACTION_STOP.

ivon_audio_speaking_event_fn

typedef void(* ivon_audio_speaking_event_fn) (const ivon_speaking_event_t *event, void *user_data)

Speaking state change callback.

ivon_audio_stats_t

typedef struct ivon_audio_stats ivon_audio_stats_t

Aggregate audio processor statistics.

Snapshot of counters from the decoder, encoder, and pipeline. Values are approximate when the processor is running (counters are updated from worker threads without full synchronisation).

ivon_audio_t

typedef struct ivon_audio* ivon_audio_t

C ABI types for the libivon audio processor.

Author

Cliff Foster (Nou) cliff.nosp@m.@idi.nosp@m.-syst.nosp@m.ems..nosp@m.com

Copyright

Copyright (c) 2025 International Development & Integration Systems LLC

Pure C header — no C++ dependencies. Defines the opaque handle, configuration structure, enumerations, and callback function-pointer typedefs used by ivon_audio.h.

Opaque handle to an audio processor instance.

ivon_codec_sample_rate_t

typedef enum ivon_codec_sample_rate ivon_codec_sample_rate_t

Supported codec-internal sample rates.

This affects the encoding resolution, not the PCM pipeline rate (which is always 48 kHz).

ivon_dsp_action_t

typedef enum ivon_dsp_action ivon_dsp_action_t

DSP callback return value — controls pipeline continuation.

ivon_frame_duration_t

typedef enum ivon_frame_duration ivon_frame_duration_t

Supported frame durations for audio codecs.

Not every codec supports every duration — an invalid combination will cause ivon_audio_create() to return NULL.

ivon_frame_type_t

typedef enum ivon_frame_type ivon_frame_type_t

How a decoded PCM frame was produced.

ivon_packet_buffer_t

typedef struct ivon_packet_buffer* ivon_packet_buffer_t

Opaque handle to a packet buffer from the audio processor's pool.

ivon_post_mix_context_t

typedef struct ivon_post_mix_context ivon_post_mix_context_t

Context for post-mix callbacks (final mixed stream).

PCM is the final mix (frame_size * channels samples, interleaved). Modify in-place.

ivon_post_spatial_context_t

typedef struct ivon_post_spatial_context ivon_post_spatial_context_t

Context for post-spatial callbacks (expanded per-sender).

PCM is expanded (frame_size * channels samples, interleaved). Modify in-place.

ivon_pre_dsp_context_t

typedef struct ivon_pre_dsp_context ivon_pre_dsp_context_t

Context for pre-DSP callbacks (mono per-sender).

PCM is mono, IVON_AUDIO_FRAME_SIZE samples. Modify in-place.

ivon_speaking_event_t

typedef struct ivon_speaking_event ivon_speaking_event_t

Speaking state transition event.

ivon_speaking_mode_t

typedef enum ivon_speaking_mode ivon_speaking_mode_t

How the local user is transmitting audio.

Enumeration Type Documentation

ivon_codec_sample_rate

enum ivon_codec_sample_rate

Supported codec-internal sample rates.

This affects the encoding resolution, not the PCM pipeline rate (which is always 48 kHz).

Enumerator
IVON_CODEC_SAMPLE_RATE_8000	8 kHz (narrowband)
IVON_CODEC_SAMPLE_RATE_12000	12 kHz (medium-band)
IVON_CODEC_SAMPLE_RATE_16000	16 kHz (wideband)
IVON_CODEC_SAMPLE_RATE_24000	24 kHz (super-wideband)
IVON_CODEC_SAMPLE_RATE_48000	48 kHz (fullband) — default

ivon_dsp_action

enum ivon_dsp_action

DSP callback return value — controls pipeline continuation.

Enumerator
IVON_DSP_ACTION_CONTINUE	Continue to next pipeline stage.
IVON_DSP_ACTION_STOP	Stop processing here.

ivon_frame_duration

enum ivon_frame_duration

Supported frame durations for audio codecs.

Not every codec supports every duration — an invalid combination will cause ivon_audio_create() to return NULL.

Enumerator
IVON_FRAME_DURATION_2_5_MS	2.5 ms (120 PCM samples at 48 kHz)
IVON_FRAME_DURATION_5_MS	5 ms (240 PCM samples at 48 kHz)
IVON_FRAME_DURATION_10_MS	10 ms (480 PCM samples at 48 kHz)
IVON_FRAME_DURATION_20_MS	20 ms (960 PCM samples at 48 kHz) — default
IVON_FRAME_DURATION_40_MS	40 ms (1920 PCM samples at 48 kHz) — maximum

ivon_frame_type

enum ivon_frame_type

How a decoded PCM frame was produced.

Enumerator
IVON_FRAME_TYPE_DECODED	Normal Opus decode.
IVON_FRAME_TYPE_FEC	Forward Error Correction recovery.
IVON_FRAME_TYPE_PLC	Opus packet-loss concealment.
IVON_FRAME_TYPE_SILENCE	Zeroed PCM (extended loss)

ivon_speaking_mode

enum ivon_speaking_mode

How the local user is transmitting audio.

Enumerator
IVON_SPEAKING_MODE_PTT	Push-to-talk.
IVON_SPEAKING_MODE_VAD	Voice-activity detection.
IVON_SPEAKING_MODE_PTT_VAD	PTT gated with VAD.
IVON_SPEAKING_MODE_CONTINUOUS	Hot mic / continuous.