feat(M2): UDP voice/media plane -- SFU relay, Opus, AEAD, jitter buffer

Adds the full voice pipeline: 14-byte binary frame header, ChaCha20-Poly1305
AEAD keyed from the TLS exporter, libopus encode/decode with FEC/PLC/DTX,
an adaptive per-ssrc jitter buffer, a miniaudio capture/playback engine, an
APM passthrough stub, and the UdpBinding/StreamAnnounce signaling chain
wired through ConnSession/SessionRegistry into a new server-side SFU
(MediaRelay) that decrypts and re-encrypts frames per channel member.

Exit criterion verified: test_m2_voice — two headless clients relay 50
encrypted Opus frames through the server; ctest --preset m1-dev is 9/9
green. Also corrects protocol.md's UdpBinding diagram, which described the
UDP-side binding packet as AEAD-sealed when it is in fact a plaintext
bootstrap frame (separate from the TCP/TLS UdpBinding ack).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

tests/test_opus_codec.cpp

@@ -0,0 +1,149 @@
+/*
+ * test_opus_codec — Opus encode/decode round-trip, PLC, energy check.
+ *
+ * Requires VOICECAT_HAS_OPUS (m1-dev and m2-dev presets).
+ */
+#include <cmath>
+#include <cstdio>
+#include <cstring>
+#include <vector>
+
+#include "codec/opus_codec.h"
+
+namespace vc_codec = voicecat::codec;
+
+static int g_failures = 0;
+
+#define CHECK(cond) \
+    do { if (!(cond)) { \
+        std::printf("FAIL [%s:%d]: %s\n", __FILE__, __LINE__, #cond); \
+        ++g_failures; \
+    }} while (0)
+
+#ifndef VOICECAT_HAS_OPUS
+
+int main() {
+    std::printf("opus_codec: VOICECAT_HAS_OPUS not defined — skipped\n");
+    return 0;
+}
+
+#else
+
+static constexpr int kSampleRate  = 48000;
+static constexpr int kFrameMs     = 20;
+static constexpr int kFrameSamples = kSampleRate / 1000 * kFrameMs;  // 960
+
+// Generate one frame of 440 Hz sine wave at 16-bit mono, 48 kHz.
+static std::vector<int16_t> make_sine_frame(int samples, float freq = 440.0f) {
+    std::vector<int16_t> pcm(samples);
+    for (int i = 0; i < samples; ++i) {
+        float t = static_cast<float>(i) / kSampleRate;
+        pcm[i] = static_cast<int16_t>(std::sin(2.0f * 3.14159265f * freq * t) * 16000.0f);
+    }
+    return pcm;
+}
+
+// Compute RMS energy of a PCM buffer.
+static double rms(const int16_t* pcm, int n) {
+    double sum = 0.0;
+    for (int i = 0; i < n; ++i) sum += static_cast<double>(pcm[i]) * pcm[i];
+    return std::sqrt(sum / n);
+}
+
+static void test_encode_decode_round_trip() {
+    vc_codec::OpusParams p;
+    p.sample_rate = kSampleRate;
+    p.frame_ms    = kFrameMs;
+    p.fec         = true;
+
+    vc_codec::OpusEncoder enc;
+    vc_codec::OpusDecoder dec;
+    CHECK(enc.init(p));
+    CHECK(dec.init(p));
+
+    auto src = make_sine_frame(kFrameSamples);
+
+    uint8_t encoded[4000];
+    int enc_bytes = enc.encode(src.data(), kFrameSamples, encoded, sizeof(encoded));
+    CHECK(enc_bytes > 0);
+    CHECK(enc_bytes < 1000);  // Opus at 24 kbps/20 ms ≈ 60 bytes, well under 1000
+
+    std::vector<int16_t> decoded(kFrameSamples);
+    int dec_samples = dec.decode(encoded, enc_bytes, decoded.data(), kFrameSamples);
+    CHECK(dec_samples == kFrameSamples);
+
+    // Energy check: decoded RMS should be within 3 dB of original (Opus is lossy).
+    double rms_src = rms(src.data(), kFrameSamples);
+    double rms_dec = rms(decoded.data(), dec_samples);
+    CHECK(rms_src > 0.0);
+    CHECK(rms_dec > 0.0);
+    double ratio_db = 20.0 * std::log10(rms_dec / rms_src);
+    std::printf("  opus round-trip: enc_bytes=%d dec_samples=%d rms_ratio_db=%.1f\n",
+                enc_bytes, dec_samples, ratio_db);
+    CHECK(std::abs(ratio_db) < 3.0);
+
+    enc.destroy();
+    dec.destroy();
+}
+
+static void test_plc() {
+    vc_codec::OpusParams p;
+    p.sample_rate = kSampleRate;
+    p.frame_ms    = kFrameMs;
+
+    vc_codec::OpusDecoder dec;
+    CHECK(dec.init(p));
+
+    // First send a real packet so the decoder has state for PLC.
+    vc_codec::OpusEncoder enc;
+    CHECK(enc.init(p));
+    auto src = make_sine_frame(kFrameSamples);
+    uint8_t encoded[4000];
+    int enc_bytes = enc.encode(src.data(), kFrameSamples, encoded, sizeof(encoded));
+    CHECK(enc_bytes > 0);
+
+    std::vector<int16_t> real_out(kFrameSamples);
+    int r = dec.decode(encoded, enc_bytes, real_out.data(), kFrameSamples);
+    CHECK(r == kFrameSamples);
+
+    // Now simulate packet loss with PLC (nullptr, len=0).
+    std::vector<int16_t> plc_out(kFrameSamples, 0);
+    int plc_samples = dec.decode(nullptr, 0, plc_out.data(), kFrameSamples);
+    CHECK(plc_samples == kFrameSamples);
+
+    // PLC output should not be silent (Opus extrapolates from previous frame).
+    double plc_rms = rms(plc_out.data(), kFrameSamples);
+    std::printf("  plc_rms=%.1f (should be > 0)\n", plc_rms);
+    CHECK(plc_rms > 0.0);
+
+    enc.destroy();
+    dec.destroy();
+}
+
+static void test_frame_samples_helper() {
+    vc_codec::OpusParams p;
+    p.sample_rate = 48000;
+    p.frame_ms    = 20;
+    CHECK(vc_codec::opus_frame_samples(p) == 960);
+
+    p.frame_ms = 10;
+    CHECK(vc_codec::opus_frame_samples(p) == 480);
+
+    p.frame_ms = 40;
+    CHECK(vc_codec::opus_frame_samples(p) == 1920);
+}
+
+int main() {
+    test_frame_samples_helper();
+    test_encode_decode_round_trip();
+    test_plc();
+
+    if (g_failures == 0) {
+        std::printf("opus_codec: all tests passed\n");
+        return 0;
+    }
+    std::printf("opus_codec: %d test(s) FAILED\n", g_failures);
+    return 1;
+}
+
+#endif  // VOICECAT_HAS_OPUS