92 lines
7.0 KiB
Markdown
92 lines
7.0 KiB
Markdown
|
# Tech Stack & Dependencies
|
||
|
|
|
||
|
|
Concrete library choices with versions and rationale. Everything in the **core** is C++
|
||
|
|
(C++20). UIs are Swift and C#. Build is CMake + vcpkg.
|
||
|
|
|
||
|
|
## 1. Core library (`libvoicecat`, C++20)
|
||
|
|
|
||
|
|
| Concern | Choice | Version (as of 2026-06) | Why / notes |
|
||
|
|
|---------|--------|-------------------------|-------------|
|
||
|
|
| Sockets, timers, async | **Standalone Asio** | 1.30.x | Header-only, no Boost dependency, cross-platform TCP+UDP+timers, one reactor for client and server. (Boost.Asio is interchangeable if we already pull Boost.) |
|
||
|
|
| TLS 1.3 (control) | **mbedTLS 3.6 LTS** | 3.6.x (LTS ≥ Mar 2027) | **Apache-2.0** (permissive — clean for eventual closed-source distribution). TLS 1.3 client+server, plus `mbedtls_ssl_export_keying_material()` to seed the media AEAD. **Static-links cleanly → single self-host binary.** OpenSSL 3.x (Apache-2.0) is an interchangeable alternative. No DTLS/wolfSSL (GPL) — see [security.md](security.md) §2. |
|
||
|
|
| Crypto primitives + password hashing + media AEAD | **libsodium** | 1.0.20 | **ISC.** Argon2id (`crypto_pwhash`), ChaCha20-Poly1305 (per-frame media encryption), Ed25519 server identity, X25519, CSPRNG. Audited, hard to misuse. |
|
||
|
|
| Audio codec | **libopus** | **1.6** (2025-12) | Per-channel mono/stereo, bitrate, frame size; in-band FEC, DTX, PLC, and optional **DRED** deep redundancy; Opus HD/96 kHz available. The whole reason the design is codec-flexible. |
|
||
|
|
| Audio capture/playback | **miniaudio** | 0.11.x | Single-header, public-domain, backends for **WASAPI / CoreAudio / ALSA / PulseAudio**. One real-time abstraction across all desktop targets; keeps the RT path identical. |
|
||
|
|
| Audio DSP — AEC/NS/AGC/VAD | **webrtc-audio-processing** (APM) | 1.x (standalone APM) | **BSD-3.** The primary DSP engine: high-quality acoustic echo cancellation, noise suppression, AGC, and VAD in one tuned module. Used **send-side** (clean the mic) and **receive-side per user** (listener-chosen NS on a specific stream — voice.md §10). AEC is in from the start, not deferred. |
|
||
|
|
| Resampling + jitter ref | **speexdsp** | 1.2.x | BSD. Resampler for non-48 kHz devices; lightweight jitter-buffer reference. (No longer the NS/AGC/VAD source — APM replaces it.) |
|
||
|
|
| Control serialization | **Protocol Buffers** (protobuf-lite) | 5.x (proto3) | Codegen for C++/C#/Swift; additive, forward/backward compatible; `oneof` envelopes. `nanopb` is a fallback if footprint matters. |
|
||
|
|
| Server persistence | **SQLite** | 3.4x | Accounts, channels, bans, config. Zero-admin, single file, ships everywhere. |
|
||
|
|
| Logging | **spdlog** | 1.14.x | Fast, async-capable; off the RT path. |
|
||
|
|
|
||
|
|
Resampling note: Opus runs internally at 48 kHz; miniaudio can deliver 48 kHz directly, so
|
||
|
|
explicit resampling (speexdsp/libsamplerate) is only needed when a device can't do 48 kHz.
|
||
|
|
|
||
|
|
## 2. Clients
|
||
|
|
|
||
|
|
### macOS / iOS — Swift
|
||
|
|
|
||
|
|
| Concern | Choice | Notes |
|
||
|
|
|---------|--------|-------|
|
||
|
|
| Language | **Swift 5.9+** | Direct **Swift↔C++ interop** available, but we bind through the C ABI for parity with Windows. |
|
||
|
|
| UI | **SwiftUI** | Single UI codebase for macOS + iOS where practical; AppKit/UIKit shims as needed. |
|
||
|
|
| Audio session (iOS) | **AVAudioSession** | App owns category `.playAndRecord` + `.voiceChat` mode, mic permission, interruption/route-change handling; calls `vc_audio_suspend/resume` on the core. macOS uses CoreAudio via the core directly. |
|
||
|
|
| Packaging | Swift Package + Xcode project | Core shipped as an XCFramework (device + simulator + macOS slices). |
|
||
|
|
| Future | CallKit / PushKit | For background VoIP + incoming-call UX on iOS. Post-v1. |
|
||
|
|
|
||
|
|
### Windows — C#
|
||
|
|
|
||
|
|
| Concern | Choice | Notes |
|
||
|
|
|---------|--------|-------|
|
||
|
|
| Runtime | **.NET 8+** | LTS. |
|
||
|
|
| Interop | **`LibraryImport`** (source-gen P/Invoke) over the C ABI | Marshal the event callback as a function pointer (`[UnmanagedCallersOnly]`) to avoid delegate-lifetime bugs; keep the interface "chunky" not "chatty" to minimize managed↔native transitions. |
|
||
|
|
| UI | **WinUI 3** (most native) or **Avalonia** | WinUI for a first-class Windows look; Avalonia if we later want one C# UI across desktop OSes. |
|
||
|
|
| Audio | handled by the core (miniaudio/WASAPI) | C# only drives device selection + meters. |
|
||
|
|
|
||
|
|
## 3. Server (`voicecat-server`)
|
||
|
|
|
||
|
|
- Pure C++ linking the core; **no GUI**. Runs on **Linux** (primary), **macOS**, **Windows**.
|
||
|
|
- Config via a `server.toml` (`allow_guests`, ports, channel defaults, Opus policy, TLS cert
|
||
|
|
paths or auto-self-signed + Ed25519 identity, Argon2id cost params, rate limits).
|
||
|
|
- SQLite for state. Single process for v1; interfaces drawn so a multi-node build is
|
||
|
|
*possible* later but explicitly out of scope.
|
||
|
|
- Packaging: static-ish binary per OS; systemd unit + Docker image for Linux.
|
||
|
|
|
||
|
|
## 4. Build & tooling
|
||
|
|
|
||
|
|
| Tool | Use |
|
||
|
|
|------|-----|
|
||
|
|
| **CMake** (3.25+) | One build graph for core + server + test CLI; UI projects consume the built core. |
|
||
|
|
| **vcpkg** (manifest mode) | Pin C/C++ deps (opus, libsodium, mbedtls, protobuf, sqlite3, spdlog, webrtc-audio-processing, speexdsp, asio, miniaudio). Reproducible across OSes. |
|
||
|
|
| **protoc** | Generate C++/C#/Swift from `core/proto/*.proto` (single source of truth). |
|
||
|
|
| **clang-format / clang-tidy** | Style + static analysis on the core. |
|
||
|
|
| **CTest + a fuzz target** | Unit/integration tests; fuzz the frame parser and protobuf boundary (security-sensitive). |
|
||
|
|
| **GitHub Actions** (or similar) | Matrix CI: Linux/macOS/Windows core+server; Xcode build for Apple; `dotnet` build for Windows. |
|
||
|
|
|
||
|
|
## 5. Licensing — permissive only (hard rule)
|
||
|
|
|
||
|
|
The code will eventually be distributed in **closed-source** form, so **no GPL/LGPL
|
||
|
|
dependencies are permitted.** Every dependency below is BSD / MIT / ISC / Apache-2.0 /
|
||
|
|
public-domain:
|
||
|
|
|
||
|
|
- **mbedTLS** — Apache-2.0 ✅ · **libsodium** — ISC ✅ · **libopus** — BSD ✅ ·
|
||
|
|
**miniaudio** — public domain / MIT-0 ✅ · **speexdsp** — BSD ✅ · **protobuf** — BSD ✅ ·
|
||
|
|
**SQLite** — public domain ✅ · **Asio** (standalone) — Boost ✅ · **spdlog** — MIT ✅ ·
|
||
|
|
**webrtc-audio-processing** — BSD-3 ✅ (heavier build, but core to the DSP path).
|
||
|
|
- **Explicitly rejected:** **wolfSSL** (GPLv2/commercial) and any DTLS stack that would drag
|
||
|
|
in copyleft. The exported-keys + AEAD media design (security.md §2) removes the need for
|
||
|
|
one entirely.
|
||
|
|
- CI runs a license scanner over the resolved vcpkg graph and **fails the build on any
|
||
|
|
GPL/LGPL transitive dependency**, so this rule can't silently regress.
|
||
|
|
|
||
|
|
## 6. Why not the obvious alternatives
|
||
|
|
|
||
|
|
- **WebRTC** — explicitly rejected: ICE/SDP/TURN complexity, huge dependency, opaque. We
|
||
|
|
want plain TCP+UDP we fully control.
|
||
|
|
- **QUIC** — capable (reliable streams + datagrams + TLS 1.3 in one), but heavier and drifts
|
||
|
|
toward the complexity we're avoiding. Revisit only if NAT traversal/multiplexing pain
|
||
|
|
appears.
|
||
|
|
- **gRPC** for control — pulls HTTP/2 and a lot of surface for what is a simple framed
|
||
|
|
message stream over TLS. Plain protobuf-over-framed-TLS is enough.
|
||
|
|
- **A Rust core** — viable and memory-safe, but the user prefers C++ and the Swift/C#
|
||
|
|
binding story is marginally simpler from C++ (Swift can even consume C++ directly).
|