#include "libivon/public/export.h"
#include "libivon/public/ivon_voice_session_types.h"

Macros
#define	IVON_VOICE_SESSION_API_VERSION_MAJOR 1
	C ABI for the libivon voice session helper.

#define	IVON_VOICE_SESSION_API_VERSION_MINOR 0
	Minor version of the voice session C ABI.

#define	IVON_LOG_LEVEL_TRACE 0
	Log level constants (shared across all ivon subsystems).

#define	IVON_LOG_LEVEL_DEBUG 1

#define	IVON_LOG_LEVEL_INFO 2

#define	IVON_LOG_LEVEL_WARN 3

#define	IVON_LOG_LEVEL_ERROR 4

#define	IVON_LOG_LEVEL_CRITICAL 5

#define	IVON_LOG_LEVEL_OFF 6

Functions
int	ivon_voice_session_api_version_major (void)
	Get the major version of the voice session C ABI at runtime.

int	ivon_voice_session_api_version_minor (void)
	Get the minor version of the voice session C ABI at runtime.

ivon_voice_session_config_t	ivon_voice_session_config_create (void)
	Create a new voice session configuration with defaults.

void	ivon_voice_session_config_destroy (ivon_voice_session_config_t config)
	Destroy a voice session configuration. NULL is a safe no-op.

void	ivon_voice_session_config_set_client (ivon_voice_session_config_t config, ivon_client_config_t client)
	Set the client sub-configuration.

void	ivon_voice_session_config_set_audio (ivon_voice_session_config_t config, ivon_audio_config_t audio)
	Set the audio sub-configuration.

void	ivon_voice_session_config_set_voice_group_id (ivon_voice_session_config_t config, const char *group_id)
	Set the voice group to auto-join after connection.

void	ivon_voice_session_config_set_poll_interval (ivon_voice_session_config_t config, uint32_t ms)
	Set the worker poll interval in milliseconds (0 = default 10 ms).

ivon_voice_session_t	ivon_voice_session_create (ivon_voice_session_config_t config)
	Create a new voice session.

void	ivon_voice_session_destroy (ivon_voice_session_t session)
	Destroy a voice session and free all resources.

ivon_connect_result_t	ivon_voice_session_connect (ivon_voice_session_t session)
	Connect to the server (blocking).

void	ivon_voice_session_disconnect (ivon_voice_session_t session)
	Disconnect from the server.

void	ivon_voice_session_start_audio (ivon_voice_session_t session)
	Start the audio processor (tick coordinator + worker threads).

void	ivon_voice_session_stop_audio (ivon_voice_session_t session)
	Stop the audio processor.

void	ivon_voice_session_set_pcm_source (ivon_voice_session_t session, ivon_audio_pcm_source_fn callback, void *user_data)
	Set the PCM source callback for local audio capture.

void	ivon_voice_session_start_speaking (ivon_voice_session_t session, ivon_speaking_mode_t mode)
	Start speaking (PTT activated).

void	ivon_voice_session_enable_transmit (ivon_voice_session_t session, const char *group_id)
	Enable audio transmission.

void	ivon_voice_session_disable_transmit (ivon_voice_session_t session, const char *group_id)
	Disable audio transmission.

int	ivon_voice_session_join_voice_group (ivon_voice_session_t session, const char *group_id)
	Manually join a voice group.

int	ivon_voice_session_leave_voice_group (ivon_voice_session_t session, const char *group_id)
	Leave a voice group.

int	ivon_voice_session_is_voice_group_joined (ivon_voice_session_t session, const char *group_id)
	Check if a voice group has been joined.

ivon_client_t	ivon_voice_session_client_handle (ivon_voice_session_t session)
	Get the underlying client handle.

ivon_audio_t	ivon_voice_session_audio_handle (ivon_voice_session_t session)
	Get the underlying audio processor handle (non-owning).

uint64_t	ivon_voice_session_local_sender_id (ivon_voice_session_t session)
	Get the local fanout sender ID.

