Talon
845f995826
- docs/building.md: explains what each CMake preset (dev, m1-dev, m2-dev, server-release) is actually for, and how to build voicecat-server + vccli for manual testing. Linked from CLAUDE.md's doc index. - core/include/voicecat.h, core/src/voicecat.cpp, core/src/protocol/protocol.h, server/src/main.cpp: doc-header comments still claimed M0-skeleton/stub behavior (VC_ERR_NOT_IMPLEMENTED everywhere, "prints what it would do", protobuf codegen "commented") that M1-M3 made real. Updated to describe current behavior, with the dev-preset stub fallback noted explicitly where it still applies.
257 lines
11 KiB
C
257 lines
11 KiB
C
/*
|
|
* 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.
|
|
*
|
|
* STATUS: real, behind VOICECAT_HAS_NET (the `m1-dev`/`server-release` presets — vcpkg deps
|
|
* on; see docs/building.md). As of M3, control plane, voice, multi-stream, device
|
|
* enumeration, VAD/PTT, and stereo playback all work for real via core/src/core/client.cpp.
|
|
* The no-deps `dev` preset still links a stub vc_client that returns VC_ERR_NOT_IMPLEMENTED
|
|
* for everything below `connect`, purely to keep that skeleton build green. webrtc AEC/NS/AGC
|
|
* remains an inert passthrough regardless of preset (no Windows/MSVC port upstream —
|
|
* docs/voice.md §8/§11, PROGRESS.md).
|
|
*/
|
|
#ifndef VOICECAT_H
|
|
#define VOICECAT_H
|
|
|
|
#include <stddef.h>
|
|
#include <stdint.h>
|
|
|
|
#if defined(__cplusplus)
|
|
extern "C" {
|
|
#endif
|
|
|
|
/* ── Export macro ─────────────────────────────────────────────────────────── */
|
|
#if defined(VOICECAT_STATIC)
|
|
#define VC_API
|
|
#elif defined(_WIN32)
|
|
#if defined(VOICECAT_BUILDING)
|
|
#define VC_API __declspec(dllexport)
|
|
#else
|
|
#define VC_API __declspec(dllimport)
|
|
#endif
|
|
#else
|
|
#if defined(VOICECAT_BUILDING)
|
|
#define VC_API __attribute__((visibility("default")))
|
|
#else
|
|
#define VC_API
|
|
#endif
|
|
#endif
|
|
|
|
/* ── Version ──────────────────────────────────────────────────────────────── */
|
|
#define VOICECAT_VERSION_MAJOR 0
|
|
#define VOICECAT_VERSION_MINOR 0
|
|
#define VOICECAT_VERSION_PATCH 1
|
|
|
|
/* The control-protocol version this build speaks (docs/protocol.md §4). */
|
|
#define VOICECAT_PROTOCOL_VERSION 1
|
|
|
|
/* ── Result codes ─────────────────────────────────────────────────────────── */
|
|
typedef enum vc_result {
|
|
VC_OK = 0,
|
|
VC_ERR_NOT_IMPLEMENTED = 1, /* skeleton stub */
|
|
VC_ERR_INVALID_ARG = 2,
|
|
VC_ERR_NOT_CONNECTED = 3,
|
|
VC_ERR_ALREADY = 4,
|
|
VC_ERR_AUTH_FAILED = 5,
|
|
VC_ERR_PERMISSION_DENIED = 6,
|
|
VC_ERR_TIMEOUT = 7,
|
|
VC_ERR_IO = 8,
|
|
VC_ERR_PROTOCOL = 9,
|
|
VC_ERR_CRYPTO = 10,
|
|
VC_ERR_AUDIO = 11,
|
|
VC_ERR_INTERNAL = 12,
|
|
} vc_result;
|
|
|
|
typedef enum vc_log_level {
|
|
VC_LOG_TRACE = 0,
|
|
VC_LOG_DEBUG = 1,
|
|
VC_LOG_INFO = 2,
|
|
VC_LOG_WARN = 3,
|
|
VC_LOG_ERROR = 4,
|
|
VC_LOG_OFF = 5,
|
|
} vc_log_level;
|
|
|
|
typedef enum vc_connection_state {
|
|
VC_STATE_DISCONNECTED = 0,
|
|
VC_STATE_CONNECTING = 1,
|
|
VC_STATE_TLS_HANDSHAKE = 2,
|
|
VC_STATE_AUTHENTICATING = 3,
|
|
VC_STATE_CONNECTED = 4,
|
|
} vc_connection_state;
|
|
|
|
typedef enum vc_text_scope {
|
|
VC_TEXT_CHANNEL = 0,
|
|
VC_TEXT_PRIVATE = 1,
|
|
VC_TEXT_SERVER = 2,
|
|
} vc_text_scope;
|
|
|
|
typedef enum vc_device_kind {
|
|
VC_DEVICE_INPUT = 0,
|
|
VC_DEVICE_OUTPUT = 1,
|
|
} 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_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,
|
|
} 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_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 */
|
|
VC_EVENT_USER_UPDATED = 5, /* user_id */
|
|
VC_EVENT_TEXT_MESSAGE = 6, /* text_scope, user_id (sender), channel_id, text */
|
|
VC_EVENT_STREAM_STARTED = 7, /* user_id, stream_id */
|
|
VC_EVENT_STREAM_STOPPED = 8, /* user_id, stream_id */
|
|
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 */
|
|
} vc_event_type;
|
|
|
|
/* ── Structs ──────────────────────────────────────────────────────────────── */
|
|
|
|
/*
|
|
* An event delivered to vc_callbacks.on_event. Pointer fields are owned by the core and
|
|
* valid ONLY for the duration of the callback — copy what you need. Which fields are
|
|
* meaningful depends on `type` (see vc_event_type comments above).
|
|
*/
|
|
typedef struct vc_event {
|
|
vc_event_type type;
|
|
vc_connection_state connection_state;
|
|
int32_t result; /* vc_result */
|
|
uint32_t user_id;
|
|
uint32_t channel_id;
|
|
uint32_t stream_id;
|
|
vc_text_scope text_scope;
|
|
uint32_t u32a; /* generic small payload, meaning per event type */
|
|
const char* text;
|
|
uint64_t timestamp_unix_ms;
|
|
} vc_event;
|
|
|
|
typedef struct vc_callbacks {
|
|
/* State changes, messages, presence. Called on the core's event thread. */
|
|
void (*on_event)(void* user, const vc_event* ev);
|
|
/* Throttled level meter (RMS 0..1) for a local or remote stream; may be NULL. */
|
|
void (*on_level)(void* user, uint32_t stream_id, float rms);
|
|
void* user;
|
|
} vc_callbacks;
|
|
|
|
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;
|
|
} vc_config;
|
|
|
|
typedef struct vc_stream_desc {
|
|
vc_stream_kind kind;
|
|
const char* device_id; /* NULL = default device for this kind */
|
|
const char* label; /* human label, e.g. "Microphone" */
|
|
} 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
|
|
* 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 */
|
|
uint32_t mode; /* 0 = mono, 1 = stereo */
|
|
uint32_t sample_rate;
|
|
uint32_t bitrate_bps;
|
|
uint32_t frame_ms;
|
|
uint32_t application; /* 0 = VOIP, 1 = AUDIO, 2 = LOWDELAY */
|
|
int fec; /* bool */
|
|
uint32_t expected_packet_loss; /* % 0..100 */
|
|
int dtx; /* bool */
|
|
uint32_t complexity; /* 0..10 */
|
|
} vc_audio_config;
|
|
|
|
typedef struct vc_device {
|
|
const char* id;
|
|
const char* name;
|
|
int is_default; /* bool */
|
|
} vc_device;
|
|
|
|
typedef struct vc_device_list {
|
|
vc_device* items;
|
|
size_t count;
|
|
} vc_device_list;
|
|
|
|
/* Opaque client handle. */
|
|
typedef struct vc_client vc_client;
|
|
|
|
/* ── 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) ──────────────────────── */
|
|
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 ─────────────────────────────────────────────────────────────── */
|
|
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);
|
|
|
|
/* ── 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);
|
|
VC_API vc_result vc_set_input_device(vc_client* c, uint32_t stream_id,
|
|
const char* device_id);
|
|
|
|
/* Send-side: input gate mode + PTT key state, and self mute/deafen. */
|
|
VC_API vc_result vc_set_input_mode(vc_client* c, vc_input_mode mode);
|
|
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);
|
|
|
|
/* Receive-side, per remote stream, all LOCAL (no protocol traffic) — docs/voice.md §10:
|
|
* 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);
|
|
|
|
/* Effective Opus config in use for (user_id, stream_id) — your own stream or a peer's.
|
|
* VC_ERR_INVALID_ARG if the user/stream isn't known. */
|
|
VC_API vc_result vc_get_stream_audio_config(vc_client* c, uint32_t user_id, uint32_t stream_id,
|
|
vc_audio_config* out);
|
|
|
|
/* TEST-ONLY — not for production use. Bypasses the real capture device, injecting raw PCM
|
|
* directly into the named local stream's encode pipeline (see AudioEngine::inject_capture).
|
|
* Exists so automated tests can drive the real vc_client/ABI path end-to-end without a
|
|
* microphone. `stream_id` is the id returned by vc_stream_start. */
|
|
VC_API vc_result vc_test_inject_capture(vc_client* c, uint32_t stream_id, const int16_t* pcm,
|
|
size_t samples);
|
|
|
|
/* ── 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) ──────────────────────────────────── */
|
|
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);
|
|
|
|
#if defined(__cplusplus)
|
|
} /* extern "C" */
|
|
#endif
|
|
|
|
#endif /* VOICECAT_H */
|