libivon is a real-time multi-party voice communication library. It provides a stable C ABI for maximum portability and header-only C++ wrappers for ergonomic use from C++ consumers. This reference covers the public API surface: voice sessions, client networking, audio processing, and server administration.

Headers at a Glance

All public headers live under include/libivon/public/ within each component. Include them with #include "libivon/public/...".

Header	Purpose
`ivon_voice_session.h`	High-level API — bundles client + audio into one object
`ivon_voice_session_wrapper.hpp`	C++ RAII wrapper for the voice session
`ivon_voice_session_types.h`	Opaque handles, enums, and config for the voice session
`ivon_client.h`	Network client — connect, message, groups
`ivon_client_wrapper.hpp`	C++ RAII wrapper for the client
`ivon_client_interface.hpp`	Abstract C++ interface for the client
`ivon_client_types.h`	Opaque handles, enums, and callbacks for the client
`ivon_audio.h`	Audio processor — encode, decode, mix
`ivon_audio_wrapper.hpp`	C++ RAII wrapper for the audio processor
`ivon_audio_interface.hpp`	Abstract C++ interface for the audio processor
`ivon_audio_types.h`	Opaque handles, enums, frame duration, and constants
`ivon_server.h`	Server — accept connections, manage groups
`ivon_server_wrapper.hpp`	C++ RAII wrapper for the server
`ivon_server_interface.hpp`	Abstract C++ interface for the server
`ivon_server_types.h`	Opaque handles, enums, and callbacks for the server
`ivon_common_types.h`	Shared callback typedefs
`ivon_types.hpp`	C++ value types — `NegotiationError`, `AudioOutputFrame`, enums, callbacks

Each *_types.h header defines the opaque handles, enumerations, config structs, and callback typedefs used by the corresponding API header.

Quick Start — Voice Session (C++)

The voice session is the recommended entry point for most consumers. It wires the client and audio processor together automatically.

#include "libivon/public/ivon_voice_session_wrapper.hpp"
#include <iostream>
#include <span>
#include <vector>
 
// Application-provided stubs (replace with real implementations)
bool capture_mic(float *buf, size_t n);  // fill buf with n mono samples
void play_audio(const float *buf, size_t n);
volatile bool running = true;
 
int main() {
    // 1. Configure
    ivon::VoiceSessionWrapper::Config cfg;
    cfg.client.server_address = "192.168.1.100";
    cfg.client.server_port    = 9129;
    cfg.client.client_id      = "alice";
    cfg.voice_group_id        = "voice";      // auto-join after connect
    cfg.audio.output_channels = 2;            // stereo output
 
    // 2. Create session
    ivon::VoiceSessionWrapper session(cfg);
 
    // 3. Set PCM source (called each frame while speaking)
    session.set_pcm_source([](std::span<float> pcm_out) -> bool {
        // Fill pcm_out with mono float samples from your mic.
        // The span size equals the runtime frame size (e.g. 480 for 10 ms).
        return capture_mic(pcm_out.data(), pcm_out.size());
    });
 
    // 4. TOFU key verification (accept all keys in this example)
    session.on_tofu_verify([](const std::string &, auto, auto, auto) {
        return true;
    });
 
    // 5. React to speaking state changes
    session.on_speaking([](const ivon::VoiceSessionWrapper::SpeakingInfo &info) {
        std::cout << info.client_id
                  << (info.speaking ? " started" : " stopped")
                  << " speaking\n";
    });
 
    // 6. Connect (blocking)
    auto result = session.connect();
    if (!result) {
        std::cerr << "Connect failed: " << result.error().message()
                  << " — " << result.error().detail() << "\n";
        return 1;
    }
 
    // 7. Start audio processing
    session.start_audio();
    session.start_speaking(IVON_SPEAKING_MODE_VAD);
 
    // 8. Read mixed output in your audio thread.
    //    IVON_AUDIO_FRAME_SIZE (960) is the compile-time maximum;
    //    the actual frame size may be smaller when the server
    //    configures a shorter frame duration.
    std::vector<float> pcm(IVON_AUDIO_FRAME_SIZE * 2); // stereo max
    while (running) {
        auto frame = session.audio().try_read_output(pcm.data(), pcm.size());
        if (frame.valid) {
            play_audio(pcm.data(),
              static_cast<size_t>(frame.frame_size) * frame.channels);
        }
    }
 
    // 9. Cleanup (RAII handles the rest)
    session.audio().stop_speaking();
    session.disconnect();
}