void	ivon_voice_session_set_on_voice_joined (ivon_voice_session_t session, ivon_voice_session_voice_joined_fn callback, void *user_data)
	Set callback for voice group join result.

void	ivon_voice_session_set_on_speaking (ivon_voice_session_t session, ivon_voice_session_speaking_fn callback, void *user_data)
	Set callback for remote speaking state changes.

void	ivon_voice_session_set_on_voice_error (ivon_voice_session_t session, ivon_voice_session_voice_error_fn callback, void *user_data)
	Set callback for voice group runtime errors.

void	ivon_voice_session_set_on_member_joined (ivon_voice_session_t session, ivon_voice_session_member_joined_fn callback, void *user_data)
	Set callback for when a member joins the voice group.

void	ivon_voice_session_set_on_member_left (ivon_voice_session_t session, ivon_voice_session_member_left_fn callback, void *user_data)
	Set callback for when a member leaves the voice group.

size_t	ivon_voice_session_get_speaking_senders (ivon_voice_session_t session, uint64_t *sender_ids_out, size_t max_count)
	Get the sender IDs of currently speaking remote senders.

void	ivon_voice_session_get_audio_stats (ivon_voice_session_t session, ivon_audio_stats_t *out)
	Get aggregate audio statistics for the session.

void	ivon_voice_session_set_log_level (ivon_voice_session_t session, int level)
	Set the runtime log level for the session's internal loggers.

int	ivon_voice_session_get_log_level (ivon_voice_session_t session)
	Get the current log level of the session's client logger.

Macro Definition Documentation

◆ IVON_LOG_LEVEL_CRITICAL

#define IVON_LOG_LEVEL_CRITICAL 5

◆ IVON_LOG_LEVEL_DEBUG

#define IVON_LOG_LEVEL_DEBUG 1

◆ IVON_LOG_LEVEL_ERROR

#define IVON_LOG_LEVEL_ERROR 4

◆ IVON_LOG_LEVEL_INFO

#define IVON_LOG_LEVEL_INFO 2

◆ IVON_LOG_LEVEL_OFF

#define IVON_LOG_LEVEL_OFF 6

◆ IVON_LOG_LEVEL_TRACE

#define IVON_LOG_LEVEL_TRACE 0

Log level constants (shared across all ivon subsystems).

Values match idi::logging::level and spdlog::level::level_enum.

◆ IVON_LOG_LEVEL_WARN

#define IVON_LOG_LEVEL_WARN 3

◆ IVON_VOICE_SESSION_API_VERSION_MAJOR

#define IVON_VOICE_SESSION_API_VERSION_MAJOR 1

C ABI for the libivon voice session helper.

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

The voice session bundles a client connection and audio processor into a single object. Internally it provides zero-copy wiring:

Fanout data → pool-allocated buffer → audio decoder (no extra copy)
Encoded audio → client send_group_data (direct drain)
Group membership events → automatic sender registration

Consumers provide PCM via a callback and read mixed output via ivon_audio_try_read_output() on the session's audio handle. All network, decode, encode, and mixing runs inside the session's worker threads.

The session exposes both an ivon_client_t and ivon_audio_t handle via ivon_voice_session_client_handle() / ivon_voice_session_audio_handle(). Use these handles to call client/audio functions directly (e.g. ivon_client_is_connected(), ivon_audio_is_speaking()).

Audio/group callbacks on the client handle are reserved by the session — do not replace them.

See also: ivon_voice_session_types.h for type definitions.

Major version of the voice session C ABI.

◆ IVON_VOICE_SESSION_API_VERSION_MINOR

#define IVON_VOICE_SESSION_API_VERSION_MINOR 0

Minor version of the voice session C ABI.

Function Documentation

◆ ivon_voice_session_api_version_major()

int ivon_voice_session_api_version_major ( void )

Get the major version of the voice session C ABI at runtime.

◆ ivon_voice_session_api_version_minor()

