voice-cat/core/include/voicecat.h

/*
 * 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: M0 skeleton. Implementations live in core/src and currently return
 * VC_ERR_NOT_IMPLEMENTED. The shapes below are the contract to build against.
 */
#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 */