Quick Start — Voice Session (C)

#include "libivon/public/ivon_voice_session.h"
#include <stdio.h>
 
/* Application-provided stubs (replace with real implementations) */
int  capture_mic(float *buf, int n);      /* fill buf with n mono samples */
void play_audio(const float *buf, int n);
volatile int running = 1;
 
static int pcm_source(float *pcm_out, int frame_size, void *user_data) {
    (void)user_data;
    /* Fill pcm_out with frame_size mono float samples */
    return capture_mic(pcm_out, frame_size);
}
 
static int tofu_verify(const char *server_id, ivon_tofu_verify_result_t result,
                       const uint8_t server_key[IVON_PUBLIC_KEY_SIZE],
                       const uint8_t *stored, void *user_data) {
    (void)server_id; (void)result; (void)server_key;
    (void)stored; (void)user_data;
    return 1; /* Accept all keys */
}
 
int main(void) {
    /* 1. Build configuration via opaque config handles */
    ivon_voice_session_config_t vs_cfg = ivon_voice_session_config_create();
 
    ivon_client_config_t c_cfg = ivon_client_config_create();
    ivon_client_config_set_server_address(c_cfg, "192.168.1.100");
    ivon_client_config_set_port(c_cfg, 9129);
    ivon_client_config_set_client_id(c_cfg, "alice");
    ivon_voice_session_config_set_client(vs_cfg, c_cfg);
    ivon_client_config_destroy(c_cfg);
 
    ivon_audio_config_t a_cfg = ivon_audio_config_create();
    ivon_audio_config_set_output_channels(a_cfg, 2);  /* stereo */
    ivon_voice_session_config_set_audio(vs_cfg, a_cfg);
    ivon_audio_config_destroy(a_cfg);
 
    ivon_voice_session_config_set_voice_group_id(vs_cfg, "voice");
 
    /* 2. Create session (copies config internally) */
    ivon_voice_session_t session = ivon_voice_session_create(vs_cfg);
    ivon_voice_session_config_destroy(vs_cfg);
    if (!session) { return 1; }
 
    /* 3. Register callbacks */
    ivon_voice_session_set_pcm_source(session, pcm_source, NULL);
 
    /* Set TOFU on the client handle */
    ivon_client_t client = ivon_voice_session_client_handle(session);
    ivon_client_set_on_tofu_verify(client, tofu_verify, NULL);
 
    /* 4. Connect */
    ivon_connect_result_t r = ivon_voice_session_connect(session);
    if (!r.success) {
        fprintf(stderr, "Connect failed: %s\n", r.message);
        ivon_voice_session_destroy(session);
        return 1;
    }
 
    /* 5. Start audio and speaking */
    ivon_voice_session_start_audio(session);
    ivon_voice_session_start_speaking(session, IVON_SPEAKING_MODE_VAD);
 
    /* 6. Read mixed output via audio handle.
     *    IVON_AUDIO_FRAME_SIZE (960) is the compile-time maximum;
     *    the actual frame size may be smaller depending on the
     *    server's frame_duration_ms property. */
    ivon_audio_t audio = ivon_voice_session_audio_handle(session);
    float pcm[IVON_AUDIO_FRAME_SIZE * 2];
    while (running) {
        ivon_audio_output_frame_t frame =
            ivon_audio_try_read_output(audio, pcm, sizeof(pcm)/sizeof(pcm[0]));
        if (frame.valid) {
            play_audio(pcm, frame.frame_size * frame.channels);
        }
    }
 
    /* 7. Cleanup */
    ivon_audio_stop_speaking(audio);
    ivon_voice_session_disconnect(session);
    ivon_voice_session_destroy(session);  /* NULL-safe */
}

Quick Start — Server

#include "libivon/public/ivon_server_wrapper.hpp"
#include <iostream>
#include <thread>
 