int ivon_voice_session_api_version_minor ( void )

Get the minor version of the voice session C ABI at runtime.

◆ ivon_voice_session_audio_handle()

ivon_audio_t ivon_voice_session_audio_handle ( ivon_voice_session_t session )

Get the underlying audio processor handle (non-owning).

The returned handle is owned by the session — do NOT call ivon_audio_destroy() on it.

Use this handle to call ivon_audio_*() functions directly (e.g. ivon_audio_is_running(), ivon_audio_is_speaking(), ivon_audio_set_sender_gain(), ivon_audio_try_read_output()).

Warning: Returns NULL before ivon_voice_session_start_audio() has been called.

◆ ivon_voice_session_client_handle()

ivon_client_t ivon_voice_session_client_handle ( ivon_voice_session_t session )

Get the underlying client handle.

The returned handle is owned by the session — do NOT call ivon_client_destroy() on it.

Use this handle to register non-audio callbacks (chat, presence, TOFU, etc.) and to call client methods like send_client_message().

Warning

Do NOT replace the following callbacks on this handle; they are managed internally by the voice session:

on_fanout_data
on_group_joined
on_group_member_joined
on_group_member_left
on_group_mute
on_fanout_error

◆ ivon_voice_session_config_create()

ivon_voice_session_config_t ivon_voice_session_config_create ( void )

Create a new voice session configuration with defaults.

Embeds default client and audio sub-configurations. Use the ivon_voice_session_config_set_*() functions to customise, then pass to ivon_voice_session_create().

Returns: A new config handle, or NULL on allocation failure.

◆ ivon_voice_session_config_destroy()

void ivon_voice_session_config_destroy ( ivon_voice_session_config_t config )

Destroy a voice session configuration. NULL is a safe no-op.

◆ ivon_voice_session_config_set_audio()

void ivon_voice_session_config_set_audio	(	ivon_voice_session_config_t	config,
		ivon_audio_config_t	audio
	)

Set the audio sub-configuration.

Copies the contents of audio into the session config. The caller retains ownership of audio and must destroy it separately.

◆ ivon_voice_session_config_set_client()

void ivon_voice_session_config_set_client	(	ivon_voice_session_config_t	config,
		ivon_client_config_t	client
	)

Set the client sub-configuration.

Copies the contents of client into the session config. The caller retains ownership of client and must destroy it separately.

◆ ivon_voice_session_config_set_poll_interval()

void ivon_voice_session_config_set_poll_interval	(	ivon_voice_session_config_t	config,
		uint32_t	ms
	)

Set the worker poll interval in milliseconds (0 = default 10 ms).

◆ ivon_voice_session_config_set_voice_group_id()

void ivon_voice_session_config_set_voice_group_id	(	ivon_voice_session_config_t	config,
		const char *	group_id
	)

Set the voice group to auto-join after connection.

Parameters

group_id Group ID string (copied), or NULL for manual management.

◆ ivon_voice_session_connect()

ivon_connect_result_t ivon_voice_session_connect ( ivon_voice_session_t session )

Connect to the server (blocking).

If voice_group_id was set in the config, the session will automatically join that voice group after connection.

Returns: Connection result with error details on failure.

◆ ivon_voice_session_create()

ivon_voice_session_t ivon_voice_session_create ( ivon_voice_session_config_t config )

Create a new voice session.

Creates the internal client and audio processor. The config handle may be destroyed after this call returns.

Parameters

config Session configuration handle.

Returns: A new session handle, or NULL on failure.

◆ ivon_voice_session_destroy()

void ivon_voice_session_destroy ( ivon_voice_session_t session )

Destroy a voice session and free all resources.

Stops audio, disconnects the client, and frees everything. Passing NULL is a safe no-op.

◆ ivon_voice_session_disable_transmit()

void ivon_voice_session_disable_transmit	(	ivon_voice_session_t	session,
		const char *	group_id
	)

Disable audio transmission.

