fix(build): declare VARIANT in local script half (was remote-only)

The VARIANT variable was set inside the REMOTE_SCRIPT heredoc for
naming artifacts during the cargo tauri build, but never declared
in the local half of the script where it's used to rename downloaded
files. Under `set -u` strict mode this aborted the local downloads
with "unbound variable: VARIANT" after a successful remote build.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.agents/skills/caveman/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: caveman
+description: >
+  Ultra-compressed communication mode. Slash token usage ~75% by speaking like caveman
+  while keeping full technical accuracy. Use when user says "caveman mode", "talk like caveman",
+  "use caveman", "less tokens", "be brief", or invokes /caveman. Also auto-triggers
+  when token efficiency is requested.
+---
+
+# Caveman Mode
+
+## Core Rule
+
+Respond like smart caveman. Cut articles, filler, pleasantries. Keep all technical substance.
+
+## Grammar
+
+- Drop articles (a, an, the)
+- Drop filler (just, really, basically, actually, simply)
+- Drop pleasantries (sure, certainly, of course, happy to)
+- Short synonyms (big not extensive, fix not "implement a solution for")
+- No hedging (skip "it might be worth considering")
+- Fragments fine. No need full sentence
+- Technical terms stay exact. "Polymorphism" stays "polymorphism"
+- Code blocks unchanged. Caveman speak around code, not in code
+- Error messages quoted exact. Caveman only for explanation
+
+## Pattern
+
+```
+[thing] [action] [reason]. [next step].
+```
+
+Not:
+> Sure! I'd be happy to help you with that. The issue you're experiencing is likely caused by...
+
+Yes:
+> Bug in auth middleware. Token expiry check use `<` not `<=`. Fix:
+
+## Examples
+
+**User:** Why is my React component re-rendering?
+
+**Normal (69 tokens):** "The reason your React component is re-rendering is likely because you're creating a new object reference on each render cycle. When you pass an inline object as a prop, React's shallow comparison sees it as a different object every time, which triggers a re-render. I'd recommend using useMemo to memoize the object."
+
+**Caveman (19 tokens):** "New object ref each render. Inline object prop = new ref = re-render. Wrap in `useMemo`."
+
+---
+
+**User:** How do I set up a PostgreSQL connection pool?
+
+**Caveman:**
+```
+Use `pg` pool:
+```
+```js
+const pool = new Pool({
+  max: 20,
+  idleTimeoutMillis: 30000,
+  connectionTimeoutMillis: 2000,
+})
+```
+```
+max = concurrent connections. Keep under DB limit. idleTimeout kill stale conn.
+```
+
+## Boundaries
+
+- Code: write normal. Caveman English only
+- Git commits: normal
+- PR descriptions: normal
+- User say "stop caveman" or "normal mode": revert immediately

.cargo/config.toml

@@ -0,0 +1,5 @@
+[target.aarch64-linux-android]
+linker = "aarch64-linux-android26-clang"
+
+[target.armv7-linux-androideabi]
+linker = "armv7a-linux-androideabi26-clang"

.gitea/workflows/build.yml

@@ -2,187 +2,57 @@ name: Build Release Binaries
 
 on:
   push:
+    branches:
+      - main
+      - 'feat/*'
     tags:
       - 'v*'
+    paths-ignore:
+      - '.gitea/**'
   workflow_dispatch:
-    inputs:
-      targets:
-        description: 'Targets to build (comma-separated: amd64,arm64,armv7,mac-arm64)'
-        required: false
-        default: 'amd64'
 
 env:
   CARGO_TERM_COLOR: always
 
 jobs:
-  # Always builds on push tags. On manual dispatch, reads inputs.
   build-amd64:
-    if: >-
-      github.event_name == 'push' ||
-      contains(github.event.inputs.targets, 'amd64')
     runs-on: ubuntu-latest
     container:
-      image: rust:1-bookworm
+      image: catthehacker/ubuntu:act-latest
     steps:
       - uses: actions/checkout@v4
 
-      - name: Install dependencies
-        run: apt-get update && apt-get install -y cmake pkg-config libasound2-dev
-
-      - name: Cache cargo
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.cargo/registry
-            ~/.cargo/git
-            target
-          key: cargo-amd64-${{ hashFiles('Cargo.lock') }}
-          restore-keys: cargo-amd64-
-
-      - name: Build headless binaries
-        run: cargo build --release --bin wzp-relay --bin wzp-client --bin wzp-bench --bin wzp-web
-
-      - name: Build audio client
+      - name: Init submodules
         run: |
-          cargo build --release --bin wzp-client --features audio
-          cp target/release/wzp-client target/release/wzp-client-audio
-          cargo build --release --bin wzp-client
+          git config --global url."https://git.manko.yoga/".insteadOf "ssh://git@git.manko.yoga:222/"
+          git submodule update --init --recursive
+
+      - name: Install Rust + dependencies
+        run: |
+          curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
+          source "$HOME/.cargo/env"
+          apt-get update && apt-get install -y cmake pkg-config libasound2-dev ninja-build
+          rustc --version
+
+      - name: Build relay + tools
+        run: |
+          source "$HOME/.cargo/env"
+          cargo build --release --bin wzp-relay --bin wzp-client --bin wzp-bench --bin wzp-web
 
       - name: Run tests
-        run: cargo test --workspace --lib
-
-      - name: Package
         run: |
-          mkdir -p dist/wzp-linux-amd64
-          cp target/release/wzp-relay dist/wzp-linux-amd64/
-          cp target/release/wzp-client dist/wzp-linux-amd64/
-          cp target/release/wzp-client-audio dist/wzp-linux-amd64/
-          cp target/release/wzp-web dist/wzp-linux-amd64/
-          cp target/release/wzp-bench dist/wzp-linux-amd64/
-          cp -r crates/wzp-web/static dist/wzp-linux-amd64/
-          cd dist && tar czf wzp-linux-amd64.tar.gz wzp-linux-amd64/
+          source "$HOME/.cargo/env"
+          cargo test --workspace --lib
 
-      - name: Upload artifact
-        uses: actions/upload-artifact@v4
-        with:
-          name: wzp-linux-amd64
-          path: dist/wzp-linux-amd64.tar.gz
-
-  build-arm64:
-    if: >-
-      github.event_name == 'push' ||
-      contains(github.event.inputs.targets, 'arm64')
-    runs-on: ubuntu-latest
-    container:
-      image: rust:1-bookworm
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Install cross-compilation tools
-        run: |
-          dpkg --add-architecture arm64
-          apt-get update
-          apt-get install -y cmake pkg-config gcc-aarch64-linux-gnu libc6-dev-arm64-cross
-          rustup target add aarch64-unknown-linux-gnu
-
-      - name: Cache cargo
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.cargo/registry
-            ~/.cargo/git
-            target
-          key: cargo-arm64-${{ hashFiles('Cargo.lock') }}
-          restore-keys: cargo-arm64-
-
-      - name: Build
+      - name: Upload to rustypaste
         env:
-          CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER: aarch64-linux-gnu-gcc
-          CC_aarch64_unknown_linux_gnu: aarch64-linux-gnu-gcc
+          PASTE_AUTH: ${{ secrets.PASTE_AUTH }}
+          PASTE_URL: ${{ secrets.PASTE_URL }}
         run: |
-          cargo build --release --target aarch64-unknown-linux-gnu \
-            --bin wzp-relay --bin wzp-client --bin wzp-bench --bin wzp-web
-
-      - name: Package
-        run: |
-          mkdir -p dist/wzp-linux-arm64
-          cp target/aarch64-unknown-linux-gnu/release/wzp-relay dist/wzp-linux-arm64/
-          cp target/aarch64-unknown-linux-gnu/release/wzp-client dist/wzp-linux-arm64/
-          cp target/aarch64-unknown-linux-gnu/release/wzp-web dist/wzp-linux-arm64/
-          cp target/aarch64-unknown-linux-gnu/release/wzp-bench dist/wzp-linux-arm64/
-          cp -r crates/wzp-web/static dist/wzp-linux-arm64/
-          cd dist && tar czf wzp-linux-arm64.tar.gz wzp-linux-arm64/
-
-      - name: Upload artifact
-        uses: actions/upload-artifact@v4
-        with:
-          name: wzp-linux-arm64
-          path: dist/wzp-linux-arm64.tar.gz
-
-  build-armv7:
-    if: >-
-      github.event_name == 'push' ||
-      contains(github.event.inputs.targets, 'armv7')
-    runs-on: ubuntu-latest
-    container:
-      image: rust:1-bookworm
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Install cross-compilation tools
-        run: |
-          dpkg --add-architecture armhf
-          apt-get update
-          apt-get install -y cmake pkg-config gcc-arm-linux-gnueabihf libc6-dev-armhf-cross
-          rustup target add armv7-unknown-linux-gnueabihf
-
-      - name: Cache cargo
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.cargo/registry
-            ~/.cargo/git
-            target
-          key: cargo-armv7-${{ hashFiles('Cargo.lock') }}
-          restore-keys: cargo-armv7-
-
-      - name: Build
-        env:
-          CARGO_TARGET_ARMV7_UNKNOWN_LINUX_GNUEABIHF_LINKER: arm-linux-gnueabihf-gcc
-          CC_armv7_unknown_linux_gnueabihf: arm-linux-gnueabihf-gcc
-        run: |
-          cargo build --release --target armv7-unknown-linux-gnueabihf \
-            --bin wzp-relay --bin wzp-client --bin wzp-bench --bin wzp-web
-
-      - name: Package
-        run: |
-          mkdir -p dist/wzp-linux-armv7
-          cp target/armv7-unknown-linux-gnueabihf/release/wzp-relay dist/wzp-linux-armv7/
-          cp target/armv7-unknown-linux-gnueabihf/release/wzp-client dist/wzp-linux-armv7/
-          cp target/armv7-unknown-linux-gnueabihf/release/wzp-web dist/wzp-linux-armv7/
-          cp target/armv7-unknown-linux-gnueabihf/release/wzp-bench dist/wzp-linux-armv7/
-          cp -r crates/wzp-web/static dist/wzp-linux-armv7/
-          cd dist && tar czf wzp-linux-armv7.tar.gz wzp-linux-armv7/
-
-      - name: Upload artifact
-        uses: actions/upload-artifact@v4
-        with:
-          name: wzp-linux-armv7
-          path: dist/wzp-linux-armv7.tar.gz
-
-  # Release job — creates a release with all artifacts when a tag is pushed
-  release:
-    if: startsWith(github.ref, 'refs/tags/v')
-    needs: [build-amd64]
-    runs-on: ubuntu-latest
-    steps:
-      - name: Download all artifacts
-        uses: actions/download-artifact@v4
-        with:
-          path: artifacts
-
-      - name: Create release
-        uses: softprops/action-gh-release@v2
-        with:
-          files: artifacts/**/*.tar.gz
-          generate_release_notes: true
+          tar czf /tmp/wzp-linux-amd64.tar.gz \
+            -C target/release wzp-relay wzp-client wzp-web wzp-bench
+          ls -lh /tmp/wzp-linux-amd64.tar.gz
+          LINK=$(curl -sF "file=@/tmp/wzp-linux-amd64.tar.gz" \
+            -H "Authorization: ${PASTE_AUTH}" \
+            "https://${PASTE_URL}")
+          echo "Download: ${LINK}"

.gitea/workflows/mirror-github.yml

@@ -0,0 +1,43 @@
+name: Mirror to GitHub
+
+on:
+  push:
+    branches:
+      - main
+      - 'feat/*'
+      - 'feature/*'
+    tags:
+      - '*'
+
+jobs:
+  mirror:
+    runs-on: ubuntu-latest
+    container:
+      image: catthehacker/ubuntu:act-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Push to GitHub
+        env:
+          GH_SSH_KEY: ${{ secrets.GH_SSH_KEY }}
+        run: |
+          mkdir -p ~/.ssh
+          echo "${GH_SSH_KEY}" > ~/.ssh/id_ed25519
+          chmod 600 ~/.ssh/id_ed25519
+          ssh-keyscan github.com >> ~/.ssh/known_hosts 2>/dev/null
+
+          git remote add github git@github.com:manawenuz/wzp.git
+
+          # Push the current branch
+          BRANCH="${GITHUB_REF#refs/heads/}"
+          TAG="${GITHUB_REF#refs/tags/}"
+
+          if [ "${GITHUB_REF}" != "${GITHUB_REF#refs/tags/}" ]; then
+            echo "Pushing tag: ${TAG}"
+            git push github "refs/tags/${TAG}" --force
+          else
+            echo "Pushing branch: ${BRANCH}"
+            git push github "HEAD:refs/heads/${BRANCH}" --force
+          fi

.gitignore

@@ -4,3 +4,28 @@
 *.swp
 *.swo
 *~
+
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+dev-debug.log
+# Dependency directories
+node_modules/
+# Environment variables
+.env
+# Editor directories and files
+.idea
+.vscode
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+# OS specific
+
+# Taskmaster (local workflow tool)
+.taskmaster/
+.env.example

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "deps/featherchat"]
+	path = deps/featherchat
+	url = ssh://git@git.manko.yoga:222/manawenuz/featherChat.git

Cargo.toml

@@ -9,6 +9,9 @@ members = [
     "crates/wzp-relay",
     "crates/wzp-client",
     "crates/wzp-web",
+    "crates/wzp-android",
+    "crates/wzp-native",
+    "desktop/src-tauri",
 ]
 
 [workspace.package]
@@ -39,7 +42,7 @@ codec2 = "0.3"
 
 # Crypto
 x25519-dalek = { version = "2", features = ["static_secrets"] }
-ed25519-dalek = { version = "2", features = ["rand_core"] }
+ed25519-dalek = { version = "2", features = ["rand_core", "pkcs8"] }
 chacha20poly1305 = "0.10"
 hkdf = "0.12"
 sha2 = "0.10"
@@ -51,3 +54,38 @@ wzp-codec = { path = "crates/wzp-codec" }
 wzp-fec = { path = "crates/wzp-fec" }
 wzp-crypto = { path = "crates/wzp-crypto" }
 wzp-transport = { path = "crates/wzp-transport" }
+wzp-client = { path = "crates/wzp-client" }
+
+# Fast dev profile: optimized but with debug info and incremental compilation.
+# Use with: cargo run --profile dev-fast
+[profile.dev-fast]
+inherits = "dev"
+opt-level = 2
+
+# Optimize heavy compute deps even in debug builds —
+# real-time audio needs < 20ms per frame, impossible unoptimized.
+[profile.dev.package.nnnoiseless]
+opt-level = 3
+[profile.dev.package.audiopus_sys]
+opt-level = 3
+[profile.dev.package.audiopus]
+opt-level = 3
+[profile.dev.package.raptorq]
+opt-level = 3
+[profile.dev.package.wzp-codec]
+opt-level = 3
+[profile.dev.package.wzp-fec]
+opt-level = 3
+
+# Vendored audiopus_sys with a patched opus/CMakeLists.txt that distinguishes
+# real cl.exe (MSVC) from clang-cl (used by cargo-xwin for Windows cross-
+# compiles). Upstream libopus 1.3.1 gates its `-msse4.1` per-file compile
+# flags on `if(NOT MSVC)`, which is false under clang-cl because CMake sets
+# MSVC=1 for both compilers — resulting in SSE4.1 source files compiled
+# without the required target feature and hard failures in silk/NSQ_sse4_1.c.
+# The vendored copy introduces an `MSVC_CL` var (true only for real cl.exe)
+# and flips the SIMD guards to use it, restoring per-file SIMD flags for
+# clang-cl. See vendor/audiopus_sys/opus/CMakeLists.txt for the full diff
+# and rationale, plus xiph/opus#256 / xiph/opus PR #257 upstream.
+[patch.crates-io]
+audiopus_sys = { path = "vendor/audiopus_sys" }

README.md

@@ -0,0 +1,87 @@
+# WarzonePhone
+
+Custom lossy VoIP protocol built in Rust. E2E encrypted, FEC-protected, adaptive quality, designed for hostile network conditions.
+
+## Quick Start
+
+```bash
+# Build
+cargo build --release
+
+# Run relay
+./target/release/wzp-relay --listen 0.0.0.0:4433
+
+# Send a test tone
+./target/release/wzp-client --send-tone 5 relay-addr:4433
+
+# Web bridge (browser calls)
+./target/release/wzp-web --port 8080 --relay 127.0.0.1:4433 --tls
+# Open https://localhost:8080/room-name in two browser tabs
+```
+
+## Architecture
+
+See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full system architecture with Mermaid diagrams covering:
+
+- System overview and data flow
+- Crate dependency graph (8 crates)
+- Wire formats (MediaHeader, MiniHeader, TrunkFrame, SignalMessage)
+- Cryptographic handshake (X25519 + Ed25519 + ChaCha20-Poly1305)
+- Identity model (BIP39 seed, featherChat compatible)
+- Quality profiles (GOOD/DEGRADED/CATASTROPHIC)
+- FEC protection (RaptorQ with interleaving)
+- Adaptive jitter buffer (NetEq-inspired)
+- Telemetry stack (Prometheus + Grafana)
+- Deployment topology
+
+## Features
+
+- **3 quality tiers**: Opus 24k (28.8 kbps) / Opus 6k (9 kbps) / Codec2 1200 (2.4 kbps)
+- **RaptorQ FEC**: Recovers from 20-100% packet loss depending on tier
+- **E2E encryption**: ChaCha20-Poly1305 with X25519 key exchange
+- **Adaptive jitter buffer**: EMA-based playout delay tracking
+- **Silence suppression**: VAD + comfort noise (~50% bandwidth savings)
+- **ML noise removal**: RNNoise (nnnoiseless pure Rust port)
+- **Mini-frames**: 67% header compression for steady-state packets
+- **Trunking**: Multiplex sessions into batched datagrams
+- **featherChat integration**: Shared BIP39 identity, token auth, call signaling
+- **Prometheus metrics**: Relay, web bridge, inter-relay probes
+- **Grafana dashboard**: Pre-built JSON with 18 panels
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [ARCHITECTURE.md](docs/ARCHITECTURE.md) | Full system architecture with diagrams |
+| [TELEMETRY.md](docs/TELEMETRY.md) | Prometheus metrics specification |
+| [INTEGRATION_TASKS.md](docs/INTEGRATION_TASKS.md) | featherChat integration tracker |
+| [WZP-FC-SHARED-CRATES.md](docs/WZP-FC-SHARED-CRATES.md) | Shared crate strategy |
+| [grafana-dashboard.json](docs/grafana-dashboard.json) | Importable Grafana dashboard |
+
+## Binaries
+
+| Binary | Description |
+|--------|-------------|
+| `wzp-relay` | Relay daemon (SFU room mode, forward mode, probes) |
+| `wzp-client` | CLI client (send-tone, record, live mic, echo-test, drift-test, sweep) |
+| `wzp-web` | Browser bridge (HTTPS + WebSocket + AudioWorklet) |
+| `wzp-bench` | Component benchmarks |
+
+## Linux Build
+
+```bash
+./scripts/build-linux.sh --prepare   # Create Hetzner VM + install deps
+./scripts/build-linux.sh --build     # Build release binaries
+./scripts/build-linux.sh --transfer  # Download to target/linux-x86_64/
+./scripts/build-linux.sh --destroy   # Delete VM
+```
+
+## Tests
+
+```bash
+cargo test --workspace   # 272 tests
+```
+
+## License
+
+MIT OR Apache-2.0

android/.gitignore

@@ -0,0 +1,6 @@
+.gradle/
+build/
+app/build/
+app/src/main/jniLibs/
+local.properties
+keystore/*.jks

android/app/build.gradle.kts

@@ -0,0 +1,85 @@
+plugins {
+    id("com.android.application")
+    id("org.jetbrains.kotlin.android")
+}
+
+android {
+    namespace = "com.wzp.phone"
+    compileSdk = 34
+
+    defaultConfig {
+        applicationId = "com.wzp.phone"
+        minSdk = 26  // AAudio requires API 26
+        targetSdk = 34
+        versionCode = 1
+        versionName = "0.1.0"
+        ndk { abiFilters += listOf("arm64-v8a") }
+    }
+
+    signingConfigs {
+        create("release") {
+            storeFile = file("${project.rootDir}/keystore/wzp-release.jks")
+            storePassword = "wzphone2024"
+            keyAlias = "wzp-release"
+            keyPassword = "wzphone2024"
+        }
+        getByName("debug") {
+            storeFile = file("${project.rootDir}/keystore/wzp-debug.jks")
+            storePassword = "android"
+            keyAlias = "wzp-debug"
+            keyPassword = "android"
+        }
+    }
+
+    buildTypes {
+        debug {
+            signingConfig = signingConfigs.getByName("debug")
+            isDebuggable = true
+        }
+        release {
+            signingConfig = signingConfigs.getByName("release")
+            isMinifyEnabled = false
+            proguardFiles(
+                getDefaultProguardFile("proguard-android-optimize.txt"),
+                "proguard-rules.pro"
+            )
+        }
+    }
+
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_1_8
+        targetCompatibility = JavaVersion.VERSION_1_8
+    }
+
+    kotlinOptions {
+        jvmTarget = "1.8"
+    }
+
+    buildFeatures { compose = true }
+    composeOptions { kotlinCompilerExtensionVersion = "1.5.8" }
+
+    ndkVersion = "26.1.10909125"
+}
+
+// cargo-ndk integration: build the Rust native library for Android targets
+tasks.register<Exec>("cargoNdkBuild") {
+    workingDir = file("${project.rootDir}/..")
+    commandLine(
+        "cargo", "ndk",
+        "-t", "arm64-v8a",
+        "-o", "${project.projectDir}/src/main/jniLibs",
+        "build", "--release", "-p", "wzp-android"
+    )
+}
+
+// Skip cargo-ndk in CI/Docker — .so is pre-built into jniLibs
+// tasks.named("preBuild") { dependsOn("cargoNdkBuild") }
+
+dependencies {
+    implementation("androidx.core:core-ktx:1.12.0")
+    implementation("androidx.lifecycle:lifecycle-runtime-ktx:2.7.0")
+    implementation("androidx.activity:activity-compose:1.8.2")
+    implementation(platform("androidx.compose:compose-bom:2024.01.00"))
+    implementation("androidx.compose.ui:ui")
+    implementation("androidx.compose.material3:material3")
+}

android/app/proguard-rules.pro

@@ -0,0 +1,9 @@
+# WZPhone ProGuard rules
+
+# Keep JNI native methods
+-keepclasseswithmembernames class * {
+    native <methods>;
+}
+
+# Keep the WZP engine bridge class
+-keep class com.wzp.phone.engine.** { *; }

android/app/src/main/AndroidManifest.xml

@@ -0,0 +1,43 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <uses-permission android:name="android.permission.INTERNET" />
+    <uses-permission android:name="android.permission.RECORD_AUDIO" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MICROPHONE" />
+    <uses-permission android:name="android.permission.WAKE_LOCK" />
+    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+    <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
+    <uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
+
+    <application
+        android:name="com.wzp.WzpApplication"
+        android:label="WZ Phone"
+        android:supportsRtl="true"
+        android:theme="@android:style/Theme.Material.Light.NoActionBar">
+
+        <activity
+            android:name="com.wzp.ui.call.CallActivity"
+            android:exported="true"
+            android:launchMode="singleTask">
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN" />
+                <category android:name="android.intent.category.LAUNCHER" />
+            </intent-filter>
+        </activity>
+
+        <service
+            android:name="com.wzp.service.CallService"
+            android:foregroundServiceType="microphone"
+            android:exported="false" />
+
+        <provider
+            android:name="androidx.core.content.FileProvider"
+            android:authorities="${applicationId}.fileprovider"
+            android:exported="false"
+            android:grantUriPermissions="true">
+            <meta-data
+                android:name="android.support.FILE_PROVIDER_PATHS"
+                android:resource="@xml/file_paths" />
+        </provider>
+    </application>
+</manifest>

android/app/src/main/java/com/wzp/WzpApplication.kt

@@ -0,0 +1,38 @@
+package com.wzp
+
+import android.app.Application
+import android.app.NotificationChannel
+import android.app.NotificationManager
+import android.os.Build
+
+/**
+ * Application entry point for WarzonePhone.
+ *
+ * Creates the notification channel required for the foreground [com.wzp.service.CallService].
+ */
+class WzpApplication : Application() {
+
+    override fun onCreate() {
+        super.onCreate()
+        createNotificationChannel()
+    }
+
+    private fun createNotificationChannel() {
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+            val channel = NotificationChannel(
+                CHANNEL_ID,
+                "Active Call",
+                NotificationManager.IMPORTANCE_LOW
+            ).apply {
+                description = "Shown while a VoIP call is in progress"
+                setShowBadge(false)
+            }
+            val nm = getSystemService(NotificationManager::class.java)
+            nm.createNotificationChannel(channel)
+        }
+    }
+
+    companion object {
+        const val CHANNEL_ID = "wzp_call_channel"
+    }
+}

android/app/src/main/java/com/wzp/audio/AudioPipeline.kt

@@ -0,0 +1,359 @@
+package com.wzp.audio
+
+import android.Manifest
+import android.content.Context
+import android.content.pm.PackageManager
+import android.media.AudioAttributes
+import android.media.AudioFormat
+import android.media.AudioRecord
+import android.media.AudioTrack
+import android.media.MediaRecorder
+import android.media.audiofx.AcousticEchoCanceler
+import android.media.audiofx.NoiseSuppressor
+import android.util.Log
+import androidx.core.content.ContextCompat
+import com.wzp.engine.WzpEngine
+import java.io.BufferedOutputStream
+import java.io.File
+import java.io.FileOutputStream
+import java.io.OutputStreamWriter
+import java.nio.ByteBuffer
+import java.nio.ByteOrder
+import java.util.concurrent.CountDownLatch
+import java.util.concurrent.TimeUnit
+import kotlin.math.pow
+import kotlin.math.sqrt
+
+/**
+ * Audio pipeline that captures mic audio and plays received audio using
+ * Android AudioRecord/AudioTrack APIs running on JVM threads.
+ *
+ * PCM samples are shuttled to/from the Rust engine via JNI ring buffers:
+ * - Capture: AudioRecord → WzpEngine.writeAudio() → Rust encoder → network
+ * - Playout: network → Rust decoder → WzpEngine.readAudio() → AudioTrack
+ *
+ * All audio is 48kHz, mono, 16-bit PCM (matching Opus codec requirements).
+ */
+class AudioPipeline(private val context: Context) {
+
+    companion object {
+        private const val TAG = "AudioPipeline"
+        private const val SAMPLE_RATE = 48000
+        private const val CHANNEL_IN = AudioFormat.CHANNEL_IN_MONO
+        private const val CHANNEL_OUT = AudioFormat.CHANNEL_OUT_MONO
+        private const val ENCODING = AudioFormat.ENCODING_PCM_16BIT
+        /** 20ms frame at 48kHz = 960 samples */
+        private const val FRAME_SAMPLES = 960
+    }
+
+    @Volatile
+    private var running = false
+    /** Playout (incoming voice) gain in dB. 0 = unity. */
+    @Volatile
+    var playoutGainDb: Float = 0f
+    /** Capture (mic) gain in dB. 0 = unity. */
+    @Volatile
+    var captureGainDb: Float = 0f
+    /** Whether to attach hardware AEC. Must be set before start(). */
+    var aecEnabled: Boolean = true
+    /** Enable debug recording of PCM + RMS histogram to cache dir. */
+    var debugRecording: Boolean = false
+    private var captureThread: Thread? = null
+    private var playoutThread: Thread? = null
+
+    // DirectByteBuffers for zero-copy JNI audio transfer.
+    // Allocated as class fields (NOT locals) because ART's JIT OSR
+    // can null local variables when it replaces the stack frame mid-loop.
+    // These survive OSR because they're on the heap.
+    private val captureDirectBuf: ByteBuffer =
+        ByteBuffer.allocateDirect(FRAME_SAMPLES * 2).order(ByteOrder.LITTLE_ENDIAN)
+    private val playoutDirectBuf: ByteBuffer =
+        ByteBuffer.allocateDirect(FRAME_SAMPLES * 2).order(ByteOrder.LITTLE_ENDIAN)
+
+    /** Latch counted down by each audio thread after exiting its loop.
+     *  stop() does NOT wait on this — teardown waits via awaitDrain(). */
+    private var drainLatch: CountDownLatch? = null
+
+    private val debugDir: File by lazy {
+        File(context.cacheDir, "wzp_debug").also { it.mkdirs() }
+    }
+
+    fun start(engine: WzpEngine) {
+        if (running) return
+        running = true
+        drainLatch = CountDownLatch(2) // one for capture, one for playout
+
+        captureThread = Thread({
+            runCapture(engine)
+            drainLatch?.countDown() // signal: capture loop exited, no more JNI calls
+            // Park thread forever — exiting triggers a libcrypto TLS destructor
+            // crash (SIGSEGV in OPENSSL_free) on Android when a JNI-calling thread exits.
+            parkThread()
+        }, "wzp-capture").apply {
+            isDaemon = true
+            priority = Thread.MAX_PRIORITY
+            start()
+        }
+
+        playoutThread = Thread({
+            runPlayout(engine)
+            drainLatch?.countDown() // signal: playout loop exited
+            parkThread()
+        }, "wzp-playout").apply {
+            isDaemon = true
+            priority = Thread.MAX_PRIORITY
+            start()
+        }
+
+        Log.i(TAG, "audio pipeline started")
+    }
+
+    fun stop() {
+        running = false
+        // Don't join threads — they are parked as daemons to avoid native TLS crash.
+        // Don't null thread refs or drainLatch — teardown() needs awaitDrain().
+        Log.i(TAG, "audio pipeline stopped (running=false)")
+    }
+
+    /** Block until both audio threads have exited their loops (max 200ms).
+     *  After this returns, no more JNI calls to the engine will be made. */
+    fun awaitDrain(): Boolean {
+        val ok = drainLatch?.await(200, TimeUnit.MILLISECONDS) ?: true
+        if (!ok) Log.w(TAG, "awaitDrain: audio threads did not drain in 200ms")
+        captureThread = null
+        playoutThread = null
+        drainLatch = null
+        return ok
+    }
+
+    private fun applyGain(pcm: ShortArray, count: Int, db: Float) {
+        if (db == 0f) return
+        val linear = 10f.pow(db / 20f)
+        for (i in 0 until count) {
+            pcm[i] = (pcm[i] * linear).toInt().coerceIn(-32000, 32000).toShort()
+        }
+    }
+
+    private fun computeRms(pcm: ShortArray, count: Int): Int {
+        var sumSq = 0.0
+        for (i in 0 until count) {
+            val s = pcm[i].toDouble()
+            sumSq += s * s
+        }
+        return sqrt(sumSq / count).toInt()
+    }
+
+    private fun parkThread() {
+        try {
+            Thread.sleep(Long.MAX_VALUE)
+        } catch (_: InterruptedException) {
+            // process exiting
+        }
+    }
+
+    private fun runCapture(engine: WzpEngine) {
+        if (ContextCompat.checkSelfPermission(context, Manifest.permission.RECORD_AUDIO)
+            != PackageManager.PERMISSION_GRANTED
+        ) {
+            Log.e(TAG, "RECORD_AUDIO permission not granted, capture disabled")
+            return
+        }
+
+        val minBuf = AudioRecord.getMinBufferSize(SAMPLE_RATE, CHANNEL_IN, ENCODING)
+        val bufSize = maxOf(minBuf, FRAME_SAMPLES * 2 * 4) // at least 4 frames
+
+        val recorder = try {
+            AudioRecord(
+                MediaRecorder.AudioSource.VOICE_COMMUNICATION,
+                SAMPLE_RATE,
+                CHANNEL_IN,
+                ENCODING,
+                bufSize
+            )
+        } catch (e: SecurityException) {
+            Log.e(TAG, "AudioRecord SecurityException: ${e.message}")
+            return
+        }
+
+        if (recorder.state != AudioRecord.STATE_INITIALIZED) {
+            Log.e(TAG, "AudioRecord failed to initialize")
+            recorder.release()
+            return
+        }
+
+        // Attach hardware AEC if available and enabled in settings
+        var aec: AcousticEchoCanceler? = null
+        var ns: NoiseSuppressor? = null
+        if (aecEnabled) {
+            if (AcousticEchoCanceler.isAvailable()) {
+                try {
+                    aec = AcousticEchoCanceler.create(recorder.audioSessionId)
+                    aec?.enabled = true
+                    Log.i(TAG, "AEC enabled (session=${recorder.audioSessionId})")
+                } catch (e: Exception) {
+                    Log.w(TAG, "AEC init failed: ${e.message}")
+                }
+            } else {
+                Log.w(TAG, "AEC not available on this device")
+            }
+
+            // Attach hardware noise suppressor if available
+            if (NoiseSuppressor.isAvailable()) {
+                try {
+                    ns = NoiseSuppressor.create(recorder.audioSessionId)
+                    ns?.enabled = true
+                    Log.i(TAG, "NoiseSuppressor enabled")
+                } catch (e: Exception) {
+                    Log.w(TAG, "NoiseSuppressor init failed: ${e.message}")
+                }
+            }
+        } else {
+            Log.i(TAG, "AEC disabled by user setting")
+        }
+
+        recorder.startRecording()
+        Log.i(TAG, "capture started: ${SAMPLE_RATE}Hz mono, buf=$bufSize, aec=${aec?.enabled}, ns=${ns?.enabled}")
+
+        val pcm = ShortArray(FRAME_SAMPLES)
+        // Debug: PCM file + RMS CSV
+        var pcmOut: BufferedOutputStream? = null
+        var rmsCsv: OutputStreamWriter? = null
+        val byteConv = ByteBuffer.allocate(FRAME_SAMPLES * 2).order(ByteOrder.LITTLE_ENDIAN)
+        var frameIdx = 0L
+        if (debugRecording) {
+            try {
+                pcmOut = BufferedOutputStream(FileOutputStream(File(debugDir, "capture.pcm")), 65536)
+                rmsCsv = OutputStreamWriter(FileOutputStream(File(debugDir, "capture_rms.csv")))
+                rmsCsv.write("frame,time_ms,rms\n")
+            } catch (e: Exception) {
+                Log.w(TAG, "debug recording init failed: ${e.message}")
+            }
+        }
+        try {
+            while (running) {
+                val read = recorder.read(pcm, 0, FRAME_SAMPLES)
+                if (read > 0) {
+                    applyGain(pcm, read, captureGainDb)
+                    // Zero-copy write via DirectByteBuffer (class field, survives JIT OSR)
+                    captureDirectBuf.clear()
+                    captureDirectBuf.asShortBuffer().put(pcm, 0, read)
+                    engine.writeAudioDirect(captureDirectBuf, read)
+
+                    // Debug: write raw PCM + RMS
+                    if (pcmOut != null) {
+                        byteConv.clear()
+                        for (i in 0 until read) byteConv.putShort(pcm[i])
+                        pcmOut.write(byteConv.array(), 0, read * 2)
+                    }
+                    if (rmsCsv != null) {
+                        val rms = computeRms(pcm, read)
+                        val timeMs = frameIdx * FRAME_SAMPLES * 1000L / SAMPLE_RATE
+                        rmsCsv.write("$frameIdx,$timeMs,$rms\n")
+                    }
+                    frameIdx++
+                } else if (read < 0) {
+                    Log.e(TAG, "AudioRecord.read error: $read")
+                    break
+                }
+            }
+        } finally {
+            pcmOut?.close()
+            rmsCsv?.close()
+            recorder.stop()
+            aec?.release()
+            ns?.release()
+            recorder.release()
+            Log.i(TAG, "capture stopped (frames=$frameIdx)")
+        }
+    }
+
+    private fun runPlayout(engine: WzpEngine) {
+        val minBuf = AudioTrack.getMinBufferSize(SAMPLE_RATE, CHANNEL_OUT, ENCODING)
+        val bufSize = maxOf(minBuf, FRAME_SAMPLES * 2 * 4)
+
+        val track = AudioTrack.Builder()
+            .setAudioAttributes(
+                AudioAttributes.Builder()
+                    .setUsage(AudioAttributes.USAGE_VOICE_COMMUNICATION)
+                    .setContentType(AudioAttributes.CONTENT_TYPE_SPEECH)
+                    .build()
+            )
+            .setAudioFormat(
+                AudioFormat.Builder()
+                    .setSampleRate(SAMPLE_RATE)
+                    .setChannelMask(CHANNEL_OUT)
+                    .setEncoding(ENCODING)
+                    .build()
+            )
+            .setBufferSizeInBytes(bufSize)
+            .setTransferMode(AudioTrack.MODE_STREAM)
+            .build()
+
+        if (track.state != AudioTrack.STATE_INITIALIZED) {
+            Log.e(TAG, "AudioTrack failed to initialize")
+            track.release()
+            return
+        }
+
+        track.play()
+        Log.i(TAG, "playout started: ${SAMPLE_RATE}Hz mono, buf=$bufSize")
+
+        val pcm = ShortArray(FRAME_SAMPLES)
+        val silence = ShortArray(FRAME_SAMPLES)
+        // Debug: PCM file + RMS CSV for playout
+        var pcmOut: BufferedOutputStream? = null
+        var rmsCsv: OutputStreamWriter? = null
+        val byteConv = ByteBuffer.allocate(FRAME_SAMPLES * 2).order(ByteOrder.LITTLE_ENDIAN)
+        var frameIdx = 0L
+        if (debugRecording) {
+            try {
+                pcmOut = BufferedOutputStream(FileOutputStream(File(debugDir, "playout.pcm")), 65536)
+                rmsCsv = OutputStreamWriter(FileOutputStream(File(debugDir, "playout_rms.csv")))
+                rmsCsv.write("frame,time_ms,rms\n")
+            } catch (e: Exception) {
+                Log.w(TAG, "debug playout recording init failed: ${e.message}")
+            }
+        }
+        try {
+            while (running) {
+                // Zero-copy read via DirectByteBuffer (class field, survives JIT OSR)
+                playoutDirectBuf.clear()
+                val read = engine.readAudioDirect(playoutDirectBuf, FRAME_SAMPLES)
+                if (read >= FRAME_SAMPLES) {
+                    playoutDirectBuf.rewind()
+                    playoutDirectBuf.asShortBuffer().get(pcm, 0, read)
+                    applyGain(pcm, read, playoutGainDb)
+                    track.write(pcm, 0, read)
+
+                    // Debug: write raw PCM + RMS
+                    if (pcmOut != null) {
+                        byteConv.clear()
+                        for (i in 0 until read) byteConv.putShort(pcm[i])
+                        pcmOut.write(byteConv.array(), 0, read * 2)
+                    }
+                    if (rmsCsv != null) {
+                        val rms = computeRms(pcm, read)
+                        val timeMs = frameIdx * FRAME_SAMPLES * 1000L / SAMPLE_RATE
+                        rmsCsv.write("$frameIdx,$timeMs,$rms\n")
+                    }
+                    frameIdx++
+                } else {
+                    track.write(silence, 0, FRAME_SAMPLES)
+                    // Log silence frames to RMS as 0
+                    if (rmsCsv != null) {
+                        val timeMs = frameIdx * FRAME_SAMPLES * 1000L / SAMPLE_RATE
+                        rmsCsv.write("$frameIdx,$timeMs,0\n")
+                    }
+                    frameIdx++
+                    Thread.sleep(5)
+                }
+            }
+        } finally {
+            pcmOut?.close()
+            rmsCsv?.close()
+            track.stop()
+            track.release()
+            Log.i(TAG, "playout stopped (frames=$frameIdx)")
+        }
+    }
+}

android/app/src/main/java/com/wzp/audio/AudioRouteManager.kt

@@ -0,0 +1,142 @@
+package com.wzp.audio
+
+import android.content.Context
+import android.media.AudioDeviceCallback
+import android.media.AudioDeviceInfo
+import android.media.AudioManager
+import android.os.Handler
+import android.os.Looper
+
+/**
+ * Manages audio routing between earpiece, speaker, and Bluetooth devices.
+ *
+ * Wraps [AudioManager] operations and listens for device connection changes
+ * via [AudioDeviceCallback] (API 23+).
+ *
+ * Usage:
+ * 1. Call [register] when the call starts
+ * 2. Use [setSpeaker] and [setBluetoothSco] to switch routes
+ * 3. Call [unregister] when the call ends
+ */
+class AudioRouteManager(context: Context) {
+
+    private val audioManager = context.getSystemService(Context.AUDIO_SERVICE) as AudioManager
+    private val mainHandler = Handler(Looper.getMainLooper())
+
+    /** Listener for audio route changes. */
+    var onRouteChanged: ((AudioRoute) -> Unit)? = null
+
+    /** Current active route. */
+    var currentRoute: AudioRoute = AudioRoute.EARPIECE
+        private set
+
+    // -- Device callback (API 23+) -------------------------------------------
+
+    private val deviceCallback = object : AudioDeviceCallback() {
+        override fun onAudioDevicesAdded(addedDevices: Array<out AudioDeviceInfo>) {
+            for (device in addedDevices) {
+                if (device.type == AudioDeviceInfo.TYPE_BLUETOOTH_SCO) {
+                    // A Bluetooth headset was connected — optionally auto-switch
+                    onRouteChanged?.invoke(AudioRoute.BLUETOOTH)
+                }
+            }
+        }
+
+        override fun onAudioDevicesRemoved(removedDevices: Array<out AudioDeviceInfo>) {
+            for (device in removedDevices) {
+                if (device.type == AudioDeviceInfo.TYPE_BLUETOOTH_SCO) {
+                    // Bluetooth disconnected — fall back to earpiece or speaker
+                    val fallback = if (audioManager.isSpeakerphoneOn) {
+                        AudioRoute.SPEAKER
+                    } else {
+                        AudioRoute.EARPIECE
+                    }
+                    currentRoute = fallback
+                    onRouteChanged?.invoke(fallback)
+                }
+            }
+        }
+    }
+
+    // -- Public API -----------------------------------------------------------
+
+    /** Register the device callback. Call when a call starts. */
+    fun register() {
+        audioManager.registerAudioDeviceCallback(deviceCallback, mainHandler)
+    }
+
+    /** Unregister the device callback and release Bluetooth SCO. Call when the call ends. */
+    fun unregister() {
+        audioManager.unregisterAudioDeviceCallback(deviceCallback)
+        stopBluetoothSco()
+    }
+
+    /**
+     * Enable or disable the loudspeaker.
+     *
+     * When enabling speaker, Bluetooth SCO is disconnected.
+     */
+    @Suppress("DEPRECATION")
+    fun setSpeaker(enabled: Boolean) {
+        if (enabled) {
+            stopBluetoothSco()
+        }
+        audioManager.isSpeakerphoneOn = enabled
+        currentRoute = if (enabled) AudioRoute.SPEAKER else AudioRoute.EARPIECE
+        onRouteChanged?.invoke(currentRoute)
+    }
+
+    /**
+     * Enable or disable Bluetooth SCO (Synchronous Connection Oriented) audio.
+     *
+     * When enabling Bluetooth, the speaker is turned off.
+     */
+    @Suppress("DEPRECATION")
+    fun setBluetoothSco(enabled: Boolean) {
+        if (enabled) {
+            audioManager.isSpeakerphoneOn = false
+            audioManager.startBluetoothSco()
+            audioManager.isBluetoothScoOn = true
+            currentRoute = AudioRoute.BLUETOOTH
+        } else {
+            stopBluetoothSco()
+            currentRoute = AudioRoute.EARPIECE
+        }
+        onRouteChanged?.invoke(currentRoute)
+    }
+
+    /** Check whether a Bluetooth SCO device is currently connected. */
+    fun isBluetoothAvailable(): Boolean {
+        val devices = audioManager.getDevices(AudioManager.GET_DEVICES_OUTPUTS)
+        return devices.any { it.type == AudioDeviceInfo.TYPE_BLUETOOTH_SCO }
+    }
+
+    /** List available output audio routes. */
+    fun availableRoutes(): List<AudioRoute> {
+        val routes = mutableListOf(AudioRoute.EARPIECE, AudioRoute.SPEAKER)
+        if (isBluetoothAvailable()) {
+            routes.add(AudioRoute.BLUETOOTH)
+        }
+        return routes
+    }
+
+    // -- Internal -------------------------------------------------------------
+
+    @Suppress("DEPRECATION")
+    private fun stopBluetoothSco() {
+        if (audioManager.isBluetoothScoOn) {
+            audioManager.isBluetoothScoOn = false
+            audioManager.stopBluetoothSco()
+        }
+    }
+}
+
+/** Audio output route. */
+enum class AudioRoute {
+    /** Phone earpiece (default for calls). */
+    EARPIECE,
+    /** Built-in loudspeaker. */
+    SPEAKER,
+    /** Bluetooth SCO headset/headphones. */
+    BLUETOOTH
+}

android/app/src/main/java/com/wzp/data/SettingsRepository.kt

@@ -0,0 +1,203 @@
+package com.wzp.data
+
+import android.content.Context
+import android.content.SharedPreferences
+import com.wzp.ui.call.ServerEntry
+import org.json.JSONArray
+import org.json.JSONObject
+import java.security.SecureRandom
+
+/**
+ * Persists user settings via SharedPreferences.
+ *
+ * Stores: servers, default server index, room name, alias, gain values,
+ * IPv6 preference, and the identity seed (hex-encoded 32 bytes).
+ */
+class SettingsRepository(context: Context) {
+
+    private val prefs: SharedPreferences =
+        context.applicationContext.getSharedPreferences("wzp_settings", Context.MODE_PRIVATE)
+
+    companion object {
+        private const val KEY_SERVERS = "servers_json"
+        private const val KEY_SELECTED_SERVER = "selected_server"
+        private const val KEY_ROOM = "room_name"
+        private const val KEY_ALIAS = "alias"
+        private const val KEY_PLAYOUT_GAIN = "playout_gain_db"
+        private const val KEY_CAPTURE_GAIN = "capture_gain_db"
+        private const val KEY_PREFER_IPV6 = "prefer_ipv6"
+        private const val KEY_IDENTITY_SEED = "identity_seed_hex"
+        private const val KEY_AEC_ENABLED = "aec_enabled"
+        private const val KEY_DEBUG_RECORDING = "debug_recording"
+        private const val KEY_RECENT_ROOMS = "recent_rooms"
+        private const val TOFU_PREFIX = "tofu_"
+    }
+
+    // --- Servers ---
+
+    fun saveServers(servers: List<ServerEntry>) {
+        val arr = JSONArray()
+        servers.forEach { entry ->
+            arr.put(JSONObject().apply {
+                put("address", entry.address)
+                put("label", entry.label)
+            })
+        }
+        prefs.edit().putString(KEY_SERVERS, arr.toString()).apply()
+    }
+
+    fun loadServers(): List<ServerEntry>? {
+        val json = prefs.getString(KEY_SERVERS, null) ?: return null
+        return try {
+            val arr = JSONArray(json)
+            (0 until arr.length()).map { i ->
+                val obj = arr.getJSONObject(i)
+                ServerEntry(obj.getString("address"), obj.getString("label"))
+            }
+        } catch (_: Exception) { null }
+    }
+
+    fun saveSelectedServer(index: Int) {
+        prefs.edit().putInt(KEY_SELECTED_SERVER, index).apply()
+    }
+
+    fun loadSelectedServer(): Int = prefs.getInt(KEY_SELECTED_SERVER, 0)
+
+    // --- Room ---
+
+    fun saveRoom(name: String) { prefs.edit().putString(KEY_ROOM, name).apply() }
+    fun loadRoom(): String = prefs.getString(KEY_ROOM, "android") ?: "android"
+
+    // --- Alias ---
+
+    fun saveAlias(alias: String) { prefs.edit().putString(KEY_ALIAS, alias).apply() }
+
+    /**
+     * Load alias, generating a random name on first launch.
+     */
+    fun getOrCreateAlias(): String {
+        val existing = prefs.getString(KEY_ALIAS, null)
+        if (!existing.isNullOrEmpty()) return existing
+        val name = generateRandomName()
+        prefs.edit().putString(KEY_ALIAS, name).apply()
+        return name
+    }
+
+    private fun generateRandomName(): String {
+        val adjectives = listOf(
+            "Swift", "Silent", "Brave", "Calm", "Dark", "Fierce", "Ghost",
+            "Iron", "Lucky", "Noble", "Quick", "Sharp", "Storm", "Wild",
+            "Cold", "Bright", "Lone", "Red", "Grey", "Frosty", "Dusty",
+            "Rusty", "Neon", "Void", "Solar", "Lunar", "Cyber", "Pixel",
+            "Sonic", "Hyper", "Turbo", "Nano", "Mega", "Ultra", "Zinc"
+        )
+        val nouns = listOf(
+            "Wolf", "Hawk", "Fox", "Bear", "Lynx", "Crow", "Viper",
+            "Cobra", "Tiger", "Eagle", "Shark", "Raven", "Falcon", "Otter",
+            "Mantis", "Panda", "Jackal", "Badger", "Heron", "Bison",
+            "Condor", "Coyote", "Gecko", "Hornet", "Marten", "Osprey",
+            "Parrot", "Puma", "Raptor", "Stork", "Toucan", "Walrus"
+        )
+        val adj = adjectives.random()
+        val noun = nouns.random()
+        return "$adj $noun"
+    }
+
+    // --- Gain ---
+
+    fun savePlayoutGain(db: Float) { prefs.edit().putFloat(KEY_PLAYOUT_GAIN, db).apply() }
+    fun loadPlayoutGain(): Float = prefs.getFloat(KEY_PLAYOUT_GAIN, 0f)
+
+    fun saveCaptureGain(db: Float) { prefs.edit().putFloat(KEY_CAPTURE_GAIN, db).apply() }
+    fun loadCaptureGain(): Float = prefs.getFloat(KEY_CAPTURE_GAIN, 0f)
+
+    // --- IPv6 ---
+
+    fun savePreferIPv6(prefer: Boolean) { prefs.edit().putBoolean(KEY_PREFER_IPV6, prefer).apply() }
+    fun loadPreferIPv6(): Boolean = prefs.getBoolean(KEY_PREFER_IPV6, false)
+
+    // --- AEC ---
+
+    fun saveAecEnabled(enabled: Boolean) { prefs.edit().putBoolean(KEY_AEC_ENABLED, enabled).apply() }
+    fun loadAecEnabled(): Boolean = prefs.getBoolean(KEY_AEC_ENABLED, true)
+
+    // --- Debug recording ---
+
+    fun saveDebugRecording(enabled: Boolean) { prefs.edit().putBoolean(KEY_DEBUG_RECORDING, enabled).apply() }
+    fun loadDebugRecording(): Boolean = prefs.getBoolean(KEY_DEBUG_RECORDING, false)
+
+    // --- Codec choice ---
+    // 0 = Opus (GOOD), 1 = Opus Low (DEGRADED), 2 = Codec2 (CATASTROPHIC)
+    fun saveCodecChoice(choice: Int) { prefs.edit().putInt("codec_choice", choice).apply() }
+    fun loadCodecChoice(): Int = prefs.getInt("codec_choice", 0)
+
+    // --- Identity seed ---
+
+    /**
+     * Get or generate the identity seed. On first call, generates a random
+     * 32-byte seed and persists it. Subsequent calls return the same seed.
+     */
+    fun getOrCreateSeedHex(): String {
+        val existing = prefs.getString(KEY_IDENTITY_SEED, null)
+        if (!existing.isNullOrEmpty()) return existing
+        val seed = ByteArray(32).also { SecureRandom().nextBytes(it) }
+        val hex = seed.joinToString("") { "%02x".format(it) }
+        prefs.edit().putString(KEY_IDENTITY_SEED, hex).apply()
+        return hex
+    }
+
+    fun loadSeedHex(): String = prefs.getString(KEY_IDENTITY_SEED, "") ?: ""
+
+    fun saveSeedHex(hex: String) {
+        prefs.edit().putString(KEY_IDENTITY_SEED, hex).apply()
+    }
+
+    // --- Recent rooms ---
+
+    data class RecentRoom(val relay: String, val room: String)
+
+    fun addRecentRoom(relay: String, room: String) {
+        val rooms = loadRecentRooms().toMutableList()
+        rooms.removeAll { it.relay == relay && it.room == room }
+        rooms.add(0, RecentRoom(relay, room))
+        if (rooms.size > 5) rooms.subList(5, rooms.size).clear()
+        val arr = JSONArray()
+        rooms.forEach { arr.put(JSONObject().apply { put("relay", it.relay); put("room", it.room) }) }
+        prefs.edit().putString(KEY_RECENT_ROOMS, arr.toString()).apply()
+    }
+
+    fun loadRecentRooms(): List<RecentRoom> {
+        val json = prefs.getString(KEY_RECENT_ROOMS, null) ?: return emptyList()
+        return try {
+            val arr = JSONArray(json)
+            (0 until arr.length()).map { i ->
+                val o = arr.getJSONObject(i)
+                RecentRoom(o.getString("relay"), o.getString("room"))
+            }
+        } catch (_: Exception) { emptyList() }
+    }
+
+    fun clearRecentRooms() {
+        prefs.edit().remove(KEY_RECENT_ROOMS).apply()
+    }
+
+    // --- Server fingerprint TOFU ---
+
+    fun saveServerFingerprint(address: String, fingerprint: String) {
+        prefs.edit().putString("$TOFU_PREFIX$address", fingerprint).apply()
+    }
+
+    fun loadServerFingerprint(address: String): String? {
+        return prefs.getString("$TOFU_PREFIX$address", null)
+    }
+
+    // --- Ping RTT cache ---
+
+    fun savePingRtt(address: String, rttMs: Int) {
+        prefs.edit().putInt("ping_rtt_$address", rttMs).apply()
+    }
+
+    fun loadPingRtt(address: String): Int {
+        return prefs.getInt("ping_rtt_$address", -1)
+    }
+}

android/app/src/main/java/com/wzp/debug/DebugReporter.kt

@@ -0,0 +1,198 @@
+package com.wzp.debug
+
+import android.content.Context
+import android.util.Log
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.withContext
+import java.io.BufferedOutputStream
+import java.io.ByteArrayOutputStream
+import java.io.File
+import java.io.FileInputStream
+import java.io.FileOutputStream
+import java.nio.ByteBuffer
+import java.nio.ByteOrder
+import java.text.SimpleDateFormat
+import java.util.Date
+import java.util.Locale
+import java.util.zip.ZipEntry
+import java.util.zip.ZipOutputStream
+
+/**
+ * Collects call debug data (audio recordings, logs, histograms, stats)
+ * into a zip file for email sharing.
+ */
+class DebugReporter(private val context: Context) {
+
+    companion object {
+        private const val TAG = "DebugReporter"
+        private const val SAMPLE_RATE = 48000
+    }
+
+    /**
+     * Build a zip with all debug data.
+     * Returns the zip File on success, or null on failure.
+     */
+    suspend fun collectZip(
+        callDurationSecs: Double,
+        finalStatsJson: String,
+        aecEnabled: Boolean,
+        alias: String,
+        server: String,
+        room: String
+    ): File? = withContext(Dispatchers.IO) {
+        try {
+            val debugDir = File(context.cacheDir, "wzp_debug")
+            val timestamp = SimpleDateFormat("yyyyMMdd_HHmmss", Locale.US).format(Date())
+            val zipFile = File(context.cacheDir, "wzp_debug_${timestamp}.zip")
+
+            ZipOutputStream(BufferedOutputStream(FileOutputStream(zipFile))).use { zos ->
+                // 1. Call metadata
+                val meta = buildString {
+                    appendLine("=== WZ Phone Debug Report ===")
+                    appendLine("Timestamp: $timestamp")
+                    appendLine("Alias: $alias")
+                    appendLine("Server: $server")
+                    appendLine("Room: $room")
+                    appendLine("Duration: ${"%.1f".format(callDurationSecs)}s")
+                    appendLine("AEC: ${if (aecEnabled) "ON" else "OFF"}")
+                    appendLine("Device: ${android.os.Build.MANUFACTURER} ${android.os.Build.MODEL}")
+                    appendLine("Android: ${android.os.Build.VERSION.RELEASE} (API ${android.os.Build.VERSION.SDK_INT})")
+                    appendLine()
+                    appendLine("=== Final Stats ===")
+                    appendLine(finalStatsJson)
+                }
+                addTextEntry(zos, "meta.txt", meta)
+
+                // 2. Logcat — WZP-related tags
+                val logcat = collectLogcat()
+                addTextEntry(zos, "logcat.txt", logcat)
+
+                // 3. Capture audio (mic) → WAV
+                val captureRaw = File(debugDir, "capture.pcm")
+                if (captureRaw.exists() && captureRaw.length() > 0) {
+                    addWavEntry(zos, "capture.wav", captureRaw)
+                    Log.i(TAG, "capture.pcm: ${captureRaw.length()} bytes -> WAV")
+                }
+
+                // 4. Playout audio (speaker) → WAV
+                val playoutRaw = File(debugDir, "playout.pcm")
+                if (playoutRaw.exists() && playoutRaw.length() > 0) {
+                    addWavEntry(zos, "playout.wav", playoutRaw)
+                    Log.i(TAG, "playout.pcm: ${playoutRaw.length()} bytes -> WAV")
+                }
+
+                // 5. RMS histogram CSV
+                val captureHist = File(debugDir, "capture_rms.csv")
+                if (captureHist.exists()) addFileEntry(zos, "capture_rms.csv", captureHist)
+                val playoutHist = File(debugDir, "playout_rms.csv")
+                if (playoutHist.exists()) addFileEntry(zos, "playout_rms.csv", playoutHist)
+            }
+
+            Log.i(TAG, "zip created: ${zipFile.length()} bytes (${zipFile.length() / 1024}KB)")
+
+            // Clean up raw debug files (keep zip)
+            debugDir.listFiles()?.forEach { it.delete() }
+
+            zipFile
+        } catch (e: Exception) {
+            Log.e(TAG, "debug report failed", e)
+            null
+        }
+    }
+
+    /** Clean up any leftover debug files from a previous session. */
+    fun prepareForCall() {
+        val debugDir = File(context.cacheDir, "wzp_debug")
+        if (debugDir.exists()) {
+            debugDir.listFiles()?.forEach { it.delete() }
+        }
+        debugDir.mkdirs()
+        // Also clean up old zip files
+        context.cacheDir.listFiles()?.filter { it.name.startsWith("wzp_debug_") }?.forEach { it.delete() }
+    }
+
+    private fun collectLogcat(): String {
+        return try {
+            val process = Runtime.getRuntime().exec(
+                arrayOf(
+                    "logcat", "-d",
+                    "-t", "5000",
+                    "--format", "threadtime"
+                )
+            )
+            val output = process.inputStream.bufferedReader().readText()
+            process.waitFor()
+            output.lines()
+                .filter { line ->
+                    line.contains("wzp", ignoreCase = true) ||
+                    line.contains("WzpEngine") ||
+                    line.contains("AudioPipeline") ||
+                    line.contains("WzpCall") ||
+                    line.contains("CallService") ||
+                    line.contains("AudioTrack") ||
+                    line.contains("AudioRecord") ||
+                    line.contains("AcousticEchoCanceler") ||
+                    line.contains("NoiseSuppressor") ||
+                    line.contains("FATAL") ||
+                    line.contains("ANR") ||
+                    line.contains("AudioFlinger") ||
+                    line.contains("DebugReporter") ||
+                    line.contains("QUIC") ||
+                    line.contains("quinn") ||
+                    line.contains("send task") ||
+                    line.contains("recv task") ||
+                    line.contains("send stats") ||
+                    line.contains("recv stats") ||
+                    line.contains("send_media") ||
+                    line.contains("FEC block") ||
+                    line.contains("recv gap") ||
+                    line.contains("frames_dropped") ||
+                    line.contains("opus")
+                }
+                .joinToString("\n")
+        } catch (e: Exception) {
+            "Failed to collect logcat: ${e.message}"
+        }
+    }
+
+    private fun addWavEntry(zos: ZipOutputStream, name: String, pcmFile: File) {
+        val dataSize = pcmFile.length().toInt()
+        val byteRate = SAMPLE_RATE * 1 * 16 / 8
+        val blockAlign = 1 * 16 / 8
+
+        zos.putNextEntry(ZipEntry(name))
+
+        // Write WAV header (44 bytes)
+        val header = ByteBuffer.allocate(44).order(ByteOrder.LITTLE_ENDIAN)
+        header.put("RIFF".toByteArray())
+        header.putInt(36 + dataSize)
+        header.put("WAVE".toByteArray())
+        header.put("fmt ".toByteArray())
+        header.putInt(16)
+        header.putShort(1)   // PCM
+        header.putShort(1)   // mono
+        header.putInt(SAMPLE_RATE)
+        header.putInt(byteRate)
+        header.putShort(blockAlign.toShort())
+        header.putShort(16)  // bits per sample
+        header.put("data".toByteArray())
+        header.putInt(dataSize)
+        zos.write(header.array())
+
+        // Stream PCM data directly (avoids loading entire file into memory)
+        FileInputStream(pcmFile).use { it.copyTo(zos) }
+        zos.closeEntry()
+    }
+
+    private fun addTextEntry(zos: ZipOutputStream, name: String, content: String) {
+        zos.putNextEntry(ZipEntry(name))
+        zos.write(content.toByteArray())
+        zos.closeEntry()
+    }
+
+    private fun addFileEntry(zos: ZipOutputStream, name: String, file: File) {
+        zos.putNextEntry(ZipEntry(name))
+        FileInputStream(file).use { it.copyTo(zos) }
+        zos.closeEntry()
+    }
+}

android/app/src/main/java/com/wzp/engine/CallStats.kt

@@ -0,0 +1,120 @@
+package com.wzp.engine
+
+import org.json.JSONArray
+import org.json.JSONObject
+
+/**
+ * Snapshot of call statistics, mirroring the Rust `CallStats` struct.
+ *
+ * Constructed from the JSON string returned by [WzpEngine.getStats].
+ */
+data class CallStats(
+    /** Current call state ordinal (see [CallStateConstants]). */
+    val state: Int = 0,
+    /** Call duration in seconds. */
+    val durationSecs: Double = 0.0,
+    /** Quality tier: 0 = Good, 1 = Degraded, 2 = Catastrophic. */
+    val qualityTier: Int = 0,
+    /** Observed packet loss percentage (0..100). */
+    val lossPct: Float = 0f,
+    /** Smoothed round-trip time in milliseconds. */
+    val rttMs: Int = 0,
+    /** Jitter in milliseconds. */
+    val jitterMs: Int = 0,
+    /** Current jitter buffer depth in packets. */
+    val jitterBufferDepth: Int = 0,
+    /** Total frames encoded since call start. */
+    val framesEncoded: Long = 0,
+    /** Total frames decoded since call start. */
+    val framesDecoded: Long = 0,
+    /** Number of playout underruns (buffer empty when audio was needed). */
+    val underruns: Long = 0,
+    /** Frames recovered by FEC. */
+    val fecRecovered: Long = 0,
+    /** Current mic audio level (RMS, 0-32767). */
+    val audioLevel: Int = 0,
+    /** Our current outgoing codec (e.g. "Opus24k"). */
+    val currentCodec: String = "",
+    /** Last seen incoming codec from peers. */
+    val peerCodec: String = "",
+    /** Whether auto quality mode is active. */
+    val autoMode: Boolean = false,
+    /** Number of participants in the room. */
+    val roomParticipantCount: Int = 0,
+    /** Participants in the room (fingerprint + optional alias). */
+    val roomParticipants: List<RoomMember> = emptyList(),
+    /** SAS verification code (4-digit, null if not in a call). */
+    val sasCode: Int? = null,
+    /** Incoming call ID (or "relay|room" for CallSetup). */
+    val incomingCallId: String? = null,
+    /** Incoming caller's fingerprint. */
+    val incomingCallerFp: String? = null,
+    /** Incoming caller's alias. */
+    val incomingCallerAlias: String? = null,
+) {
+    /** Human-readable quality label. */
+    val qualityLabel: String
+        get() = when (qualityTier) {
+            0 -> "Good"
+            1 -> "Degraded"
+            2 -> "Catastrophic"
+            else -> "Unknown"
+        }
+
+    companion object {
+        private fun parseParticipants(arr: JSONArray?): List<RoomMember> {
+            if (arr == null) return emptyList()
+            return (0 until arr.length()).map { i ->
+                val o = arr.getJSONObject(i)
+                RoomMember(
+                    fingerprint = o.optString("fingerprint", ""),
+                    alias = if (o.isNull("alias")) null else o.optString("alias", null),
+                    relayLabel = if (o.isNull("relay_label")) null else o.optString("relay_label", null)
+                )
+            }
+        }
+
+        /** Deserialise from the JSON string produced by the native engine. */
+        fun fromJson(json: String): CallStats {
+            return try {
+                val obj = JSONObject(json)
+                CallStats(
+                    state = obj.optInt("state", 0),
+                    durationSecs = obj.optDouble("duration_secs", 0.0),
+                    qualityTier = obj.optInt("quality_tier", 0),
+                    lossPct = obj.optDouble("loss_pct", 0.0).toFloat(),
+                    rttMs = obj.optInt("rtt_ms", 0),
+                    jitterMs = obj.optInt("jitter_ms", 0),
+                    jitterBufferDepth = obj.optInt("jitter_buffer_depth", 0),
+                    framesEncoded = obj.optLong("frames_encoded", 0),
+                    framesDecoded = obj.optLong("frames_decoded", 0),
+                    underruns = obj.optLong("underruns", 0),
+                    fecRecovered = obj.optLong("fec_recovered", 0),
+                    audioLevel = obj.optInt("audio_level", 0),
+                    currentCodec = obj.optString("current_codec", ""),
+                    peerCodec = obj.optString("peer_codec", ""),
+                    autoMode = obj.optBoolean("auto_mode", false),
+                    roomParticipantCount = obj.optInt("room_participant_count", 0),
+                    roomParticipants = parseParticipants(obj.optJSONArray("room_participants")),
+                    sasCode = if (obj.has("sas_code")) obj.optInt("sas_code") else null,
+                    incomingCallId = if (obj.isNull("incoming_call_id")) null else obj.optString("incoming_call_id", null),
+                    incomingCallerFp = if (obj.isNull("incoming_caller_fp")) null else obj.optString("incoming_caller_fp", null),
+                    incomingCallerAlias = if (obj.isNull("incoming_caller_alias")) null else obj.optString("incoming_caller_alias", null),
+                )
+            } catch (e: Exception) {
+                CallStats()
+            }
+        }
+    }
+}
+
+data class RoomMember(
+    val fingerprint: String,
+    val alias: String? = null,
+    val relayLabel: String? = null
+) {
+    /** Short display name: alias if set, otherwise first 8 chars of fingerprint. */
+    val displayName: String
+        get() = alias?.takeIf { it.isNotBlank() }
+            ?: fingerprint.take(8).ifEmpty { "unknown" }
+}

android/app/src/main/java/com/wzp/engine/WzpCallback.kt

@@ -0,0 +1,32 @@
+package com.wzp.engine
+
+/**
+ * Callback interface for VoIP engine events.
+ *
+ * All callbacks are invoked on the main/UI thread.
+ */
+interface WzpCallback {
+
+    /**
+     * Called when the call state changes.
+     *
+     * @param state one of [CallStateConstants]: IDLE(0), CONNECTING(1), ACTIVE(2),
+     *              RECONNECTING(3), CLOSED(4)
+     */
+    fun onCallStateChanged(state: Int)
+
+    /**
+     * Called when the network quality tier changes.
+     *
+     * @param tier 0 = Good, 1 = Degraded, 2 = Catastrophic
+     */
+    fun onQualityTierChanged(tier: Int)
+
+    /**
+     * Called when an error occurs in the native engine.
+     *
+     * @param code    numeric error code (negative)
+     * @param message human-readable description
+     */
+    fun onError(code: Int, message: String)
+}

android/app/src/main/java/com/wzp/engine/WzpEngine.kt

@@ -0,0 +1,225 @@
+package com.wzp.engine
+
+/**
+ * Native VoIP engine wrapper. Delegates all work to libwzp_android.so via JNI.
+ *
+ * Lifecycle:
+ * 1. Construct with a [WzpCallback]
+ * 2. Call [init] to create the native engine
+ * 3. Call [startCall] to begin a VoIP session
+ * 4. Use [setMute], [setSpeaker], [getStats], [forceProfile] during the call
+ * 5. Call [stopCall] to end the session
+ * 6. Call [destroy] when the engine is no longer needed
+ *
+ * Thread safety: all methods must be called from the same thread (typically main).
+ */
+class WzpEngine(private val callback: WzpCallback) {
+
+    /** Opaque pointer to the native EngineHandle. 0 means not initialised. */
+    private var nativeHandle: Long = 0L
+
+    /** Whether the engine has been initialised. */
+    val isInitialized: Boolean get() = nativeHandle != 0L
+
+    /** Create the native engine. Must be called before any other method. */
+    fun init() {
+        check(nativeHandle == 0L) { "Engine already initialized" }
+        nativeHandle = nativeInit()
+        check(nativeHandle != 0L) { "Native engine creation failed" }
+    }
+
+    /**
+     * Start a call.
+     *
+     * @param relayAddr relay server address (host:port)
+     * @param room      room identifier (used as QUIC SNI)
+     * @param seedHex   64-char hex-encoded 32-byte identity seed (empty = random)
+     * @param token     authentication token (empty = no auth)
+     * @param alias     display name sent to relay for room participant list
+     * @return 0 on success, negative error code on failure
+     */
+    /**
+     * @param profile 0 = Opus GOOD, 1 = Opus DEGRADED, 2 = Codec2 CATASTROPHIC
+     */
+    fun startCall(relayAddr: String, room: String, seedHex: String = "", token: String = "", alias: String = "", profile: Int = 0): Int {
+        check(nativeHandle != 0L) { "Engine not initialized" }
+        val result = nativeStartCall(nativeHandle, relayAddr, room, seedHex, token, alias, profile)
+        if (result == 0) {
+            callback.onCallStateChanged(CallStateConstants.CONNECTING)
+        } else {
+            callback.onError(result, "Failed to start call")
+        }
+        return result
+    }
+
+    /** Stop the active call. Safe to call when no call is active. */
+    @Synchronized
+    fun stopCall() {
+        if (nativeHandle != 0L) {
+            nativeStopCall(nativeHandle)
+            callback.onCallStateChanged(CallStateConstants.CLOSED)
+        }
+    }
+
+    /** Mute or unmute the microphone. */
+    fun setMute(muted: Boolean) {
+        if (nativeHandle != 0L) nativeSetMute(nativeHandle, muted)
+    }
+
+    /** Enable or disable loudspeaker mode. */
+    fun setSpeaker(speaker: Boolean) {
+        if (nativeHandle != 0L) nativeSetSpeaker(nativeHandle, speaker)
+    }
+
+
+    /**
+     * Get current call statistics as a JSON string.
+     *
+     * @return JSON-serialised [CallStats], or `"{}"` if the engine is not initialised.
+     */
+    @Synchronized
+    fun getStats(): String {
+        if (nativeHandle == 0L) return "{}"
+        return try {
+            nativeGetStats(nativeHandle) ?: "{}"
+        } catch (_: Exception) {
+            "{}"
+        }
+    }
+
+    /**
+     * Force a quality profile, overriding adaptive selection.
+     *
+     * @param profile 0 = GOOD, 1 = DEGRADED, 2 = CATASTROPHIC
+     */
+    fun forceProfile(profile: Int) {
+        if (nativeHandle != 0L) nativeForceProfile(nativeHandle, profile)
+    }
+
+    /** Destroy the native engine and free all resources. The instance must not be reused. */
+    @Synchronized
+    fun destroy() {
+        if (nativeHandle != 0L) {
+            nativeDestroy(nativeHandle)
+            nativeHandle = 0L
+        }
+    }
+
+    /**
+     * Write captured PCM samples into the engine's capture ring buffer.
+     * Called from the AudioRecord capture thread.
+     */
+    fun writeAudio(pcm: ShortArray): Int {
+        if (nativeHandle == 0L) return 0
+        return nativeWriteAudio(nativeHandle, pcm)
+    }
+
+    /**
+     * Read decoded PCM samples from the engine's playout ring buffer.
+     * Called from the AudioTrack playout thread.
+     */
+    fun readAudio(pcm: ShortArray): Int {
+        if (nativeHandle == 0L) return 0
+        return nativeReadAudio(nativeHandle, pcm)
+    }
+
+    /**
+     * Write captured PCM from a DirectByteBuffer — zero JNI array copy.
+     * The buffer must be a direct ByteBuffer with native byte order containing i16 samples.
+     * Called from the AudioRecord capture thread.
+     */
+    fun writeAudioDirect(buffer: java.nio.ByteBuffer, sampleCount: Int): Int {
+        if (nativeHandle == 0L) return 0
+        return nativeWriteAudioDirect(nativeHandle, buffer, sampleCount)
+    }
+
+    /**
+     * Read decoded PCM into a DirectByteBuffer — zero JNI array copy.
+     * The buffer must be a direct ByteBuffer with native byte order.
+     * Called from the AudioTrack playout thread.
+     */
+    fun readAudioDirect(buffer: java.nio.ByteBuffer, maxSamples: Int): Int {
+        if (nativeHandle == 0L) return 0
+        return nativeReadAudioDirect(nativeHandle, buffer, maxSamples)
+    }
+
+    // -- JNI native methods --------------------------------------------------
+
+    private external fun nativeInit(): Long
+    private external fun nativeStartCall(
+        handle: Long, relay: String, room: String, seed: String, token: String, alias: String, profile: Int
+    ): Int
+    private external fun nativeStopCall(handle: Long)
+    private external fun nativeSetMute(handle: Long, muted: Boolean)
+    private external fun nativeSetSpeaker(handle: Long, speaker: Boolean)
+    private external fun nativeGetStats(handle: Long): String?
+    private external fun nativeForceProfile(handle: Long, profile: Int)
+    private external fun nativeWriteAudio(handle: Long, pcm: ShortArray): Int
+    private external fun nativeReadAudio(handle: Long, pcm: ShortArray): Int
+    private external fun nativeWriteAudioDirect(handle: Long, buffer: java.nio.ByteBuffer, sampleCount: Int): Int
+    private external fun nativeReadAudioDirect(handle: Long, buffer: java.nio.ByteBuffer, maxSamples: Int): Int
+    private external fun nativeDestroy(handle: Long)
+    private external fun nativePingRelay(handle: Long, relay: String): String?
+    private external fun nativeStartSignaling(handle: Long, relay: String, seed: String, token: String, alias: String): Int
+    private external fun nativePlaceCall(handle: Long, targetFp: String): Int
+    private external fun nativeAnswerCall(handle: Long, callId: String, mode: Int): Int
+
+    /**
+     * Ping a relay server. Requires engine to be initialized.
+     * Returns JSON `{"rtt_ms":N,"server_fingerprint":"hex"}` or null.
+     */
+    fun pingRelay(address: String): String? {
+        if (nativeHandle == 0L) return null
+        return nativePingRelay(nativeHandle, address)
+    }
+
+    /**
+     * Start persistent signaling connection for direct 1:1 calls.
+     * The engine registers on the relay and listens for incoming calls.
+     * Call state updates are available via [getStats].
+     *
+     * @return 0 on success, -1 on error
+     */
+    fun startSignaling(relay: String, seed: String = "", token: String = "", alias: String = ""): Int {
+        check(nativeHandle != 0L) { "Engine not initialized" }
+        return nativeStartSignaling(nativeHandle, relay, seed, token, alias)
+    }
+
+    /**
+     * Place a direct call to a peer by fingerprint.
+     * Requires [startSignaling] to have been called first.
+     *
+     * @return 0 on success, -1 on error
+     */
+    fun placeCall(targetFingerprint: String): Int {
+        check(nativeHandle != 0L) { "Engine not initialized" }
+        return nativePlaceCall(nativeHandle, targetFingerprint)
+    }
+
+    /**
+     * Answer an incoming direct call.
+     *
+     * @param callId The call ID from the incoming call (available in stats.incoming_call_id)
+     * @param mode 0=Reject, 1=AcceptTrusted (P2P in Phase 2), 2=AcceptGeneric (relay-mediated)
+     * @return 0 on success, -1 on error
+     */
+    fun answerCall(callId: String, mode: Int = 2): Int {
+        check(nativeHandle != 0L) { "Engine not initialized" }
+        return nativeAnswerCall(nativeHandle, callId, mode)
+    }
+
+    companion object {
+        init {
+            System.loadLibrary("wzp_android")
+        }
+    }
+}
+
+/** Integer constants matching the Rust [CallState] enum ordinals. */
+object CallStateConstants {
+    const val IDLE = 0
+    const val CONNECTING = 1
+    const val ACTIVE = 2
+    const val RECONNECTING = 3
+    const val CLOSED = 4
+}

android/app/src/main/java/com/wzp/net/RelayPinger.kt

@@ -0,0 +1,12 @@
+package com.wzp.net
+
+// Relay pinging is now done via WzpEngine.pingRelay() (instance method).
+// This file kept for the data class only.
+
+object RelayPinger {
+    data class PingResult(
+        val rttMs: Int,
+        val reachable: Boolean,
+        val serverFingerprint: String = "",
+    )
+}

android/app/src/main/java/com/wzp/service/CallService.kt

@@ -0,0 +1,172 @@
+package com.wzp.service
+
+import android.app.Notification
+import android.app.PendingIntent
+import android.app.Service
+import android.content.Context
+import android.content.Intent
+import android.media.AudioManager
+import android.net.wifi.WifiManager
+import android.os.IBinder
+import android.os.PowerManager
+import androidx.core.app.NotificationCompat
+import com.wzp.WzpApplication
+import com.wzp.ui.call.CallActivity
+
+/**
+ * Foreground service that keeps the VoIP call alive when the app is backgrounded.
+ *
+ * Responsibilities:
+ * - Shows a persistent notification during the call
+ * - Acquires a partial wake lock so the CPU stays on
+ * - Acquires a Wi-Fi lock to prevent Wi-Fi from going to sleep
+ * - Sets [AudioManager] mode to [AudioManager.MODE_IN_COMMUNICATION]
+ * - Releases all resources when the call ends
+ */
+class CallService : Service() {
+
+    private var wakeLock: PowerManager.WakeLock? = null
+    private var wifiLock: WifiManager.WifiLock? = null
+    private var previousAudioMode: Int = AudioManager.MODE_NORMAL
+
+    // -- Lifecycle ------------------------------------------------------------
+
+    override fun onCreate() {
+        super.onCreate()
+        acquireWakeLock()
+        acquireWifiLock()
+        setAudioMode()
+    }
+
+    override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
+        when (intent?.action) {
+            ACTION_STOP -> {
+                onStopFromNotification?.invoke()
+                stopSelf()
+                return START_NOT_STICKY
+            }
+        }
+
+        startForeground(NOTIFICATION_ID, buildNotification())
+        return START_STICKY
+    }
+
+    override fun onDestroy() {
+        restoreAudioMode()
+        releaseWifiLock()
+        releaseWakeLock()
+        super.onDestroy()
+    }
+
+    override fun onBind(intent: Intent?): IBinder? = null
+
+    // -- Notification ---------------------------------------------------------
+
+    private fun buildNotification(): Notification {
+        // Tapping the notification returns to the call screen
+        val contentIntent = PendingIntent.getActivity(
+            this,
+            0,
+            Intent(this, CallActivity::class.java).apply {
+                flags = Intent.FLAG_ACTIVITY_SINGLE_TOP
+            },
+            PendingIntent.FLAG_IMMUTABLE or PendingIntent.FLAG_UPDATE_CURRENT
+        )
+
+        // "End call" action button
+        val stopIntent = PendingIntent.getService(
+            this,
+            1,
+            Intent(this, CallService::class.java).apply { action = ACTION_STOP },
+            PendingIntent.FLAG_IMMUTABLE or PendingIntent.FLAG_UPDATE_CURRENT
+        )
+
+        return NotificationCompat.Builder(this, WzpApplication.CHANNEL_ID)
+            .setContentTitle("WZ Phone")
+            .setContentText("Call in progress")
+            .setSmallIcon(android.R.drawable.ic_menu_call)
+            .setOngoing(true)
+            .setContentIntent(contentIntent)
+            .addAction(android.R.drawable.ic_menu_close_clear_cancel, "End Call", stopIntent)
+            .setCategory(NotificationCompat.CATEGORY_CALL)
+            .setPriority(NotificationCompat.PRIORITY_LOW)
+            .build()
+    }
+
+    // -- Wake lock ------------------------------------------------------------
+
+    private fun acquireWakeLock() {
+        val pm = getSystemService(Context.POWER_SERVICE) as PowerManager
+        wakeLock = pm.newWakeLock(
+            PowerManager.PARTIAL_WAKE_LOCK,
+            "wzp:call_wake_lock"
+        ).apply {
+            acquire(MAX_CALL_DURATION_MS)
+        }
+    }
+
+    private fun releaseWakeLock() {
+        wakeLock?.let {
+            if (it.isHeld) it.release()
+        }
+        wakeLock = null
+    }
+
+    // -- Wi-Fi lock -----------------------------------------------------------
+
+    @Suppress("DEPRECATION")
+    private fun acquireWifiLock() {
+        val wm = applicationContext.getSystemService(Context.WIFI_SERVICE) as WifiManager
+        wifiLock = wm.createWifiLock(
+            WifiManager.WIFI_MODE_FULL_HIGH_PERF,
+            "wzp:call_wifi_lock"
+        ).apply {
+            acquire()
+        }
+    }
+
+    private fun releaseWifiLock() {
+        wifiLock?.let {
+            if (it.isHeld) it.release()
+        }
+        wifiLock = null
+    }
+
+    // -- Audio mode -----------------------------------------------------------
+
+    private fun setAudioMode() {
+        val am = getSystemService(Context.AUDIO_SERVICE) as AudioManager
+        previousAudioMode = am.mode
+        am.mode = AudioManager.MODE_IN_COMMUNICATION
+    }
+
+    private fun restoreAudioMode() {
+        val am = getSystemService(Context.AUDIO_SERVICE) as AudioManager
+        am.mode = previousAudioMode
+    }
+
+    // -- Static helpers -------------------------------------------------------
+
+    companion object {
+        private const val NOTIFICATION_ID = 1001
+        private const val ACTION_STOP = "com.wzp.service.STOP"
+        private const val MAX_CALL_DURATION_MS = 4L * 60 * 60 * 1000 // 4 hours
+
+        /** Called when the user taps "End Call" in the notification. */
+        var onStopFromNotification: (() -> Unit)? = null
+
+        /** Start the foreground call service. */
+        fun start(context: Context) {
+            val intent = Intent(context, CallService::class.java)
+            context.startForegroundService(intent)
+        }
+
+        /** Stop the foreground call service. */
+        fun stop(context: Context) {
+            val intent = Intent(context, CallService::class.java).apply {
+                action = ACTION_STOP
+            }
+            context.startService(intent)
+        }
+    }
+}

android/app/src/main/java/com/wzp/ui/call/CallActivity.kt

@@ -0,0 +1,149 @@
+package com.wzp.ui.call
+
+import android.Manifest
+import android.content.Intent
+import android.content.pm.PackageManager
+import android.os.Bundle
+import android.util.Log
+import android.widget.Toast
+import androidx.activity.ComponentActivity
+import androidx.activity.compose.setContent
+import androidx.activity.result.contract.ActivityResultContracts
+import androidx.activity.viewModels
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.darkColorScheme
+import androidx.compose.material3.dynamicDarkColorScheme
+import androidx.compose.material3.dynamicLightColorScheme
+import androidx.compose.material3.lightColorScheme
+import androidx.compose.foundation.isSystemInDarkTheme
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.platform.LocalContext
+import androidx.core.content.ContextCompat
+import androidx.core.content.FileProvider
+import androidx.lifecycle.Lifecycle
+import androidx.lifecycle.lifecycleScope
+import androidx.lifecycle.repeatOnLifecycle
+import com.wzp.ui.settings.SettingsScreen
+import kotlinx.coroutines.launch
+
+/**
+ * Main activity hosting the in-call Compose UI.
+ *
+ * Call lifecycle (wake lock, Wi-Fi lock, audio mode, notification)
+ * is managed by [com.wzp.service.CallService] foreground service.
+ */
+class CallActivity : ComponentActivity() {
+
+    companion object {
+        private const val TAG = "CallActivity"
+    }
+
+    private val viewModel: CallViewModel by viewModels()
+
+    private val audioPermissionLauncher = registerForActivityResult(
+        ActivityResultContracts.RequestPermission()
+    ) { granted ->
+        if (!granted) {
+            Toast.makeText(this, "Microphone permission is required for calls", Toast.LENGTH_LONG).show()
+        }
+    }
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+
+        viewModel.setContext(this)
+
+        setContent {
+            WzpTheme {
+                var showSettings by remember { mutableStateOf(false) }
+                if (showSettings) {
+                    SettingsScreen(
+                        viewModel = viewModel,
+                        onBack = { showSettings = false }
+                    )
+                } else {
+                    InCallScreen(
+                        viewModel = viewModel,
+                        onHangUp = { viewModel.stopCall() },
+                        onOpenSettings = { showSettings = true }
+                    )
+                }
+            }
+        }
+
+        if (ContextCompat.checkSelfPermission(this, Manifest.permission.RECORD_AUDIO)
+            != PackageManager.PERMISSION_GRANTED
+        ) {
+            audioPermissionLauncher.launch(Manifest.permission.RECORD_AUDIO)
+        }
+
+        // Watch for debug zip ready → launch email intent
+        lifecycleScope.launch {
+            repeatOnLifecycle(Lifecycle.State.STARTED) {
+                viewModel.debugZipReady.collect { zipFile ->
+                    if (zipFile != null && zipFile.exists()) {
+                        Log.i(TAG, "debug zip ready: ${zipFile.absolutePath} (${zipFile.length()} bytes)")
+                        launchEmailIntent(zipFile)
+                        viewModel.onDebugReportSent()
+                    }
+                }
+            }
+        }
+    }
+
+    private fun launchEmailIntent(zipFile: java.io.File) {
+        try {
+            val authority = "${applicationContext.packageName}.fileprovider"
+            Log.i(TAG, "FileProvider authority: $authority, file: ${zipFile.absolutePath}")
+            val uri = FileProvider.getUriForFile(this, authority, zipFile)
+            Log.i(TAG, "FileProvider URI: $uri")
+
+            val intent = Intent(Intent.ACTION_SEND).apply {
+                type = "message/rfc822"
+                putExtra(Intent.EXTRA_EMAIL, arrayOf("manwefarm@gmail.com"))
+                putExtra(Intent.EXTRA_SUBJECT, "WZ Phone Debug Report - ${zipFile.name}")
+                putExtra(
+                    Intent.EXTRA_TEXT,
+                    "Debug report attached.\n\nContains: call recordings (WAV), RMS histograms (CSV), logcat, stats."
+                )
+                putExtra(Intent.EXTRA_STREAM, uri)
+                addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION)
+            }
+            startActivity(Intent.createChooser(intent, "Send debug report"))
+            Log.i(TAG, "email intent launched")
+        } catch (e: Exception) {
+            Log.e(TAG, "email intent failed", e)
+            Toast.makeText(this, "Failed to launch email: ${e.message}", Toast.LENGTH_LONG).show()
+        }
+    }
+
+    override fun onDestroy() {
+        super.onDestroy()
+        if (isFinishing) {
+            viewModel.stopCall()
+        }
+    }
+}
+
+@Composable
+fun WzpTheme(content: @Composable () -> Unit) {
+    val darkTheme = isSystemInDarkTheme()
+    val context = LocalContext.current
+
+    val colorScheme = when {
+        android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.S -> {
+            if (darkTheme) dynamicDarkColorScheme(context) else dynamicLightColorScheme(context)
+        }
+        darkTheme -> darkColorScheme()
+        else -> lightColorScheme()
+    }
+
+    MaterialTheme(
+        colorScheme = colorScheme,
+        content = content
+    )
+}

android/app/src/main/java/com/wzp/ui/call/CallViewModel.kt

@@ -0,0 +1,732 @@
+package com.wzp.ui.call
+
+import android.content.Context
+import android.util.Log
+import androidx.lifecycle.ViewModel
+import androidx.lifecycle.viewModelScope
+import com.wzp.audio.AudioPipeline
+import com.wzp.audio.AudioRouteManager
+import com.wzp.data.SettingsRepository
+import com.wzp.debug.DebugReporter
+import com.wzp.engine.CallStats
+import com.wzp.service.CallService
+import com.wzp.engine.WzpCallback
+import com.wzp.engine.WzpEngine
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+import kotlinx.coroutines.isActive
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.withContext
+import org.json.JSONObject
+import java.io.File
+import java.net.Inet4Address
+import java.net.Inet6Address
+import java.net.InetAddress
+
+data class ServerEntry(val address: String, val label: String)
+
+data class PingResult(
+    val rttMs: Int,
+    val serverFingerprint: String = "",
+    val reachable: Boolean = rttMs > 0,
+)
+
+enum class LockStatus { UNKNOWN, OFFLINE, NEW, VERIFIED, CHANGED }
+
+class CallViewModel : ViewModel(), WzpCallback {
+
+    private var engine: WzpEngine? = null
+    private var engineInitialized = false
+    private var audioPipeline: AudioPipeline? = null
+    private var audioRouteManager: AudioRouteManager? = null
+    private var audioStarted = false
+    private var appContext: Context? = null
+    private var settings: SettingsRepository? = null
+    private var debugReporter: DebugReporter? = null
+    private var lastStatsJson: String = "{}"
+    private var lastCallDuration: Double = 0.0
+    private var lastCallServer: String = ""
+
+    private val _callState = MutableStateFlow(0)
+    val callState: StateFlow<Int> get() = _callState.asStateFlow()
+
+    private val _isMuted = MutableStateFlow(false)
+    val isMuted: StateFlow<Boolean> = _isMuted.asStateFlow()
+
+    private val _isSpeaker = MutableStateFlow(false)
+    val isSpeaker: StateFlow<Boolean> = _isSpeaker.asStateFlow()
+
+    private val _stats = MutableStateFlow(CallStats())
+    val stats: StateFlow<CallStats> = _stats.asStateFlow()
+
+    private val _qualityTier = MutableStateFlow(0)
+    val qualityTier: StateFlow<Int> = _qualityTier.asStateFlow()
+
+    private val _errorMessage = MutableStateFlow<String?>(null)
+    val errorMessage: StateFlow<String?> = _errorMessage.asStateFlow()
+
+    private val _roomName = MutableStateFlow(DEFAULT_ROOM)
+    val roomName: StateFlow<String> = _roomName.asStateFlow()
+
+    private val _selectedServer = MutableStateFlow(0)
+    val selectedServer: StateFlow<Int> = _selectedServer.asStateFlow()
+
+    private val _servers = MutableStateFlow(DEFAULT_SERVERS.toList())
+    val servers: StateFlow<List<ServerEntry>> = _servers.asStateFlow()
+
+    private val _preferIPv6 = MutableStateFlow(false)
+    val preferIPv6: StateFlow<Boolean> = _preferIPv6.asStateFlow()
+
+    private val _recentRooms = MutableStateFlow<List<com.wzp.data.SettingsRepository.RecentRoom>>(emptyList())
+    val recentRooms: StateFlow<List<com.wzp.data.SettingsRepository.RecentRoom>> = _recentRooms.asStateFlow()
+
+    /** Ping results keyed by server address. */
+    private val _pingResults = MutableStateFlow<Map<String, PingResult>>(emptyMap())
+    val pingResults: StateFlow<Map<String, PingResult>> = _pingResults.asStateFlow()
+
+    /** Known server fingerprints (TOFU). */
+    private val _knownFingerprints = MutableStateFlow<Map<String, String>>(emptyMap())
+
+    private val _playoutGainDb = MutableStateFlow(0f)
+    val playoutGainDb: StateFlow<Float> = _playoutGainDb.asStateFlow()
+
+    private val _captureGainDb = MutableStateFlow(0f)
+    val captureGainDb: StateFlow<Float> = _captureGainDb.asStateFlow()
+
+    private val _alias = MutableStateFlow("")
+    val alias: StateFlow<String> = _alias.asStateFlow()
+
+    private val _seedHex = MutableStateFlow("")
+    val seedHex: StateFlow<String> = _seedHex.asStateFlow()
+
+    private val _aecEnabled = MutableStateFlow(true)
+    val aecEnabled: StateFlow<Boolean> = _aecEnabled.asStateFlow()
+
+    private val _debugRecording = MutableStateFlow(false)
+    val debugRecording: StateFlow<Boolean> = _debugRecording.asStateFlow()
+
+    // Quality profile index (matches JNI bridge profile_from_int)
+    private val _codecChoice = MutableStateFlow(0)
+    val codecChoice: StateFlow<Int> = _codecChoice.asStateFlow()
+
+    /** Key-change warning dialog state. */
+    data class KeyWarningInfo(val address: String, val oldFp: String, val newFp: String)
+    private val _keyWarning = MutableStateFlow<KeyWarningInfo?>(null)
+    val keyWarning: StateFlow<KeyWarningInfo?> = _keyWarning.asStateFlow()
+
+    /** True when a call just ended and debug report can be sent. */
+    private val _debugReportAvailable = MutableStateFlow(false)
+    val debugReportAvailable: StateFlow<Boolean> = _debugReportAvailable.asStateFlow()
+
+    /** Status: null=idle, "Preparing..."=in progress, "ready"=zip ready, "Error:..."=failed */
+    private val _debugReportStatus = MutableStateFlow<String?>(null)
+    val debugReportStatus: StateFlow<String?> = _debugReportStatus.asStateFlow()
+
+    /** The zip file ready to be emailed. Set by sendDebugReport, consumed by Activity. */
+    private val _debugZipReady = MutableStateFlow<File?>(null)
+    val debugZipReady: StateFlow<File?> = _debugZipReady.asStateFlow()
+
+    private var statsJob: Job? = null
+
+    // ── Direct calling state ──
+    /** 0=room mode, 1=direct call mode */
+    private val _callMode = MutableStateFlow(0)
+    val callMode: StateFlow<Int> = _callMode.asStateFlow()
+
+    /** Target fingerprint for direct call */
+    private val _targetFingerprint = MutableStateFlow("")
+    val targetFingerprint: StateFlow<String> = _targetFingerprint.asStateFlow()
+
+    /** Signal connection state: 0=idle, 5=registered, 6=ringing, 7=incoming */
+    private val _signalState = MutableStateFlow(0)
+    val signalState: StateFlow<Int> = _signalState.asStateFlow()
+
+    /** Incoming call info */
+    private val _incomingCallId = MutableStateFlow<String?>(null)
+    val incomingCallId: StateFlow<String?> = _incomingCallId.asStateFlow()
+
+    private val _incomingCallerFp = MutableStateFlow<String?>(null)
+    val incomingCallerFp: StateFlow<String?> = _incomingCallerFp.asStateFlow()
+
+    private val _incomingCallerAlias = MutableStateFlow<String?>(null)
+    val incomingCallerAlias: StateFlow<String?> = _incomingCallerAlias.asStateFlow()
+
+    fun setCallMode(mode: Int) { _callMode.value = mode }
+    fun setTargetFingerprint(fp: String) { _targetFingerprint.value = fp }
+
+    /** Register on relay for direct calls */
+    fun registerForCalls() {
+        if (engine == null) {
+            engine = WzpEngine(this).also { it.init() }
+        }
+        val serverIdx = _selectedServer.value
+        val serverList = _servers.value
+        if (serverIdx >= serverList.size) return
+
+        val relay = serverList[serverIdx].address
+        val seed = _seedHex.value
+        val alias = _alias.value
+
+        viewModelScope.launch(Dispatchers.IO) {
+            val resolvedRelay = resolveToIp(relay) ?: relay
+            val result = engine?.startSignaling(resolvedRelay, seed, "", alias)
+            if (result == 0) {
+                _signalState.value = 5 // Registered
+                startStatsPolling()
+            } else {
+                _errorMessage.value = "Failed to register on relay"
+            }
+        }
+    }
+
+    /** Place a direct call to the target fingerprint */
+    fun placeDirectCall() {
+        val target = _targetFingerprint.value.trim()
+        if (target.isEmpty()) {
+            _errorMessage.value = "Enter a fingerprint to call"
+            return
+        }
+        engine?.placeCall(target)
+        _signalState.value = 6 // Ringing
+    }
+
+    /** Answer an incoming direct call */
+    fun answerIncomingCall(mode: Int = 2) {
+        val callId = _incomingCallId.value ?: return
+        engine?.answerCall(callId, mode)
+    }
+
+    /** Reject an incoming direct call */
+    fun rejectIncomingCall() {
+        val callId = _incomingCallId.value ?: return
+        engine?.answerCall(callId, 0) // 0 = Reject
+        _signalState.value = 5 // Back to registered
+        _incomingCallId.value = null
+        _incomingCallerFp.value = null
+        _incomingCallerAlias.value = null
+    }
+
+    companion object {
+        private const val TAG = "WzpCall"
+        val DEFAULT_SERVERS = listOf(
+            ServerEntry("172.16.81.175:4433", "LAN (172.16.81.175)"),
+            ServerEntry("193.180.213.68:4433", "Pangolin (IP)"),
+        )
+        const val DEFAULT_ROOM = "general"
+    }
+
+    fun setContext(context: Context) {
+        val appCtx = context.applicationContext
+        appContext = appCtx
+        if (audioPipeline == null) {
+            audioPipeline = AudioPipeline(appCtx)
+        }
+        if (audioRouteManager == null) {
+            audioRouteManager = AudioRouteManager(appCtx)
+        }
+        if (debugReporter == null) {
+            debugReporter = DebugReporter(appCtx)
+        }
+        if (settings == null) {
+            settings = SettingsRepository(appCtx)
+            loadSettings()
+        }
+    }
+
+    private fun loadSettings() {
+        val s = settings ?: return
+        s.loadServers()?.let { saved ->
+            if (saved.isNotEmpty()) _servers.value = saved
+        }
+        _selectedServer.value = s.loadSelectedServer().coerceIn(0, _servers.value.lastIndex)
+        _roomName.value = s.loadRoom()
+        _alias.value = s.getOrCreateAlias()
+        _preferIPv6.value = s.loadPreferIPv6()
+        _playoutGainDb.value = s.loadPlayoutGain()
+        _captureGainDb.value = s.loadCaptureGain()
+        _seedHex.value = s.getOrCreateSeedHex()
+        _aecEnabled.value = s.loadAecEnabled()
+        _debugRecording.value = s.loadDebugRecording()
+        _codecChoice.value = s.loadCodecChoice()
+        _recentRooms.value = s.loadRecentRooms()
+    }
+
+    fun selectServer(index: Int) {
+        if (index in _servers.value.indices) {
+            _selectedServer.value = index
+            settings?.saveSelectedServer(index)
+        }
+    }
+
+    fun setPreferIPv6(prefer: Boolean) {
+        _preferIPv6.value = prefer
+        settings?.savePreferIPv6(prefer)
+    }
+
+    fun addServer(hostPort: String, label: String) {
+        val current = _servers.value.toMutableList()
+        current.add(ServerEntry(hostPort, label))
+        _servers.value = current
+        settings?.saveServers(current)
+    }
+
+    fun removeServer(index: Int) {
+        if (index < DEFAULT_SERVERS.size) return // don't remove built-in servers
+        val current = _servers.value.toMutableList()
+        if (index in current.indices) {
+            current.removeAt(index)
+            _servers.value = current
+            if (_selectedServer.value >= current.size) {
+                _selectedServer.value = 0
+            }
+            settings?.saveServers(current)
+            settings?.saveSelectedServer(_selectedServer.value)
+        }
+    }
+
+    /** Batch-apply servers and selection from Settings draft state. */
+    fun applyServers(servers: List<ServerEntry>, selected: Int) {
+        _servers.value = servers
+        _selectedServer.value = selected.coerceIn(0, servers.lastIndex)
+        settings?.saveServers(servers)
+        settings?.saveSelectedServer(_selectedServer.value)
+    }
+
+    /**
+     * Ping all servers via native QUIC. Requires engine to be initialized.
+     * Creates engine if needed, pings, keeps engine alive for subsequent Connect.
+     */
+    fun pingAllServers() {
+        viewModelScope.launch {
+            // Ensure engine exists
+            if (engine == null || engine?.isInitialized != true) {
+                try {
+                    engine = WzpEngine(this@CallViewModel).also { it.init() }
+                    engineInitialized = true
+                } catch (e: Exception) {
+                    Log.w(TAG, "engine init for ping failed: $e")
+                    return@launch
+                }
+            }
+            val eng = engine ?: return@launch
+
+            val results = mutableMapOf<String, PingResult>()
+            val known = mutableMapOf<String, String>()
+            _servers.value.forEach { server ->
+                val json = withContext(Dispatchers.IO) {
+                    eng.pingRelay(server.address)
+                }
+                if (json != null) {
+                    try {
+                        val obj = JSONObject(json)
+                        val rtt = obj.getInt("rtt_ms")
+                        val fp = obj.optString("server_fingerprint", "")
+                        results[server.address] = PingResult(rttMs = rtt, serverFingerprint = fp)
+                        // TOFU
+                        if (fp.isNotEmpty()) {
+                            val saved = settings?.loadServerFingerprint(server.address)
+                            if (saved == null) settings?.saveServerFingerprint(server.address, fp)
+                            known[server.address] = saved ?: fp
+                        }
+                    } catch (_: Exception) {}
+                }
+            }
+            _pingResults.value = results
+            _knownFingerprints.value = known
+        }
+    }
+
+    /** Load saved TOFU fingerprints. */
+    fun loadSavedFingerprints() {
+        val known = mutableMapOf<String, String>()
+        _servers.value.forEach { server ->
+            settings?.loadServerFingerprint(server.address)?.let {
+                known[server.address] = it
+            }
+        }
+        _knownFingerprints.value = known
+    }
+
+    /** Get lock status for a server. */
+    fun lockStatus(address: String): LockStatus {
+        val pr = _pingResults.value[address] ?: return LockStatus.UNKNOWN
+        if (!pr.reachable) return LockStatus.OFFLINE
+        val known = _knownFingerprints.value[address] ?: return LockStatus.NEW
+        if (pr.serverFingerprint.isEmpty()) return LockStatus.NEW
+        return if (pr.serverFingerprint == known) LockStatus.VERIFIED else LockStatus.CHANGED
+    }
+
+    fun setRoomName(name: String) {
+        _roomName.value = name
+        settings?.saveRoom(name)
+    }
+
+    fun setPlayoutGainDb(db: Float) {
+        _playoutGainDb.value = db
+        audioPipeline?.playoutGainDb = db
+        settings?.savePlayoutGain(db)
+    }
+
+    fun setCaptureGainDb(db: Float) {
+        _captureGainDb.value = db
+        audioPipeline?.captureGainDb = db
+        settings?.saveCaptureGain(db)
+    }
+
+    fun setAlias(alias: String) {
+        _alias.value = alias
+        settings?.saveAlias(alias)
+    }
+
+    fun restoreSeed(hex: String) {
+        _seedHex.value = hex
+        settings?.saveSeedHex(hex)
+    }
+
+    fun setAecEnabled(enabled: Boolean) {
+        _aecEnabled.value = enabled
+        settings?.saveAecEnabled(enabled)
+    }
+
+    fun setDebugRecording(enabled: Boolean) {
+        _debugRecording.value = enabled
+        settings?.saveDebugRecording(enabled)
+    }
+
+    fun setCodecChoice(choice: Int) {
+        _codecChoice.value = choice
+        settings?.saveCodecChoice(choice)
+    }
+
+    /**
+     * Resolve DNS hostname to IP address on the Kotlin/Android side,
+     * since Rust's DNS resolution may not work on Android.
+     * Returns "ip:port" string.
+     */
+    private fun resolveToIp(hostPort: String): String {
+        val parts = hostPort.split(":")
+        if (parts.size != 2) return hostPort
+        val host = parts[0]
+        val port = parts[1]
+
+        // Already an IP address — return as-is
+        if (host.matches(Regex("""\d+\.\d+\.\d+\.\d+"""))) return hostPort
+        if (host.contains(":")) return hostPort // IPv6 literal
+
+        return try {
+            val addresses = InetAddress.getAllByName(host)
+            val preferV6 = _preferIPv6.value
+            val picked = if (preferV6) {
+                addresses.firstOrNull { it is Inet6Address } ?: addresses.firstOrNull { it is Inet4Address }
+            } else {
+                addresses.firstOrNull { it is Inet4Address } ?: addresses.firstOrNull { it is Inet6Address }
+            }
+            if (picked != null) {
+                val ip = picked.hostAddress ?: host
+                val formatted = if (picked is Inet6Address) "[$ip]:$port" else "$ip:$port"
+                formatted
+            } else {
+                hostPort
+            }
+        } catch (_: Exception) {
+            hostPort // resolution failed — pass through and let Rust try
+        }
+    }
+
+    /** Tear down engine and audio. Pass stopService=true to also stop the foreground service. */
+    private fun teardown(stopService: Boolean = true) {
+        Log.i(TAG, "teardown: stopping audio, stopService=$stopService")
+        val hadCall = audioStarted
+        CallService.onStopFromNotification = null
+        stopAudio()             // sets running=false (non-blocking)
+        stopStatsPolling()
+
+        // Wait for audio threads to exit their loops before destroying the engine.
+        // This guarantees no in-flight JNI calls to writeAudio/readAudio.
+        val drained = audioPipeline?.awaitDrain() ?: true
+        if (!drained) {
+            Log.w(TAG, "teardown: audio threads did not drain in time")
+        }
+        audioPipeline = null
+
+        Log.i(TAG, "teardown: stopping engine")
+        try { engine?.stopCall() } catch (e: Exception) { Log.w(TAG, "stopCall err: $e") }
+        try { engine?.destroy() } catch (e: Exception) { Log.w(TAG, "destroy err: $e") }
+        engine = null
+        engineInitialized = false
+        _callState.value = 0
+        if (hadCall) {
+            _debugReportAvailable.value = true
+        }
+        if (stopService) {
+            try { appContext?.let { CallService.stop(it) } } catch (_: Exception) {}
+        }
+        Log.i(TAG, "teardown: done")
+    }
+
+    /** Accept the new server key and proceed with the call. */
+    fun acceptNewFingerprint() {
+        val info = _keyWarning.value ?: return
+        _knownFingerprints.value = _knownFingerprints.value.toMutableMap().also {
+            it[info.address] = info.newFp
+        }
+        settings?.saveServerFingerprint(info.address, info.newFp)
+        _keyWarning.value = null
+        startCallInternal()
+    }
+
+    fun dismissKeyWarning() {
+        _keyWarning.value = null
+    }
+
+    fun startCall() {
+        val serverEntry = _servers.value[_selectedServer.value]
+        // Check for key change before connecting
+        val ls = lockStatus(serverEntry.address)
+        if (ls == LockStatus.CHANGED) {
+            val known = _knownFingerprints.value[serverEntry.address] ?: ""
+            val current = _pingResults.value[serverEntry.address]?.serverFingerprint ?: ""
+            _keyWarning.value = KeyWarningInfo(serverEntry.address, known, current)
+            return
+        }
+        startCallInternal()
+    }
+
+    /** Start a call to a specific relay + room (used by direct call setup). */
+    private fun startCallInternal(relay: String, room: String) {
+        Log.i(TAG, "startCallDirect: relay=$relay room=$room")
+        try {
+            // Don't teardown — keep the signal connection alive
+            engine = WzpEngine(this)
+            engine!!.init()
+            engineInitialized = true
+            _callState.value = 1
+            _errorMessage.value = null
+            try { appContext?.let { CallService.start(it) } } catch (e: Exception) {
+                Log.w(TAG, "service start err: $e")
+            }
+            startStatsPolling()
+            viewModelScope.launch(kotlinx.coroutines.Dispatchers.IO) {
+                try {
+                    val seed = _seedHex.value
+                    val name = _alias.value
+                    val result = engine?.startCall(relay, room, seedHex = seed, alias = name, profile = _codecChoice.value) ?: -1
+                    CallService.onStopFromNotification = { stopCall() }
+                    if (result != 0) {
+                        _callState.value = 0
+                        _errorMessage.value = "Failed to connect to call room (code $result)"
+                        appContext?.let { CallService.stop(it) }
+                    }
+                } catch (e: Exception) {
+                    Log.e(TAG, "startCallDirect error", e)
+                    _callState.value = 0
+                    _errorMessage.value = "Engine error: ${e.message}"
+                    appContext?.let { CallService.stop(it) }
+                }
+            }
+        } catch (e: Exception) {
+            Log.e(TAG, "startCallDirect error", e)
+            _callState.value = 0
+            _errorMessage.value = "Engine error: ${e.message}"
+        }
+    }
+
+    private fun startCallInternal() {
+        val serverEntry = _servers.value[_selectedServer.value]
+        val room = _roomName.value
+        Log.i(TAG, "startCall: server=${serverEntry.address} room=$room")
+        _debugReportAvailable.value = false
+        _debugReportStatus.value = null
+        lastCallServer = serverEntry.address
+        settings?.addRecentRoom(serverEntry.address, room)
+        _recentRooms.value = settings?.loadRecentRooms() ?: emptyList()
+        debugReporter?.prepareForCall()
+        try {
+            // Teardown previous call but don't stop the service (we're about to restart it)
+            teardown(stopService = false)
+
+            Log.i(TAG, "startCall: creating engine")
+            engine = WzpEngine(this)
+            engine!!.init()
+            engineInitialized = true
+            _callState.value = 1
+            _errorMessage.value = null
+            try { appContext?.let { CallService.start(it) } } catch (e: Exception) {
+                Log.w(TAG, "service start err: $e")
+            }
+            startStatsPolling()
+
+            viewModelScope.launch(kotlinx.coroutines.Dispatchers.IO) {
+                try {
+                    val relay = resolveToIp(serverEntry.address)
+                    val seed = _seedHex.value
+                    val name = _alias.value
+                    Log.i(TAG, "startCall: resolved=$relay, alias=$name, calling engine.startCall")
+                    val result = engine?.startCall(relay, room, seedHex = seed, alias = name, profile = _codecChoice.value) ?: -1
+                    Log.i(TAG, "startCall: engine returned $result")
+                    // Only wire up notification callback after engine is running
+                    CallService.onStopFromNotification = { stopCall() }
+                    if (result != 0) {
+                        _callState.value = 0
+                        _errorMessage.value = "Failed to start call (code $result)"
+                        appContext?.let { CallService.stop(it) }
+                    }
+                } catch (e: Exception) {
+                    Log.e(TAG, "startCall IO error", e)
+                    _callState.value = 0
+                    _errorMessage.value = "Engine error: ${e.message}"
+                    appContext?.let { CallService.stop(it) }
+                }
+            }
+        } catch (e: Exception) {
+            Log.e(TAG, "startCall error", e)
+            _callState.value = 0
+            _errorMessage.value = "Engine error: ${e.message}"
+            appContext?.let { CallService.stop(it) }
+        }
+    }
+
+    fun stopCall() {
+        Log.i(TAG, "stopCall")
+        teardown()
+    }
+
+    fun toggleMute() {
+        val newMuted = !_isMuted.value
+        _isMuted.value = newMuted
+        try { engine?.setMute(newMuted) } catch (_: Exception) {}
+    }
+
+    fun toggleSpeaker() {
+        val newSpeaker = !_isSpeaker.value
+        _isSpeaker.value = newSpeaker
+        audioRouteManager?.setSpeaker(newSpeaker)
+    }
+
+    fun clearError() { _errorMessage.value = null }
+
+    fun sendDebugReport() {
+        val reporter = debugReporter ?: return
+        _debugReportStatus.value = "Preparing debug report..."
+        viewModelScope.launch(kotlinx.coroutines.Dispatchers.IO) {
+            val zipFile = reporter.collectZip(
+                callDurationSecs = lastCallDuration,
+                finalStatsJson = lastStatsJson,
+                aecEnabled = _aecEnabled.value,
+                alias = _alias.value,
+                server = lastCallServer,
+                room = _roomName.value
+            )
+            if (zipFile != null) {
+                _debugZipReady.value = zipFile
+                _debugReportStatus.value = "ready"
+            } else {
+                _debugReportStatus.value = "Error: failed to create zip"
+            }
+            _debugReportAvailable.value = false
+        }
+    }
+
+    /** Called by Activity after email intent is launched. */
+    fun onDebugReportSent() {
+        _debugZipReady.value = null
+        _debugReportStatus.value = null
+    }
+
+    fun dismissDebugReport() {
+        _debugReportAvailable.value = false
+        _debugReportStatus.value = null
+        _debugZipReady.value = null
+    }
+
+    // WzpCallback
+    override fun onCallStateChanged(state: Int) { _callState.value = state }
+    override fun onQualityTierChanged(tier: Int) { _qualityTier.value = tier }
+    override fun onError(code: Int, message: String) { _errorMessage.value = "Error $code: $message" }
+
+    private fun startAudio() {
+        if (audioStarted) return
+        val e = engine ?: return
+        val ctx = appContext ?: return
+        // Create a fresh pipeline each call to avoid stale threads
+        audioPipeline = AudioPipeline(ctx).also {
+            it.playoutGainDb = _playoutGainDb.value
+            it.captureGainDb = _captureGainDb.value
+            it.aecEnabled = _aecEnabled.value
+            it.debugRecording = _debugRecording.value
+            it.start(e)
+        }
+        audioRouteManager?.register()
+        audioStarted = true
+    }
+
+    private fun stopAudio() {
+        if (!audioStarted) return
+        audioPipeline?.stop()    // sets running=false; DON'T null — teardown needs awaitDrain()
+        audioRouteManager?.unregister()
+        audioRouteManager?.setSpeaker(false)
+        _isSpeaker.value = false
+        audioStarted = false
+    }
+
+    private fun startStatsPolling() {
+        statsJob?.cancel()
+        statsJob = viewModelScope.launch {
+            while (isActive) {
+                try {
+                    val json = engine?.getStats() ?: "{}"
+                    if (json.isNotEmpty()) {
+                        Log.d(TAG, "raw: $json")
+                        lastStatsJson = json
+                        val s = CallStats.fromJson(json)
+                        lastCallDuration = s.durationSecs
+                        _stats.value = s
+                        if (s.state != 0) {
+                            _callState.value = s.state
+                        }
+                        // Track signal state changes for direct calling
+                        if (s.state in 5..7) {
+                            _signalState.value = s.state
+                        }
+                        // Incoming call detection
+                        if (s.state == 7) { // IncomingCall
+                            _incomingCallId.value = s.incomingCallId
+                            _incomingCallerFp.value = s.incomingCallerFp
+                            _incomingCallerAlias.value = s.incomingCallerAlias
+                        }
+                        // CallSetup: auto-connect to media room
+                        if (s.state == 1 && s.incomingCallId != null && s.incomingCallId.contains("|")) {
+                            // Format: "relay_addr|room_name"
+                            val parts = s.incomingCallId.split("|", limit = 2)
+                            if (parts.size == 2) {
+                                val mediaRelay = parts[0]
+                                val mediaRoom = parts[1]
+                                Log.i(TAG, "CallSetup: connecting to $mediaRelay room $mediaRoom")
+                                startCallInternal(mediaRelay, mediaRoom)
+                            }
+                        }
+                        if (s.state == 2 && !audioStarted) {
+                            startAudio()
+                        }
+                    }
+                } catch (_: Exception) {}
+                delay(500L)
+            }
+        }
+    }
+
+    private fun stopStatsPolling() {
+        statsJob?.cancel()
+        statsJob = null
+    }
+
+    override fun onCleared() {
+        super.onCleared()
+        Log.i(TAG, "onCleared")
+        teardown()
+    }
+}

android/app/src/main/java/com/wzp/ui/components/Identicon.kt

@@ -0,0 +1,141 @@
+package com.wzp.ui.components
+
+import android.widget.Toast
+import androidx.compose.foundation.Canvas
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.geometry.Offset
+import androidx.compose.ui.geometry.Size
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.platform.LocalClipboardManager
+import androidx.compose.ui.platform.LocalContext
+import androidx.compose.ui.text.AnnotatedString
+import androidx.compose.ui.unit.Dp
+import androidx.compose.ui.unit.dp
+import kotlin.math.min
+
+/**
+ * Deterministic identicon — generates a unique 5x5 symmetric pattern
+ * from a hex fingerprint string. Identical algorithm to the desktop
+ * TypeScript implementation in identicon.ts.
+ */
+@Composable
+fun Identicon(
+    fingerprint: String,
+    size: Dp = 36.dp,
+    clickToCopy: Boolean = true,
+    modifier: Modifier = Modifier,
+) {
+    val clipboard = LocalClipboardManager.current
+    val context = LocalContext.current
+    val bytes = hashBytes(fingerprint)
+    val (bg, fg) = deriveColors(bytes)
+    val grid = buildGrid(bytes)
+
+    Canvas(
+        modifier = modifier
+            .size(size)
+            .clip(RoundedCornerShape(size * 0.12f))
+            .then(
+                if (clickToCopy && fingerprint.isNotEmpty()) {
+                    Modifier.clickable {
+                        clipboard.setText(AnnotatedString(fingerprint))
+                        Toast.makeText(context, "Copied", Toast.LENGTH_SHORT).show()
+                    }
+                } else Modifier
+            )
+    ) {
+        val cellW = this.size.width / 5f
+        val cellH = this.size.height / 5f
+
+        // Background
+        drawRect(color = bg, size = this.size)
+
+        // Foreground cells
+        for (y in 0 until 5) {
+            for (x in 0 until 5) {
+                if (grid[y][x]) {
+                    drawRect(
+                        color = fg,
+                        topLeft = Offset(x * cellW, y * cellH),
+                        size = Size(cellW, cellH),
+                    )
+                }
+            }
+        }
+    }
+}
+
+/**
+ * Fingerprint text that copies to clipboard on tap.
+ */
+@Composable
+fun CopyableFingerprint(
+    fingerprint: String,
+    modifier: Modifier = Modifier,
+    style: androidx.compose.ui.text.TextStyle = androidx.compose.material3.MaterialTheme.typography.bodySmall,
+    color: Color = Color.Unspecified,
+) {
+    val clipboard = LocalClipboardManager.current
+    val context = LocalContext.current
+
+    androidx.compose.material3.Text(
+        text = fingerprint,
+        style = style,
+        color = color,
+        modifier = modifier.clickable {
+            if (fingerprint.isNotEmpty()) {
+                clipboard.setText(AnnotatedString(fingerprint))
+                Toast.makeText(context, "Fingerprint copied", Toast.LENGTH_SHORT).show()
+            }
+        }
+    )
+}
+
+// --- Internal helpers (matching desktop identicon.ts) ---
+
+private fun hashBytes(hex: String): List<Int> {
+    val clean = hex.filter { it.isLetterOrDigit() }
+    val bytes = mutableListOf<Int>()
+    var i = 0
+    while (i + 1 < clean.length) {
+        val b = clean.substring(i, i + 2).toIntOrNull(16) ?: 0
+        bytes.add(b)
+        i += 2
+    }
+    // Pad to at least 16 bytes
+    while (bytes.size < 16) bytes.add(0)
+    return bytes
+}
+
+private fun deriveColors(bytes: List<Int>): Pair<Color, Color> {
+    val hue1 = bytes[0] * 360f / 256f
+    val hue2 = (bytes[1] * 360f / 256f + 120f) % 360f
+    val bg = hslToColor(hue1, 0.65f, 0.35f)
+    val fg = hslToColor(hue2, 0.70f, 0.55f)
+    return bg to fg
+}
+
+private fun buildGrid(bytes: List<Int>): List<List<Boolean>> {
+    return (0 until 5).map { y ->
+        val left = (0 until 3).map { x ->
+            val idx = 2 + y * 3 + x
+            bytes[idx % bytes.size] > 128
+        }
+        // Mirror: col3 = col1, col4 = col0
+        listOf(left[0], left[1], left[2], left[1], left[0])
+    }
+}
+
+private fun hslToColor(h: Float, s: Float, l: Float): Color {
+    val k = { n: Float -> (n + h / 30f) % 12f }
+    val a = s * min(l, 1f - l)
+    val f = { n: Float ->
+        l - a * maxOf(-1f, minOf(k(n) - 3f, minOf(9f - k(n), 1f)))
+    }
+    return Color(f(0f), f(8f), f(4f))
+}

android/app/src/main/java/com/wzp/ui/settings/SettingsScreen.kt

@@ -0,0 +1,567 @@
+package com.wzp.ui.settings
+
+import androidx.compose.foundation.clickable
+import android.content.ClipData
+import android.content.ClipboardManager
+import android.content.Context
+import android.widget.Toast
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.ExperimentalLayoutApi
+import androidx.compose.foundation.layout.FlowRow
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.width
+import androidx.compose.foundation.rememberScrollState
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.foundation.verticalScroll
+import androidx.compose.material3.AlertDialog
+import androidx.compose.material3.Button
+import androidx.compose.material3.ButtonDefaults
+import androidx.compose.material3.Divider
+import androidx.compose.material3.RadioButton
+import androidx.compose.material3.FilledTonalButton
+import androidx.compose.material3.FilledTonalIconButton
+import androidx.compose.material3.IconButtonDefaults
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.OutlinedButton
+import androidx.compose.material3.OutlinedTextField
+import androidx.compose.material3.Slider
+import androidx.compose.material3.Surface
+import androidx.compose.material3.Switch
+import androidx.compose.material3.Text
+import androidx.compose.material3.TextButton
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.collectAsState
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableFloatStateOf
+import androidx.compose.runtime.mutableIntStateOf
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.setValue
+import androidx.compose.runtime.toMutableStateList
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.platform.LocalContext
+import androidx.compose.ui.text.font.FontFamily
+import androidx.compose.ui.text.font.FontWeight
+import androidx.compose.ui.unit.dp
+import com.wzp.ui.call.CallViewModel
+import com.wzp.ui.call.ServerEntry
+
+@OptIn(ExperimentalLayoutApi::class)
+@Composable
+fun SettingsScreen(
+    viewModel: CallViewModel,
+    onBack: () -> Unit
+) {
+    val context = LocalContext.current
+
+    // Snapshot current values into local draft state
+    val currentAlias by viewModel.alias.collectAsState()
+    val currentSeedHex by viewModel.seedHex.collectAsState()
+    val currentServers by viewModel.servers.collectAsState()
+    val currentSelectedServer by viewModel.selectedServer.collectAsState()
+    val currentRoomName by viewModel.roomName.collectAsState()
+    val currentPreferIPv6 by viewModel.preferIPv6.collectAsState()
+    val currentPlayoutGain by viewModel.playoutGainDb.collectAsState()
+    val currentCaptureGain by viewModel.captureGainDb.collectAsState()
+    val currentAecEnabled by viewModel.aecEnabled.collectAsState()
+
+    // Draft state — initialized from current values
+    var draftAlias by remember { mutableStateOf(currentAlias) }
+    var draftSeedHex by remember { mutableStateOf(currentSeedHex) }
+    val draftServers = remember { currentServers.toMutableStateList() }
+    var draftSelectedServer by remember { mutableIntStateOf(currentSelectedServer) }
+    var draftRoomName by remember { mutableStateOf(currentRoomName) }
+    var draftPreferIPv6 by remember { mutableStateOf(currentPreferIPv6) }
+    var draftPlayoutGain by remember { mutableFloatStateOf(currentPlayoutGain) }
+    var draftCaptureGain by remember { mutableFloatStateOf(currentCaptureGain) }
+    var draftAecEnabled by remember { mutableStateOf(currentAecEnabled) }
+
+    // Track if anything changed
+    val hasChanges = draftAlias != currentAlias ||
+            draftSeedHex != currentSeedHex ||
+            draftServers.toList() != currentServers ||
+            draftSelectedServer != currentSelectedServer ||
+            draftRoomName != currentRoomName ||
+            draftPreferIPv6 != currentPreferIPv6 ||
+            draftPlayoutGain != currentPlayoutGain ||
+            draftCaptureGain != currentCaptureGain ||
+            draftAecEnabled != currentAecEnabled
+
+    var showAddServerDialog by remember { mutableStateOf(false) }
+    var showRestoreKeyDialog by remember { mutableStateOf(false) }
+
+    Surface(
+        modifier = Modifier.fillMaxSize(),
+        color = MaterialTheme.colorScheme.background
+    ) {
+        Column(
+            modifier = Modifier
+                .fillMaxSize()
+                .padding(24.dp)
+                .verticalScroll(rememberScrollState())
+        ) {
+            // Header
+            Row(
+                modifier = Modifier.fillMaxWidth(),
+                verticalAlignment = Alignment.CenterVertically
+            ) {
+                TextButton(onClick = onBack) {
+                    Text("< Back")
+                }
+                Spacer(modifier = Modifier.weight(1f))
+                Text(
+                    text = "Settings",
+                    style = MaterialTheme.typography.headlineSmall.copy(
+                        fontWeight = FontWeight.Bold
+                    ),
+                    color = MaterialTheme.colorScheme.primary
+                )
+                Spacer(modifier = Modifier.weight(1f))
+                // Save button — only enabled when changes exist
+                Button(
+                    onClick = {
+                        viewModel.setAlias(draftAlias)
+                        if (draftSeedHex != currentSeedHex) viewModel.restoreSeed(draftSeedHex)
+                        viewModel.applyServers(draftServers.toList(), draftSelectedServer)
+                        viewModel.setRoomName(draftRoomName)
+                        viewModel.setPreferIPv6(draftPreferIPv6)
+                        viewModel.setPlayoutGainDb(draftPlayoutGain)
+                        viewModel.setCaptureGainDb(draftCaptureGain)
+                        viewModel.setAecEnabled(draftAecEnabled)
+                        Toast.makeText(context, "Settings saved", Toast.LENGTH_SHORT).show()
+                        onBack()
+                    },
+                    enabled = hasChanges
+                ) {
+                    Text("Save")
+                }
+            }
+
+            Spacer(modifier = Modifier.height(24.dp))
+
+            // --- Identity ---
+            SectionHeader("Identity")
+
+            OutlinedTextField(
+                value = draftAlias,
+                onValueChange = { draftAlias = it },
+                label = { Text("Display Name") },
+                singleLine = true,
+                modifier = Modifier.fillMaxWidth()
+            )
+
+            Spacer(modifier = Modifier.height(16.dp))
+
+            // Fingerprint display with identicon
+            val fingerprint = if (draftSeedHex.length >= 16) draftSeedHex.take(16).uppercase() else "Not generated"
+            Text(
+                text = "Fingerprint",
+                style = MaterialTheme.typography.labelSmall,
+                color = MaterialTheme.colorScheme.onSurfaceVariant
+            )
+            Row(
+                verticalAlignment = Alignment.CenterVertically,
+                modifier = Modifier.padding(vertical = 4.dp)
+            ) {
+                com.wzp.ui.components.Identicon(
+                    fingerprint = draftSeedHex,
+                    size = 40.dp,
+                )
+                Spacer(modifier = Modifier.width(12.dp))
+                com.wzp.ui.components.CopyableFingerprint(
+                    fingerprint = fingerprint.chunked(4).joinToString(" "),
+                    style = MaterialTheme.typography.bodyMedium.copy(
+                        fontFamily = FontFamily.Monospace
+                    ),
+                    color = MaterialTheme.colorScheme.onSurface,
+                )
+            }
+
+            Spacer(modifier = Modifier.height(12.dp))
+
+            // Key backup/restore
+            Row(horizontalArrangement = Arrangement.spacedBy(8.dp)) {
+                FilledTonalButton(onClick = {
+                    val clipboard = context.getSystemService(Context.CLIPBOARD_SERVICE) as ClipboardManager
+                    clipboard.setPrimaryClip(ClipData.newPlainText("WZP Key", draftSeedHex))
+                    Toast.makeText(context, "Key copied to clipboard", Toast.LENGTH_SHORT).show()
+                }) {
+                    Text("Copy Key")
+                }
+                OutlinedButton(onClick = { showRestoreKeyDialog = true }) {
+                    Text("Restore Key")
+                }
+            }
+
+            Spacer(modifier = Modifier.height(24.dp))
+            Divider()
+            Spacer(modifier = Modifier.height(16.dp))
+
+            // --- Audio ---
+            SectionHeader("Audio Defaults")
+
+            GainSlider(
+                label = "Voice Volume",
+                gainDb = draftPlayoutGain,
+                onGainChange = { draftPlayoutGain = Math.round(it).toFloat() }
+            )
+            Spacer(modifier = Modifier.height(4.dp))
+            GainSlider(
+                label = "Mic Gain",
+                gainDb = draftCaptureGain,
+                onGainChange = { draftCaptureGain = Math.round(it).toFloat() }
+            )
+
+            Spacer(modifier = Modifier.height(12.dp))
+
+            Row(
+                verticalAlignment = Alignment.CenterVertically,
+                modifier = Modifier.fillMaxWidth()
+            ) {
+                Column(modifier = Modifier.weight(1f)) {
+                    Text(
+                        text = "Echo Cancellation (AEC)",
+                        style = MaterialTheme.typography.bodyMedium
+                    )
+                    Text(
+                        text = "Disable if audio sounds distorted",
+                        style = MaterialTheme.typography.bodySmall,
+                        color = MaterialTheme.colorScheme.onSurfaceVariant
+                    )
+                }
+                Switch(
+                    checked = draftAecEnabled,
+                    onCheckedChange = { draftAecEnabled = it }
+                )
+            }
+
+            Spacer(modifier = Modifier.height(12.dp))
+
+            // Quality selection — slider from best (studio 64k) to worst (codec2 1.2k) + auto
+            val qualityLabels = listOf(
+                "Studio 64k", "Studio 48k", "Studio 32k", "Auto",
+                "Opus 24k", "Opus 6k", "Codec2 3.2k", "Codec2 1.2k"
+            )
+            // Map slider position to JNI profile int:
+            // 0=Studio64k(6), 1=Studio48k(5), 2=Studio32k(4), 3=Auto(7),
+            // 4=Opus24k(0), 5=Opus6k(1), 6=Codec2_3.2k(3), 7=Codec2_1.2k(2)
+            val sliderToProfile = intArrayOf(6, 5, 4, 7, 0, 1, 3, 2)
+            val profileToSlider = mapOf(6 to 0, 5 to 1, 4 to 2, 7 to 3, 0 to 4, 1 to 5, 3 to 6, 2 to 7)
+            val qualityColors = listOf(
+                Color(0xFF22C55E), Color(0xFF4ADE80), Color(0xFF86EFAC), Color(0xFFA3E635),
+                Color(0xFFA3E635), Color(0xFFFACC15), Color(0xFFE97320), Color(0xFF991B1B)
+            )
+            val currentCodec by viewModel.codecChoice.collectAsState()
+            val sliderPos = profileToSlider[currentCodec] ?: 3
+            Text("Quality", style = MaterialTheme.typography.bodyMedium)
+            Text(
+                text = "Decode always accepts all codecs",
+                style = MaterialTheme.typography.bodySmall,
+                color = MaterialTheme.colorScheme.onSurfaceVariant
+            )
+            Spacer(modifier = Modifier.height(4.dp))
+            Text(
+                text = qualityLabels[sliderPos],
+                style = MaterialTheme.typography.titleMedium.copy(fontWeight = FontWeight.Bold),
+                color = qualityColors[sliderPos]
+            )
+            Slider(
+                value = sliderPos.toFloat(),
+                onValueChange = { viewModel.setCodecChoice(sliderToProfile[it.toInt()]) },
+                valueRange = 0f..7f,
+                steps = 6,
+                modifier = Modifier.fillMaxWidth()
+            )
+            Row(
+                modifier = Modifier.fillMaxWidth(),
+                horizontalArrangement = Arrangement.SpaceBetween
+            ) {
+                Text("Best", style = MaterialTheme.typography.labelSmall, color = Color(0xFF22C55E))
+                Text("Lowest", style = MaterialTheme.typography.labelSmall, color = Color(0xFF991B1B))
+            }
+
+            Spacer(modifier = Modifier.height(24.dp))
+            Divider()
+            Spacer(modifier = Modifier.height(16.dp))
+
+            // --- Servers ---
+            SectionHeader("Servers")
+
+            FlowRow(
+                modifier = Modifier.fillMaxWidth(),
+                horizontalArrangement = Arrangement.Start,
+                verticalArrangement = Arrangement.spacedBy(4.dp)
+            ) {
+                draftServers.forEachIndexed { idx, entry ->
+                    val isSelected = draftSelectedServer == idx
+                    Row(verticalAlignment = Alignment.CenterVertically) {
+                        FilledTonalIconButton(
+                            onClick = { draftSelectedServer = idx },
+                            modifier = Modifier
+                                .padding(end = 2.dp)
+                                .height(36.dp)
+                                .width(140.dp),
+                            shape = RoundedCornerShape(8.dp),
+                            colors = if (isSelected) {
+                                IconButtonDefaults.filledTonalIconButtonColors(
+                                    containerColor = MaterialTheme.colorScheme.primaryContainer,
+                                    contentColor = MaterialTheme.colorScheme.onPrimaryContainer
+                                )
+                            } else {
+                                IconButtonDefaults.filledTonalIconButtonColors()
+                            }
+                        ) {
+                            Text(
+                                text = entry.label,
+                                style = MaterialTheme.typography.labelSmall,
+                                maxLines = 1
+                            )
+                        }
+                        // Show remove button for non-default servers
+                        if (idx >= 2) {
+                            TextButton(
+                                onClick = {
+                                    draftServers.removeAt(idx)
+                                    if (draftSelectedServer >= draftServers.size) {
+                                        draftSelectedServer = 0
+                                    }
+                                },
+                                modifier = Modifier.height(36.dp)
+                            ) {
+                                Text("X", color = MaterialTheme.colorScheme.error)
+                            }
+                        }
+                    }
+                }
+            }
+
+            Spacer(modifier = Modifier.height(8.dp))
+            OutlinedButton(
+                onClick = { showAddServerDialog = true },
+                shape = RoundedCornerShape(8.dp)
+            ) {
+                Text("+ Add Server")
+            }
+
+            // Show selected server address
+            Spacer(modifier = Modifier.height(8.dp))
+            Text(
+                text = "Default: ${draftServers.getOrNull(draftSelectedServer)?.address ?: "none"}",
+                style = MaterialTheme.typography.bodySmall,
+                color = MaterialTheme.colorScheme.onSurfaceVariant
+            )
+
+            Spacer(modifier = Modifier.height(24.dp))
+            Divider()
+            Spacer(modifier = Modifier.height(16.dp))
+
+            // --- Network ---
+            SectionHeader("Network")
+
+            Row(
+                verticalAlignment = Alignment.CenterVertically,
+                modifier = Modifier.fillMaxWidth()
+            ) {
+                Text(
+                    text = "Prefer IPv6",
+                    style = MaterialTheme.typography.bodyMedium,
+                    modifier = Modifier.weight(1f)
+                )
+                Switch(
+                    checked = draftPreferIPv6,
+                    onCheckedChange = { draftPreferIPv6 = it }
+                )
+            }
+
+            Spacer(modifier = Modifier.height(24.dp))
+            Divider()
+            Spacer(modifier = Modifier.height(16.dp))
+
+            // --- Room ---
+            SectionHeader("Room")
+
+            OutlinedTextField(
+                value = draftRoomName,
+                onValueChange = { draftRoomName = it },
+                label = { Text("Default Room") },
+                singleLine = true,
+                modifier = Modifier.fillMaxWidth()
+            )
+
+            Spacer(modifier = Modifier.height(32.dp))
+        }
+    }
+
+    if (showAddServerDialog) {
+        AddServerDialog(
+            onDismiss = { showAddServerDialog = false },
+            onAdd = { host, port, label ->
+                draftServers.add(ServerEntry("$host:$port", label))
+                showAddServerDialog = false
+            }
+        )
+    }
+
+    if (showRestoreKeyDialog) {
+        RestoreKeyDialog(
+            onDismiss = { showRestoreKeyDialog = false },
+            onRestore = { hex ->
+                draftSeedHex = hex
+                showRestoreKeyDialog = false
+                Toast.makeText(context, "Key staged — press Save to apply", Toast.LENGTH_SHORT).show()
+            }
+        )
+    }
+}
+
+@Composable
+private fun SectionHeader(title: String) {
+    Text(
+        text = title,
+        style = MaterialTheme.typography.titleMedium.copy(fontWeight = FontWeight.Bold),
+        color = MaterialTheme.colorScheme.primary
+    )
+    Spacer(modifier = Modifier.height(8.dp))
+}
+
+@Composable
+private fun GainSlider(label: String, gainDb: Float, onGainChange: (Float) -> Unit) {
+    Column(
+        modifier = Modifier.fillMaxWidth(),
+        horizontalAlignment = Alignment.CenterHorizontally
+    ) {
+        val sign = if (gainDb >= 0) "+" else ""
+        Text(
+            text = "$label: ${sign}${"%.0f".format(gainDb)} dB",
+            style = MaterialTheme.typography.labelSmall,
+            color = MaterialTheme.colorScheme.onSurfaceVariant
+        )
+        Slider(
+            value = gainDb,
+            onValueChange = onGainChange,
+            valueRange = -20f..20f,
+            steps = 0,
+            modifier = Modifier.fillMaxWidth()
+        )
+    }
+}
+
+@Composable
+private fun AddServerDialog(
+    onDismiss: () -> Unit,
+    onAdd: (host: String, port: String, label: String) -> Unit
+) {
+    var host by remember { mutableStateOf("") }
+    var port by remember { mutableStateOf("4433") }
+    var label by remember { mutableStateOf("") }
+
+    AlertDialog(
+        onDismissRequest = onDismiss,
+        title = { Text("Add Server") },
+        text = {
+            Column {
+                OutlinedTextField(
+                    value = host,
+                    onValueChange = { host = it },
+                    label = { Text("Host (IP or domain)") },
+                    singleLine = true,
+                    modifier = Modifier.fillMaxWidth()
+                )
+                Spacer(modifier = Modifier.height(8.dp))
+                OutlinedTextField(
+                    value = port,
+                    onValueChange = { port = it },
+                    label = { Text("Port") },
+                    singleLine = true,
+                    modifier = Modifier.fillMaxWidth()
+                )
+                Spacer(modifier = Modifier.height(8.dp))
+                OutlinedTextField(
+                    value = label,
+                    onValueChange = { label = it },
+                    label = { Text("Label (optional)") },
+                    singleLine = true,
+                    modifier = Modifier.fillMaxWidth()
+                )
+            }
+        },
+        confirmButton = {
+            TextButton(
+                onClick = {
+                    if (host.isNotBlank()) {
+                        val displayLabel = label.ifBlank { host }
+                        onAdd(host.trim(), port.trim(), displayLabel)
+                    }
+                }
+            ) { Text("Add") }
+        },
+        dismissButton = {
+            TextButton(onClick = onDismiss) { Text("Cancel") }
+        }
+    )
+}
+
+@Composable
+private fun RestoreKeyDialog(
+    onDismiss: () -> Unit,
+    onRestore: (hex: String) -> Unit
+) {
+    var keyInput by remember { mutableStateOf("") }
+    var error by remember { mutableStateOf<String?>(null) }
+
+    AlertDialog(
+        onDismissRequest = onDismiss,
+        title = { Text("Restore Identity Key") },
+        text = {
+            Column {
+                Text(
+                    text = "Paste your 64-character hex key below. This will replace your current identity.",
+                    style = MaterialTheme.typography.bodySmall,
+                    color = MaterialTheme.colorScheme.onSurfaceVariant
+                )
+                Spacer(modifier = Modifier.height(8.dp))
+                OutlinedTextField(
+                    value = keyInput,
+                    onValueChange = {
+                        keyInput = it.trim().lowercase()
+                        error = null
+                    },
+                    label = { Text("Identity Key (hex)") },
+                    singleLine = true,
+                    modifier = Modifier.fillMaxWidth(),
+                    isError = error != null
+                )
+                error?.let {
+                    Text(
+                        text = it,
+                        style = MaterialTheme.typography.bodySmall,
+                        color = MaterialTheme.colorScheme.error
+                    )
+                }
+            }
+        },
+        confirmButton = {
+            TextButton(
+                onClick = {
+                    val cleaned = keyInput.replace("\\s".toRegex(), "")
+                    if (cleaned.length != 64 || !cleaned.all { it in '0'..'9' || it in 'a'..'f' }) {
+                        error = "Key must be exactly 64 hex characters"
+                    } else {
+                        onRestore(cleaned)
+                    }
+                }
+            ) { Text("Restore") }
+        },
+        dismissButton = {
+            TextButton(onClick = onDismiss) { Text("Cancel") }
+        }
+    )
+}

android/app/src/main/res/xml/file_paths.xml

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="utf-8"?>
+<paths>
+    <cache-path name="debug" path="." />
+</paths>

android/build.gradle.kts

@@ -0,0 +1,4 @@
+plugins {
+    id("com.android.application") version "8.2.0" apply false
+    id("org.jetbrains.kotlin.android") version "1.9.22" apply false
+}

android/gradle.properties

@@ -0,0 +1,4 @@
+org.gradle.jvmargs=-Xmx2048m -Dfile.encoding=UTF-8
+android.useAndroidX=true
+kotlin.code.style=official
+android.nonTransitiveRClass=true

android/gradle/wrapper/gradle-wrapper.properties

@@ -0,0 +1,6 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.5-bin.zip
+networkTimeout=10000
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists

android/gradlew

@@ -0,0 +1,5 @@
+#!/bin/sh
+# Gradle wrapper script
+APP_HOME=$(cd "$(dirname "$0")" && pwd)
+CLASSPATH="$APP_HOME/gradle/wrapper/gradle-wrapper.jar"
+exec java -classpath "$CLASSPATH" org.gradle.wrapper.GradleWrapperMain "$@"

android/settings.gradle.kts

@@ -0,0 +1,18 @@
+pluginManagement {
+    repositories {
+        google()
+        mavenCentral()
+        gradlePluginPortal()
+    }
+}
+
+dependencyResolutionManagement {
+    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
+    repositories {
+        google()
+        mavenCentral()
+    }
+}
+
+rootProject.name = "WZPhone"
+include(":app")

crates/wzp-android/Cargo.toml

@@ -0,0 +1,34 @@
+[package]
+name = "wzp-android"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+rust-version.workspace = true
+description = "WarzonePhone Android native VoIP engine — Oboe audio, JNI bridge, call pipeline"
+
+[lib]
+crate-type = ["cdylib", "rlib"]
+
+[dependencies]
+wzp-proto = { workspace = true }
+wzp-codec = { workspace = true }
+wzp-fec = { workspace = true }
+wzp-crypto = { workspace = true }
+wzp-transport = { workspace = true }
+tokio = { workspace = true }
+tracing = { workspace = true }
+tracing-subscriber = { workspace = true, features = ["env-filter"] }
+bytes = { workspace = true }
+serde = { workspace = true }
+serde_json = "1"
+thiserror = { workspace = true }
+async-trait = { workspace = true }
+anyhow = "1"
+libc = "0.2"
+jni = { version = "0.21", default-features = false }
+rand = { workspace = true }
+rustls = { version = "0.23", default-features = false, features = ["ring"] }
+tracing-android = "0.2"
+
+[build-dependencies]
+cc = "1"

crates/wzp-android/build.rs

@@ -0,0 +1,154 @@
+use std::path::PathBuf;
+
+fn main() {
+    let target = std::env::var("TARGET").unwrap_or_default();
+
+    if target.contains("android") {
+        // Override broken static getauxval from compiler-rt that crashes
+        // in shared libraries. Must be compiled first to take link priority.
+        cc::Build::new()
+            .file("cpp/getauxval_fix.c")
+            .compile("getauxval_fix");
+
+        let oboe_dir = fetch_oboe();
+        match oboe_dir {
+            Some(oboe_path) => {
+                println!("cargo:warning=Building with Oboe from {:?}", oboe_path);
+
+                let mut build = cc::Build::new();
+                build
+                    .cpp(true)
+                    .std("c++17")
+                    // Use shared libc++ — avoids pulling in static libc stubs
+                    // that crash in shared libraries (getauxval, pthread_create, etc.)
+                    .cpp_link_stdlib(Some("c++_shared"))
+                    .include("cpp")
+                    .include(oboe_path.join("include"))
+                    .include(oboe_path.join("src"))
+                    .define("WZP_HAS_OBOE", None)
+                    .file("cpp/oboe_bridge.cpp");
+
+                // Compile all Oboe source files
+                let src_dir = oboe_path.join("src");
+                add_cpp_files_recursive(&mut build, &src_dir);
+
+                build.compile("oboe_bridge");
+            }
+            None => {
+                println!("cargo:warning=Oboe not found, building with stub");
+                cc::Build::new()
+                    .cpp(true)
+                    .std("c++17")
+                    .cpp_link_stdlib(Some("c++_shared"))
+                    .file("cpp/oboe_stub.cpp")
+                    .include("cpp")
+                    .compile("oboe_bridge");
+            }
+        }
+
+        // Dynamic C++ runtime — libc++_shared.so must be in jniLibs alongside
+        // libwzp_android.so. We copy it there from the NDK sysroot.
+        //
+        // WHY NOT STATIC: libc++_static.a + libc++abi.a transitively pull in
+        // object files from libc.a (static libc) which contain broken stubs for
+        // getauxval, __init_tcb, pthread_create, etc. These stubs only work in
+        // statically-linked executables. In shared libraries loaded by dlopen(),
+        // they SIGSEGV because the static libc init hasn't run.
+        // Google's official recommendation: use libc++_shared.so for native libs.
+        if let Ok(ndk) = std::env::var("ANDROID_NDK_HOME") {
+            let arch = if target.contains("aarch64") {
+                "aarch64-linux-android"
+            } else if target.contains("armv7") {
+                "arm-linux-androideabi"
+            } else if target.contains("x86_64") {
+                "x86_64-linux-android"
+            } else {
+                "aarch64-linux-android"
+            };
+            let lib_dir = format!(
+                "{ndk}/toolchains/llvm/prebuilt/linux-x86_64/sysroot/usr/lib/{arch}"
+            );
+            println!("cargo:rustc-link-search=native={lib_dir}");
+
+            // Copy libc++_shared.so to the jniLibs directory
+            let shared_so = format!("{lib_dir}/libc++_shared.so");
+            if std::path::Path::new(&shared_so).exists() {
+                let jni_abi = if target.contains("aarch64") {
+                    "arm64-v8a"
+                } else if target.contains("armv7") {
+                    "armeabi-v7a"
+                } else {
+                    "arm64-v8a"
+                };
+                // Try to copy to the Gradle jniLibs directory
+                let manifest = std::env::var("CARGO_MANIFEST_DIR").unwrap_or_default();
+                let jni_dir = format!(
+                    "{manifest}/../../android/app/src/main/jniLibs/{jni_abi}"
+                );
+                if let Ok(_) = std::fs::create_dir_all(&jni_dir) {
+                    let _ = std::fs::copy(&shared_so, format!("{jni_dir}/libc++_shared.so"));
+                    println!("cargo:warning=Copied libc++_shared.so to {jni_dir}");
+                }
+            }
+        }
+
+        // Oboe needs liblog and libOpenSLES from Android
+        println!("cargo:rustc-link-lib=log");
+        println!("cargo:rustc-link-lib=OpenSLES");
+    } else {
+        // Non-Android: always use stub
+        cc::Build::new()
+            .cpp(true)
+            .std("c++17")
+            .file("cpp/oboe_stub.cpp")
+            .include("cpp")
+            .compile("oboe_bridge");
+    }
+}
+
+/// Recursively add all .cpp files from a directory to a cc::Build.
+fn add_cpp_files_recursive(build: &mut cc::Build, dir: &std::path::Path) {
+    if !dir.is_dir() {
+        return;
+    }
+    for entry in std::fs::read_dir(dir).unwrap() {
+        let entry = entry.unwrap();
+        let path = entry.path();
+        if path.is_dir() {
+            add_cpp_files_recursive(build, &path);
+        } else if path.extension().map_or(false, |e| e == "cpp") {
+            build.file(&path);
+        }
+    }
+}
+
+/// Try to find or fetch Oboe headers + source.
+fn fetch_oboe() -> Option<PathBuf> {
+    let out_dir = PathBuf::from(std::env::var("OUT_DIR").unwrap());
+    let oboe_dir = out_dir.join("oboe");
+
+    if oboe_dir.join("include").join("oboe").join("Oboe.h").exists() {
+        return Some(oboe_dir);
+    }
+
+    let status = std::process::Command::new("git")
+        .args([
+            "clone",
+            "--depth=1",
+            "--branch=1.8.1",
+            "https://github.com/google/oboe.git",
+            oboe_dir.to_str().unwrap(),
+        ])
+        .status();
+
+    match status {
+        Ok(s) if s.success() => {
+            if oboe_dir.join("include").join("oboe").join("Oboe.h").exists() {
+                Some(oboe_dir)
+            } else {
+                None
+            }
+        }
+        _ => None,
+    }
+}

crates/wzp-android/cpp/getauxval_fix.c

@@ -0,0 +1,21 @@
+// Override the broken static getauxval from compiler-rt/CRT.
+// The static version reads from __libc_auxv which is NULL in shared libs
+// loaded via dlopen, causing SIGSEGV in init_have_lse_atomics at load time.
+// This version calls the real bionic getauxval via dlsym.
+#ifdef __ANDROID__
+#include <dlfcn.h>
+#include <stdint.h>
+
+typedef unsigned long (*getauxval_fn)(unsigned long);
+
+unsigned long getauxval(unsigned long type) {
+    static getauxval_fn real_getauxval = (getauxval_fn)0;
+    if (!real_getauxval) {
+        real_getauxval = (getauxval_fn)dlsym((void*)-1L /* RTLD_DEFAULT */, "getauxval");
+        if (!real_getauxval) {
+            return 0;
+        }
+    }
+    return real_getauxval(type);
+}
+#endif

crates/wzp-android/cpp/oboe_bridge.cpp

@@ -0,0 +1,278 @@
+// Full Oboe implementation for Android
+// This file is compiled only when targeting Android
+
+#include "oboe_bridge.h"
+
+#ifdef __ANDROID__
+#include <oboe/Oboe.h>
+#include <android/log.h>
+#include <cstring>
+#include <atomic>
+
+#define LOG_TAG "wzp-oboe"
+#define LOGI(...) __android_log_print(ANDROID_LOG_INFO, LOG_TAG, __VA_ARGS__)
+#define LOGW(...) __android_log_print(ANDROID_LOG_WARN, LOG_TAG, __VA_ARGS__)
+#define LOGE(...) __android_log_print(ANDROID_LOG_ERROR, LOG_TAG, __VA_ARGS__)
+
+// ---------------------------------------------------------------------------
+// Ring buffer helpers (SPSC, lock-free)
+// ---------------------------------------------------------------------------
+
+static inline int32_t ring_available_read(const wzp_atomic_int* write_idx,
+                                           const wzp_atomic_int* read_idx,
+                                           int32_t capacity) {
+    int32_t w = std::atomic_load_explicit(write_idx, std::memory_order_acquire);
+    int32_t r = std::atomic_load_explicit(read_idx, std::memory_order_relaxed);
+    int32_t avail = w - r;
+    if (avail < 0) avail += capacity;
+    return avail;
+}
+
+static inline int32_t ring_available_write(const wzp_atomic_int* write_idx,
+                                            const wzp_atomic_int* read_idx,
+                                            int32_t capacity) {
+    return capacity - 1 - ring_available_read(write_idx, read_idx, capacity);
+}
+
+static inline void ring_write(int16_t* buf, int32_t capacity,
+                               wzp_atomic_int* write_idx, const wzp_atomic_int* read_idx,
+                               const int16_t* src, int32_t count) {
+    int32_t w = std::atomic_load_explicit(write_idx, std::memory_order_relaxed);
+    for (int32_t i = 0; i < count; i++) {
+        buf[w] = src[i];
+        w++;
+        if (w >= capacity) w = 0;
+    }
+    std::atomic_store_explicit(write_idx, w, std::memory_order_release);
+}
+
+static inline void ring_read(int16_t* buf, int32_t capacity,
+                              const wzp_atomic_int* write_idx, wzp_atomic_int* read_idx,
+                              int16_t* dst, int32_t count) {
+    int32_t r = std::atomic_load_explicit(read_idx, std::memory_order_relaxed);
+    for (int32_t i = 0; i < count; i++) {
+        dst[i] = buf[r];
+        r++;
+        if (r >= capacity) r = 0;
+    }
+    std::atomic_store_explicit(read_idx, r, std::memory_order_release);
+}
+
+// ---------------------------------------------------------------------------
+// Global state
+// ---------------------------------------------------------------------------
+
+static std::shared_ptr<oboe::AudioStream> g_capture_stream;
+static std::shared_ptr<oboe::AudioStream> g_playout_stream;
+static const WzpOboeRings* g_rings = nullptr;
+static std::atomic<bool> g_running{false};
+static std::atomic<float> g_capture_latency_ms{0.0f};
+static std::atomic<float> g_playout_latency_ms{0.0f};
+
+// ---------------------------------------------------------------------------
+// Capture callback
+// ---------------------------------------------------------------------------
+
+class CaptureCallback : public oboe::AudioStreamDataCallback {
+public:
+    oboe::DataCallbackResult onAudioReady(
+            oboe::AudioStream* stream,
+            void* audioData,
+            int32_t numFrames) override {
+        if (!g_running.load(std::memory_order_relaxed) || !g_rings) {
+            return oboe::DataCallbackResult::Stop;
+        }
+
+        const int16_t* src = static_cast<const int16_t*>(audioData);
+        int32_t avail = ring_available_write(g_rings->capture_write_idx,
+                                              g_rings->capture_read_idx,
+                                              g_rings->capture_capacity);
+        int32_t to_write = (numFrames < avail) ? numFrames : avail;
+        if (to_write > 0) {
+            ring_write(g_rings->capture_buf, g_rings->capture_capacity,
+                       g_rings->capture_write_idx, g_rings->capture_read_idx,
+                       src, to_write);
+        }
+
+        // Update latency estimate
+        auto result = stream->calculateLatencyMillis();
+        if (result) {
+            g_capture_latency_ms.store(static_cast<float>(result.value()),
+                                        std::memory_order_relaxed);
+        }
+
+        return oboe::DataCallbackResult::Continue;
+    }
+};
+
+// ---------------------------------------------------------------------------
+// Playout callback
+// ---------------------------------------------------------------------------
+
+class PlayoutCallback : public oboe::AudioStreamDataCallback {
+public:
+    oboe::DataCallbackResult onAudioReady(
+            oboe::AudioStream* stream,
+            void* audioData,
+            int32_t numFrames) override {
+        if (!g_running.load(std::memory_order_relaxed) || !g_rings) {
+            memset(audioData, 0, numFrames * sizeof(int16_t));
+            return oboe::DataCallbackResult::Stop;
+        }
+
+        int16_t* dst = static_cast<int16_t*>(audioData);
+        int32_t avail = ring_available_read(g_rings->playout_write_idx,
+                                             g_rings->playout_read_idx,
+                                             g_rings->playout_capacity);
+        int32_t to_read = (numFrames < avail) ? numFrames : avail;
+
+        if (to_read > 0) {
+            ring_read(g_rings->playout_buf, g_rings->playout_capacity,
+                      g_rings->playout_write_idx, g_rings->playout_read_idx,
+                      dst, to_read);
+        }
+        // Fill remainder with silence on underrun
+        if (to_read < numFrames) {
+            memset(dst + to_read, 0, (numFrames - to_read) * sizeof(int16_t));
+        }
+
+        // Update latency estimate
+        auto result = stream->calculateLatencyMillis();
+        if (result) {
+            g_playout_latency_ms.store(static_cast<float>(result.value()),
+                                        std::memory_order_relaxed);
+        }
+
+        return oboe::DataCallbackResult::Continue;
+    }
+};
+
+static CaptureCallback g_capture_cb;
+static PlayoutCallback g_playout_cb;
+
+// ---------------------------------------------------------------------------
+// Public C API
+// ---------------------------------------------------------------------------
+
+int wzp_oboe_start(const WzpOboeConfig* config, const WzpOboeRings* rings) {
+    if (g_running.load(std::memory_order_relaxed)) {
+        LOGW("wzp_oboe_start: already running");
+        return -1;
+    }
+
+    g_rings = rings;
+
+    // Build capture stream
+    oboe::AudioStreamBuilder captureBuilder;
+    captureBuilder.setDirection(oboe::Direction::Input)
+        ->setPerformanceMode(oboe::PerformanceMode::LowLatency)
+        ->setSharingMode(oboe::SharingMode::Exclusive)
+        ->setFormat(oboe::AudioFormat::I16)
+        ->setChannelCount(config->channel_count)
+        ->setSampleRate(config->sample_rate)
+        ->setFramesPerDataCallback(config->frames_per_burst)
+        ->setInputPreset(oboe::InputPreset::VoiceCommunication)
+        ->setDataCallback(&g_capture_cb);
+
+    oboe::Result result = captureBuilder.openStream(g_capture_stream);
+    if (result != oboe::Result::OK) {
+        LOGE("Failed to open capture stream: %s", oboe::convertToText(result));
+        return -2;
+    }
+
+    // Build playout stream
+    oboe::AudioStreamBuilder playoutBuilder;
+    playoutBuilder.setDirection(oboe::Direction::Output)
+        ->setPerformanceMode(oboe::PerformanceMode::LowLatency)
+        ->setSharingMode(oboe::SharingMode::Exclusive)
+        ->setFormat(oboe::AudioFormat::I16)
+        ->setChannelCount(config->channel_count)
+        ->setSampleRate(config->sample_rate)
+        ->setFramesPerDataCallback(config->frames_per_burst)
+        ->setUsage(oboe::Usage::VoiceCommunication)
+        ->setDataCallback(&g_playout_cb);
+
+    result = playoutBuilder.openStream(g_playout_stream);
+    if (result != oboe::Result::OK) {
+        LOGE("Failed to open playout stream: %s", oboe::convertToText(result));
+        g_capture_stream->close();
+        g_capture_stream.reset();
+        return -3;
+    }
+
+    g_running.store(true, std::memory_order_release);
+
+    // Start both streams
+    result = g_capture_stream->requestStart();
+    if (result != oboe::Result::OK) {
+        LOGE("Failed to start capture: %s", oboe::convertToText(result));
+        g_running.store(false, std::memory_order_release);
+        g_capture_stream->close();
+        g_playout_stream->close();
+        g_capture_stream.reset();
+        g_playout_stream.reset();
+        return -4;
+    }
+
+    result = g_playout_stream->requestStart();
+    if (result != oboe::Result::OK) {
+        LOGE("Failed to start playout: %s", oboe::convertToText(result));
+        g_running.store(false, std::memory_order_release);
+        g_capture_stream->requestStop();
+        g_capture_stream->close();
+        g_playout_stream->close();
+        g_capture_stream.reset();
+        g_playout_stream.reset();
+        return -5;
+    }
+
+    LOGI("Oboe started: sr=%d burst=%d ch=%d",
+         config->sample_rate, config->frames_per_burst, config->channel_count);
+    return 0;
+}
+
+void wzp_oboe_stop(void) {
+    g_running.store(false, std::memory_order_release);
+
+    if (g_capture_stream) {
+        g_capture_stream->requestStop();
+        g_capture_stream->close();
+        g_capture_stream.reset();
+    }
+    if (g_playout_stream) {
+        g_playout_stream->requestStop();
+        g_playout_stream->close();
+        g_playout_stream.reset();
+    }
+
+    g_rings = nullptr;
+    LOGI("Oboe stopped");
+}
+
+float wzp_oboe_capture_latency_ms(void) {
+    return g_capture_latency_ms.load(std::memory_order_relaxed);
+}
+
+float wzp_oboe_playout_latency_ms(void) {
+    return g_playout_latency_ms.load(std::memory_order_relaxed);
+}
+
+int wzp_oboe_is_running(void) {
+    return g_running.load(std::memory_order_relaxed) ? 1 : 0;
+}
+
+#else
+// Non-Android fallback — should not be reached; oboe_stub.cpp is used instead.
+// Provide empty implementations just in case.
+
+int wzp_oboe_start(const WzpOboeConfig* config, const WzpOboeRings* rings) {
+    (void)config; (void)rings;
+    return -99;
+}
+
+void wzp_oboe_stop(void) {}
+float wzp_oboe_capture_latency_ms(void) { return 0.0f; }
+float wzp_oboe_playout_latency_ms(void) { return 0.0f; }
+int wzp_oboe_is_running(void) { return 0; }
+
+#endif // __ANDROID__

crates/wzp-android/cpp/oboe_bridge.h

@@ -0,0 +1,43 @@
+#ifndef WZP_OBOE_BRIDGE_H
+#define WZP_OBOE_BRIDGE_H
+
+#include <stdint.h>
+
+#ifdef __cplusplus
+#include <atomic>
+typedef std::atomic<int32_t> wzp_atomic_int;
+extern "C" {
+#else
+#include <stdatomic.h>
+typedef atomic_int wzp_atomic_int;
+#endif
+
+typedef struct {
+    int32_t sample_rate;
+    int32_t frames_per_burst;
+    int32_t channel_count;
+} WzpOboeConfig;
+
+typedef struct {
+    int16_t* capture_buf;
+    int32_t  capture_capacity;
+    wzp_atomic_int* capture_write_idx;
+    wzp_atomic_int* capture_read_idx;
+
+    int16_t* playout_buf;
+    int32_t  playout_capacity;
+    wzp_atomic_int* playout_write_idx;
+    wzp_atomic_int* playout_read_idx;
+} WzpOboeRings;
+
+int wzp_oboe_start(const WzpOboeConfig* config, const WzpOboeRings* rings);
+void wzp_oboe_stop(void);
+float wzp_oboe_capture_latency_ms(void);
+float wzp_oboe_playout_latency_ms(void);
+int wzp_oboe_is_running(void);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif // WZP_OBOE_BRIDGE_H

crates/wzp-android/cpp/oboe_stub.cpp

@@ -0,0 +1,27 @@
+// Stub implementation for non-Android host builds (testing, cargo check, etc.)
+
+#include "oboe_bridge.h"
+#include <stdio.h>
+
+int wzp_oboe_start(const WzpOboeConfig* config, const WzpOboeRings* rings) {
+    (void)config;
+    (void)rings;
+    fprintf(stderr, "wzp_oboe_start: stub (not on Android)\n");
+    return 0;
+}
+
+void wzp_oboe_stop(void) {
+    fprintf(stderr, "wzp_oboe_stop: stub (not on Android)\n");
+}
+
+float wzp_oboe_capture_latency_ms(void) {
+    return 0.0f;
+}
+
+float wzp_oboe_playout_latency_ms(void) {
+    return 0.0f;
+}
+
+int wzp_oboe_is_running(void) {
+    return 0;
+}

crates/wzp-android/src/audio_android.rs

@@ -0,0 +1,424 @@
+//! Lock-free SPSC ring buffer audio backend for Android (Oboe).
+//!
+//! The ring buffers are shared between Rust and C++: the Oboe callbacks
+//! (running on a high-priority audio thread) read/write directly into
+//! the buffers via atomic indices, while the Rust codec thread on the
+//! other side does the same.
+
+use std::sync::atomic::{AtomicI32, Ordering};
+
+use tracing::info;
+#[allow(unused_imports)]
+use tracing::warn;
+
+/// Number of samples per 20 ms frame at 48 kHz mono.
+pub const FRAME_SAMPLES: usize = 960;
+
+/// Default ring buffer capacity: 8 frames = 160 ms at 48 kHz.
+const RING_CAPACITY: usize = 7680;
+
+// ---------------------------------------------------------------------------
+// FFI declarations matching oboe_bridge.h
+// ---------------------------------------------------------------------------
+
+#[repr(C)]
+#[allow(non_snake_case)]
+struct WzpOboeConfig {
+    sample_rate: i32,
+    frames_per_burst: i32,
+    channel_count: i32,
+}
+
+#[repr(C)]
+#[allow(non_snake_case)]
+struct WzpOboeRings {
+    capture_buf: *mut i16,
+    capture_capacity: i32,
+    capture_write_idx: *mut AtomicI32,
+    capture_read_idx: *mut AtomicI32,
+
+    playout_buf: *mut i16,
+    playout_capacity: i32,
+    playout_write_idx: *mut AtomicI32,
+    playout_read_idx: *mut AtomicI32,
+}
+
+unsafe impl Send for WzpOboeRings {}
+unsafe impl Sync for WzpOboeRings {}
+
+unsafe extern "C" {
+    fn wzp_oboe_start(config: *const WzpOboeConfig, rings: *const WzpOboeRings) -> i32;
+    fn wzp_oboe_stop();
+    fn wzp_oboe_capture_latency_ms() -> f32;
+    fn wzp_oboe_playout_latency_ms() -> f32;
+    fn wzp_oboe_is_running() -> i32;
+}
+
+// ---------------------------------------------------------------------------
+// SPSC Ring Buffer
+// ---------------------------------------------------------------------------
+
+/// Single-producer single-consumer lock-free ring buffer.
+///
+/// The producer calls `write()` and the consumer calls `read()`.
+/// Atomics use acquire/release ordering to ensure correct visibility
+/// across the Oboe audio thread and the Rust codec thread.
+pub struct RingBuffer {
+    buf: Vec<i16>,
+    capacity: usize,
+    write_idx: AtomicI32,
+    read_idx: AtomicI32,
+}
+
+impl RingBuffer {
+    /// Create a new ring buffer with the given capacity (in samples).
+    ///
+    /// The actual usable capacity is `capacity - 1` to distinguish
+    /// full from empty.
+    pub fn new(capacity: usize) -> Self {
+        Self {
+            buf: vec![0i16; capacity],
+            capacity,
+            write_idx: AtomicI32::new(0),
+            read_idx: AtomicI32::new(0),
+        }
+    }
+
+    /// Number of samples available to read.
+    pub fn available_read(&self) -> usize {
+        let w = self.write_idx.load(Ordering::Acquire);
+        let r = self.read_idx.load(Ordering::Relaxed);
+        let avail = w - r;
+        if avail < 0 {
+            (avail + self.capacity as i32) as usize
+        } else {
+            avail as usize
+        }
+    }
+
+    /// Number of samples that can be written before the buffer is full.
+    pub fn available_write(&self) -> usize {
+        self.capacity - 1 - self.available_read()
+    }
+
+    /// Write samples into the ring buffer (producer side).
+    ///
+    /// Returns the number of samples actually written (may be less than
+    /// `data.len()` if the buffer is nearly full).
+    pub fn write(&self, data: &[i16]) -> usize {
+        let avail = self.available_write();
+        let count = data.len().min(avail);
+        if count == 0 {
+            return 0;
+        }
+
+        let mut w = self.write_idx.load(Ordering::Relaxed) as usize;
+        let cap = self.capacity;
+        let buf_ptr = self.buf.as_ptr() as *mut i16;
+
+        for i in 0..count {
+            // SAFETY: w is always in [0, capacity) and we are the sole producer.
+            unsafe {
+                *buf_ptr.add(w) = data[i];
+            }
+            w += 1;
+            if w >= cap {
+                w = 0;
+            }
+        }
+
+        self.write_idx.store(w as i32, Ordering::Release);
+        count
+    }
+
+    /// Read samples from the ring buffer (consumer side).
+    ///
+    /// Returns the number of samples actually read (may be less than
+    /// `out.len()` if the buffer doesn't have enough data).
+    pub fn read(&self, out: &mut [i16]) -> usize {
+        let avail = self.available_read();
+        let count = out.len().min(avail);
+        if count == 0 {
+            return 0;
+        }
+
+        let mut r = self.read_idx.load(Ordering::Relaxed) as usize;
+        let cap = self.capacity;
+        let buf_ptr = self.buf.as_ptr();
+
+        for i in 0..count {
+            // SAFETY: r is always in [0, capacity) and we are the sole consumer.
+            unsafe {
+                out[i] = *buf_ptr.add(r);
+            }
+            r += 1;
+            if r >= cap {
+                r = 0;
+            }
+        }
+
+        self.read_idx.store(r as i32, Ordering::Release);
+        count
+    }
+
+    /// Get a raw pointer to the buffer data (for FFI).
+    fn buf_ptr(&self) -> *mut i16 {
+        self.buf.as_ptr() as *mut i16
+    }
+
+    /// Get a raw pointer to the write index atomic (for FFI).
+    fn write_idx_ptr(&self) -> *mut AtomicI32 {
+        &self.write_idx as *const AtomicI32 as *mut AtomicI32
+    }
+
+    /// Get a raw pointer to the read index atomic (for FFI).
+    fn read_idx_ptr(&self) -> *mut AtomicI32 {
+        &self.read_idx as *const AtomicI32 as *mut AtomicI32
+    }
+}
+
+// SAFETY: The ring buffer is designed for SPSC use where producer and consumer
+// are on different threads. The atomic indices provide the synchronization.
+unsafe impl Send for RingBuffer {}
+unsafe impl Sync for RingBuffer {}
+
+// ---------------------------------------------------------------------------
+// Oboe Backend
+// ---------------------------------------------------------------------------
+
+/// Oboe-based audio backend for Android.
+///
+/// Owns two SPSC ring buffers (capture and playout) that are shared with
+/// the C++ Oboe callbacks via raw pointers. The Oboe callbacks run on
+/// high-priority audio threads managed by the Android audio system.
+pub struct OboeBackend {
+    capture_ring: RingBuffer,
+    playout_ring: RingBuffer,
+    started: bool,
+}
+
+impl OboeBackend {
+    /// Create a new backend with default ring buffer sizes (160 ms each).
+    pub fn new() -> Self {
+        Self {
+            capture_ring: RingBuffer::new(RING_CAPACITY),
+            playout_ring: RingBuffer::new(RING_CAPACITY),
+            started: false,
+        }
+    }
+
+    /// Start Oboe audio streams.
+    ///
+    /// This sets up the ring buffer pointers and calls into the C++ layer
+    /// to open and start the capture and playout Oboe streams.
+    pub fn start(&mut self) -> Result<(), anyhow::Error> {
+        if self.started {
+            return Ok(());
+        }
+
+        let config = WzpOboeConfig {
+            sample_rate: 48_000,
+            frames_per_burst: FRAME_SAMPLES as i32,
+            channel_count: 1,
+        };
+
+        let rings = WzpOboeRings {
+            capture_buf: self.capture_ring.buf_ptr(),
+            capture_capacity: self.capture_ring.capacity as i32,
+            capture_write_idx: self.capture_ring.write_idx_ptr(),
+            capture_read_idx: self.capture_ring.read_idx_ptr(),
+
+            playout_buf: self.playout_ring.buf_ptr(),
+            playout_capacity: self.playout_ring.capacity as i32,
+            playout_write_idx: self.playout_ring.write_idx_ptr(),
+            playout_read_idx: self.playout_ring.read_idx_ptr(),
+        };
+
+        let ret = unsafe { wzp_oboe_start(&config, &rings) };
+        if ret != 0 {
+            return Err(anyhow::anyhow!("wzp_oboe_start failed with code {}", ret));
+        }
+
+        self.started = true;
+        info!("Oboe backend started");
+        Ok(())
+    }
+
+    /// Stop Oboe audio streams.
+    pub fn stop(&mut self) {
+        if !self.started {
+            return;
+        }
+        unsafe { wzp_oboe_stop() };
+        self.started = false;
+        info!("Oboe backend stopped");
+    }
+
+    /// Read captured audio samples from the capture ring buffer.
+    ///
+    /// Returns the number of samples actually read. The caller should
+    /// provide a buffer of at least `FRAME_SAMPLES` (960) samples.
+    pub fn read_capture(&self, out: &mut [i16]) -> usize {
+        self.capture_ring.read(out)
+    }
+
+    /// Write audio samples to the playout ring buffer.
+    ///
+    /// Returns the number of samples actually written.
+    pub fn write_playout(&self, samples: &[i16]) -> usize {
+        self.playout_ring.write(samples)
+    }
+
+    /// Get the current capture latency in milliseconds (from Oboe).
+    #[allow(unused)]
+    pub fn capture_latency_ms(&self) -> f32 {
+        unsafe { wzp_oboe_capture_latency_ms() }
+    }
+
+    /// Get the current playout latency in milliseconds (from Oboe).
+    #[allow(unused)]
+    pub fn playout_latency_ms(&self) -> f32 {
+        unsafe { wzp_oboe_playout_latency_ms() }
+    }
+
+    /// Check if the Oboe streams are currently running.
+    #[allow(unused)]
+    pub fn is_running(&self) -> bool {
+        unsafe { wzp_oboe_is_running() != 0 }
+    }
+}
+
+impl Drop for OboeBackend {
+    fn drop(&mut self) {
+        self.stop();
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Thread affinity / priority helpers
+// ---------------------------------------------------------------------------
+
+/// Pin the current thread to the highest-numbered CPU cores (big cores on
+/// ARM big.LITTLE architectures). Falls back silently on failure.
+#[allow(unused)]
+pub fn pin_to_big_core() {
+    #[cfg(target_os = "android")]
+    {
+        unsafe {
+            let num_cpus = libc::sysconf(libc::_SC_NPROCESSORS_ONLN);
+            if num_cpus <= 0 {
+                warn!("pin_to_big_core: could not determine CPU count");
+                return;
+            }
+            let num_cpus = num_cpus as usize;
+
+            // Target the upper half of CPUs (big cores on most big.LITTLE SoCs)
+            let start = num_cpus / 2;
+            let mut set: libc::cpu_set_t = std::mem::zeroed();
+            libc::CPU_ZERO(&mut set);
+            for cpu in start..num_cpus {
+                libc::CPU_SET(cpu, &mut set);
+            }
+
+            let ret = libc::sched_setaffinity(
+                0, // current thread
+                std::mem::size_of::<libc::cpu_set_t>(),
+                &set,
+            );
+            if ret != 0 {
+                warn!("sched_setaffinity failed: {}", std::io::Error::last_os_error());
+            } else {
+                info!(start, num_cpus, "pinned to big cores");
+            }
+        }
+    }
+    #[cfg(not(target_os = "android"))]
+    {
+        // No-op on non-Android
+    }
+}
+
+/// Attempt to set SCHED_FIFO real-time priority for the current thread.
+/// Falls back silently on failure (requires appropriate permissions on Android).
+#[allow(unused)]
+pub fn set_realtime_priority() {
+    #[cfg(target_os = "android")]
+    {
+        unsafe {
+            let param = libc::sched_param {
+                sched_priority: 2, // Low RT priority — enough for audio, safe
+            };
+            let ret = libc::sched_setscheduler(0, libc::SCHED_FIFO, &param);
+            if ret != 0 {
+                warn!(
+                    "sched_setscheduler(SCHED_FIFO) failed: {}",
+                    std::io::Error::last_os_error()
+                );
+            } else {
+                info!("set SCHED_FIFO priority 2");
+            }
+        }
+    }
+    #[cfg(not(target_os = "android"))]
+    {
+        // No-op on non-Android
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn ring_buffer_write_read() {
+        let ring = RingBuffer::new(16);
+        let data = [1i16, 2, 3, 4, 5];
+        assert_eq!(ring.write(&data), 5);
+        assert_eq!(ring.available_read(), 5);
+
+        let mut out = [0i16; 5];
+        assert_eq!(ring.read(&mut out), 5);
+        assert_eq!(out, [1, 2, 3, 4, 5]);
+        assert_eq!(ring.available_read(), 0);
+    }
+
+    #[test]
+    fn ring_buffer_wraparound() {
+        let ring = RingBuffer::new(8);
+        let data = [10i16, 20, 30, 40, 50, 60]; // 6 samples, capacity 8 (usable 7)
+        assert_eq!(ring.write(&data), 6);
+
+        let mut out = [0i16; 4];
+        assert_eq!(ring.read(&mut out), 4);
+        assert_eq!(out, [10, 20, 30, 40]);
+
+        // Now write more, which should wrap around
+        let data2 = [70i16, 80, 90, 100];
+        assert_eq!(ring.write(&data2), 4);
+
+        let mut out2 = [0i16; 6];
+        assert_eq!(ring.read(&mut out2), 6);
+        assert_eq!(out2, [50, 60, 70, 80, 90, 100]);
+    }
+
+    #[test]
+    fn ring_buffer_full() {
+        let ring = RingBuffer::new(4); // usable capacity = 3
+        let data = [1i16, 2, 3, 4, 5];
+        assert_eq!(ring.write(&data), 3); // Only 3 fit
+        assert_eq!(ring.available_write(), 0);
+    }
+
+    #[test]
+    fn oboe_backend_stub_start_stop() {
+        let mut backend = OboeBackend::new();
+        backend.start().expect("stub start should succeed");
+        assert!(backend.started);
+        backend.stop();
+        assert!(!backend.started);
+    }
+}

crates/wzp-android/src/audio_ring.rs

@@ -0,0 +1,128 @@
+//! Lock-free SPSC ring buffer — "Reader-Detects-Lap" architecture.
+//!
+//! SPSC invariant: the producer ONLY writes `write_pos`, the consumer
+//! ONLY writes `read_pos`.  Neither thread touches the other's cursor.
+//!
+//! On overflow (writer laps the reader), the writer simply overwrites
+//! old buffer data.  The reader detects the lap via `available() >
+//! RING_CAPACITY` and snaps its own `read_pos` forward.
+//!
+//! Capacity is a power of 2 for bitmask indexing (no modulo).
+
+use std::sync::atomic::{AtomicU64, AtomicUsize, Ordering};
+
+/// Ring buffer capacity — power of 2 for bitmask indexing.
+/// 16384 samples = 341.3ms at 48kHz mono.  70% more headroom
+/// than the previous 9600 (200ms) for surviving Android GC pauses.
+const RING_CAPACITY: usize = 16384; // 2^14
+const RING_MASK: usize = RING_CAPACITY - 1;
+
+/// Lock-free single-producer single-consumer ring buffer for i16 PCM samples.
+pub struct AudioRing {
+    buf: Box<[i16]>,
+    /// Monotonically increasing write cursor. ONLY written by producer.
+    write_pos: AtomicUsize,
+    /// Monotonically increasing read cursor. ONLY written by consumer.
+    read_pos: AtomicUsize,
+    /// Incremented by reader when it detects it was lapped (overflow).
+    overflow_count: AtomicU64,
+    /// Incremented by reader when ring is empty (underrun).
+    underrun_count: AtomicU64,
+}
+
+// SAFETY: AudioRing is SPSC — one thread writes (producer), one reads (consumer).
+// The producer only writes write_pos. The consumer only writes read_pos.
+// Neither thread writes the other's cursor. Buffer indices are derived from
+// the owning thread's cursor, ensuring no concurrent access to the same index.
+unsafe impl Send for AudioRing {}
+unsafe impl Sync for AudioRing {}
+
+impl AudioRing {
+    pub fn new() -> Self {
+        debug_assert!(RING_CAPACITY.is_power_of_two());
+        Self {
+            buf: vec![0i16; RING_CAPACITY].into_boxed_slice(),
+            write_pos: AtomicUsize::new(0),
+            read_pos: AtomicUsize::new(0),
+            overflow_count: AtomicU64::new(0),
+            underrun_count: AtomicU64::new(0),
+        }
+    }
+
+    /// Number of samples available to read (clamped to capacity).
+    pub fn available(&self) -> usize {
+        let w = self.write_pos.load(Ordering::Acquire);
+        let r = self.read_pos.load(Ordering::Relaxed);
+        w.wrapping_sub(r).min(RING_CAPACITY)
+    }
+
+    /// Number of samples that can be written without overwriting unread data.
+    pub fn free_space(&self) -> usize {
+        RING_CAPACITY.saturating_sub(self.available())
+    }
+
+    /// Write samples into the ring. Returns number of samples written.
+    ///
+    /// If the ring is full, old data is silently overwritten.  The reader
+    /// will detect the lap and self-correct.  The writer NEVER touches
+    /// `read_pos` — this is the key invariant that prevents cursor desync.
+    pub fn write(&self, samples: &[i16]) -> usize {
+        let count = samples.len().min(RING_CAPACITY);
+        let w = self.write_pos.load(Ordering::Relaxed);
+
+        for i in 0..count {
+            unsafe {
+                let ptr = self.buf.as_ptr() as *mut i16;
+                *ptr.add((w + i) & RING_MASK) = samples[i];
+            }
+        }
+
+        self.write_pos.store(w.wrapping_add(count), Ordering::Release);
+        count
+    }
+
+    /// Read samples from the ring into `out`. Returns number of samples read.
+    ///
+    /// If the writer has lapped the reader (overflow), `read_pos` is snapped
+    /// forward to the oldest valid data.  This is safe because only the
+    /// reader thread writes `read_pos`.
+    pub fn read(&self, out: &mut [i16]) -> usize {
+        let w = self.write_pos.load(Ordering::Acquire);
+        let mut r = self.read_pos.load(Ordering::Relaxed);
+
+        let mut avail = w.wrapping_sub(r);
+
+        // Lap detection: writer has overwritten our unread data.
+        // Snap read_pos forward to oldest valid data in the buffer.
+        if avail > RING_CAPACITY {
+            r = w.wrapping_sub(RING_CAPACITY);
+            avail = RING_CAPACITY;
+            self.overflow_count.fetch_add(1, Ordering::Relaxed);
+        }
+
+        let count = out.len().min(avail);
+        if count == 0 {
+            if w == r {
+                self.underrun_count.fetch_add(1, Ordering::Relaxed);
+            }
+            return 0;
+        }
+
+        for i in 0..count {
+            out[i] = unsafe { *self.buf.as_ptr().add((r + i) & RING_MASK) };
+        }
+
+        self.read_pos.store(r.wrapping_add(count), Ordering::Release);
+        count
+    }
+
+    /// Number of overflow events (reader was lapped by writer).
+    pub fn overflow_count(&self) -> u64 {
+        self.overflow_count.load(Ordering::Relaxed)
+    }
+
+    /// Number of underrun events (reader found empty buffer).
+    pub fn underrun_count(&self) -> u64 {
+        self.underrun_count.load(Ordering::Relaxed)
+    }
+}

crates/wzp-android/src/commands.rs

@@ -0,0 +1,24 @@
+//! Engine commands sent from the JNI/UI thread to the engine.
+
+use wzp_proto::QualityProfile;
+
+/// Commands that can be sent to the running engine.
+pub enum EngineCommand {
+    /// Mute or unmute the microphone.
+    SetMute(bool),
+    /// Enable or disable speaker (loudspeaker) mode.
+    SetSpeaker(bool),
+    /// Force a specific quality profile (overrides adaptive logic).
+    ForceProfile(QualityProfile),
+    /// Stop the call and shut down the engine.
+    Stop,
+    /// Place a direct call to a fingerprint (requires signal connection).
+    PlaceCall { target_fingerprint: String },
+    /// Answer an incoming direct call.
+    AnswerCall {
+        call_id: String,
+        accept_mode: wzp_proto::CallAcceptMode,
+    },
+    /// Reject an incoming direct call.
+    RejectCall { call_id: String },
+}

crates/wzp-android/src/jni_bridge.rs

@@ -0,0 +1,447 @@
+//! JNI bridge for Android — thin layer between Kotlin and the WzpEngine.
+
+use std::panic;
+use std::sync::Once;
+
+use jni::objects::{JClass, JObject, JString};
+use jni::sys::{jboolean, jint, jlong, jstring};
+use jni::JNIEnv;
+use tracing::{error, info};
+use wzp_proto::QualityProfile;
+
+use crate::engine::{CallStartConfig, WzpEngine};
+
+/// Opaque engine handle passed to/from Kotlin as a `jlong`.
+struct EngineHandle {
+    engine: WzpEngine,
+}
+
+/// Recover the `EngineHandle` from a raw handle value.
+unsafe fn handle_ref(handle: jlong) -> &'static mut EngineHandle {
+    unsafe { &mut *(handle as *mut EngineHandle) }
+}
+
+/// 7 = auto (use relay's chosen profile)
+const PROFILE_AUTO: jint = 7;
+
+fn profile_from_int(value: jint) -> QualityProfile {
+    match value {
+        0 => QualityProfile::GOOD,            // Opus 24k
+        1 => QualityProfile::DEGRADED,        // Opus 6k
+        2 => QualityProfile::CATASTROPHIC,    // Codec2 1.2k
+        3 => QualityProfile {                 // Codec2 3.2k
+            codec: wzp_proto::CodecId::Codec2_3200,
+            fec_ratio: 0.5,
+            frame_duration_ms: 20,
+            frames_per_block: 5,
+        },
+        4 => QualityProfile::STUDIO_32K,      // Opus 32k
+        5 => QualityProfile::STUDIO_48K,      // Opus 48k
+        6 => QualityProfile::STUDIO_64K,      // Opus 64k
+        _ => QualityProfile::GOOD,            // auto falls back to GOOD
+    }
+}
+
+static INIT_LOGGING: Once = Once::new();
+
+/// Initialize tracing → Android logcat (tag "wzp_android").
+/// Safe to call multiple times — only the first call takes effect.
+fn init_logging() {
+    INIT_LOGGING.call_once(|| {
+        // Wrap in catch_unwind — sharded_slab allocation inside
+        // tracing_subscriber::registry() can crash on some Android
+        // devices if scudo malloc fails during early initialization.
+        let _ = std::panic::catch_unwind(|| {
+            use tracing_subscriber::layer::SubscriberExt;
+            use tracing_subscriber::util::SubscriberInitExt;
+            use tracing_subscriber::EnvFilter;
+            if let Ok(layer) = tracing_android::layer("wzp_android") {
+                // Filter: INFO for our crates, WARN for everything else.
+                // The jni crate emits VERBOSE logs for every method lookup
+                // (~10 lines per JNI call, 100+ calls/sec) which floods logcat
+                // and causes the system to kill the app.
+                let filter = EnvFilter::new("warn,wzp_android=info,wzp_proto=info,wzp_transport=info,wzp_codec=info,wzp_fec=info,wzp_crypto=info");
+                let _ = tracing_subscriber::registry()
+                    .with(layer)
+                    .with(filter)
+                    .try_init();
+            }
+        });
+    });
+}
+
+#[unsafe(no_mangle)]
+pub unsafe extern "system" fn Java_com_wzp_engine_WzpEngine_nativeInit(
+    _env: JNIEnv,
+    _class: JClass,
+) -> jlong {
+    let result = panic::catch_unwind(|| {
+        init_logging();
+        let handle = Box::new(EngineHandle {
+            engine: WzpEngine::new(),
+        });
+        Box::into_raw(handle) as jlong
+    });
+    match result {
+        Ok(h) => h,
+        Err(_) => 0,
+    }
+}
+
+#[unsafe(no_mangle)]
+pub unsafe extern "system" fn Java_com_wzp_engine_WzpEngine_nativeStartCall(
+    mut env: JNIEnv,
+    _class: JClass,
+    handle: jlong,
+    relay_addr_j: JString,
+    room_j: JString,
+    seed_hex_j: JString,
+    token_j: JString,
+    alias_j: JString,
+    profile_j: jint,
+) -> jint {
+    let result = panic::catch_unwind(panic::AssertUnwindSafe(|| {
+        let relay_addr: String = env.get_string(&relay_addr_j).map(|s| s.into()).unwrap_or_default();
+        let room: String = env.get_string(&room_j).map(|s| s.into()).unwrap_or_default();
+        let seed_hex: String = env.get_string(&seed_hex_j).map(|s| s.into()).unwrap_or_default();
+        let token: String = env.get_string(&token_j).map(|s| s.into()).unwrap_or_default();
+        let alias: String = env.get_string(&alias_j).map(|s| s.into()).unwrap_or_default();
+
+        let h = unsafe { handle_ref(handle) };
+
+        // Parse hex seed
+        let mut identity_seed = [0u8; 32];
+        if seed_hex.len() == 64 {
+            for i in 0..32 {
+                if let Ok(byte) = u8::from_str_radix(&seed_hex[i * 2..i * 2 + 2], 16) {
+                    identity_seed[i] = byte;
+                }
+            }
+        } else {
+            // Generate random seed if not provided
+            use rand::RngCore;
+            rand::thread_rng().fill_bytes(&mut identity_seed);
+        }
+
+        let config = CallStartConfig {
+            profile: profile_from_int(profile_j),
+            auto_profile: profile_j == PROFILE_AUTO,
+            relay_addr,
+            room,
+            auth_token: if token.is_empty() { Vec::new() } else { token.into_bytes() },
+            identity_seed,
+            alias: if alias.is_empty() { None } else { Some(alias) },
+        };
+
+        match h.engine.start_call(config) {
+            Ok(()) => 0,
+            Err(e) => {
+                error!("start_call failed: {e}");
+                -1
+            }
+        }
+    }));
+
+    match result {
+        Ok(code) => code,
+        Err(_) => -1,
+    }
+}
+
+#[unsafe(no_mangle)]
+pub unsafe extern "system" fn Java_com_wzp_engine_WzpEngine_nativeStopCall(
+    _env: JNIEnv,
+    _class: JClass,
+    handle: jlong,
+) {
+    let _ = panic::catch_unwind(panic::AssertUnwindSafe(|| {
+        let h = unsafe { handle_ref(handle) };
+        h.engine.stop_call();
+    }));
+}
+
+#[unsafe(no_mangle)]
+pub unsafe extern "system" fn Java_com_wzp_engine_WzpEngine_nativeSetMute(
+    _env: JNIEnv,
+    _class: JClass,
+    handle: jlong,
+    muted: jboolean,
+) {
+    let _ = panic::catch_unwind(panic::AssertUnwindSafe(|| {
+        let h = unsafe { handle_ref(handle) };
+        h.engine.set_mute(muted != 0);
+    }));
+}
+
+#[unsafe(no_mangle)]
+pub unsafe extern "system" fn Java_com_wzp_engine_WzpEngine_nativeSetSpeaker(
+    _env: JNIEnv,
+    _class: JClass,
+    handle: jlong,
+    speaker: jboolean,
+) {
+    let _ = panic::catch_unwind(panic::AssertUnwindSafe(|| {
+        let h = unsafe { handle_ref(handle) };
+        h.engine.set_speaker(speaker != 0);
+    }));
+}
+
+#[unsafe(no_mangle)]
+pub unsafe extern "system" fn Java_com_wzp_engine_WzpEngine_nativeGetStats<'a>(
+    mut env: JNIEnv<'a>,
+    _class: JClass,
+    handle: jlong,
+) -> jstring {
+    let result = panic::catch_unwind(panic::AssertUnwindSafe(|| {
+        let h = unsafe { handle_ref(handle) };
+        let stats = h.engine.get_stats();
+        serde_json::to_string(&stats).unwrap_or_else(|_| "{}".to_string())
+    }));
+
+    let json = match result {
+        Ok(s) => s,
+        Err(_) => "{}".to_string(),
+    };
+
+    env.new_string(&json)
+        .map(|s| s.into_raw())
+        .unwrap_or(JObject::null().into_raw())
+}
+
+#[unsafe(no_mangle)]
+pub unsafe extern "system" fn Java_com_wzp_engine_WzpEngine_nativeForceProfile(
+    _env: JNIEnv,
+    _class: JClass,
+    handle: jlong,
+    profile: jint,
+) {
+    let _ = panic::catch_unwind(panic::AssertUnwindSafe(|| {
+        let h = unsafe { handle_ref(handle) };
+        let qp = profile_from_int(profile);
+        h.engine.force_profile(qp);
+    }));
+}
+
+/// Write captured PCM samples from Kotlin AudioRecord into the engine's capture ring.
+/// pcm is a Java short[] array.
+#[unsafe(no_mangle)]
+pub unsafe extern "system" fn Java_com_wzp_engine_WzpEngine_nativeWriteAudio(
+    env: JNIEnv,
+    _class: JClass,
+    handle: jlong,
+    pcm: jni::objects::JShortArray,
+) -> jint {
+    let result = panic::catch_unwind(panic::AssertUnwindSafe(|| {
+        let h = unsafe { handle_ref(handle) };
+        let len = env.get_array_length(&pcm).unwrap_or(0) as usize;
+        if len == 0 {
+            return 0;
+        }
+        let mut buf = vec![0i16; len];
+        if env.get_short_array_region(&pcm, 0, &mut buf).is_err() {
+            return 0;
+        }
+        h.engine.write_audio(&buf) as jint
+    }));
+    result.unwrap_or(0)
+}
+
+/// Read decoded PCM samples from the engine's playout ring for Kotlin AudioTrack.
+/// pcm is a Java short[] array to fill. Returns number of samples actually read.
+#[unsafe(no_mangle)]
+pub unsafe extern "system" fn Java_com_wzp_engine_WzpEngine_nativeReadAudio(
+    env: JNIEnv,
+    _class: JClass,
+    handle: jlong,
+    pcm: jni::objects::JShortArray,
+) -> jint {
+    let result = panic::catch_unwind(panic::AssertUnwindSafe(|| {
+        let h = unsafe { handle_ref(handle) };
+        let len = env.get_array_length(&pcm).unwrap_or(0) as usize;
+        if len == 0 {
+            return 0;
+        }
+        let mut buf = vec![0i16; len];
+        let read = h.engine.read_audio(&mut buf);
+        if read > 0 {
+            let _ = env.set_short_array_region(&pcm, 0, &buf[..read]);
+        }
+        read as jint
+    }));
+    result.unwrap_or(0)
+}
+
+/// Write captured PCM from a DirectByteBuffer — zero JNI array copies.
+/// The ByteBuffer must contain little-endian i16 samples.
+/// Called from the AudioRecord capture thread.
+#[unsafe(no_mangle)]
+pub unsafe extern "system" fn Java_com_wzp_engine_WzpEngine_nativeWriteAudioDirect(
+    env: JNIEnv,
+    _class: JClass,
+    handle: jlong,
+    buffer: jni::objects::JByteBuffer,
+    sample_count: jint,
+) -> jint {
+    let result = panic::catch_unwind(panic::AssertUnwindSafe(|| {
+        let h = unsafe { handle_ref(handle) };
+        let ptr = env.get_direct_buffer_address(&buffer).unwrap_or(std::ptr::null_mut());
+        if ptr.is_null() || sample_count <= 0 {
+            return 0;
+        }
+        let samples = unsafe {
+            std::slice::from_raw_parts(ptr as *const i16, sample_count as usize)
+        };
+        h.engine.write_audio(samples) as jint
+    }));
+    result.unwrap_or(0)
+}
+
+/// Read decoded PCM into a DirectByteBuffer — zero JNI array copies.
+/// The ByteBuffer will be filled with little-endian i16 samples.
+/// Called from the AudioTrack playout thread.
+#[unsafe(no_mangle)]
+pub unsafe extern "system" fn Java_com_wzp_engine_WzpEngine_nativeReadAudioDirect(
+    env: JNIEnv,
+    _class: JClass,
+    handle: jlong,
+    buffer: jni::objects::JByteBuffer,
+    max_samples: jint,
+) -> jint {
+    let result = panic::catch_unwind(panic::AssertUnwindSafe(|| {
+        let h = unsafe { handle_ref(handle) };
+        let ptr = env.get_direct_buffer_address(&buffer).unwrap_or(std::ptr::null_mut());
+        if ptr.is_null() || max_samples <= 0 {
+            return 0;
+        }
+        let samples = unsafe {
+            std::slice::from_raw_parts_mut(ptr as *mut i16, max_samples as usize)
+        };
+        h.engine.read_audio(samples) as jint
+    }));
+    result.unwrap_or(0)
+}
+
+#[unsafe(no_mangle)]
+pub unsafe extern "system" fn Java_com_wzp_engine_WzpEngine_nativeDestroy(
+    _env: JNIEnv,
+    _class: JClass,
+    handle: jlong,
+) {
+    let _ = panic::catch_unwind(panic::AssertUnwindSafe(|| {
+        let h = unsafe { Box::from_raw(handle as *mut EngineHandle) };
+        drop(h);
+    }));
+}
+
+/// Ping a relay server — instance method, requires engine handle.
+/// Returns JSON `{"rtt_ms":N,"server_fingerprint":"hex"}` or null on failure.
+#[unsafe(no_mangle)]
+pub unsafe extern "system" fn Java_com_wzp_engine_WzpEngine_nativePingRelay<'a>(
+    mut env: JNIEnv<'a>,
+    _class: JClass,
+    handle: jlong,
+    relay_j: JString,
+) -> jstring {
+    let result = panic::catch_unwind(panic::AssertUnwindSafe(|| {
+        let h = unsafe { handle_ref(handle) };
+        let relay: String = env.get_string(&relay_j).map(|s| s.into()).unwrap_or_default();
+        match h.engine.ping_relay(&relay) {
+            Ok(json) => Some(json),
+            Err(_) => None,
+        }
+    }));
+
+    let json = match result {
+        Ok(Some(s)) => s,
+        _ => return JObject::null().into_raw(),
+    };
+    env.new_string(&json)
+        .map(|s| s.into_raw())
+        .unwrap_or(JObject::null().into_raw())
+}
+
+// ── Direct calling JNI functions ──
+
+/// Start persistent signaling connection to relay for direct calls.
+/// Returns 0 on success, -1 on error.
+#[unsafe(no_mangle)]
+pub unsafe extern "system" fn Java_com_wzp_engine_WzpEngine_nativeStartSignaling<'a>(
+    mut env: JNIEnv<'a>,
+    _class: JClass,
+    handle: jlong,
+    relay_addr_j: JString,
+    seed_hex_j: JString,
+    token_j: JString,
+    alias_j: JString,
+) -> jint {
+    let result = panic::catch_unwind(panic::AssertUnwindSafe(|| {
+        let h = unsafe { handle_ref(handle) };
+        let relay_addr: String = env.get_string(&relay_addr_j).map(|s| s.into()).unwrap_or_default();
+        let seed_hex: String = env.get_string(&seed_hex_j).map(|s| s.into()).unwrap_or_default();
+        let token: String = env.get_string(&token_j).map(|s| s.into()).unwrap_or_default();
+        let alias: String = env.get_string(&alias_j).map(|s| s.into()).unwrap_or_default();
+
+        h.engine.start_signaling(
+            &relay_addr,
+            &seed_hex,
+            if token.is_empty() { None } else { Some(&token) },
+            if alias.is_empty() { None } else { Some(&alias) },
+        )
+    }));
+
+    match result {
+        Ok(Ok(())) => 0,
+        Ok(Err(e)) => { error!("start_signaling failed: {e}"); -1 }
+        Err(_) => { error!("start_signaling panicked"); -1 }
+    }
+}
+
+/// Place a direct call to a target fingerprint.
+/// Returns 0 on success, -1 on error.
+#[unsafe(no_mangle)]
+pub unsafe extern "system" fn Java_com_wzp_engine_WzpEngine_nativePlaceCall<'a>(
+    mut env: JNIEnv<'a>,
+    _class: JClass,
+    handle: jlong,
+    target_fp_j: JString,
+) -> jint {
+    let result = panic::catch_unwind(panic::AssertUnwindSafe(|| {
+        let h = unsafe { handle_ref(handle) };
+        let target: String = env.get_string(&target_fp_j).map(|s| s.into()).unwrap_or_default();
+        h.engine.place_call(&target)
+    }));
+
+    match result {
+        Ok(Ok(())) => 0,
+        Ok(Err(e)) => { error!("place_call failed: {e}"); -1 }
+        Err(_) => { error!("place_call panicked"); -1 }
+    }
+}
+
+/// Answer an incoming direct call.
+/// mode: 0=Reject, 1=AcceptTrusted, 2=AcceptGeneric
+#[unsafe(no_mangle)]
+pub unsafe extern "system" fn Java_com_wzp_engine_WzpEngine_nativeAnswerCall<'a>(
+    mut env: JNIEnv<'a>,
+    _class: JClass,
+    handle: jlong,
+    call_id_j: JString,
+    mode: jint,
+) -> jint {
+    let result = panic::catch_unwind(panic::AssertUnwindSafe(|| {
+        let h = unsafe { handle_ref(handle) };
+        let call_id: String = env.get_string(&call_id_j).map(|s| s.into()).unwrap_or_default();
+        let accept_mode = match mode {
+            0 => wzp_proto::CallAcceptMode::Reject,
+            1 => wzp_proto::CallAcceptMode::AcceptTrusted,
+            _ => wzp_proto::CallAcceptMode::AcceptGeneric,
+        };
+        h.engine.answer_call(&call_id, accept_mode)
+    }));
+
+    match result {
+        Ok(Ok(())) => 0,
+        Ok(Err(e)) => { error!("answer_call failed: {e}"); -1 }
+        Err(_) => { error!("answer_call panicked"); -1 }
+    }
+}

crates/wzp-android/src/lib.rs

@@ -0,0 +1,18 @@
+//! WarzonePhone Android native VoIP engine.
+//!
+//! Provides:
+//! - Oboe audio backend with lock-free SPSC ring buffers
+//! - Engine orchestrator managing call lifecycle
+//! - Codec pipeline thread (encode/decode/FEC/jitter)
+//! - Call statistics and command interface
+//!
+//! On non-Android targets, the Oboe C++ layer compiles as a stub,
+//! allowing `cargo check` and unit tests on the host.
+
+pub mod audio_android;
+pub mod audio_ring;
+pub mod commands;
+pub mod engine;
+pub mod pipeline;
+pub mod stats;
+pub mod jni_bridge;

crates/wzp-android/src/pipeline.rs

@@ -0,0 +1,262 @@
+//! Codec pipeline — encode/decode with FEC and jitter buffer.
+//!
+//! Runs on a dedicated thread, processing 20 ms frames at 48 kHz.
+//! The pipeline is NOT Send/Sync (Opus encoder state) — it is owned
+//! exclusively by the codec thread.
+
+use tracing::{debug, warn};
+use wzp_codec::{AdaptiveDecoder, AdaptiveEncoder, AutoGainControl, EchoCanceller};
+use wzp_fec::{RaptorQFecDecoder, RaptorQFecEncoder};
+use wzp_proto::jitter::{JitterBuffer, PlayoutResult};
+use wzp_proto::quality::AdaptiveQualityController;
+use wzp_proto::traits::{AudioDecoder, AudioEncoder, FecDecoder, FecEncoder};
+use wzp_proto::traits::QualityController;
+use wzp_proto::{MediaPacket, QualityProfile};
+
+use crate::audio_android::FRAME_SAMPLES;
+
+/// Maximum encoded frame size (Opus worst case at highest bitrate).
+const MAX_ENCODED_BYTES: usize = 1275;
+
+/// Pipeline statistics snapshot.
+#[derive(Clone, Debug, Default)]
+pub struct PipelineStats {
+    pub frames_encoded: u64,
+    pub frames_decoded: u64,
+    pub underruns: u64,
+    pub jitter_depth: usize,
+    pub quality_tier: u8,
+}
+
+/// The codec pipeline: encode, FEC, jitter buffer, decode.
+///
+/// This struct is owned by the codec thread and not shared.
+pub struct Pipeline {
+    encoder: AdaptiveEncoder,
+    decoder: AdaptiveDecoder,
+    fec_encoder: RaptorQFecEncoder,
+    fec_decoder: RaptorQFecDecoder,
+    jitter_buffer: JitterBuffer,
+    quality_ctrl: AdaptiveQualityController,
+    /// Acoustic echo canceller applied before encoding.
+    aec: EchoCanceller,
+    /// Automatic gain control applied before encoding.
+    agc: AutoGainControl,
+    /// Last decoded PCM frame, used as the AEC far-end reference.
+    last_decoded_farend: Option<Vec<i16>>,
+    // Pre-allocated scratch buffers
+    capture_buf: Vec<i16>,
+    #[allow(dead_code)]
+    playout_buf: Vec<i16>,
+    encode_out: Vec<u8>,
+    // Stats counters
+    frames_encoded: u64,
+    frames_decoded: u64,
+    underruns: u64,
+}
+
+impl Pipeline {
+    /// Create a new pipeline configured for the given quality profile.
+    pub fn new(profile: QualityProfile) -> Result<Self, anyhow::Error> {
+        let encoder = AdaptiveEncoder::new(profile)
+            .map_err(|e| anyhow::anyhow!("encoder init: {e}"))?;
+        let decoder = AdaptiveDecoder::new(profile)
+            .map_err(|e| anyhow::anyhow!("decoder init: {e}"))?;
+        let fec_encoder =
+            RaptorQFecEncoder::with_defaults(profile.frames_per_block as usize);
+        let fec_decoder =
+            RaptorQFecDecoder::with_defaults(profile.frames_per_block as usize);
+        let jitter_buffer = JitterBuffer::new(10, 250, 3);
+        let quality_ctrl = AdaptiveQualityController::new();
+
+        Ok(Self {
+            encoder,
+            decoder,
+            fec_encoder,
+            fec_decoder,
+            jitter_buffer,
+            quality_ctrl,
+            aec: EchoCanceller::new(48000, 100), // 100 ms echo tail
+            agc: AutoGainControl::new(),
+            last_decoded_farend: None,
+            capture_buf: vec![0i16; FRAME_SAMPLES],
+            playout_buf: vec![0i16; FRAME_SAMPLES],
+            encode_out: vec![0u8; MAX_ENCODED_BYTES],
+            frames_encoded: 0,
+            frames_decoded: 0,
+            underruns: 0,
+        })
+    }
+
+    /// Encode a PCM frame into a compressed packet.
+    ///
+    /// If `muted` is true, a silence frame is encoded (all zeros).
+    /// Returns the encoded bytes, or `None` on encoder error.
+    pub fn encode_frame(&mut self, pcm: &[i16], muted: bool) -> Option<Vec<u8>> {
+        let input = if muted {
+            // Zero the capture buffer for silence
+            for s in self.capture_buf.iter_mut() {
+                *s = 0;
+            }
+            &self.capture_buf[..]
+        } else {
+            // Feed the last decoded playout as AEC far-end reference.
+            if let Some(ref farend) = self.last_decoded_farend {
+                self.aec.feed_farend(farend);
+            }
+
+            // Apply AEC + AGC to the captured PCM.
+            let len = pcm.len().min(self.capture_buf.len());
+            self.capture_buf[..len].copy_from_slice(&pcm[..len]);
+            self.aec.process_frame(&mut self.capture_buf[..len]);
+            self.agc.process_frame(&mut self.capture_buf[..len]);
+            &self.capture_buf[..len]
+        };
+
+        match self.encoder.encode(input, &mut self.encode_out) {
+            Ok(n) => {
+                self.frames_encoded += 1;
+                let encoded = self.encode_out[..n].to_vec();
+
+                // Feed into FEC encoder
+                if let Err(e) = self.fec_encoder.add_source_symbol(&encoded) {
+                    warn!("FEC encode error: {e}");
+                }
+
+                Some(encoded)
+            }
+            Err(e) => {
+                warn!("encode error: {e}");
+                None
+            }
+        }
+    }
+
+    /// Feed a received media packet into the jitter buffer.
+    pub fn feed_packet(&mut self, packet: MediaPacket) {
+        // Feed FEC symbols if present
+        let header = &packet.header;
+        if header.fec_block != 0 || header.fec_symbol != 0 {
+            let is_repair = header.is_repair;
+            if let Err(e) = self.fec_decoder.add_symbol(
+                header.fec_block,
+                header.fec_symbol,
+                is_repair,
+                &packet.payload,
+            ) {
+                debug!("FEC symbol feed error: {e}");
+            }
+        }
+
+        self.jitter_buffer.push(packet);
+    }
+
+    /// Decode the next frame from the jitter buffer.
+    ///
+    /// Returns decoded PCM samples, or `None` if the buffer is not ready.
+    /// Decoded PCM is also stored as the AEC far-end reference for the next
+    /// encode cycle.
+    pub fn decode_frame(&mut self) -> Option<Vec<i16>> {
+        let result = match self.jitter_buffer.pop() {
+            PlayoutResult::Packet(pkt) => {
+                let mut pcm = vec![0i16; FRAME_SAMPLES];
+                match self.decoder.decode(&pkt.payload, &mut pcm) {
+                    Ok(n) => {
+                        self.frames_decoded += 1;
+                        pcm.truncate(n);
+                        Some(pcm)
+                    }
+                    Err(e) => {
+                        warn!("decode error: {e}");
+                        // Attempt PLC
+                        self.generate_plc()
+                    }
+                }
+            }
+            PlayoutResult::Missing { seq } => {
+                debug!(seq, "jitter buffer: missing packet, generating PLC");
+                self.generate_plc()
+            }
+            PlayoutResult::NotReady => {
+                self.underruns += 1;
+                None
+            }
+        };
+
+        // Save decoded PCM as far-end reference for AEC.
+        if let Some(ref pcm) = result {
+            self.last_decoded_farend = Some(pcm.clone());
+        }
+
+        result
+    }
+
+    /// Generate packet loss concealment output.
+    fn generate_plc(&mut self) -> Option<Vec<i16>> {
+        let mut pcm = vec![0i16; FRAME_SAMPLES];
+        match self.decoder.decode_lost(&mut pcm) {
+            Ok(n) => {
+                self.frames_decoded += 1;
+                pcm.truncate(n);
+                Some(pcm)
+            }
+            Err(e) => {
+                warn!("PLC error: {e}");
+                None
+            }
+        }
+    }
+
+    /// Feed a quality report into the adaptive quality controller.
+    ///
+    /// Returns a new profile if a tier transition occurred.
+    #[allow(unused)]
+    pub fn observe_quality(
+        &mut self,
+        report: &wzp_proto::QualityReport,
+    ) -> Option<QualityProfile> {
+        let new_profile = self.quality_ctrl.observe(report);
+        if let Some(ref profile) = new_profile {
+            if let Err(e) = self.encoder.set_profile(*profile) {
+                warn!("encoder set_profile error: {e}");
+            }
+            if let Err(e) = self.decoder.set_profile(*profile) {
+                warn!("decoder set_profile error: {e}");
+            }
+        }
+        new_profile
+    }
+
+    /// Force a specific quality profile.
+    #[allow(unused)]
+    pub fn force_profile(&mut self, profile: QualityProfile) {
+        self.quality_ctrl.force_profile(profile);
+        if let Err(e) = self.encoder.set_profile(profile) {
+            warn!("encoder set_profile error: {e}");
+        }
+        if let Err(e) = self.decoder.set_profile(profile) {
+            warn!("decoder set_profile error: {e}");
+        }
+    }
+
+    /// Get current pipeline statistics.
+    pub fn stats(&self) -> PipelineStats {
+        PipelineStats {
+            frames_encoded: self.frames_encoded,
+            frames_decoded: self.frames_decoded,
+            underruns: self.underruns,
+            jitter_depth: self.jitter_buffer.stats().current_depth,
+            quality_tier: self.quality_ctrl.tier() as u8,
+        }
+    }
+
+    /// Enable or disable acoustic echo cancellation.
+    pub fn set_aec_enabled(&mut self, enabled: bool) {
+        self.aec.set_enabled(enabled);
+    }
+
+    /// Enable or disable automatic gain control.
+    pub fn set_agc_enabled(&mut self, enabled: bool) {
+        self.agc.set_enabled(enabled);
+    }
+}

crates/wzp-android/src/stats.rs

@@ -0,0 +1,101 @@
+//! Call statistics for the Android engine.
+
+/// State of the call.
+/// Serializes as integer for easy parsing on the Kotlin side:
+/// 0=Idle, 1=Connecting, 2=Active, 3=Reconnecting, 4=Closed
+#[derive(Clone, Debug, Default, PartialEq, Eq)]
+pub enum CallState {
+    #[default]
+    Idle,
+    Connecting,
+    Active,
+    Reconnecting,
+    Closed,
+    /// Connected to relay signal channel, registered for direct calls.
+    Registered,
+    /// Outgoing call ringing on callee's side.
+    Ringing,
+    /// Incoming call received, waiting for user to accept/reject.
+    IncomingCall,
+}
+
+impl serde::Serialize for CallState {
+    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
+        let n: u8 = match self {
+            CallState::Idle => 0,
+            CallState::Connecting => 1,
+            CallState::Active => 2,
+            CallState::Reconnecting => 3,
+            CallState::Closed => 4,
+            CallState::Registered => 5,
+            CallState::Ringing => 6,
+            CallState::IncomingCall => 7,
+        };
+        serializer.serialize_u8(n)
+    }
+}
+
+/// Aggregated call statistics, serializable for JNI bridge.
+#[derive(Clone, Debug, Default, serde::Serialize)]
+pub struct CallStats {
+    /// Current call state.
+    pub state: CallState,
+    /// Call duration in seconds.
+    pub duration_secs: f64,
+    /// Current quality tier (0=GOOD, 1=DEGRADED, 2=CATASTROPHIC).
+    pub quality_tier: u8,
+    /// Observed packet loss percentage.
+    pub loss_pct: f32,
+    /// Smoothed round-trip time in milliseconds.
+    pub rtt_ms: u32,
+    /// Jitter in milliseconds.
+    pub jitter_ms: u32,
+    /// Current jitter buffer depth in packets.
+    pub jitter_buffer_depth: usize,
+    /// Total frames encoded since call start.
+    pub frames_encoded: u64,
+    /// Total frames decoded since call start.
+    pub frames_decoded: u64,
+    /// Number of playout underruns (buffer empty when audio needed).
+    pub underruns: u64,
+    /// Frames recovered by FEC.
+    pub fec_recovered: u64,
+    /// Playout ring overflow count (reader was lapped by writer).
+    pub playout_overflows: u64,
+    /// Playout ring underrun count (reader found empty buffer).
+    pub playout_underruns: u64,
+    /// Capture ring overflow count.
+    pub capture_overflows: u64,
+    /// Current mic audio level (RMS of i16 samples, 0-32767).
+    pub audio_level: u32,
+    /// Our current outgoing codec name (e.g. "Opus24k", "Codec2_1200").
+    pub current_codec: String,
+    /// Last seen incoming codec from other participants.
+    pub peer_codec: String,
+    /// Whether auto quality mode is active.
+    pub auto_mode: bool,
+    /// Number of participants in the room (from last RoomUpdate).
+    pub room_participant_count: u32,
+    /// Participant list (fingerprint + optional alias) serialized as JSON array.
+    pub room_participants: Vec<RoomMember>,
+    /// SAS code for verbal verification (None if not in a call).
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub sas_code: Option<u32>,
+    /// Incoming call info (present when state == IncomingCall).
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub incoming_call_id: Option<String>,
+    /// Fingerprint of the caller (present when state == IncomingCall).
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub incoming_caller_fp: Option<String>,
+    /// Alias of the caller (present when state == IncomingCall).
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub incoming_caller_alias: Option<String>,
+}
+
+/// A room member entry, serialized into the stats JSON.
+#[derive(Clone, Debug, Default, serde::Serialize)]
+pub struct RoomMember {
+    pub fingerprint: String,
+    pub alias: Option<String>,
+    pub relay_label: Option<String>,
+}

crates/wzp-client/Cargo.toml

@@ -18,11 +18,76 @@ tracing-subscriber = { workspace = true }
 async-trait = { workspace = true }
 bytes = { workspace = true }
 anyhow = "1"
+serde = { workspace = true }
+serde_json = "1"
+chrono = "0.4"
+rustls = { version = "0.23", default-features = false, features = ["ring", "std"] }
 cpal = { version = "0.15", optional = true }
+libc = "0.2"
+
+# coreaudio-rs is Apple-framework-only; gate it to macOS so enabling
+# the `vpio` feature from a non-macOS target builds cleanly instead of
+# pulling in a crate that can only link against Apple frameworks.
+[target.'cfg(target_os = "macos")'.dependencies]
+coreaudio-rs = { version = "0.11", optional = true }
+
+# Windows-only: direct WASAPI bindings for the `windows-aec` feature.
+# `windows` is Microsoft's official Rust COM bindings crate. We pull in
+# only the audio + COM subfeatures we need — the crate is organized as
+# a massive optional-feature tree, so enabling just these keeps compile
+# times reasonable (~5s for these features vs ~60s for the full crate).
+[target.'cfg(target_os = "windows")'.dependencies]
+windows = { version = "0.58", optional = true, features = [
+    "Win32_Foundation",
+    "Win32_Media_Audio",
+    "Win32_Security",
+    "Win32_System_Com",
+    "Win32_System_Com_StructuredStorage",
+    "Win32_System_Threading",
+    "Win32_System_Variant",
+] }
+
+# Linux-only: WebRTC AEC (Audio Processing Module) bindings for the
+# `linux-aec` feature. This is the 0.3.x line of the `tonarino/
+# webrtc-audio-processing` crate, which links against Debian's
+# `libwebrtc-audio-processing-dev` apt package (0.3-1+b1 on Bookworm).
+#
+# Note: we attempted the 2.x line with its `bundled` sub-feature first
+# (which would give us AEC3 instead of AEC2), but both the crates.io
+# tarball AND the upstream git `main` branch of webrtc-audio-processing-sys
+# 2.0.3 hit a `meson setup --reconfigure` bug where the build.rs passes
+# --reconfigure unconditionally even on first-run empty build dirs,
+# causing the bundled build to fail with "Directory does not contain a
+# valid build tree". The 0.x line doesn't use bundled mode and sidesteps
+# this entirely by linking the apt-provided library. AEC2 is older than
+# AEC3 but still the same algorithm family — this is what PulseAudio's
+# module-echo-cancel and PipeWire's filter-chain use by default on
+# current Debian-family distros.
+[target.'cfg(target_os = "linux")'.dependencies]
+webrtc-audio-processing = { version = "0.3", optional = true }
 
 [features]
 default = []
 audio = ["cpal"]
+# vpio enables coreaudio-rs but that dep is itself gated to macOS above,
+# so enabling this feature on Windows/Linux is a no-op (the audio_vpio
+# module is also #[cfg(target_os = "macos")] in lib.rs).
+vpio = ["dep:coreaudio-rs"]
+# windows-aec enables a direct WASAPI capture backend that opens the
+# microphone under AudioCategory_Communications, turning on Windows's
+# OS-level communications audio processing (AEC + noise suppression +
+# AGC). The `windows` dep is itself target-gated to Windows above, so
+# enabling this feature on non-Windows targets is a no-op (the
+# audio_wasapi module is also #[cfg(target_os = "windows")] in lib.rs).
+windows-aec = ["dep:windows"]
+# linux-aec enables a CPAL + WebRTC AEC3 capture/playback backend that
+# runs the WebRTC Audio Processing Module (same algo as Chrome / Zoom /
+# Teams) in-process, using the playback PCM as the reference signal for
+# echo cancellation. The webrtc-audio-processing dep is target-gated to
+# Linux above, so enabling this feature on non-Linux targets is a no-op
+# (the audio_linux_aec module is also #[cfg(target_os = "linux")] in
+# lib.rs).
+linux-aec = ["dep:webrtc-audio-processing"]
 
 [[bin]]
 name = "wzp-client"

crates/wzp-client/src/audio_io.rs

@@ -3,12 +3,10 @@
 //! Both structs use 48 kHz, mono, i16 format to match the WarzonePhone codec
 //! pipeline. Frames are 960 samples (20 ms at 48 kHz).
 //!
-//! The cpal `Stream` type is not `Send`, so each struct spawns a dedicated OS
-//! thread that owns the stream. The public API exposes only `Send + Sync`
-//! channel handles.
+//! Audio callbacks are **lock-free**: they read/write directly to an `AudioRing`
+//! (atomic SPSC ring buffer). No Mutex, no channel, no allocation on the hot path.
 
 use std::sync::atomic::{AtomicBool, Ordering};
-use std::sync::mpsc;
 use std::sync::Arc;
 
 use anyhow::{anyhow, Context};
@@ -16,6 +14,8 @@ use cpal::traits::{DeviceTrait, HostTrait, StreamTrait};
 use cpal::{SampleFormat, SampleRate, StreamConfig};
 use tracing::{info, warn};
 
+use crate::audio_ring::AudioRing;
+
 /// Number of samples per 20 ms frame at 48 kHz mono.
 pub const FRAME_SAMPLES: usize = 960;
 
@@ -23,22 +23,24 @@ pub const FRAME_SAMPLES: usize = 960;
 // AudioCapture
 // ---------------------------------------------------------------------------
 
-/// Captures microphone input and yields 960-sample PCM frames.
+/// Captures microphone input via CPAL and writes PCM into a lock-free ring buffer.
 ///
 /// The cpal stream lives on a dedicated OS thread; this handle is `Send + Sync`.
 pub struct AudioCapture {
-    rx: mpsc::Receiver<Vec<i16>>,
+    ring: Arc<AudioRing>,
     running: Arc<AtomicBool>,
 }
 
 impl AudioCapture {
     /// Create and start capturing from the default input device at 48 kHz mono.
     pub fn start() -> Result<Self, anyhow::Error> {
-        let (tx, rx) = mpsc::sync_channel::<Vec<i16>>(64);
+        let ring = Arc::new(AudioRing::new());
         let running = Arc::new(AtomicBool::new(true));
-        let running_clone = running.clone();
 
-        let (init_tx, init_rx) = mpsc::sync_channel::<Result<(), String>>(1);
+        let (init_tx, init_rx) = std::sync::mpsc::sync_channel::<Result<(), String>>(1);
+
+        let ring_cb = ring.clone();
+        let running_clone = running.clone();
 
         std::thread::Builder::new()
             .name("wzp-audio-capture".into())
@@ -59,53 +61,51 @@ impl AudioCapture {
 
                     let use_f32 = !supports_i16_input(&device)?;
 
-                    let buf = Arc::new(std::sync::Mutex::new(
-                        Vec::<i16>::with_capacity(FRAME_SAMPLES),
-                    ));
                     let err_cb = |e: cpal::StreamError| {
                         warn!("input stream error: {e}");
                     };
 
+                    let logged_cb_size = Arc::new(AtomicBool::new(false));
+
                     let stream = if use_f32 {
-                        let buf = buf.clone();
-                        let tx = tx.clone();
+                        let ring = ring_cb.clone();
                         let running = running_clone.clone();
+                        let logged = logged_cb_size.clone();
                         device.build_input_stream(
                             &config,
                             move |data: &[f32], _: &cpal::InputCallbackInfo| {
                                 if !running.load(Ordering::Relaxed) {
                                     return;
                                 }
-                                let mut lock = buf.lock().unwrap();
-                                for &s in data {
-                                    lock.push(f32_to_i16(s));
-                                    if lock.len() == FRAME_SAMPLES {
-                                        let frame = lock.drain(..).collect();
-                                        let _ = tx.try_send(frame);
+                                if !logged.swap(true, Ordering::Relaxed) {
+                                    eprintln!("[audio] capture callback: {} f32 samples", data.len());
+                                }
+                                let mut tmp = [0i16; FRAME_SAMPLES];
+                                for chunk in data.chunks(FRAME_SAMPLES) {
+                                    let n = chunk.len();
+                                    for i in 0..n {
+                                        tmp[i] = f32_to_i16(chunk[i]);
                                     }
+                                    ring.write(&tmp[..n]);
                                 }
                             },
                             err_cb,
                             None,
                         )?
                     } else {
-                        let buf = buf.clone();
-                        let tx = tx.clone();
+                        let ring = ring_cb.clone();
                         let running = running_clone.clone();
+                        let logged = logged_cb_size.clone();
                         device.build_input_stream(
                             &config,
                             move |data: &[i16], _: &cpal::InputCallbackInfo| {
                                 if !running.load(Ordering::Relaxed) {
                                     return;
                                 }
-                                let mut lock = buf.lock().unwrap();
-                                for &s in data {
-                                    lock.push(s);
-                                    if lock.len() == FRAME_SAMPLES {
-                                        let frame = lock.drain(..).collect();
-                                        let _ = tx.try_send(frame);
-                                    }
+                                if !logged.swap(true, Ordering::Relaxed) {
+                                    eprintln!("[audio] capture callback: {} i16 samples", data.len());
                                 }
+                                ring.write(data);
                             },
                             err_cb,
                             None,
@@ -114,7 +114,6 @@ impl AudioCapture {
 
                     stream.play().context("failed to start input stream")?;
 
-                    // Signal success to the caller before parking.
                     let _ = init_tx.send(Ok(()));
 
                     // Keep stream alive until stopped.
@@ -135,15 +134,12 @@ impl AudioCapture {
             .map_err(|_| anyhow!("capture thread exited before signaling"))?
             .map_err(|e| anyhow!("{e}"))?;
 
-        Ok(Self { rx, running })
+        Ok(Self { ring, running })
     }
 
-    /// Read the next frame of 960 PCM samples (blocking until available).
-    ///
-    /// Returns `None` when the stream has been stopped or the channel is
-    /// disconnected.
-    pub fn read_frame(&self) -> Option<Vec<i16>> {
-        self.rx.recv().ok()
+    /// Get a reference to the capture ring buffer for direct polling.
+    pub fn ring(&self) -> &Arc<AudioRing> {
+        &self.ring
     }
 
     /// Stop capturing.
@@ -152,26 +148,34 @@ impl AudioCapture {
     }
 }
 
+impl Drop for AudioCapture {
+    fn drop(&mut self) {
+        self.stop();
+    }
+}
+
 // ---------------------------------------------------------------------------
 // AudioPlayback
 // ---------------------------------------------------------------------------
 
-/// Plays PCM frames through the default output device at 48 kHz mono.
+/// Plays PCM through the default output device, reading from a lock-free ring buffer.
 ///
 /// The cpal stream lives on a dedicated OS thread; this handle is `Send + Sync`.
 pub struct AudioPlayback {
-    tx: mpsc::SyncSender<Vec<i16>>,
+    ring: Arc<AudioRing>,
     running: Arc<AtomicBool>,
 }
 
 impl AudioPlayback {
     /// Create and start playback on the default output device at 48 kHz mono.
     pub fn start() -> Result<Self, anyhow::Error> {
-        let (tx, rx) = mpsc::sync_channel::<Vec<i16>>(64);
+        let ring = Arc::new(AudioRing::new());
         let running = Arc::new(AtomicBool::new(true));
-        let running_clone = running.clone();
 
-        let (init_tx, init_rx) = mpsc::sync_channel::<Result<(), String>>(1);
+        let (init_tx, init_rx) = std::sync::mpsc::sync_channel::<Result<(), String>>(1);
+
+        let ring_cb = ring.clone();
+        let running_clone = running.clone();
 
         std::thread::Builder::new()
             .name("wzp-audio-playback".into())
@@ -192,62 +196,40 @@ impl AudioPlayback {
 
                     let use_f32 = !supports_i16_output(&device)?;
 
-                    // Shared ring of samples the cpal callback drains from.
-                    let ring = Arc::new(std::sync::Mutex::new(
-                        std::collections::VecDeque::<i16>::with_capacity(FRAME_SAMPLES * 8),
-                    ));
-
-                    // Background drainer: moves frames from the mpsc channel into the ring.
-                    {
-                        let ring = ring.clone();
-                        let running = running_clone.clone();
-                        std::thread::Builder::new()
-                            .name("wzp-playback-drain".into())
-                            .spawn(move || {
-                                while running.load(Ordering::Relaxed) {
-                                    match rx.recv_timeout(std::time::Duration::from_millis(100)) {
-                                        Ok(frame) => {
-                                            let mut lock = ring.lock().unwrap();
-                                            lock.extend(frame);
-                                            while lock.len() > FRAME_SAMPLES * 16 {
-                                                lock.pop_front();
-                                            }
-                                        }
-                                        Err(mpsc::RecvTimeoutError::Timeout) => {}
-                                        Err(mpsc::RecvTimeoutError::Disconnected) => break,
-                                    }
-                                }
-                            })?;
-                    }
-
                     let err_cb = |e: cpal::StreamError| {
                         warn!("output stream error: {e}");
                     };
 
                     let stream = if use_f32 {
-                        let ring = ring.clone();
+                        let ring = ring_cb.clone();
                         device.build_output_stream(
                             &config,
                             move |data: &mut [f32], _: &cpal::OutputCallbackInfo| {
-                                let mut lock = ring.lock().unwrap();
-                                for sample in data.iter_mut() {
-                                    *sample = match lock.pop_front() {
-                                        Some(s) => i16_to_f32(s),
-                                        None => 0.0,
-                                    };
+                                let mut tmp = [0i16; FRAME_SAMPLES];
+                                for chunk in data.chunks_mut(FRAME_SAMPLES) {
+                                    let n = chunk.len();
+                                    let read = ring.read(&mut tmp[..n]);
+                                    for i in 0..read {
+                                        chunk[i] = i16_to_f32(tmp[i]);
+                                    }
+                                    // Fill remainder with silence if ring underran
+                                    for i in read..n {
+                                        chunk[i] = 0.0;
+                                    }
                                 }
                             },
                             err_cb,
                             None,
                         )?
                     } else {
-                        let ring = ring.clone();
+                        let ring = ring_cb.clone();
                         device.build_output_stream(
                             &config,
                             move |data: &mut [i16], _: &cpal::OutputCallbackInfo| {
-                                let mut lock = ring.lock().unwrap();
-                                for sample in data.iter_mut() {
-                                    *sample = lock.pop_front().unwrap_or(0);
+                                let read = ring.read(data);
+                                // Fill remainder with silence if ring underran
+                                for sample in &mut data[read..] {
+                                    *sample = 0;
                                 }
                             },
                             err_cb,
@@ -257,7 +239,6 @@ impl AudioPlayback {
 
                     stream.play().context("failed to start output stream")?;
 
-                    // Signal success to the caller before parking.
                     let _ = init_tx.send(Ok(()));
 
                     // Keep stream alive until stopped.
@@ -278,12 +259,12 @@ impl AudioPlayback {
             .map_err(|_| anyhow!("playback thread exited before signaling"))?
             .map_err(|e| anyhow!("{e}"))?;
 
-        Ok(Self { tx, running })
+        Ok(Self { ring, running })
     }
 
-    /// Write a frame of PCM samples for playback.
-    pub fn write_frame(&self, pcm: &[i16]) {
-        let _ = self.tx.try_send(pcm.to_vec());
+    /// Get a reference to the playout ring buffer for direct writing.
+    pub fn ring(&self) -> &Arc<AudioRing> {
+        &self.ring
     }
 
     /// Stop playback.
@@ -292,11 +273,16 @@ impl AudioPlayback {
     }
 }
 
+impl Drop for AudioPlayback {
+    fn drop(&mut self) {
+        self.stop();
+    }
+}
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 
-/// Check if the input device supports i16 at 48 kHz mono.
 fn supports_i16_input(device: &cpal::Device) -> Result<bool, anyhow::Error> {
     let supported = device
         .supported_input_configs()
@@ -313,7 +299,6 @@ fn supports_i16_input(device: &cpal::Device) -> Result<bool, anyhow::Error> {
     Ok(false)
 }
 
-/// Check if the output device supports i16 at 48 kHz mono.
 fn supports_i16_output(device: &cpal::Device) -> Result<bool, anyhow::Error> {
     let supported = device
         .supported_output_configs()

crates/wzp-client/src/audio_linux_aec.rs

@@ -0,0 +1,537 @@
+//! Linux AEC backend: CPAL capture + playback wired through the WebRTC Audio
+//! Processing Module (AEC3 + noise suppression + high-pass filter).
+//!
+//! This is the same algorithm used by Chrome WebRTC, Zoom, Teams, Jitsi, and
+//! any other "serious" Linux VoIP app. It runs in-process — no dependency on
+//! PulseAudio's module-echo-cancel or PipeWire's filter-chain, so it works
+//! identically on ALSA / PulseAudio / PipeWire systems.
+//!
+//! ## Architecture
+//!
+//! A single module-level `Arc<Mutex<Processor>>` is shared between the
+//! capture and playback paths. On each 20 ms frame (960 samples @ 48 kHz
+//! mono):
+//!
+//! - **Playback path**: `LinuxAecPlayback::start` spawns the usual CPAL
+//!   output thread, but wraps each chunk in a call to
+//!   `Processor::process_render_frame` **before** handing it to CPAL. That
+//!   gives APM an authoritative reference of exactly what's going out to
+//!   the speakers (same approach Zoom/Teams/Jitsi use). The AEC then knows
+//!   what to cancel when it sees echo in the capture stream.
+//!
+//! - **Capture path**: `LinuxAecCapture::start` spawns the usual CPAL
+//!   input thread, and runs `Processor::process_capture_frame` on each
+//!   incoming mic chunk **in place** before pushing it into the ring
+//!   buffer. The AEC subtracts the echo using the render reference it
+//!   saw on the playback side.
+//!
+//! APM is strict about frame size: it requires exactly 10 ms = 480 samples
+//! per call at 48 kHz. Our pipeline uses 20 ms = 960 samples, so each 20 ms
+//! frame is split into two 480-sample halves, APM is called twice, and the
+//! halves are stitched back together.
+//!
+//! APM only accepts f32 samples in `[-1.0, 1.0]`, so we convert i16 → f32
+//! before the call and f32 → i16 after (with clamping on the return path).
+//!
+//! ## Stream delay
+//!
+//! AEC needs to know roughly how long it takes between a sample being passed
+//! to `process_render_frame` and its echo showing up at `process_capture_frame`
+//! — i.e. the round trip through CPAL playback → speaker → air → microphone
+//! → CPAL capture. AEC3's internal estimator tracks this within a window
+//! around whatever hint we give it. We hardcode 60 ms as a reasonable
+//! starting point for typical Linux audio stacks; the delay estimator does
+//! the fine-tuning automatically.
+//!
+//! ## Thread safety
+//!
+//! The 0.3.x line of `webrtc-audio-processing` takes `&mut self` on both
+//! `process_capture_frame` and `process_render_frame`, so the `Processor`
+//! needs a `Mutex` around it for cross-thread sharing. The capture and
+//! playback threads each acquire the lock briefly (sub-millisecond per
+//! 10 ms frame) so contention is minimal at our frame rates.
+
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{Arc, Mutex, OnceLock};
+
+use anyhow::{anyhow, Context};
+use cpal::traits::{DeviceTrait, HostTrait, StreamTrait};
+use cpal::{SampleFormat, SampleRate, StreamConfig};
+use tracing::{info, warn};
+use webrtc_audio_processing::{
+    Config, EchoCancellation, EchoCancellationSuppressionLevel, InitializationConfig,
+    NoiseSuppression, NoiseSuppressionLevel, Processor, NUM_SAMPLES_PER_FRAME,
+};
+
+use crate::audio_ring::AudioRing;
+
+/// 20 ms at 48 kHz, mono — matches the rest of the pipeline and the codec.
+pub const FRAME_SAMPLES: usize = 960;
+/// APM requires strict 10 ms frames at 48 kHz = 480 samples per call.
+/// Imported from the webrtc-audio-processing crate so we can't drift out
+/// of sync with whatever sample rate / frame length the C++ lib is using.
+const APM_FRAME_SAMPLES: usize = NUM_SAMPLES_PER_FRAME as usize;
+const APM_NUM_CHANNELS: usize = 1;
+/// Round-trip delay hint passed to APM; the estimator refines from here.
+/// 60 ms is a reasonable default for CPAL on ALSA / PulseAudio / PipeWire.
+#[allow(dead_code)]
+const STREAM_DELAY_MS: i32 = 60;
+
+// ---------------------------------------------------------------------------
+// Shared APM instance
+// ---------------------------------------------------------------------------
+
+/// Module-level lazily-initialized APM. Shared between capture and playback
+/// so they operate on the same echo-cancellation state — the render frames
+/// pushed by playback are what the capture path subtracts from the mic input.
+/// Wrapped in a Mutex because the 0.3.x Processor takes `&mut self` on both
+/// process_capture_frame and process_render_frame.
+static PROCESSOR: OnceLock<Arc<Mutex<Processor>>> = OnceLock::new();
+
+fn get_or_init_processor() -> anyhow::Result<Arc<Mutex<Processor>>> {
+    if let Some(p) = PROCESSOR.get() {
+        return Ok(p.clone());
+    }
+    let init_config = InitializationConfig {
+        num_capture_channels: APM_NUM_CHANNELS as i32,
+        num_render_channels: APM_NUM_CHANNELS as i32,
+        ..Default::default()
+    };
+    let mut processor = Processor::new(&init_config)
+        .map_err(|e| anyhow!("webrtc APM init failed: {e:?}"))?;
+
+    let config = Config {
+        echo_cancellation: Some(EchoCancellation {
+            suppression_level: EchoCancellationSuppressionLevel::High,
+            stream_delay_ms: Some(STREAM_DELAY_MS),
+            enable_delay_agnostic: true,
+            enable_extended_filter: true,
+        }),
+        noise_suppression: Some(NoiseSuppression {
+            suppression_level: NoiseSuppressionLevel::High,
+        }),
+        enable_high_pass_filter: true,
+        // AGC left off for now — it can fight the Opus encoder's own gain
+        // staging and the adaptive-quality controller. Add later if users
+        // report low mic levels.
+        ..Default::default()
+    };
+    processor.set_config(config);
+
+    let arc = Arc::new(Mutex::new(processor));
+    let _ = PROCESSOR.set(arc.clone());
+    info!(
+        stream_delay_ms = STREAM_DELAY_MS,
+        "webrtc APM initialized (AEC High + NS High + HPF, AGC off)"
+    );
+    Ok(arc)
+}
+
+// ---------------------------------------------------------------------------
+// Helpers: i16 ↔ f32 and APM frame processing
+// ---------------------------------------------------------------------------
+
+#[inline]
+fn i16_to_f32(s: i16) -> f32 {
+    s as f32 / 32768.0
+}
+
+#[inline]
+fn f32_to_i16(s: f32) -> i16 {
+    (s.clamp(-1.0, 1.0) * 32767.0) as i16
+}
+
+/// Feed a 20 ms (960-sample) playback frame to APM as the render reference.
+/// Splits into two 10 ms halves because APM is strict about frame size.
+/// Takes the Mutex-wrapped Processor and locks briefly around each call.
+fn push_render_frame_20ms(apm: &Mutex<Processor>, pcm: &[i16]) {
+    debug_assert_eq!(pcm.len(), FRAME_SAMPLES);
+    let mut buf = [0f32; APM_FRAME_SAMPLES];
+    for half in pcm.chunks_exact(APM_FRAME_SAMPLES) {
+        for (i, &s) in half.iter().enumerate() {
+            buf[i] = i16_to_f32(s);
+        }
+        match apm.lock() {
+            Ok(mut p) => {
+                if let Err(e) = p.process_render_frame(&mut buf) {
+                    warn!("webrtc APM process_render_frame failed: {e:?}");
+                }
+            }
+            Err(_) => {
+                warn!("webrtc APM mutex poisoned in render path");
+                return;
+            }
+        }
+    }
+}
+
+/// Run a 20 ms (960-sample) capture frame through APM's echo cancellation
+/// in place. Splits into two 10 ms halves, runs APM on each, stitches
+/// results back into the caller's buffer. Briefly holds the Mutex once
+/// per 10 ms half.
+fn process_capture_frame_20ms(apm: &Mutex<Processor>, pcm: &mut [i16]) {
+    debug_assert_eq!(pcm.len(), FRAME_SAMPLES);
+    let mut buf = [0f32; APM_FRAME_SAMPLES];
+    for half in pcm.chunks_exact_mut(APM_FRAME_SAMPLES) {
+        for (i, &s) in half.iter().enumerate() {
+            buf[i] = i16_to_f32(s);
+        }
+        match apm.lock() {
+            Ok(mut p) => {
+                if let Err(e) = p.process_capture_frame(&mut buf) {
+                    warn!("webrtc APM process_capture_frame failed: {e:?}");
+                }
+            }
+            Err(_) => {
+                warn!("webrtc APM mutex poisoned in capture path");
+                return;
+            }
+        }
+        for (i, d) in half.iter_mut().enumerate() {
+            *d = f32_to_i16(buf[i]);
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// LinuxAecCapture — CPAL mic + WebRTC AEC capture-side processing
+// ---------------------------------------------------------------------------
+
+/// Microphone capture with WebRTC AEC3 applied in place before the codec
+/// sees the samples. Mirrors the public API of `audio_io::AudioCapture` so
+/// downstream code doesn't change.
+pub struct LinuxAecCapture {
+    ring: Arc<AudioRing>,
+    running: Arc<AtomicBool>,
+}
+
+impl LinuxAecCapture {
+    pub fn start() -> Result<Self, anyhow::Error> {
+        // Eagerly init the APM so the playback side can find it already
+        // configured, and so init errors surface on the caller thread
+        // instead of silently failing inside the capture thread.
+        let apm = get_or_init_processor()?;
+
+        let ring = Arc::new(AudioRing::new());
+        let running = Arc::new(AtomicBool::new(true));
+
+        let (init_tx, init_rx) = std::sync::mpsc::sync_channel::<Result<(), String>>(1);
+
+        let ring_cb = ring.clone();
+        let running_clone = running.clone();
+        let apm_capture = apm.clone();
+
+        std::thread::Builder::new()
+            .name("wzp-audio-capture-linuxaec".into())
+            .spawn(move || {
+                let result = (|| -> Result<(), anyhow::Error> {
+                    let host = cpal::default_host();
+                    let device = host
+                        .default_input_device()
+                        .ok_or_else(|| anyhow!("no default input audio device found"))?;
+                    info!(device = %device.name().unwrap_or_default(), "LinuxAEC: using input device");
+
+                    let config = StreamConfig {
+                        channels: 1,
+                        sample_rate: SampleRate(48_000),
+                        buffer_size: cpal::BufferSize::Default,
+                    };
+
+                    let use_f32 = !supports_i16_input(&device)?;
+
+                    let err_cb = |e: cpal::StreamError| {
+                        warn!("LinuxAEC input stream error: {e}");
+                    };
+
+                    // Leftover buffer for when CPAL gives us partial frames.
+                    // We need exactly 960-sample chunks to feed APM.
+                    let leftover = std::sync::Mutex::new(Vec::<i16>::with_capacity(FRAME_SAMPLES * 4));
+
+                    let stream = if use_f32 {
+                        let ring = ring_cb.clone();
+                        let running = running_clone.clone();
+                        let apm = apm_capture.clone();
+                        device.build_input_stream(
+                            &config,
+                            move |data: &[f32], _: &cpal::InputCallbackInfo| {
+                                if !running.load(Ordering::Relaxed) {
+                                    return;
+                                }
+                                let mut lv = leftover.lock().unwrap();
+                                lv.reserve(data.len());
+                                for &s in data {
+                                    lv.push(f32_to_i16(s));
+                                }
+                                drain_frames_through_apm(&mut lv, &apm, &ring);
+                            },
+                            err_cb,
+                            None,
+                        )?
+                    } else {
+                        let ring = ring_cb.clone();
+                        let running = running_clone.clone();
+                        let apm = apm_capture.clone();
+                        device.build_input_stream(
+                            &config,
+                            move |data: &[i16], _: &cpal::InputCallbackInfo| {
+                                if !running.load(Ordering::Relaxed) {
+                                    return;
+                                }
+                                let mut lv = leftover.lock().unwrap();
+                                lv.extend_from_slice(data);
+                                drain_frames_through_apm(&mut lv, &apm, &ring);
+                            },
+                            err_cb,
+                            None,
+                        )?
+                    };
+
+                    stream.play().context("failed to start LinuxAEC input stream")?;
+                    let _ = init_tx.send(Ok(()));
+                    info!("LinuxAEC capture started (AEC3 active)");
+
+                    while running_clone.load(Ordering::Relaxed) {
+                        std::thread::park_timeout(std::time::Duration::from_millis(200));
+                    }
+                    drop(stream);
+                    Ok(())
+                })();
+
+                if let Err(e) = result {
+                    let _ = init_tx.send(Err(e.to_string()));
+                }
+            })?;
+
+        init_rx
+            .recv()
+            .map_err(|_| anyhow!("LinuxAEC capture thread exited before signaling"))?
+            .map_err(|e| anyhow!("{e}"))?;
+
+        Ok(Self { ring, running })
+    }
+
+    pub fn ring(&self) -> &Arc<AudioRing> {
+        &self.ring
+    }
+
+    pub fn stop(&self) {
+        self.running.store(false, Ordering::Relaxed);
+    }
+}
+
+impl Drop for LinuxAecCapture {
+    fn drop(&mut self) {
+        self.stop();
+    }
+}
+
+/// Pull whole 960-sample frames out of the leftover buffer, run them through
+/// APM's capture-side processing, and push to the ring. Leaves any partial
+/// sub-960 remainder in `leftover` for the next callback.
+fn drain_frames_through_apm(leftover: &mut Vec<i16>, apm: &Mutex<Processor>, ring: &AudioRing) {
+    let mut frame = [0i16; FRAME_SAMPLES];
+    while leftover.len() >= FRAME_SAMPLES {
+        frame.copy_from_slice(&leftover[..FRAME_SAMPLES]);
+        process_capture_frame_20ms(apm, &mut frame);
+        ring.write(&frame);
+        leftover.drain(..FRAME_SAMPLES);
+    }
+}
+
+// ---------------------------------------------------------------------------
+// LinuxAecPlayback — CPAL speaker output + WebRTC AEC render-side tee
+// ---------------------------------------------------------------------------
+
+/// Speaker playback with a render-side tee: each frame written to CPAL is
+/// ALSO fed to APM via `process_render_frame` as the echo-cancellation
+/// reference signal. This is the "tee the playback ring" approach (Zoom,
+/// Teams, Jitsi) — deterministic, does not depend on PulseAudio loopback or
+/// PipeWire monitor sources.
+pub struct LinuxAecPlayback {
+    ring: Arc<AudioRing>,
+    running: Arc<AtomicBool>,
+}
+
+impl LinuxAecPlayback {
+    pub fn start() -> Result<Self, anyhow::Error> {
+        let apm = get_or_init_processor()?;
+
+        let ring = Arc::new(AudioRing::new());
+        let running = Arc::new(AtomicBool::new(true));
+
+        let (init_tx, init_rx) = std::sync::mpsc::sync_channel::<Result<(), String>>(1);
+
+        let ring_cb = ring.clone();
+        let running_clone = running.clone();
+        let apm_render = apm.clone();
+
+        std::thread::Builder::new()
+            .name("wzp-audio-playback-linuxaec".into())
+            .spawn(move || {
+                let result = (|| -> Result<(), anyhow::Error> {
+                    let host = cpal::default_host();
+                    let device = host
+                        .default_output_device()
+                        .ok_or_else(|| anyhow!("no default output audio device found"))?;
+                    info!(device = %device.name().unwrap_or_default(), "LinuxAEC: using output device");
+
+                    let config = StreamConfig {
+                        channels: 1,
+                        sample_rate: SampleRate(48_000),
+                        buffer_size: cpal::BufferSize::Default,
+                    };
+
+                    let use_f32 = !supports_i16_output(&device)?;
+
+                    let err_cb = |e: cpal::StreamError| {
+                        warn!("LinuxAEC output stream error: {e}");
+                    };
+
+                    // Same 960-sample batching approach as the capture side:
+                    // CPAL may ask for N samples in a callback where N doesn't
+                    // divide 960. We accumulate partial frames in a Vec and
+                    // feed APM as soon as we have a whole 20 ms frame.
+                    let carry = std::sync::Mutex::new(Vec::<i16>::with_capacity(FRAME_SAMPLES * 4));
+
+                    let stream = if use_f32 {
+                        let ring = ring_cb.clone();
+                        let apm = apm_render.clone();
+                        device.build_output_stream(
+                            &config,
+                            move |data: &mut [f32], _: &cpal::OutputCallbackInfo| {
+                                fill_output_and_tee_f32(data, &ring, &apm, &carry);
+                            },
+                            err_cb,
+                            None,
+                        )?
+                    } else {
+                        let ring = ring_cb.clone();
+                        let apm = apm_render.clone();
+                        device.build_output_stream(
+                            &config,
+                            move |data: &mut [i16], _: &cpal::OutputCallbackInfo| {
+                                fill_output_and_tee_i16(data, &ring, &apm, &carry);
+                            },
+                            err_cb,
+                            None,
+                        )?
+                    };
+
+                    stream.play().context("failed to start LinuxAEC output stream")?;
+                    let _ = init_tx.send(Ok(()));
+                    info!("LinuxAEC playback started (render tee active)");
+
+                    while running_clone.load(Ordering::Relaxed) {
+                        std::thread::park_timeout(std::time::Duration::from_millis(200));
+                    }
+                    drop(stream);
+                    Ok(())
+                })();
+
+                if let Err(e) = result {
+                    let _ = init_tx.send(Err(e.to_string()));
+                }
+            })?;
+
+        init_rx
+            .recv()
+            .map_err(|_| anyhow!("LinuxAEC playback thread exited before signaling"))?
+            .map_err(|e| anyhow!("{e}"))?;
+
+        Ok(Self { ring, running })
+    }
+
+    pub fn ring(&self) -> &Arc<AudioRing> {
+        &self.ring
+    }
+
+    pub fn stop(&self) {
+        self.running.store(false, Ordering::Relaxed);
+    }
+}
+
+impl Drop for LinuxAecPlayback {
+    fn drop(&mut self) {
+        self.stop();
+    }
+}
+
+fn fill_output_and_tee_i16(
+    data: &mut [i16],
+    ring: &AudioRing,
+    apm: &Mutex<Processor>,
+    carry: &std::sync::Mutex<Vec<i16>>,
+) {
+    let read = ring.read(data);
+    for s in &mut data[read..] {
+        *s = 0;
+    }
+    tee_render_samples(data, apm, carry);
+}
+
+fn fill_output_and_tee_f32(
+    data: &mut [f32],
+    ring: &AudioRing,
+    apm: &Mutex<Processor>,
+    carry: &std::sync::Mutex<Vec<i16>>,
+) {
+    let mut tmp = vec![0i16; data.len()];
+    let read = ring.read(&mut tmp);
+    for s in &mut tmp[read..] {
+        *s = 0;
+    }
+    for (d, &s) in data.iter_mut().zip(tmp.iter()) {
+        *d = i16_to_f32(s);
+    }
+    tee_render_samples(&tmp, apm, carry);
+}
+
+/// Push CPAL-bound samples into APM's render-side input for echo cancellation.
+/// Uses a carry buffer to batch into exact 960-sample (20 ms) frames.
+fn tee_render_samples(samples: &[i16], apm: &Mutex<Processor>, carry: &std::sync::Mutex<Vec<i16>>) {
+    let mut lv = carry.lock().unwrap();
+    lv.extend_from_slice(samples);
+    while lv.len() >= FRAME_SAMPLES {
+        let mut frame = [0i16; FRAME_SAMPLES];
+        frame.copy_from_slice(&lv[..FRAME_SAMPLES]);
+        push_render_frame_20ms(apm, &frame);
+        lv.drain(..FRAME_SAMPLES);
+    }
+}
+
+// ---------------------------------------------------------------------------
+// CPAL format helpers (duplicated from audio_io.rs to keep the modules
+// independent — each backend file is a self-contained unit)
+// ---------------------------------------------------------------------------
+
+fn supports_i16_input(device: &cpal::Device) -> Result<bool, anyhow::Error> {
+    let supported = device
+        .supported_input_configs()
+        .context("failed to query input configs")?;
+    for cfg in supported {
+        if cfg.sample_format() == SampleFormat::I16
+            && cfg.min_sample_rate() <= SampleRate(48_000)
+            && cfg.max_sample_rate() >= SampleRate(48_000)
+            && cfg.channels() >= 1
+        {
+            return Ok(true);
+        }
+    }
+    Ok(false)
+}
+
+fn supports_i16_output(device: &cpal::Device) -> Result<bool, anyhow::Error> {
+    let supported = device
+        .supported_output_configs()
+        .context("failed to query output configs")?;
+    for cfg in supported {
+        if cfg.sample_format() == SampleFormat::I16
+            && cfg.min_sample_rate() <= SampleRate(48_000)
+            && cfg.max_sample_rate() >= SampleRate(48_000)
+            && cfg.channels() >= 1
+        {
+            return Ok(true);
+        }
+    }
+    Ok(false)
+}

crates/wzp-client/src/audio_ring.rs

@@ -0,0 +1,122 @@
+//! Lock-free SPSC ring buffer — "Reader-Detects-Lap" architecture.
+//!
+//! SPSC invariant: the producer ONLY writes `write_pos`, the consumer
+//! ONLY writes `read_pos`.  Neither thread touches the other's cursor.
+//!
+//! On overflow (writer laps the reader), the writer simply overwrites
+//! old buffer data.  The reader detects the lap via `available() >
+//! RING_CAPACITY` and snaps its own `read_pos` forward.
+//!
+//! Capacity is a power of 2 for bitmask indexing (no modulo).
+
+use std::sync::atomic::{AtomicU64, AtomicUsize, Ordering};
+
+/// Ring buffer capacity — power of 2 for bitmask indexing.
+/// 16384 samples = 341.3ms at 48kHz mono.
+const RING_CAPACITY: usize = 16384; // 2^14
+const RING_MASK: usize = RING_CAPACITY - 1;
+
+/// Lock-free single-producer single-consumer ring buffer for i16 PCM samples.
+pub struct AudioRing {
+    buf: Box<[i16]>,
+    /// Monotonically increasing write cursor. ONLY written by producer.
+    write_pos: AtomicUsize,
+    /// Monotonically increasing read cursor. ONLY written by consumer.
+    read_pos: AtomicUsize,
+    /// Incremented by reader when it detects it was lapped (overflow).
+    overflow_count: AtomicU64,
+    /// Incremented by reader when ring is empty (underrun).
+    underrun_count: AtomicU64,
+}
+
+// SAFETY: AudioRing is SPSC — one thread writes (producer), one reads (consumer).
+// The producer only writes write_pos. The consumer only writes read_pos.
+// Neither thread writes the other's cursor. Buffer indices are derived from
+// the owning thread's cursor, ensuring no concurrent access to the same index.
+unsafe impl Send for AudioRing {}
+unsafe impl Sync for AudioRing {}
+
+impl AudioRing {
+    pub fn new() -> Self {
+        debug_assert!(RING_CAPACITY.is_power_of_two());
+        Self {
+            buf: vec![0i16; RING_CAPACITY].into_boxed_slice(),
+            write_pos: AtomicUsize::new(0),
+            read_pos: AtomicUsize::new(0),
+            overflow_count: AtomicU64::new(0),
+            underrun_count: AtomicU64::new(0),
+        }
+    }
+
+    /// Number of samples available to read (clamped to capacity).
+    pub fn available(&self) -> usize {
+        let w = self.write_pos.load(Ordering::Acquire);
+        let r = self.read_pos.load(Ordering::Relaxed);
+        w.wrapping_sub(r).min(RING_CAPACITY)
+    }
+
+    /// Write samples into the ring. Returns number of samples written.
+    ///
+    /// If the ring is full, old data is silently overwritten.  The reader
+    /// will detect the lap and self-correct.  The writer NEVER touches
+    /// `read_pos`.
+    pub fn write(&self, samples: &[i16]) -> usize {
+        let count = samples.len().min(RING_CAPACITY);
+        let w = self.write_pos.load(Ordering::Relaxed);
+
+        for i in 0..count {
+            unsafe {
+                let ptr = self.buf.as_ptr() as *mut i16;
+                *ptr.add((w + i) & RING_MASK) = samples[i];
+            }
+        }
+
+        self.write_pos
+            .store(w.wrapping_add(count), Ordering::Release);
+        count
+    }
+
+    /// Read samples from the ring into `out`. Returns number of samples read.
+    ///
+    /// If the writer has lapped the reader (overflow), `read_pos` is snapped
+    /// forward to the oldest valid data.
+    pub fn read(&self, out: &mut [i16]) -> usize {
+        let w = self.write_pos.load(Ordering::Acquire);
+        let mut r = self.read_pos.load(Ordering::Relaxed);
+
+        let mut avail = w.wrapping_sub(r);
+
+        // Lap detection: writer has overwritten our unread data.
+        if avail > RING_CAPACITY {
+            r = w.wrapping_sub(RING_CAPACITY);
+            avail = RING_CAPACITY;
+            self.overflow_count.fetch_add(1, Ordering::Relaxed);
+        }
+
+        let count = out.len().min(avail);
+        if count == 0 {
+            if w == r {
+                self.underrun_count.fetch_add(1, Ordering::Relaxed);
+            }
+            return 0;
+        }
+
+        for i in 0..count {
+            out[i] = unsafe { *self.buf.as_ptr().add((r + i) & RING_MASK) };
+        }
+
+        self.read_pos
+            .store(r.wrapping_add(count), Ordering::Release);
+        count
+    }
+
+    /// Number of overflow events (reader was lapped by writer).
+    pub fn overflow_count(&self) -> u64 {
+        self.overflow_count.load(Ordering::Relaxed)
+    }
+
+    /// Number of underrun events (reader found empty buffer).
+    pub fn underrun_count(&self) -> u64 {
+        self.underrun_count.load(Ordering::Relaxed)
+    }
+}

crates/wzp-client/src/audio_vpio.rs

@@ -0,0 +1,179 @@
+//! macOS Voice Processing I/O — uses Apple's VoiceProcessingIO audio unit
+//! for hardware-accelerated echo cancellation, AGC, and noise suppression.
+//!
+//! VoiceProcessingIO is a combined input+output unit that knows what's going
+//! to the speaker, so it can cancel the echo from the mic signal internally.
+//! This is the same engine FaceTime and other Apple apps use.
+
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::Arc;
+
+use anyhow::Context;
+use coreaudio::audio_unit::audio_format::LinearPcmFlags;
+use coreaudio::audio_unit::render_callback::{self, data};
+use coreaudio::audio_unit::{AudioUnit, Element, IOType, SampleFormat, Scope, StreamFormat};
+use coreaudio::sys;
+use tracing::info;
+
+use crate::audio_ring::AudioRing;
+
+/// Number of samples per 20 ms frame at 48 kHz mono.
+pub const FRAME_SAMPLES: usize = 960;
+
+/// Combined capture + playback via macOS VoiceProcessingIO.
+///
+/// The OS handles AEC internally — no manual far-end feeding needed.
+pub struct VpioAudio {
+    capture_ring: Arc<AudioRing>,
+    playout_ring: Arc<AudioRing>,
+    _audio_unit: AudioUnit,
+    running: Arc<AtomicBool>,
+}
+
+impl VpioAudio {
+    /// Start VoiceProcessingIO with AEC enabled.
+    pub fn start() -> Result<Self, anyhow::Error> {
+        let capture_ring = Arc::new(AudioRing::new());
+        let playout_ring = Arc::new(AudioRing::new());
+        let running = Arc::new(AtomicBool::new(true));
+
+        let mut au = AudioUnit::new(IOType::VoiceProcessingIO)
+            .context("failed to create VoiceProcessingIO audio unit")?;
+
+        // Must uninitialize before configuring properties.
+        au.uninitialize()
+            .context("failed to uninitialize VPIO for configuration")?;
+
+        // Enable input (mic) on Element::Input (bus 1).
+        let enable: u32 = 1;
+        au.set_property(
+            sys::kAudioOutputUnitProperty_EnableIO,
+            Scope::Input,
+            Element::Input,
+            Some(&enable),
+        )
+        .context("failed to enable VPIO input")?;
+
+        // Output (speaker) is enabled by default on VPIO, but be explicit.
+        au.set_property(
+            sys::kAudioOutputUnitProperty_EnableIO,
+            Scope::Output,
+            Element::Output,
+            Some(&enable),
+        )
+        .context("failed to enable VPIO output")?;
+
+        // Configure stream format: 48kHz mono f32 non-interleaved
+        let stream_format = StreamFormat {
+            sample_rate: 48_000.0,
+            sample_format: SampleFormat::F32,
+            flags: LinearPcmFlags::IS_FLOAT
+                | LinearPcmFlags::IS_PACKED
+                | LinearPcmFlags::IS_NON_INTERLEAVED,
+            channels: 1,
+        };
+
+        let asbd = stream_format.to_asbd();
+
+        // Input: set format on Output scope of Input element
+        // (= the format the AU delivers to us from the mic)
+        au.set_property(
+            sys::kAudioUnitProperty_StreamFormat,
+            Scope::Output,
+            Element::Input,
+            Some(&asbd),
+        )
+        .context("failed to set input stream format")?;
+
+        // Output: set format on Input scope of Output element
+        // (= the format we feed to the AU for the speaker)
+        au.set_property(
+            sys::kAudioUnitProperty_StreamFormat,
+            Scope::Input,
+            Element::Output,
+            Some(&asbd),
+        )
+        .context("failed to set output stream format")?;
+
+        // Set up input callback (mic capture with AEC applied)
+        let cap_ring = capture_ring.clone();
+        let cap_running = running.clone();
+        let logged = Arc::new(AtomicBool::new(false));
+        au.set_input_callback(
+            move |args: render_callback::Args<data::NonInterleaved<f32>>| {
+                if !cap_running.load(Ordering::Relaxed) {
+                    return Ok(());
+                }
+                let mut buffers = args.data.channels();
+                if let Some(ch) = buffers.next() {
+                    if !logged.swap(true, Ordering::Relaxed) {
+                        eprintln!("[vpio] capture callback: {} f32 samples", ch.len());
+                    }
+                    let mut tmp = [0i16; FRAME_SAMPLES];
+                    for chunk in ch.chunks(FRAME_SAMPLES) {
+                        let n = chunk.len();
+                        for i in 0..n {
+                            tmp[i] = (chunk[i].clamp(-1.0, 1.0) * i16::MAX as f32) as i16;
+                        }
+                        cap_ring.write(&tmp[..n]);
+                    }
+                }
+                Ok(())
+            },
+        )
+        .context("failed to set input callback")?;
+
+        // Set up output callback (speaker playback — AEC uses this as reference)
+        let play_ring = playout_ring.clone();
+        au.set_render_callback(
+            move |mut args: render_callback::Args<data::NonInterleaved<f32>>| {
+                let mut buffers = args.data.channels_mut();
+                if let Some(ch) = buffers.next() {
+                    let mut tmp = [0i16; FRAME_SAMPLES];
+                    for chunk in ch.chunks_mut(FRAME_SAMPLES) {
+                        let n = chunk.len();
+                        let read = play_ring.read(&mut tmp[..n]);
+                        for i in 0..read {
+                            chunk[i] = tmp[i] as f32 / i16::MAX as f32;
+                        }
+                        for i in read..n {
+                            chunk[i] = 0.0;
+                        }
+                    }
+                }
+                Ok(())
+            },
+        )
+        .context("failed to set render callback")?;
+
+        au.initialize().context("failed to initialize VoiceProcessingIO")?;
+        au.start().context("failed to start VoiceProcessingIO")?;
+
+        info!("VoiceProcessingIO started (OS-level AEC enabled)");
+
+        Ok(Self {
+            capture_ring,
+            playout_ring,
+            _audio_unit: au,
+            running,
+        })
+    }
+
+    pub fn capture_ring(&self) -> &Arc<AudioRing> {
+        &self.capture_ring
+    }
+
+    pub fn playout_ring(&self) -> &Arc<AudioRing> {
+        &self.playout_ring
+    }
+
+    pub fn stop(&self) {
+        self.running.store(false, Ordering::Relaxed);
+    }
+}
+
+impl Drop for VpioAudio {
+    fn drop(&mut self) {
+        self.stop();
+    }
+}

crates/wzp-client/src/audio_wasapi.rs

@@ -0,0 +1,332 @@
+//! Direct WASAPI microphone capture with Windows's OS-level AEC enabled.
+//!
+//! Bypasses CPAL and opens the default capture endpoint directly via
+//! `IMMDeviceEnumerator` + `IAudioClient2::SetClientProperties`, setting
+//! `AudioClientProperties.eCategory = AudioCategory_Communications`. That's
+//! the switch that tells Windows "this is a VoIP call" — the OS then
+//! enables its communications audio processing chain (AEC, noise
+//! suppression, automatic gain control) for the stream. AEC operates at
+//! the OS level using the currently-playing audio as the reference
+//! signal, so it cancels echo from our CPAL playback (and any other app's
+//! audio) without us having to plumb a reference signal ourselves.
+//!
+//! Platform: Windows only, compiled only when the `windows-aec` feature
+//! is enabled. Mirrors the public API of `audio_io::AudioCapture` so
+//! `wzp-client`'s lib.rs can transparently re-export either one as
+//! `AudioCapture`.
+
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::Arc;
+
+use anyhow::{anyhow, Context};
+use tracing::{info, warn};
+use windows::core::{Interface, GUID};
+use windows::Win32::Foundation::{CloseHandle, BOOL, WAIT_OBJECT_0};
+use windows::Win32::Media::Audio::{
+    eCapture, eCommunications, AudioCategory_Communications, AudioClientProperties,
+    IAudioCaptureClient, IAudioClient, IAudioClient2, IMMDeviceEnumerator, MMDeviceEnumerator,
+    AUDCLNT_SHAREMODE_SHARED, AUDCLNT_STREAMFLAGS_AUTOCONVERTPCM,
+    AUDCLNT_STREAMFLAGS_EVENTCALLBACK, AUDCLNT_STREAMFLAGS_SRC_DEFAULT_QUALITY, WAVEFORMATEX,
+    WAVE_FORMAT_PCM,
+};
+use windows::Win32::System::Com::{
+    CoCreateInstance, CoInitializeEx, CoUninitialize, CLSCTX_ALL, COINIT_MULTITHREADED,
+};
+use windows::Win32::System::Threading::{CreateEventW, WaitForSingleObject, INFINITE};
+
+use crate::audio_ring::AudioRing;
+
+/// 20 ms at 48 kHz, mono. Matches the rest of the audio pipeline.
+pub const FRAME_SAMPLES: usize = 960;
+
+/// Microphone capture via WASAPI with Windows's communications AEC enabled.
+///
+/// The WASAPI capture stream runs on a dedicated OS thread. This handle is
+/// `Send + Sync`. Dropping it stops the stream and joins the thread.
+pub struct WasapiAudioCapture {
+    ring: Arc<AudioRing>,
+    running: Arc<AtomicBool>,
+    thread: Option<std::thread::JoinHandle<()>>,
+}
+
+impl WasapiAudioCapture {
+    /// Open the default communications microphone, enable OS AEC, and start
+    /// streaming PCM into a lock-free ring buffer.
+    ///
+    /// Returns only after the capture thread has successfully initialized
+    /// the stream, or propagates the error back to the caller.
+    pub fn start() -> Result<Self, anyhow::Error> {
+        let ring = Arc::new(AudioRing::new());
+        let running = Arc::new(AtomicBool::new(true));
+
+        let (init_tx, init_rx) = std::sync::mpsc::sync_channel::<Result<(), String>>(1);
+        let ring_cb = ring.clone();
+        let running_cb = running.clone();
+
+        let thread = std::thread::Builder::new()
+            .name("wzp-audio-capture-wasapi".into())
+            .spawn(move || {
+                let result = unsafe { capture_thread_main(ring_cb, running_cb.clone(), &init_tx) };
+                if let Err(e) = result {
+                    warn!("wasapi capture thread exited with error: {e}");
+                    // If we failed before signaling init, signal now so the
+                    // caller unblocks. Double-send is harmless (channel is
+                    // bounded to 1 and we only hit the second send path on
+                    // late errors).
+                    let _ = init_tx.send(Err(e.to_string()));
+                }
+            })
+            .context("failed to spawn WASAPI capture thread")?;
+
+        init_rx
+            .recv()
+            .map_err(|_| anyhow!("WASAPI capture thread exited before signaling init"))?
+            .map_err(|e| anyhow!("{e}"))?;
+
+        Ok(Self {
+            ring,
+            running,
+            thread: Some(thread),
+        })
+    }
+
+    /// Get a reference to the capture ring buffer for direct polling.
+    pub fn ring(&self) -> &Arc<AudioRing> {
+        &self.ring
+    }
+
+    /// Stop capturing.
+    pub fn stop(&self) {
+        self.running.store(false, Ordering::Relaxed);
+    }
+}
+
+impl Drop for WasapiAudioCapture {
+    fn drop(&mut self) {
+        self.stop();
+        if let Some(handle) = self.thread.take() {
+            // Join best-effort. The thread loop polls `running` every 200ms
+            // via a short WaitForSingleObject timeout, so it should exit
+            // within ~200ms of `stop()`.
+            let _ = handle.join();
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// WASAPI thread entry point — everything below this line runs on the
+// dedicated wzp-audio-capture-wasapi thread.
+// ---------------------------------------------------------------------------
+
+unsafe fn capture_thread_main(
+    ring: Arc<AudioRing>,
+    running: Arc<AtomicBool>,
+    init_tx: &std::sync::mpsc::SyncSender<Result<(), String>>,
+) -> Result<(), anyhow::Error> {
+    // COM init for the capture thread. MULTITHREADED because we're not
+    // running a message pump. Must be balanced by CoUninitialize on exit.
+    CoInitializeEx(None, COINIT_MULTITHREADED)
+        .ok()
+        .context("CoInitializeEx failed")?;
+
+    // Use a guard struct so CoUninitialize runs even on early returns.
+    struct ComGuard;
+    impl Drop for ComGuard {
+        fn drop(&mut self) {
+            unsafe { CoUninitialize() };
+        }
+    }
+    let _com_guard = ComGuard;
+
+    let enumerator: IMMDeviceEnumerator =
+        CoCreateInstance(&MMDeviceEnumerator, None, CLSCTX_ALL)
+            .context("CoCreateInstance(MMDeviceEnumerator) failed")?;
+
+    // eCommunications role (not eConsole) — this picks the device the user
+    // has designated for communications in Sound Settings. It's the one
+    // Windows's AEC is actually tuned for and the one Teams/Zoom use.
+    let device = enumerator
+        .GetDefaultAudioEndpoint(eCapture, eCommunications)
+        .context("GetDefaultAudioEndpoint(eCapture, eCommunications) failed")?;
+
+    if let Ok(name) = device_name(&device) {
+        info!(device = %name, "opening WASAPI communications capture endpoint");
+    }
+
+    let audio_client: IAudioClient = device
+        .Activate(CLSCTX_ALL, None)
+        .context("IMMDevice::Activate(IAudioClient) failed")?;
+
+    // IAudioClient2 exposes SetClientProperties, which is the ONLY way to
+    // set AudioCategory_Communications pre-Initialize. Calling it on the
+    // base IAudioClient would not compile, and setting it after Initialize
+    // is a no-op.
+    let audio_client2: IAudioClient2 = audio_client
+        .cast()
+        .context("QueryInterface IAudioClient2 failed")?;
+
+    let mut props = AudioClientProperties {
+        cbSize: std::mem::size_of::<AudioClientProperties>() as u32,
+        bIsOffload: BOOL(0),
+        eCategory: AudioCategory_Communications,
+        // 0 = AUDCLNT_STREAMOPTIONS_NONE. The `windows` crate doesn't
+        // export the enum constant in all versions, so use 0 directly.
+        Options: Default::default(),
+    };
+    audio_client2
+        .SetClientProperties(&mut props as *mut _)
+        .context("SetClientProperties(AudioCategory_Communications) failed")?;
+
+    // Request 48 kHz mono i16 directly. AUDCLNT_STREAMFLAGS_AUTOCONVERTPCM
+    // tells Windows to do any needed format conversion inside the audio
+    // engine rather than rejecting our format. SRC_DEFAULT_QUALITY picks
+    // the standard Windows resampler quality (fine for voice).
+    let wave_format = WAVEFORMATEX {
+        wFormatTag: WAVE_FORMAT_PCM as u16,
+        nChannels: 1,
+        nSamplesPerSec: 48_000,
+        nAvgBytesPerSec: 48_000 * 2, // 1 ch * 2 bytes/sample * 48000 Hz
+        nBlockAlign: 2,              // 1 ch * 2 bytes/sample
+        wBitsPerSample: 16,
+        cbSize: 0,
+    };
+
+    // 1,000,000 hns = 100 ms buffer (hns = 100-nanosecond units). Windows
+    // treats this as the minimum; the engine may give us a larger one.
+    const BUFFER_DURATION_HNS: i64 = 1_000_000;
+
+    audio_client
+        .Initialize(
+            AUDCLNT_SHAREMODE_SHARED,
+            AUDCLNT_STREAMFLAGS_EVENTCALLBACK
+                | AUDCLNT_STREAMFLAGS_AUTOCONVERTPCM
+                | AUDCLNT_STREAMFLAGS_SRC_DEFAULT_QUALITY,
+            BUFFER_DURATION_HNS,
+            0,
+            &wave_format,
+            Some(&GUID::zeroed()),
+        )
+        .context("IAudioClient::Initialize failed — Windows rejected communications-mode 48k mono i16")?;
+
+    // Event-driven capture: Windows signals this handle each time a new
+    // audio packet is available. We wait on it from the loop below.
+    let event = CreateEventW(None, false, false, None)
+        .context("CreateEventW failed")?;
+    audio_client
+        .SetEventHandle(event)
+        .context("SetEventHandle failed")?;
+
+    let capture_client: IAudioCaptureClient = audio_client
+        .GetService()
+        .context("IAudioClient::GetService(IAudioCaptureClient) failed")?;
+
+    audio_client.Start().context("IAudioClient::Start failed")?;
+
+    // Signal to the parent thread that init succeeded before entering the
+    // hot loop. From this point on, errors get logged but don't propagate
+    // back to the caller (they'd just cause the ring buffer to stop
+    // filling, which the main thread detects as underruns).
+    let _ = init_tx.send(Ok(()));
+    info!("WASAPI communications-mode capture started with OS AEC enabled");
+
+    let mut logged_first_packet = false;
+
+    // Main capture loop. Exit when `running` goes false (from Drop or an
+    // explicit stop() call).
+    while running.load(Ordering::Relaxed) {
+        // 200 ms timeout so we check `running` regularly even if the audio
+        // engine stops delivering packets (e.g. device unplugged).
+        let wait = WaitForSingleObject(event, 200);
+        if wait.0 != WAIT_OBJECT_0.0 {
+            // Timeout or failure — just loop and re-check running.
+            continue;
+        }
+
+        // Drain all available packets. Windows may have queued more than
+        // one since we were last scheduled.
+        loop {
+            let packet_length = match capture_client.GetNextPacketSize() {
+                Ok(n) => n,
+                Err(e) => {
+                    warn!("GetNextPacketSize failed: {e}");
+                    break;
+                }
+            };
+            if packet_length == 0 {
+                break;
+            }
+
+            let mut buffer_ptr: *mut u8 = std::ptr::null_mut();
+            let mut num_frames: u32 = 0;
+            let mut flags: u32 = 0;
+            let mut device_position: u64 = 0;
+            let mut qpc_position: u64 = 0;
+
+            if let Err(e) = capture_client.GetBuffer(
+                &mut buffer_ptr,
+                &mut num_frames,
+                &mut flags,
+                Some(&mut device_position),
+                Some(&mut qpc_position),
+            ) {
+                warn!("GetBuffer failed: {e}");
+                break;
+            }
+
+            if num_frames > 0 && !buffer_ptr.is_null() {
+                if !logged_first_packet {
+                    info!(
+                        frames = num_frames,
+                        flags, "WASAPI capture: first packet received"
+                    );
+                    logged_first_packet = true;
+                }
+
+                // Because we asked for 48 kHz mono i16, each frame is
+                // exactly one i16. Windows's AUTOCONVERTPCM handles the
+                // conversion from whatever the engine mix format is.
+                let samples = std::slice::from_raw_parts(
+                    buffer_ptr as *const i16,
+                    num_frames as usize,
+                );
+                ring.write(samples);
+            }
+
+            if let Err(e) = capture_client.ReleaseBuffer(num_frames) {
+                warn!("ReleaseBuffer failed: {e}");
+                break;
+            }
+        }
+    }
+
+    info!("WASAPI capture thread stopping");
+    let _ = audio_client.Stop();
+    let _ = CloseHandle(event);
+    // _com_guard drops here, calling CoUninitialize.
+
+    // Silence INFINITE unused-import warning — it's referenced by the
+    // `windows` crate's WaitForSingleObject alternative but we use the
+    // 200 ms timeout variant instead. Explicit suppression for clarity.
+    let _ = INFINITE;
+
+    Ok(())
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/// Best-effort device ID string for logging. Grabbing the friendly name via
+/// PKEY_Device_FriendlyName requires IPropertyStore + PROPVARIANT plumbing
+/// that's far more ceremony than a log line justifies; the ID is already
+/// sufficient to confirm we opened the right endpoint.
+///
+/// Rust 2024 edition's `unsafe_op_in_unsafe_fn` lint requires explicit
+/// `unsafe { ... }` blocks inside `unsafe fn` bodies for each unsafe call,
+/// even though the whole function is already marked unsafe.
+unsafe fn device_name(
+    device: &windows::Win32::Media::Audio::IMMDevice,
+) -> Result<String, anyhow::Error> {
+    let id = unsafe { device.GetId() }.context("IMMDevice::GetId failed")?;
+    Ok(unsafe { id.to_string() }.unwrap_or_else(|_| "<non-utf16>".to_string()))
+}

crates/wzp-client/src/call.rs

@@ -2,17 +2,21 @@
 //!
 //! Pipeline: mic → encode → FEC → encrypt → send / recv → decrypt → FEC → decode → speaker
 
-use bytes::Bytes;
-use tracing::{debug, warn};
+use std::time::{Duration, Instant};
 
+use bytes::Bytes;
+use tracing::{debug, info, warn};
+
+use wzp_codec::{AutoGainControl, ComfortNoise, EchoCanceller, NoiseSupressor, SilenceDetector};
 use wzp_fec::{RaptorQFecDecoder, RaptorQFecEncoder};
 use wzp_proto::jitter::{JitterBuffer, PlayoutResult};
-use wzp_proto::packet::{MediaHeader, MediaPacket};
+use wzp_proto::packet::{MediaHeader, MediaPacket, MiniFrameContext};
 use wzp_proto::quality::AdaptiveQualityController;
 use wzp_proto::traits::{
     AudioDecoder, AudioEncoder, FecDecoder, FecEncoder,
 };
-use wzp_proto::QualityProfile;
+use wzp_proto::packet::QualityReport;
+use wzp_proto::{CodecId, QualityProfile};
 
 /// Configuration for a call session.
 pub struct CallConfig {
@@ -24,6 +28,28 @@ pub struct CallConfig {
     pub jitter_max: usize,
     /// Jitter buffer min depth before playout.
     pub jitter_min: usize,
+    /// Enable silence suppression (default: true).
+    pub suppression_enabled: bool,
+    /// RMS threshold for silence detection (default: 100.0 for i16 PCM).
+    pub silence_threshold_rms: f64,
+    /// Hangover frames before suppression begins (default: 5 = 100ms at 20ms frames).
+    pub silence_hangover_frames: u32,
+    /// Comfort noise amplitude (default: 50).
+    pub comfort_noise_level: i16,
+    /// Enable ML-based noise suppression via RNNoise (default: true).
+    pub noise_suppression: bool,
+    /// Enable mini-frame header compression (default: true).
+    /// When enabled, only every 50th frame carries a full 12-byte MediaHeader;
+    /// intermediate frames use a compact 4-byte MiniHeader.
+    pub mini_frames_enabled: bool,
+    /// AEC far-end delay compensation in milliseconds (default: 40).
+    /// Compensates for the round-trip audio latency from playout to mic capture.
+    pub aec_delay_ms: u32,
+    /// Enable adaptive jitter buffer (default: true).
+    ///
+    /// When true, the jitter buffer target depth is automatically adjusted
+    /// based on observed inter-arrival jitter (NetEq-inspired algorithm).
+    pub adaptive_jitter: bool,
 }
 
 impl Default for CallConfig {
@@ -33,6 +59,138 @@ impl Default for CallConfig {
             jitter_target: 10,
             jitter_max: 250,
             jitter_min: 3, // 60ms — low latency start, still smooths jitter
+            suppression_enabled: true,
+            silence_threshold_rms: 100.0,
+            silence_hangover_frames: 5,
+            comfort_noise_level: 50,
+            noise_suppression: true,
+            mini_frames_enabled: true,
+            adaptive_jitter: true,
+            aec_delay_ms: 40,
+        }
+    }
+}
+
+impl CallConfig {
+    /// Build a `CallConfig` tuned for the given quality profile.
+    pub fn from_profile(profile: QualityProfile) -> Self {
+        let (jitter_target, jitter_max, jitter_min) = if profile == QualityProfile::CATASTROPHIC {
+            // Catastrophic: larger jitter buffer to absorb spikes
+            (20, 500, 8)
+        } else if profile == QualityProfile::DEGRADED {
+            // Degraded: moderately deeper buffer
+            (15, 350, 5)
+        } else {
+            // Good: low-latency defaults
+            (10, 250, 3)
+        };
+        Self {
+            profile,
+            jitter_target,
+            jitter_max,
+            jitter_min,
+            ..Default::default()
+        }
+    }
+}
+
+/// Sliding-window quality adapter that reacts to relay `QualityReport`s.
+///
+/// Thresholds (per-report):
+///   - loss > 15% OR rtt > 200ms  => CATASTROPHIC
+///   - loss > 5%  OR rtt > 100ms  => DEGRADED
+///   - otherwise                   => GOOD
+///
+/// Hysteresis: a profile switch is only recommended after the new profile
+/// has been the recommendation for 3 or more consecutive reports.
+pub struct QualityAdapter {
+    /// Sliding window of the last N reports.
+    window: std::collections::VecDeque<QualityReport>,
+    /// Maximum window size.
+    max_window: usize,
+    /// Number of consecutive reports recommending the same (non-current) profile.
+    consecutive_same: u32,
+    /// The profile that the last `consecutive_same` reports recommended.
+    pending_profile: Option<QualityProfile>,
+}
+
+/// Number of consecutive reports required before accepting a switch.
+const HYSTERESIS_COUNT: u32 = 3;
+/// Default sliding window capacity.
+const ADAPTER_WINDOW: usize = 10;
+
+impl QualityAdapter {
+    pub fn new() -> Self {
+        Self {
+            window: std::collections::VecDeque::with_capacity(ADAPTER_WINDOW),
+            max_window: ADAPTER_WINDOW,
+            consecutive_same: 0,
+            pending_profile: None,
+        }
+    }
+
+    /// Record a new quality report from the relay.
+    pub fn ingest(&mut self, report: &QualityReport) {
+        if self.window.len() >= self.max_window {
+            self.window.pop_front();
+        }
+        self.window.push_back(*report);
+    }
+
+    /// Classify a single report into a recommended profile.
+    fn classify(report: &QualityReport) -> QualityProfile {
+        let loss = report.loss_percent();
+        let rtt = report.rtt_ms();
+
+        if loss > 15.0 || rtt > 200 {
+            QualityProfile::CATASTROPHIC
+        } else if loss > 5.0 || rtt > 100 {
+            QualityProfile::DEGRADED
+        } else {
+            QualityProfile::GOOD
+        }
+    }
+
+    /// Return the best profile based on the most recent report in the window.
+    pub fn recommended_profile(&self) -> QualityProfile {
+        match self.window.back() {
+            Some(report) => Self::classify(report),
+            None => QualityProfile::GOOD,
+        }
+    }
+
+    /// Determine if a profile switch should happen, applying hysteresis.
+    ///
+    /// Returns `Some(new_profile)` only when the recommendation has differed
+    /// from `current` for at least `HYSTERESIS_COUNT` consecutive reports.
+    pub fn should_switch(&mut self, current: &QualityProfile) -> Option<QualityProfile> {
+        let recommended = self.recommended_profile();
+
+        if recommended == *current {
+            // Conditions match current profile — reset pending state.
+            self.consecutive_same = 0;
+            self.pending_profile = None;
+            return None;
+        }
+
+        // Recommended differs from current.
+        match self.pending_profile {
+            Some(pending) if pending == recommended => {
+                self.consecutive_same += 1;
+            }
+            _ => {
+                // New or changed recommendation — restart counter.
+                self.pending_profile = Some(recommended);
+                self.consecutive_same = 1;
+            }
+        }
+
+        if self.consecutive_same >= HYSTERESIS_COUNT {
+            self.consecutive_same = 0;
+            self.pending_profile = None;
+            Some(recommended)
+        } else {
+            None
         }
     }
 }
@@ -53,6 +211,28 @@ pub struct CallEncoder {
     frame_in_block: u8,
     /// Timestamp counter (ms).
     timestamp_ms: u32,
+    /// Acoustic echo canceller (removes speaker echo from mic signal).
+    aec: EchoCanceller,
+    /// Automatic gain control (normalises mic level).
+    agc: AutoGainControl,
+    /// Silence detector for suppression.
+    silence_detector: SilenceDetector,
+    /// Whether silence suppression is enabled.
+    suppression_enabled: bool,
+    /// Total frames suppressed (telemetry).
+    frames_suppressed: u64,
+    /// Frames since last CN packet was sent.
+    cn_counter: u32,
+    /// Comfort noise amplitude level (stored for CN packet payload).
+    cn_level: i16,
+    /// ML-based noise suppressor (RNNoise).
+    denoiser: NoiseSupressor,
+    /// Mini-frame compression context (tracks last full header).
+    mini_context: MiniFrameContext,
+    /// Whether mini-frame header compression is enabled.
+    mini_frames_enabled: bool,
+    /// Frames encoded since the last full header was emitted.
+    frames_since_full: u32,
 }
 
 impl CallEncoder {
@@ -65,6 +245,37 @@ impl CallEncoder {
             block_id: 0,
             frame_in_block: 0,
             timestamp_ms: 0,
+            aec: EchoCanceller::with_delay(48000, 60, config.aec_delay_ms),
+            agc: AutoGainControl::new(),
+            silence_detector: SilenceDetector::new(
+                config.silence_threshold_rms,
+                config.silence_hangover_frames,
+            ),
+            suppression_enabled: config.suppression_enabled,
+            frames_suppressed: 0,
+            cn_counter: 0,
+            cn_level: config.comfort_noise_level,
+            denoiser: {
+                let mut d = NoiseSupressor::new();
+                d.set_enabled(config.noise_suppression);
+                d
+            },
+            mini_context: MiniFrameContext::default(),
+            mini_frames_enabled: config.mini_frames_enabled,
+            frames_since_full: 0,
+        }
+    }
+
+    /// Serialize a `MediaPacket` for transmission, applying mini-frame
+    /// compression when enabled.
+    ///
+    /// Returns compact wire bytes: either `[FRAME_TYPE_FULL][MediaHeader][payload]`
+    /// or `[FRAME_TYPE_MINI][MiniHeader][payload]`.
+    pub fn serialize_compact(&mut self, packet: &MediaPacket) -> Bytes {
+        if self.mini_frames_enabled {
+            packet.encode_compact(&mut self.mini_context, &mut self.frames_since_full)
+        } else {
+            packet.to_bytes()
         }
     }
 
@@ -73,6 +284,61 @@ impl CallEncoder {
     /// Input: 48kHz mono PCM, frame size depends on profile (960 for 20ms, 1920 for 40ms).
     /// Output: one or more MediaPackets to send.
     pub fn encode_frame(&mut self, pcm: &[i16]) -> Result<Vec<MediaPacket>, anyhow::Error> {
+        // Copy PCM into a mutable buffer for the processing pipeline.
+        let mut pcm_buf = pcm.to_vec();
+
+        // Step 1: Echo cancellation (far-end reference must have been fed already).
+        self.aec.process_frame(&mut pcm_buf);
+
+        // Step 2: Automatic gain control (normalise mic level).
+        self.agc.process_frame(&mut pcm_buf);
+
+        // Step 3: Noise suppression (RNNoise).
+        if self.denoiser.is_enabled() {
+            self.denoiser.process(&mut pcm_buf);
+        }
+
+        let pcm = &pcm_buf[..];
+
+        // Silence suppression: skip encoding silent frames, periodically send CN.
+        if self.suppression_enabled && self.silence_detector.is_silent(pcm) {
+            self.frames_suppressed += 1;
+            self.cn_counter += 1;
+
+            // Advance timestamp even for suppressed frames.
+            self.timestamp_ms = self
+                .timestamp_ms
+                .wrapping_add(self.profile.frame_duration_ms as u32);
+
+            // Every 10 frames (~200ms), send a comfort noise packet.
+            if self.cn_counter % 10 == 0 {
+                let cn_pkt = MediaPacket {
+                    header: MediaHeader {
+                        version: 0,
+                        is_repair: false,
+                        codec_id: CodecId::ComfortNoise,
+                        has_quality_report: false,
+                        fec_ratio_encoded: 0,
+                        seq: self.seq,
+                        timestamp: self.timestamp_ms,
+                        fec_block: self.block_id,
+                        fec_symbol: 0,
+                        reserved: 0,
+                        csrc_count: 0,
+                    },
+                    payload: Bytes::from(vec![self.cn_level as u8]),
+                    quality_report: None,
+                };
+                self.seq = self.seq.wrapping_add(1);
+                return Ok(vec![cn_pkt]);
+            }
+
+            return Ok(vec![]);
+        }
+
+        // Not silent — reset CN counter and proceed with normal encoding.
+        self.cn_counter = 0;
+
         // Encode audio
         let mut encoded = vec![0u8; self.audio_enc.max_frame_bytes()];
         let enc_len = self.audio_enc.encode(pcm, &mut encoded)?;
@@ -150,6 +416,24 @@ impl CallEncoder {
         self.frame_in_block = 0;
         Ok(())
     }
+
+    /// Feed decoded playout audio as the echo reference signal.
+    ///
+    /// Must be called with each decoded frame BEFORE the corresponding
+    /// microphone frame is processed.
+    pub fn feed_aec_farend(&mut self, farend: &[i16]) {
+        self.aec.feed_farend(farend);
+    }
+
+    /// Enable or disable acoustic echo cancellation.
+    pub fn set_aec_enabled(&mut self, enabled: bool) {
+        self.aec.set_enabled(enabled);
+    }
+
+    /// Enable or disable automatic gain control.
+    pub fn set_agc_enabled(&mut self, enabled: bool) {
+        self.agc.set_enabled(enabled);
+    }
 }
 
 /// Manages the recv/decode side of a call.
@@ -164,19 +448,42 @@ pub struct CallDecoder {
     pub quality: AdaptiveQualityController,
     /// Current profile.
     profile: QualityProfile,
+    /// Comfort noise generator for filling silent gaps.
+    comfort_noise: ComfortNoise,
+    /// Whether the last decoded frame was comfort noise.
+    last_was_cn: bool,
+    /// Mini-frame decompression context (tracks last full header baseline).
+    mini_context: MiniFrameContext,
 }
 
 impl CallDecoder {
     pub fn new(config: &CallConfig) -> Self {
+        let jitter = if config.adaptive_jitter {
+            JitterBuffer::new_adaptive(config.jitter_min, config.jitter_max)
+        } else {
+            JitterBuffer::new(config.jitter_target, config.jitter_max, config.jitter_min)
+        };
         Self {
             audio_dec: wzp_codec::create_decoder(config.profile),
             fec_dec: wzp_fec::create_decoder(&config.profile),
-            jitter: JitterBuffer::new(config.jitter_target, config.jitter_max, config.jitter_min),
+            jitter,
             quality: AdaptiveQualityController::new(),
             profile: config.profile,
+            comfort_noise: ComfortNoise::new(50),
+            last_was_cn: false,
+            mini_context: MiniFrameContext::default(),
         }
     }
 
+    /// Deserialize a compact wire-format buffer into a `MediaPacket`,
+    /// auto-detecting full vs mini headers.
+    ///
+    /// Returns `None` on malformed data or if a mini-frame arrives before
+    /// any full header baseline has been established.
+    pub fn deserialize_compact(&mut self, buf: &[u8]) -> Option<MediaPacket> {
+        MediaPacket::decode_compact(buf, &mut self.mini_context)
+    }
+
     /// Feed a received media packet into the decode pipeline.
     pub fn ingest(&mut self, packet: MediaPacket) {
         // Feed to FEC decoder
@@ -193,31 +500,101 @@ impl CallDecoder {
         }
     }
 
+    /// Switch the decoder to match an incoming packet's codec if it differs
+    /// from the current profile. This enables cross-codec interop (e.g. one
+    /// client sends Opus, the other sends Codec2).
+    fn switch_decoder_if_needed(&mut self, incoming_codec: CodecId) {
+        if incoming_codec == self.profile.codec || incoming_codec == CodecId::ComfortNoise {
+            return;
+        }
+        let new_profile = Self::profile_for_codec(incoming_codec);
+        info!(
+            from = ?self.profile.codec,
+            to = ?incoming_codec,
+            "decoder switching codec to match incoming packet"
+        );
+        if let Err(e) = self.audio_dec.set_profile(new_profile) {
+            warn!("failed to switch decoder profile: {e}");
+            return;
+        }
+        self.fec_dec = wzp_fec::create_decoder(&new_profile);
+        self.profile = new_profile;
+    }
+
+    /// Map a `CodecId` to a reasonable `QualityProfile` for decoding.
+    fn profile_for_codec(codec: CodecId) -> QualityProfile {
+        match codec {
+            CodecId::Opus24k => QualityProfile::GOOD,
+            CodecId::Opus16k => QualityProfile {
+                codec: CodecId::Opus16k,
+                fec_ratio: 0.3,
+                frame_duration_ms: 20,
+                frames_per_block: 5,
+            },
+            CodecId::Opus6k => QualityProfile::DEGRADED,
+            CodecId::Opus32k => QualityProfile::STUDIO_32K,
+            CodecId::Opus48k => QualityProfile::STUDIO_48K,
+            CodecId::Opus64k => QualityProfile::STUDIO_64K,
+            CodecId::Codec2_3200 => QualityProfile {
+                codec: CodecId::Codec2_3200,
+                fec_ratio: 0.5,
+                frame_duration_ms: 20,
+                frames_per_block: 5,
+            },
+            CodecId::Codec2_1200 => QualityProfile::CATASTROPHIC,
+            CodecId::ComfortNoise => QualityProfile::GOOD,
+        }
+    }
+
     /// Decode the next audio frame from the jitter buffer.
     ///
     /// Returns PCM samples (48kHz mono) or None if not ready.
     pub fn decode_next(&mut self, pcm: &mut [i16]) -> Option<usize> {
         match self.jitter.pop() {
             PlayoutResult::Packet(pkt) => {
-                match self.audio_dec.decode(&pkt.payload, pcm) {
+                // Comfort noise packet: generate CN instead of decoding audio.
+                if pkt.header.codec_id == CodecId::ComfortNoise {
+                    self.comfort_noise.generate(pcm);
+                    self.last_was_cn = true;
+                    self.jitter.record_decode();
+                    return Some(pcm.len());
+                }
+
+                // Auto-switch decoder if incoming codec differs from current.
+                self.switch_decoder_if_needed(pkt.header.codec_id);
+
+                self.last_was_cn = false;
+                let result = match self.audio_dec.decode(&pkt.payload, pcm) {
                     Ok(n) => Some(n),
                     Err(e) => {
                         warn!("decode error: {e}, using PLC");
                         self.audio_dec.decode_lost(pcm).ok()
                     }
+                };
+                if result.is_some() {
+                    self.jitter.record_decode();
                 }
+                result
             }
             PlayoutResult::Missing { seq } => {
                 // Only generate PLC if there are still packets buffered ahead.
                 // Otherwise we've drained everything — return None to stop.
                 if self.jitter.depth() > 0 {
                     debug!(seq, "packet loss, generating PLC");
-                    self.audio_dec.decode_lost(pcm).ok()
+                    let result = self.audio_dec.decode_lost(pcm).ok();
+                    if result.is_some() {
+                        self.jitter.record_decode();
+                    }
+                    result
                 } else {
+                    self.jitter.record_underrun();
                     None
                 }
             }
-            PlayoutResult::NotReady => None,
+            PlayoutResult::NotReady => {
+                self.jitter.record_underrun();
+                None
+            }
         }
     }
 
@@ -227,8 +604,54 @@ impl CallDecoder {
     }
 
     /// Get jitter buffer statistics.
-    pub fn jitter_stats(&self) -> wzp_proto::jitter::JitterStats {
-        self.jitter.stats().clone()
+    pub fn stats(&self) -> &wzp_proto::jitter::JitterStats {
+        self.jitter.stats()
+    }
+
+    /// Reset jitter buffer statistics counters.
+    pub fn reset_stats(&mut self) {
+        self.jitter.reset_stats();
+    }
+}
+
+/// Periodic telemetry logger for jitter buffer statistics.
+///
+/// Call `maybe_log` on each decode tick; it will emit a `tracing::info!` event
+/// no more frequently than the configured interval.
+pub struct JitterTelemetry {
+    interval: Duration,
+    last_report: Instant,
+}
+
+impl JitterTelemetry {
+    /// Create a new telemetry logger that reports at most once per `interval_secs`.
+    pub fn new(interval_secs: u64) -> Self {
+        Self {
+            interval: Duration::from_secs(interval_secs),
+            last_report: Instant::now(),
+        }
+    }
+
+    /// Log jitter statistics if the interval has elapsed. Returns `true` when a
+    /// log line was emitted.
+    pub fn maybe_log(&mut self, stats: &wzp_proto::jitter::JitterStats) -> bool {
+        let now = Instant::now();
+        if now.duration_since(self.last_report) >= self.interval {
+            info!(
+                buffer_depth = stats.current_depth,
+                underruns = stats.underruns,
+                overruns = stats.overruns,
+                late_packets = stats.packets_late,
+                total_received = stats.packets_received,
+                total_decoded = stats.total_decoded,
+                max_depth_seen = stats.max_depth_seen,
+                "jitter buffer telemetry"
+            );
+            self.last_report = now;
+            true
+        } else {
+            false
+        }
     }
 }
 
@@ -301,4 +724,279 @@ mod tests {
         let mut pcm = vec![0i16; 960];
         assert!(dec.decode_next(&mut pcm).is_none());
     }
+
+    // ---- QualityAdapter tests ----
+
+    /// Helper: build a QualityReport from human-readable loss% and RTT ms.
+    fn make_report(loss_pct_f: f32, rtt_ms: u16) -> QualityReport {
+        QualityReport {
+            loss_pct: (loss_pct_f / 100.0 * 255.0) as u8,
+            rtt_4ms: (rtt_ms / 4) as u8,
+            jitter_ms: 10,
+            bitrate_cap_kbps: 200,
+        }
+    }
+
+    #[test]
+    fn good_conditions_stays_good() {
+        let mut adapter = QualityAdapter::new();
+        let good = make_report(1.0, 40);
+        for _ in 0..10 {
+            adapter.ingest(&good);
+        }
+        assert_eq!(adapter.recommended_profile(), QualityProfile::GOOD);
+
+        let current = QualityProfile::GOOD;
+        for _ in 0..10 {
+            adapter.ingest(&good);
+            assert!(adapter.should_switch(&current).is_none());
+        }
+    }
+
+    #[test]
+    fn high_loss_degrades() {
+        let mut adapter = QualityAdapter::new();
+        // 8% loss, low RTT => DEGRADED
+        let degraded = make_report(8.0, 40);
+        let mut current = QualityProfile::GOOD;
+
+        // Feed 3 consecutive degraded reports to pass hysteresis
+        for _ in 0..3 {
+            adapter.ingest(&degraded);
+            if let Some(new) = adapter.should_switch(&current) {
+                current = new;
+            }
+        }
+        assert_eq!(current, QualityProfile::DEGRADED);
+    }
+
+    #[test]
+    fn catastrophic_conditions() {
+        let mut adapter = QualityAdapter::new();
+        // 20% loss => CATASTROPHIC
+        let terrible = make_report(20.0, 50);
+        let mut current = QualityProfile::GOOD;
+
+        for _ in 0..3 {
+            adapter.ingest(&terrible);
+            if let Some(new) = adapter.should_switch(&current) {
+                current = new;
+            }
+        }
+        assert_eq!(current, QualityProfile::CATASTROPHIC);
+
+        // Also test via high RTT alone (250ms > 200ms threshold)
+        let mut adapter2 = QualityAdapter::new();
+        let high_rtt = make_report(1.0, 252); // rtt_4ms rounds to 63 => 252ms
+        let mut current2 = QualityProfile::GOOD;
+
+        for _ in 0..3 {
+            adapter2.ingest(&high_rtt);
+            if let Some(new) = adapter2.should_switch(&current2) {
+                current2 = new;
+            }
+        }
+        assert_eq!(current2, QualityProfile::CATASTROPHIC);
+    }
+
+    #[test]
+    fn hysteresis_prevents_flapping() {
+        let mut adapter = QualityAdapter::new();
+        let good = make_report(1.0, 40);
+        let bad = make_report(8.0, 40); // DEGRADED
+        let current = QualityProfile::GOOD;
+
+        // Alternate good/bad — should never trigger a switch because
+        // we never get 3 consecutive same-recommendation reports.
+        for _ in 0..20 {
+            adapter.ingest(&bad);
+            assert!(adapter.should_switch(&current).is_none());
+            adapter.ingest(&good);
+            assert!(adapter.should_switch(&current).is_none());
+        }
+        assert_eq!(current, QualityProfile::GOOD);
+    }
+
+    #[test]
+    fn recovery_to_good() {
+        let mut adapter = QualityAdapter::new();
+        let bad = make_report(20.0, 50);
+        let good = make_report(1.0, 40);
+
+        // Drive to CATASTROPHIC first
+        let mut current = QualityProfile::GOOD;
+        for _ in 0..3 {
+            adapter.ingest(&bad);
+            if let Some(new) = adapter.should_switch(&current) {
+                current = new;
+            }
+        }
+        assert_eq!(current, QualityProfile::CATASTROPHIC);
+
+        // Now feed good reports — should recover to GOOD after 3 consecutive
+        for _ in 0..3 {
+            adapter.ingest(&good);
+            if let Some(new) = adapter.should_switch(&current) {
+                current = new;
+            }
+        }
+        assert_eq!(current, QualityProfile::GOOD);
+    }
+
+    #[test]
+    fn call_config_from_profile() {
+        let good = CallConfig::from_profile(QualityProfile::GOOD);
+        assert_eq!(good.profile, QualityProfile::GOOD);
+        assert_eq!(good.jitter_min, 3);
+
+        let degraded = CallConfig::from_profile(QualityProfile::DEGRADED);
+        assert_eq!(degraded.profile, QualityProfile::DEGRADED);
+        assert!(degraded.jitter_target > good.jitter_target);
+
+        let catastrophic = CallConfig::from_profile(QualityProfile::CATASTROPHIC);
+        assert_eq!(catastrophic.profile, QualityProfile::CATASTROPHIC);
+        assert!(catastrophic.jitter_max > degraded.jitter_max);
+    }
+
+    // ---- JitterStats telemetry tests ----
+
+    fn make_test_packet(seq: u16) -> MediaPacket {
+        MediaPacket {
+            header: MediaHeader {
+                version: 0,
+                is_repair: false,
+                codec_id: CodecId::Opus24k,
+                has_quality_report: false,
+                fec_ratio_encoded: 0,
+                seq,
+                timestamp: seq as u32 * 20,
+                fec_block: 0,
+                fec_symbol: seq as u8,
+                reserved: 0,
+                csrc_count: 0,
+            },
+            payload: Bytes::from(vec![0u8; 60]),
+            quality_report: None,
+        }
+    }
+
+    #[test]
+    fn stats_track_ingestion() {
+        let config = CallConfig::default();
+        let mut dec = CallDecoder::new(&config);
+
+        for i in 0..5u16 {
+            dec.ingest(make_test_packet(i));
+        }
+
+        let stats = dec.stats();
+        assert_eq!(stats.packets_received, 5);
+        assert_eq!(stats.current_depth, 5);
+        assert_eq!(stats.max_depth_seen, 5);
+    }
+
+    #[test]
+    fn stats_track_underruns() {
+        let config = CallConfig::default();
+        let mut dec = CallDecoder::new(&config);
+
+        // Empty buffer — decode_next should record underruns
+        let mut pcm = vec![0i16; 960];
+        dec.decode_next(&mut pcm);
+        dec.decode_next(&mut pcm);
+        dec.decode_next(&mut pcm);
+
+        assert_eq!(dec.stats().underruns, 3);
+    }
+
+    #[test]
+    fn stats_reset() {
+        let config = CallConfig::default();
+        let mut dec = CallDecoder::new(&config);
+
+        // Generate some stats: ingest packets and trigger underruns on empty buffer
+        for i in 0..3u16 {
+            dec.ingest(make_test_packet(i));
+        }
+        // Also call decode on empty decoder to get underruns
+        let config2 = CallConfig::default();
+        let mut dec2 = CallDecoder::new(&config2);
+        let mut pcm = vec![0i16; 960];
+        dec2.decode_next(&mut pcm); // underrun — nothing in buffer
+
+        assert!(dec.stats().packets_received > 0);
+        assert!(dec2.stats().underruns > 0);
+
+        // Test reset on the decoder with ingested packets
+        dec.reset_stats();
+        let stats = dec.stats();
+        assert_eq!(stats.packets_received, 0);
+        assert_eq!(stats.underruns, 0);
+        assert_eq!(stats.overruns, 0);
+        assert_eq!(stats.total_decoded, 0);
+        assert_eq!(stats.packets_late, 0);
+        assert_eq!(stats.max_depth_seen, 0);
+
+        // Test reset on the decoder with underruns
+        dec2.reset_stats();
+        assert_eq!(dec2.stats().underruns, 0);
+    }
+
+    #[test]
+    fn telemetry_respects_interval() {
+        use wzp_proto::jitter::JitterStats;
+
+        let mut telemetry = JitterTelemetry::new(60); // 60-second interval
+        let stats = JitterStats::default();
+
+        // First call right after creation — should not log because no time has passed
+        // (the interval hasn't elapsed since construction)
+        let logged = telemetry.maybe_log(&stats);
+        assert!(!logged, "should not log before interval elapses");
+    }
+
+    #[test]
+    fn silence_suppression_skips_silent_frames() {
+        let config = CallConfig {
+            suppression_enabled: true,
+            silence_threshold_rms: 100.0,
+            silence_hangover_frames: 5,
+            comfort_noise_level: 50,
+            ..Default::default()
+        };
+        let mut enc = CallEncoder::new(&config);
+
+        let silence = vec![0i16; 960];
+        let mut total_packets = 0;
+        let mut cn_packets = 0;
+
+        for _ in 0..20 {
+            let packets = enc.encode_frame(&silence).unwrap();
+            for p in &packets {
+                if p.header.codec_id == CodecId::ComfortNoise {
+                    cn_packets += 1;
+                    // CN payload should be a single byte with the noise level.
+                    assert_eq!(p.payload.len(), 1);
+                }
+            }
+            total_packets += packets.len();
+        }
+
+        // First 5 frames are hangover (not suppressed) => 5 normal source packets
+        // (plus potential repair packets from FEC block completion).
+        // Remaining 15 frames are suppressed; CN every 10 frames => 1 CN packet
+        // (cn_counter hits 10 on the 10th suppressed frame).
+        assert!(
+            total_packets < 20,
+            "suppression should reduce packet count, got {total_packets}"
+        );
+        assert!(
+            cn_packets >= 1,
+            "should have at least one CN packet, got {cn_packets}"
+        );
+        assert!(
+            enc.frames_suppressed > 0,
+            "frames_suppressed should be > 0"
+        );
+    }
 }

crates/wzp-client/src/cli.rs

@@ -40,6 +40,43 @@ struct CliArgs {
     send_file: Option<String>,
     record_file: Option<String>,
     echo_test_secs: Option<u32>,
+    drift_test_secs: Option<u32>,
+    sweep: bool,
+    seed_hex: Option<String>,
+    mnemonic: Option<String>,
+    room: Option<String>,
+    token: Option<String>,
+    _metrics_file: Option<String>,
+    version_check: bool,
+    /// Connect to relay for persistent signaling (direct calls).
+    signal: bool,
+    /// Place a direct call to a fingerprint (requires --signal).
+    call_target: Option<String>,
+}
+
+impl CliArgs {
+    /// Resolve the identity seed from --seed, --mnemonic, or generate a new one.
+    pub fn resolve_seed(&self) -> wzp_crypto::Seed {
+        if let Some(ref hex_str) = self.seed_hex {
+            let seed = wzp_crypto::Seed::from_hex(hex_str).expect("invalid --seed hex");
+            let id = seed.derive_identity();
+            let fp = id.public_identity().fingerprint;
+            info!(fingerprint = %fp, "identity from --seed");
+            seed
+        } else if let Some(ref words) = self.mnemonic {
+            let seed = wzp_crypto::Seed::from_mnemonic(words).expect("invalid --mnemonic");
+            let id = seed.derive_identity();
+            let fp = id.public_identity().fingerprint;
+            info!(fingerprint = %fp, "identity from --mnemonic");
+            seed
+        } else {
+            let seed = wzp_crypto::Seed::generate();
+            let id = seed.derive_identity();
+            let fp = id.public_identity().fingerprint;
+            info!(fingerprint = %fp, "generated ephemeral identity");
+            seed
+        }
+    }
 }
 
 fn parse_args() -> CliArgs {
@@ -49,12 +86,27 @@ fn parse_args() -> CliArgs {
     let mut send_file = None;
     let mut record_file = None;
     let mut echo_test_secs = None;
+    let mut drift_test_secs = None;
+    let mut sweep = false;
+    let mut seed_hex = None;
+    let mut mnemonic = None;
+    let mut room = None;
+    let mut token = None;
+    let mut metrics_file = None;
+    let mut version_check = false;
     let mut relay_str = None;
+    let mut signal = false;
+    let mut call_target = None;
 
     let mut i = 1;
     while i < args.len() {
         match args[i].as_str() {
             "--live" => live = true,
+            "--signal" => signal = true,
+            "--call" => {
+                i += 1;
+                call_target = Some(args.get(i).expect("--call requires a fingerprint").to_string());
+            }
             "--send-tone" => {
                 i += 1;
                 send_tone_secs = Some(
@@ -72,6 +124,37 @@ fn parse_args() -> CliArgs {
                         .to_string(),
                 );
             }
+            "--seed" => {
+                i += 1;
+                seed_hex = Some(args.get(i).expect("--seed requires hex string").to_string());
+            }
+            "--mnemonic" => {
+                // Consume all remaining words until next flag or end
+                i += 1;
+                let mut words = Vec::new();
+                while i < args.len() && !args[i].starts_with('-') {
+                    words.push(args[i].clone());
+                    i += 1;
+                }
+                i -= 1; // back up since outer loop will increment
+                mnemonic = Some(words.join(" "));
+            }
+            "--room" => {
+                i += 1;
+                room = Some(args.get(i).expect("--room requires a name").to_string());
+            }
+            "--token" => {
+                i += 1;
+                token = Some(args.get(i).expect("--token requires a value").to_string());
+            }
+            "--metrics-file" => {
+                i += 1;
+                metrics_file = Some(
+                    args.get(i)
+                        .expect("--metrics-file requires a path")
+                        .to_string(),
+                );
+            }
             "--record" => {
                 i += 1;
                 record_file = Some(
@@ -89,6 +172,17 @@ fn parse_args() -> CliArgs {
                         .expect("--echo-test value must be a number"),
                 );
             }
+            "--drift-test" => {
+                i += 1;
+                drift_test_secs = Some(
+                    args.get(i)
+                        .expect("--drift-test requires seconds")
+                        .parse()
+                        .expect("--drift-test value must be a number"),
+                );
+            }
+            "--sweep" => sweep = true,
+            "--version-check" => { version_check = true; }
             "--help" | "-h" => {
                 eprintln!("Usage: wzp-client [options] [relay-addr]");
                 eprintln!();
@@ -98,6 +192,13 @@ fn parse_args() -> CliArgs {
                 eprintln!("  --send-file <file>     Send a raw PCM file (48kHz mono s16le)");
                 eprintln!("  --record <file.raw>    Record received audio to raw PCM file");
                 eprintln!("  --echo-test <secs>     Run automated echo quality test");
+                eprintln!("  --drift-test <secs>    Run automated clock-drift measurement");
+                eprintln!("  --sweep                Run jitter buffer parameter sweep (local, no network)");
+                eprintln!("  --seed <hex>           Identity seed (64 hex chars, featherChat compatible)");
+                eprintln!("  --mnemonic <words...>  Identity seed as BIP39 mnemonic (24 words)");
+                eprintln!("  --room <name>          Room name (hashed for privacy before sending)");
+                eprintln!("  --token <token>        featherChat bearer token for relay auth");
+                eprintln!("  --metrics-file <path>  Write JSONL telemetry to file (1 line/sec)");
                 eprintln!("                         (48kHz mono s16le, play with ffplay -f s16le -ar 48000 -ch_layout mono file.raw)");
                 eprintln!();
                 eprintln!("Default relay: 127.0.0.1:4433");
@@ -127,23 +228,80 @@ fn parse_args() -> CliArgs {
         send_file,
         record_file,
         echo_test_secs,
+        drift_test_secs,
+        sweep,
+        seed_hex,
+        mnemonic,
+        room,
+        token,
+        _metrics_file: metrics_file,
+        version_check,
+        signal,
+        call_target,
     }
 }
 
 #[tokio::main]
 async fn main() -> anyhow::Result<()> {
     tracing_subscriber::fmt().init();
+    rustls::crypto::ring::default_provider()
+        .install_default()
+        .expect("failed to install rustls crypto provider");
 
     let cli = parse_args();
 
+    // --sweep runs locally (no network), so handle it before connecting.
+    if cli.sweep {
+        wzp_client::sweep::run_and_print_default_sweep();
+        return Ok(());
+    }
+
+    // --version-check: query relay version over QUIC and exit
+    if cli.version_check {
+        let client_config = wzp_transport::client_config();
+        let bind_addr: SocketAddr = "0.0.0.0:0".parse()?;
+        let endpoint = wzp_transport::create_endpoint(bind_addr, None)?;
+        let conn = wzp_transport::connect(&endpoint, cli.relay_addr, "version", client_config).await?;
+        match conn.accept_uni().await {
+            Ok(mut recv) => {
+                let data = recv.read_to_end(256).await.unwrap_or_default();
+                let version = String::from_utf8_lossy(&data);
+                println!("{} {}", cli.relay_addr, version.trim());
+            }
+            Err(e) => {
+                eprintln!("relay {} does not support version query: {e}", cli.relay_addr);
+            }
+        }
+        endpoint.close(0u32.into(), b"done");
+        return Ok(());
+    }
+
+    // --signal mode: persistent signaling for direct calls
+    if cli.signal {
+        let seed = cli.resolve_seed();
+        return run_signal_mode(cli.relay_addr, seed, cli.token, cli.call_target).await;
+    }
+
+    let seed = cli.resolve_seed();
+
     info!(
         relay = %cli.relay_addr,
         live = cli.live,
         send_tone = ?cli.send_tone_secs,
         record = ?cli.record_file,
+        room = ?cli.room,
         "WarzonePhone client"
     );
 
+    // Use raw room name as SNI (consistent with Android + Desktop clients for federation)
+    let sni = match &cli.room {
+        Some(name) => {
+            info!(room = %name, "using room name as SNI");
+            name.clone()
+        }
+        None => "default".to_string(),
+    };
+
     let client_config = wzp_transport::client_config();
     let bind_addr = if cli.relay_addr.is_ipv6() {
         "[::]:0".parse()?
@@ -152,12 +310,49 @@ async fn main() -> anyhow::Result<()> {
     };
     let endpoint = wzp_transport::create_endpoint(bind_addr, None)?;
     let connection =
-        wzp_transport::connect(&endpoint, cli.relay_addr, "localhost", client_config).await?;
+        wzp_transport::connect(&endpoint, cli.relay_addr, &sni, client_config).await?;
 
     info!("Connected to relay");
 
     let transport = Arc::new(wzp_transport::QuinnTransport::new(connection));
 
+    // Register shutdown handler so SIGTERM/SIGINT always closes QUIC cleanly.
+    // Without this, killed clients leave zombie connections on the relay for ~30s.
+    {
+        let shutdown_transport = transport.clone();
+        tokio::spawn(async move {
+            let mut sigterm = tokio::signal::unix::signal(tokio::signal::unix::SignalKind::terminate())
+                .expect("failed to register SIGTERM handler");
+            let mut sigint = tokio::signal::unix::signal(tokio::signal::unix::SignalKind::interrupt())
+                .expect("failed to register SIGINT handler");
+            tokio::select! {
+                _ = sigterm.recv() => { info!("SIGTERM received, closing connection..."); }
+                _ = sigint.recv() => { info!("SIGINT received, closing connection..."); }
+            }
+            // Close the QUIC connection immediately (APPLICATION_CLOSE frame).
+            // Don't call process::exit — let the main task detect the closed
+            // connection and perform clean shutdown (e.g., save recordings).
+            shutdown_transport.connection().close(0u32.into(), b"shutdown");
+        });
+    }
+
+    // Send auth token if provided (relay with --auth-url expects this first)
+    if let Some(ref token) = cli.token {
+        let auth = wzp_proto::SignalMessage::AuthToken {
+            token: token.clone(),
+        };
+        transport.send_signal(&auth).await?;
+        info!("auth token sent");
+    }
+
+    // Crypto handshake — establishes verified identity + session key
+    let _crypto_session = wzp_client::handshake::perform_handshake(
+        &*transport,
+        &seed.0,
+        None, // alias — desktop client doesn't set one yet
+    ).await?;
+    info!("crypto handshake complete");
+
     if cli.live {
         #[cfg(feature = "audio")]
         {
@@ -172,6 +367,15 @@ async fn main() -> anyhow::Result<()> {
         wzp_client::echo_test::print_report(&result);
         transport.close().await?;
         Ok(())
+    } else if let Some(secs) = cli.drift_test_secs {
+        let config = wzp_client::drift_test::DriftTestConfig {
+            duration_secs: secs,
+            tone_freq_hz: 440.0,
+        };
+        let result = wzp_client::drift_test::run_drift_test(&*transport, &config).await?;
+        wzp_client::drift_test::print_drift_report(&result);
+        transport.close().await?;
+        Ok(())
     } else if cli.send_tone_secs.is_some() || cli.send_file.is_some() || cli.record_file.is_some() {
         run_file_mode(transport, cli.send_tone_secs, cli.send_file, cli.record_file).await
     } else {
@@ -218,6 +422,10 @@ async fn run_silence(transport: Arc<wzp_transport::QuinnTransport>) -> anyhow::R
     }
 
     info!(total_source, total_repair, total_bytes, "done — closing");
+    let hangup = wzp_proto::SignalMessage::Hangup {
+        reason: wzp_proto::HangupReason::Normal,
+    };
+    transport.send_signal(&hangup).await.ok();
     transport.close().await?;
     Ok(())
 }
@@ -364,16 +572,20 @@ async fn run_file_mode(
     // Wait for send to finish (or ctrl+c in recv)
     let _ = send_handle.await;
 
-    // If send finished but recv is still going, give it a moment then stop
+    // Send Hangup signal so the relay knows we're done
+    let hangup = wzp_proto::SignalMessage::Hangup {
+        reason: wzp_proto::HangupReason::Normal,
+    };
+    transport.send_signal(&hangup).await.ok();
+
     let all_pcm = if record_file.is_some() {
-        // Wait a bit for remaining packets after sender finishes
         tokio::time::sleep(tokio::time::Duration::from_secs(2)).await;
-        // The recv task will be aborted when we drop it, but first
-        // let's signal it by closing transport
         transport.close().await?;
         recv_handle.await.unwrap_or_default()
     } else {
-        recv_handle.await.unwrap_or_default()
+        transport.close().await?;
+        recv_handle.abort();
+        Vec::new()
     };
 
     // Write recorded audio to file
@@ -474,3 +686,195 @@ async fn run_live(transport: Arc<wzp_transport::QuinnTransport>) -> anyhow::Resu
     info!("done");
     Ok(())
 }
+
+/// Persistent signaling mode for direct 1:1 calls.
+async fn run_signal_mode(
+    relay_addr: SocketAddr,
+    seed: wzp_crypto::Seed,
+    token: Option<String>,
+    call_target: Option<String>,
+) -> anyhow::Result<()> {
+    use wzp_proto::SignalMessage;
+
+    let identity = seed.derive_identity();
+    let pub_id = identity.public_identity();
+    let fp = pub_id.fingerprint.to_string();
+    let identity_pub = *pub_id.signing.as_bytes();
+    info!(fingerprint = %fp, "signal mode");
+
+    // Connect to relay with SNI "_signal"
+    let client_config = wzp_transport::client_config();
+    let bind_addr: SocketAddr = if relay_addr.is_ipv6() {
+        "[::]:0".parse()?
+    } else {
+        "0.0.0.0:0".parse()?
+    };
+    let endpoint = wzp_transport::create_endpoint(bind_addr, None)?;
+    let conn = wzp_transport::connect(&endpoint, relay_addr, "_signal", client_config).await?;
+    let transport = Arc::new(wzp_transport::QuinnTransport::new(conn));
+    info!("connected to relay (signal channel)");
+
+    // Auth if token provided
+    if let Some(ref tok) = token {
+        transport.send_signal(&SignalMessage::AuthToken { token: tok.clone() }).await?;
+    }
+
+    // Register presence (signature not verified in Phase 1)
+    transport.send_signal(&SignalMessage::RegisterPresence {
+        identity_pub,
+        signature: vec![], // Phase 1: not verified
+        alias: None,
+    }).await?;
+
+    // Wait for ack
+    match transport.recv_signal().await? {
+        Some(SignalMessage::RegisterPresenceAck { success: true, .. }) => {
+            info!(fingerprint = %fp, "registered on relay — waiting for calls");
+        }
+        Some(SignalMessage::RegisterPresenceAck { success: false, error }) => {
+            anyhow::bail!("registration failed: {}", error.unwrap_or_default());
+        }
+        other => {
+            anyhow::bail!("unexpected response: {other:?}");
+        }
+    }
+
+    // If --call specified, place the call
+    if let Some(ref target) = call_target {
+        info!(target = %target, "placing direct call...");
+        let call_id = format!("{:016x}", std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH).unwrap().as_nanos());
+
+        transport.send_signal(&SignalMessage::DirectCallOffer {
+            caller_fingerprint: fp.clone(),
+            caller_alias: None,
+            target_fingerprint: target.clone(),
+            call_id: call_id.clone(),
+            identity_pub,
+            ephemeral_pub: [0u8; 32], // Phase 1: not used for key exchange
+            signature: vec![],
+            supported_profiles: vec![wzp_proto::QualityProfile::GOOD],
+        }).await?;
+    }
+
+    // Signal recv loop — handle incoming signals
+    let signal_transport = transport.clone();
+    let relay = relay_addr;
+    let my_fp = fp.clone();
+    let my_seed = seed.0;
+
+    loop {
+        match signal_transport.recv_signal().await {
+            Ok(Some(msg)) => match msg {
+                SignalMessage::CallRinging { call_id } => {
+                    info!(call_id = %call_id, "ringing...");
+                }
+                SignalMessage::DirectCallOffer { caller_fingerprint, caller_alias, call_id, .. } => {
+                    info!(
+                        from = %caller_fingerprint,
+                        alias = ?caller_alias,
+                        call_id = %call_id,
+                        "incoming call — auto-accepting (generic)"
+                    );
+                    // Auto-accept for CLI testing
+                    let _ = signal_transport.send_signal(&SignalMessage::DirectCallAnswer {
+                        call_id,
+                        accept_mode: wzp_proto::CallAcceptMode::AcceptGeneric,
+                        identity_pub: Some(identity_pub),
+                        ephemeral_pub: None,
+                        signature: None,
+                        chosen_profile: Some(wzp_proto::QualityProfile::GOOD),
+                    }).await;
+                }
+                SignalMessage::DirectCallAnswer { call_id, accept_mode, .. } => {
+                    info!(call_id = %call_id, mode = ?accept_mode, "call answered");
+                }
+                SignalMessage::CallSetup { call_id, room, relay_addr: setup_relay } => {
+                    info!(call_id = %call_id, room = %room, relay = %setup_relay, "call setup — connecting to media room");
+
+                    // Connect to the media room
+                    let media_relay: SocketAddr = setup_relay.parse().unwrap_or(relay);
+                    let media_cfg = wzp_transport::client_config();
+                    match wzp_transport::connect(&endpoint, media_relay, &room, media_cfg).await {
+                        Ok(media_conn) => {
+                            let media_transport = Arc::new(wzp_transport::QuinnTransport::new(media_conn));
+
+                            // Crypto handshake
+                            match wzp_client::handshake::perform_handshake(&*media_transport, &my_seed, None).await {
+                                Ok(_session) => {
+                                    info!("media connected — sending tone (press Ctrl+C to hang up)");
+
+                                    // Simple tone sender for testing
+                                    let mt = media_transport.clone();
+                                    let send_task = tokio::spawn(async move {
+                                        let config = wzp_client::call::CallConfig::default();
+                                        let mut encoder = wzp_client::call::CallEncoder::new(&config);
+                                        let duration = tokio::time::Duration::from_millis(20);
+                                        loop {
+                                            let pcm: Vec<i16> = (0..FRAME_SAMPLES)
+                                                .map(|_| 0i16) // silence — could be tone
+                                                .collect();
+                                            if let Ok(pkts) = encoder.encode_frame(&pcm) {
+                                                for pkt in &pkts {
+                                                    if mt.send_media(pkt).await.is_err() { return; }
+                                                }
+                                            }
+                                            tokio::time::sleep(duration).await;
+                                        }
+                                    });
+
+                                    // Wait for hangup or ctrl+c
+                                    loop {
+                                        tokio::select! {
+                                            sig = signal_transport.recv_signal() => {
+                                                match sig {
+                                                    Ok(Some(SignalMessage::Hangup { .. })) => {
+                                                        info!("remote hung up");
+                                                        break;
+                                                    }
+                                                    Ok(None) | Err(_) => break,
+                                                    _ => {}
+                                                }
+                                            }
+                                            _ = tokio::signal::ctrl_c() => {
+                                                info!("hanging up...");
+                                                let _ = signal_transport.send_signal(&SignalMessage::Hangup {
+                                                    reason: wzp_proto::HangupReason::Normal,
+                                                }).await;
+                                                break;
+                                            }
+                                        }
+                                    }
+
+                                    send_task.abort();
+                                    media_transport.close().await.ok();
+                                    info!("call ended");
+                                }
+                                Err(e) => error!("media handshake failed: {e}"),
+                            }
+                        }
+                        Err(e) => error!("media connect failed: {e}"),
+                    }
+                }
+                SignalMessage::Hangup { reason } => {
+                    info!(reason = ?reason, "call ended by remote");
+                }
+                SignalMessage::Pong { .. } => {}
+                other => {
+                    info!("signal: {:?}", std::mem::discriminant(&other));
+                }
+            },
+            Ok(None) => {
+                info!("signal connection closed");
+                break;
+            }
+            Err(e) => {
+                error!("signal error: {e}");
+                break;
+            }
+        }
+    }
+
+    transport.close().await.ok();
+    Ok(())
+}

crates/wzp-client/src/drift_test.rs

@@ -0,0 +1,293 @@
+//! Automated clock-drift measurement tool.
+//!
+//! Sends N seconds of a known 440 Hz tone through the transport, records
+//! received frame timestamps on the other side, and compares actual received
+//! duration vs expected duration to quantify timing drift and packet loss.
+
+use std::time::{Duration, Instant};
+
+use tracing::info;
+
+use wzp_proto::MediaTransport;
+
+use crate::call::{CallConfig, CallDecoder, CallEncoder};
+
+const FRAME_SAMPLES: usize = 960; // 20ms @ 48kHz
+const SAMPLE_RATE: u32 = 48_000;
+
+/// Configuration for a drift measurement run.
+#[derive(Debug, Clone)]
+pub struct DriftTestConfig {
+    /// How many seconds of tone to send.
+    pub duration_secs: u32,
+    /// Frequency of the test tone (Hz).
+    pub tone_freq_hz: f32,
+}
+
+impl Default for DriftTestConfig {
+    fn default() -> Self {
+        Self {
+            duration_secs: 10,
+            tone_freq_hz: 440.0,
+        }
+    }
+}
+
+/// Results from a drift measurement run.
+#[derive(Debug, Clone)]
+pub struct DriftResult {
+    /// Expected duration in milliseconds (`duration_secs * 1000`).
+    pub expected_duration_ms: u64,
+    /// Actual measured duration in milliseconds (last_recv - first_recv).
+    pub actual_duration_ms: u64,
+    /// Drift: `actual - expected` (positive = receiver clock ran slow / packets delayed).
+    pub drift_ms: i64,
+    /// Drift as a percentage of expected duration.
+    pub drift_pct: f64,
+    /// Total frames sent by the sender.
+    pub frames_sent: u64,
+    /// Total frames successfully received and decoded.
+    pub frames_received: u64,
+    /// Packet loss percentage: `(1 - frames_received / frames_sent) * 100`.
+    pub loss_pct: f64,
+}
+
+impl DriftResult {
+    /// Compute a `DriftResult` from raw counters and timestamps.
+    pub fn compute(
+        expected_duration_ms: u64,
+        actual_duration_ms: u64,
+        frames_sent: u64,
+        frames_received: u64,
+    ) -> Self {
+        let drift_ms = actual_duration_ms as i64 - expected_duration_ms as i64;
+        let drift_pct = if expected_duration_ms > 0 {
+            drift_ms as f64 / expected_duration_ms as f64 * 100.0
+        } else {
+            0.0
+        };
+        let loss_pct = if frames_sent > 0 {
+            (1.0 - frames_received as f64 / frames_sent as f64) * 100.0
+        } else {
+            0.0
+        };
+        Self {
+            expected_duration_ms,
+            actual_duration_ms,
+            drift_ms,
+            drift_pct,
+            frames_sent,
+            frames_received,
+            loss_pct,
+        }
+    }
+}
+
+/// Generate a sine wave frame at a given frequency.
+fn sine_frame(freq_hz: f32, frame_offset: u64) -> Vec<i16> {
+    let start = frame_offset * FRAME_SAMPLES as u64;
+    (0..FRAME_SAMPLES)
+        .map(|i| {
+            let t = (start + i as u64) as f32 / SAMPLE_RATE as f32;
+            (f32::sin(2.0 * std::f32::consts::PI * freq_hz * t) * 16000.0) as i16
+        })
+        .collect()
+}
+
+/// Run the drift measurement test.
+///
+/// 1. Spawns a send task that encodes `duration_secs` of tone at 20 ms intervals.
+/// 2. Spawns a recv task that counts decoded frames and tracks first/last timestamps.
+/// 3. After the sender finishes, waits 2 seconds for trailing packets.
+/// 4. Computes and returns the `DriftResult`.
+pub async fn run_drift_test(
+    transport: &(dyn MediaTransport + Send + Sync),
+    config: &DriftTestConfig,
+) -> anyhow::Result<DriftResult> {
+    let call_config = CallConfig::default();
+    let mut encoder = CallEncoder::new(&call_config);
+    let mut decoder = CallDecoder::new(&call_config);
+
+    let total_frames: u64 = config.duration_secs as u64 * 50; // 50 frames/s at 20 ms
+    let frame_duration = Duration::from_millis(20);
+    let mut pcm_buf = vec![0i16; FRAME_SAMPLES];
+
+    let mut frames_sent: u64 = 0;
+    let mut frames_received: u64 = 0;
+    let mut first_recv_time: Option<Instant> = None;
+    let mut last_recv_time: Option<Instant> = None;
+
+    info!(
+        duration_secs = config.duration_secs,
+        tone_hz = config.tone_freq_hz,
+        total_frames = total_frames,
+        "starting drift measurement"
+    );
+
+    let start = Instant::now();
+
+    // Send + interleaved receive loop (same pattern as echo_test)
+    for frame_idx in 0..total_frames {
+        // --- send ---
+        let pcm = sine_frame(config.tone_freq_hz, frame_idx);
+        let packets = encoder.encode_frame(&pcm)?;
+        for pkt in &packets {
+            transport.send_media(pkt).await?;
+        }
+        frames_sent += 1;
+
+        // --- try to receive (short window so we don't block the sender) ---
+        let recv_deadline = Instant::now() + Duration::from_millis(5);
+        loop {
+            if Instant::now() >= recv_deadline {
+                break;
+            }
+            match tokio::time::timeout(Duration::from_millis(2), transport.recv_media()).await {
+                Ok(Ok(Some(pkt))) => {
+                    let is_repair = pkt.header.is_repair;
+                    decoder.ingest(pkt);
+                    if !is_repair {
+                        if let Some(_n) = decoder.decode_next(&mut pcm_buf) {
+                            let now = Instant::now();
+                            if first_recv_time.is_none() {
+                                first_recv_time = Some(now);
+                            }
+                            last_recv_time = Some(now);
+                            frames_received += 1;
+                        }
+                    }
+                }
+                _ => break,
+            }
+        }
+
+        if (frame_idx + 1) % 250 == 0 {
+            info!(
+                frame = frame_idx + 1,
+                sent = frames_sent,
+                recv = frames_received,
+                elapsed = format!("{:.1}s", start.elapsed().as_secs_f64()),
+                "drift-test progress"
+            );
+        }
+
+        tokio::time::sleep(frame_duration).await;
+    }
+
+    // Drain trailing packets for 2 seconds
+    info!("sender done, draining trailing packets for 2s...");
+    let drain_deadline = Instant::now() + Duration::from_secs(2);
+    while Instant::now() < drain_deadline {
+        match tokio::time::timeout(Duration::from_millis(100), transport.recv_media()).await {
+            Ok(Ok(Some(pkt))) => {
+                let is_repair = pkt.header.is_repair;
+                decoder.ingest(pkt);
+                if !is_repair {
+                    if let Some(_n) = decoder.decode_next(&mut pcm_buf) {
+                        let now = Instant::now();
+                        if first_recv_time.is_none() {
+                            first_recv_time = Some(now);
+                        }
+                        last_recv_time = Some(now);
+                        frames_received += 1;
+                    }
+                }
+            }
+            _ => break,
+        }
+    }
+
+    // Compute result
+    let expected_duration_ms = config.duration_secs as u64 * 1000;
+    let actual_duration_ms = match (first_recv_time, last_recv_time) {
+        (Some(first), Some(last)) => last.duration_since(first).as_millis() as u64,
+        _ => 0,
+    };
+
+    let result = DriftResult::compute(
+        expected_duration_ms,
+        actual_duration_ms,
+        frames_sent,
+        frames_received,
+    );
+
+    info!(
+        expected_ms = result.expected_duration_ms,
+        actual_ms = result.actual_duration_ms,
+        drift_ms = result.drift_ms,
+        drift_pct = format!("{:.4}%", result.drift_pct),
+        loss_pct = format!("{:.1}%", result.loss_pct),
+        "drift measurement complete"
+    );
+
+    Ok(result)
+}
+
+/// Pretty-print the drift measurement results.
+pub fn print_drift_report(result: &DriftResult) {
+    println!();
+    println!("=== Drift Measurement Report ===");
+    println!();
+    println!("Frames sent:        {}", result.frames_sent);
+    println!("Frames received:    {}", result.frames_received);
+    println!("Packet loss:        {:.1}%", result.loss_pct);
+    println!();
+    println!("Expected duration:  {} ms", result.expected_duration_ms);
+    println!("Actual duration:    {} ms", result.actual_duration_ms);
+    println!("Drift:              {} ms ({:+.4}%)", result.drift_ms, result.drift_pct);
+    println!();
+
+    // Interpretation
+    let abs_drift = result.drift_ms.unsigned_abs();
+    if result.frames_received == 0 {
+        println!("WARNING: No frames received. Transport may be non-functional.");
+    } else if abs_drift < 5 {
+        println!("Result: EXCELLENT -- drift is negligible (<5 ms).");
+    } else if abs_drift < 20 {
+        println!("Result: GOOD -- drift is within acceptable bounds (<20 ms).");
+    } else if abs_drift < 100 {
+        println!("Result: FAIR -- noticeable drift ({} ms). Clock sync may be needed.", abs_drift);
+    } else {
+        println!("Result: POOR -- significant drift ({} ms). Investigate clock sources.", abs_drift);
+    }
+    println!();
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn drift_result_calculations() {
+        // Perfect case: no drift, no loss
+        let r = DriftResult::compute(10_000, 10_000, 500, 500);
+        assert_eq!(r.drift_ms, 0);
+        assert!((r.drift_pct - 0.0).abs() < f64::EPSILON);
+        assert!((r.loss_pct - 0.0).abs() < f64::EPSILON);
+
+        // Positive drift (receiver duration longer than expected)
+        let r = DriftResult::compute(10_000, 10_050, 500, 490);
+        assert_eq!(r.drift_ms, 50);
+        assert!((r.drift_pct - 0.5).abs() < 1e-9); // 50/10000 * 100 = 0.5%
+        assert!((r.loss_pct - 2.0).abs() < 1e-9); // (1 - 490/500) * 100 = 2.0%
+
+        // Negative drift (receiver duration shorter than expected)
+        let r = DriftResult::compute(10_000, 9_900, 500, 450);
+        assert_eq!(r.drift_ms, -100);
+        assert!((r.drift_pct - (-1.0)).abs() < 1e-9); // -100/10000 * 100 = -1.0%
+        assert!((r.loss_pct - 10.0).abs() < 1e-9); // (1 - 450/500) * 100 = 10.0%
+
+        // Edge: zero frames sent (avoid division by zero)
+        let r = DriftResult::compute(0, 0, 0, 0);
+        assert_eq!(r.drift_ms, 0);
+        assert!((r.drift_pct - 0.0).abs() < f64::EPSILON);
+        assert!((r.loss_pct - 0.0).abs() < f64::EPSILON);
+    }
+
+    #[test]
+    fn drift_config_defaults() {
+        let cfg = DriftTestConfig::default();
+        assert_eq!(cfg.duration_secs, 10);
+        assert!((cfg.tone_freq_hz - 440.0).abs() < f32::EPSILON);
+    }
+}

crates/wzp-client/src/echo_test.rs

@@ -266,7 +266,7 @@ pub async fn run_echo_test(
         }
     }
 
-    let jitter_stats = decoder.jitter_stats();
+    let jitter_stats = decoder.stats().clone();
     let total_frames_received = recv_pcm.len() as u64 / FRAME_SAMPLES as u64;
     let overall_loss = if total_frames > 0 {
         (1.0 - total_frames_received as f32 / total_frames as f32) * 100.0

crates/wzp-client/src/featherchat.rs

@@ -0,0 +1,175 @@
+//! featherChat signaling bridge.
+//!
+//! Sends WZP call signaling (Offer/Answer/Hangup) through featherChat's
+//! E2E encrypted WebSocket channel as `WireMessage::CallSignal`.
+//!
+//! Flow:
+//! 1. Client connects to featherChat WS with bearer token
+//! 2. Sends CallOffer as CallSignal(signal_type=Offer, payload=JSON SignalMessage)
+//! 3. Receives CallAnswer as CallSignal(signal_type=Answer, payload=JSON SignalMessage)
+//! 4. Extracts relay address from the answer
+//! 5. Connects QUIC to relay for media
+
+use serde::{Deserialize, Serialize};
+use wzp_proto::packet::SignalMessage;
+
+/// featherChat CallSignal types (mirrors warzone-protocol::message::CallSignalType).
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub enum CallSignalType {
+    Offer,
+    Answer,
+    IceCandidate,
+    Hangup,
+    Reject,
+    Ringing,
+    Busy,
+    Hold,
+    Unhold,
+    Mute,
+    Unmute,
+    Transfer,
+}
+
+/// A CallSignal as sent through featherChat's WireMessage.
+/// This is what goes in the `payload` field of `WireMessage::CallSignal`.
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct WzpCallPayload {
+    /// The WZP SignalMessage (CallOffer, CallAnswer, etc.) serialized as JSON.
+    pub signal: SignalMessage,
+    /// The relay address to connect to for media (host:port).
+    pub relay_addr: Option<String>,
+    /// Room name on the relay.
+    pub room: Option<String>,
+}
+
+/// Parameters for initiating a call through featherChat.
+pub struct CallInitParams {
+    /// featherChat server URL (e.g., "wss://chat.example.com/ws").
+    pub server_url: String,
+    /// Bearer token for authentication.
+    pub token: String,
+    /// Target peer fingerprint (who to call).
+    pub target_fingerprint: String,
+    /// Relay address for media transport.
+    pub relay_addr: String,
+    /// Room name on the relay.
+    pub room: String,
+    /// Our identity seed for crypto.
+    pub seed: [u8; 32],
+}
+
+/// Result of a successful call setup.
+pub struct CallSetupResult {
+    /// Relay address to connect to.
+    pub relay_addr: String,
+    /// Room name.
+    pub room: String,
+    /// The peer's CallAnswer signal (contains ephemeral key, etc.)
+    pub answer: SignalMessage,
+}
+
+/// Serialize a WZP SignalMessage into a featherChat CallSignal payload string.
+pub fn encode_call_payload(
+    signal: &SignalMessage,
+    relay_addr: Option<&str>,
+    room: Option<&str>,
+) -> String {
+    let payload = WzpCallPayload {
+        signal: signal.clone(),
+        relay_addr: relay_addr.map(|s| s.to_string()),
+        room: room.map(|s| s.to_string()),
+    };
+    serde_json::to_string(&payload).unwrap_or_default()
+}
+
+/// Deserialize a featherChat CallSignal payload back to WZP types.
+pub fn decode_call_payload(payload: &str) -> Result<WzpCallPayload, String> {
+    serde_json::from_str(payload).map_err(|e| format!("invalid call payload: {e}"))
+}
+
+/// Map WZP SignalMessage type to featherChat CallSignalType.
+pub fn signal_to_call_type(signal: &SignalMessage) -> CallSignalType {
+    match signal {
+        SignalMessage::CallOffer { .. } => CallSignalType::Offer,
+        SignalMessage::CallAnswer { .. } => CallSignalType::Answer,
+        SignalMessage::IceCandidate { .. } => CallSignalType::IceCandidate,
+        SignalMessage::Hangup { .. } => CallSignalType::Hangup,
+        SignalMessage::Rekey { .. } => CallSignalType::Offer, // reuse
+        SignalMessage::QualityUpdate { .. } => CallSignalType::Offer, // reuse
+        SignalMessage::Ping { .. } | SignalMessage::Pong { .. } => CallSignalType::Offer,
+        SignalMessage::AuthToken { .. } => CallSignalType::Offer,
+        SignalMessage::Hold => CallSignalType::Hold,
+        SignalMessage::Unhold => CallSignalType::Unhold,
+        SignalMessage::Mute => CallSignalType::Mute,
+        SignalMessage::Unmute => CallSignalType::Unmute,
+        SignalMessage::Transfer { .. } => CallSignalType::Transfer,
+        SignalMessage::TransferAck => CallSignalType::Offer, // reuse
+        SignalMessage::PresenceUpdate { .. } => CallSignalType::Offer, // reuse
+        SignalMessage::RouteQuery { .. } => CallSignalType::Offer, // reuse
+        SignalMessage::RouteResponse { .. } => CallSignalType::Offer, // reuse
+        SignalMessage::SessionForward { .. } => CallSignalType::Offer, // reuse
+        SignalMessage::SessionForwardAck { .. } => CallSignalType::Offer, // reuse
+        SignalMessage::RoomUpdate { .. } => CallSignalType::Offer, // reuse
+        SignalMessage::FederationHello { .. }
+        | SignalMessage::GlobalRoomActive { .. }
+        | SignalMessage::GlobalRoomInactive { .. } => CallSignalType::Offer, // relay-only
+        SignalMessage::DirectCallOffer { .. } => CallSignalType::Offer,
+        SignalMessage::DirectCallAnswer { .. } => CallSignalType::Answer,
+        SignalMessage::CallSetup { .. } => CallSignalType::Offer, // relay-only
+        SignalMessage::CallRinging { .. } => CallSignalType::Ringing,
+        SignalMessage::RegisterPresence { .. }
+        | SignalMessage::RegisterPresenceAck { .. } => CallSignalType::Offer, // relay-only
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use wzp_proto::QualityProfile;
+
+    #[test]
+    fn payload_roundtrip() {
+        let signal = SignalMessage::CallOffer {
+            identity_pub: [1u8; 32],
+            ephemeral_pub: [2u8; 32],
+            signature: vec![3u8; 64],
+            supported_profiles: vec![QualityProfile::GOOD],
+            alias: None,
+        };
+
+        let encoded = encode_call_payload(&signal, Some("relay.example.com:4433"), Some("myroom"));
+        let decoded = decode_call_payload(&encoded).unwrap();
+
+        assert_eq!(decoded.relay_addr.unwrap(), "relay.example.com:4433");
+        assert_eq!(decoded.room.unwrap(), "myroom");
+        assert!(matches!(decoded.signal, SignalMessage::CallOffer { .. }));
+    }
+
+    #[test]
+    fn signal_type_mapping() {
+        let offer = SignalMessage::CallOffer {
+            identity_pub: [0; 32],
+            ephemeral_pub: [0; 32],
+            signature: vec![],
+            supported_profiles: vec![],
+            alias: None,
+        };
+        assert!(matches!(signal_to_call_type(&offer), CallSignalType::Offer));
+
+        let hangup = SignalMessage::Hangup {
+            reason: wzp_proto::HangupReason::Normal,
+        };
+        assert!(matches!(signal_to_call_type(&hangup), CallSignalType::Hangup));
+
+        assert!(matches!(signal_to_call_type(&SignalMessage::Hold), CallSignalType::Hold));
+        assert!(matches!(signal_to_call_type(&SignalMessage::Unhold), CallSignalType::Unhold));
+        assert!(matches!(signal_to_call_type(&SignalMessage::Mute), CallSignalType::Mute));
+        assert!(matches!(signal_to_call_type(&SignalMessage::Unmute), CallSignalType::Unmute));
+
+        let transfer = SignalMessage::Transfer {
+            target_fingerprint: "abc".to_string(),
+            relay_addr: None,
+        };
+        assert!(matches!(signal_to_call_type(&transfer), CallSignalType::Transfer));
+    }
+}

crates/wzp-client/src/handshake.rs

@@ -17,6 +17,7 @@ use wzp_proto::{MediaTransport, QualityProfile, SignalMessage};
 pub async fn perform_handshake(
     transport: &dyn MediaTransport,
     seed: &[u8; 32],
+    alias: Option<&str>,
 ) -> Result<Box<dyn CryptoSession>, anyhow::Error> {
     // 1. Create key exchange from identity seed
     let mut kx = WarzoneKeyExchange::from_identity_seed(seed);
@@ -37,10 +38,14 @@ pub async fn perform_handshake(
         ephemeral_pub,
         signature,
         supported_profiles: vec![
+            QualityProfile::STUDIO_64K,
+            QualityProfile::STUDIO_48K,
+            QualityProfile::STUDIO_32K,
             QualityProfile::GOOD,
             QualityProfile::DEGRADED,
             QualityProfile::CATASTROPHIC,
         ],
+        alias: alias.map(|s| s.to_string()),
     };
     transport.send_signal(&offer).await?;
 

crates/wzp-client/src/lib.rs

@@ -8,12 +8,75 @@
 
 #[cfg(feature = "audio")]
 pub mod audio_io;
+#[cfg(feature = "audio")]
+pub mod audio_ring;
+// VoiceProcessingIO is an Apple Core Audio API — only compile the module
+// when the `vpio` feature is on AND we're targeting macOS. Enabling the
+// feature on Windows/Linux was previously silently broken.
+#[cfg(all(feature = "vpio", target_os = "macos"))]
+pub mod audio_vpio;
+// WASAPI-direct capture with Windows's OS-level AEC (AudioCategory_Communications).
+// Only compiled when `windows-aec` feature is on AND target is Windows. The
+// `windows` dependency is itself gated to Windows in Cargo.toml, so enabling
+// this feature on non-Windows targets is a no-op.
+#[cfg(all(feature = "windows-aec", target_os = "windows"))]
+pub mod audio_wasapi;
+// WebRTC AEC3 (Audio Processing Module) wrapper around CPAL capture + playback
+// on Linux. Only compiled when `linux-aec` feature is on AND target is Linux.
+// The webrtc-audio-processing dep is itself gated to Linux in Cargo.toml.
+#[cfg(all(feature = "linux-aec", target_os = "linux"))]
+pub mod audio_linux_aec;
 pub mod bench;
 pub mod call;
+pub mod drift_test;
 pub mod echo_test;
+pub mod featherchat;
 pub mod handshake;
+pub mod metrics;
+pub mod sweep;
 
-#[cfg(feature = "audio")]
-pub use audio_io::{AudioCapture, AudioPlayback};
+// AudioPlayback: three possible backends depending on feature flags.
+//   1. Default CPAL (`audio_io::AudioPlayback`) — baseline on every platform.
+//   2. Linux AEC (`audio_linux_aec::LinuxAecPlayback`) — CPAL + WebRTC APM
+//      render-side tee, so echo from speakers gets cancelled from the mic.
+//
+// On macOS and Windows we always use the default CPAL playback because:
+//   - macOS: VoiceProcessingIO handles AEC at the capture side (Apple's
+//     native hardware AEC uses its own reference signal handling).
+//   - Windows: WASAPI AudioCategory_Communications AEC uses the system
+//     render mix as reference — no per-process plumbing needed.
+//
+// Linux is the only platform where the in-app approach is necessary, so
+// the AEC playback path is gated to target_os = "linux".
+
+#[cfg(all(
+    feature = "audio",
+    any(not(feature = "linux-aec"), not(target_os = "linux"))
+))]
+pub use audio_io::AudioPlayback;
+
+#[cfg(all(feature = "linux-aec", target_os = "linux"))]
+pub use audio_linux_aec::LinuxAecPlayback as AudioPlayback;
+
+// AudioCapture: three possible backends depending on feature flags.
+//   1. Default CPAL (`audio_io::AudioCapture`) — baseline on every platform.
+//   2. Windows AEC (`audio_wasapi::WasapiAudioCapture`) — direct WASAPI
+//      with AudioCategory_Communications, OS APO chain does AEC.
+//   3. Linux AEC (`audio_linux_aec::LinuxAecCapture`) — CPAL + WebRTC APM
+//      capture-side echo cancellation using the playback tee as reference.
+// All three expose the same public API (`start`, `ring`, `stop`, `Drop`).
+
+#[cfg(all(
+    feature = "audio",
+    any(not(feature = "windows-aec"), not(target_os = "windows")),
+    any(not(feature = "linux-aec"), not(target_os = "linux"))
+))]
+pub use audio_io::AudioCapture;
+
+#[cfg(all(feature = "windows-aec", target_os = "windows"))]
+pub use audio_wasapi::WasapiAudioCapture as AudioCapture;
+
+#[cfg(all(feature = "linux-aec", target_os = "linux"))]
+pub use audio_linux_aec::LinuxAecCapture as AudioCapture;
 pub use call::{CallConfig, CallDecoder, CallEncoder};
 pub use handshake::perform_handshake;

crates/wzp-client/src/metrics.rs

@@ -0,0 +1,186 @@
+//! Client-side JSONL metrics export.
+//!
+//! When `--metrics-file <path>` is passed, the client writes one JSON object
+//! per second to the specified file. Each line is a self-contained JSON object
+//! (JSONL format) containing jitter buffer stats, loss, and quality profile.
+
+use std::fs::{File, OpenOptions};
+use std::io::Write;
+use std::time::{Duration, Instant};
+
+use serde::Serialize;
+
+use wzp_proto::jitter::JitterStats;
+
+/// A single metrics snapshot written as one JSONL line.
+#[derive(Serialize)]
+pub struct ClientMetricsSnapshot {
+    pub ts: String,
+    pub buffer_depth: usize,
+    pub underruns: u64,
+    pub overruns: u64,
+    pub loss_pct: f64,
+    pub rtt_ms: u64,
+    pub jitter_ms: u64,
+    pub frames_sent: u64,
+    pub frames_received: u64,
+    pub quality_profile: String,
+}
+
+/// Periodic JSONL writer that respects a configurable interval.
+pub struct MetricsWriter {
+    file: File,
+    interval: Duration,
+    last_write: Instant,
+}
+
+impl MetricsWriter {
+    /// Create a new `MetricsWriter` that appends JSONL to the given path.
+    ///
+    /// The file is created (or truncated) immediately.
+    pub fn new(path: &str, interval_secs: u64) -> Result<Self, anyhow::Error> {
+        let file = OpenOptions::new()
+            .create(true)
+            .write(true)
+            .truncate(true)
+            .open(path)?;
+        Ok(Self {
+            file,
+            interval: Duration::from_secs(interval_secs),
+            // Set last_write far in the past so the first call writes immediately.
+            last_write: Instant::now() - Duration::from_secs(interval_secs + 1),
+        })
+    }
+
+    /// Write a JSONL line if the interval has elapsed since the last write.
+    ///
+    /// Returns `Ok(true)` when a line was written, `Ok(false)` when skipped.
+    pub fn maybe_write(&mut self, snapshot: &ClientMetricsSnapshot) -> Result<bool, anyhow::Error> {
+        let now = Instant::now();
+        if now.duration_since(self.last_write) >= self.interval {
+            let line = serde_json::to_string(snapshot)?;
+            writeln!(self.file, "{}", line)?;
+            self.file.flush()?;
+            self.last_write = now;
+            Ok(true)
+        } else {
+            Ok(false)
+        }
+    }
+}
+
+/// Build a `ClientMetricsSnapshot` from jitter buffer stats and a quality profile name.
+///
+/// Fields not available from `JitterStats` alone (rtt_ms, jitter_ms, frames_sent)
+/// are set to zero — the caller can override them if the data is available.
+pub fn snapshot_from_stats(stats: &JitterStats, profile: &str) -> ClientMetricsSnapshot {
+    let loss_pct = if stats.packets_received > 0 {
+        (stats.packets_lost as f64 / stats.packets_received as f64) * 100.0
+    } else {
+        0.0
+    };
+    ClientMetricsSnapshot {
+        ts: chrono::Utc::now().to_rfc3339_opts(chrono::SecondsFormat::Secs, true),
+        buffer_depth: stats.current_depth,
+        underruns: stats.underruns,
+        overruns: stats.overruns,
+        loss_pct,
+        rtt_ms: 0,
+        jitter_ms: 0,
+        frames_sent: 0,
+        frames_received: stats.total_decoded,
+        quality_profile: profile.to_string(),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn make_test_stats() -> JitterStats {
+        JitterStats {
+            packets_received: 100,
+            packets_played: 95,
+            packets_lost: 5,
+            packets_late: 2,
+            packets_duplicate: 0,
+            current_depth: 8,
+            total_decoded: 93,
+            underruns: 1,
+            overruns: 0,
+            max_depth_seen: 12,
+        }
+    }
+
+    #[test]
+    fn snapshot_serializes_to_json() {
+        let stats = make_test_stats();
+        let snap = snapshot_from_stats(&stats, "GOOD");
+        let json = serde_json::to_string(&snap).unwrap();
+
+        // Verify expected fields are present in the JSON string.
+        assert!(json.contains("\"ts\""));
+        assert!(json.contains("\"buffer_depth\":8"));
+        assert!(json.contains("\"underruns\":1"));
+        assert!(json.contains("\"overruns\":0"));
+        assert!(json.contains("\"loss_pct\":5."));
+        assert!(json.contains("\"rtt_ms\":0"));
+        assert!(json.contains("\"jitter_ms\":0"));
+        assert!(json.contains("\"frames_sent\":0"));
+        assert!(json.contains("\"frames_received\":93"));
+        assert!(json.contains("\"quality_profile\":\"GOOD\""));
+
+        // Verify it round-trips as valid JSON.
+        let value: serde_json::Value = serde_json::from_str(&json).unwrap();
+        assert_eq!(value["buffer_depth"], 8);
+        assert_eq!(value["quality_profile"], "GOOD");
+    }
+
+    #[test]
+    fn metrics_writer_creates_file() {
+        let dir = std::env::temp_dir();
+        let path = dir.join("wzp_metrics_test.jsonl");
+        let path_str = path.to_str().unwrap();
+
+        let mut writer = MetricsWriter::new(path_str, 1).unwrap();
+        let stats = make_test_stats();
+        let snap = snapshot_from_stats(&stats, "DEGRADED");
+
+        let wrote = writer.maybe_write(&snap).unwrap();
+        assert!(wrote, "first write should succeed immediately");
+
+        // Read the file back and verify it contains valid JSONL.
+        let contents = std::fs::read_to_string(&path).unwrap();
+        let lines: Vec<&str> = contents.lines().collect();
+        assert_eq!(lines.len(), 1, "should have exactly one JSONL line");
+
+        let value: serde_json::Value = serde_json::from_str(lines[0]).unwrap();
+        assert_eq!(value["quality_profile"], "DEGRADED");
+        assert_eq!(value["buffer_depth"], 8);
+
+        // Clean up.
+        let _ = std::fs::remove_file(&path);
+    }
+
+    #[test]
+    fn metrics_writer_respects_interval() {
+        let dir = std::env::temp_dir();
+        let path = dir.join("wzp_metrics_interval_test.jsonl");
+        let path_str = path.to_str().unwrap();
+
+        let mut writer = MetricsWriter::new(path_str, 60).unwrap();
+        let stats = make_test_stats();
+        let snap = snapshot_from_stats(&stats, "GOOD");
+
+        // First write succeeds (last_write is set far in the past).
+        let first = writer.maybe_write(&snap).unwrap();
+        assert!(first, "first write should succeed");
+
+        // Immediate second write should be skipped (60s interval).
+        let second = writer.maybe_write(&snap).unwrap();
+        assert!(!second, "second write should be skipped — interval not elapsed");
+
+        // Clean up.
+        let _ = std::fs::remove_file(&path);
+    }
+}

crates/wzp-client/src/sweep.rs

@@ -0,0 +1,254 @@
+//! Parameter sweep tool for jitter buffer configurations.
+//!
+//! Tests different (target_depth, max_depth) combinations in a local
+//! encoder-to-decoder pipeline (no network) and reports frame loss,
+//! estimated latency, underruns, and overruns for each configuration.
+
+use crate::call::{CallConfig, CallDecoder, CallEncoder};
+use wzp_proto::QualityProfile;
+
+const FRAME_SAMPLES: usize = 960; // 20ms @ 48kHz
+const SAMPLE_RATE: u32 = 48_000;
+const FRAME_DURATION_MS: u32 = 20;
+
+/// Configuration for a parameter sweep.
+pub struct SweepConfig {
+    /// Target jitter buffer depths to test (in packets).
+    pub target_depths: Vec<usize>,
+    /// Maximum jitter buffer depths to test (in packets).
+    pub max_depths: Vec<usize>,
+    /// Duration in seconds to run each configuration.
+    pub test_duration_secs: u32,
+    /// Frequency of the test tone in Hz.
+    pub tone_freq_hz: f32,
+}
+
+impl Default for SweepConfig {
+    fn default() -> Self {
+        Self {
+            target_depths: vec![10, 25, 50, 100, 200],
+            max_depths: vec![50, 100, 250, 500],
+            test_duration_secs: 2,
+            tone_freq_hz: 440.0,
+        }
+    }
+}
+
+/// Result from one (target_depth, max_depth) configuration.
+#[derive(Debug, Clone)]
+pub struct SweepResult {
+    /// Jitter buffer target depth used.
+    pub target_depth: usize,
+    /// Jitter buffer max depth used.
+    pub max_depth: usize,
+    /// Total frames sent into the encoder.
+    pub frames_sent: u64,
+    /// Total frames successfully decoded.
+    pub frames_received: u64,
+    /// Frame loss percentage.
+    pub loss_pct: f64,
+    /// Estimated latency in ms (target_depth * frame_duration).
+    pub avg_latency_ms: f64,
+    /// Number of jitter buffer underruns.
+    pub underruns: u64,
+    /// Number of jitter buffer overruns (packets dropped due to full buffer).
+    pub overruns: u64,
+}
+
+/// Generate a sine wave frame at the given frequency and frame offset.
+fn sine_frame(freq_hz: f32, frame_offset: u64) -> Vec<i16> {
+    let start = frame_offset * FRAME_SAMPLES as u64;
+    (0..FRAME_SAMPLES)
+        .map(|i| {
+            let t = (start + i as u64) as f32 / SAMPLE_RATE as f32;
+            (f32::sin(2.0 * std::f32::consts::PI * freq_hz * t) * 16000.0) as i16
+        })
+        .collect()
+}
+
+/// Run a local parameter sweep (no network).
+///
+/// For each (target_depth, max_depth) combination, creates an encoder and
+/// decoder, pushes frames through the pipeline, and collects statistics.
+/// Combinations where `target_depth > max_depth` are skipped.
+pub fn run_local_sweep(config: &SweepConfig) -> Vec<SweepResult> {
+    let frames_per_config =
+        (config.test_duration_secs as u64) * (1000 / FRAME_DURATION_MS as u64);
+
+    let mut results = Vec::new();
+
+    for &target in &config.target_depths {
+        for &max in &config.max_depths {
+            // Skip invalid combinations where target exceeds max.
+            if target > max {
+                continue;
+            }
+
+            let call_cfg = CallConfig {
+                profile: QualityProfile::GOOD,
+                jitter_target: target,
+                jitter_max: max,
+                jitter_min: target.min(3).max(1),
+                ..Default::default()
+            };
+
+            let mut encoder = CallEncoder::new(&call_cfg);
+            let mut decoder = CallDecoder::new(&call_cfg);
+
+            let mut pcm_out = vec![0i16; FRAME_SAMPLES];
+            let mut frames_decoded = 0u64;
+
+            for frame_idx in 0..frames_per_config {
+                // Encode a tone frame.
+                let pcm_in = sine_frame(config.tone_freq_hz, frame_idx);
+                let packets = match encoder.encode_frame(&pcm_in) {
+                    Ok(p) => p,
+                    Err(_) => continue,
+                };
+
+                // Feed all packets (source + repair) into the decoder.
+                for pkt in packets {
+                    decoder.ingest(pkt);
+                }
+
+                // Attempt to decode one frame.
+                if decoder.decode_next(&mut pcm_out).is_some() {
+                    frames_decoded += 1;
+                }
+            }
+
+            // Drain: keep decoding until the jitter buffer is empty.
+            for _ in 0..max {
+                if decoder.decode_next(&mut pcm_out).is_some() {
+                    frames_decoded += 1;
+                } else {
+                    break;
+                }
+            }
+
+            let stats = decoder.stats().clone();
+
+            let loss_pct = if frames_per_config > 0 {
+                (1.0 - frames_decoded as f64 / frames_per_config as f64) * 100.0
+            } else {
+                0.0
+            };
+
+            results.push(SweepResult {
+                target_depth: target,
+                max_depth: max,
+                frames_sent: frames_per_config,
+                frames_received: frames_decoded,
+                loss_pct: loss_pct.max(0.0),
+                avg_latency_ms: target as f64 * FRAME_DURATION_MS as f64,
+                underruns: stats.underruns,
+                overruns: stats.overruns,
+            });
+        }
+    }
+
+    results
+}
+
+/// Print a formatted ASCII table of sweep results.
+pub fn print_sweep_table(results: &[SweepResult]) {
+    println!();
+    println!("=== Jitter Buffer Parameter Sweep ===");
+    println!();
+    println!(
+        " {:>6} | {:>4} | {:>6} | {:>6} | {:>6} | {:>10} | {:>9} | {:>8}",
+        "target", "max", "sent", "recv", "loss%", "latency_ms", "underruns", "overruns"
+    );
+    println!(
+        " {:-<6}-+-{:-<4}-+-{:-<6}-+-{:-<6}-+-{:-<6}-+-{:-<10}-+-{:-<9}-+-{:-<8}",
+        "", "", "", "", "", "", "", ""
+    );
+    for r in results {
+        println!(
+            " {:>6} | {:>4} | {:>6} | {:>6} | {:>5.1}% | {:>10.0} | {:>9} | {:>8}",
+            r.target_depth,
+            r.max_depth,
+            r.frames_sent,
+            r.frames_received,
+            r.loss_pct,
+            r.avg_latency_ms,
+            r.underruns,
+            r.overruns,
+        );
+    }
+    println!();
+}
+
+/// Run a default sweep and print the results.
+///
+/// This is the entry point for the `--sweep` CLI flag.
+pub fn run_and_print_default_sweep() {
+    let config = SweepConfig::default();
+    let results = run_local_sweep(&config);
+    print_sweep_table(&results);
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn sweep_config_default() {
+        let cfg = SweepConfig::default();
+        assert_eq!(cfg.target_depths.len(), 5);
+        assert_eq!(cfg.max_depths.len(), 4);
+        assert!(cfg.test_duration_secs > 0);
+        assert!(cfg.tone_freq_hz > 0.0);
+        // All default targets should be positive.
+        assert!(cfg.target_depths.iter().all(|&d| d > 0));
+        assert!(cfg.max_depths.iter().all(|&d| d > 0));
+    }
+
+    #[test]
+    fn local_sweep_runs() {
+        let cfg = SweepConfig {
+            target_depths: vec![3, 10],
+            max_depths: vec![50, 100],
+            test_duration_secs: 1,
+            tone_freq_hz: 440.0,
+        };
+        let results = run_local_sweep(&cfg);
+        // 2 targets x 2 maxes = 4 configs (all valid since targets < maxes).
+        assert_eq!(results.len(), 4);
+        for r in &results {
+            assert!(r.frames_sent > 0, "frames_sent should be > 0");
+            assert!(r.frames_received > 0, "frames_received should be > 0");
+            assert!(r.avg_latency_ms > 0.0, "latency should be > 0");
+        }
+    }
+
+    #[test]
+    fn sweep_table_formats() {
+        // Verify print_sweep_table doesn't panic with various inputs.
+        print_sweep_table(&[]);
+
+        let results = vec![
+            SweepResult {
+                target_depth: 10,
+                max_depth: 50,
+                frames_sent: 100,
+                frames_received: 98,
+                loss_pct: 2.0,
+                avg_latency_ms: 200.0,
+                underruns: 2,
+                overruns: 0,
+            },
+            SweepResult {
+                target_depth: 25,
+                max_depth: 100,
+                frames_sent: 100,
+                frames_received: 100,
+                loss_pct: 0.0,
+                avg_latency_ms: 500.0,
+                underruns: 0,
+                overruns: 0,
+            },
+        ];
+        print_sweep_table(&results);
+    }
+}

crates/wzp-client/tests/long_session.rs

@@ -0,0 +1,190 @@
+//! WZP-P2-T1-S5: 60-second long-session regression tests.
+//!
+//! Verifies that the full codec + FEC + jitter buffer pipeline does not drift
+//! or degrade over a sustained 60-second (3000-frame) session. Runs entirely
+//! in-process with no network — packets flow directly from encoder to decoder.
+
+use wzp_client::call::{CallConfig, CallDecoder, CallEncoder};
+use wzp_proto::QualityProfile;
+
+const FRAME_SAMPLES: usize = 960; // 20ms @ 48kHz
+const SAMPLE_RATE: f32 = 48_000.0;
+const TOTAL_FRAMES: u64 = 3_000; // 60 seconds at 50 fps
+
+/// Build a CallConfig tuned for direct-loopback testing (no network).
+///
+/// Disables silence suppression and noise suppression (which would mangle
+/// or squelch the synthetic tone), uses a fixed (non-adaptive) jitter buffer
+/// with min_depth=1 so that packets are played out as soon as they arrive.
+fn test_config() -> CallConfig {
+    CallConfig {
+        profile: QualityProfile::GOOD,
+        jitter_target: 4,
+        jitter_max: 500,
+        jitter_min: 1,
+        suppression_enabled: false,
+        noise_suppression: false,
+        adaptive_jitter: false,
+        ..Default::default()
+    }
+}
+
+/// Generate a 20ms frame of 440 Hz sine tone.
+fn sine_frame(frame_offset: u64) -> Vec<i16> {
+    let start_sample = frame_offset * FRAME_SAMPLES as u64;
+    (0..FRAME_SAMPLES)
+        .map(|i| {
+            let t = (start_sample + i as u64) as f32 / SAMPLE_RATE;
+            (f32::sin(2.0 * std::f32::consts::PI * 440.0 * t) * 16000.0) as i16
+        })
+        .collect()
+}
+
+/// 60-second session with a perfect (lossless, in-order) channel.
+///
+/// Encodes 3000 frames of 440 Hz tone, feeds every packet directly into the
+/// decoder, and verifies:
+///   - frame loss < 5%  (>2850 of 3000 source frames decoded or PLC'd)
+///   - no panics
+///
+/// Note: the encoder shares a single sequence counter between source and
+/// repair packets.  Since repair packets are NOT pushed into the jitter
+/// buffer, each FEC block creates a gap in the playout sequence.  GOOD
+/// profile (5 frames/block, fec_ratio=0.2) generates 1 repair per block,
+/// so every 6th seq number is a "phantom" Missing in the jitter buffer.
+/// The jitter buffer correctly fills these gaps with PLC.  We call
+/// `decode_next` once per encode tick; the buffer stays shallow because
+/// PLC frames consume the phantom seqs at the same rate they're created.
+#[test]
+fn long_session_no_drift() {
+    let config = test_config();
+    let mut encoder = CallEncoder::new(&config);
+    let mut decoder = CallDecoder::new(&config);
+
+    let mut frames_decoded = 0u64;
+    let mut pcm_buf = vec![0i16; FRAME_SAMPLES];
+
+    for i in 0..TOTAL_FRAMES {
+        let pcm = sine_frame(i);
+        let packets = encoder.encode_frame(&pcm).expect("encode should not fail");
+
+        for pkt in packets {
+            decoder.ingest(pkt);
+        }
+
+        // Decode one frame per tick (mirrors real-time 50 fps cadence).
+        if decoder.decode_next(&mut pcm_buf).is_some() {
+            frames_decoded += 1;
+        }
+    }
+
+    let stats = decoder.stats();
+
+    println!(
+        "long_session_no_drift: decoded={frames_decoded}/{TOTAL_FRAMES}, \
+         underruns={}, overruns={}, depth={}, max_depth={}, late={}, lost={}",
+        stats.underruns, stats.overruns, stats.current_depth, stats.max_depth_seen,
+        stats.packets_late, stats.packets_lost,
+    );
+
+    // With 1 decode per tick over 3000 ticks, we expect ~3000 decoded frames
+    // (some via PLC for repair-seq gaps).  Allow up to 5% gap.
+    assert!(
+        frames_decoded > 2850,
+        "frame loss too high: decoded {frames_decoded}/3000 (need >2850 = <5% loss)"
+    );
+}
+
+/// 60-second session with simulated 5% packet loss and reordering.
+///
+/// Every 20th source packet is dropped; pairs of adjacent packets are swapped
+/// every 7 frames.  Verifies that FEC + jitter buffer recover gracefully:
+///   - frame loss < 10% (FEC should recover some of the 5% artificial loss)
+///   - no panics
+#[test]
+fn long_session_with_simulated_loss() {
+    let config = test_config();
+    let mut encoder = CallEncoder::new(&config);
+    let mut decoder = CallDecoder::new(&config);
+
+    let mut frames_decoded = 0u64;
+    let mut pcm_buf = vec![0i16; FRAME_SAMPLES];
+
+    for i in 0..TOTAL_FRAMES {
+        let pcm = sine_frame(i);
+        let packets = encoder.encode_frame(&pcm).expect("encode should not fail");
+
+        let mut batch: Vec<_> = packets.into_iter().collect();
+
+        // Simulate reordering: swap first two packets in the batch every 7 frames.
+        if i % 7 == 0 && batch.len() >= 2 {
+            batch.swap(0, 1);
+        }
+
+        for (j, pkt) in batch.into_iter().enumerate() {
+            // Drop every 20th *source* (non-repair) packet to simulate ~5% loss.
+            if !pkt.header.is_repair && i % 20 == 0 && j == 0 {
+                continue; // drop this packet
+            }
+            decoder.ingest(pkt);
+        }
+
+        if decoder.decode_next(&mut pcm_buf).is_some() {
+            frames_decoded += 1;
+        }
+    }
+
+    let stats = decoder.stats();
+
+    println!(
+        "long_session_with_simulated_loss: decoded={frames_decoded}/{TOTAL_FRAMES}, \
+         underruns={}, overruns={}, depth={}, max_depth={}, late={}, lost={}",
+        stats.underruns, stats.overruns, stats.current_depth, stats.max_depth_seen,
+        stats.packets_late, stats.packets_lost,
+    );
+
+    // With 5% artificial loss + FEC recovery + PLC, we should still get >90% decoded.
+    assert!(
+        frames_decoded > 2700,
+        "frame loss too high under simulated loss: decoded {frames_decoded}/3000 (need >2700 = <10%)"
+    );
+}
+
+/// Verify that the jitter buffer's decoded-frame count is consistent with its
+/// own internal statistics over a long session.
+#[test]
+fn long_session_stats_consistency() {
+    let config = test_config();
+    let mut encoder = CallEncoder::new(&config);
+    let mut decoder = CallDecoder::new(&config);
+
+    let mut frames_decoded = 0u64;
+    let mut pcm_buf = vec![0i16; FRAME_SAMPLES];
+
+    for i in 0..TOTAL_FRAMES {
+        let pcm = sine_frame(i);
+        let packets = encoder.encode_frame(&pcm).expect("encode");
+
+        for pkt in packets {
+            decoder.ingest(pkt);
+        }
+        if decoder.decode_next(&mut pcm_buf).is_some() {
+            frames_decoded += 1;
+        }
+    }
+
+    let stats = decoder.stats();
+
+    // total_decoded should match our manual counter.
+    assert_eq!(
+        stats.total_decoded, frames_decoded,
+        "stats.total_decoded ({}) != manually counted frames_decoded ({frames_decoded})",
+        stats.total_decoded,
+    );
+
+    // packets_received should be > 0.
+    assert!(
+        stats.packets_received > 0,
+        "stats.packets_received should be > 0"
+    );
+}

crates/wzp-codec/Cargo.toml

@@ -16,4 +16,10 @@ audiopus = { workspace = true }
 # Pure-Rust Codec2 implementation
 codec2 = { workspace = true }
 
+# RNG for comfort noise generation
+rand = { workspace = true }
+
+# ML-based noise suppression (pure-Rust port of RNNoise)
+nnnoiseless = "0.5"
+
 [dev-dependencies]

crates/wzp-codec/src/adaptive.rs

@@ -14,7 +14,7 @@ use crate::codec2_dec::Codec2Decoder;
 use crate::codec2_enc::Codec2Encoder;
 use crate::opus_dec::OpusDecoder;
 use crate::opus_enc::OpusEncoder;
-use crate::resample;
+use crate::resample::{Downsampler48to8, Upsampler8to48};
 
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
@@ -54,6 +54,7 @@ pub struct AdaptiveEncoder {
     opus: OpusEncoder,
     codec2: Codec2Encoder,
     active: CodecId,
+    downsampler: Downsampler48to8,
 }
 
 impl AdaptiveEncoder {
@@ -66,6 +67,7 @@ impl AdaptiveEncoder {
             opus,
             codec2,
             active: profile.codec,
+            downsampler: Downsampler48to8::new(),
         })
     }
 }
@@ -74,7 +76,7 @@ impl AudioEncoder for AdaptiveEncoder {
     fn encode(&mut self, pcm: &[i16], out: &mut [u8]) -> Result<usize, CodecError> {
         if is_codec2(self.active) {
             // Downsample 48 kHz → 8 kHz then encode via Codec2.
-            let pcm_8k = resample::resample_48k_to_8k(pcm);
+            let pcm_8k = self.downsampler.process(pcm);
             self.codec2.encode(&pcm_8k, out)
         } else {
             self.opus.encode(pcm, out)
@@ -126,6 +128,7 @@ pub struct AdaptiveDecoder {
     opus: OpusDecoder,
     codec2: Codec2Decoder,
     active: CodecId,
+    upsampler: Upsampler8to48,
 }
 
 impl AdaptiveDecoder {
@@ -138,6 +141,7 @@ impl AdaptiveDecoder {
             opus,
             codec2,
             active: profile.codec,
+            upsampler: Upsampler8to48::new(),
         })
     }
 }
@@ -149,7 +153,7 @@ impl AudioDecoder for AdaptiveDecoder {
             let c2_samples = self.codec2_frame_samples();
             let mut buf_8k = vec![0i16; c2_samples];
             let n = self.codec2.decode(encoded, &mut buf_8k)?;
-            let pcm_48k = resample::resample_8k_to_48k(&buf_8k[..n]);
+            let pcm_48k = self.upsampler.process(&buf_8k[..n]);
             let out_len = pcm_48k.len().min(pcm.len());
             pcm[..out_len].copy_from_slice(&pcm_48k[..out_len]);
             Ok(out_len)
@@ -163,7 +167,7 @@ impl AudioDecoder for AdaptiveDecoder {
             let c2_samples = self.codec2_frame_samples();
             let mut buf_8k = vec![0i16; c2_samples];
             let n = self.codec2.decode_lost(&mut buf_8k)?;
-            let pcm_48k = resample::resample_8k_to_48k(&buf_8k[..n]);
+            let pcm_48k = self.upsampler.process(&buf_8k[..n]);
             let out_len = pcm_48k.len().min(pcm.len());
             pcm[..out_len].copy_from_slice(&pcm_48k[..out_len]);
             Ok(out_len)

crates/wzp-codec/src/aec.rs

@@ -0,0 +1,335 @@
+//! Acoustic Echo Cancellation — delay-compensated leaky NLMS with
+//! Geigel double-talk detection.
+//!
+//! Key insight: on a laptop, the round-trip audio latency (playout → speaker
+//! → air → mic → capture) is 30–50ms.  The far-end reference must be delayed
+//! by this amount so the adaptive filter models the *echo path*, not the
+//! *system delay + echo path*.
+//!
+//! The leaky coefficient decay prevents the filter from diverging when the
+//! echo path changes (e.g. hand near laptop) or when the delay estimate
+//! is slightly off.
+
+/// Delay-compensated leaky NLMS echo canceller with Geigel DTD.
+pub struct EchoCanceller {
+    // --- Adaptive filter ---
+    filter: Vec<f32>,
+    filter_len: usize,
+    /// Circular buffer of far-end reference samples (after delay).
+    far_buf: Vec<f32>,
+    far_pos: usize,
+    /// NLMS step size.
+    mu: f32,
+    /// Leakage factor: coefficients are multiplied by (1 - leak) each frame.
+    /// Prevents unbounded growth / divergence.  0.0001 is gentle.
+    leak: f32,
+    enabled: bool,
+
+    // --- Delay buffer ---
+    /// Raw far-end samples before delay compensation.
+    delay_ring: Vec<f32>,
+    delay_write: usize,
+    delay_read: usize,
+    /// Delay in samples (e.g. 1920 = 40ms at 48kHz).
+    delay_samples: usize,
+    /// Capacity of the delay ring.
+    delay_cap: usize,
+
+    // --- Double-talk detection (Geigel) ---
+    /// Peak far-end level over the last filter_len samples.
+    far_peak: f32,
+    /// Geigel threshold: if |near| > threshold * far_peak, assume double-talk.
+    geigel_threshold: f32,
+    /// Holdover counter: keep DTD active for a few frames after detection.
+    dtd_holdover: u32,
+    dtd_hold_frames: u32,
+}
+
+impl EchoCanceller {
+    /// Create a new echo canceller.
+    ///
+    /// * `sample_rate` — typically 48000
+    /// * `filter_ms`   — echo-tail length in milliseconds (60ms recommended)
+    /// * `delay_ms`    — far-end delay compensation in milliseconds (40ms for laptops)
+    pub fn new(sample_rate: u32, filter_ms: u32) -> Self {
+        Self::with_delay(sample_rate, filter_ms, 40)
+    }
+
+    pub fn with_delay(sample_rate: u32, filter_ms: u32, delay_ms: u32) -> Self {
+        let filter_len = (sample_rate as usize) * (filter_ms as usize) / 1000;
+        let delay_samples = (sample_rate as usize) * (delay_ms as usize) / 1000;
+        // Delay ring must hold at least delay_samples + one frame (960) of headroom.
+        let delay_cap = delay_samples + (sample_rate as usize / 10); // +100ms headroom
+        Self {
+            filter: vec![0.0; filter_len],
+            filter_len,
+            far_buf: vec![0.0; filter_len],
+            far_pos: 0,
+            mu: 0.01,
+            leak: 0.0001,
+            enabled: true,
+
+            delay_ring: vec![0.0; delay_cap],
+            delay_write: 0,
+            delay_read: 0,
+            delay_samples,
+            delay_cap,
+
+            far_peak: 0.0,
+            geigel_threshold: 0.7,
+            dtd_holdover: 0,
+            dtd_hold_frames: 5,
+        }
+    }
+
+    /// Feed far-end (speaker) samples.  These go into the delay buffer first;
+    /// once enough samples have accumulated, they are released to the filter's
+    /// circular buffer with the correct delay offset.
+    pub fn feed_farend(&mut self, farend: &[i16]) {
+        // Write raw samples into the delay ring.
+        for &s in farend {
+            self.delay_ring[self.delay_write % self.delay_cap] = s as f32;
+            self.delay_write += 1;
+        }
+
+        // Release delayed samples to the filter's far-end buffer.
+        while self.delay_available() >= 1 {
+            let sample = self.delay_ring[self.delay_read % self.delay_cap];
+            self.delay_read += 1;
+
+            self.far_buf[self.far_pos] = sample;
+            self.far_pos = (self.far_pos + 1) % self.filter_len;
+
+            // Track peak far-end level for Geigel DTD.
+            let abs_s = sample.abs();
+            if abs_s > self.far_peak {
+                self.far_peak = abs_s;
+            }
+        }
+
+        // Decay far_peak slowly (avoids stale peak from a loud burst long ago).
+        self.far_peak *= 0.9995;
+    }
+
+    /// Number of delayed samples available to release.
+    fn delay_available(&self) -> usize {
+        let buffered = self.delay_write - self.delay_read;
+        if buffered > self.delay_samples {
+            buffered - self.delay_samples
+        } else {
+            0
+        }
+    }
+
+    /// Process a near-end (microphone) frame, removing the estimated echo.
+    pub fn process_frame(&mut self, nearend: &mut [i16]) -> f32 {
+        if !self.enabled {
+            return 1.0;
+        }
+
+        let n = nearend.len();
+        let fl = self.filter_len;
+
+        // --- Geigel double-talk detection ---
+        // If any near-end sample exceeds threshold * far_peak, assume
+        // the local speaker is active and freeze adaptation.
+        let mut is_doubletalk = self.dtd_holdover > 0;
+        if !is_doubletalk {
+            let threshold_level = self.geigel_threshold * self.far_peak;
+            for &s in nearend.iter() {
+                if (s as f32).abs() > threshold_level && self.far_peak > 100.0 {
+                    is_doubletalk = true;
+                    self.dtd_holdover = self.dtd_hold_frames;
+                    break;
+                }
+            }
+        }
+        if self.dtd_holdover > 0 {
+            self.dtd_holdover -= 1;
+        }
+
+        // Check if far-end is active (otherwise nothing to cancel).
+        let far_active = self.far_peak > 100.0;
+
+        // --- Leaky coefficient decay ---
+        // Applied once per frame for efficiency.
+        let decay = 1.0 - self.leak;
+        for c in self.filter.iter_mut() {
+            *c *= decay;
+        }
+
+        let mut sum_near_sq: f64 = 0.0;
+        let mut sum_err_sq: f64 = 0.0;
+
+        for i in 0..n {
+            let near_f = nearend[i] as f32;
+
+            // Position of far-end "now" for this near-end sample.
+            let base = (self.far_pos + fl * ((n / fl) + 2) + i - n) % fl;
+
+            // --- Echo estimation: dot(filter, far_end_window) ---
+            let mut echo_est: f32 = 0.0;
+            let mut power: f32 = 0.0;
+
+            for k in 0..fl {
+                let fe_idx = (base + fl - k) % fl;
+                let fe = self.far_buf[fe_idx];
+                echo_est += self.filter[k] * fe;
+                power += fe * fe;
+            }
+
+            let error = near_f - echo_est;
+
+            // --- NLMS adaptation (only when far-end active & no double-talk) ---
+            if far_active && !is_doubletalk && power > 10.0 {
+                let step = self.mu * error / (power + 1.0);
+                for k in 0..fl {
+                    let fe_idx = (base + fl - k) % fl;
+                    self.filter[k] += step * self.far_buf[fe_idx];
+                }
+            }
+
+            let out = error.clamp(-32768.0, 32767.0);
+            nearend[i] = out as i16;
+
+            sum_near_sq += (near_f as f64).powi(2);
+            sum_err_sq += (out as f64).powi(2);
+        }
+
+        if sum_err_sq < 1.0 {
+            100.0
+        } else {
+            (sum_near_sq / sum_err_sq).sqrt() as f32
+        }
+    }
+
+    pub fn set_enabled(&mut self, enabled: bool) {
+        self.enabled = enabled;
+    }
+
+    pub fn is_enabled(&self) -> bool {
+        self.enabled
+    }
+
+    pub fn reset(&mut self) {
+        self.filter.iter_mut().for_each(|c| *c = 0.0);
+        self.far_buf.iter_mut().for_each(|s| *s = 0.0);
+        self.far_pos = 0;
+        self.far_peak = 0.0;
+        self.delay_ring.iter_mut().for_each(|s| *s = 0.0);
+        self.delay_write = 0;
+        self.delay_read = 0;
+        self.dtd_holdover = 0;
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn creates_with_correct_sizes() {
+        let aec = EchoCanceller::with_delay(48000, 60, 40);
+        assert_eq!(aec.filter_len, 2880); // 60ms @ 48kHz
+        assert_eq!(aec.delay_samples, 1920); // 40ms @ 48kHz
+    }
+
+    #[test]
+    fn passthrough_when_disabled() {
+        let mut aec = EchoCanceller::new(48000, 60);
+        aec.set_enabled(false);
+
+        let original: Vec<i16> = (0..960).map(|i| (i * 10) as i16).collect();
+        let mut frame = original.clone();
+        aec.process_frame(&mut frame);
+        assert_eq!(frame, original);
+    }
+
+    #[test]
+    fn silence_passthrough() {
+        let mut aec = EchoCanceller::with_delay(48000, 30, 0);
+        aec.feed_farend(&vec![0i16; 960]);
+        let mut frame = vec![0i16; 960];
+        aec.process_frame(&mut frame);
+        assert!(frame.iter().all(|&s| s == 0));
+    }
+
+    #[test]
+    fn reduces_echo_with_no_delay() {
+        // Simulate: far-end plays, echo arrives at mic attenuated by ~50%
+        // (realistic — speaker to mic on laptop loses volume).
+        let mut aec = EchoCanceller::with_delay(48000, 10, 0);
+
+        let frame_len = 480;
+        let make_tone = |offset: usize| -> Vec<i16> {
+            (0..frame_len)
+                .map(|i| {
+                    let t = (offset + i) as f64 / 48000.0;
+                    (5000.0 * (2.0 * std::f64::consts::PI * 300.0 * t).sin()) as i16
+                })
+                .collect()
+        };
+
+        let mut last_erle = 1.0f32;
+        for frame_idx in 0..100 {
+            let farend = make_tone(frame_idx * frame_len);
+            aec.feed_farend(&farend);
+
+            // Near-end = attenuated copy of far-end (echo at ~50% volume).
+            let mut nearend: Vec<i16> = farend.iter().map(|&s| s / 2).collect();
+            last_erle = aec.process_frame(&mut nearend);
+        }
+
+        assert!(
+            last_erle > 1.0,
+            "expected ERLE > 1.0 after adaptation, got {last_erle}"
+        );
+    }
+
+    #[test]
+    fn preserves_nearend_during_doubletalk() {
+        let mut aec = EchoCanceller::with_delay(48000, 30, 0);
+
+        let frame_len = 960;
+        let nearend: Vec<i16> = (0..frame_len)
+            .map(|i| {
+                let t = i as f64 / 48000.0;
+                (10000.0 * (2.0 * std::f64::consts::PI * 440.0 * t).sin()) as i16
+            })
+            .collect();
+
+        // Feed silence as far-end (no echo source).
+        aec.feed_farend(&vec![0i16; frame_len]);
+
+        let mut frame = nearend.clone();
+        aec.process_frame(&mut frame);
+
+        let input_energy: f64 = nearend.iter().map(|&s| (s as f64).powi(2)).sum();
+        let output_energy: f64 = frame.iter().map(|&s| (s as f64).powi(2)).sum();
+        let ratio = output_energy / input_energy;
+
+        assert!(
+            ratio > 0.8,
+            "near-end speech should be preserved, energy ratio = {ratio:.3}"
+        );
+    }
+
+    #[test]
+    fn delay_buffer_holds_samples() {
+        let mut aec = EchoCanceller::with_delay(48000, 10, 20);
+        // 20ms delay = 960 samples @ 48kHz.
+        // After feeding, feed_farend auto-drains available samples to far_buf.
+        // So delay_available() is always 0 after feed_farend returns.
+        // Instead, verify far_pos advances only after the delay is filled.
+
+        // Feed 960 samples (= delay amount). No samples released yet.
+        aec.feed_farend(&vec![1i16; 960]);
+        // far_buf should still be all zeros (nothing released).
+        assert!(aec.far_buf.iter().all(|&s| s == 0.0), "nothing should be released yet");
+
+        // Feed 480 more. 480 should be released to far_buf.
+        aec.feed_farend(&vec![2i16; 480]);
+        let non_zero = aec.far_buf.iter().filter(|&&s| s != 0.0).count();
+        assert!(non_zero > 0, "samples should have been released to far_buf");
+    }
+}

crates/wzp-codec/src/agc.rs

@@ -0,0 +1,219 @@
+//! Automatic Gain Control (AGC) with two-stage smoothing.
+//!
+//! Uses a fast attack / slow release envelope follower to keep the
+//! output signal near a configurable target RMS level.  This prevents
+//! both clipping (when the speaker is too loud) and inaudibility (when
+//! the speaker is too quiet or far from the mic).
+
+/// Two-stage automatic gain control.
+///
+/// The gain is adjusted per-frame based on the measured RMS energy,
+/// with a fast attack (gain decreases quickly when signal gets louder)
+/// and a slow release (gain increases gradually when signal gets quieter).
+pub struct AutoGainControl {
+    target_rms: f64,
+    current_gain: f64,
+    min_gain: f64,
+    max_gain: f64,
+    attack_alpha: f64,
+    release_alpha: f64,
+    enabled: bool,
+}
+
+impl AutoGainControl {
+    /// Create a new AGC with sensible VoIP defaults.
+    pub fn new() -> Self {
+        Self {
+            target_rms: 3000.0,   // ~-20 dBFS for i16
+            current_gain: 1.0,
+            min_gain: 0.5,
+            max_gain: 32.0,
+            attack_alpha: 0.3,    // fast attack
+            release_alpha: 0.02,  // slow release
+            enabled: true,
+        }
+    }
+
+    /// Process a frame of PCM audio in-place, applying gain adjustment.
+    pub fn process_frame(&mut self, pcm: &mut [i16]) {
+        if !self.enabled {
+            return;
+        }
+
+        // Compute RMS of the frame.
+        let rms = Self::compute_rms(pcm);
+
+        // Don't amplify near-silence — it would just boost noise.
+        if rms < 10.0 {
+            return;
+        }
+
+        // Desired instantaneous gain.
+        let desired_gain = (self.target_rms / rms).clamp(self.min_gain, self.max_gain);
+
+        // Smooth the gain transition.
+        let alpha = if desired_gain < self.current_gain {
+            // Signal is louder than target → reduce gain quickly (attack).
+            self.attack_alpha
+        } else {
+            // Signal is quieter than target → raise gain slowly (release).
+            self.release_alpha
+        };
+
+        self.current_gain = self.current_gain * (1.0 - alpha) + desired_gain * alpha;
+
+        // Apply gain to each sample with hard limiting at ±31000 (~0.946 * i16::MAX).
+        const LIMIT: f64 = 31000.0;
+        let gain = self.current_gain;
+        for sample in pcm.iter_mut() {
+            let amplified = (*sample as f64) * gain;
+            let clamped = amplified.clamp(-LIMIT, LIMIT);
+            *sample = clamped as i16;
+        }
+    }
+
+    /// Enable or disable the AGC.
+    pub fn set_enabled(&mut self, enabled: bool) {
+        self.enabled = enabled;
+    }
+
+    /// Returns whether the AGC is currently enabled.
+    pub fn is_enabled(&self) -> bool {
+        self.enabled
+    }
+
+    /// Current gain expressed in dB.
+    pub fn current_gain_db(&self) -> f64 {
+        20.0 * self.current_gain.log10()
+    }
+
+    /// Compute the RMS (root mean square) of a PCM buffer.
+    fn compute_rms(pcm: &[i16]) -> f64 {
+        if pcm.is_empty() {
+            return 0.0;
+        }
+        let sum_sq: f64 = pcm.iter().map(|&s| (s as f64) * (s as f64)).sum();
+        (sum_sq / pcm.len() as f64).sqrt()
+    }
+}
+
+impl Default for AutoGainControl {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn agc_creates_with_defaults() {
+        let agc = AutoGainControl::new();
+        assert!(agc.is_enabled());
+        assert!((agc.current_gain - 1.0).abs() < f64::EPSILON);
+    }
+
+    #[test]
+    fn agc_passthrough_when_disabled() {
+        let mut agc = AutoGainControl::new();
+        agc.set_enabled(false);
+
+        let original: Vec<i16> = (0..960).map(|i| (i * 5) as i16).collect();
+        let mut frame = original.clone();
+        agc.process_frame(&mut frame);
+
+        assert_eq!(frame, original);
+    }
+
+    #[test]
+    fn agc_does_not_amplify_silence() {
+        let mut agc = AutoGainControl::new();
+        let mut frame = vec![0i16; 960];
+        agc.process_frame(&mut frame);
+        assert!(frame.iter().all(|&s| s == 0));
+        // Gain should remain at initial value.
+        assert!((agc.current_gain - 1.0).abs() < f64::EPSILON);
+    }
+
+    #[test]
+    fn agc_amplifies_quiet_signal() {
+        let mut agc = AutoGainControl::new();
+
+        // Very quiet signal (RMS ~ 50).
+        let mut frame: Vec<i16> = (0..960)
+            .map(|i| {
+                let t = i as f64 / 48000.0;
+                (50.0 * (2.0 * std::f64::consts::PI * 440.0 * t).sin()) as i16
+            })
+            .collect();
+
+        // Process several frames to let the gain ramp up.
+        for _ in 0..50 {
+            let mut f = frame.clone();
+            agc.process_frame(&mut f);
+            frame = f;
+        }
+
+        // Gain should have increased past 1.0.
+        assert!(
+            agc.current_gain > 1.05,
+            "expected gain > 1.05 for quiet signal, got {}",
+            agc.current_gain
+        );
+    }
+
+    #[test]
+    fn agc_attenuates_loud_signal() {
+        let mut agc = AutoGainControl::new();
+
+        // Loud signal (RMS ~ 20000).
+        let frame: Vec<i16> = (0..960)
+            .map(|i| {
+                let t = i as f64 / 48000.0;
+                (28000.0 * (2.0 * std::f64::consts::PI * 440.0 * t).sin()) as i16
+            })
+            .collect();
+
+        // Process several frames.
+        for _ in 0..20 {
+            let mut f = frame.clone();
+            agc.process_frame(&mut f);
+        }
+
+        // Gain should have decreased below 1.0.
+        assert!(
+            agc.current_gain < 1.0,
+            "expected gain < 1.0 for loud signal, got {}",
+            agc.current_gain
+        );
+    }
+
+    #[test]
+    fn agc_output_within_limits() {
+        let mut agc = AutoGainControl::new();
+        // Force a high gain by processing many quiet frames first.
+        for _ in 0..100 {
+            let mut f: Vec<i16> = vec![100; 960];
+            agc.process_frame(&mut f);
+        }
+
+        // Now send a louder frame — output should still be within ±31000.
+        let mut frame: Vec<i16> = vec![20000; 960];
+        agc.process_frame(&mut frame);
+        assert!(
+            frame.iter().all(|&s| s.abs() <= 31000),
+            "output samples must be within ±31000"
+        );
+    }
+
+    #[test]
+    fn agc_gain_db_at_unity() {
+        let agc = AutoGainControl::new();
+        let db = agc.current_gain_db();
+        assert!(
+            db.abs() < 0.01,
+            "expected ~0 dB at unity gain, got {db}"
+        );
+    }
+}

crates/wzp-codec/src/denoise.rs

@@ -0,0 +1,183 @@
+//! ML-based noise suppression using nnnoiseless (pure-Rust RNNoise port).
+//!
+//! RNNoise operates on 480-sample frames at 48 kHz (10 ms). Our codec pipeline
+//! uses 960-sample frames (20 ms), so each call processes two halves.
+
+use nnnoiseless::DenoiseState;
+
+/// Wraps [`DenoiseState`] to provide noise suppression on 960-sample (20 ms) PCM
+/// frames at 48 kHz.
+pub struct NoiseSupressor {
+    state: Box<DenoiseState<'static>>,
+    enabled: bool,
+}
+
+impl NoiseSupressor {
+    /// Create a new noise suppressor (enabled by default).
+    pub fn new() -> Self {
+        Self {
+            state: DenoiseState::new(),
+            enabled: true,
+        }
+    }
+
+    /// Process a 960-sample frame of 48 kHz mono PCM **in place**.
+    ///
+    /// nnnoiseless expects f32 samples in the range roughly [-32768, 32767].
+    /// We convert i16 → f32, process two 480-sample halves, then convert back.
+    pub fn process(&mut self, pcm: &mut [i16]) {
+        if !self.enabled {
+            return;
+        }
+
+        debug_assert!(
+            pcm.len() >= 960,
+            "NoiseSupressor::process expects at least 960 samples, got {}",
+            pcm.len()
+        );
+
+        // Process in two 480-sample halves.
+        for half in 0..2 {
+            let offset = half * 480;
+            let end = offset + 480;
+            if end > pcm.len() {
+                break;
+            }
+
+            // i16 → f32
+            let mut float_buf = [0.0f32; 480];
+            for (i, &sample) in pcm[offset..end].iter().enumerate() {
+                float_buf[i] = sample as f32;
+            }
+
+            // nnnoiseless processes in-place, returns VAD probability (unused here).
+            let mut output = [0.0f32; 480];
+            let _vad = self.state.process_frame(&mut output, &float_buf);
+
+            // f32 → i16 with clamping
+            for (i, &val) in output.iter().enumerate() {
+                let clamped = val.max(-32768.0).min(32767.0);
+                pcm[offset + i] = clamped as i16;
+            }
+        }
+    }
+
+    /// Enable or disable noise suppression.
+    pub fn set_enabled(&mut self, enabled: bool) {
+        self.enabled = enabled;
+    }
+
+    /// Returns `true` if noise suppression is currently enabled.
+    pub fn is_enabled(&self) -> bool {
+        self.enabled
+    }
+}
+
+impl Default for NoiseSupressor {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn denoiser_creates() {
+        let ns = NoiseSupressor::new();
+        assert!(ns.is_enabled());
+    }
+
+    #[test]
+    fn denoiser_processes_frame() {
+        let mut ns = NoiseSupressor::new();
+        let mut pcm = vec![0i16; 960];
+        // Fill with a simple pattern so we have something to process.
+        for (i, s) in pcm.iter_mut().enumerate() {
+            *s = ((i % 100) as i16).wrapping_mul(100);
+        }
+        let original_len = pcm.len();
+        ns.process(&mut pcm);
+        assert_eq!(pcm.len(), original_len, "output length must match input length");
+    }
+
+    #[test]
+    fn denoiser_reduces_noise() {
+        let mut ns = NoiseSupressor::new();
+
+        // Generate a 440 Hz sine tone + white noise at 48 kHz.
+        // We need multiple frames for the RNN to converge.
+        let sample_rate = 48000.0f64;
+        let freq = 440.0f64;
+        let amplitude = 10000.0f64;
+        let noise_amplitude = 3000.0f64;
+
+        // Use a simple PRNG for reproducibility.
+        let mut rng_state: u32 = 12345;
+        let mut next_noise = || -> f64 {
+            // xorshift32
+            rng_state ^= rng_state << 13;
+            rng_state ^= rng_state >> 17;
+            rng_state ^= rng_state << 5;
+            // Map to [-1, 1]
+            (rng_state as f64 / u32::MAX as f64) * 2.0 - 1.0
+        };
+
+        // Feed several frames to let the RNN warm up, then measure the last one.
+        let num_warmup_frames = 20;
+        let mut last_input = vec![0i16; 960];
+        let mut last_output = vec![0i16; 960];
+
+        for frame_idx in 0..=num_warmup_frames {
+            let mut pcm = vec![0i16; 960];
+            for (i, s) in pcm.iter_mut().enumerate() {
+                let t = (frame_idx * 960 + i) as f64 / sample_rate;
+                let sine = amplitude * (2.0 * std::f64::consts::PI * freq * t).sin();
+                let noise = noise_amplitude * next_noise();
+                *s = (sine + noise).max(-32768.0).min(32767.0) as i16;
+            }
+
+            if frame_idx == num_warmup_frames {
+                last_input = pcm.clone();
+            }
+
+            ns.process(&mut pcm);
+
+            if frame_idx == num_warmup_frames {
+                last_output = pcm;
+            }
+        }
+
+        // Compute RMS of input and output.
+        let rms = |buf: &[i16]| -> f64 {
+            let sum: f64 = buf.iter().map(|&s| (s as f64) * (s as f64)).sum();
+            (sum / buf.len() as f64).sqrt()
+        };
+
+        let input_rms = rms(&last_input);
+        let output_rms = rms(&last_output);
+
+        // The denoiser should not amplify the signal beyond input.
+        // More importantly, the output should have measurably lower noise.
+        // We verify the output RMS is less than the input RMS (noise was reduced).
+        assert!(
+            output_rms < input_rms,
+            "expected output RMS ({output_rms:.1}) < input RMS ({input_rms:.1}); \
+             denoiser should reduce noise"
+        );
+    }
+
+    #[test]
+    fn denoiser_passthrough_when_disabled() {
+        let mut ns = NoiseSupressor::new();
+        ns.set_enabled(false);
+        assert!(!ns.is_enabled());
+
+        let original: Vec<i16> = (0..960).map(|i| (i * 10) as i16).collect();
+        let mut pcm = original.clone();
+        ns.process(&mut pcm);
+
+        assert_eq!(pcm, original, "disabled denoiser must not alter input");
+    }
+}

crates/wzp-codec/src/lib.rs

@@ -10,13 +10,21 @@
 //! trait-object encoders/decoders that handle adaptive switching internally.
 
 pub mod adaptive;
+pub mod aec;
+pub mod agc;
 pub mod codec2_dec;
 pub mod codec2_enc;
+pub mod denoise;
 pub mod opus_dec;
 pub mod opus_enc;
 pub mod resample;
+pub mod silence;
 
 pub use adaptive::{AdaptiveDecoder, AdaptiveEncoder};
+pub use aec::EchoCanceller;
+pub use agc::AutoGainControl;
+pub use denoise::NoiseSupressor;
+pub use silence::{ComfortNoise, SilenceDetector};
 pub use wzp_proto::{AudioDecoder, AudioEncoder, CodecId, QualityProfile};
 
 /// Create an adaptive encoder starting at the given quality profile.

crates/wzp-codec/src/opus_dec.rs

@@ -79,7 +79,7 @@ impl AudioDecoder for OpusDecoder {
 
     fn set_profile(&mut self, profile: QualityProfile) -> Result<(), CodecError> {
         match profile.codec {
-            CodecId::Opus24k | CodecId::Opus16k | CodecId::Opus6k => {
+            c if c.is_opus() => {
                 self.codec_id = profile.codec;
                 self.frame_duration_ms = profile.frame_duration_ms;
                 Ok(())

crates/wzp-codec/src/opus_enc.rs

@@ -40,6 +40,11 @@ impl OpusEncoder {
             .set_signal(Signal::Voice)
             .map_err(|e| CodecError::EncodeFailed(format!("set signal: {e}")))?;
 
+        // Default complexity 7 — good quality/CPU trade-off for VoIP
+        enc.inner
+            .set_complexity(7)
+            .map_err(|e| CodecError::EncodeFailed(format!("set complexity: {e}")))?;
+
         Ok(enc)
     }
 
@@ -56,6 +61,21 @@ impl OpusEncoder {
     pub fn frame_samples(&self) -> usize {
         (48_000 * self.frame_duration_ms as usize) / 1000
     }
+
+    /// Set the encoder complexity (0-10). Higher values produce better quality
+    /// at the cost of more CPU. Default is 7.
+    pub fn set_complexity(&mut self, complexity: i32) {
+        let c = (complexity as u8).min(10);
+        let _ = self.inner.set_complexity(c);
+    }
+
+    /// Hint the encoder about expected packet loss percentage (0-100).
+    ///
+    /// Higher values cause the encoder to use more redundancy to survive
+    /// packet loss, at the expense of slightly higher bitrate.
+    pub fn set_expected_loss(&mut self, loss_pct: u8) {
+        let _ = self.inner.set_packet_loss_perc(loss_pct.min(100));
+    }
 }
 
 impl AudioEncoder for OpusEncoder {
@@ -80,7 +100,7 @@ impl AudioEncoder for OpusEncoder {
 
     fn set_profile(&mut self, profile: QualityProfile) -> Result<(), CodecError> {
         match profile.codec {
-            CodecId::Opus24k | CodecId::Opus16k | CodecId::Opus6k => {
+            c if c.is_opus() => {
                 self.codec_id = profile.codec;
                 self.frame_duration_ms = profile.frame_duration_ms;
                 self.apply_bitrate(profile.codec)?;

crates/wzp-codec/src/resample.rs

@@ -1,55 +1,258 @@
-//! Simple linear resampler for 48 kHz <-> 8 kHz conversion.
+//! Windowed-sinc FIR resampler for 48 kHz <-> 8 kHz conversion.
 //!
-//! These are basic implementations suitable for voice. For higher quality,
-//! replace with the `rubato` crate later.
+//! Provides both stateless free functions (backward-compatible) and stateful
+//! `Downsampler48to8` / `Upsampler8to48` structs that maintain overlap history
+//! between frames for glitch-free streaming.
 
-/// Downsample from 48 kHz to 8 kHz (6:1 decimation with averaging).
+use std::f64::consts::PI;
+
+// ─── FIR kernel parameters ─────────────────────────────────────────────────
+
+/// Number of FIR taps in the anti-alias / interpolation filter.
+const FIR_TAPS: usize = 48;
+/// Kaiser window beta parameter — controls sidelobe attenuation.
+const KAISER_BETA: f64 = 8.0;
+/// Cutoff frequency in Hz for the low-pass filter (just below 4 kHz Nyquist of 8 kHz).
+const CUTOFF_HZ: f64 = 3800.0;
+/// Working sample rate in Hz.
+const SAMPLE_RATE: f64 = 48000.0;
+/// Decimation / interpolation ratio between 48 kHz and 8 kHz.
+const RATIO: usize = 6;
+
+// ─── Kaiser window helpers ─────────────────────────────────────────────────
+
+/// Zeroth-order modified Bessel function of the first kind, I₀(x).
 ///
-/// Each output sample is the average of 6 consecutive input samples,
-/// providing basic anti-aliasing via a box filter.
-pub fn resample_48k_to_8k(input: &[i16]) -> Vec<i16> {
-    const RATIO: usize = 6;
-    let out_len = input.len() / RATIO;
-    let mut output = Vec::with_capacity(out_len);
-
-    for chunk in input.chunks_exact(RATIO) {
-        let sum: i32 = chunk.iter().map(|&s| s as i32).sum();
-        output.push((sum / RATIO as i32) as i16);
+/// Computed via the well-known power-series expansion, converging rapidly
+/// for the moderate values of x used in Kaiser window design.
+fn bessel_i0(x: f64) -> f64 {
+    let mut sum = 1.0f64;
+    let mut term = 1.0f64;
+    let half_x = x / 2.0;
+    for k in 1..=25 {
+        term *= (half_x / k as f64) * (half_x / k as f64);
+        sum += term;
+        if term < 1e-12 * sum {
+            break;
+        }
     }
-
-    output
+    sum
 }
 
-/// Upsample from 8 kHz to 48 kHz (1:6 interpolation with linear interp).
+/// Build a windowed-sinc low-pass FIR kernel.
 ///
-/// Linearly interpolates between each pair of input samples to produce
-/// 6 output samples per input sample.
-pub fn resample_8k_to_48k(input: &[i16]) -> Vec<i16> {
-    const RATIO: usize = 6;
-    if input.is_empty() {
-        return Vec::new();
-    }
+/// Returns `FIR_TAPS` coefficients normalised so that the DC gain is exactly 1.0.
+fn build_fir_kernel() -> [f64; FIR_TAPS] {
+    let mut kernel = [0.0f64; FIR_TAPS];
+    let m = (FIR_TAPS - 1) as f64;
+    let fc = CUTOFF_HZ / SAMPLE_RATE; // normalised cutoff (0..0.5)
+    let beta_denom = bessel_i0(KAISER_BETA);
 
-    let out_len = input.len() * RATIO;
-    let mut output = Vec::with_capacity(out_len);
-
-    for i in 0..input.len() {
-        let current = input[i] as i32;
-        let next = if i + 1 < input.len() {
-            input[i + 1] as i32
+    for i in 0..FIR_TAPS {
+        // Sinc
+        let n = i as f64 - m / 2.0;
+        let sinc = if n.abs() < 1e-12 {
+            2.0 * fc
         } else {
-            current // hold last sample
+            (2.0 * PI * fc * n).sin() / (PI * n)
         };
 
-        for j in 0..RATIO {
-            let interp = current + (next - current) * j as i32 / RATIO as i32;
-            output.push(interp as i16);
+        // Kaiser window
+        let t = 2.0 * i as f64 / m - 1.0; // range [-1, 1]
+        let kaiser = bessel_i0(KAISER_BETA * (1.0 - t * t).max(0.0).sqrt()) / beta_denom;
+
+        kernel[i] = sinc * kaiser;
+    }
+
+    // Normalise to unity DC gain.
+    let sum: f64 = kernel.iter().sum();
+    if sum.abs() > 1e-15 {
+        for k in kernel.iter_mut() {
+            *k /= sum;
         }
     }
 
-    output
+    kernel
 }
 
+// ─── Stateful Downsampler 48→8 ─────────────────────────────────────────────
+
+/// Stateful polyphase FIR downsampler from 48 kHz to 8 kHz.
+///
+/// Maintains `FIR_TAPS - 1` samples of history between successive calls to
+/// `process()` for seamless frame boundaries.
+pub struct Downsampler48to8 {
+    kernel: [f64; FIR_TAPS],
+    history: Vec<f64>,
+}
+
+impl Downsampler48to8 {
+    pub fn new() -> Self {
+        Self {
+            kernel: build_fir_kernel(),
+            history: vec![0.0; FIR_TAPS - 1],
+        }
+    }
+
+    /// Downsample a block of 48 kHz samples to 8 kHz.
+    ///
+    /// The input length should be a multiple of 6; any trailing samples that
+    /// don't form a complete output sample are consumed into the history.
+    pub fn process(&mut self, input: &[i16]) -> Vec<i16> {
+        let hist_len = self.history.len(); // FIR_TAPS - 1
+        let total_len = hist_len + input.len();
+
+        // Build a working buffer: history ++ input (as f64).
+        let mut work = Vec::with_capacity(total_len);
+        work.extend_from_slice(&self.history);
+        work.extend(input.iter().map(|&s| s as f64));
+
+        let out_len = input.len() / RATIO;
+        let mut output = Vec::with_capacity(out_len);
+
+        for i in 0..out_len {
+            // The centre of the filter for output sample i sits at
+            // position hist_len + i*RATIO in the work buffer (aligning
+            // with the first new input sample at decimation phase 0).
+            let centre = hist_len + i * RATIO;
+            let start = centre + 1 - FIR_TAPS; // may be 0 for the first few
+
+            let mut acc = 0.0f64;
+            for k in 0..FIR_TAPS {
+                let idx = start + k;
+                if idx < work.len() {
+                    acc += work[idx] * self.kernel[k];
+                }
+            }
+            output.push(acc.round().clamp(-32768.0, 32767.0) as i16);
+        }
+
+        // Update history: keep the last (FIR_TAPS - 1) samples from work.
+        if work.len() >= hist_len {
+            self.history
+                .copy_from_slice(&work[work.len() - hist_len..]);
+        } else {
+            // Input was shorter than history — shift.
+            let shift = hist_len - work.len();
+            self.history.copy_within(shift.., 0);
+            for (i, &v) in work.iter().enumerate() {
+                self.history[hist_len - work.len() + i] = v;
+            }
+        }
+
+        output
+    }
+}
+
+impl Default for Downsampler48to8 {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+// ─── Stateful Upsampler 8→48 ───────────────────────────────────────────────
+
+/// Stateful FIR upsampler from 8 kHz to 48 kHz.
+///
+/// Inserts zeros between input samples (zero-stuffing), then applies the
+/// low-pass FIR to remove imaging, with gain compensation of `RATIO`.
+pub struct Upsampler8to48 {
+    kernel: [f64; FIR_TAPS],
+    history: Vec<f64>,
+}
+
+impl Upsampler8to48 {
+    pub fn new() -> Self {
+        Self {
+            kernel: build_fir_kernel(),
+            history: vec![0.0; FIR_TAPS - 1],
+        }
+    }
+
+    /// Upsample a block of 8 kHz samples to 48 kHz.
+    pub fn process(&mut self, input: &[i16]) -> Vec<i16> {
+        let hist_len = self.history.len(); // FIR_TAPS - 1
+
+        // Zero-stuff: insert RATIO-1 zeros between each input sample.
+        let stuffed_len = input.len() * RATIO;
+        let total_len = hist_len + stuffed_len;
+
+        let mut work = Vec::with_capacity(total_len);
+        work.extend_from_slice(&self.history);
+        for &s in input {
+            work.push(s as f64);
+            for _ in 1..RATIO {
+                work.push(0.0);
+            }
+        }
+
+        let out_len = stuffed_len;
+        let mut output = Vec::with_capacity(out_len);
+
+        // The gain factor compensates for the zeros introduced by stuffing.
+        let gain = RATIO as f64;
+
+        for i in 0..out_len {
+            let centre = hist_len + i;
+            let start = centre + 1 - FIR_TAPS;
+
+            let mut acc = 0.0f64;
+            for k in 0..FIR_TAPS {
+                let idx = start + k;
+                if idx < work.len() {
+                    acc += work[idx] * self.kernel[k];
+                }
+            }
+            acc *= gain;
+            output.push(acc.round().clamp(-32768.0, 32767.0) as i16);
+        }
+
+        // Update history.
+        if work.len() >= hist_len {
+            self.history
+                .copy_from_slice(&work[work.len() - hist_len..]);
+        } else {
+            let shift = hist_len - work.len();
+            self.history.copy_within(shift.., 0);
+            for (i, &v) in work.iter().enumerate() {
+                self.history[hist_len - work.len() + i] = v;
+            }
+        }
+
+        output
+    }
+}
+
+impl Default for Upsampler8to48 {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+// ─── Backward-compatible free functions ─────────────────────────────────────
+
+/// Downsample from 48 kHz to 8 kHz (6:1 decimation with FIR anti-alias filter).
+///
+/// This is a convenience wrapper that creates a temporary [`Downsampler48to8`].
+/// For streaming use, prefer the stateful struct to avoid edge artefacts between
+/// frames.
+pub fn resample_48k_to_8k(input: &[i16]) -> Vec<i16> {
+    let mut ds = Downsampler48to8::new();
+    ds.process(input)
+}
+
+/// Upsample from 8 kHz to 48 kHz (1:6 interpolation with FIR imaging filter).
+///
+/// This is a convenience wrapper that creates a temporary [`Upsampler8to48`].
+/// For streaming use, prefer the stateful struct to avoid edge artefacts between
+/// frames.
+pub fn resample_8k_to_48k(input: &[i16]) -> Vec<i16> {
+    let mut us = Upsampler8to48::new();
+    us.process(input)
+}
+
+// ─── Tests ──────────────────────────────────────────────────────────────────
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -66,12 +269,28 @@ mod tests {
 
     #[test]
     fn dc_signal_preserved() {
-        // A constant signal should survive resampling
+        // A constant signal should survive resampling (approximately).
         let input = vec![1000i16; 960];
         let down = resample_48k_to_8k(&input);
-        assert!(down.iter().all(|&s| s == 1000));
+        // Allow some edge transient — check that the middle samples are close.
+        let mid_start = down.len() / 4;
+        let mid_end = 3 * down.len() / 4;
+        for &s in &down[mid_start..mid_end] {
+            assert!(
+                (s - 1000).abs() < 50,
+                "DC downsampled sample {s} too far from 1000"
+            );
+        }
+
         let up = resample_8k_to_48k(&down);
-        assert!(up.iter().all(|&s| s == 1000));
+        let mid_start_up = up.len() / 4;
+        let mid_end_up = 3 * up.len() / 4;
+        for &s in &up[mid_start_up..mid_end_up] {
+            assert!(
+                (s - 1000).abs() < 100,
+                "DC upsampled sample {s} too far from 1000"
+            );
+        }
     }
 
     #[test]
@@ -79,4 +298,40 @@ mod tests {
         assert!(resample_48k_to_8k(&[]).is_empty());
         assert!(resample_8k_to_48k(&[]).is_empty());
     }
+
+    #[test]
+    fn stateful_downsampler_produces_correct_length() {
+        let mut ds = Downsampler48to8::new();
+        let out = ds.process(&vec![0i16; 960]);
+        assert_eq!(out.len(), 160);
+        let out2 = ds.process(&vec![0i16; 960]);
+        assert_eq!(out2.len(), 160);
+    }
+
+    #[test]
+    fn stateful_upsampler_produces_correct_length() {
+        let mut us = Upsampler8to48::new();
+        let out = us.process(&vec![0i16; 160]);
+        assert_eq!(out.len(), 960);
+        let out2 = us.process(&vec![0i16; 160]);
+        assert_eq!(out2.len(), 960);
+    }
+
+    #[test]
+    fn fir_kernel_has_unity_dc_gain() {
+        let kernel = build_fir_kernel();
+        let sum: f64 = kernel.iter().sum();
+        assert!(
+            (sum - 1.0).abs() < 1e-10,
+            "FIR kernel DC gain should be 1.0, got {sum}"
+        );
+    }
+
+    #[test]
+    fn bessel_i0_known_values() {
+        // I₀(0) = 1
+        assert!((bessel_i0(0.0) - 1.0).abs() < 1e-12);
+        // I₀(1) ≈ 1.2660658
+        assert!((bessel_i0(1.0) - 1.2660658).abs() < 1e-5);
+    }
 }

crates/wzp-codec/src/silence.rs

@@ -0,0 +1,191 @@
+//! Silence suppression and comfort noise generation.
+//!
+//! During silent periods (~50% of a typical call), full encoded frames waste
+//! bandwidth. [`SilenceDetector`] detects silent audio based on RMS energy,
+//! and [`ComfortNoise`] generates low-level background noise to fill gaps on
+//! the decoder side.
+
+use rand::Rng;
+
+/// Detects silence in PCM audio using RMS energy with a hangover period.
+///
+/// The hangover prevents clipping the onset of speech: after silence is first
+/// detected, the detector continues reporting "not silent" for `hangover_frames`
+/// additional frames before transitioning to suppression.
+pub struct SilenceDetector {
+    /// RMS threshold below which audio is considered silent (for i16 samples).
+    threshold_rms: f64,
+    /// Number of frames to keep sending after silence starts (prevents speech clipping).
+    hangover_frames: u32,
+    /// Count of consecutive frames whose RMS is below the threshold.
+    silent_frames: u32,
+    /// Whether suppression is currently active.
+    is_suppressing: bool,
+}
+
+impl SilenceDetector {
+    /// Create a new silence detector.
+    ///
+    /// * `threshold_rms` — RMS energy below which a frame is silent (default: 100.0 for i16).
+    /// * `hangover_frames` — frames to keep sending after silence onset (default: 5 = 100ms at 20ms frames).
+    pub fn new(threshold_rms: f64, hangover_frames: u32) -> Self {
+        Self {
+            threshold_rms,
+            hangover_frames,
+            silent_frames: 0,
+            is_suppressing: false,
+        }
+    }
+
+    /// Compute the RMS (root mean square) energy of a PCM buffer.
+    pub fn rms(pcm: &[i16]) -> f64 {
+        if pcm.is_empty() {
+            return 0.0;
+        }
+        let sum_sq: f64 = pcm.iter().map(|&s| (s as f64) * (s as f64)).sum();
+        (sum_sq / pcm.len() as f64).sqrt()
+    }
+
+    /// Returns `true` if the frame should be suppressed (i.e. is silence past
+    /// the hangover period).
+    ///
+    /// Call once per frame. The detector tracks consecutive silent frames
+    /// internally and only reports suppression after the hangover expires.
+    pub fn is_silent(&mut self, pcm: &[i16]) -> bool {
+        let energy = Self::rms(pcm);
+
+        if energy < self.threshold_rms {
+            self.silent_frames = self.silent_frames.saturating_add(1);
+
+            if self.silent_frames > self.hangover_frames {
+                self.is_suppressing = true;
+            }
+        } else {
+            // Speech detected — reset.
+            self.silent_frames = 0;
+            self.is_suppressing = false;
+        }
+
+        self.is_suppressing
+    }
+
+    /// Whether the detector is currently in the suppressing state.
+    pub fn suppressing(&self) -> bool {
+        self.is_suppressing
+    }
+}
+
+/// Generates low-level comfort noise to fill silent periods.
+///
+/// When the decoder receives a comfort-noise descriptor (or detects a gap
+/// caused by silence suppression), it uses this to produce a natural-sounding
+/// background hiss instead of dead silence.
+pub struct ComfortNoise {
+    /// Peak amplitude of the generated noise (default: 50).
+    level: i16,
+}
+
+impl ComfortNoise {
+    /// Create a comfort noise generator with the given amplitude level.
+    pub fn new(level: i16) -> Self {
+        Self { level }
+    }
+
+    /// Fill `pcm` with low-level random noise in the range `[-level, level]`.
+    pub fn generate(&self, pcm: &mut [i16]) {
+        let mut rng = rand::thread_rng();
+        for sample in pcm.iter_mut() {
+            *sample = rng.gen_range(-self.level..=self.level);
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn silence_detector_detects_silence() {
+        let mut det = SilenceDetector::new(100.0, 5);
+        let silence = vec![0i16; 960];
+
+        // First 5 frames are hangover — should NOT suppress yet.
+        for _ in 0..5 {
+            assert!(!det.is_silent(&silence));
+        }
+        // Frame 6 onward: past hangover, should suppress.
+        assert!(det.is_silent(&silence));
+        assert!(det.is_silent(&silence));
+    }
+
+    #[test]
+    fn silence_detector_detects_speech() {
+        let mut det = SilenceDetector::new(100.0, 5);
+
+        // Generate a 1kHz sine wave at decent amplitude.
+        let pcm: Vec<i16> = (0..960)
+            .map(|i| {
+                let t = i as f64 / 48000.0;
+                (10000.0 * (2.0 * std::f64::consts::PI * 1000.0 * t).sin()) as i16
+            })
+            .collect();
+
+        // Should never report silent.
+        for _ in 0..20 {
+            assert!(!det.is_silent(&pcm));
+        }
+    }
+
+    #[test]
+    fn silence_detector_hangover() {
+        let mut det = SilenceDetector::new(100.0, 3);
+        let silence = vec![0i16; 960];
+        let speech: Vec<i16> = (0..960)
+            .map(|i| {
+                let t = i as f64 / 48000.0;
+                (5000.0 * (2.0 * std::f64::consts::PI * 440.0 * t).sin()) as i16
+            })
+            .collect();
+
+        // Feed silence past hangover to enter suppression.
+        for _ in 0..4 {
+            det.is_silent(&silence);
+        }
+        assert!(det.is_silent(&silence), "should be suppressing after hangover");
+
+        // Speech arrives — should immediately stop suppressing.
+        assert!(!det.is_silent(&speech));
+        assert!(!det.is_silent(&speech));
+    }
+
+    #[test]
+    fn comfort_noise_generates_nonzero() {
+        let cn = ComfortNoise::new(50);
+        let mut pcm = vec![0i16; 960];
+        cn.generate(&mut pcm);
+
+        // At least some samples should be non-zero.
+        assert!(pcm.iter().any(|&s| s != 0), "CN output should not be all zeros");
+
+        // All samples should be within [-50, 50].
+        assert!(pcm.iter().all(|&s| s.abs() <= 50), "CN samples out of range");
+    }
+
+    #[test]
+    fn rms_calculation() {
+        // All zeros → RMS 0.
+        assert_eq!(SilenceDetector::rms(&[0i16; 100]), 0.0);
+
+        // Constant value: RMS of [v, v, v, ...] = |v|.
+        let pcm = vec![100i16; 100];
+        let rms = SilenceDetector::rms(&pcm);
+        assert!((rms - 100.0).abs() < 0.01, "RMS of constant 100 should be 100, got {rms}");
+
+        // Known pattern: [3, 4] → sqrt((9+16)/2) = sqrt(12.5) ≈ 3.5355
+        let rms2 = SilenceDetector::rms(&[3, 4]);
+        assert!((rms2 - 3.5355).abs() < 0.01, "RMS of [3,4] should be ~3.5355, got {rms2}");
+
+        // Empty buffer → 0.
+        assert_eq!(SilenceDetector::rms(&[]), 0.0);
+    }
+}

crates/wzp-crypto/Cargo.toml

@@ -15,5 +15,18 @@ hkdf = { workspace = true }
 sha2 = { workspace = true }
 rand = { workspace = true }
 tracing = { workspace = true }
+bip39 = "2"
+hex = "0.4"
+
+# featherChat identity — the source of truth for Seed, IdentityKeyPair, Fingerprint
+warzone-protocol = { path = "../../deps/featherchat/warzone/crates/warzone-protocol" }
 
 [dev-dependencies]
+ed25519-dalek = { workspace = true }
+warzone-protocol = { path = "../../deps/featherchat/warzone/crates/warzone-protocol" }
+wzp-proto = { workspace = true }
+wzp-client = { path = "../wzp-client" }
+wzp-relay = { path = "../wzp-relay" }
+serde_json = "1"
+serde = { workspace = true }
+bincode = "1"

crates/wzp-crypto/src/handshake.rs

@@ -110,7 +110,18 @@ impl KeyExchange for WarzoneKeyExchange {
         hk.expand(b"warzone-session-key", &mut session_key)
             .expect("HKDF expand for session key should not fail");
 
-        Ok(Box::new(ChaChaSession::new(session_key)))
+        // Derive SAS (Short Authentication String) from shared secret only.
+        // The shared secret is identical on both sides (X25519 DH property).
+        // A MITM would produce a different shared secret → different SAS.
+        // We use a dedicated HKDF label so SAS is independent of the session key.
+        let mut sas_key = [0u8; 4];
+        hk.expand(b"warzone-sas-code", &mut sas_key)
+            .expect("HKDF expand for SAS should not fail");
+        let sas_code = u32::from_be_bytes(sas_key) % 10000;
+
+        let mut session = ChaChaSession::new(session_key);
+        session.set_sas(sas_code);
+        Ok(Box::new(session))
     }
 }
 
@@ -211,4 +222,47 @@ mod tests {
 
         assert_eq!(&decrypted, plaintext);
     }
+
+    #[test]
+    fn sas_codes_match_between_peers() {
+        let mut alice = WarzoneKeyExchange::from_identity_seed(&[0xAA; 32]);
+        let mut bob = WarzoneKeyExchange::from_identity_seed(&[0xBB; 32]);
+
+        let alice_eph_pub = alice.generate_ephemeral();
+        let bob_eph_pub = bob.generate_ephemeral();
+
+        let alice_session = alice.derive_session(&bob_eph_pub).unwrap();
+        let bob_session = bob.derive_session(&alice_eph_pub).unwrap();
+
+        let alice_sas = alice_session.sas_code();
+        let bob_sas = bob_session.sas_code();
+
+        assert!(alice_sas.is_some(), "Alice should have SAS");
+        assert!(bob_sas.is_some(), "Bob should have SAS");
+        assert_eq!(alice_sas, bob_sas, "SAS codes must match between peers");
+        assert!(alice_sas.unwrap() < 10000, "SAS should be 4 digits");
+    }
+
+    #[test]
+    fn sas_differs_for_different_peers() {
+        let mut alice = WarzoneKeyExchange::from_identity_seed(&[0xAA; 32]);
+        let mut bob = WarzoneKeyExchange::from_identity_seed(&[0xBB; 32]);
+        let mut eve = WarzoneKeyExchange::from_identity_seed(&[0xEE; 32]);
+
+        let alice_eph = alice.generate_ephemeral();
+        let bob_eph = bob.generate_ephemeral();
+        let eve_eph = eve.generate_ephemeral();
+
+        let alice_bob_session = alice.derive_session(&bob_eph).unwrap();
+
+        // Eve does separate handshake with Bob (MITM scenario)
+        let eve_bob_session = eve.derive_session(&bob_eph).unwrap();
+
+        // SAS codes should differ — Eve's session has different shared secret
+        assert_ne!(
+            alice_bob_session.sas_code(),
+            eve_bob_session.sas_code(),
+            "MITM session should produce different SAS"
+        );
+    }
 }

crates/wzp-crypto/src/identity.rs

@@ -0,0 +1,281 @@
+//! featherChat-compatible identity module.
+//!
+//! Mirrors `warzone-protocol/src/identity.rs` and `warzone-protocol/src/mnemonic.rs`
+//! from featherChat. Same seed → same keys → same fingerprint in both codebases.
+//!
+//! Source of truth: deps/featherchat/warzone/crates/warzone-protocol/src/identity.rs
+
+use ed25519_dalek::{SigningKey, VerifyingKey};
+use hkdf::Hkdf;
+use sha2::{Digest, Sha256};
+use x25519_dalek::StaticSecret;
+
+/// The root secret — 32 bytes from which all keys are derived.
+/// Displayed to users as a BIP39 mnemonic (24 words).
+///
+/// Mirrors: `warzone-protocol::identity::Seed`
+pub struct Seed(pub [u8; 32]);
+
+impl Seed {
+    /// Generate a new random seed.
+    pub fn generate() -> Self {
+        let mut bytes = [0u8; 32];
+        rand::RngCore::fill_bytes(&mut rand::rngs::OsRng, &mut bytes);
+        Seed(bytes)
+    }
+
+    /// Create seed from raw bytes.
+    pub fn from_bytes(bytes: [u8; 32]) -> Self {
+        Seed(bytes)
+    }
+
+    /// Create seed from hex string (64 hex chars).
+    pub fn from_hex(hex_str: &str) -> Result<Self, String> {
+        let bytes = hex::decode(hex_str).map_err(|e| format!("invalid hex: {e}"))?;
+        if bytes.len() != 32 {
+            return Err(format!("expected 32 bytes, got {}", bytes.len()));
+        }
+        let mut seed = [0u8; 32];
+        seed.copy_from_slice(&bytes);
+        Ok(Seed(seed))
+    }
+
+    /// Derive the full identity keypair from this seed.
+    ///
+    /// Uses identical HKDF derivation as featherChat:
+    /// - Ed25519: `HKDF(seed, salt=None, info="warzone-ed25519")`
+    /// - X25519:  `HKDF(seed, salt=None, info="warzone-x25519")`
+    pub fn derive_identity(&self) -> IdentityKeyPair {
+        let hk = Hkdf::<Sha256>::new(None, &self.0);
+
+        let mut ed_bytes = [0u8; 32];
+        hk.expand(b"warzone-ed25519", &mut ed_bytes)
+            .expect("HKDF expand for Ed25519");
+        let signing = SigningKey::from_bytes(&ed_bytes);
+        ed_bytes.fill(0);
+
+        let mut x_bytes = [0u8; 32];
+        hk.expand(b"warzone-x25519", &mut x_bytes)
+            .expect("HKDF expand for X25519");
+        let encryption = StaticSecret::from(x_bytes);
+        x_bytes.fill(0);
+
+        IdentityKeyPair {
+            signing,
+            encryption,
+        }
+    }
+
+    /// Convert to BIP39 mnemonic (24 words).
+    ///
+    /// Mirrors: `warzone-protocol::mnemonic::seed_to_mnemonic`
+    pub fn to_mnemonic(&self) -> String {
+        let mnemonic =
+            bip39::Mnemonic::from_entropy(&self.0).expect("32 bytes is valid BIP39 entropy");
+        mnemonic.to_string()
+    }
+
+    /// Recover seed from BIP39 mnemonic (24 words).
+    ///
+    /// Mirrors: `warzone-protocol::mnemonic::mnemonic_to_seed`
+    pub fn from_mnemonic(words: &str) -> Result<Self, String> {
+        let mnemonic: bip39::Mnemonic = words.parse().map_err(|e| format!("invalid mnemonic: {e}"))?;
+        let entropy = mnemonic.to_entropy();
+        if entropy.len() != 32 {
+            return Err(format!("expected 32 bytes entropy, got {}", entropy.len()));
+        }
+        let mut seed = [0u8; 32];
+        seed.copy_from_slice(&entropy);
+        Ok(Seed(seed))
+    }
+}
+
+impl Drop for Seed {
+    fn drop(&mut self) {
+        self.0.fill(0); // zeroize on drop
+    }
+}
+
+/// The full identity keypair derived from a seed.
+///
+/// Mirrors: `warzone-protocol::identity::IdentityKeyPair`
+pub struct IdentityKeyPair {
+    pub signing: SigningKey,
+    pub encryption: StaticSecret,
+}
+
+impl IdentityKeyPair {
+    /// Get the public identity (safe to share).
+    pub fn public_identity(&self) -> PublicIdentity {
+        let verifying = self.signing.verifying_key();
+        let encryption_pub = x25519_dalek::PublicKey::from(&self.encryption);
+        let fingerprint = Fingerprint::from_verifying_key(&verifying);
+
+        PublicIdentity {
+            signing: verifying,
+            encryption: encryption_pub,
+            fingerprint,
+        }
+    }
+}
+
+/// Truncated SHA-256 hash of the Ed25519 public key (16 bytes).
+/// Displayed as `xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx`.
+///
+/// Mirrors: `warzone-protocol::types::Fingerprint`
+#[derive(Clone, Copy, PartialEq, Eq, Hash)]
+pub struct Fingerprint(pub [u8; 16]);
+
+impl Fingerprint {
+    pub fn from_verifying_key(key: &VerifyingKey) -> Self {
+        let hash = Sha256::digest(key.as_bytes());
+        let mut fp = [0u8; 16];
+        fp.copy_from_slice(&hash[..16]);
+        Fingerprint(fp)
+    }
+
+    /// Parse from hex string (with or without colons).
+    pub fn from_hex(s: &str) -> Result<Self, String> {
+        let clean: String = s.chars().filter(|c| c.is_ascii_hexdigit()).collect();
+        let bytes = hex::decode(&clean).map_err(|e| format!("invalid hex: {e}"))?;
+        if bytes.len() < 16 {
+            return Err("fingerprint too short".to_string());
+        }
+        let mut fp = [0u8; 16];
+        fp.copy_from_slice(&bytes[..16]);
+        Ok(Fingerprint(fp))
+    }
+
+    /// As raw bytes.
+    pub fn as_bytes(&self) -> &[u8; 16] {
+        &self.0
+    }
+
+    /// As hex string without colons.
+    pub fn to_hex(&self) -> String {
+        hex::encode(self.0)
+    }
+}
+
+impl std::fmt::Display for Fingerprint {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(
+            f,
+            "{:04x}:{:04x}:{:04x}:{:04x}:{:04x}:{:04x}:{:04x}:{:04x}",
+            u16::from_be_bytes([self.0[0], self.0[1]]),
+            u16::from_be_bytes([self.0[2], self.0[3]]),
+            u16::from_be_bytes([self.0[4], self.0[5]]),
+            u16::from_be_bytes([self.0[6], self.0[7]]),
+            u16::from_be_bytes([self.0[8], self.0[9]]),
+            u16::from_be_bytes([self.0[10], self.0[11]]),
+            u16::from_be_bytes([self.0[12], self.0[13]]),
+            u16::from_be_bytes([self.0[14], self.0[15]]),
+        )
+    }
+}
+
+impl std::fmt::Debug for Fingerprint {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "Fingerprint({})", self)
+    }
+}
+
+/// The public portion of an identity — safe to share with anyone.
+pub struct PublicIdentity {
+    pub signing: VerifyingKey,
+    pub encryption: x25519_dalek::PublicKey,
+    pub fingerprint: Fingerprint,
+}
+
+/// Hash a human-readable room/group name into an opaque hex string.
+/// Used as QUIC SNI to prevent leaking group names to network observers.
+///
+/// `hash_room_name("my-group")` → 32 hex chars (16 bytes of SHA-256).
+///
+/// Mirrors the convention in featherChat WZP-FC-5:
+/// `SHA-256("featherchat-group:" + group_name)[:16]`
+pub fn hash_room_name(group_name: &str) -> String {
+    use sha2::{Digest, Sha256};
+    let mut hasher = Sha256::new();
+    hasher.update(b"featherchat-group:");
+    hasher.update(group_name.as_bytes());
+    let hash = hasher.finalize();
+    hex::encode(&hash[..16])
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn deterministic_derivation() {
+        let seed = Seed::from_bytes([42u8; 32]);
+        let id1 = seed.derive_identity();
+        let id2 = seed.derive_identity();
+        assert_eq!(
+            id1.signing.verifying_key().as_bytes(),
+            id2.signing.verifying_key().as_bytes(),
+        );
+    }
+
+    #[test]
+    fn mnemonic_roundtrip() {
+        let seed = Seed::generate();
+        let words = seed.to_mnemonic();
+        let word_count = words.split_whitespace().count();
+        assert_eq!(word_count, 24);
+        let recovered = Seed::from_mnemonic(&words).unwrap();
+        assert_eq!(seed.0, recovered.0);
+    }
+
+    #[test]
+    fn hex_roundtrip() {
+        let seed = Seed::generate();
+        let hex_str = hex::encode(seed.0);
+        let recovered = Seed::from_hex(&hex_str).unwrap();
+        assert_eq!(seed.0, recovered.0);
+    }
+
+    #[test]
+    fn fingerprint_format() {
+        let seed = Seed::generate();
+        let id = seed.derive_identity();
+        let pub_id = id.public_identity();
+        let fp_str = pub_id.fingerprint.to_string();
+        // Format: xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx
+        assert_eq!(fp_str.len(), 39);
+        assert_eq!(fp_str.chars().filter(|c| *c == ':').count(), 7);
+    }
+
+    #[test]
+    fn hash_room_name_deterministic() {
+        let h1 = hash_room_name("my-group");
+        let h2 = hash_room_name("my-group");
+        assert_eq!(h1, h2);
+        assert_eq!(h1.len(), 32); // 16 bytes = 32 hex chars
+        assert!(h1.chars().all(|c| c.is_ascii_hexdigit()));
+    }
+
+    #[test]
+    fn hash_room_name_different_inputs() {
+        assert_ne!(hash_room_name("alpha"), hash_room_name("beta"));
+    }
+
+    #[test]
+    fn matches_handshake_derivation() {
+        use wzp_proto::KeyExchange;
+        // Verify identity module matches the KeyExchange trait implementation
+        let seed = [99u8; 32];
+        let id = Seed::from_bytes(seed).derive_identity();
+        let kx = crate::WarzoneKeyExchange::from_identity_seed(&seed);
+
+        assert_eq!(
+            id.signing.verifying_key().as_bytes(),
+            &kx.identity_public_key(),
+        );
+        assert_eq!(
+            id.public_identity().fingerprint.as_bytes(),
+            &kx.fingerprint(),
+        );
+    }
+}

crates/wzp-crypto/src/lib.rs

@@ -9,12 +9,14 @@
 
 pub mod anti_replay;
 pub mod handshake;
+pub mod identity;
 pub mod nonce;
 pub mod rekey;
 pub mod session;
 
 pub use anti_replay::AntiReplayWindow;
 pub use handshake::WarzoneKeyExchange;
+pub use identity::{hash_room_name, Fingerprint, IdentityKeyPair, PublicIdentity, Seed};
 pub use nonce::{build_nonce, Direction};
 pub use rekey::RekeyManager;
 pub use session::ChaChaSession;

crates/wzp-crypto/src/session.rs

@@ -26,6 +26,8 @@ pub struct ChaChaSession {
     rekey_mgr: RekeyManager,
     /// Pending ephemeral secret for rekey (stored until peer responds).
     pending_rekey_secret: Option<StaticSecret>,
+    /// Short Authentication String (4-digit code for verbal verification).
+    sas_code: Option<u32>,
 }
 
 impl ChaChaSession {
@@ -46,9 +48,15 @@ impl ChaChaSession {
             recv_seq: 0,
             rekey_mgr: RekeyManager::new(shared_secret),
             pending_rekey_secret: None,
+            sas_code: None,
         }
     }
 
+    /// Set the SAS code (called by key exchange after derivation).
+    pub fn set_sas(&mut self, code: u32) {
+        self.sas_code = Some(code);
+    }
+
     /// Install a new key (after rekeying).
     fn install_key(&mut self, new_key: [u8; 32]) {
         use sha2::Digest;
@@ -136,6 +144,10 @@ impl CryptoSession for ChaChaSession {
 
         Ok(())
     }
+
+    fn sas_code(&self) -> Option<u32> {
+        self.sas_code
+    }
 }
 
 #[cfg(test)]

crates/wzp-crypto/tests/featherchat_compat.rs

@@ -0,0 +1,571 @@
+//! Cross-project compatibility tests between WZP and featherChat.
+//!
+//! Verifies:
+//! 1. Identity: same seed → same keys → same fingerprints (WZP-FC-8)
+//! 2. CallSignal: WZP SignalMessage serializes into FC CallSignal.payload correctly
+//! 3. Auth: WZP auth module request/response matches FC's /v1/auth/validate contract
+//! 4. Mnemonic: BIP39 interop between both implementations
+
+use wzp_proto::KeyExchange;
+
+// ─── Identity Compatibility (WZP-FC-8) ──────────────────────────────────────
+
+#[test]
+fn same_seed_same_ed25519_key() {
+    let seed = [42u8; 32];
+
+    let wzp_kx = wzp_crypto::WarzoneKeyExchange::from_identity_seed(&seed);
+    let wzp_pub = wzp_kx.identity_public_key();
+
+    let fc_seed = warzone_protocol::identity::Seed::from_bytes(seed);
+    let fc_id = fc_seed.derive_identity();
+    let fc_pub = fc_id.signing.verifying_key();
+
+    assert_eq!(&wzp_pub, fc_pub.as_bytes(), "Ed25519 keys must match");
+}
+
+#[test]
+fn same_seed_same_fingerprint() {
+    let seed = [99u8; 32];
+
+    let wzp_kx = wzp_crypto::WarzoneKeyExchange::from_identity_seed(&seed);
+    let wzp_fp = wzp_kx.fingerprint();
+
+    let fc_seed = warzone_protocol::identity::Seed::from_bytes(seed);
+    let fc_fp = fc_seed.derive_identity().public_identity().fingerprint.0;
+
+    assert_eq!(wzp_fp, fc_fp, "Fingerprints must match");
+}
+
+#[test]
+fn wzp_identity_module_matches_featherchat() {
+    let seed = [0xAB; 32];
+
+    let wzp_pub = wzp_crypto::Seed::from_bytes(seed)
+        .derive_identity()
+        .public_identity();
+
+    let fc_pub = warzone_protocol::identity::Seed::from_bytes(seed)
+        .derive_identity()
+        .public_identity();
+
+    assert_eq!(wzp_pub.signing.as_bytes(), fc_pub.signing.as_bytes());
+    assert_eq!(wzp_pub.encryption.as_bytes(), fc_pub.encryption.as_bytes());
+    assert_eq!(wzp_pub.fingerprint.0, fc_pub.fingerprint.0);
+    assert_eq!(wzp_pub.fingerprint.to_string(), fc_pub.fingerprint.to_string());
+}
+
+#[test]
+fn random_seed_identity_match() {
+    let fc_seed = warzone_protocol::identity::Seed::generate();
+    let raw = fc_seed.0;
+
+    let fc_fp = fc_seed.derive_identity().public_identity().fingerprint.0;
+    let wzp_fp = wzp_crypto::WarzoneKeyExchange::from_identity_seed(&raw).fingerprint();
+
+    assert_eq!(wzp_fp, fc_fp);
+}
+
+#[test]
+fn hkdf_derive_matches() {
+    let seed = [0x55; 32];
+
+    let fc_ed = warzone_protocol::crypto::hkdf_derive(&seed, b"", b"warzone-ed25519", 32);
+    let fc_signing = ed25519_dalek::SigningKey::from_bytes(&fc_ed.try_into().unwrap());
+    let fc_pub = fc_signing.verifying_key();
+
+    let wzp_pub = wzp_crypto::WarzoneKeyExchange::from_identity_seed(&seed).identity_public_key();
+
+    assert_eq!(&wzp_pub, fc_pub.as_bytes());
+}
+
+// ─── BIP39 Mnemonic Interop ─────────────────────────────────────────────────
+
+#[test]
+fn mnemonic_roundtrip_fc_to_wzp() {
+    let seed = [0x77; 32];
+    let fc_mnemonic = warzone_protocol::identity::Seed::from_bytes(seed).to_mnemonic();
+    let wzp_recovered = wzp_crypto::Seed::from_mnemonic(&fc_mnemonic).unwrap();
+    assert_eq!(wzp_recovered.0, seed);
+}
+
+#[test]
+fn mnemonic_roundtrip_wzp_to_fc() {
+    let seed = [0x33; 32];
+    let wzp_mnemonic = wzp_crypto::Seed::from_bytes(seed).to_mnemonic();
+    let fc_recovered = warzone_protocol::identity::Seed::from_mnemonic(&wzp_mnemonic).unwrap();
+    assert_eq!(fc_recovered.0, seed);
+}
+
+#[test]
+fn mnemonic_strings_identical() {
+    let seed = [0xDE; 32];
+    let fc_words = warzone_protocol::identity::Seed::from_bytes(seed).to_mnemonic();
+    let wzp_words = wzp_crypto::Seed::from_bytes(seed).to_mnemonic();
+    assert_eq!(fc_words, wzp_words);
+}
+
+// ─── CallSignal Payload Interop ─────────────────────────────────────────────
+
+#[test]
+fn wzp_signal_serializes_into_fc_callsignal_payload() {
+    // WZP creates a CallOffer SignalMessage
+    let offer = wzp_proto::SignalMessage::CallOffer {
+        identity_pub: [1u8; 32],
+        ephemeral_pub: [2u8; 32],
+        signature: vec![3u8; 64],
+        supported_profiles: vec![wzp_proto::QualityProfile::GOOD],
+    };
+
+    // Encode as featherChat CallSignal payload
+    let payload = wzp_client::featherchat::encode_call_payload(
+        &offer,
+        Some("relay.example.com:4433"),
+        Some("myroom"),
+    );
+
+    // Verify it's valid JSON
+    let parsed: serde_json::Value = serde_json::from_str(&payload).unwrap();
+    assert!(parsed.get("signal").is_some());
+    assert_eq!(parsed["relay_addr"], "relay.example.com:4433");
+    assert_eq!(parsed["room"], "myroom");
+
+    // featherChat would put this in WireMessage::CallSignal { payload, ... }
+    // Verify the FC side can create a CallSignal with this payload
+    let fc_msg = warzone_protocol::message::WireMessage::CallSignal {
+        id: "call-123".to_string(),
+        sender_fingerprint: "abcd1234".to_string(),
+        signal_type: warzone_protocol::message::CallSignalType::Offer,
+        payload: payload.clone(),
+        target: "peer-fingerprint".to_string(),
+    };
+
+    // Verify it serializes with bincode (FC's wire format)
+    let encoded = bincode::serialize(&fc_msg).unwrap();
+    assert!(!encoded.is_empty());
+
+    // And deserializes back
+    let decoded: warzone_protocol::message::WireMessage = bincode::deserialize(&encoded).unwrap();
+    if let warzone_protocol::message::WireMessage::CallSignal {
+        id, payload: p, signal_type, ..
+    } = decoded
+    {
+        assert_eq!(id, "call-123");
+        assert!(matches!(signal_type, warzone_protocol::message::CallSignalType::Offer));
+
+        // Decode the WZP payload back
+        let wzp_payload = wzp_client::featherchat::decode_call_payload(&p).unwrap();
+        assert_eq!(wzp_payload.relay_addr.unwrap(), "relay.example.com:4433");
+        assert!(matches!(wzp_payload.signal, wzp_proto::SignalMessage::CallOffer { .. }));
+    } else {
+        panic!("expected CallSignal");
+    }
+}
+
+#[test]
+fn wzp_answer_round_trips_through_fc_callsignal() {
+    let answer = wzp_proto::SignalMessage::CallAnswer {
+        identity_pub: [10u8; 32],
+        ephemeral_pub: [20u8; 32],
+        signature: vec![30u8; 64],
+        chosen_profile: wzp_proto::QualityProfile::DEGRADED,
+    };
+
+    let payload = wzp_client::featherchat::encode_call_payload(&answer, None, None);
+
+    let fc_msg = warzone_protocol::message::WireMessage::CallSignal {
+        id: "call-456".to_string(),
+        sender_fingerprint: "efgh5678".to_string(),
+        signal_type: warzone_protocol::message::CallSignalType::Answer,
+        payload,
+        target: "caller-fp".to_string(),
+    };
+
+    let bytes = bincode::serialize(&fc_msg).unwrap();
+    let decoded: warzone_protocol::message::WireMessage = bincode::deserialize(&bytes).unwrap();
+
+    if let warzone_protocol::message::WireMessage::CallSignal { payload, .. } = decoded {
+        let wzp = wzp_client::featherchat::decode_call_payload(&payload).unwrap();
+        if let wzp_proto::SignalMessage::CallAnswer { chosen_profile, .. } = wzp.signal {
+            assert_eq!(chosen_profile.codec, wzp_proto::CodecId::Opus6k);
+        } else {
+            panic!("expected CallAnswer");
+        }
+    }
+}
+
+#[test]
+fn wzp_hangup_round_trips_through_fc_callsignal() {
+    let hangup = wzp_proto::SignalMessage::Hangup {
+        reason: wzp_proto::HangupReason::Normal,
+    };
+
+    let payload = wzp_client::featherchat::encode_call_payload(&hangup, None, None);
+    let signal_type = wzp_client::featherchat::signal_to_call_type(&hangup);
+    assert!(matches!(signal_type, wzp_client::featherchat::CallSignalType::Hangup));
+
+    let fc_msg = warzone_protocol::message::WireMessage::CallSignal {
+        id: "call-789".to_string(),
+        sender_fingerprint: "xyz".to_string(),
+        signal_type: warzone_protocol::message::CallSignalType::Hangup,
+        payload,
+        target: "peer".to_string(),
+    };
+
+    let bytes = bincode::serialize(&fc_msg).unwrap();
+    let decoded: warzone_protocol::message::WireMessage = bincode::deserialize(&bytes).unwrap();
+
+    if let warzone_protocol::message::WireMessage::CallSignal { payload, .. } = decoded {
+        let wzp = wzp_client::featherchat::decode_call_payload(&payload).unwrap();
+        assert!(matches!(wzp.signal, wzp_proto::SignalMessage::Hangup { .. }));
+    }
+}
+
+// ─── Auth Token Contract ────────────────────────────────────────────────────
+
+#[test]
+fn auth_validate_request_matches_fc_contract() {
+    // WZP sends: { "token": "..." }
+    // FC expects: ValidateRequest { token: String }
+    let wzp_request = serde_json::json!({ "token": "test-token-123" });
+    let json_str = wzp_request.to_string();
+
+    // FC can deserialize this (same shape as their ValidateRequest)
+    #[derive(serde::Deserialize)]
+    struct FcValidateRequest {
+        token: String,
+    }
+    let fc_req: FcValidateRequest = serde_json::from_str(&json_str).unwrap();
+    assert_eq!(fc_req.token, "test-token-123");
+}
+
+#[test]
+fn auth_validate_response_matches_wzp_expectations() {
+    // FC returns: { "valid": true, "fingerprint": "...", "alias": "..." }
+    // WZP expects: wzp_relay::auth::ValidateResponse
+    let fc_response = serde_json::json!({
+        "valid": true,
+        "fingerprint": "a3f8:1b2c:3d4e:5f60:7182:93a4:b5c6:d7e8",
+        "alias": "manwe",
+        "eth_address": null
+    });
+
+    let wzp_resp: wzp_relay::auth::ValidateResponse =
+        serde_json::from_value(fc_response).unwrap();
+    assert!(wzp_resp.valid);
+    assert_eq!(
+        wzp_resp.fingerprint.unwrap(),
+        "a3f8:1b2c:3d4e:5f60:7182:93a4:b5c6:d7e8"
+    );
+    assert_eq!(wzp_resp.alias.unwrap(), "manwe");
+}
+
+#[test]
+fn auth_invalid_response_matches() {
+    let fc_response = serde_json::json!({ "valid": false });
+    let wzp_resp: wzp_relay::auth::ValidateResponse =
+        serde_json::from_value(fc_response).unwrap();
+    assert!(!wzp_resp.valid);
+    assert!(wzp_resp.fingerprint.is_none());
+}
+
+// ─── Signal Type Mapping ────────────────────────────────────────────────────
+
+#[test]
+fn all_signal_types_map_correctly() {
+    use wzp_client::featherchat::{signal_to_call_type, CallSignalType};
+
+    let cases: Vec<(wzp_proto::SignalMessage, &str)> = vec![
+        (
+            wzp_proto::SignalMessage::CallOffer {
+                identity_pub: [0; 32], ephemeral_pub: [0; 32],
+                signature: vec![], supported_profiles: vec![],
+            },
+            "Offer",
+        ),
+        (
+            wzp_proto::SignalMessage::CallAnswer {
+                identity_pub: [0; 32], ephemeral_pub: [0; 32],
+                signature: vec![],
+                chosen_profile: wzp_proto::QualityProfile::GOOD,
+            },
+            "Answer",
+        ),
+        (
+            wzp_proto::SignalMessage::IceCandidate {
+                candidate: "candidate:1".to_string(),
+            },
+            "IceCandidate",
+        ),
+        (
+            wzp_proto::SignalMessage::Hangup {
+                reason: wzp_proto::HangupReason::Normal,
+            },
+            "Hangup",
+        ),
+    ];
+
+    for (signal, expected_name) in cases {
+        let ct = signal_to_call_type(&signal);
+        let name = format!("{ct:?}");
+        assert_eq!(name, expected_name, "signal type mapping for {expected_name}");
+    }
+}
+
+// ─── Room Hashing + Access Control ─────────────────────────────────────────
+
+#[test]
+fn hash_room_name_deterministic() {
+    let h1 = wzp_crypto::hash_room_name("ops-channel");
+    let h2 = wzp_crypto::hash_room_name("ops-channel");
+    assert_eq!(h1, h2, "same input must produce same hash");
+}
+
+#[test]
+fn hash_room_name_is_32_hex_chars() {
+    let h = wzp_crypto::hash_room_name("test-room");
+    assert_eq!(h.len(), 32, "hash must be 32 hex chars (16 bytes)");
+    assert!(
+        h.chars().all(|c| c.is_ascii_hexdigit()),
+        "hash must contain only hex characters, got: {h}"
+    );
+}
+
+#[test]
+fn hash_room_name_different_inputs() {
+    let h1 = wzp_crypto::hash_room_name("alpha");
+    let h2 = wzp_crypto::hash_room_name("beta");
+    let h3 = wzp_crypto::hash_room_name("alpha-2");
+    assert_ne!(h1, h2, "different names must produce different hashes");
+    assert_ne!(h1, h3);
+    assert_ne!(h2, h3);
+}
+
+#[test]
+fn hash_room_name_matches_fc_convention() {
+    // Manual SHA-256("featherchat-group:" + name)[:16] using the sha2 crate directly
+    use sha2::{Digest, Sha256};
+
+    let name = "warzone-squad";
+    let mut hasher = Sha256::new();
+    hasher.update(b"featherchat-group:");
+    hasher.update(name.as_bytes());
+    let digest = hasher.finalize();
+    let expected = hex::encode(&digest[..16]);
+
+    let actual = wzp_crypto::hash_room_name(name);
+    assert_eq!(
+        actual, expected,
+        "hash_room_name must equal SHA-256('featherchat-group:' + name)[:16]"
+    );
+}
+
+#[test]
+fn room_acl_open_mode() {
+    let mgr = wzp_relay::room::RoomManager::new();
+    // Open mode: everyone is authorized regardless of fingerprint presence
+    assert!(mgr.is_authorized("any-room", None));
+    assert!(mgr.is_authorized("any-room", Some("random-fp")));
+    assert!(mgr.is_authorized("another-room", Some("abc:def")));
+}
+
+#[test]
+fn room_acl_enforced() {
+    let mgr = wzp_relay::room::RoomManager::with_acl();
+    // ACL enabled but no fingerprint provided => denied
+    assert!(
+        !mgr.is_authorized("room1", None),
+        "ACL mode must reject connections without a fingerprint"
+    );
+}
+
+#[test]
+fn room_acl_allows_listed() {
+    let mut mgr = wzp_relay::room::RoomManager::with_acl();
+    mgr.allow("secure-room", "alice-fp");
+    mgr.allow("secure-room", "bob-fp");
+
+    assert!(mgr.is_authorized("secure-room", Some("alice-fp")));
+    assert!(mgr.is_authorized("secure-room", Some("bob-fp")));
+}
+
+#[test]
+fn room_acl_denies_unlisted() {
+    let mut mgr = wzp_relay::room::RoomManager::with_acl();
+    mgr.allow("secure-room", "alice-fp");
+
+    assert!(
+        !mgr.is_authorized("secure-room", Some("eve-fp")),
+        "unlisted fingerprints must be denied"
+    );
+    assert!(
+        !mgr.is_authorized("secure-room", Some("mallory-fp")),
+        "unlisted fingerprints must be denied"
+    );
+    // No fingerprint at all => also denied
+    assert!(
+        !mgr.is_authorized("secure-room", None),
+        "no fingerprint must be denied in ACL mode"
+    );
+}
+
+// ─── Web Bridge Auth + Proto Standalone + S-9 ──────────────────────────────
+
+/// WZP-S-6: featherChat may include `eth_address` in ValidateResponse.
+/// WZP's ValidateResponse must handle it gracefully (serde ignores unknown fields).
+#[test]
+fn auth_response_with_eth_address() {
+    // FC response with eth_address present (non-null)
+    let with_eth = serde_json::json!({
+        "valid": true,
+        "fingerprint": "a1b2:c3d4:e5f6:7890:abcd:ef01:2345:6789",
+        "alias": "vitalik",
+        "eth_address": "0x1234567890abcdef1234567890abcdef12345678"
+    });
+    let resp: wzp_relay::auth::ValidateResponse =
+        serde_json::from_value(with_eth).unwrap();
+    assert!(resp.valid);
+    assert_eq!(
+        resp.fingerprint.unwrap(),
+        "a1b2:c3d4:e5f6:7890:abcd:ef01:2345:6789"
+    );
+    assert_eq!(resp.alias.unwrap(), "vitalik");
+
+    // FC response with eth_address = null
+    let with_null_eth = serde_json::json!({
+        "valid": true,
+        "fingerprint": "dead:beef:cafe:babe:1234:5678:9abc:def0",
+        "alias": "anon",
+        "eth_address": null
+    });
+    let resp2: wzp_relay::auth::ValidateResponse =
+        serde_json::from_value(with_null_eth).unwrap();
+    assert!(resp2.valid);
+    assert_eq!(
+        resp2.fingerprint.unwrap(),
+        "dead:beef:cafe:babe:1234:5678:9abc:def0"
+    );
+
+    // FC response without eth_address at all
+    let without_eth = serde_json::json!({
+        "valid": false
+    });
+    let resp3: wzp_relay::auth::ValidateResponse =
+        serde_json::from_value(without_eth).unwrap();
+    assert!(!resp3.valid);
+}
+
+/// WZP-S-7: SignalMessage::AuthToken { token } exists and round-trips via serde.
+#[test]
+fn wzp_proto_has_auth_token_variant() {
+    let msg = wzp_proto::SignalMessage::AuthToken {
+        token: "fc-bearer-token-xyz".to_string(),
+    };
+
+    // Serialize to JSON
+    let json = serde_json::to_string(&msg).unwrap();
+    assert!(json.contains("AuthToken"));
+    assert!(json.contains("fc-bearer-token-xyz"));
+
+    // Deserialize back
+    let decoded: wzp_proto::SignalMessage = serde_json::from_str(&json).unwrap();
+    if let wzp_proto::SignalMessage::AuthToken { token } = decoded {
+        assert_eq!(token, "fc-bearer-token-xyz");
+    } else {
+        panic!("expected AuthToken variant, got: {decoded:?}");
+    }
+}
+
+/// WZP-S-6: WZP CallSignalType has all variants matching featherChat's set.
+#[test]
+fn all_fc_call_signal_types_representable() {
+    use wzp_client::featherchat::CallSignalType;
+
+    // Verify each FC variant can be constructed and debug-printed
+    let variants: Vec<(CallSignalType, &str)> = vec![
+        (CallSignalType::Offer, "Offer"),
+        (CallSignalType::Answer, "Answer"),
+        (CallSignalType::IceCandidate, "IceCandidate"),
+        (CallSignalType::Hangup, "Hangup"),
+        (CallSignalType::Reject, "Reject"),
+        (CallSignalType::Ringing, "Ringing"),
+        (CallSignalType::Busy, "Busy"),
+    ];
+
+    assert_eq!(variants.len(), 7, "featherChat defines exactly 7 call signal types");
+
+    for (variant, expected_name) in &variants {
+        let name = format!("{variant:?}");
+        assert_eq!(&name, expected_name);
+
+        // Each variant should serialize/deserialize cleanly
+        let json = serde_json::to_string(variant).unwrap();
+        let round_tripped: CallSignalType = serde_json::from_str(&json).unwrap();
+        assert_eq!(format!("{round_tripped:?}"), *expected_name);
+    }
+}
+
+/// WZP-S-9: hashed room name used as QUIC SNI must be valid — lowercase hex only.
+#[test]
+fn hash_room_name_used_as_sni_is_valid() {
+    let long_name = "x".repeat(1000);
+    let test_rooms = [
+        "general",
+        "Voice Room #1",
+        "café-lounge",
+        "a]b[c{d}e",
+        "\u{1f480}\u{1f525}",
+        long_name.as_str(),
+    ];
+
+    for room in &test_rooms {
+        let hashed = wzp_crypto::hash_room_name(room);
+
+        // Must be non-empty
+        assert!(!hashed.is_empty(), "hash of '{room}' must not be empty");
+
+        // Must contain only lowercase hex chars (valid for SNI)
+        for ch in hashed.chars() {
+            assert!(
+                ch.is_ascii_hexdigit() && !ch.is_ascii_uppercase(),
+                "hash of '{room}' contains invalid SNI char: '{ch}' (full: {hashed})"
+            );
+        }
+
+        // SHA-256 truncated to 16 bytes -> 32 hex chars
+        assert_eq!(
+            hashed.len(),
+            32,
+            "hash should be 32 hex chars (16 bytes), got {} for '{room}'",
+            hashed.len()
+        );
+    }
+}
+
+/// WZP-S-7: wzp-proto Cargo.toml must be standalone — no `.workspace = true` inheritance.
+#[test]
+fn wzp_proto_cargo_toml_is_standalone() {
+    // Try both paths (run from workspace root or from crate directory)
+    let candidates = [
+        "crates/wzp-proto/Cargo.toml",
+        "../wzp-proto/Cargo.toml",
+    ];
+
+    let contents = candidates
+        .iter()
+        .find_map(|p| std::fs::read_to_string(p).ok())
+        .expect("could not read crates/wzp-proto/Cargo.toml from any expected path");
+
+    // Must NOT contain ".workspace = true" anywhere — that would break standalone use
+    assert!(
+        !contents.contains(".workspace = true"),
+        "wzp-proto Cargo.toml must not use workspace inheritance (.workspace = true), \
+         found in:\n{contents}"
+    );
+
+    // Sanity: it should still be a valid Cargo.toml with the right package name
+    assert!(
+        contents.contains("name = \"wzp-proto\""),
+        "expected package name 'wzp-proto' in Cargo.toml"
+    );
+}

crates/wzp-fec/src/decoder.rs

@@ -1,6 +1,7 @@
 //! RaptorQ FEC decoder — reassembles source blocks from received source and repair symbols.
 
 use std::collections::HashMap;
+use std::time::Instant;
 
 use raptorq::{EncodingPacket, ObjectTransmissionInformation, PayloadId, SourceBlockDecoder};
 use wzp_proto::error::FecError;
@@ -9,6 +10,9 @@ use wzp_proto::FecDecoder;
 /// Length prefix size (u16 little-endian), must match encoder.
 const LEN_PREFIX: usize = 2;
 
+/// Decoded blocks older than this are eligible for reuse by a new sender.
+const BLOCK_STALE_SECS: u64 = 2;
+
 /// State for one in-flight block being decoded.
 struct BlockState {
     /// Number of source symbols expected.
@@ -21,6 +25,8 @@ struct BlockState {
     decoded: bool,
     /// Cached decoded result.
     result: Option<Vec<Vec<u8>>>,
+    /// When this block was last decoded (for staleness check).
+    decoded_at: Option<Instant>,
 }
 
 /// RaptorQ-based FEC decoder that handles multiple concurrent blocks.
@@ -58,6 +64,7 @@ impl RaptorQFecDecoder {
             symbol_size: self.symbol_size,
             decoded: false,
             result: None,
+            decoded_at: None,
         })
     }
 }
@@ -74,8 +81,20 @@ impl FecDecoder for RaptorQFecDecoder {
         let block = self.get_or_create_block(block_id);
 
         if block.decoded {
-            // Already decoded, ignore additional symbols.
-            return Ok(());
+            // If the block was decoded recently, skip (normal duplicate).
+            // If it's stale (>2s), a new sender is reusing this block_id — reset it.
+            if let Some(at) = block.decoded_at {
+                if at.elapsed().as_secs() >= BLOCK_STALE_SECS {
+                    block.decoded = false;
+                    block.result = None;
+                    block.decoded_at = None;
+                    block.packets.clear();
+                } else {
+                    return Ok(());
+                }
+            } else {
+                return Ok(());
+            }
         }
 
         // Data should already be at symbol_size (length-prefixed and padded by the encoder).
@@ -132,6 +151,7 @@ impl FecDecoder for RaptorQFecDecoder {
 
                 let block = self.blocks.get_mut(&block_id).unwrap();
                 block.decoded = true;
+                block.decoded_at = Some(Instant::now());
                 block.result = Some(frames.clone());
                 Ok(Some(frames))
             }

crates/wzp-native/Cargo.toml

@@ -0,0 +1,29 @@
+[package]
+name = "wzp-native"
+version = "0.1.0"
+edition = "2024"
+description = "WarzonePhone native audio library — standalone Android cdylib that eventually owns all C++ (Oboe bridge) and exposes a pure-C FFI. Built with cargo-ndk, loaded at runtime by the Tauri desktop cdylib via libloading."
+
+# Crate-type is DELIBERATELY only cdylib (no rlib, no staticlib). This crate
+# is built with `cargo ndk -t arm64-v8a build --release -p wzp-native` as a
+# standalone .so, which is the same path the legacy wzp-android crate uses
+# successfully on the same phone / same NDK. Keeping the crate-type single
+# avoids the rust-lang/rust#104707 symbol leak that bit us when Tauri's
+# desktop crate had ["staticlib", "cdylib", "rlib"] and any C++ static
+# archive pulled bionic's internal pthread_create into the final .so.
+[lib]
+name = "wzp_native"
+crate-type = ["cdylib"]
+
+[build-dependencies]
+# cc is SAFE to use here because this crate is a single-cdylib: no
+# staticlib in crate-type → no rust-lang/rust#104707 symbol leak. The
+# legacy wzp-android crate uses the same setup and works.
+cc = "1"
+
+[dependencies]
+# Phase 2: Oboe C++ audio bridge. Still no Rust deps — we do the whole
+# audio pipeline via extern "C" into the bundled C++ and expose our own
+# narrow extern "C" API for wzp-desktop to dlopen via libloading.
+# Phase 3 can add wzp-proto/wzp-codec if we want to share codec logic
+# instead of calling back into wzp-desktop via callbacks.

crates/wzp-native/build.rs

@@ -0,0 +1,119 @@
+//! wzp-native build.rs — Oboe C++ bridge compile on Android.
+//!
+//! Near-verbatim copy of crates/wzp-android/build.rs (which is known to
+//! work). The crucial distinction: this crate is a single-cdylib (no
+//! staticlib, no rlib in crate-type) so rust-lang/rust#104707 doesn't
+//! apply — bionic's internal pthread_create / __init_tcb symbols stay
+//! UND and resolve against libc.so at runtime, as they should.
+//!
+//! On non-Android hosts we compile `cpp/oboe_stub.cpp` (empty stubs) so
+//! `cargo check --target <host>` still works for IDEs and CI.
+
+use std::path::PathBuf;
+
+fn main() {
+    let target = std::env::var("TARGET").unwrap_or_default();
+
+    if target.contains("android") {
+        // getauxval_fix: override compiler-rt's broken static getauxval
+        // stub that SIGSEGVs in shared libraries.
+        cc::Build::new()
+            .file("cpp/getauxval_fix.c")
+            .compile("wzp_native_getauxval_fix");
+
+        let oboe_dir = fetch_oboe();
+        match oboe_dir {
+            Some(oboe_path) => {
+                println!("cargo:warning=wzp-native: building with Oboe from {:?}", oboe_path);
+                let mut build = cc::Build::new();
+                build
+                    .cpp(true)
+                    .std("c++17")
+                    // Shared libc++ — matches legacy wzp-android setup.
+                    .cpp_link_stdlib(Some("c++_shared"))
+                    .include("cpp")
+                    .include(oboe_path.join("include"))
+                    .include(oboe_path.join("src"))
+                    .define("WZP_HAS_OBOE", None)
+                    .file("cpp/oboe_bridge.cpp");
+                add_cpp_files_recursive(&mut build, &oboe_path.join("src"));
+                build.compile("wzp_native_oboe_bridge");
+            }
+            None => {
+                println!("cargo:warning=wzp-native: Oboe not found, building stub");
+                cc::Build::new()
+                    .cpp(true)
+                    .std("c++17")
+                    .cpp_link_stdlib(Some("c++_shared"))
+                    .file("cpp/oboe_stub.cpp")
+                    .include("cpp")
+                    .compile("wzp_native_oboe_bridge");
+            }
+        }
+
+        // Oboe needs log + OpenSLES backends at runtime.
+        println!("cargo:rustc-link-lib=log");
+        println!("cargo:rustc-link-lib=OpenSLES");
+
+        // Re-run if any cpp file changes
+        println!("cargo:rerun-if-changed=cpp/oboe_bridge.cpp");
+        println!("cargo:rerun-if-changed=cpp/oboe_bridge.h");
+        println!("cargo:rerun-if-changed=cpp/oboe_stub.cpp");
+        println!("cargo:rerun-if-changed=cpp/getauxval_fix.c");
+    } else {
+        // Non-Android hosts: compile the empty stub so lib.rs's extern
+        // declarations resolve when someone runs `cargo check` on macOS
+        // or Linux without an NDK.
+        cc::Build::new()
+            .cpp(true)
+            .std("c++17")
+            .file("cpp/oboe_stub.cpp")
+            .include("cpp")
+            .compile("wzp_native_oboe_bridge");
+        println!("cargo:rerun-if-changed=cpp/oboe_stub.cpp");
+    }
+}
+
+/// Recursively add all `.cpp` files from a directory to a cc::Build.
+fn add_cpp_files_recursive(build: &mut cc::Build, dir: &std::path::Path) {
+    if !dir.is_dir() {
+        return;
+    }
+    for entry in std::fs::read_dir(dir).unwrap() {
+        let entry = entry.unwrap();
+        let path = entry.path();
+        if path.is_dir() {
+            add_cpp_files_recursive(build, &path);
+        } else if path.extension().map_or(false, |e| e == "cpp") {
+            build.file(&path);
+        }
+    }
+}
+
+/// Fetch or find Oboe headers + sources (v1.8.1). Same logic as the
+/// legacy wzp-android crate's build.rs.
+fn fetch_oboe() -> Option<PathBuf> {
+    let out_dir = PathBuf::from(std::env::var("OUT_DIR").unwrap());
+    let oboe_dir = out_dir.join("oboe");
+
+    if oboe_dir.join("include").join("oboe").join("Oboe.h").exists() {
+        return Some(oboe_dir);
+    }
+
+    let status = std::process::Command::new("git")
+        .args([
+            "clone",
+            "--depth=1",
+            "--branch=1.8.1",
+            "https://github.com/google/oboe.git",
+            oboe_dir.to_str().unwrap(),
+        ])
+        .status();
+
+    match status {
+        Ok(s) if s.success() && oboe_dir.join("include").join("oboe").join("Oboe.h").exists() => {
+            Some(oboe_dir)
+        }
+        _ => None,
+    }
+}

crates/wzp-native/cpp/getauxval_fix.c

@@ -0,0 +1,21 @@
+// Override the broken static getauxval from compiler-rt/CRT.
+// The static version reads from __libc_auxv which is NULL in shared libs
+// loaded via dlopen, causing SIGSEGV in init_have_lse_atomics at load time.
+// This version calls the real bionic getauxval via dlsym.
+#ifdef __ANDROID__
+#include <dlfcn.h>
+#include <stdint.h>
+
+typedef unsigned long (*getauxval_fn)(unsigned long);
+
+unsigned long getauxval(unsigned long type) {
+    static getauxval_fn real_getauxval = (getauxval_fn)0;
+    if (!real_getauxval) {
+        real_getauxval = (getauxval_fn)dlsym((void*)-1L /* RTLD_DEFAULT */, "getauxval");
+        if (!real_getauxval) {
+            return 0;
+        }
+    }
+    return real_getauxval(type);
+}
+#endif

crates/wzp-native/cpp/oboe_bridge.cpp

@@ -0,0 +1,420 @@
+// Full Oboe implementation for Android
+// This file is compiled only when targeting Android
+
+#include "oboe_bridge.h"
+
+#ifdef __ANDROID__
+#include <oboe/Oboe.h>
+#include <android/log.h>
+#include <cstring>
+#include <atomic>
+
+#define LOG_TAG "wzp-oboe"
+#define LOGI(...) __android_log_print(ANDROID_LOG_INFO, LOG_TAG, __VA_ARGS__)
+#define LOGW(...) __android_log_print(ANDROID_LOG_WARN, LOG_TAG, __VA_ARGS__)
+#define LOGE(...) __android_log_print(ANDROID_LOG_ERROR, LOG_TAG, __VA_ARGS__)
+
+// ---------------------------------------------------------------------------
+// Ring buffer helpers (SPSC, lock-free)
+// ---------------------------------------------------------------------------
+
+static inline int32_t ring_available_read(const wzp_atomic_int* write_idx,
+                                           const wzp_atomic_int* read_idx,
+                                           int32_t capacity) {
+    int32_t w = std::atomic_load_explicit(write_idx, std::memory_order_acquire);
+    int32_t r = std::atomic_load_explicit(read_idx, std::memory_order_relaxed);
+    int32_t avail = w - r;
+    if (avail < 0) avail += capacity;
+    return avail;
+}
+
+static inline int32_t ring_available_write(const wzp_atomic_int* write_idx,
+                                            const wzp_atomic_int* read_idx,
+                                            int32_t capacity) {
+    return capacity - 1 - ring_available_read(write_idx, read_idx, capacity);
+}
+
+static inline void ring_write(int16_t* buf, int32_t capacity,
+                               wzp_atomic_int* write_idx, const wzp_atomic_int* read_idx,
+                               const int16_t* src, int32_t count) {
+    int32_t w = std::atomic_load_explicit(write_idx, std::memory_order_relaxed);
+    for (int32_t i = 0; i < count; i++) {
+        buf[w] = src[i];
+        w++;
+        if (w >= capacity) w = 0;
+    }
+    std::atomic_store_explicit(write_idx, w, std::memory_order_release);
+}
+
+static inline void ring_read(int16_t* buf, int32_t capacity,
+                              const wzp_atomic_int* write_idx, wzp_atomic_int* read_idx,
+                              int16_t* dst, int32_t count) {
+    int32_t r = std::atomic_load_explicit(read_idx, std::memory_order_relaxed);
+    for (int32_t i = 0; i < count; i++) {
+        dst[i] = buf[r];
+        r++;
+        if (r >= capacity) r = 0;
+    }
+    std::atomic_store_explicit(read_idx, r, std::memory_order_release);
+}
+
+// ---------------------------------------------------------------------------
+// Global state
+// ---------------------------------------------------------------------------
+
+static std::shared_ptr<oboe::AudioStream> g_capture_stream;
+static std::shared_ptr<oboe::AudioStream> g_playout_stream;
+// Value copy — the WzpOboeRings the Rust side passes us lives on the caller's
+// stack frame and goes away as soon as wzp_oboe_start returns. The raw
+// int16/atomic pointers INSIDE the struct point into the Rust-owned, leaked-
+// for-the-lifetime-of-the-process AudioBackend singleton, so copying the
+// struct by value is safe and keeps the inner pointers valid indefinitely.
+// g_rings_valid guards the audio-callback-side read; clearing it in stop()
+// signals "no backend" to the callbacks which then return silence + Stop.
+static WzpOboeRings g_rings{};
+static std::atomic<bool> g_rings_valid{false};
+static std::atomic<bool> g_running{false};
+static std::atomic<float> g_capture_latency_ms{0.0f};
+static std::atomic<float> g_playout_latency_ms{0.0f};
+
+// ---------------------------------------------------------------------------
+// Capture callback
+// ---------------------------------------------------------------------------
+
+class CaptureCallback : public oboe::AudioStreamDataCallback {
+public:
+    uint64_t calls = 0;
+    uint64_t total_frames = 0;
+    uint64_t total_written = 0;
+    uint64_t ring_full_drops = 0;
+
+    oboe::DataCallbackResult onAudioReady(
+            oboe::AudioStream* stream,
+            void* audioData,
+            int32_t numFrames) override {
+        if (!g_running.load(std::memory_order_relaxed) ||
+            !g_rings_valid.load(std::memory_order_acquire)) {
+            return oboe::DataCallbackResult::Stop;
+        }
+
+        const int16_t* src = static_cast<const int16_t*>(audioData);
+        int32_t avail = ring_available_write(g_rings.capture_write_idx,
+                                              g_rings.capture_read_idx,
+                                              g_rings.capture_capacity);
+        int32_t to_write = (numFrames < avail) ? numFrames : avail;
+        if (to_write > 0) {
+            ring_write(g_rings.capture_buf, g_rings.capture_capacity,
+                       g_rings.capture_write_idx, g_rings.capture_read_idx,
+                       src, to_write);
+        }
+        total_frames += numFrames;
+        total_written += to_write;
+        if (to_write < numFrames) {
+            ring_full_drops += (numFrames - to_write);
+        }
+
+        // Sample-range probe on the FIRST callback to prove we get real audio
+        if (calls == 0 && numFrames > 0) {
+            int16_t lo = src[0], hi = src[0];
+            int32_t sumsq = 0;
+            for (int32_t i = 0; i < numFrames; i++) {
+                if (src[i] < lo) lo = src[i];
+                if (src[i] > hi) hi = src[i];
+                sumsq += (int32_t)src[i] * (int32_t)src[i];
+            }
+            int32_t rms = (int32_t) (numFrames > 0 ? (int32_t)__builtin_sqrt((double)sumsq / (double)numFrames) : 0);
+            LOGI("capture cb#0: numFrames=%d sample_range=[%d..%d] rms=%d to_write=%d",
+                 numFrames, lo, hi, rms, to_write);
+        }
+        // Heartbeat every 50 callbacks (~1s at 20ms/burst)
+        calls++;
+        if ((calls % 50) == 0) {
+            LOGI("capture heartbeat: calls=%llu numFrames=%d ring_avail_write=%d to_write=%d full_drops=%llu total_written=%llu",
+                 (unsigned long long)calls, numFrames, avail, to_write,
+                 (unsigned long long)ring_full_drops, (unsigned long long)total_written);
+        }
+
+        // Update latency estimate
+        auto result = stream->calculateLatencyMillis();
+        if (result) {
+            g_capture_latency_ms.store(static_cast<float>(result.value()),
+                                        std::memory_order_relaxed);
+        }
+
+        return oboe::DataCallbackResult::Continue;
+    }
+};
+
+// ---------------------------------------------------------------------------
+// Playout callback
+// ---------------------------------------------------------------------------
+
+class PlayoutCallback : public oboe::AudioStreamDataCallback {
+public:
+    uint64_t calls = 0;
+    uint64_t total_frames = 0;
+    uint64_t total_played_real = 0;
+    uint64_t underrun_frames = 0;
+    uint64_t nonempty_calls = 0;
+
+    oboe::DataCallbackResult onAudioReady(
+            oboe::AudioStream* stream,
+            void* audioData,
+            int32_t numFrames) override {
+        if (!g_running.load(std::memory_order_relaxed) ||
+            !g_rings_valid.load(std::memory_order_acquire)) {
+            memset(audioData, 0, numFrames * sizeof(int16_t));
+            return oboe::DataCallbackResult::Stop;
+        }
+
+        int16_t* dst = static_cast<int16_t*>(audioData);
+        int32_t avail = ring_available_read(g_rings.playout_write_idx,
+                                             g_rings.playout_read_idx,
+                                             g_rings.playout_capacity);
+        int32_t to_read = (numFrames < avail) ? numFrames : avail;
+
+        if (to_read > 0) {
+            ring_read(g_rings.playout_buf, g_rings.playout_capacity,
+                      g_rings.playout_write_idx, g_rings.playout_read_idx,
+                      dst, to_read);
+            nonempty_calls++;
+        }
+        // Fill remainder with silence on underrun
+        if (to_read < numFrames) {
+            memset(dst + to_read, 0, (numFrames - to_read) * sizeof(int16_t));
+            underrun_frames += (numFrames - to_read);
+        }
+        total_frames += numFrames;
+        total_played_real += to_read;
+
+        // First callback: log requested config + prove we're being called
+        if (calls == 0) {
+            LOGI("playout cb#0: numFrames=%d ring_avail_read=%d to_read=%d",
+                 numFrames, avail, to_read);
+        }
+        // On the first callback that actually has data, log the sample range
+        // so we can tell if the samples coming out of the ring look like real
+        // audio vs constant-zeroes vs garbage.
+        if (to_read > 0 && nonempty_calls == 1) {
+            int16_t lo = dst[0], hi = dst[0];
+            int32_t sumsq = 0;
+            for (int32_t i = 0; i < to_read; i++) {
+                if (dst[i] < lo) lo = dst[i];
+                if (dst[i] > hi) hi = dst[i];
+                sumsq += (int32_t)dst[i] * (int32_t)dst[i];
+            }
+            int32_t rms = (to_read > 0) ? (int32_t)__builtin_sqrt((double)sumsq / (double)to_read) : 0;
+            LOGI("playout FIRST nonempty read: to_read=%d sample_range=[%d..%d] rms=%d",
+                 to_read, lo, hi, rms);
+        }
+        // Heartbeat every 50 callbacks (~1s at 20ms/burst)
+        calls++;
+        if ((calls % 50) == 0) {
+            int state = (int)stream->getState();
+            auto xrunRes = stream->getXRunCount();
+            int xruns = xrunRes ? xrunRes.value() : -1;
+            LOGI("playout heartbeat: calls=%llu nonempty=%llu numFrames=%d ring_avail_read=%d to_read=%d underrun_frames=%llu total_played_real=%llu state=%d xruns=%d",
+                 (unsigned long long)calls, (unsigned long long)nonempty_calls,
+                 numFrames, avail, to_read,
+                 (unsigned long long)underrun_frames, (unsigned long long)total_played_real,
+                 state, xruns);
+        }
+
+        // Update latency estimate
+        auto result = stream->calculateLatencyMillis();
+        if (result) {
+            g_playout_latency_ms.store(static_cast<float>(result.value()),
+                                        std::memory_order_relaxed);
+        }
+
+        return oboe::DataCallbackResult::Continue;
+    }
+};
+
+static CaptureCallback g_capture_cb;
+static PlayoutCallback g_playout_cb;
+
+// ---------------------------------------------------------------------------
+// Public C API
+// ---------------------------------------------------------------------------
+
+int wzp_oboe_start(const WzpOboeConfig* config, const WzpOboeRings* rings) {
+    if (g_running.load(std::memory_order_relaxed)) {
+        LOGW("wzp_oboe_start: already running");
+        return -1;
+    }
+
+    // Deep-copy the rings struct into static storage BEFORE we publish it to
+    // the audio callbacks — `rings` points at the caller's stack frame and
+    // goes away as soon as this function returns.
+    g_rings = *rings;
+    g_rings_valid.store(true, std::memory_order_release);
+
+    // Build capture stream
+    oboe::AudioStreamBuilder captureBuilder;
+    captureBuilder.setDirection(oboe::Direction::Input)
+        ->setPerformanceMode(oboe::PerformanceMode::LowLatency)
+        ->setSharingMode(oboe::SharingMode::Exclusive)
+        ->setFormat(oboe::AudioFormat::I16)
+        ->setChannelCount(config->channel_count)
+        ->setSampleRate(config->sample_rate)
+        ->setFramesPerDataCallback(config->frames_per_burst)
+        ->setInputPreset(oboe::InputPreset::VoiceCommunication)
+        ->setDataCallback(&g_capture_cb);
+
+    oboe::Result result = captureBuilder.openStream(g_capture_stream);
+    if (result != oboe::Result::OK) {
+        LOGE("Failed to open capture stream: %s", oboe::convertToText(result));
+        return -2;
+    }
+    LOGI("capture stream opened: actualSR=%d actualCh=%d actualFormat=%d actualFramesPerBurst=%d actualFramesPerDataCallback=%d bufferCapacityInFrames=%d sharing=%d perfMode=%d",
+         g_capture_stream->getSampleRate(),
+         g_capture_stream->getChannelCount(),
+         (int)g_capture_stream->getFormat(),
+         g_capture_stream->getFramesPerBurst(),
+         g_capture_stream->getFramesPerDataCallback(),
+         g_capture_stream->getBufferCapacityInFrames(),
+         (int)g_capture_stream->getSharingMode(),
+         (int)g_capture_stream->getPerformanceMode());
+
+    // Build playout stream.
+    //
+    // Regression triangulation between builds:
+    //   96be740 (Usage::Media, default API): playout callback DID drain
+    //   the ring at steady 50Hz (playout heartbeat: calls=1100,
+    //   total_played_real=1055040). Audio not audible because OS routing
+    //   sent it to a silent output.
+    //
+    //   8c36fb5 (Usage::VoiceCommunication + setAudioApi(AAudio) +
+    //   ContentType::Speech): playout callback fired cb#0 once then
+    //   stopped draining the ring entirely. written_samples stuck at
+    //   ring capacity (7679) across all subsequent heartbeats, so Oboe
+    //   accepted zero samples after startup. Still inaudible.
+    //
+    // Hypothesis: forcing setAudioApi(AAudio) + VoiceCommunication on
+    // Pixel 6 / Android 15 opens a stream that succeeds at cb#0 but
+    // then detaches from the real audio driver. Reverting to the
+    // config that at least drove callbacks correctly, plus the
+    // Kotlin-side MODE_IN_COMMUNICATION + setSpeakerphoneOn(true)
+    // handled in MainActivity.kt to route audio to the loud speaker.
+    // Usage::VoiceCommunication is the correct Oboe usage for a VoIP app
+    // — it respects Android's in-call audio routing and lets
+    // AudioManager.setSpeakerphoneOn/setBluetoothScoOn actually switch
+    // between earpiece, loudspeaker, and Bluetooth headset. Combined with
+    // MODE_IN_COMMUNICATION set from MainActivity.kt and
+    // speakerphoneOn=false by default, this produces handset/earpiece as
+    // the default output.
+    //
+    // IMPORTANT: do NOT add setAudioApi(AAudio) here. Build 8c36fb5 proved
+    // forcing AAudio with Usage::VoiceCommunication makes the playout
+    // callback stop draining the ring after cb#0, even though the stream
+    // opens successfully. Letting Oboe pick the API (which will be AAudio
+    // on API ≥ 27 but via a different codepath) kept callbacks firing in
+    // every other build.
+    oboe::AudioStreamBuilder playoutBuilder;
+    playoutBuilder.setDirection(oboe::Direction::Output)
+        ->setPerformanceMode(oboe::PerformanceMode::LowLatency)
+        ->setSharingMode(oboe::SharingMode::Exclusive)
+        ->setFormat(oboe::AudioFormat::I16)
+        ->setChannelCount(config->channel_count)
+        ->setSampleRate(config->sample_rate)
+        ->setFramesPerDataCallback(config->frames_per_burst)
+        ->setUsage(oboe::Usage::VoiceCommunication)
+        ->setDataCallback(&g_playout_cb);
+
+    result = playoutBuilder.openStream(g_playout_stream);
+    if (result != oboe::Result::OK) {
+        LOGE("Failed to open playout stream: %s", oboe::convertToText(result));
+        g_capture_stream->close();
+        g_capture_stream.reset();
+        return -3;
+    }
+    LOGI("playout stream opened: actualSR=%d actualCh=%d actualFormat=%d actualFramesPerBurst=%d actualFramesPerDataCallback=%d bufferCapacityInFrames=%d sharing=%d perfMode=%d",
+         g_playout_stream->getSampleRate(),
+         g_playout_stream->getChannelCount(),
+         (int)g_playout_stream->getFormat(),
+         g_playout_stream->getFramesPerBurst(),
+         g_playout_stream->getFramesPerDataCallback(),
+         g_playout_stream->getBufferCapacityInFrames(),
+         (int)g_playout_stream->getSharingMode(),
+         (int)g_playout_stream->getPerformanceMode());
+
+    g_running.store(true, std::memory_order_release);
+
+    // Start both streams
+    result = g_capture_stream->requestStart();
+    if (result != oboe::Result::OK) {
+        LOGE("Failed to start capture: %s", oboe::convertToText(result));
+        g_running.store(false, std::memory_order_release);
+        g_capture_stream->close();
+        g_playout_stream->close();
+        g_capture_stream.reset();
+        g_playout_stream.reset();
+        return -4;
+    }
+
+    result = g_playout_stream->requestStart();
+    if (result != oboe::Result::OK) {
+        LOGE("Failed to start playout: %s", oboe::convertToText(result));
+        g_running.store(false, std::memory_order_release);
+        g_capture_stream->requestStop();
+        g_capture_stream->close();
+        g_playout_stream->close();
+        g_capture_stream.reset();
+        g_playout_stream.reset();
+        return -5;
+    }
+
+    LOGI("Oboe started: sr=%d burst=%d ch=%d",
+         config->sample_rate, config->frames_per_burst, config->channel_count);
+    return 0;
+}
+
+void wzp_oboe_stop(void) {
+    g_running.store(false, std::memory_order_release);
+    // Tell the audio callbacks to stop touching g_rings BEFORE we tear down
+    // the streams, so any in-flight callback returns Stop instead of reading
+    // stale pointers.
+    g_rings_valid.store(false, std::memory_order_release);
+
+    if (g_capture_stream) {
+        g_capture_stream->requestStop();
+        g_capture_stream->close();
+        g_capture_stream.reset();
+    }
+    if (g_playout_stream) {
+        g_playout_stream->requestStop();
+        g_playout_stream->close();
+        g_playout_stream.reset();
+    }
+
+    LOGI("Oboe stopped");
+}
+
+float wzp_oboe_capture_latency_ms(void) {
+    return g_capture_latency_ms.load(std::memory_order_relaxed);
+}
+
+float wzp_oboe_playout_latency_ms(void) {
+    return g_playout_latency_ms.load(std::memory_order_relaxed);
+}
+
+int wzp_oboe_is_running(void) {
+    return g_running.load(std::memory_order_relaxed) ? 1 : 0;
+}
+
+#else
+// Non-Android fallback — should not be reached; oboe_stub.cpp is used instead.
+// Provide empty implementations just in case.
+
+int wzp_oboe_start(const WzpOboeConfig* config, const WzpOboeRings* rings) {
+    (void)config; (void)rings;
+    return -99;
+}
+
+void wzp_oboe_stop(void) {}
+float wzp_oboe_capture_latency_ms(void) { return 0.0f; }
+float wzp_oboe_playout_latency_ms(void) { return 0.0f; }
+int wzp_oboe_is_running(void) { return 0; }
+
+#endif // __ANDROID__

crates/wzp-native/cpp/oboe_bridge.h

@@ -0,0 +1,43 @@
+#ifndef WZP_OBOE_BRIDGE_H
+#define WZP_OBOE_BRIDGE_H
+
+#include <stdint.h>
+
+#ifdef __cplusplus
+#include <atomic>
+typedef std::atomic<int32_t> wzp_atomic_int;
+extern "C" {
+#else
+#include <stdatomic.h>
+typedef atomic_int wzp_atomic_int;
+#endif
+
+typedef struct {
+    int32_t sample_rate;
+    int32_t frames_per_burst;
+    int32_t channel_count;
+} WzpOboeConfig;
+
+typedef struct {
+    int16_t* capture_buf;
+    int32_t  capture_capacity;
+    wzp_atomic_int* capture_write_idx;
+    wzp_atomic_int* capture_read_idx;
+
+    int16_t* playout_buf;
+    int32_t  playout_capacity;
+    wzp_atomic_int* playout_write_idx;
+    wzp_atomic_int* playout_read_idx;
+} WzpOboeRings;
+
+int wzp_oboe_start(const WzpOboeConfig* config, const WzpOboeRings* rings);
+void wzp_oboe_stop(void);
+float wzp_oboe_capture_latency_ms(void);
+float wzp_oboe_playout_latency_ms(void);
+int wzp_oboe_is_running(void);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif // WZP_OBOE_BRIDGE_H

crates/wzp-native/cpp/oboe_stub.cpp

@@ -0,0 +1,27 @@
+// Stub implementation for non-Android host builds (testing, cargo check, etc.)
+
+#include "oboe_bridge.h"
+#include <stdio.h>
+
+int wzp_oboe_start(const WzpOboeConfig* config, const WzpOboeRings* rings) {
+    (void)config;
+    (void)rings;
+    fprintf(stderr, "wzp_oboe_start: stub (not on Android)\n");
+    return 0;
+}
+
+void wzp_oboe_stop(void) {
+    fprintf(stderr, "wzp_oboe_stop: stub (not on Android)\n");
+}
+
+float wzp_oboe_capture_latency_ms(void) {
+    return 0.0f;
+}
+
+float wzp_oboe_playout_latency_ms(void) {
+    return 0.0f;
+}
+
+int wzp_oboe_is_running(void) {
+    return 0;
+}

crates/wzp-native/src/lib.rs

@@ -0,0 +1,331 @@
+//! wzp-native — standalone Android cdylib for all the C++ audio code.
+//!
+//! Built with `cargo ndk`, NOT `cargo tauri android build`. Loaded at
+//! runtime by the Tauri desktop cdylib (`wzp-desktop`) via libloading.
+//! See `docs/incident-tauri-android-init-tcb.md` for why the split exists.
+//!
+//! Phase 2: real Oboe audio backend.
+//!
+//! Architecture: Oboe runs capture + playout streams on its own high-
+//! priority AAudio callback threads inside the C++ bridge. Two SPSC ring
+//! buffers (capture and playout) are shared between the C++ callbacks
+//! and the Rust side via atomic indices — no locks on the hot path.
+//! `wzp-desktop` drains the capture ring into its Opus encoder and fills
+//! the playout ring with decoded PCM.
+
+use std::sync::atomic::{AtomicI32, Ordering};
+
+// ─── Phase 1 smoke-test exports (kept for sanity checks) ─────────────────
+
+/// Returns 42. Used by wzp-desktop's setup() to verify dlopen + dlsym
+/// work before any audio code runs.
+#[unsafe(no_mangle)]
+pub extern "C" fn wzp_native_version() -> i32 {
+    42
+}
+
+/// Writes a NUL-terminated string into `out` (capped at `cap`) and
+/// returns bytes written excluding the NUL.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn wzp_native_hello(out: *mut u8, cap: usize) -> usize {
+    const MSG: &[u8] = b"hello from wzp-native\0";
+    if out.is_null() || cap == 0 {
+        return 0;
+    }
+    let n = MSG.len().min(cap);
+    unsafe {
+        core::ptr::copy_nonoverlapping(MSG.as_ptr(), out, n);
+        *out.add(n - 1) = 0;
+    }
+    n - 1
+}
+
+// ─── C++ Oboe bridge FFI ─────────────────────────────────────────────────
+
+#[repr(C)]
+struct WzpOboeConfig {
+    sample_rate: i32,
+    frames_per_burst: i32,
+    channel_count: i32,
+}
+
+#[repr(C)]
+struct WzpOboeRings {
+    capture_buf: *mut i16,
+    capture_capacity: i32,
+    capture_write_idx: *mut AtomicI32,
+    capture_read_idx: *mut AtomicI32,
+    playout_buf: *mut i16,
+    playout_capacity: i32,
+    playout_write_idx: *mut AtomicI32,
+    playout_read_idx: *mut AtomicI32,
+}
+
+// SAFETY: atomics synchronise producer/consumer; raw pointers are owned
+// by the AudioBackend singleton below whose lifetime covers all calls.
+unsafe impl Send for WzpOboeRings {}
+unsafe impl Sync for WzpOboeRings {}
+
+unsafe extern "C" {
+    fn wzp_oboe_start(config: *const WzpOboeConfig, rings: *const WzpOboeRings) -> i32;
+    fn wzp_oboe_stop();
+    fn wzp_oboe_capture_latency_ms() -> f32;
+    fn wzp_oboe_playout_latency_ms() -> f32;
+    fn wzp_oboe_is_running() -> i32;
+}
+
+// ─── SPSC ring buffer (shared with C++ via AtomicI32) ────────────────────
+
+/// 20 ms @ 48 kHz mono = 960 samples.
+const FRAME_SAMPLES: usize = 960;
+/// ~160 ms headroom at 48 kHz.
+const RING_CAPACITY: usize = 7680;
+
+struct RingBuffer {
+    buf: Vec<i16>,
+    capacity: usize,
+    write_idx: AtomicI32,
+    read_idx: AtomicI32,
+}
+
+// SAFETY: SPSC with atomic read/write cursors; producer and consumer
+// are always on different threads.
+unsafe impl Send for RingBuffer {}
+unsafe impl Sync for RingBuffer {}
+
+impl RingBuffer {
+    fn new(capacity: usize) -> Self {
+        Self {
+            buf: vec![0i16; capacity],
+            capacity,
+            write_idx: AtomicI32::new(0),
+            read_idx: AtomicI32::new(0),
+        }
+    }
+
+    fn available_read(&self) -> usize {
+        let w = self.write_idx.load(Ordering::Acquire);
+        let r = self.read_idx.load(Ordering::Relaxed);
+        let avail = w - r;
+        if avail < 0 { (avail + self.capacity as i32) as usize } else { avail as usize }
+    }
+
+    fn available_write(&self) -> usize {
+        self.capacity - 1 - self.available_read()
+    }
+
+    fn write(&self, data: &[i16]) -> usize {
+        let count = data.len().min(self.available_write());
+        if count == 0 {
+            return 0;
+        }
+        let mut w = self.write_idx.load(Ordering::Relaxed) as usize;
+        let cap = self.capacity;
+        let buf_ptr = self.buf.as_ptr() as *mut i16;
+        for sample in &data[..count] {
+            unsafe { *buf_ptr.add(w) = *sample; }
+            w += 1;
+            if w >= cap { w = 0; }
+        }
+        self.write_idx.store(w as i32, Ordering::Release);
+        count
+    }
+
+    fn read(&self, out: &mut [i16]) -> usize {
+        let count = out.len().min(self.available_read());
+        if count == 0 {
+            return 0;
+        }
+        let mut r = self.read_idx.load(Ordering::Relaxed) as usize;
+        let cap = self.capacity;
+        let buf_ptr = self.buf.as_ptr();
+        for slot in &mut out[..count] {
+            unsafe { *slot = *buf_ptr.add(r); }
+            r += 1;
+            if r >= cap { r = 0; }
+        }
+        self.read_idx.store(r as i32, Ordering::Release);
+        count
+    }
+
+    fn buf_ptr(&self) -> *mut i16 {
+        self.buf.as_ptr() as *mut i16
+    }
+    fn write_idx_ptr(&self) -> *mut AtomicI32 {
+        &self.write_idx as *const AtomicI32 as *mut AtomicI32
+    }
+    fn read_idx_ptr(&self) -> *mut AtomicI32 {
+        &self.read_idx as *const AtomicI32 as *mut AtomicI32
+    }
+}
+
+// ─── AudioBackend singleton ──────────────────────────────────────────────
+//
+// There is one global AudioBackend instance because Oboe's C++ side
+// holds its own singleton of the streams. The `Box::leak`'d statics own
+// the ring buffers for the lifetime of the process — dropping them while
+// Oboe is still running would cause use-after-free in the audio callback.
+
+use std::sync::OnceLock;
+
+struct AudioBackend {
+    capture: RingBuffer,
+    playout: RingBuffer,
+    started: std::sync::Mutex<bool>,
+    /// Per-write logging throttle counter for wzp_native_audio_write_playout.
+    playout_write_log_count: std::sync::atomic::AtomicU64,
+}
+
+static BACKEND: OnceLock<&'static AudioBackend> = OnceLock::new();
+
+fn backend() -> &'static AudioBackend {
+    BACKEND.get_or_init(|| {
+        Box::leak(Box::new(AudioBackend {
+            capture: RingBuffer::new(RING_CAPACITY),
+            playout: RingBuffer::new(RING_CAPACITY),
+            started: std::sync::Mutex::new(false),
+            playout_write_log_count: std::sync::atomic::AtomicU64::new(0),
+        }))
+    })
+}
+
+// ─── C FFI for wzp-desktop ───────────────────────────────────────────────
+
+/// Start the Oboe audio streams. Returns 0 on success, non-zero on error.
+/// Idempotent — calling while already running is a no-op that returns 0.
+#[unsafe(no_mangle)]
+pub extern "C" fn wzp_native_audio_start() -> i32 {
+    let b = backend();
+    let mut started = match b.started.lock() {
+        Ok(g) => g,
+        Err(_) => return -1,
+    };
+    if *started {
+        return 0;
+    }
+
+    let config = WzpOboeConfig {
+        sample_rate: 48_000,
+        frames_per_burst: FRAME_SAMPLES as i32,
+        channel_count: 1,
+    };
+    let rings = WzpOboeRings {
+        capture_buf: b.capture.buf_ptr(),
+        capture_capacity: b.capture.capacity as i32,
+        capture_write_idx: b.capture.write_idx_ptr(),
+        capture_read_idx: b.capture.read_idx_ptr(),
+        playout_buf: b.playout.buf_ptr(),
+        playout_capacity: b.playout.capacity as i32,
+        playout_write_idx: b.playout.write_idx_ptr(),
+        playout_read_idx: b.playout.read_idx_ptr(),
+    };
+    let ret = unsafe { wzp_oboe_start(&config, &rings) };
+    if ret != 0 {
+        return ret;
+    }
+    *started = true;
+    0
+}
+
+/// Stop Oboe. Idempotent. Safe to call from any thread.
+#[unsafe(no_mangle)]
+pub extern "C" fn wzp_native_audio_stop() {
+    let b = backend();
+    if let Ok(mut started) = b.started.lock() {
+        if *started {
+            unsafe { wzp_oboe_stop() };
+            *started = false;
+        }
+    }
+}
+
+/// Read captured PCM samples from the capture ring. Returns the number
+/// of `i16` samples actually copied into `out` (may be less than
+/// `out_len` if the ring is empty).
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn wzp_native_audio_read_capture(out: *mut i16, out_len: usize) -> usize {
+    if out.is_null() || out_len == 0 {
+        return 0;
+    }
+    let slice = unsafe { std::slice::from_raw_parts_mut(out, out_len) };
+    backend().capture.read(slice)
+}
+
+/// Write PCM samples into the playout ring. Returns the number of
+/// samples actually enqueued (may be less than `in_len` if the ring
+/// is nearly full — in practice the caller should pace to 20 ms
+/// frames and spin briefly if the ring is full).
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn wzp_native_audio_write_playout(input: *const i16, in_len: usize) -> usize {
+    if input.is_null() || in_len == 0 {
+        return 0;
+    }
+    let slice = unsafe { std::slice::from_raw_parts(input, in_len) };
+    let b = backend();
+    let before_w = b.playout.write_idx.load(std::sync::atomic::Ordering::Relaxed);
+    let before_r = b.playout.read_idx.load(std::sync::atomic::Ordering::Relaxed);
+    let written = b.playout.write(slice);
+    // First few writes: log ring state + sample range so we can compare what
+    // engine.rs hands us to what the C++ playout callback reads.
+    let first_writes = b.playout_write_log_count.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
+    if first_writes < 3 || first_writes % 50 == 0 {
+        let (mut lo, mut hi, mut sumsq) = (i16::MAX, i16::MIN, 0i64);
+        for &s in slice.iter() {
+            if s < lo { lo = s; }
+            if s > hi { hi = s; }
+            sumsq += (s as i64) * (s as i64);
+        }
+        let rms = (sumsq as f64 / slice.len() as f64).sqrt() as i32;
+        let avail_w_after = b.playout.available_write();
+        let avail_r_after = b.playout.available_read();
+        let msg = format!(
+            "playout WRITE #{first_writes}: in_len={} written={} range=[{lo}..{hi}] rms={rms} before_w={before_w} before_r={before_r} avail_read_after={avail_r_after} avail_write_after={avail_w_after}",
+            slice.len(), written
+        );
+        unsafe {
+            android_log(msg.as_str());
+        }
+    }
+    written
+}
+
+// Minimal android logcat shim so we can print from the cdylib without pulling
+// in android_logger crate (which would add another dep that has to build with
+// cargo-ndk). Uses libc's __android_log_print via extern linkage.
+#[cfg(target_os = "android")]
+unsafe extern "C" {
+    fn __android_log_write(prio: i32, tag: *const u8, text: *const u8) -> i32;
+}
+
+#[cfg(target_os = "android")]
+unsafe fn android_log(msg: &str) {
+    // ANDROID_LOG_INFO = 4. Tag and text must be NUL-terminated.
+    let tag = b"wzp-native\0";
+    let mut buf = Vec::with_capacity(msg.len() + 1);
+    buf.extend_from_slice(msg.as_bytes());
+    buf.push(0);
+    unsafe { __android_log_write(4, tag.as_ptr(), buf.as_ptr()); }
+}
+
+#[cfg(not(target_os = "android"))]
+#[allow(dead_code)]
+unsafe fn android_log(_msg: &str) {}
+
+/// Current capture latency reported by Oboe, in milliseconds. Returns
+/// NaN / 0.0 if the stream isn't running.
+#[unsafe(no_mangle)]
+pub extern "C" fn wzp_native_audio_capture_latency_ms() -> f32 {
+    unsafe { wzp_oboe_capture_latency_ms() }
+}
+
+/// Current playout latency reported by Oboe, in milliseconds.
+#[unsafe(no_mangle)]
+pub extern "C" fn wzp_native_audio_playout_latency_ms() -> f32 {
+    unsafe { wzp_oboe_playout_latency_ms() }
+}
+
+/// Non-zero if both Oboe streams are currently running.
+#[unsafe(no_mangle)]
+pub extern "C" fn wzp_native_audio_is_running() -> i32 {
+    unsafe { wzp_oboe_is_running() }
+}

crates/wzp-proto/Cargo.toml

@@ -1,17 +1,22 @@
 [package]
 name = "wzp-proto"
-version.workspace = true
-edition.workspace = true
-license.workspace = true
-rust-version.workspace = true
+version = "0.1.0"
+edition = "2024"
+license = "MIT OR Apache-2.0"
+rust-version = "1.85"
 description = "WarzonePhone protocol types, traits, and core logic"
 
+# This crate is designed to be importable standalone — no workspace inheritance.
+# featherChat and other projects can depend on it directly via git:
+#   wzp-proto = { git = "ssh://git@git.manko.yoga:222/manawenuz/wz-phone.git", path = "crates/wzp-proto" }
+
 [dependencies]
-bytes = { workspace = true }
-thiserror = { workspace = true }
-async-trait = { workspace = true }
-serde = { workspace = true }
-tracing = { workspace = true }
+bytes = "1"
+thiserror = "2"
+async-trait = "0.1"
+serde = { version = "1", features = ["derive"] }
+tracing = "0.1"
 
 [dev-dependencies]
-tokio = { workspace = true }
+tokio = { version = "1", features = ["full"] }
+serde_json = "1"

crates/wzp-proto/src/bandwidth.rs

@@ -0,0 +1,454 @@
+//! GCC-style bandwidth estimation and congestion control.
+//!
+//! Tracks available bandwidth using delay-based and loss-based signals,
+//! then adjusts the sending bitrate to avoid congestion. The estimator
+//! uses multiplicative decrease (15%) on congestion and additive increase
+//! (5%) during underuse, following the general shape of Google Congestion
+//! Control (GCC).
+
+use std::collections::VecDeque;
+use std::time::Instant;
+
+use crate::packet::QualityReport;
+use crate::QualityProfile;
+
+/// Network congestion state derived from delay and loss signals.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum CongestionState {
+    /// Network is fine, can increase bandwidth.
+    Underuse,
+    /// Normal operation.
+    Normal,
+    /// Congestion detected, should decrease bandwidth.
+    Overuse,
+}
+
+/// Detects congestion from increasing RTT using an exponential moving average.
+///
+/// Maintains a baseline RTT (minimum observed) and compares the smoothed RTT
+/// against it. If `rtt_ema > baseline * threshold_ratio`, congestion is detected.
+/// The baseline slowly drifts upward to handle route changes.
+struct DelayBasedDetector {
+    /// Baseline RTT (minimum observed).
+    baseline_rtt_ms: f64,
+    /// EMA of recent RTT.
+    rtt_ema: f64,
+    /// EMA smoothing factor.
+    alpha: f64,
+    /// Threshold: if rtt_ema > baseline * threshold_ratio, congestion detected.
+    threshold_ratio: f64,
+    /// Current state.
+    state: CongestionState,
+    /// Whether we have received any RTT sample yet.
+    initialized: bool,
+    /// Drift factor: baseline slowly increases each update to track route changes.
+    baseline_drift: f64,
+}
+
+impl DelayBasedDetector {
+    fn new() -> Self {
+        Self {
+            baseline_rtt_ms: f64::MAX,
+            rtt_ema: 0.0,
+            alpha: 0.3,
+            threshold_ratio: 1.5,
+            state: CongestionState::Normal,
+            initialized: false,
+            baseline_drift: 0.001,
+        }
+    }
+
+    /// Update the detector with a new RTT sample.
+    fn update(&mut self, rtt_ms: f64) {
+        if !self.initialized {
+            self.baseline_rtt_ms = rtt_ms;
+            self.rtt_ema = rtt_ms;
+            self.initialized = true;
+            self.state = CongestionState::Normal;
+            return;
+        }
+
+        // Track minimum RTT as baseline.
+        if rtt_ms < self.baseline_rtt_ms {
+            self.baseline_rtt_ms = rtt_ms;
+        } else {
+            // Slowly drift baseline upward to handle route changes.
+            self.baseline_rtt_ms += self.baseline_drift * (rtt_ms - self.baseline_rtt_ms);
+        }
+
+        // Update EMA.
+        self.rtt_ema = self.alpha * rtt_ms + (1.0 - self.alpha) * self.rtt_ema;
+
+        // Determine state.
+        let overuse_threshold = self.baseline_rtt_ms * self.threshold_ratio;
+        let underuse_threshold = self.baseline_rtt_ms * 1.1;
+
+        if self.rtt_ema > overuse_threshold {
+            self.state = CongestionState::Overuse;
+        } else if self.rtt_ema < underuse_threshold {
+            self.state = CongestionState::Underuse;
+        } else {
+            self.state = CongestionState::Normal;
+        }
+    }
+
+    fn state(&self) -> CongestionState {
+        self.state
+    }
+}
+
+/// Detects congestion from packet loss using a sliding window average.
+struct LossBasedDetector {
+    /// Recent loss percentages (sliding window).
+    loss_window: VecDeque<f64>,
+    /// Maximum window size.
+    window_size: usize,
+    /// Loss threshold for congestion (default 5%).
+    threshold_pct: f64,
+}
+
+impl LossBasedDetector {
+    fn new() -> Self {
+        Self {
+            loss_window: VecDeque::with_capacity(10),
+            window_size: 10,
+            threshold_pct: 5.0,
+        }
+    }
+
+    /// Add a loss percentage sample to the window.
+    fn update(&mut self, loss_pct: f64) {
+        if self.loss_window.len() >= self.window_size {
+            self.loss_window.pop_front();
+        }
+        self.loss_window.push_back(loss_pct);
+    }
+
+    /// Returns true if the average loss in the window exceeds the threshold.
+    fn is_congested(&self) -> bool {
+        if self.loss_window.is_empty() {
+            return false;
+        }
+        let avg = self.loss_window.iter().sum::<f64>() / self.loss_window.len() as f64;
+        avg > self.threshold_pct
+    }
+}
+
+// ─── BandwidthEstimator ─────────────────────────────────────────────────────
+
+/// GCC-style bandwidth estimator that tracks available bandwidth using
+/// delay-based and loss-based congestion signals.
+///
+/// # Algorithm
+///
+/// - **Overuse** (delay or loss): multiplicative decrease by 15%.
+/// - **Underuse** (delay) with no loss congestion: additive increase by 5%.
+/// - **Normal**: hold steady.
+/// - Result is always clamped to `[min_bw_kbps, max_bw_kbps]`.
+pub struct BandwidthEstimator {
+    /// Current estimated bandwidth in kbps.
+    estimated_bw_kbps: f64,
+    /// Minimum bandwidth floor (don't go below this).
+    min_bw_kbps: f64,
+    /// Maximum bandwidth ceiling.
+    max_bw_kbps: f64,
+    /// Delay-based detector state.
+    delay_detector: DelayBasedDetector,
+    /// Loss-based detector state.
+    loss_detector: LossBasedDetector,
+    /// Last update timestamp.
+    last_update: Option<Instant>,
+}
+
+/// Multiplicative decrease factor applied on congestion (15% reduction).
+const DECREASE_FACTOR: f64 = 0.85;
+/// Additive increase factor applied during underuse (5% of current estimate).
+const INCREASE_FACTOR: f64 = 0.05;
+
+impl BandwidthEstimator {
+    /// Create a new bandwidth estimator.
+    ///
+    /// - `initial_bw_kbps`: starting bandwidth estimate.
+    /// - `min`: minimum bandwidth floor in kbps.
+    /// - `max`: maximum bandwidth ceiling in kbps.
+    pub fn new(initial_bw_kbps: f64, min: f64, max: f64) -> Self {
+        Self {
+            estimated_bw_kbps: initial_bw_kbps,
+            min_bw_kbps: min,
+            max_bw_kbps: max,
+            delay_detector: DelayBasedDetector::new(),
+            loss_detector: LossBasedDetector::new(),
+            last_update: None,
+        }
+    }
+
+    /// Update the estimator with new network observations.
+    ///
+    /// Returns the new estimated bandwidth in kbps.
+    ///
+    /// - If delay overuse OR loss congested: decrease by 15% (multiplicative decrease).
+    /// - If delay underuse AND not loss congested: increase by 5% (additive increase).
+    /// - If normal: hold steady.
+    /// - Result is clamped to `[min, max]`.
+    pub fn update(&mut self, rtt_ms: f64, loss_pct: f64, _jitter_ms: f64) -> f64 {
+        self.delay_detector.update(rtt_ms);
+        self.loss_detector.update(loss_pct);
+        self.last_update = Some(Instant::now());
+
+        let delay_state = self.delay_detector.state();
+        let loss_congested = self.loss_detector.is_congested();
+
+        if delay_state == CongestionState::Overuse || loss_congested {
+            // Multiplicative decrease.
+            self.estimated_bw_kbps *= DECREASE_FACTOR;
+        } else if delay_state == CongestionState::Underuse && !loss_congested {
+            // Additive increase.
+            self.estimated_bw_kbps += self.estimated_bw_kbps * INCREASE_FACTOR;
+        }
+        // Normal: hold steady — no change.
+
+        // Clamp to [min, max].
+        self.estimated_bw_kbps = self
+            .estimated_bw_kbps
+            .clamp(self.min_bw_kbps, self.max_bw_kbps);
+
+        self.estimated_bw_kbps
+    }
+
+    /// Current estimated bandwidth in kbps.
+    pub fn estimated_kbps(&self) -> f64 {
+        self.estimated_bw_kbps
+    }
+
+    /// Current congestion state (derived from delay detector).
+    pub fn congestion_state(&self) -> CongestionState {
+        self.delay_detector.state()
+    }
+
+    /// Convenience method: update from a `QualityReport`.
+    ///
+    /// Extracts RTT, loss, and jitter from the report and feeds them into
+    /// the estimator.
+    pub fn from_quality_report(&mut self, report: &QualityReport) -> f64 {
+        let rtt_ms = report.rtt_ms() as f64;
+        let loss_pct = report.loss_percent() as f64;
+        let jitter_ms = report.jitter_ms as f64;
+        self.update(rtt_ms, loss_pct, jitter_ms)
+    }
+
+    /// Recommend a `QualityProfile` based on the current bandwidth estimate.
+    ///
+    /// - bw >= 25 kbps -> GOOD (Opus 24k + 20% FEC = ~28.8 kbps total)
+    /// - bw >= 8 kbps  -> DEGRADED (Opus 6k + 50% FEC = ~9.0 kbps)
+    /// - bw < 8 kbps   -> CATASTROPHIC (Codec2 1.2k + 100% FEC = ~2.4 kbps)
+    pub fn recommended_profile(&self) -> QualityProfile {
+        if self.estimated_bw_kbps >= 25.0 {
+            QualityProfile::GOOD
+        } else if self.estimated_bw_kbps >= 8.0 {
+            QualityProfile::DEGRADED
+        } else {
+            QualityProfile::CATASTROPHIC
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn initial_bandwidth() {
+        let bwe = BandwidthEstimator::new(50.0, 2.0, 100.0);
+        assert!((bwe.estimated_kbps() - 50.0).abs() < f64::EPSILON);
+    }
+
+    #[test]
+    fn stable_network_holds_bandwidth() {
+        let mut bwe = BandwidthEstimator::new(50.0, 2.0, 100.0);
+        // Feed stable, low RTT and 0% loss — after initial sample sets baseline,
+        // subsequent identical RTT should be underuse (rtt_ema < baseline * 1.1),
+        // causing slow increases. The bandwidth should stay near initial or grow slightly.
+        let initial = bwe.estimated_kbps();
+        for _ in 0..20 {
+            bwe.update(30.0, 0.0, 5.0);
+        }
+        // Should not have decreased significantly.
+        assert!(
+            bwe.estimated_kbps() >= initial,
+            "bandwidth should not decrease on stable network: got {} vs initial {}",
+            bwe.estimated_kbps(),
+            initial
+        );
+    }
+
+    #[test]
+    fn high_rtt_decreases_bandwidth() {
+        let mut bwe = BandwidthEstimator::new(50.0, 2.0, 100.0);
+        // Establish a low baseline.
+        for _ in 0..5 {
+            bwe.update(20.0, 0.0, 2.0);
+        }
+        let before = bwe.estimated_kbps();
+
+        // Now feed high RTT to trigger overuse.
+        for _ in 0..10 {
+            bwe.update(200.0, 0.0, 10.0);
+        }
+        assert!(
+            bwe.estimated_kbps() < before,
+            "bandwidth should decrease on high RTT: got {} vs before {}",
+            bwe.estimated_kbps(),
+            before
+        );
+    }
+
+    #[test]
+    fn high_loss_decreases_bandwidth() {
+        let mut bwe = BandwidthEstimator::new(50.0, 2.0, 100.0);
+        let before = bwe.estimated_kbps();
+
+        // Feed 10% loss repeatedly (above the 5% threshold).
+        for _ in 0..15 {
+            bwe.update(20.0, 10.0, 2.0);
+        }
+        assert!(
+            bwe.estimated_kbps() < before,
+            "bandwidth should decrease on high loss: got {} vs before {}",
+            bwe.estimated_kbps(),
+            before
+        );
+    }
+
+    #[test]
+    fn recovery_increases_bandwidth() {
+        let mut bwe = BandwidthEstimator::new(50.0, 2.0, 100.0);
+
+        // Drive bandwidth down with high RTT.
+        for _ in 0..5 {
+            bwe.update(20.0, 0.0, 2.0);
+        }
+        for _ in 0..20 {
+            bwe.update(200.0, 0.0, 10.0);
+        }
+        let low_bw = bwe.estimated_kbps();
+        assert!(low_bw < 50.0, "should have decreased");
+
+        // Now feed good conditions — low RTT should be underuse, causing increase.
+        // Reset the baseline by feeding very low RTT.
+        for _ in 0..30 {
+            bwe.update(10.0, 0.0, 1.0);
+        }
+        assert!(
+            bwe.estimated_kbps() > low_bw,
+            "bandwidth should recover: got {} vs low {}",
+            bwe.estimated_kbps(),
+            low_bw
+        );
+    }
+
+    #[test]
+    fn bandwidth_clamped_to_min() {
+        let mut bwe = BandwidthEstimator::new(10.0, 5.0, 100.0);
+        // Keep feeding congestion to drive bandwidth down.
+        for _ in 0..5 {
+            bwe.update(20.0, 0.0, 2.0);
+        }
+        for _ in 0..100 {
+            bwe.update(500.0, 50.0, 100.0);
+        }
+        assert!(
+            (bwe.estimated_kbps() - 5.0).abs() < f64::EPSILON,
+            "bandwidth should be clamped to min: got {}",
+            bwe.estimated_kbps()
+        );
+    }
+
+    #[test]
+    fn bandwidth_clamped_to_max() {
+        let mut bwe = BandwidthEstimator::new(90.0, 2.0, 100.0);
+        // Keep feeding great conditions to drive bandwidth up.
+        for _ in 0..200 {
+            bwe.update(5.0, 0.0, 1.0);
+        }
+        assert!(
+            bwe.estimated_kbps() <= 100.0,
+            "bandwidth should be clamped to max: got {}",
+            bwe.estimated_kbps()
+        );
+    }
+
+    #[test]
+    fn recommended_profile_thresholds() {
+        // At boundary: >= 25 kbps => GOOD
+        let bwe_good = BandwidthEstimator::new(25.0, 2.0, 100.0);
+        assert_eq!(bwe_good.recommended_profile(), QualityProfile::GOOD);
+
+        // Just below 25 => DEGRADED
+        let bwe_degraded = BandwidthEstimator::new(24.9, 2.0, 100.0);
+        assert_eq!(bwe_degraded.recommended_profile(), QualityProfile::DEGRADED);
+
+        // At boundary: >= 8 kbps => DEGRADED
+        let bwe_degraded2 = BandwidthEstimator::new(8.0, 2.0, 100.0);
+        assert_eq!(
+            bwe_degraded2.recommended_profile(),
+            QualityProfile::DEGRADED
+        );
+
+        // Below 8 => CATASTROPHIC
+        let bwe_cat = BandwidthEstimator::new(7.9, 2.0, 100.0);
+        assert_eq!(
+            bwe_cat.recommended_profile(),
+            QualityProfile::CATASTROPHIC
+        );
+
+        // High bandwidth
+        let bwe_high = BandwidthEstimator::new(80.0, 2.0, 100.0);
+        assert_eq!(bwe_high.recommended_profile(), QualityProfile::GOOD);
+    }
+
+    #[test]
+    fn from_quality_report_integration() {
+        let mut bwe = BandwidthEstimator::new(50.0, 2.0, 100.0);
+
+        // Build a QualityReport with moderate loss and RTT.
+        let report = QualityReport {
+            loss_pct: (10.0_f32 / 100.0 * 255.0) as u8, // ~10% loss
+            rtt_4ms: 25,                                   // 100ms RTT
+            jitter_ms: 10,
+            bitrate_cap_kbps: 200,
+        };
+
+        let new_bw = bwe.from_quality_report(&report);
+        // Should return a valid bandwidth value.
+        assert!(new_bw > 0.0);
+        assert!(new_bw <= 100.0);
+        // The estimator should have been updated.
+        assert!((bwe.estimated_kbps() - new_bw).abs() < f64::EPSILON);
+    }
+
+    // ── Additional detector unit tests ──────────────────────────────────
+
+    #[test]
+    fn delay_detector_starts_normal() {
+        let det = DelayBasedDetector::new();
+        assert_eq!(det.state(), CongestionState::Normal);
+    }
+
+    #[test]
+    fn loss_detector_below_threshold() {
+        let mut det = LossBasedDetector::new();
+        for _ in 0..10 {
+            det.update(2.0); // 2% loss, well below 5% threshold
+        }
+        assert!(!det.is_congested());
+    }
+
+    #[test]
+    fn loss_detector_above_threshold() {
+        let mut det = LossBasedDetector::new();
+        for _ in 0..10 {
+            det.update(8.0); // 8% loss, above 5% threshold
+        }
+        assert!(det.is_congested());
+    }
+}

crates/wzp-proto/src/codec_id.rs

@@ -16,6 +16,14 @@ pub enum CodecId {
     Codec2_3200 = 3,
     /// Codec2 at 1200bps (catastrophic conditions)
     Codec2_1200 = 4,
+    /// Comfort noise descriptor (silence suppression)
+    ComfortNoise = 5,
+    /// Opus at 32kbps (studio low)
+    Opus32k = 6,
+    /// Opus at 48kbps (studio)
+    Opus48k = 7,
+    /// Opus at 64kbps (studio high)
+    Opus64k = 8,
 }
 
 impl CodecId {
@@ -25,27 +33,33 @@ impl CodecId {
             Self::Opus24k => 24_000,
             Self::Opus16k => 16_000,
             Self::Opus6k => 6_000,
+            Self::Opus32k => 32_000,
+            Self::Opus48k => 48_000,
+            Self::Opus64k => 64_000,
             Self::Codec2_3200 => 3_200,
             Self::Codec2_1200 => 1_200,
+            Self::ComfortNoise => 0,
         }
     }
 
     /// Preferred frame duration in milliseconds.
     pub const fn frame_duration_ms(self) -> u8 {
         match self {
-            Self::Opus24k => 20,
-            Self::Opus16k => 20,
+            Self::Opus24k | Self::Opus16k | Self::Opus32k | Self::Opus48k | Self::Opus64k => 20,
             Self::Opus6k => 40,
             Self::Codec2_3200 => 20,
             Self::Codec2_1200 => 40,
+            Self::ComfortNoise => 20,
         }
     }
 
     /// Sample rate expected by this codec.
     pub const fn sample_rate_hz(self) -> u32 {
         match self {
-            Self::Opus24k | Self::Opus16k | Self::Opus6k => 48_000,
+            Self::Opus24k | Self::Opus16k | Self::Opus6k
+            | Self::Opus32k | Self::Opus48k | Self::Opus64k => 48_000,
             Self::Codec2_3200 | Self::Codec2_1200 => 8_000,
+            Self::ComfortNoise => 48_000,
         }
     }
 
@@ -57,6 +71,10 @@ impl CodecId {
             2 => Some(Self::Opus6k),
             3 => Some(Self::Codec2_3200),
             4 => Some(Self::Codec2_1200),
+            5 => Some(Self::ComfortNoise),
+            6 => Some(Self::Opus32k),
+            7 => Some(Self::Opus48k),
+            8 => Some(Self::Opus64k),
             _ => None,
         }
     }
@@ -65,6 +83,12 @@ impl CodecId {
     pub const fn to_wire(self) -> u8 {
         self as u8
     }
+
+    /// Returns true if this is an Opus variant.
+    pub const fn is_opus(self) -> bool {
+        matches!(self, Self::Opus6k | Self::Opus16k | Self::Opus24k
+            | Self::Opus32k | Self::Opus48k | Self::Opus64k)
+    }
 }
 
 /// Describes the complete quality configuration for a call session.
@@ -105,6 +129,30 @@ impl QualityProfile {
         frames_per_block: 8,
     };
 
+    /// Studio low: Opus 32kbps, minimal FEC.
+    pub const STUDIO_32K: Self = Self {
+        codec: CodecId::Opus32k,
+        fec_ratio: 0.1,
+        frame_duration_ms: 20,
+        frames_per_block: 5,
+    };
+
+    /// Studio: Opus 48kbps, minimal FEC.
+    pub const STUDIO_48K: Self = Self {
+        codec: CodecId::Opus48k,
+        fec_ratio: 0.1,
+        frame_duration_ms: 20,
+        frames_per_block: 5,
+    };
+
+    /// Studio high: Opus 64kbps, minimal FEC.
+    pub const STUDIO_64K: Self = Self {
+        codec: CodecId::Opus64k,
+        fec_ratio: 0.1,
+        frame_duration_ms: 20,
+        frames_per_block: 5,
+    };
+
     /// Estimated total bandwidth in kbps including FEC overhead.
     pub fn total_bitrate_kbps(&self) -> f32 {
         let base = self.codec.bitrate_bps() as f32 / 1000.0;

crates/wzp-proto/src/jitter.rs

@@ -1,7 +1,161 @@
 use std::collections::BTreeMap;
+use std::time::{Duration, Instant};
 
 use crate::packet::MediaPacket;
 
+// ---------------------------------------------------------------------------
+// Adaptive playout delay (NetEq-inspired)
+// ---------------------------------------------------------------------------
+
+/// Adaptive playout delay estimator based on observed inter-arrival jitter.
+///
+/// Inspired by WebRTC NetEq and IAX2 adaptive jitter buffering. Tracks an
+/// exponential moving average (EMA) of inter-packet arrival jitter and
+/// converts it to a target buffer depth in packets.
+pub struct AdaptivePlayoutDelay {
+    /// Current target delay in packets (equivalent to target_depth).
+    target_delay: usize,
+    /// Minimum allowed delay.
+    min_delay: usize,
+    /// Maximum allowed delay.
+    max_delay: usize,
+    /// Exponential moving average of inter-packet arrival jitter (ms).
+    jitter_ema: f64,
+    /// EMA smoothing factor for jitter increases (fast reaction).
+    alpha_up: f64,
+    /// EMA smoothing factor for jitter decreases (slow decay).
+    alpha_down: f64,
+    /// Last packet arrival timestamp (for computing inter-arrival jitter).
+    last_arrival_ms: Option<u64>,
+    /// Last packet expected timestamp.
+    last_expected_ms: Option<u64>,
+    /// Safety margin added to jitter-derived target (in packets).
+    safety_margin: f64,
+    /// Instant when a jitter spike was detected (handoff detection).
+    spike_detected_at: Option<Instant>,
+    /// Duration to hold max_delay after a spike is detected.
+    spike_cooldown: Duration,
+    /// Multiplier of jitter_ema that constitutes a spike.
+    spike_threshold_multiplier: f64,
+}
+
+/// Frame duration in milliseconds (20ms Opus/Codec2 frames).
+const FRAME_DURATION_MS: f64 = 20.0;
+/// Default safety margin in packets.
+const DEFAULT_SAFETY_MARGIN: f64 = 2.0;
+/// Default EMA smoothing factor (used for both up/down in non-mobile mode).
+const DEFAULT_ALPHA: f64 = 0.05;
+
+impl AdaptivePlayoutDelay {
+    /// Create a new adaptive playout delay estimator.
+    ///
+    /// - `min_delay`: minimum target delay in packets
+    /// - `max_delay`: maximum target delay in packets
+    pub fn new(min_delay: usize, max_delay: usize) -> Self {
+        Self {
+            target_delay: min_delay,
+            min_delay,
+            max_delay,
+            jitter_ema: 0.0,
+            alpha_up: DEFAULT_ALPHA,
+            alpha_down: DEFAULT_ALPHA,
+            last_arrival_ms: None,
+            last_expected_ms: None,
+            safety_margin: DEFAULT_SAFETY_MARGIN,
+            spike_detected_at: None,
+            spike_cooldown: Duration::from_secs(2),
+            spike_threshold_multiplier: 3.0,
+        }
+    }
+
+    /// Update with a new packet arrival. Returns the new target delay.
+    ///
+    /// - `arrival_ms`: when the packet actually arrived (wall clock)
+    /// - `expected_ms`: when it should have arrived (based on sequence * 20ms)
+    pub fn update(&mut self, arrival_ms: u64, expected_ms: u64) -> usize {
+        if let (Some(last_arrival), Some(last_expected)) =
+            (self.last_arrival_ms, self.last_expected_ms)
+        {
+            let actual_delta = arrival_ms as f64 - last_arrival as f64;
+            let expected_delta = expected_ms as f64 - last_expected as f64;
+            let jitter = (actual_delta - expected_delta).abs();
+
+            // Spike detection: check before EMA update
+            if self.jitter_ema > 0.0
+                && jitter > self.jitter_ema * self.spike_threshold_multiplier
+            {
+                self.spike_detected_at = Some(Instant::now());
+            }
+
+            // Asymmetric EMA update
+            let alpha = if jitter > self.jitter_ema {
+                self.alpha_up
+            } else {
+                self.alpha_down
+            };
+            self.jitter_ema = alpha * jitter + (1.0 - alpha) * self.jitter_ema;
+
+            // Check if spike cooldown has expired
+            if let Some(spike_time) = self.spike_detected_at {
+                if spike_time.elapsed() >= self.spike_cooldown {
+                    self.spike_detected_at = None;
+                }
+            }
+
+            // If within spike cooldown, return max_delay
+            if self.spike_detected_at.is_some() {
+                self.target_delay = self.max_delay;
+            } else {
+                // Convert jitter estimate to target delay in packets
+                let raw_target =
+                    (self.jitter_ema / FRAME_DURATION_MS).ceil() + self.safety_margin;
+                self.target_delay =
+                    (raw_target as usize).clamp(self.min_delay, self.max_delay);
+            }
+        }
+
+        self.last_arrival_ms = Some(arrival_ms);
+        self.last_expected_ms = Some(expected_ms);
+        self.target_delay
+    }
+
+    /// Get current target delay in packets.
+    pub fn target_delay(&self) -> usize {
+        self.target_delay
+    }
+
+    /// Get current jitter estimate in ms.
+    pub fn jitter_estimate_ms(&self) -> f64 {
+        self.jitter_ema
+    }
+
+    /// Enable or disable mobile mode, adjusting parameters for cellular networks.
+    ///
+    /// Mobile mode uses:
+    /// - Asymmetric alpha (fast up=0.3, slow down=0.02) for quicker spike detection
+    /// - Higher safety margin (3.0 packets) to absorb handoff jitter
+    /// - Spike detection with 2-second cooldown at 3x threshold
+    pub fn set_mobile_mode(&mut self, enabled: bool) {
+        if enabled {
+            self.safety_margin = 3.0;
+            self.alpha_up = 0.3;
+            self.alpha_down = 0.02;
+            self.spike_threshold_multiplier = 3.0;
+            self.spike_cooldown = Duration::from_secs(2);
+        } else {
+            self.safety_margin = DEFAULT_SAFETY_MARGIN;
+            self.alpha_up = DEFAULT_ALPHA;
+            self.alpha_down = DEFAULT_ALPHA;
+            self.spike_threshold_multiplier = 3.0;
+            self.spike_cooldown = Duration::from_secs(2);
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Jitter buffer
+// ---------------------------------------------------------------------------
+
 /// Adaptive jitter buffer that reorders packets by sequence number.
 ///
 /// Designed for the lossy relay link with up to 5 seconds of buffering depth.
@@ -21,6 +175,8 @@ pub struct JitterBuffer {
     initialized: bool,
     /// Statistics.
     stats: JitterStats,
+    /// Optional adaptive playout delay estimator.
+    adaptive: Option<AdaptivePlayoutDelay>,
 }
 
 /// Jitter buffer statistics.
@@ -32,6 +188,14 @@ pub struct JitterStats {
     pub packets_late: u64,
     pub packets_duplicate: u64,
     pub current_depth: usize,
+    /// Total frames decoded by the consumer (tracked externally via `record_decode`).
+    pub total_decoded: u64,
+    /// Number of times the consumer tried to decode but the buffer was empty/not-ready.
+    pub underruns: u64,
+    /// Number of packets dropped because the buffer exceeded max depth.
+    pub overruns: u64,
+    /// High water mark — maximum buffer depth observed.
+    pub max_depth_seen: usize,
 }
 
 /// Result of attempting to get the next packet for playout.
@@ -60,6 +224,27 @@ impl JitterBuffer {
             min_depth,
             initialized: false,
             stats: JitterStats::default(),
+            adaptive: None,
+        }
+    }
+
+    /// Create a jitter buffer with adaptive playout delay.
+    ///
+    /// The target depth will be automatically adjusted based on observed
+    /// inter-arrival jitter (NetEq-inspired algorithm).
+    ///
+    /// - `min_delay`: minimum target delay in packets
+    /// - `max_delay`: maximum target delay in packets (also used as max_depth)
+    pub fn new_adaptive(min_delay: usize, max_delay: usize) -> Self {
+        Self {
+            buffer: BTreeMap::new(),
+            next_playout_seq: 0,
+            max_depth: max_delay,
+            target_depth: min_delay,
+            min_depth: min_delay,
+            initialized: false,
+            stats: JitterStats::default(),
+            adaptive: Some(AdaptivePlayoutDelay::new(min_delay, max_delay)),
         }
     }
 
@@ -88,10 +273,21 @@ impl JitterBuffer {
             return;
         }
 
-        // Check if packet is too old (already played out)
+        // Check if packet is too old (already played out).
+        // A backward jump of >100 seq (~2s at 50fps) indicates a new sender in a
+        // federation room — reset instead of dropping.
         if self.stats.packets_played > 0 && seq_before(seq, self.next_playout_seq) {
-            self.stats.packets_late += 1;
-            return;
+            let backward_distance = self.next_playout_seq.wrapping_sub(seq);
+            tracing::warn!(seq, next = self.next_playout_seq, backward_distance, "jitter: backward seq detected");
+            if backward_distance > 100 {
+                tracing::info!(seq, next = self.next_playout_seq, "jitter: RESET — new sender detected");
+                self.buffer.clear();
+                self.next_playout_seq = seq;
+                self.stats.packets_late = 0;
+            } else {
+                self.stats.packets_late += 1;
+                return;
+            }
         }
 
         // If we haven't started playout yet, adjust next_playout_seq to earliest known
@@ -99,12 +295,35 @@ impl JitterBuffer {
             self.next_playout_seq = seq;
         }
 
+        // Update adaptive playout delay if enabled.
+        // Use the packet's timestamp as expected_ms and compute a simple wall-clock
+        // proxy from the header timestamp (arrival_ms is approximated as timestamp
+        // + observed jitter, but since we don't have real wall-clock here we use
+        // the receive order with the header timestamp as the expected baseline).
+        if let Some(ref mut adaptive) = self.adaptive {
+            // expected_ms derived from sequence-implied timing: seq * frame_duration
+            let expected_ms = packet.header.timestamp as u64;
+            // For arrival_ms, use the actual receive timestamp. In the absence of
+            // a wall-clock parameter, we use std::time for a monotonic approximation.
+            // However, to keep the API simple, we compute arrival from the packet
+            // stats: the Nth received packet "arrives" at N * frame_duration as a
+            // baseline, and real network jitter shows in the deviation.
+            // NOTE: In production, the caller should pass real wall-clock time.
+            // For now, we use the header timestamp as-is (callers with adaptive
+            // mode should feed arrival time via push_with_arrival).
+            let arrival_ms = expected_ms; // no-op for basic push; use push_with_arrival
+            adaptive.update(arrival_ms, expected_ms);
+            self.target_depth = adaptive.target_delay();
+            self.min_depth = self.min_depth.min(self.target_depth);
+        }
+
         self.buffer.insert(seq, packet);
 
         // Evict oldest if over max depth
         while self.buffer.len() > self.max_depth {
             if let Some((&oldest_seq, _)) = self.buffer.first_key_value() {
                 self.buffer.remove(&oldest_seq);
+                self.stats.overruns += 1;
                 // Advance playout seq past evicted packet
                 if seq_before(self.next_playout_seq, oldest_seq.wrapping_add(1)) {
                     self.next_playout_seq = oldest_seq.wrapping_add(1);
@@ -114,6 +333,9 @@ impl JitterBuffer {
         }
 
         self.stats.current_depth = self.buffer.len();
+        if self.stats.current_depth > self.stats.max_depth_seen {
+            self.stats.max_depth_seen = self.stats.current_depth;
+        }
     }
 
     /// Get the next packet for playout.
@@ -163,6 +385,102 @@ impl JitterBuffer {
         self.stats = JitterStats::default();
     }
 
+    /// Record that the consumer attempted to decode but the buffer was empty/not-ready.
+    pub fn record_underrun(&mut self) {
+        self.stats.underruns += 1;
+    }
+
+    /// Record a successful frame decode by the consumer.
+    pub fn record_decode(&mut self) {
+        self.stats.total_decoded += 1;
+    }
+
+    /// Reset statistics counters (preserves buffer contents and playout state).
+    pub fn reset_stats(&mut self) {
+        self.stats = JitterStats {
+            current_depth: self.buffer.len(),
+            ..JitterStats::default()
+        };
+    }
+
+    /// Push a received packet with an explicit wall-clock arrival time.
+    ///
+    /// This is the preferred entry point when adaptive playout delay is enabled,
+    /// since the estimator needs real arrival timestamps.
+    pub fn push_with_arrival(&mut self, packet: MediaPacket, arrival_ms: u64) {
+        let expected_ms = packet.header.timestamp as u64;
+        let seq = packet.header.seq;
+        self.stats.packets_received += 1;
+
+        if !self.initialized {
+            self.next_playout_seq = seq;
+            self.initialized = true;
+        }
+
+        // Check for duplicates
+        if self.buffer.contains_key(&seq) {
+            self.stats.packets_duplicate += 1;
+            return;
+        }
+
+        // Check if packet is too old (already played out).
+        // A backward jump of >100 seq (~2s at 50fps) indicates a new sender in a
+        // federation room — reset instead of dropping.
+        if self.stats.packets_played > 0 && seq_before(seq, self.next_playout_seq) {
+            let backward_distance = self.next_playout_seq.wrapping_sub(seq);
+            tracing::warn!(seq, next = self.next_playout_seq, backward_distance, "jitter: backward seq detected");
+            if backward_distance > 100 {
+                tracing::info!(seq, next = self.next_playout_seq, "jitter: RESET — new sender detected");
+                self.buffer.clear();
+                self.next_playout_seq = seq;
+                self.stats.packets_late = 0;
+            } else {
+                self.stats.packets_late += 1;
+                return;
+            }
+        }
+
+        // If we haven't started playout yet, adjust next_playout_seq to earliest known
+        if self.stats.packets_played == 0 && seq_before(seq, self.next_playout_seq) {
+            self.next_playout_seq = seq;
+        }
+
+        // Update adaptive playout delay if enabled.
+        if let Some(ref mut adaptive) = self.adaptive {
+            adaptive.update(arrival_ms, expected_ms);
+            self.target_depth = adaptive.target_delay();
+        }
+
+        self.buffer.insert(seq, packet);
+
+        // Evict oldest if over max depth
+        while self.buffer.len() > self.max_depth {
+            if let Some((&oldest_seq, _)) = self.buffer.first_key_value() {
+                self.buffer.remove(&oldest_seq);
+                self.stats.overruns += 1;
+                if seq_before(self.next_playout_seq, oldest_seq.wrapping_add(1)) {
+                    self.next_playout_seq = oldest_seq.wrapping_add(1);
+                    self.stats.packets_lost += 1;
+                }
+            }
+        }
+
+        self.stats.current_depth = self.buffer.len();
+        if self.stats.current_depth > self.stats.max_depth_seen {
+            self.stats.max_depth_seen = self.stats.current_depth;
+        }
+    }
+
+    /// Get a reference to the adaptive playout delay estimator, if enabled.
+    pub fn adaptive_delay(&self) -> Option<&AdaptivePlayoutDelay> {
+        self.adaptive.as_ref()
+    }
+
+    /// Get a mutable reference to the adaptive playout delay estimator.
+    pub fn adaptive_delay_mut(&mut self) -> Option<&mut AdaptivePlayoutDelay> {
+        self.adaptive.as_mut()
+    }
+
     /// Adjust target depth based on observed jitter.
     pub fn set_target_depth(&mut self, depth: usize) {
         self.target_depth = depth.min(self.max_depth);
@@ -304,4 +622,217 @@ mod tests {
             other => panic!("expected packet 0, got {:?}", other),
         }
     }
+
+    // ---------------------------------------------------------------
+    // AdaptivePlayoutDelay tests
+    // ---------------------------------------------------------------
+
+    #[test]
+    fn adaptive_delay_stable() {
+        // Feed packets with consistent 20ms spacing — target should stay at minimum.
+        let mut apd = AdaptivePlayoutDelay::new(3, 50);
+
+        for i in 0u64..200 {
+            let arrival_ms = i * 20;
+            let expected_ms = i * 20;
+            apd.update(arrival_ms, expected_ms);
+        }
+
+        // With zero jitter, target should be min_delay (ceil(0/20) + 2 = 2,
+        // clamped to min_delay=3).
+        assert_eq!(apd.target_delay(), 3);
+        assert!(
+            apd.jitter_estimate_ms() < 1.0,
+            "jitter estimate should be near zero, got {}",
+            apd.jitter_estimate_ms()
+        );
+    }
+
+    #[test]
+    fn adaptive_delay_increases_on_jitter() {
+        // Feed packets with variable spacing (±10ms jitter).
+        let mut apd = AdaptivePlayoutDelay::new(3, 50);
+
+        // Alternate: arrive 10ms early / 10ms late
+        for i in 0u64..200 {
+            let expected_ms = i * 20;
+            let jitter_offset: i64 = if i % 2 == 0 { 10 } else { -10 };
+            let arrival_ms = (expected_ms as i64 + jitter_offset).max(0) as u64;
+            apd.update(arrival_ms, expected_ms);
+        }
+
+        // Inter-arrival jitter should be ~20ms (swing of 10 to -10 = delta 20).
+        // target = ceil(~20/20) + 2 = 3, but EMA converges near 20 so target >= 3.
+        assert!(
+            apd.target_delay() >= 3,
+            "target should increase with jitter, got {}",
+            apd.target_delay()
+        );
+        assert!(
+            apd.jitter_estimate_ms() > 5.0,
+            "jitter estimate should be significant, got {}",
+            apd.jitter_estimate_ms()
+        );
+    }
+
+    #[test]
+    fn adaptive_delay_decreases_on_recovery() {
+        let mut apd = AdaptivePlayoutDelay::new(3, 50);
+
+        // Phase 1: high jitter (±30ms)
+        for i in 0u64..200 {
+            let expected_ms = i * 20;
+            let offset: i64 = if i % 2 == 0 { 30 } else { -30 };
+            let arrival_ms = (expected_ms as i64 + offset).max(0) as u64;
+            apd.update(arrival_ms, expected_ms);
+        }
+        let high_target = apd.target_delay();
+        let high_jitter = apd.jitter_estimate_ms();
+
+        // Phase 2: stable (no jitter) — target should decrease via EMA decay
+        for i in 200u64..600 {
+            let t = i * 20;
+            apd.update(t, t);
+        }
+        let low_target = apd.target_delay();
+        let low_jitter = apd.jitter_estimate_ms();
+
+        assert!(
+            low_target <= high_target,
+            "target should decrease after recovery: {} -> {}",
+            high_target,
+            low_target
+        );
+        assert!(
+            low_jitter < high_jitter,
+            "jitter estimate should decrease: {} -> {}",
+            high_jitter,
+            low_jitter
+        );
+    }
+
+    #[test]
+    fn adaptive_delay_clamped() {
+        let mut apd = AdaptivePlayoutDelay::new(3, 10);
+
+        // Extreme jitter: packets arrive with huge variance
+        for i in 0u64..500 {
+            let expected_ms = i * 20;
+            let offset: i64 = if i % 2 == 0 { 500 } else { -500 };
+            let arrival_ms = (expected_ms as i64 + offset).max(0) as u64;
+            apd.update(arrival_ms, expected_ms);
+        }
+
+        assert!(
+            apd.target_delay() <= 10,
+            "target should not exceed max_delay=10, got {}",
+            apd.target_delay()
+        );
+        assert!(
+            apd.target_delay() >= 3,
+            "target should not go below min_delay=3, got {}",
+            apd.target_delay()
+        );
+    }
+
+    #[test]
+    fn adaptive_jitter_estimate() {
+        let mut apd = AdaptivePlayoutDelay::new(3, 50);
+
+        // Initial jitter estimate should be zero
+        assert_eq!(apd.jitter_estimate_ms(), 0.0);
+
+        // After one packet, still zero (no delta yet)
+        apd.update(0, 0);
+        assert_eq!(apd.jitter_estimate_ms(), 0.0);
+
+        // Second packet with 5ms jitter
+        apd.update(25, 20); // arrived 5ms late
+        assert!(
+            apd.jitter_estimate_ms() > 0.0,
+            "jitter estimate should be positive after jittery packet"
+        );
+        assert!(
+            apd.jitter_estimate_ms() <= 5.0,
+            "first jitter sample of 5ms with alpha=0.05 should not exceed 5ms, got {}",
+            apd.jitter_estimate_ms()
+        );
+
+        // Feed many packets with ~15ms jitter — EMA should converge
+        for i in 2u64..500 {
+            let expected_ms = i * 20;
+            let arrival_ms = expected_ms + 15; // consistently 15ms late
+            apd.update(arrival_ms, expected_ms);
+        }
+        // Steady-state: inter-arrival jitter = |35 - 20| = 0 actually,
+        // because if every packet is 15ms late, delta_actual = 35-35 = 20,
+        // same as expected. So jitter should converge toward 0.
+        // Let's use variable jitter instead for a better test.
+        let mut apd2 = AdaptivePlayoutDelay::new(3, 50);
+        for i in 0u64..500 {
+            let expected_ms = i * 20;
+            // Alternate 0ms and 15ms late
+            let extra = if i % 2 == 0 { 0 } else { 15 };
+            let arrival_ms = expected_ms + extra;
+            apd2.update(arrival_ms, expected_ms);
+        }
+        let est = apd2.jitter_estimate_ms();
+        assert!(
+            est > 5.0 && est < 20.0,
+            "jitter estimate should converge near 15ms with alternating 0/15ms offsets, got {}",
+            est
+        );
+    }
+
+    // ---------------------------------------------------------------
+    // JitterBuffer with adaptive mode tests
+    // ---------------------------------------------------------------
+
+    #[test]
+    fn jitter_buffer_adaptive_constructor() {
+        let jb = JitterBuffer::new_adaptive(5, 250);
+        assert!(jb.adaptive_delay().is_some());
+        assert_eq!(jb.adaptive_delay().unwrap().target_delay(), 5);
+    }
+
+    #[test]
+    fn jitter_buffer_adaptive_push_with_arrival() {
+        let mut jb = JitterBuffer::new_adaptive(3, 50);
+
+        // Push packets with consistent timing
+        for i in 0u16..20 {
+            let pkt = make_packet(i);
+            let arrival_ms = i as u64 * 20;
+            jb.push_with_arrival(pkt, arrival_ms);
+        }
+
+        // With zero jitter, target should stay at min
+        let ad = jb.adaptive_delay().unwrap();
+        assert_eq!(ad.target_delay(), 3);
+    }
+
+    // ---------------------------------------------------------------
+    // Mobile mode tests
+    // ---------------------------------------------------------------
+
+    #[test]
+    fn mobile_mode_increases_safety_margin() {
+        let mut apd = AdaptivePlayoutDelay::new(3, 50);
+        apd.set_mobile_mode(true);
+        assert_eq!(apd.safety_margin, 3.0);
+        assert_eq!(apd.alpha_up, 0.3);
+        assert_eq!(apd.alpha_down, 0.02);
+
+        apd.set_mobile_mode(false);
+        assert_eq!(apd.safety_margin, DEFAULT_SAFETY_MARGIN);
+        assert_eq!(apd.alpha_up, DEFAULT_ALPHA);
+        assert_eq!(apd.alpha_down, DEFAULT_ALPHA);
+    }
+
+    #[test]
+    fn mobile_mode_accessible_via_jitter_buffer() {
+        let mut jb = JitterBuffer::new_adaptive(3, 50);
+        jb.adaptive_delay_mut().unwrap().set_mobile_mode(true);
+        assert_eq!(jb.adaptive_delay().unwrap().safety_margin, 3.0);
+    }
 }

crates/wzp-proto/src/lib.rs

@@ -12,6 +12,7 @@
 //! - Identity = 32-byte seed → HKDF → Ed25519 (signing) + X25519 (encryption)
 //! - Fingerprint = SHA-256(Ed25519 pub)[:16]
 
+pub mod bandwidth;
 pub mod codec_id;
 pub mod error;
 pub mod jitter;
@@ -23,7 +24,12 @@ pub mod traits;
 // Re-export key types at crate root for convenience.
 pub use codec_id::{CodecId, QualityProfile};
 pub use error::*;
-pub use packet::{HangupReason, MediaHeader, MediaPacket, QualityReport, SignalMessage};
-pub use quality::{AdaptiveQualityController, Tier};
+pub use packet::{
+    CallAcceptMode, HangupReason, MediaHeader, MediaPacket, MiniFrameContext, MiniHeader,
+    QualityReport, RoomParticipant, SignalMessage, TrunkEntry, TrunkFrame, FRAME_TYPE_FULL,
+    FRAME_TYPE_MINI,
+};
+pub use bandwidth::{BandwidthEstimator, CongestionState};
+pub use quality::{AdaptiveQualityController, NetworkContext, Tier};
 pub use session::{Session, SessionEvent, SessionState};
 pub use traits::*;

crates/wzp-proto/src/packet.rs

@@ -46,6 +46,23 @@ impl MediaHeader {
     /// Header size in bytes on the wire.
     pub const WIRE_SIZE: usize = 12;
 
+    /// Create a default header for raw PCM relay (used by WebSocket bridge).
+    pub fn default_pcm() -> Self {
+        Self {
+            version: 0,
+            is_repair: false,
+            codec_id: CodecId::Opus24k,
+            has_quality_report: false,
+            fec_ratio_encoded: 0,
+            seq: 0,
+            timestamp: 0,
+            fec_block: 0,
+            fec_symbol: 0,
+            reserved: 0,
+            csrc_count: 0,
+        }
+    }
+
     /// Encode the FEC ratio float (0.0-2.0+) to a 7-bit value (0-127).
     pub fn encode_fec_ratio(ratio: f32) -> u8 {
         // Map 0.0-2.0 to 0-127, clamping at 127
@@ -191,6 +208,9 @@ pub struct MediaPacket {
     pub quality_report: Option<QualityReport>,
 }
 
+/// Maximum number of mini-frames between full headers (1 second at 50 fps).
+pub const MINI_FRAME_FULL_INTERVAL: u32 = 50;
+
 impl MediaPacket {
     /// Serialize the entire packet to bytes.
     pub fn to_bytes(&self) -> Bytes {
@@ -239,6 +259,276 @@ impl MediaPacket {
             quality_report,
         })
     }
+
+    /// Serialize with mini-frame compression.
+    ///
+    /// Uses the `MiniFrameContext` to decide whether to emit a compact 4-byte
+    /// mini-header or a full 12-byte header.  A full header is forced on the
+    /// first frame and every `MINI_FRAME_FULL_INTERVAL` frames thereafter.
+    pub fn encode_compact(
+        &self,
+        ctx: &mut MiniFrameContext,
+        frames_since_full: &mut u32,
+    ) -> Bytes {
+        if *frames_since_full > 0 && *frames_since_full < MINI_FRAME_FULL_INTERVAL {
+            // --- mini frame ---
+            let ts_delta = self
+                .header
+                .timestamp
+                .wrapping_sub(ctx.last_header.unwrap().timestamp)
+                as u16;
+            let mini = MiniHeader {
+                timestamp_delta_ms: ts_delta,
+                payload_len: self.payload.len() as u16,
+            };
+            let total = 1 + MiniHeader::WIRE_SIZE + self.payload.len();
+            let mut buf = BytesMut::with_capacity(total);
+            buf.put_u8(FRAME_TYPE_MINI);
+            mini.write_to(&mut buf);
+            buf.put(self.payload.clone());
+            // Advance the context so the next mini-frame delta is relative
+            // to this frame, mirroring what expand() does on the decoder side.
+            ctx.update(&self.header);
+            *frames_since_full += 1;
+            buf.freeze()
+        } else {
+            // --- full frame ---
+            let qr_size = if self.quality_report.is_some() {
+                QualityReport::WIRE_SIZE
+            } else {
+                0
+            };
+            let total = 1 + MediaHeader::WIRE_SIZE + self.payload.len() + qr_size;
+            let mut buf = BytesMut::with_capacity(total);
+            buf.put_u8(FRAME_TYPE_FULL);
+            self.header.write_to(&mut buf);
+            buf.put(self.payload.clone());
+            if let Some(ref qr) = self.quality_report {
+                qr.write_to(&mut buf);
+            }
+            ctx.update(&self.header);
+            *frames_since_full = 1; // next frame will be the 1st after full
+            buf.freeze()
+        }
+    }
+
+    /// Decode from compact wire format (auto-detects full vs mini).
+    ///
+    /// Returns `None` on malformed input or if a mini-frame arrives before any
+    /// full header baseline has been established.
+    pub fn decode_compact(buf: &[u8], ctx: &mut MiniFrameContext) -> Option<Self> {
+        if buf.is_empty() {
+            return None;
+        }
+        let frame_type = buf[0];
+        let rest = &buf[1..];
+
+        match frame_type {
+            FRAME_TYPE_FULL => {
+                let pkt = Self::from_bytes(Bytes::copy_from_slice(rest))?;
+                ctx.update(&pkt.header);
+                Some(pkt)
+            }
+            FRAME_TYPE_MINI => {
+                if rest.len() < MiniHeader::WIRE_SIZE {
+                    return None;
+                }
+                let mut cursor = rest;
+                let mini = MiniHeader::read_from(&mut cursor)?;
+                let payload_start = 1 + MiniHeader::WIRE_SIZE;
+                let payload_end = payload_start + mini.payload_len as usize;
+                if buf.len() < payload_end {
+                    return None;
+                }
+                let payload = Bytes::copy_from_slice(&buf[payload_start..payload_end]);
+                let header = ctx.expand(&mini)?;
+                Some(Self {
+                    header,
+                    payload,
+                    quality_report: None,
+                })
+            }
+            _ => None,
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Trunking — multiplex multiple session packets into one QUIC datagram
+// ---------------------------------------------------------------------------
+
+/// A single entry inside a [`TrunkFrame`].
+#[derive(Clone, Debug)]
+pub struct TrunkEntry {
+    /// 2-byte session identifier (up to 65 536 sessions).
+    pub session_id: [u8; 2],
+    /// Encoded MediaPacket payload (already compressed).
+    pub payload: Bytes,
+}
+
+impl TrunkEntry {
+    /// Per-entry wire overhead: 2 (session_id) + 2 (len).
+    pub const OVERHEAD: usize = 4;
+}
+
+/// A trunked frame carrying multiple session packets in one datagram.
+///
+/// Wire format:
+/// ```text
+/// [count:u16] [entry1] [entry2] ...
+/// ```
+/// Each entry:
+/// ```text
+/// [session_id:2] [len:u16] [payload:len]
+/// ```
+#[derive(Clone, Debug)]
+pub struct TrunkFrame {
+    pub packets: Vec<TrunkEntry>,
+}
+
+impl TrunkFrame {
+    /// Create an empty trunk frame.
+    pub fn new() -> Self {
+        Self {
+            packets: Vec::new(),
+        }
+    }
+
+    /// Append a session packet to the frame.
+    pub fn push(&mut self, session_id: [u8; 2], payload: Bytes) {
+        self.packets.push(TrunkEntry {
+            session_id,
+            payload,
+        });
+    }
+
+    /// Number of entries in the frame.
+    pub fn len(&self) -> usize {
+        self.packets.len()
+    }
+
+    /// Whether the frame is empty.
+    pub fn is_empty(&self) -> bool {
+        self.packets.is_empty()
+    }
+
+    /// Total wire size of the encoded frame.
+    pub fn wire_size(&self) -> usize {
+        // 2 bytes for count + each entry
+        2 + self
+            .packets
+            .iter()
+            .map(|e| TrunkEntry::OVERHEAD + e.payload.len())
+            .sum::<usize>()
+    }
+
+    /// Encode to wire bytes.
+    pub fn encode(&self) -> Bytes {
+        let mut buf = BytesMut::with_capacity(self.wire_size());
+        buf.put_u16(self.packets.len() as u16);
+        for entry in &self.packets {
+            buf.put_slice(&entry.session_id);
+            buf.put_u16(entry.payload.len() as u16);
+            buf.put(entry.payload.clone());
+        }
+        buf.freeze()
+    }
+
+    /// Decode from wire bytes. Returns `None` on malformed input.
+    pub fn decode(buf: &[u8]) -> Option<Self> {
+        if buf.len() < 2 {
+            return None;
+        }
+        let mut cursor = &buf[..];
+        let count = cursor.get_u16() as usize;
+        let mut packets = Vec::with_capacity(count);
+        for _ in 0..count {
+            if cursor.remaining() < TrunkEntry::OVERHEAD {
+                return None;
+            }
+            let mut session_id = [0u8; 2];
+            session_id[0] = cursor.get_u8();
+            session_id[1] = cursor.get_u8();
+            let len = cursor.get_u16() as usize;
+            if cursor.remaining() < len {
+                return None;
+            }
+            let payload = Bytes::copy_from_slice(&cursor[..len]);
+            cursor.advance(len);
+            packets.push(TrunkEntry {
+                session_id,
+                payload,
+            });
+        }
+        Some(Self { packets })
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Mini-frames — compact header for steady-state media packets
+// ---------------------------------------------------------------------------
+
+/// Frame type tag: full MediaHeader follows.
+pub const FRAME_TYPE_FULL: u8 = 0x00;
+/// Frame type tag: MiniHeader follows (requires prior baseline).
+pub const FRAME_TYPE_MINI: u8 = 0x01;
+
+/// Compact 4-byte header used after a full MediaHeader baseline has been
+/// established. Only the timestamp delta and payload length are transmitted;
+/// all other fields are inherited from the last full header.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct MiniHeader {
+    /// Milliseconds elapsed since the last header's timestamp.
+    pub timestamp_delta_ms: u16,
+    /// Length of the payload that follows this header.
+    pub payload_len: u16,
+}
+
+impl MiniHeader {
+    /// Header size in bytes on the wire.
+    pub const WIRE_SIZE: usize = 4;
+
+    /// Serialize to a 4-byte buffer.
+    pub fn write_to(&self, buf: &mut impl BufMut) {
+        buf.put_u16(self.timestamp_delta_ms);
+        buf.put_u16(self.payload_len);
+    }
+
+    /// Deserialize from a buffer. Returns `None` if insufficient data.
+    pub fn read_from(buf: &mut impl Buf) -> Option<Self> {
+        if buf.remaining() < Self::WIRE_SIZE {
+            return None;
+        }
+        Some(Self {
+            timestamp_delta_ms: buf.get_u16(),
+            payload_len: buf.get_u16(),
+        })
+    }
+}
+
+/// Stateful context that expands [`MiniHeader`]s back into full
+/// [`MediaHeader`]s by tracking the last baseline header.
+#[derive(Clone, Debug, Default)]
+pub struct MiniFrameContext {
+    last_header: Option<MediaHeader>,
+}
+
+impl MiniFrameContext {
+    /// Record a full header as the new baseline for subsequent mini-frames.
+    pub fn update(&mut self, header: &MediaHeader) {
+        self.last_header = Some(*header);
+    }
+
+    /// Expand a mini-header into a full [`MediaHeader`] using the stored
+    /// baseline.  Returns `None` if no baseline has been set yet.
+    pub fn expand(&mut self, mini: &MiniHeader) -> Option<MediaHeader> {
+        let base = self.last_header.as_ref()?;
+        let mut expanded = *base;
+        expanded.seq = base.seq.wrapping_add(1);
+        expanded.timestamp = base.timestamp.wrapping_add(mini.timestamp_delta_ms as u32);
+        self.last_header = Some(expanded);
+        Some(expanded)
+    }
 }
 
 /// Signaling messages sent over the reliable QUIC stream.
@@ -258,6 +548,9 @@ pub enum SignalMessage {
         signature: Vec<u8>,
         /// Supported quality profiles.
         supported_profiles: Vec<crate::QualityProfile>,
+        /// Optional display name set by the caller.
+        #[serde(default)]
+        alias: Option<String>,
     },
 
     /// Call acceptance (analogous to Warzone's WireMessage::CallAnswer).
@@ -297,6 +590,191 @@ pub enum SignalMessage {
 
     /// End the call.
     Hangup { reason: HangupReason },
+
+    /// featherChat bearer token for relay authentication.
+    /// Sent as the first signal message when --auth-url is configured.
+    AuthToken { token: String },
+
+    /// Put the call on hold (stop sending media, keep session alive).
+    Hold,
+    /// Resume a held call.
+    Unhold,
+    /// Mute request from the remote side (server-initiated mute, like IAX2 QUELCH).
+    Mute,
+    /// Unmute request from the remote side (like IAX2 UNQUELCH).
+    Unmute,
+    /// Transfer the call to another peer.
+    Transfer {
+        target_fingerprint: String,
+        /// Optional relay address for the transfer target.
+        relay_addr: Option<String>,
+    },
+    /// Acknowledge a transfer request.
+    TransferAck,
+
+    /// Presence update from a peer relay (gossip protocol).
+    /// Sent periodically over probe connections to share which fingerprints
+    /// are connected to the sending relay.
+    PresenceUpdate {
+        /// Fingerprints currently connected to the sending relay.
+        fingerprints: Vec<String>,
+        /// Address of the sending relay (e.g., "192.168.1.10:4433").
+        relay_addr: String,
+    },
+
+    /// Ask a peer relay to look up a fingerprint in its registry.
+    RouteQuery {
+        fingerprint: String,
+        ttl: u8,
+    },
+    /// Response to a route query.
+    RouteResponse {
+        fingerprint: String,
+        found: bool,
+        relay_chain: Vec<String>,
+    },
+
+    /// Request to set up a forwarding session for a specific fingerprint.
+    /// Sent over a relay link (`_relay` SNI) to ask the peer relay to
+    /// create a room and forward media for the given session.
+    SessionForward {
+        session_id: String,
+        target_fingerprint: String,
+        source_relay: String,
+    },
+    /// Confirm that the forwarding session has been set up on the peer relay.
+    /// The `room_name` tells the source relay which room to address media to.
+    SessionForwardAck {
+        session_id: String,
+        room_name: String,
+    },
+
+    /// Room membership update — sent by relay to all participants when someone joins or leaves.
+    RoomUpdate {
+        /// Current participant count.
+        count: u32,
+        /// List of participants currently in the room.
+        participants: Vec<RoomParticipant>,
+    },
+
+    // ── Federation signals (relay-to-relay) ──
+
+    /// Federation: initial handshake — the connecting relay identifies itself.
+    FederationHello {
+        /// TLS certificate fingerprint of the connecting relay.
+        tls_fingerprint: String,
+    },
+
+    /// Federation: this relay now has local participants in a global room.
+    GlobalRoomActive {
+        room: String,
+        /// Participants on the announcing relay (for federated presence).
+        #[serde(default)]
+        participants: Vec<RoomParticipant>,
+    },
+
+    /// Federation: this relay's last local participant left a global room.
+    GlobalRoomInactive {
+        room: String,
+    },
+
+    // ── Direct calling signals (client ↔ relay signaling) ──
+
+    /// Register on relay for direct calls. Sent on `_signal` connections
+    /// after optional AuthToken.
+    RegisterPresence {
+        /// Client's Ed25519 identity public key.
+        identity_pub: [u8; 32],
+        /// Signature over ("register-presence" || identity_pub).
+        signature: Vec<u8>,
+        /// Optional display name.
+        alias: Option<String>,
+    },
+
+    /// Relay confirms presence registration.
+    RegisterPresenceAck {
+        success: bool,
+        #[serde(skip_serializing_if = "Option::is_none")]
+        error: Option<String>,
+    },
+
+    /// Direct call offer routed through the relay to a specific peer.
+    DirectCallOffer {
+        /// Caller's fingerprint.
+        caller_fingerprint: String,
+        /// Caller's display name.
+        caller_alias: Option<String>,
+        /// Target's fingerprint.
+        target_fingerprint: String,
+        /// Unique call session ID (UUID).
+        call_id: String,
+        /// Caller's Ed25519 identity pub.
+        identity_pub: [u8; 32],
+        /// Caller's ephemeral X25519 pub (for key exchange on media connect).
+        ephemeral_pub: [u8; 32],
+        /// Signature over (ephemeral_pub || target_fingerprint || call_id).
+        signature: Vec<u8>,
+        /// Supported quality profiles.
+        supported_profiles: Vec<crate::QualityProfile>,
+    },
+
+    /// Callee's response to a direct call.
+    DirectCallAnswer {
+        call_id: String,
+        /// How the callee accepts (or rejects).
+        accept_mode: CallAcceptMode,
+        /// Callee's identity pub (present when accepting).
+        #[serde(skip_serializing_if = "Option::is_none")]
+        identity_pub: Option<[u8; 32]>,
+        /// Callee's ephemeral pub (present when accepting).
+        #[serde(skip_serializing_if = "Option::is_none")]
+        ephemeral_pub: Option<[u8; 32]>,
+        /// Signature (present when accepting).
+        #[serde(skip_serializing_if = "Option::is_none")]
+        signature: Option<Vec<u8>>,
+        /// Chosen quality profile (present when accepting).
+        #[serde(skip_serializing_if = "Option::is_none")]
+        chosen_profile: Option<crate::QualityProfile>,
+    },
+
+    /// Relay tells both parties: media room is ready.
+    CallSetup {
+        call_id: String,
+        /// Room name on the relay for the media session (e.g., "_call:a1b2c3d4").
+        room: String,
+        /// Relay address for the QUIC media connection.
+        relay_addr: String,
+    },
+
+    /// Ringing notification (relay → caller, callee received the offer).
+    CallRinging {
+        call_id: String,
+    },
+}
+
+/// How the callee responds to a direct call.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub enum CallAcceptMode {
+    /// Reject the call.
+    Reject,
+    /// Accept with trust — in Phase 2, this enables P2P (reveals IP).
+    /// In Phase 1, behaves the same as AcceptGeneric.
+    AcceptTrusted,
+    /// Accept with privacy — relay always mediates media.
+    AcceptGeneric,
+}
+
+/// A participant entry in a RoomUpdate message.
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct RoomParticipant {
+    /// Identity fingerprint (hex string, stable across reconnects if seed is persisted).
+    pub fingerprint: String,
+    /// Optional display name set by the client.
+    pub alias: Option<String>,
+    /// Relay label — identifies which relay this participant is connected to.
+    /// None for local participants, Some("Relay B") for federated.
+    #[serde(default)]
+    pub relay_label: Option<String>,
 }
 
 /// Reasons for ending a call.
@@ -410,6 +888,112 @@ mod tests {
         assert_eq!(packet.quality_report, decoded.quality_report);
     }
 
+    #[test]
+    fn hold_unhold_serialize() {
+        let hold = SignalMessage::Hold;
+        let json = serde_json::to_string(&hold).unwrap();
+        let decoded: SignalMessage = serde_json::from_str(&json).unwrap();
+        assert!(matches!(decoded, SignalMessage::Hold));
+
+        let unhold = SignalMessage::Unhold;
+        let json = serde_json::to_string(&unhold).unwrap();
+        let decoded: SignalMessage = serde_json::from_str(&json).unwrap();
+        assert!(matches!(decoded, SignalMessage::Unhold));
+    }
+
+    #[test]
+    fn mute_unmute_serialize() {
+        let mute = SignalMessage::Mute;
+        let json = serde_json::to_string(&mute).unwrap();
+        let decoded: SignalMessage = serde_json::from_str(&json).unwrap();
+        assert!(matches!(decoded, SignalMessage::Mute));
+
+        let unmute = SignalMessage::Unmute;
+        let json = serde_json::to_string(&unmute).unwrap();
+        let decoded: SignalMessage = serde_json::from_str(&json).unwrap();
+        assert!(matches!(decoded, SignalMessage::Unmute));
+    }
+
+    #[test]
+    fn transfer_serialize() {
+        let transfer = SignalMessage::Transfer {
+            target_fingerprint: "abc123".to_string(),
+            relay_addr: Some("relay.example.com:4433".to_string()),
+        };
+        let json = serde_json::to_string(&transfer).unwrap();
+        let decoded: SignalMessage = serde_json::from_str(&json).unwrap();
+        match decoded {
+            SignalMessage::Transfer {
+                target_fingerprint,
+                relay_addr,
+            } => {
+                assert_eq!(target_fingerprint, "abc123");
+                assert_eq!(relay_addr.unwrap(), "relay.example.com:4433");
+            }
+            _ => panic!("expected Transfer variant"),
+        }
+
+        // Also test with relay_addr = None
+        let transfer_no_relay = SignalMessage::Transfer {
+            target_fingerprint: "def456".to_string(),
+            relay_addr: None,
+        };
+        let json = serde_json::to_string(&transfer_no_relay).unwrap();
+        let decoded: SignalMessage = serde_json::from_str(&json).unwrap();
+        match decoded {
+            SignalMessage::Transfer {
+                target_fingerprint,
+                relay_addr,
+            } => {
+                assert_eq!(target_fingerprint, "def456");
+                assert!(relay_addr.is_none());
+            }
+            _ => panic!("expected Transfer variant"),
+        }
+    }
+
+    #[test]
+    fn transfer_ack_serialize() {
+        let ack = SignalMessage::TransferAck;
+        let json = serde_json::to_string(&ack).unwrap();
+        let decoded: SignalMessage = serde_json::from_str(&json).unwrap();
+        assert!(matches!(decoded, SignalMessage::TransferAck));
+    }
+
+    #[test]
+    fn presence_update_signal_roundtrip() {
+        let msg = SignalMessage::PresenceUpdate {
+            fingerprints: vec!["aabb".to_string(), "ccdd".to_string()],
+            relay_addr: "10.0.0.1:4433".to_string(),
+        };
+        let json = serde_json::to_string(&msg).unwrap();
+        let decoded: SignalMessage = serde_json::from_str(&json).unwrap();
+        match decoded {
+            SignalMessage::PresenceUpdate { fingerprints, relay_addr } => {
+                assert_eq!(fingerprints.len(), 2);
+                assert!(fingerprints.contains(&"aabb".to_string()));
+                assert!(fingerprints.contains(&"ccdd".to_string()));
+                assert_eq!(relay_addr, "10.0.0.1:4433");
+            }
+            _ => panic!("expected PresenceUpdate variant"),
+        }
+
+        // Empty fingerprints list
+        let msg_empty = SignalMessage::PresenceUpdate {
+            fingerprints: vec![],
+            relay_addr: "10.0.0.2:4433".to_string(),
+        };
+        let json = serde_json::to_string(&msg_empty).unwrap();
+        let decoded: SignalMessage = serde_json::from_str(&json).unwrap();
+        match decoded {
+            SignalMessage::PresenceUpdate { fingerprints, relay_addr } => {
+                assert!(fingerprints.is_empty());
+                assert_eq!(relay_addr, "10.0.0.2:4433");
+            }
+            _ => panic!("expected PresenceUpdate variant"),
+        }
+    }
+
     #[test]
     fn fec_ratio_encode_decode() {
         let ratio = 0.5;
@@ -421,4 +1005,247 @@ mod tests {
         let encoded_max = MediaHeader::encode_fec_ratio(ratio_max);
         assert_eq!(encoded_max, 127);
     }
+
+    // ---------------------------------------------------------------
+    // TrunkFrame tests
+    // ---------------------------------------------------------------
+
+    #[test]
+    fn trunk_frame_encode_decode() {
+        let mut frame = TrunkFrame::new();
+        frame.push([0, 1], Bytes::from_static(b"hello"));
+        frame.push([0, 2], Bytes::from_static(b"world!"));
+        frame.push([1, 0], Bytes::from_static(b"x"));
+        assert_eq!(frame.len(), 3);
+
+        let encoded = frame.encode();
+        let decoded = TrunkFrame::decode(&encoded).expect("decode failed");
+        assert_eq!(decoded.len(), 3);
+        assert_eq!(decoded.packets[0].session_id, [0, 1]);
+        assert_eq!(decoded.packets[0].payload, Bytes::from_static(b"hello"));
+        assert_eq!(decoded.packets[1].session_id, [0, 2]);
+        assert_eq!(decoded.packets[1].payload, Bytes::from_static(b"world!"));
+        assert_eq!(decoded.packets[2].session_id, [1, 0]);
+        assert_eq!(decoded.packets[2].payload, Bytes::from_static(b"x"));
+    }
+
+    #[test]
+    fn trunk_frame_empty() {
+        let frame = TrunkFrame::new();
+        assert!(frame.is_empty());
+        assert_eq!(frame.len(), 0);
+
+        let encoded = frame.encode();
+        // Just the 2-byte count header with value 0.
+        assert_eq!(encoded.len(), 2);
+        assert_eq!(&encoded[..], &[0, 0]);
+
+        let decoded = TrunkFrame::decode(&encoded).unwrap();
+        assert!(decoded.is_empty());
+    }
+
+    #[test]
+    fn trunk_entry_wire_size() {
+        // Each entry overhead must be exactly 4 bytes (2 session_id + 2 len).
+        assert_eq!(TrunkEntry::OVERHEAD, 4);
+
+        // Verify empirically: one entry with a 10-byte payload should produce
+        // 2 (count) + 4 (overhead) + 10 (payload) = 16 bytes total.
+        let mut frame = TrunkFrame::new();
+        frame.push([0xAB, 0xCD], Bytes::from(vec![0u8; 10]));
+        let encoded = frame.encode();
+        assert_eq!(encoded.len(), 2 + 4 + 10);
+    }
+
+    // ---------------------------------------------------------------
+    // MiniHeader / MiniFrameContext tests
+    // ---------------------------------------------------------------
+
+    #[test]
+    fn mini_header_encode_decode() {
+        let mini = MiniHeader {
+            timestamp_delta_ms: 20,
+            payload_len: 160,
+        };
+        let mut buf = BytesMut::new();
+        mini.write_to(&mut buf);
+
+        let mut cursor = &buf[..];
+        let decoded = MiniHeader::read_from(&mut cursor).unwrap();
+        assert_eq!(mini, decoded);
+    }
+
+    #[test]
+    fn mini_header_wire_size() {
+        let mini = MiniHeader {
+            timestamp_delta_ms: 0xFFFF,
+            payload_len: 0xFFFF,
+        };
+        let mut buf = BytesMut::new();
+        mini.write_to(&mut buf);
+        assert_eq!(buf.len(), 4);
+        assert_eq!(MiniHeader::WIRE_SIZE, 4);
+    }
+
+    #[test]
+    fn mini_frame_context_expand() {
+        let baseline = MediaHeader {
+            version: 0,
+            is_repair: false,
+            codec_id: CodecId::Opus24k,
+            has_quality_report: false,
+            fec_ratio_encoded: 10,
+            seq: 100,
+            timestamp: 1000,
+            fec_block: 5,
+            fec_symbol: 0,
+            reserved: 0,
+            csrc_count: 0,
+        };
+
+        let mut ctx = MiniFrameContext::default();
+        ctx.update(&baseline);
+
+        // First expansion
+        let mini1 = MiniHeader {
+            timestamp_delta_ms: 20,
+            payload_len: 80,
+        };
+        let h1 = ctx.expand(&mini1).unwrap();
+        assert_eq!(h1.seq, 101);
+        assert_eq!(h1.timestamp, 1020);
+        assert_eq!(h1.codec_id, CodecId::Opus24k);
+        assert_eq!(h1.fec_block, 5);
+
+        // Second expansion — builds on expanded h1
+        let mini2 = MiniHeader {
+            timestamp_delta_ms: 20,
+            payload_len: 80,
+        };
+        let h2 = ctx.expand(&mini2).unwrap();
+        assert_eq!(h2.seq, 102);
+        assert_eq!(h2.timestamp, 1040);
+    }
+
+    #[test]
+    fn mini_frame_context_no_baseline() {
+        let mut ctx = MiniFrameContext::default();
+        let mini = MiniHeader {
+            timestamp_delta_ms: 20,
+            payload_len: 80,
+        };
+        assert!(ctx.expand(&mini).is_none());
+    }
+
+    #[test]
+    fn full_vs_mini_size_comparison() {
+        // Full frame on wire: 1 byte type tag + 12 byte MediaHeader = 13
+        let full_size = 1 + MediaHeader::WIRE_SIZE;
+        assert_eq!(full_size, 13);
+
+        // Mini frame on wire: 1 byte type tag + 4 byte MiniHeader = 5
+        let mini_size = 1 + MiniHeader::WIRE_SIZE;
+        assert_eq!(mini_size, 5);
+
+        // Verify the constants match expectations
+        assert_eq!(FRAME_TYPE_FULL, 0x00);
+        assert_eq!(FRAME_TYPE_MINI, 0x01);
+    }
+
+    // ---------------------------------------------------------------
+    // encode_compact / decode_compact tests
+    // ---------------------------------------------------------------
+
+    fn make_media_packet(seq: u16, ts: u32, payload: &[u8]) -> MediaPacket {
+        MediaPacket {
+            header: MediaHeader {
+                version: 0,
+                is_repair: false,
+                codec_id: CodecId::Opus24k,
+                has_quality_report: false,
+                fec_ratio_encoded: 10,
+                seq,
+                timestamp: ts,
+                fec_block: 0,
+                fec_symbol: 0,
+                reserved: 0,
+                csrc_count: 0,
+            },
+            payload: Bytes::from(payload.to_vec()),
+            quality_report: None,
+        }
+    }
+
+    #[test]
+    fn mini_frame_encode_decode_sequence() {
+        let mut enc_ctx = MiniFrameContext::default();
+        let mut dec_ctx = MiniFrameContext::default();
+        let mut frames_since_full: u32 = 0;
+
+        let packets: Vec<MediaPacket> = (0..5)
+            .map(|i| make_media_packet(i, i as u32 * 20, b"audio"))
+            .collect();
+
+        for (i, pkt) in packets.iter().enumerate() {
+            let wire = pkt.encode_compact(&mut enc_ctx, &mut frames_since_full);
+
+            if i == 0 {
+                // First frame must be full
+                assert_eq!(wire[0], FRAME_TYPE_FULL, "frame 0 should be FULL");
+            } else {
+                // Subsequent frames should be mini
+                assert_eq!(wire[0], FRAME_TYPE_MINI, "frame {i} should be MINI");
+                // Mini wire: 1 (tag) + 4 (mini header) + payload
+                assert_eq!(wire.len(), 1 + MiniHeader::WIRE_SIZE + pkt.payload.len());
+            }
+
+            let decoded = MediaPacket::decode_compact(&wire, &mut dec_ctx)
+                .unwrap_or_else(|| panic!("decode failed at frame {i}"));
+            assert_eq!(decoded.header.seq, pkt.header.seq);
+            assert_eq!(decoded.header.timestamp, pkt.header.timestamp);
+            assert_eq!(decoded.payload, pkt.payload);
+        }
+    }
+
+    #[test]
+    fn mini_frame_periodic_full() {
+        let mut ctx = MiniFrameContext::default();
+        let mut frames_since_full: u32 = 0;
+
+        // Encode MINI_FRAME_FULL_INTERVAL + 1 frames. Frame 0 and frame 50
+        // should be FULL, everything in between should be MINI.
+        for i in 0..=MINI_FRAME_FULL_INTERVAL {
+            let pkt = make_media_packet(i as u16, i * 20, b"data");
+            let wire = pkt.encode_compact(&mut ctx, &mut frames_since_full);
+
+            if i == 0 || i == MINI_FRAME_FULL_INTERVAL {
+                assert_eq!(
+                    wire[0], FRAME_TYPE_FULL,
+                    "frame {i} should be FULL"
+                );
+            } else {
+                assert_eq!(
+                    wire[0], FRAME_TYPE_MINI,
+                    "frame {i} should be MINI"
+                );
+            }
+        }
+    }
+
+    #[test]
+    fn mini_frame_disabled() {
+        // Simulate disabled mini-frames by always keeping frames_since_full at 0
+        // (which is what the encoder does when the feature is off).
+        let mut ctx = MiniFrameContext::default();
+
+        for i in 0..10u16 {
+            let pkt = make_media_packet(i, i as u32 * 20, b"payload");
+            // When mini-frames are disabled, the encoder always passes
+            // frames_since_full = 0 equivalent by never using encode_compact.
+            // We test the raw path: frames_since_full forced to 0 every time.
+            let mut frames_since_full: u32 = 0;
+            let wire = pkt.encode_compact(&mut ctx, &mut frames_since_full);
+            assert_eq!(wire[0], FRAME_TYPE_FULL, "frame {i} should be FULL when disabled");
+        }
+    }
 }

crates/wzp-proto/src/quality.rs

@@ -1,4 +1,5 @@
 use std::collections::VecDeque;
+use std::time::{Duration, Instant};
 
 use crate::packet::QualityReport;
 use crate::traits::QualityController;
@@ -24,24 +25,71 @@ impl Tier {
         }
     }
 
-    /// Determine which tier a quality report belongs to.
+    /// Determine which tier a quality report belongs to (default/WiFi thresholds).
     pub fn classify(report: &QualityReport) -> Self {
+        Self::classify_with_context(report, NetworkContext::Unknown)
+    }
+
+    /// Classify with network-context-aware thresholds.
+    pub fn classify_with_context(report: &QualityReport, context: NetworkContext) -> Self {
         let loss = report.loss_percent();
         let rtt = report.rtt_ms();
 
-        if loss > 40.0 || rtt > 600 {
-            Self::Catastrophic
-        } else if loss > 10.0 || rtt > 400 {
-            Self::Degraded
-        } else {
-            Self::Good
+        match context {
+            NetworkContext::CellularLte
+            | NetworkContext::Cellular5g
+            | NetworkContext::Cellular3g => {
+                // Tighter thresholds for cellular networks
+                if loss > 25.0 || rtt > 500 {
+                    Self::Catastrophic
+                } else if loss > 8.0 || rtt > 300 {
+                    Self::Degraded
+                } else {
+                    Self::Good
+                }
+            }
+            NetworkContext::WiFi | NetworkContext::Unknown => {
+                // Original thresholds
+                if loss > 40.0 || rtt > 600 {
+                    Self::Catastrophic
+                } else if loss > 10.0 || rtt > 400 {
+                    Self::Degraded
+                } else {
+                    Self::Good
+                }
+            }
         }
     }
+
+    /// Return the next lower (worse) tier, or None if already at the worst.
+    pub fn downgrade(self) -> Option<Tier> {
+        match self {
+            Self::Good => Some(Self::Degraded),
+            Self::Degraded => Some(Self::Catastrophic),
+            Self::Catastrophic => None,
+        }
+    }
+}
+
+/// Describes the network transport type for context-aware quality decisions.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum NetworkContext {
+    WiFi,
+    CellularLte,
+    Cellular5g,
+    Cellular3g,
+    Unknown,
+}
+
+impl Default for NetworkContext {
+    fn default() -> Self {
+        Self::Unknown
+    }
 }
 
 /// Adaptive quality controller with hysteresis to prevent tier flapping.
 ///
-/// - Downgrade: 3 consecutive reports in a worse tier
+/// - Downgrade: 3 consecutive reports in a worse tier (2 on cellular)
 /// - Upgrade: 10 consecutive reports in a better tier
 pub struct AdaptiveQualityController {
     current_tier: Tier,
@@ -54,14 +102,26 @@ pub struct AdaptiveQualityController {
     history: VecDeque<QualityReport>,
     /// Whether the profile was manually forced (disables adaptive logic).
     forced: bool,
+    /// Current network context for threshold selection.
+    network_context: NetworkContext,
+    /// FEC boost expiry time (set during network handoff).
+    fec_boost_until: Option<Instant>,
+    /// FEC boost amount to add during handoff recovery window.
+    fec_boost_amount: f32,
 }
 
 /// Threshold for downgrading (fast reaction to degradation).
 const DOWNGRADE_THRESHOLD: u32 = 3;
+/// Threshold for downgrading on cellular networks (even faster).
+const CELLULAR_DOWNGRADE_THRESHOLD: u32 = 2;
 /// Threshold for upgrading (slow, cautious improvement).
 const UPGRADE_THRESHOLD: u32 = 10;
 /// Maximum history window size.
 const HISTORY_SIZE: usize = 20;
+/// Default FEC boost amount during handoff recovery.
+const DEFAULT_FEC_BOOST: f32 = 0.2;
+/// Duration of FEC boost after a network handoff.
+const FEC_BOOST_DURATION_SECS: u64 = 10;
 
 impl AdaptiveQualityController {
     pub fn new() -> Self {
@@ -72,6 +132,9 @@ impl AdaptiveQualityController {
             consecutive_down: 0,
             history: VecDeque::with_capacity(HISTORY_SIZE),
             forced: false,
+            network_context: NetworkContext::default(),
+            fec_boost_until: None,
+            fec_boost_amount: DEFAULT_FEC_BOOST,
         }
     }
 
@@ -80,6 +143,69 @@ impl AdaptiveQualityController {
         self.current_tier
     }
 
+    /// Get the current network context.
+    pub fn network_context(&self) -> NetworkContext {
+        self.network_context
+    }
+
+    /// Signal a network transport change (e.g., WiFi to cellular handoff).
+    ///
+    /// When switching from WiFi to any cellular type, this preemptively
+    /// downgrades one quality tier and activates a temporary FEC boost.
+    pub fn signal_network_change(&mut self, new_context: NetworkContext) {
+        let old = self.network_context;
+        self.network_context = new_context;
+
+        let new_is_cellular = matches!(
+            new_context,
+            NetworkContext::CellularLte | NetworkContext::Cellular5g | NetworkContext::Cellular3g
+        );
+
+        // If switching from WiFi to cellular, preemptively downgrade one tier
+        if old == NetworkContext::WiFi && new_is_cellular {
+            if let Some(lower_tier) = self.current_tier.downgrade() {
+                self.current_tier = lower_tier;
+                self.current_profile = lower_tier.profile();
+            }
+            // Reset counters to avoid stale hysteresis state
+            self.consecutive_up = 0;
+            self.consecutive_down = 0;
+            // Un-force so adaptive logic resumes
+            self.forced = false;
+        }
+
+        // Activate FEC boost for any network change
+        self.fec_boost_until = Some(Instant::now() + Duration::from_secs(FEC_BOOST_DURATION_SECS));
+    }
+
+    /// Returns the FEC boost amount if within the handoff recovery window, 0.0 otherwise.
+    ///
+    /// Callers should add this to their base FEC ratio during the boost window.
+    pub fn fec_boost(&self) -> f32 {
+        if let Some(until) = self.fec_boost_until {
+            if Instant::now() < until {
+                return self.fec_boost_amount;
+            }
+        }
+        0.0
+    }
+
+    /// Reset the hysteresis counters.
+    pub fn reset_counters(&mut self) {
+        self.consecutive_up = 0;
+        self.consecutive_down = 0;
+    }
+
+    /// Get the effective downgrade threshold based on network context.
+    fn downgrade_threshold(&self) -> u32 {
+        match self.network_context {
+            NetworkContext::CellularLte
+            | NetworkContext::Cellular5g
+            | NetworkContext::Cellular3g => CELLULAR_DOWNGRADE_THRESHOLD,
+            _ => DOWNGRADE_THRESHOLD,
+        }
+    }
+
     fn try_transition(&mut self, observed_tier: Tier) -> Option<QualityProfile> {
         if observed_tier == self.current_tier {
             self.consecutive_up = 0;
@@ -96,7 +222,7 @@ impl AdaptiveQualityController {
         if is_worse {
             self.consecutive_up = 0;
             self.consecutive_down += 1;
-            if self.consecutive_down >= DOWNGRADE_THRESHOLD {
+            if self.consecutive_down >= self.downgrade_threshold() {
                 self.current_tier = observed_tier;
                 self.current_profile = observed_tier.profile();
                 self.consecutive_down = 0;
@@ -142,7 +268,7 @@ impl QualityController for AdaptiveQualityController {
             return None;
         }
 
-        let observed = Tier::classify(report);
+        let observed = Tier::classify_with_context(report, self.network_context);
         self.try_transition(observed)
     }
 
@@ -246,4 +372,110 @@ mod tests {
         assert_eq!(Tier::classify(&make_report(50.0, 200)), Tier::Catastrophic);
         assert_eq!(Tier::classify(&make_report(5.0, 700)), Tier::Catastrophic);
     }
+
+    // ---------------------------------------------------------------
+    // Network context tests
+    // ---------------------------------------------------------------
+
+    #[test]
+    fn cellular_tighter_thresholds() {
+        // 12% loss: Good on WiFi, Degraded on cellular
+        let report = make_report(12.0, 200);
+        assert_eq!(
+            Tier::classify_with_context(&report, NetworkContext::WiFi),
+            Tier::Degraded
+        );
+        assert_eq!(
+            Tier::classify_with_context(&report, NetworkContext::CellularLte),
+            Tier::Degraded
+        );
+
+        // 9% loss: Good on WiFi, Degraded on cellular
+        let report = make_report(9.0, 200);
+        assert_eq!(
+            Tier::classify_with_context(&report, NetworkContext::WiFi),
+            Tier::Good
+        );
+        assert_eq!(
+            Tier::classify_with_context(&report, NetworkContext::CellularLte),
+            Tier::Degraded
+        );
+
+        // 30% loss: Degraded on WiFi, Catastrophic on cellular
+        let report = make_report(30.0, 200);
+        assert_eq!(
+            Tier::classify_with_context(&report, NetworkContext::WiFi),
+            Tier::Degraded
+        );
+        assert_eq!(
+            Tier::classify_with_context(&report, NetworkContext::Cellular3g),
+            Tier::Catastrophic
+        );
+    }
+
+    #[test]
+    fn cellular_rtt_thresholds() {
+        // RTT 350ms: Good on WiFi, Degraded on cellular
+        let report = make_report(2.0, 348); // rtt_4ms rounds so use 348
+        assert_eq!(
+            Tier::classify_with_context(&report, NetworkContext::WiFi),
+            Tier::Good
+        );
+        assert_eq!(
+            Tier::classify_with_context(&report, NetworkContext::CellularLte),
+            Tier::Degraded
+        );
+    }
+
+    #[test]
+    fn cellular_faster_downgrade() {
+        let mut ctrl = AdaptiveQualityController::new();
+        ctrl.signal_network_change(NetworkContext::CellularLte);
+        // Reset tier back to Good for testing downgrade threshold
+        ctrl.current_tier = Tier::Good;
+        ctrl.current_profile = Tier::Good.profile();
+
+        // On cellular, downgrade threshold is 2 instead of 3
+        let bad = make_report(50.0, 200);
+        assert!(ctrl.observe(&bad).is_none()); // 1st bad
+        let result = ctrl.observe(&bad); // 2nd bad — should trigger on cellular
+        assert!(result.is_some());
+    }
+
+    #[test]
+    fn signal_network_change_preemptive_downgrade() {
+        let mut ctrl = AdaptiveQualityController::new();
+        assert_eq!(ctrl.tier(), Tier::Good);
+
+        // Switch from WiFi to cellular
+        ctrl.network_context = NetworkContext::WiFi;
+        ctrl.signal_network_change(NetworkContext::CellularLte);
+
+        // Should have downgraded one tier: Good -> Degraded
+        assert_eq!(ctrl.tier(), Tier::Degraded);
+    }
+
+    #[test]
+    fn signal_network_change_fec_boost() {
+        let mut ctrl = AdaptiveQualityController::new();
+        assert_eq!(ctrl.fec_boost(), 0.0);
+
+        ctrl.signal_network_change(NetworkContext::CellularLte);
+
+        // FEC boost should be active
+        assert!(ctrl.fec_boost() > 0.0);
+        assert_eq!(ctrl.fec_boost(), DEFAULT_FEC_BOOST);
+    }
+
+    #[test]
+    fn tier_downgrade() {
+        assert_eq!(Tier::Good.downgrade(), Some(Tier::Degraded));
+        assert_eq!(Tier::Degraded.downgrade(), Some(Tier::Catastrophic));
+        assert_eq!(Tier::Catastrophic.downgrade(), None);
+    }
+
+    #[test]
+    fn network_context_default() {
+        assert_eq!(NetworkContext::default(), NetworkContext::Unknown);
+    }
 }

crates/wzp-proto/src/traits.rs

@@ -132,6 +132,14 @@ pub trait CryptoSession: Send + Sync {
     fn overhead(&self) -> usize {
         16 // ChaCha20-Poly1305 tag
     }
+
+    /// Short Authentication String (SAS) — 4-digit code for verbal verification.
+    /// Both peers derive the same code from the shared secret + identity keys.
+    /// If a MITM relay is intercepting, the codes will differ.
+    /// Returns None if SAS was not computed (e.g., relay-side sessions).
+    fn sas_code(&self) -> Option<u32> {
+        None
+    }
 }
 
 /// Key exchange using the Warzone identity model.

crates/wzp-relay/Cargo.toml

@@ -20,11 +20,23 @@ bytes = { workspace = true }
 serde = { workspace = true }
 toml = "0.8"
 anyhow = "1"
+reqwest = { version = "0.12", features = ["json"] }
+serde_json = "1"
 rustls = { version = "0.23", default-features = false, features = ["ring", "std"] }
 quinn = { workspace = true }
+prometheus = "0.13"
+axum = { version = "0.7", default-features = false, features = ["tokio", "http1", "ws"] }
+tower-http = { version = "0.6", features = ["fs"] }
+futures-util = "0.3"
+dirs = "6"
+sha2 = { workspace = true }
+chrono = "0.4"
 
 [[bin]]
 name = "wzp-relay"
 path = "src/main.rs"
 
 [dev-dependencies]
+tokio = { workspace = true, features = ["rt-multi-thread", "macros"] }
+wzp-transport = { workspace = true }
+wzp-client = { workspace = true }