scaffold: M0 skeleton + agent onboarding (build, architecture, progress)
Turn the design into a buildable, dependency-free M0 skeleton plus the
onboarding layer so a new agent can pick up instantly.
Build system:
- CMake + CMakePresets (dev = no deps; server-release = vcpkg) + vcpkg.json
- Skeleton builds with just a C++20 compiler; deps stay off until needed
- .gitattributes (LF), .gitignore, .clang-format
Core (libvoicecat):
- core/include/voicecat.h: full C ABI (the client/server contract), stubbed
- core/proto/voicecat.proto: control-plane wire format, matches docs/protocol.md
- src/{net,crypto,codec,protocol,session,audio,core}: subsystem stubs that
return VC_ERR_NOT_IMPLEMENTED, each pointing to its design doc
- server/ (voicecat-server) and tools/vccli/ link the core
- tests/: CTest smoke test asserting the C ABI contract (behavior, not just build)
- clients/{apple,windows}: M4 placeholders
Onboarding for agents:
- CLAUDE.md: hub — build/test commands, architecture at a glance, doc map, rules
- AGENTS.md: working method (behavior-driven; clean compile is the floor not the goal)
- PROGRESS.md: living tracker — M0 done, M1 task checklist, "where we left off"
Verified: cmake --preset dev && cmake --build --preset dev && ctest --preset dev → green.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
223
core/include/voicecat.h
Normal file
223
core/include/voicecat.h
Normal file
@@ -0,0 +1,223 @@
|
||||
/*
|
||||
* 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;
|
||||
|
||||
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);
|
||||
|
||||
/* ── 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 */
|
||||
Reference in New Issue
Block a user