Parameters

session	The session handle.
group_id	The group to disable transmit for (NULL = all joined groups).

◆ ivon_voice_session_disconnect()

void ivon_voice_session_disconnect ( ivon_voice_session_t session )

Disconnect from the server.

Stops audio processing and disconnects.

◆ ivon_voice_session_enable_transmit()

void ivon_voice_session_enable_transmit	(	ivon_voice_session_t	session,
		const char *	group_id
	)

Enable audio transmission.

Call after the voice group join is confirmed. Until called, start_speaking() will not actually begin encoding.

Note: Automatically called when auto-join succeeds. Only needed for manual group management.

Parameters

session	The session handle.
group_id	The group to enable transmit for (NULL = all joined groups).

◆ ivon_voice_session_get_audio_stats()

void ivon_voice_session_get_audio_stats	(	ivon_voice_session_t	session,
		ivon_audio_stats_t *	out
	)

Get aggregate audio statistics for the session.

Convenience passthrough to the internal audio processor.

Parameters

session	The session handle.
out	Pointer to a stats struct to fill.

◆ ivon_voice_session_get_log_level()

int ivon_voice_session_get_log_level ( ivon_voice_session_t session )

Get the current log level of the session's client logger.

Parameters

session The session handle.

Returns: The current log level (IVON_LOG_LEVEL_*), or IVON_LOG_LEVEL_OFF if the session or logger is unavailable.

◆ ivon_voice_session_get_speaking_senders()

size_t ivon_voice_session_get_speaking_senders	(	ivon_voice_session_t	session,
		uint64_t *	sender_ids_out,
		size_t	max_count
	)

Get the sender IDs of currently speaking remote senders.

Writes up to max_count sender IDs into the output array.

Parameters

session	The session handle.
sender_ids_out	Output array for sender IDs.
max_count	Maximum entries to write.

Returns: Number of speaking senders (may exceed max_count).

◆ ivon_voice_session_is_voice_group_joined()

int ivon_voice_session_is_voice_group_joined	(	ivon_voice_session_t	session,
		const char *	group_id
	)

Check if a voice group has been joined.

Parameters

session	The session handle.
group_id	The group to check (NULL checks any group).

Returns: Non-zero if joined.

◆ ivon_voice_session_join_voice_group()

int ivon_voice_session_join_voice_group	(	ivon_voice_session_t	session,
		const char *	group_id
	)

Manually join a voice group.

Use this if voice_group_id was NULL in the config.

Returns: Non-zero if the join request was sent.

◆ ivon_voice_session_leave_voice_group()

int ivon_voice_session_leave_voice_group	(	ivon_voice_session_t	session,
		const char *	group_id
	)

Leave a voice group.

Parameters

session	The session handle.
group_id	The group to leave.

Returns: Non-zero if the leave request was sent.

◆ ivon_voice_session_local_sender_id()

uint64_t ivon_voice_session_local_sender_id ( ivon_voice_session_t session )

Get the local fanout sender ID.

Derived from the session ID after connection. Returns 0 if not yet connected.

◆ ivon_voice_session_set_log_level()

void ivon_voice_session_set_log_level	(	ivon_voice_session_t	session,
		int	level
	)

Set the runtime log level for the session's internal loggers.

Propagates to both the client and audio processor loggers (if they exist). The change takes effect immediately for subsequent log calls.

Parameters

session	The session handle.
level	One of the IVON_LOG_LEVEL_* constants (0–6).

◆ ivon_voice_session_set_on_member_joined()

void ivon_voice_session_set_on_member_joined	(	ivon_voice_session_t	session,
		ivon_voice_session_member_joined_fn	callback,
		void *	user_data
	)

Set callback for when a member joins the voice group.

◆ ivon_voice_session_set_on_member_left()

void ivon_voice_session_set_on_member_left	(	ivon_voice_session_t	session,
		ivon_voice_session_member_left_fn	callback,
		void *	user_data
	)

