diff --git a/core/include/voicecat.h b/core/include/voicecat.h index b9f4d69..7be74f2 100644 --- a/core/include/voicecat.h +++ b/core/include/voicecat.h @@ -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) diff --git a/core/proto/voicecat.proto b/core/proto/voicecat.proto index 27b97fc..d525ec3 100644 --- a/core/proto/voicecat.proto +++ b/core/proto/voicecat.proto @@ -1,19 +1,19 @@ // VoiceCat control-plane wire format. SOURCE OF TRUTH for the protocol. -// Spec: docs/protocol.md. Each TCP/TLS frame is [u32 length][encoded Envelope]. -// Media frames (voice) are NOT here — they use the fixed binary header in docs/voice.md §2. +// Each TCP/TLS frame is [u32 length][encoded Envelope]. +// Media frames (voice) are NOT here — they use a fixed binary header // -// Extensibility rules (docs/protocol.md §8): never reuse/renumber tags; new oneof arms and +// Extensibility rules: never reuse/renumber tags; new oneof arms and // fields are additive; gate new features behind capability strings in ClientHello/ServerHello. syntax = "proto3"; package voicecat.v1; -// ── Envelope ────────────────────────────────────────────────────────────────── +// Envelope message Envelope { // Nonzero on a request; echoed in the matching response for correlation. 0 = unsolicited. uint64 request_id = 1; oneof body { - // Session / handshake (tags 10–19) + // Session / handshake (tags 10-19) ClientHello client_hello = 10; ServerHello server_hello = 11; AuthRequest auth_request = 12; @@ -22,13 +22,13 @@ message Envelope { Ping ping = 15; Pong pong = 16; - // State sync (20–29) + // State sync (20-29) ServerStateSnapshot server_state = 20; ChannelEvent channel_event = 21; UserEvent user_event = 22; SubscribeRequest subscribe = 23; - // Channel operations (30–39) + // Channel operations (30-39) JoinChannelRequest join_channel = 30; JoinChannelResult join_channel_result = 31; LeaveChannelRequest leave_channel = 32; @@ -38,7 +38,7 @@ message Envelope { MoveUserRequest move_user = 36; GenericResult generic_result = 37; - // Voice signaling — media is on UDP (40–49) + // Voice signaling, media is on UDP (40-49) StreamAnnounce stream_announce = 40; StreamAnnounceResult stream_announce_result = 41; StreamStop stream_stop = 42; @@ -48,18 +48,18 @@ message Envelope { UnsubscribeVoiceRequest unsubscribe_voice = 46; VoiceSubscriptionResult voice_subscription_result = 47; - // Text (50–59) + // Text (50-59) TextMessage text_message = 50; TextMessageAck text_message_ack = 51; TypingIndicator typing = 52; - // Moderation / permissions (60–69) + // Moderation / permissions (60-69) KickRequest kick = 60; BanRequest ban = 61; SetPermissionRequest set_permission = 62; ServerMuteRequest server_mute = 63; - // Admin account management — privileged; accounts are admin-provisioned (70–79) + // Admin account management. privileged; accounts are admin-provisioned (70-79) CreateAccountRequest create_account = 70; ResetPasswordRequest reset_password = 71; DeleteAccountRequest delete_account = 72; @@ -71,18 +71,18 @@ message Envelope { } } -// ── Enums ────────────────────────────────────────────────────────────────────── +// Enums enum ChannelType { CHANNEL_PERMANENT = 0; CHANNEL_TEMPORARY = 1; } enum ChannelMode { MODE_MONO = 0; MODE_STEREO = 1; } enum StreamKind { STREAM_MIC = 0; STREAM_SCREEN_AUDIO = 1; STREAM_AUX_DEVICE = 2; } enum TextScope { TEXT_CHANNEL = 0; TEXT_PRIVATE = 1; TEXT_SERVER = 2; } enum OpusApplication { OPUS_VOIP = 0; OPUS_AUDIO = 1; OPUS_LOWDELAY = 2; } -// ── Common types ──────────────────────────────────────────────────────────────── +// Common types message AudioConfig { uint32 codec = 1; // 0 = OPUS ChannelMode mode = 2; - uint32 sample_rate = 3; // 48000 recommended + uint32 sample_rate = 3; uint32 bitrate_bps = 4; uint32 frame_ms = 5; // 2.5/5/10/20/40/60 OpusApplication application = 6; @@ -90,7 +90,7 @@ message AudioConfig { uint32 expected_packet_loss = 8; // % bool dtx = 9; uint32 complexity = 10; // 0..10 - bool dred = 11; // Deep REDundancy (Opus 1.6); off by default + bool dred = 11; // Deep REDundancy (Opus 1.6) } message StreamInfo { @@ -127,7 +127,6 @@ message User { } message Permissions { - // Minimal v1 flag set; the moderation milestone expands this. Server-side is authoritative. bool can_create_temp_channel = 1; bool can_kick = 2; bool can_ban = 3; @@ -136,7 +135,7 @@ message Permissions { bool is_admin = 6; } -// ── Session / handshake ───────────────────────────────────────────────────────── +// Session / handshake message ClientHello { uint32 proto_version = 1; repeated string features = 2; // "opus", "fec", "screen-audio", ... @@ -171,14 +170,14 @@ message AuthResult { uint64 session_id = 3; User self = 4; Permissions permissions = 5; - bytes udp_token = 6; // bind the UDP 5-tuple with this (security.md §3) + bytes udp_token = 6; // bind the UDP 5-tuple with this } message Disconnect { uint32 code = 1; string reason = 2; } message Ping { uint64 nonce = 1; } message Pong { uint64 nonce = 1; } -// ── State sync ────────────────────────────────────────────────────────────────── +// State sync message ServerStateSnapshot { repeated Channel channels = 1; repeated User users = 2; @@ -198,7 +197,7 @@ message UserEvent { } message SubscribeRequest { repeated uint32 channel_ids = 1; bool presence = 2; } -// ── Channel operations ────────────────────────────────────────────────────────── +// Channel operations message JoinChannelRequest { uint32 channel_id = 1; string password = 2; } message JoinChannelResult { bool ok = 1; string error = 2; @@ -213,22 +212,19 @@ message DeleteChannelRequest { uint32 channel_id = 1; } message MoveUserRequest { uint32 user_id = 1; uint32 channel_id = 2; } message GenericResult { bool ok = 1; uint32 code = 2; string message = 3; } -// ── Voice signaling ───────────────────────────────────────────────────────────── +// Voice signaling message StreamAnnounce { StreamKind kind = 1; AudioConfig requested_audio = 2; string label = 3; } message StreamAnnounceResult{ bool ok = 1; string error = 2; uint32 stream_id = 3; uint32 ssrc = 4; AudioConfig effective_audio = 5; } message StreamStop { uint32 stream_id = 1; } message StreamStateUpdate { uint32 user_id = 1; uint32 stream_id = 2; bool muted = 3; bool talking = 4; } message UdpBinding { bytes udp_token = 1; bool ack = 2; } -// Voice-plane subscription. Joining voice = you can hear and send voice in your channel; -// leaving voice = the server stops relaying voice frames to you and you stop receiving. -// Text chat is unaffected. The server toggles a per-session flag checked by the SFU relay's -// recipient filter (docs/protocol.md §5). Result arrives as voice_subscription_result. + message SubscribeVoiceRequest {} message UnsubscribeVoiceRequest {} message VoiceSubscriptionResult { bool ok = 1; string error = 2; bool subscribed = 3; } -// ── Text (ephemeral — server does not persist history, docs/protocol.md §5) ────── +// Text message TextMessage { TextScope scope = 1; uint32 target_id = 2; // channel_id or user_id per scope @@ -240,13 +236,13 @@ message TextMessage { message TextMessageAck { string client_msg_id = 1; bool ok = 2; } message TypingIndicator { TextScope scope = 1; uint32 target_id = 2; uint32 user_id = 3; } -// ── Moderation / permissions ───────────────────────────────────────────────────── +// Moderation / permissions message KickRequest { uint32 user_id = 1; string reason = 2; } message BanRequest { uint32 user_id = 1; string reason = 2; uint64 expires_unix_ms = 3; } message SetPermissionRequest { uint32 user_id = 1; Permissions permissions = 2; } message ServerMuteRequest { uint32 user_id = 1; bool muted = 2; bool deafened = 3; } -// ── Admin account management (privileged) ──────────────────────────────────────── +// Admin account management message CreateAccountRequest { string username = 1; string password = 2; } message ResetPasswordRequest { string username = 1; string new_password = 2; } message DeleteAccountRequest { string username = 1; } @@ -254,5 +250,5 @@ message ListAccountsRequest {} message AccountEntry { string username = 1; bool is_admin = 2; uint64 created_at_unix_ms = 3; uint64 last_login_unix_ms = 4; } message ListAccountsResult { repeated AccountEntry accounts = 1; } -// ── Extension escape hatch ─────────────────────────────────────────────────────── +// Extension escape hatch message Extension { string ns = 1; bytes payload = 2; }