Talon/voice-cat
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Cleanup core header and proto code
Some checks failed
Build Linux Binaries / linux/amd64 (push) Has been cancelled
Details
Build Linux Binaries / linux/arm64 (push) Has been cancelled
Details

Browse Source
This commit is contained in:
Talon
2026-07-03 12:46:51 +01:00
parent 5c03e5f261
commit bd844e4710
2 changed files with 70 additions and 112 deletions
Download Patch File Download Diff File Expand all files Collapse all files

128
core/include/voicecat.h
View File

@@ -1,16 +1,7 @@
/*
* voicecat.h — the C ABI for libvoicecat.
*
* This is the single boundary every front-end calls: Swift (macOS/iOS) and C# (Windows)
* both bind to this header, and the server links the same core. It is C-linkage and
* handle-based so it is stable and trivially bindable from any language.
*
* Design: docs/architecture.md §4. Everything here is async + event-driven — calls return
* immediately and results/state changes arrive via the vc_callbacks.on_event callback.
*
* webrtc AEC/NS/AGC remains an inert passthrough (no Windows/MSVC port upstream — see
* docs/voice.md §8/§11).
*/
*/
#ifndef VOICECAT_H
#define VOICECAT_H
@@ -21,7 +12,7 @@
extern "C" {
#endif
/* ── Export macro ─────────────────────────────────────────────────────────── */
#if defined(VOICECAT_STATIC)
#define VC_API
#elif defined(_WIN32)
@@ -38,17 +29,14 @@ extern "C" {
#endif
#endif
/* ── Version ──────────────────────────────────────────────────────────────── */
#define VOICECAT_VERSION_MAJOR 0
#define VOICECAT_VERSION_MINOR 0
#define VOICECAT_VERSION_PATCH 2 /* +vc_set_mixed_output_sink / vc_set_external_playback (iOS VPIO) */
#define VOICECAT_VERSION_PATCH 2
/* The control-protocol version this build speaks (docs/protocol.md §4).
* v2 widened the UDP voice frame seq field u16 → u64 (docs/voice.md §2); a v2 server
* and a v1 client cannot interoperate, so the Hello handshake rejects on mismatch. */
#define VOICECAT_PROTOCOL_VERSION 2
/* ── Result codes ─────────────────────────────────────────────────────────── */
typedef enum vc_result {
VC_OK = 0,
VC_ERR_NOT_IMPLEMENTED = 1,
@@ -80,9 +68,6 @@ typedef enum vc_connection_state {
VC_STATE_TLS_HANDSHAKE = 2,
VC_STATE_AUTHENTICATING = 3,
VC_STATE_CONNECTED = 4,
/* Between TLS_HANDSHAKE and AUTHENTICATING — the handshake succeeded and the core is
* waiting for vc_confirm_server_identity() (see VC_EVENT_SERVER_IDENTITY below). Appended
* at the end (not inserted) to keep existing enum values stable — additive-only ABI. */
VC_STATE_VERIFYING_IDENTITY = 5,
} vc_connection_state;
@@ -99,21 +84,20 @@ typedef enum vc_device_kind {
typedef enum vc_stream_kind {
VC_STREAM_MIC = 0,
VC_STREAM_SCREEN_AUDIO = 1, /* system/desktop audio (docs/voice.md §9) */
VC_STREAM_SCREEN_AUDIO = 1,
VC_STREAM_AUX_DEVICE = 2,
} vc_stream_kind;
/* Send-side input gate (docs/voice.md §11). */
typedef enum vc_input_mode {
VC_INPUT_VOICE_ACTIVATION = 0,
VC_INPUT_PUSH_TO_TALK = 1,
/* Transmit unconditionally — no VAD gate. Added at the end to keep existing values stable. */
VC_INPUT_ALWAYS_ON = 2,
} vc_input_mode;
typedef enum vc_event_type {
VC_EVENT_CONNECTION_STATE = 0, /* connection_state set */
VC_EVENT_AUTH_RESULT = 1, /* result set; user_id = self on success */
VC_EVENT_CONNECTION_STATE = 0,
VC_EVENT_AUTH_RESULT = 1,
VC_EVENT_CHANNEL_LIST = 2, /* channel tree snapshot/delta available */
VC_EVENT_USER_JOINED = 3, /* user_id, channel_id, text = nickname */
VC_EVENT_USER_LEFT = 4, /* user_id */
@@ -124,7 +108,6 @@ typedef enum vc_event_type {
VC_EVENT_TALK_STATE = 9, /* user_id, stream_id, u32a = talking(0/1) */
VC_EVENT_ERROR = 10, /* result, text */
VC_EVENT_DISCONNECTED = 11, /* result, text = reason */
/* Appended, not inserted, to keep existing enum values stable. */
VC_EVENT_JOIN_RESULT = 12, /* result (VC_OK/VC_ERR_*), channel_id, text = error on
failure. Reply to vc_join_channel(). */
VC_EVENT_SERVER_IDENTITY = 13, /* u32a = vc_tofu_status, text = hex-encoded TLS leaf-cert
@@ -133,7 +116,6 @@ typedef enum vc_event_type {
attempt, right after the TLS handshake succeeds. The
connection is held open until vc_confirm_server_identity()
is called. */
/* Appended, not inserted. */
VC_EVENT_GENERIC_RESULT = 14, /* result, u32a = server error code, text = message. Reply
to vc_kick_user/vc_ban_user/vc_set_permission/
vc_move_user/vc_create_channel/vc_edit_channel/
@@ -155,13 +137,12 @@ typedef enum vc_event_type {
* fingerprint is still available for human-readable display via
* vc_get_server_identity_display(), it just isn't the value this gate accepts/rejects on. */
typedef enum vc_tofu_status {
VC_TOFU_FIRST_CONNECT = 0, /* no pin on file yet for this host:port */
VC_TOFU_MATCHED = 1, /* matches the previously pinned fingerprint */
VC_TOFU_MISMATCH = 2, /* DIFFERENT from the pinned fingerprint — possible MITM or a
legitimate server key rotation; warn loudly */
VC_TOFU_FIRST_CONNECT = 0,
VC_TOFU_MATCHED = 1,
VC_TOFU_MISMATCH = 2,
} vc_tofu_status;
/* ── Structs ──────────────────────────────────────────────────────────────── */
/*
* An event delivered to vc_callbacks.on_event. Pointer fields are owned by the core and
@@ -193,12 +174,7 @@ typedef struct vc_config {
const char* client_name; /* e.g. "VoiceCat-macOS" */
const char* client_version; /* e.g. "0.0.1" */
vc_log_level log_level;
/* Optional (added at the end — existing brace-initialized callers default this to
* NULL, no source change needed). Path to the TOFU pin file (see VC_EVENT_SERVER_IDENTITY/
* vc_confirm_server_identity). NULL = a built-in relative default
* ("./voicecat_tofu_pins.txt") so existing tests need no real persistence. A real app
* (e.g. the Windows client) should pass an explicit per-user path, e.g.
* "%AppData%\VoiceCat\tofu_pins.txt". */
const char* tofu_store_path;
} vc_config;
@@ -215,7 +191,7 @@ typedef struct vc_stream_desc {
} vc_stream_desc;
/* The effective Opus configuration in use for a stream — for a stream you own, this is
* StreamAnnounceResult.effective_audio (channel-enforced, docs/voice.md §3); for a remote
* StreamAnnounceResult.effective_audio (channel-enforced; for a remote
* stream, it's the peer's broadcast StreamInfo.audio. See vc_get_stream_audio_config. */
typedef struct vc_audio_config {
uint32_t codec; /* 0 = OPUS */
@@ -279,9 +255,9 @@ typedef struct vc_device_list {
size_t count;
} vc_device_list;
/* ── Channel / user / stream snapshots (for the channel-tree/user-list UI) ────────────────
/* Channel / user / stream snapshots (for the channel-tree/user-list UI)
* Pull-based: re-call after VC_EVENT_CHANNEL_LIST / VC_EVENT_USER_JOINED / _LEFT / _UPDATED to
* refresh — there is no push variant; those events just mean "go look". Same ownership
* refresh, there is no push variant; those events just mean "go look". Same ownership
* contract as vc_device/vc_device_list above: core-allocated, caller frees with the matching
* vc_free_*, items' const char* fields are invalid after that call. */
typedef struct vc_channel {
@@ -292,7 +268,7 @@ typedef struct vc_channel {
int password_protected; /* bool */
uint32_t max_users; /* 0 = unlimited */
uint32_t sort_order; /* channel sort order */
/* Authoritative channel Opus params (docs/voice.md §3). Populated from the Channel proto
/* Authoritative channel Opus params. Populated from the Channel proto
* so the edit dialog can read back the current config without a separate round-trip. */
vc_audio_config audio;
} vc_channel;
@@ -334,11 +310,11 @@ typedef struct vc_stream_summary_list {
/* Receive-side state the local listener has chosen for a specific remote stream — the
* counterpart to vc_set_remote_stream, so a UI can reopen its per-mix controls at the
* listener's actual current settings. All LOCAL (no protocol traffic) — docs/voice.md §10.
* listener's actual current settings. All LOCAL (no protocol traffic).
* If (user_id, stream_id) is known but the listener has never called vc_set_remote_stream on
* it, the defaults are gain=1.0, muted=0, noise_reduction=0 (matching a fresh RemoteStream). */
typedef struct vc_remote_stream_state {
float gain; /* 0.0–… ; default 1.0 */
float gain; /* 0.0… ; default 1.0 */
int muted; /* bool */
int noise_reduction; /* bool */
} vc_remote_stream_state;
@@ -346,29 +322,29 @@ typedef struct vc_remote_stream_state {
/* Opaque client handle. */
typedef struct vc_client vc_client;
/* ── Lifecycle ────────────────────────────────────────────────────────────── */
/* Lifecycle */
VC_API const char* vc_version_string(void);
VC_API const char* vc_result_string(vc_result code);
VC_API vc_client* vc_client_create(const vc_config* cfg, vc_callbacks cb);
VC_API void vc_client_destroy(vc_client* c);
/* ── Connection & auth (async; results via on_event) ──────────────────────── */
/* Connection & auth (async; results via on_event) */
VC_API vc_result vc_connect(vc_client* c, const char* host, uint16_t port);
VC_API vc_result vc_disconnect(vc_client* c);
VC_API vc_result vc_authenticate_guest(vc_client* c, const char* nickname);
VC_API vc_result vc_authenticate_user(vc_client* c, const char* username,
const char* password);
/* ── Channels ─────────────────────────────────────────────────────────────── */
/* Result arrives as VC_EVENT_JOIN_RESULT, not a return value beyond "request queued". `password`
/* Channels */
/* Result arrives as VC_EVENT_JOIN_RESULT, not a return value beyond "request queued". password
* is forwarded to the server's JoinChannelRequest.password and checked against the channel's
* stored password for channels with vc_channel.password_protected set. */
VC_API vc_result vc_join_channel(vc_client* c, uint32_t channel_id,
const char* password /* nullable */);
VC_API vc_result vc_leave_channel(vc_client* c);
/* ── Voice-plane subscription ─────────────────────────────────────────────── */
/* Voice-plane subscription */
/* Joining voice subscribes to the voice plane: the server starts relaying voice frames
* to you, and the core wires up remote-stream decoders so you hear other users. Leaving
* voice unsubscribes: the server stops relaying voice to you, the core tears down all
@@ -378,7 +354,7 @@ VC_API vc_result vc_leave_channel(vc_client* c);
VC_API vc_result vc_join_voice(vc_client* c);
VC_API vc_result vc_leave_voice(vc_client* c);
/* ── Local media streams (mic / screen audio / aux) ───────────────────────── */
/* Local media streams (mic / screen audio / aux) */
VC_API vc_result vc_stream_start(vc_client* c, const vc_stream_desc* desc,
uint32_t* out_stream_id);
VC_API vc_result vc_stream_stop(vc_client* c, uint32_t stream_id);
@@ -395,22 +371,22 @@ VC_API vc_result vc_set_push_to_talk(vc_client* c, int active /* bool */);
VC_API vc_result vc_set_self_mute(vc_client* c, int mic_muted, int deafened);
/* Global playback volume applied after mixing all remote streams. gain 0.0 = silent,
* 1.0 = unity (default), >1.0 amplifies. Always LOCAL — no protocol traffic. */
* 1.0 = unity (default), >1.0 amplifies. */
VC_API vc_result vc_set_output_volume(vc_client* c, float gain);
/* Send-side microphone input gain. Applied to captured MIC PCM before the VAD/PTT gate and
* Opus encode (so boosting a quiet mic also helps it cross the VAD threshold). gain 0.0 = silent,
* 1.0 = unity (default), >1.0 amplifies; the boosted signal is clamped to int16. MIC stream only;
* always LOCAL — no protocol traffic. */
* */
VC_API vc_result vc_set_input_gain(vc_client* c, float gain);
/* Send-side microphone noise suppression (RNNoise). Denoises captured MIC PCM before the input
* gain and the VAD/PTT gate, so everyone hears the cleaned signal (one pass for all listeners).
* enable != 0 turns it on. MIC stream only, mono only; always LOCAL — no protocol traffic.
* Independent of the per-listener receive-side NR in vc_set_remote_stream (docs/voice.md §10). */
* enable != 0 turns it on. MIC stream only, mono only
* Independent of the per-listener receive-side NR in vc_set_remote_stream */
VC_API vc_result vc_set_input_noise_reduction(vc_client* c, int enable);
/* Receive-side, per remote stream, all LOCAL (no protocol traffic) — docs/voice.md §10:
/* Receive-side, per remote stream,
* gain (0..) , mute, and listener-chosen noise reduction on a specific user's stream. */
VC_API vc_result vc_set_remote_stream(vc_client* c, uint32_t user_id, uint32_t stream_id,
float gain, int muted, int noise_reduction);
@@ -436,24 +412,19 @@ VC_API vc_result vc_test_inject_capture(vc_client* c, uint32_t stream_id, const
/* Set the capture channel count for a local MIC stream (1 = mono, 2 = stereo interleaved).
* Must be called after vc_stream_start. Stores the value; it takes effect on the next engine
* (re)start. Does NOT restart the engine itself — the caller must follow up with
* vc_audio_restart() after AVAudioSession routing has settled (iOS) or after any platform
* audio-session reconfiguration. On iOS the Swift AVAudioSession routing layer enables stereo
* built-in mic capture by switching the built-in mic's data source to the .stereo polar
* pattern (setPreferredDataSource + setPreferredPolarPattern(.stereo) + setPreferredInput +
* setInputDataSource), calls this to record the desired channel count, and then calls
* vc_audio_restart() so the core reopens capture and playback against the new route.
* vc_audio_restart()
* VC_ERR_INVALID_ARG if stream_id is unknown or channels is not 1 or 2. */
VC_API vc_result vc_set_capture_channels(vc_client* c, uint32_t stream_id, uint32_t channels);
/* ── External PCM feed/tap ─────────────────────────────────────────────────── */
/* External PCM feed/tap */
/* External PCM feed — production-grade API for driving a local stream's encode pipeline
/* External PCM feed
* with caller-supplied PCM instead of (or in addition to) a hardware capture device. The
* stream must already be started (vc_stream_start). The core frames, encodes (Opus), seals
* (AEAD), and sends (UDP) the provided samples exactly as it would mic/loopback audio.
*
* pcm MUST be 48 kHz int16 — the core does NOT resample. (The whole audio engine runs at
* 48 kHz; see docs/voice.md §3. A bot is responsible for resampling its source to 48 kHz.)
* 48 kHz. A bot for example is responsible for resampling its source to 48 kHz.)
*
* samples_per_channel : samples per channel for THIS call. Any count is accepted — the core
* buffers and re-chunks to the channel's Opus frame size (the channel's frame_ms decides
@@ -465,12 +436,12 @@ VC_API vc_result vc_set_capture_channels(vc_client* c, uint32_t stream_id, uint3
* music / relay), soundboards, DAW integration. Works for any stream kind (MIC /
* SCREEN_AUDIO / AUX_DEVICE). Thread-safe; may be called from any thread.
*
* Replaces vc_test_inject_capture (deprecated alias, see above). */
*/
VC_API vc_result vc_stream_feed_pcm(vc_client* c, uint32_t stream_id,
const int16_t* pcm, size_t samples_per_channel,
uint32_t channels);
/* External PCM tap — receive decoded remote audio as int16 PCM per stream, before it is
/* External PCM tap receive decoded remote audio as int16 PCM per stream, before it is
* summed into the hardware mix. The callback fires on the audio playback thread once per
* decoded Opus frame (typically every 20 ms) for each active remote stream:
*
@@ -490,7 +461,7 @@ typedef void (*vc_pcm_sink_cb)(void* user, uint32_t user_id, uint32_t stream_id,
uint32_t channels, uint32_t sample_rate);
VC_API vc_result vc_set_pcm_sink(vc_client* c, vc_pcm_sink_cb cb, void* user);
/* ── External playback (iOS VPIO / echo cancellation) ───────────────────────────
/* External playback (iOS VPIO / echo cancellation)
* On iOS, real echo cancellation + noise suppression + AGC are provided ONLY by Apple's
* Voice-Processing I/O audio unit (VPIO), which the Swift AVAudioEngine layer owns. For VPIO
* to cancel echo, the remote-audio playback must go through the SAME VPIO unit as the mic
@@ -527,15 +498,15 @@ VC_API vc_result vc_set_mixed_output_sink(vc_client* c, vc_mixed_output_cb cb, v
* vc_audio_restart() to apply to a running engine. `enable` is a bool (0/1). */
VC_API vc_result vc_set_external_playback(vc_client* c, int enable);
/* ── Text ─────────────────────────────────────────────────────────────────── */
/* Text */
VC_API vc_result vc_send_text(vc_client* c, vc_text_scope scope, uint32_t target_id,
const char* utf8);
/* ── Device enumeration (for UI pickers) ──────────────────────────────────── */
/* Device enumeration (for UI pickers) */
VC_API vc_result vc_list_devices(vc_client* c, vc_device_kind kind, vc_device_list* out);
VC_API void vc_free_device_list(vc_device_list* list);
/* ── Channel / user / stream enumeration (mirrors vc_list_devices above) ──────────────────── */
/* Channel / user / stream enumeration (mirrors vc_list_devices above) */
VC_API vc_result vc_list_channels(vc_client* c, vc_channel_list* out);
VC_API void vc_free_channel_list(vc_channel_list* list);
@@ -548,7 +519,7 @@ VC_API vc_result vc_list_user_streams(vc_client* c, uint32_t user_id,
vc_stream_summary_list* out);
VC_API void vc_free_stream_summary_list(vc_stream_summary_list* list);
/* ── TOFU server-identity confirmation — see VC_EVENT_SERVER_IDENTITY/vc_tofu_status ──────── */
/* TOFU server-identity confirmation — see VC_EVENT_SERVER_IDENTITY/vc_tofu_status */
/* Accept or reject the pending server-identity check for the in-progress connect(). Must be
* called after a VC_EVENT_SERVER_IDENTITY event; the io_thread_ holds the connection open
* (ClientHello/auth deferred) until this is called, up to a generous internal timeout (after
@@ -567,7 +538,7 @@ VC_API vc_result vc_confirm_server_identity(vc_client* c, int accept /* bool */)
VC_API vc_result vc_get_server_identity_display(vc_client* c, char* out_buf, size_t buf_cap,
size_t* out_len);
/* ── Moderation & admin ───────────────────────────────────────────────────────
/* Moderation & admin
* All calls are async; the result arrives as VC_EVENT_GENERIC_RESULT (or
* VC_EVENT_ACCOUNT_LIST for vc_list_accounts). They require VC_STATE_CONNECTED and,
* on the server side, the appropriate permission. */
@@ -598,20 +569,11 @@ VC_API void vc_free_account_list(vc_account_list* list);
/* Pull the caller's own permissions (from the last AuthResult). */
VC_API vc_result vc_get_permissions(vc_client* c, vc_permissions* out);
/* AVAudioSession interruption hooks (iOS M6). Pause/resume miniaudio device I/O for
* AVAudioSession interruptions (phone call, Siri, etc.) and backgrounding. Call
* vc_audio_suspend() when an interruption begins; call vc_audio_resume() after the
* session is re-activated. No-op if the audio engine is not running. */
/* AudioSession interruption hooks*/
VC_API vc_result vc_audio_suspend(vc_client* c);
VC_API vc_result vc_audio_resume(vc_client* c);
/* Full audio engine restart (iOS M6). Unlike vc_audio_suspend/resume which only stop/start
* the existing miniaudio devices (leaving them bound to the route that was active when they
* were opened), vc_audio_restart() uninitializes and re-initializes the capture and playback
* devices so they pick up a new AVAudioSession route. Call this from the Swift layer AFTER
* reconfiguring AVAudioSession (setCategory, setPreferredInput, setPreferredPolarPattern, etc.)
* so the core's devices reopen against the new route.
* Safe to call when the engine is not running (it will just start it). */
/* Full audio engine restart Safe to call when the engine is not running (it will just start it). */
VC_API vc_result vc_audio_restart(vc_client* c);
#if defined(__cplusplus)