Set callback for when a member leaves the voice group.

◆ ivon_voice_session_set_on_speaking()

void ivon_voice_session_set_on_speaking	(	ivon_voice_session_t	session,
		ivon_voice_session_speaking_fn	callback,
		void *	user_data
	)

Set callback for remote speaking state changes.

◆ ivon_voice_session_set_on_voice_error()

void ivon_voice_session_set_on_voice_error	(	ivon_voice_session_t	session,
		ivon_voice_session_voice_error_fn	callback,
		void *	user_data
	)

Set callback for voice group runtime errors.

◆ ivon_voice_session_set_on_voice_joined()

void ivon_voice_session_set_on_voice_joined	(	ivon_voice_session_t	session,
		ivon_voice_session_voice_joined_fn	callback,
		void *	user_data
	)

Set callback for voice group join result.

◆ ivon_voice_session_set_pcm_source()

void ivon_voice_session_set_pcm_source	(	ivon_voice_session_t	session,
		ivon_audio_pcm_source_fn	callback,
		void *	user_data
	)

Set the PCM source callback for local audio capture.

Must be set before starting audio.

◆ ivon_voice_session_start_audio()

void ivon_voice_session_start_audio ( ivon_voice_session_t session )

Start the audio processor (tick coordinator + worker threads).

PCM source callback must be set before calling this.

◆ ivon_voice_session_start_speaking()

void ivon_voice_session_start_speaking	(	ivon_voice_session_t	session,
		ivon_speaking_mode_t	mode
	)

Start speaking (PTT activated).

◆ ivon_voice_session_stop_audio()

void ivon_voice_session_stop_audio ( ivon_voice_session_t session )

Stop the audio processor.

Macros

Functions

Macro Definition Documentation

◆ IVON_LOG_LEVEL_CRITICAL

◆ IVON_LOG_LEVEL_DEBUG

◆ IVON_LOG_LEVEL_ERROR

◆ IVON_LOG_LEVEL_INFO

◆ IVON_LOG_LEVEL_OFF

◆ IVON_LOG_LEVEL_TRACE

◆ IVON_LOG_LEVEL_WARN

◆ IVON_VOICE_SESSION_API_VERSION_MAJOR

◆ IVON_VOICE_SESSION_API_VERSION_MINOR

Function Documentation

◆ ivon_voice_session_api_version_major()

◆ ivon_voice_session_api_version_minor()

◆ ivon_voice_session_audio_handle()

◆ ivon_voice_session_client_handle()

◆ ivon_voice_session_config_create()

◆ ivon_voice_session_config_destroy()

◆ ivon_voice_session_config_set_audio()

◆ ivon_voice_session_config_set_client()

◆ ivon_voice_session_config_set_poll_interval()

◆ ivon_voice_session_config_set_voice_group_id()

◆ ivon_voice_session_connect()

◆ ivon_voice_session_create()

◆ ivon_voice_session_destroy()

◆ ivon_voice_session_disable_transmit()

◆ ivon_voice_session_disconnect()

◆ ivon_voice_session_enable_transmit()

◆ ivon_voice_session_get_audio_stats()

◆ ivon_voice_session_get_log_level()

◆ ivon_voice_session_get_speaking_senders()

◆ ivon_voice_session_is_voice_group_joined()

◆ ivon_voice_session_join_voice_group()

◆ ivon_voice_session_leave_voice_group()

◆ ivon_voice_session_local_sender_id()

◆ ivon_voice_session_set_log_level()

◆ ivon_voice_session_set_on_member_joined()

◆ ivon_voice_session_set_on_member_left()

◆ ivon_voice_session_set_on_speaking()

◆ ivon_voice_session_set_on_voice_error()

◆ ivon_voice_session_set_on_voice_joined()

◆ ivon_voice_session_set_pcm_source()

◆ ivon_voice_session_start_audio()

◆ ivon_voice_session_start_speaking()

◆ ivon_voice_session_stop_audio()