int main() {
    ivon::ServerWrapper::Config cfg;
    cfg.address = "0.0.0.0";
    cfg.port    = 9129;
    cfg.groups  = {"voice", "team-a", "team-b"};
 
    // Load identity keys from files
    cfg.key_files.public_key_file  = "server.pub";
    cfg.key_files.private_key_file = "server.key";
 
    // Optional: password authentication
    cfg.require_password = true;
    cfg.password         = "secret";
 
    // Create the wrapper — callbacks must be set BEFORE construction
    ivon::ServerWrapper server(cfg);
 
    // run() blocks; stop from another thread or signal handler
    std::thread stopper([&server] {
        wait_for_shutdown_signal();
        server.stop();
    });
 
    server.run();   // blocks until stop()
    stopper.join();
}

ServerWrapper callbacks (admission gates, auth hooks, connect/disconnect events) can be set before or after construction. Post-construction calls update the live server handle atomically:

ivon::ServerWrapper server(cfg);
 
// Callbacks can be installed at any time
server.on_client_connected([](const std::string &client_id, uint64_t session_id) {
    std::cout << client_id << " connected (session " << session_id << ")\n";
});
server.on_connection_admission([](const std::string &ip, uint16_t port) -> bool {
    return ip != "10.0.0.1"; // block a specific IP
});

For the C API, use ivon_server_config_set_on_*() on the config handle before calling ivon_server_create():

ivon_server_config_t cfg = ivon_server_config_create();
ivon_server_config_set_address(cfg, "0.0.0.0");
ivon_server_config_set_port(cfg, 9129);
ivon_server_config_add_group(cfg, "voice");
 
/* Gates and events — set on config before creating server */
ivon_server_config_set_on_client_connected(cfg, on_connected, NULL);
ivon_server_config_set_on_client_disconnected(cfg, on_disconnected, NULL);
 
ivon_server_t server = ivon_server_create(cfg);
ivon_server_config_destroy(cfg);  /* safe after create */
 
ivon_server_run(server);          /* blocks */
ivon_server_destroy(server);

Architecture

Threading Model

The library creates internal worker threads. Callbacks are invoked from these threads — they must be thread-safe and non-blocking.

Thread	Fires
Decoder workers (N)	`on_speaking_event`, `on_pre_dsp`
Pipeline workers (N)	`on_post_spatial`, `on_post_mix`
Encoder drain worker	(internal — drains encoded packets)
IO threads (server)	All server gate/event callbacks
Client IO thread	`on_client_message`, `on_client_joined/left`, group callbacks

Audio Format

Property	Value
Sample rate	48 000 Hz
Frame duration	20 ms default; configurable via `frame_duration` (2.5, 5, 10, 20, 40 ms)
Frame size	960 samples/channel at 20 ms; query at runtime with `pcm_frame_size()` / `ivon_audio_frame_size()`
Capture format	Mono `float` (PCM source callback)
Output format	Interleaved `float` (`try_read_output`)
Codec	Opus
Max output channels	8 (default 2 — stereo); query with `output_channels()` / `ivon_audio_output_channels()`

Object Ownership

All wrappers are RAII, move-only, non-copyable. The destructor stops the processor/server/client and frees all resources. Passing NULL to any C _destroy() function is a safe no-op.

The voice session owns its internal client and audio handles. Access the client handle via client_handle() for chat/presence callbacks, but do not destroy it or replace the audio/group callbacks that the session manages internally.

Standalone Client + Audio (Advanced)

For full control over the client and audio processor independently:

#include "libivon/public/ivon_client_wrapper.hpp"
#include "libivon/public/ivon_audio_wrapper.hpp"
 
// Create client
ivon::ClientWrapper::Config client_cfg;
client_cfg.server_address = "192.168.1.100";
client_cfg.client_id      = "bob";
ivon::ClientWrapper client(client_cfg);
 
// Create audio processor
ivon::AudioWrapper::Config audio_cfg;
audio_cfg.output_channels = 2;
audio_cfg.decoder_workers = 4;
ivon::AudioWrapper audio(audio_cfg);
 
// Wire fanout data → audio decoder
client.on_fanout_data([&audio](const std::string &group_id, uint64_t sender_id,
                               uint64_t seq, const unsigned char *data, size_t len) {
    audio.submit_packet(sender_id, data, len);
});
 
// Wire encoded audio → client send
// (run in your own drain loop)
std::array<unsigned char, 2048> pkt;
size_t n = audio.try_read_packet(pkt.data(), pkt.size());
if (n > 0) {
    client.send_group_data("voice", pkt.data(), n);
}
 
// Set up PCM source, connect, join group, start audio...

This is what the voice session does internally. Use this pattern when you need custom routing, multiple groups, or separate lifecycle control.

DSP Pipeline

The audio processor exposes three hook points in the decode → mix pipeline. Each callback receives a writeable PCM buffer — modify in-place to apply effects. Return IVON_DSP_ACTION_STOP to discard the frame.

Opus decode
    │
    ▼
┌──────────────────┐
│  on_pre_dsp      │  Mono per-sender (frame_size float samples)
│  (CONTINUE/STOP) │  Use for: per-speaker gain, noise gate, AGC
└──────────────────┘
    │
    ▼
Channel expansion (mono → stereo/surround)
    │
    ▼
┌──────────────────┐
│  on_post_spatial  │  Expanded per-sender (frame_size × channels floats)
│  (CONTINUE/STOP) │  Use for: spatial positioning, HRTF, panning
└──────────────────┘
    │
    ▼
Additive mix (all senders summed)
    │
    ▼
┌──────────────────┐
│  on_post_mix      │  Final mix (frame_size × channels floats)
│  (CONTINUE/STOP) │  Use for: limiter, master EQ, recording
└──────────────────┘
    │
    ▼
Output ring buffer → try_read_output()

frame_size is pcm_frame_size() (C++) or ivon_audio_frame_size() (C). The default is 960 (20 ms at 48 kHz), but the server may negotiate a different value.

audio.on_pre_dsp([](ivon_pre_dsp_context_t &ctx) -> ivon_dsp_action_t {
    // Apply per-sender noise gate
    float rms = compute_rms(ctx.pcm, ctx.frame_size);
    if (rms < threshold) {
        std::fill_n(ctx.pcm, ctx.frame_size, 0.0f);
    }
    return IVON_DSP_ACTION_CONTINUE;
});

Error Handling

Layer	C	C++
Object creation	Returns `NULL`	Throws `std::runtime_error`
Connection	`ivon_connect_result_t` with error codes and message	`expected_void<NegotiationError>`
Group operations	Status enum in result struct	Same struct passed through
Async operations	`int success` in completion callback	`std::function<void(bool)>`

Connection errors carry both a negotiation code (protocol/auth level) and a connection code (transport level). Check is_connection_error() to distinguish:

auto result = session.connect();
if (!result) {
    auto &err = result.error();
    if (err.is_connection_error()) {
        // Transport failure — check err.connection_code()
    } else {
        // Auth/protocol failure — check err.negotiation_code()
    }
    std::cerr << err.message() << "\n" << err.detail() << "\n";
}

TOFU Key Verification

The client uses Trust-On-First-Use for server identity. The TOFU callback receives the server's public key and a result indicating whether the key is new, trusted, or changed:

Result	Meaning	Recommended action
`IVON_TOFU_TRUSTED`	Key matches stored key	Accept
`IVON_TOFU_NEW_KEY`	First connection, no stored key	Prompt user or accept
`IVON_TOFU_KEY_CHANGED`	Key differs from stored	Warn user — possible MITM
`IVON_TOFU_VERIFICATION_ERROR`	Key verification failed	Reject

session.on_tofu_verify([](const std::string &server_id,
                         ivon::TofuVerifyResult result,
                         const std::array<uint8_t, ivon::PUBLIC_KEY_SIZE> &server_key,
                         const std::optional<std::array<uint8_t, ivon::PUBLIC_KEY_SIZE>> &stored_key) -> bool {
    if (result == ivon::TofuVerifyResult::key_changed) {
        std::cerr << "WARNING: Server key changed for " << server_id << "\n";
        return false;  // Reject
    }
    return true;       // Accept new or trusted keys
});

Server Authentication Pipeline

The server supports a multi-stage admission pipeline. Each gate is a callback that returns true (accept) or false (reject):

TCP connect
    │
    ▼
┌────────────────────────┐
│  on_connection_admission│  Gate: IP/port filtering
└────────────────────────┘
    │
    ▼
┌────────────────────────┐
│  on_client_id_check    │  Gate: validate client ID format/uniqueness
└────────────────────────┘
    │
    ▼
┌────────────────────────┐
│  on_password_validate  │  Gate: custom password check (if require_password)
└────────────────────────┘
    │
    ▼
┌────────────────────────┐
│  on_client_approve     │  Gate: final approval before visibility
└────────────────────────┘
    │
    ▼
┌────────────────────────┐
│  on_client_connected   │  Event: client is now registered
└────────────────────────┘

All gates are optional. If a gate callback is not set, the stage is automatically approved.

Configuration Reference

Audio (<tt>ivon_audio_config_t</tt> / <tt>AudioWrapper::Config</tt>)

Field	Default	Description
`frame_duration`	`IVON_FRAME_DURATION_20_MS`	Codec frame duration (2.5, 5, 10, 20, 40 ms)
`packet_pool_chunks`	4	Packet pool chunks (1024 buffers each)
`frame_pool_chunks`	4	Frame pool chunks (256 frames each)
`decoder_workers`	2	Decoder thread count
`jitter_depth`	2	Frames to buffer before playback (0 = bypass)
`pipeline_workers`	2	Pipeline (mix) thread count
`output_channels`	2	Output channels (1=mono, 2=stereo, up to 8)
`output_buffer_frames`	200	Output ring buffer capacity in frames
`encoder_bitrate`	64000	Opus target bitrate (bps)
`encoder_fec`	1	Enable Opus forward error correction
`encoder_fec_loss_percent`	5	Expected packet loss hint for FEC tuning
`encoder_complexity`	5	Opus complexity (0–10, higher = better quality)

Client (<tt>ivon_client_config_t</tt> / <tt>ClientWrapper::Config</tt>)

Field	Default	Description
`server_address`	`"127.0.0.1"`	Server hostname or IP
`server_port`	9129	Server TCP port
`client_id`	—	Unique identifier for this client
`key_store_path`	`NULL`	Path to TOFU key store file (NULL = in-memory)
`sync_timeout_seconds`	30	Initial sync timeout (0 = infinite)

Server (<tt>ivon_server_config_t</tt> / <tt>ServerWrapper::Config</tt>)

Field	Default	Description
`address`	`"0.0.0.0"`	Listen address
`port`	9129	Listen port
`network_interface`	—	Bind to specific interface (Linux only)
`num_threads`	1	IO thread count
`require_password`	false	Require client authentication
`password`	—	Expected password
`max_password_attempts`	3	Attempts before rejection
`groups`	—	Groups created at startup
`fanout_base_port`	10300	Base UDP port for audio multicast
`fanout_advertise_address`	`"127.0.0.1"`	Address advertised to clients
`key_rotation_on_leave`	true	Rotate group keys when members leave
`key_rotation_debounce_ms`	1000	Debounce interval for key rotation
`key_rotation_interval_ms`	0	Periodic key rotation (0 = disabled)

Voice Session (<tt>ivon_voice_session_config_t</tt> / <tt>VoiceSessionWrapper::Config</tt>)

Field	Default	Description
`client`	—	Nested client configuration
`audio`	—	Nested audio configuration
`voice_group_id`	`NULL`	Auto-join this group after connect
`poll_interval_ms`	10	Worker drain interval (ms)

Statistics

Both the audio processor and voice session expose runtime statistics:

auto stats = session.get_audio_stats();
 
// Pipeline health
stats.current_tick;    // Ticks elapsed since start
stats.max_drift_us;    // Maximum clock drift (microseconds)
stats.dropped_ticks;   // Ticks that couldn't keep up with real-time
 
// Decoder (across all workers and senders)
stats.packets_decoded; // Normal Opus decodes
stats.fec_recovered;   // Frames recovered via FEC
stats.plc_frames;      // Packet-loss concealment frames
stats.silence_frames;  // Extended-loss silence insertions
 
// Encoder
stats.packets_encoded; // Opus frames encoded for transmission

API Versioning

Each subsystem has compile-time and runtime version macros/functions:

/* Compile-time */
#if IVON_AUDIO_API_VERSION_MAJOR >= 2
    /* Use v2 API */
#endif
 
/* Runtime (check against loaded shared library) */
int major = ivon_audio_api_version_major();
int minor = ivon_audio_api_version_minor();

The C++ wrappers delegate to the same C ABI and share the version numbers.

Dynamic Loader (Runtime Loading)

Each profile generates a loader header that allows consumers to load the shared library at runtime via dlopen/LoadLibrary instead of linking against it at build time. This is useful for plugin architectures, optional dependencies, or applications that want to ship without bundling the .so.

The generated loader header provides:

Function-pointer typedefs for every exported C function
A global vtable struct populated at load time
Platform-aware dlopen/LoadLibrary open/close functions
Inline trampolines that match the original symbol names, so existing code compiles unchanged

Loader-Only Install

Each profile has a dedicated _loader install component that installs the loader header, all type headers, and the C++ wrapper headers — but not the shared library:

$ cmake --install build --component libivon_client_loader
$ cmake --install build --component libivon_server_loader
$ cmake --install build --component libivon_audio_loader

This gives consumers everything they need to compile against the API without requiring the .so at build time.

CMake Integration

In-tree targets can link against the loader INTERFACE target instead of the shared library:

target_link_libraries(my_app PRIVATE libivon_client_loader_target)

This target automatically provides:

Include directories for type headers and the generated loader header
The platform dl library on Linux
The LIBIVON_USE_CLIENT_LOADER compile definition, which tells the C++ wrappers to route through the loader trampolines instead of linked symbols

C++ Wrapper Compatibility

The C++ wrappers (ClientWrapper, AudioWrapper, VoiceSessionWrapper, ServerWrapper) work transparently in loader mode. When the LIBIVON_USE_<PROFILE>_LOADER define is active, the wrappers include the loader header instead of the C API header. Since the loader's inline trampolines provide the same symbol names as the linked library, no wrapper code changes are needed.

Usage (C)

Include the generated loader header directly. It provides the loader open/close functions and inline trampolines for every C API function. No library linking is required at build time — only -ldl on Linux:

$ gcc -I/path/to/includes/libivon my_app.c -ldl -o my_app

// Define the main-unit macro in exactly ONE translation unit
#define LIBIVON_CLIENT_LOADER_H_MAIN
#include "libivon/ivon_client_loader.h"
 
int main(void) {
    // Load the .so/.dll at runtime (NULL = default search path)
    if (ivon_client_loader_open(NULL) != 0)
        return 1;
 
    // All C API functions are now available as normal calls
    ivon_client_config_t cfg = ivon_client_config_create();
    ivon_client_config_set_server_address(cfg, "127.0.0.1");
    ivon_client_config_set_port(cfg, 9129);
    ivon_client_config_set_client_id(cfg, "my_app");
 
    ivon_client_t client = ivon_client_create(cfg);
    ivon_client_config_destroy(cfg);
    // ... use the API normally ...
    ivon_client_destroy(client);
 
    ivon_client_loader_close();
    return 0;
}

Usage (C++ with Wrapper)

Define LIBIVON_USE_CLIENT_LOADER before including the wrapper header. This tells the wrapper to pull in the loader header instead of the normal C API header, making the loader open/close functions and all API trampolines available:

Using a compile argument:

$ g++ -DLIBIVON_USE_CLIENT_LOADER -I/path/to/includes/libivon my_app.cpp -ldl -o my_app

Or inline:

#define LIBIVON_USE_CLIENT_LOADER
#include "libivon/public/ivon_client_wrapper.hpp"
 
int main() {
    // Load the .so/.dll at runtime
    if (ivon_client_loader_open(nullptr) != 0)
        return 1;
 
    {
        ivon::ClientWrapper::Config cfg{};
        cfg.server_address = "127.0.0.1";
        cfg.server_port    = 9129;
        cfg.client_id      = "my_app";
 
        ivon::ClientWrapper client(cfg);
        // ... use the C++ wrapper normally ...
 
    } // ClientWrapper destructor calls ivon_client_destroy() through the loader
 
    ivon_client_loader_close();
    return 0;
}

‍Note: If using the libivon CMake build tree, linking against libivon_client_loader_target sets LIBIVON_USE_CLIENT_LOADER, the include paths, and -ldl automatically — no manual flags needed.