feat(android): Bluetooth audio routing + network change detection + per-arch APK builds
Bluetooth: wire existing AudioRouteManager SCO support through both app variants. Replace binary speaker toggle with 3-way route cycling (Earpiece → Speaker → Bluetooth). Tauri side adds JNI bridge functions (start/stop/query SCO, device availability) and Oboe stream restart. Network awareness: integrate Android ConnectivityManager to detect WiFi/cellular transitions and feed them to AdaptiveQualityController via lock-free AtomicU8 signaling. Enables proactive quality downgrade and FEC boost on network handoffs. Build: add --arch flag to build-tauri-android.sh supporting arm64, armv7, or all (separate per-arch APKs for smaller tester binaries). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Siavash Sameni
@@ -940,3 +940,55 @@ The patch introduces an `MSVC_CL` variable that is true only for real `cl.exe` (
|
||||
This does not affect macOS or Linux builds — on those platforms `MSVC=0` everywhere so the patched logic behaves identically to upstream.
|
||||
|
||||
Upstream tracking: xiph/opus#256, xiph/opus PR #257 (both stale).
|
||||
|
||||
## Network Awareness (Android)
|
||||
|
||||
The adaptive quality controller (`AdaptiveQualityController` in `wzp-proto`) supports proactive network-aware adaptation via `signal_network_change(NetworkContext)`. On Android, this is fed by `NetworkMonitor.kt` which wraps `ConnectivityManager.NetworkCallback`.
|
||||
|
||||
```
|
||||
ConnectivityManager
|
||||
│ onCapabilitiesChanged / onLost
|
||||
▼
|
||||
NetworkMonitor.kt ──classify──► type: Int (WiFi=0, LTE=1, 5G=2, 3G=3)
|
||||
│ onNetworkChanged(type, bw)
|
||||
▼
|
||||
CallViewModel ──► WzpEngine.onNetworkChanged()
|
||||
│ JNI
|
||||
▼
|
||||
jni_bridge.rs
|
||||
│
|
||||
▼
|
||||
EngineState.pending_network_type (AtomicU8, lock-free)
|
||||
│ polled every ~20ms
|
||||
▼
|
||||
recv task: quality_ctrl.signal_network_change(ctx)
|
||||
│
|
||||
├─ WiFi → Cellular: preemptive 1-tier downgrade
|
||||
├─ Any change: 10s FEC boost (+0.2 ratio)
|
||||
└─ Cellular: faster downgrade thresholds (2 vs 3)
|
||||
```
|
||||
|
||||
Cellular generation is approximated from `getLinkDownstreamBandwidthKbps()` to avoid requiring `READ_PHONE_STATE` permission.
|
||||
|
||||
## Audio Routing (Android)
|
||||
|
||||
Both Android app variants support 3-way audio routing: **Earpiece → Speaker → Bluetooth SCO**.
|
||||
|
||||
### Native Kotlin App
|
||||
|
||||
`AudioRouteManager.kt` handles device detection (via `AudioDeviceCallback`), SCO lifecycle (`startBluetoothSco` / `stopBluetoothSco`), and auto-fallback on BT disconnect. `CallViewModel.cycleAudioRoute()` cycles through available routes.
|
||||
|
||||
### Tauri Desktop App
|
||||
|
||||
`android_audio.rs` provides JNI bridges to `AudioManager` for speakerphone and Bluetooth SCO control. After each route change, Oboe streams are stopped and restarted via `spawn_blocking` to force AAudio to reconfigure with the new routing.
|
||||
|
||||
```
|
||||
User tap ──► cycleAudioRoute()
|
||||
│
|
||||
├─ Earpiece: setSpeakerphoneOn(false)
|
||||
├─ Speaker: setSpeakerphoneOn(true)
|
||||
└─ BT SCO: startBluetoothSco() + setBluetoothScoOn(true)
|
||||
│
|
||||
▼
|
||||
Oboe stop + start (~60-400ms)
|
||||
```
|
||||
|
||||
@@ -583,6 +583,49 @@ Signal messages are sent over reliable QUIC streams as length-prefixed JSON:
|
||||
| wzp-client | 30 + 2 integration | Encoder/decoder, quality adapter, silence, drift, sweep |
|
||||
| wzp-web | 2 | Metrics |
|
||||
|
||||
## Audio Routing (Android)
|
||||
|
||||
WarzonePhone supports three audio output routes on Android: **Earpiece**, **Speaker**, and **Bluetooth SCO**. The user cycles through available routes with a single button.
|
||||
|
||||
### Route lifecycle
|
||||
|
||||
1. Call starts → Earpiece (default). `AudioManager.MODE_IN_COMMUNICATION` set by `CallService`.
|
||||
2. User taps route button → cycles to next available route.
|
||||
3. Route change requires Oboe stream restart (~60-400ms) because AAudio silently tears down streams on some OEMs when the routing target changes mid-stream.
|
||||
4. Bluetooth disconnect mid-call → `AudioDeviceCallback.onAudioDevicesRemoved` fires → auto-fallback to Earpiece or Speaker.
|
||||
|
||||
### Bluetooth SCO
|
||||
|
||||
SCO (Synchronous Connection Oriented) is the correct Bluetooth profile for VoIP — it provides bidirectional mono audio at 8/16 kHz with ~30ms latency. A2DP (stereo, high-quality) is unidirectional and adds 100-200ms of buffering, making it unsuitable for real-time voice.
|
||||
|
||||
The deprecated `AudioManager.startBluetoothSco()` API is used because the modern `setCommunicationDevice()` requires API 31+ and our minSdk is 26. The deprecated APIs are functional on all tested devices through API 35.
|
||||
|
||||
### Two app variants
|
||||
|
||||
Both the native Kotlin app (`AudioRouteManager.kt`) and the Tauri app (`android_audio.rs` JNI bridge) call the same `AudioManager` APIs. The native app uses `AudioDeviceCallback` for automatic device detection; the Tauri app queries `getDevices()` on demand.
|
||||
|
||||
## Network Change Response
|
||||
|
||||
The `AdaptiveQualityController` in `wzp-proto` reacts to network transport changes signaled via `signal_network_change(NetworkContext)`:
|
||||
|
||||
| Transition | Response |
|
||||
|-----------|----------|
|
||||
| WiFi → Cellular | Preemptive 1-tier quality downgrade + 10s FEC boost |
|
||||
| Cellular → WiFi | FEC boost only (quality recovers via normal adaptive logic) |
|
||||
| Any change | Reset hysteresis counters to avoid stale state |
|
||||
|
||||
On Android, `NetworkMonitor.kt` wraps `ConnectivityManager.NetworkCallback` and classifies the transport type using bandwidth heuristics (no `READ_PHONE_STATE` needed). The classification is delivered to the Rust engine via JNI → `AtomicU8` → recv task polling — the same lock-free cross-task signaling pattern used for adaptive profile switches.
|
||||
|
||||
### Cellular generation heuristics
|
||||
|
||||
| Downstream bandwidth | Classification |
|
||||
|---------------------|---------------|
|
||||
| >= 100 Mbps | 5G NR |
|
||||
| >= 10 Mbps | LTE |
|
||||
| < 10 Mbps | 3G or worse |
|
||||
|
||||
These thresholds are conservative. Carriers over-report bandwidth, but for VoIP quality decisions the exact generation matters less than the rough category.
|
||||
|
||||
## Build Requirements
|
||||
|
||||
- **Rust** 1.85+ (2024 edition)
|
||||
|
||||
98
docs/PRD-bluetooth-audio.md
Normal file
98
docs/PRD-bluetooth-audio.md
Normal file
@@ -0,0 +1,98 @@
|
||||
# PRD: Bluetooth Audio Routing
|
||||
|
||||
> Phase: Implemented
|
||||
> Status: Ready for testing
|
||||
> Platforms: Android (native Kotlin app + Tauri desktop app)
|
||||
|
||||
## Problem
|
||||
|
||||
WarzonePhone had `AudioRouteManager.kt` with complete Bluetooth SCO support, but it was disconnected from both UIs. Users with Bluetooth headsets had no way to route call audio to them.
|
||||
|
||||
## Solution
|
||||
|
||||
Wire Bluetooth SCO routing end-to-end through both app variants, replacing the binary speaker toggle with a 3-way audio route cycle: **Earpiece → Speaker → Bluetooth**.
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ Native Kotlin App (com.wzp) │
|
||||
│ │
|
||||
│ InCallScreen ──► CallViewModel ──► AudioRouteManager
|
||||
│ (Compose UI) cycleAudioRoute() setSpeaker() │
|
||||
│ "Ear/Spk/BT" audioRoute Flow setBluetoothSco()
|
||||
│ isBluetoothAvailable()
|
||||
└─────────────────────────────────────────────────────┘
|
||||
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ Tauri Desktop App (com.wzp.desktop) │
|
||||
│ │
|
||||
│ main.ts ──► Tauri Commands ──► android_audio.rs │
|
||||
│ cycleAudioRoute() set_bluetooth_sco() JNI calls │
|
||||
│ "Ear/Spk/BT" is_bluetooth_available() │
|
||||
│ get_audio_route() │
|
||||
│ │
|
||||
│ After each route change: Oboe stop + start │
|
||||
│ (spawn_blocking to avoid stalling tokio) │
|
||||
└─────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Components Modified
|
||||
|
||||
### Native Kotlin App
|
||||
|
||||
| File | Change |
|
||||
|------|--------|
|
||||
| `CallViewModel.kt` | Added `audioRoute: StateFlow<AudioRoute>`, `cycleAudioRoute()`, wired `onRouteChanged` callback |
|
||||
| `InCallScreen.kt` | `ControlRow` now takes `audioRoute: AudioRoute` + `onCycleRoute`, displays Ear/Spk/BT with distinct colors |
|
||||
|
||||
### Tauri App
|
||||
|
||||
| File | Change |
|
||||
|------|--------|
|
||||
| `android_audio.rs` | Added `start_bluetooth_sco()`, `stop_bluetooth_sco()`, `is_bluetooth_sco_on()`, `is_bluetooth_available()` |
|
||||
| `lib.rs` | Added `set_bluetooth_sco`, `is_bluetooth_available`, `get_audio_route` Tauri commands |
|
||||
| `main.ts` | Replaced `speakerphoneOn` toggle with `currentAudioRoute` cycling logic |
|
||||
| `style.css` | Added `.bt-on` CSS class (blue-400 highlight) |
|
||||
|
||||
## Audio Route Lifecycle
|
||||
|
||||
1. **Call starts** → route defaults to Earpiece
|
||||
2. **User taps route button** → cycles to next available route
|
||||
3. **Route changes** → AudioManager JNI call + Oboe stream restart (~60-400ms)
|
||||
4. **BT device disconnects mid-call** → `AudioDeviceCallback.onAudioDevicesRemoved` fires → auto-fallback to Earpiece/Speaker
|
||||
5. **Call ends** → route reset to Earpiece, BT SCO stopped
|
||||
|
||||
## Route Cycling Logic
|
||||
|
||||
```
|
||||
Available routes = [Earpiece, Speaker] + [Bluetooth] if SCO device connected
|
||||
|
||||
Tap cycle:
|
||||
Earpiece → Speaker → Bluetooth (if available) → Earpiece → ...
|
||||
|
||||
If BT not available:
|
||||
Earpiece → Speaker → Earpiece → ...
|
||||
```
|
||||
|
||||
## Permissions
|
||||
|
||||
- `BLUETOOTH_CONNECT` (Android 12+) — already in `AndroidManifest.xml`
|
||||
- `MODIFY_AUDIO_SETTINGS` — already in manifest
|
||||
|
||||
## Known Limitations
|
||||
|
||||
- **SCO only** — no A2DP (stereo music profile). SCO is correct for VoIP (bidirectional mono).
|
||||
- **Deprecated APIs** — `startBluetoothSco()`, `isBluetoothScoOn` are deprecated in API 31+ but still functional. Modern replacement `setCommunicationDevice()` requires API 31 and more complex device enumeration. Since minSdk is 26, deprecated path is correct.
|
||||
- **No auto-switch on BT connect** — when a BT device connects mid-call, `onRouteChanged` fires but we don't auto-switch. User must tap the button.
|
||||
|
||||
## Testing
|
||||
|
||||
1. Pair a Bluetooth SCO headset with Android device
|
||||
2. Start call → verify Earpiece is default
|
||||
3. Tap route → Speaker (audio moves to loudspeaker, button shows "Spk")
|
||||
4. Tap route → BT (audio moves to headset, button shows "BT", blue highlight)
|
||||
5. Tap route → Earpiece (audio back to earpiece, button shows "Ear")
|
||||
6. Disconnect BT mid-call → verify auto-fallback
|
||||
7. Verify both app variants work identically
|
||||
8. Verify no audio glitches during route transitions
|
||||
129
docs/PRD-network-awareness.md
Normal file
129
docs/PRD-network-awareness.md
Normal file
@@ -0,0 +1,129 @@
|
||||
# PRD: Network Awareness
|
||||
|
||||
> Phase: Implemented (core path)
|
||||
> Status: Ready for testing
|
||||
> Platform: Android native Kotlin app (com.wzp)
|
||||
|
||||
## Problem
|
||||
|
||||
WarzonePhone's quality controller (`AdaptiveQualityController`) had a `signal_network_change()` API for proactive adaptation to WiFi↔cellular transitions, but nothing called it. Network handoffs during calls were only detected reactively via jitter spikes — by which time the user had already experienced degraded audio.
|
||||
|
||||
## Solution
|
||||
|
||||
Integrate Android's `ConnectivityManager.NetworkCallback` to detect network transport changes in real-time and feed them to the quality controller. This enables:
|
||||
|
||||
1. **Preemptive quality downgrade** when switching from WiFi to cellular
|
||||
2. **FEC boost** (10-second window with +0.2 ratio) after any network change
|
||||
3. **Faster downgrade thresholds** on cellular (2 consecutive reports vs 3 on WiFi)
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────────┐
|
||||
│ Android │
|
||||
│ │
|
||||
│ ConnectivityManager │
|
||||
│ │ NetworkCallback │
|
||||
│ ▼ │
|
||||
│ NetworkMonitor.kt │
|
||||
│ │ onNetworkChanged(type, bandwidthKbps) │
|
||||
│ ▼ │
|
||||
│ CallViewModel.kt ──► WzpEngine.onNetworkChanged() │
|
||||
│ │ JNI │
|
||||
│ ▼ │
|
||||
│ jni_bridge.rs: nativeOnNetworkChanged(handle, type, bw) │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ engine.rs: state.pending_network_type.store(type) │
|
||||
│ │ AtomicU8 (lock-free) │
|
||||
│ ▼ │
|
||||
│ recv task: quality_ctrl.signal_network_change(ctx) │
|
||||
│ │ │
|
||||
│ ├─ Preemptive downgrade (WiFi → cellular) │
|
||||
│ ├─ FEC boost 10s │
|
||||
│ └─ Faster cellular thresholds │
|
||||
└──────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Network Classification
|
||||
|
||||
`NetworkMonitor` classifies the active transport without requiring `READ_PHONE_STATE` permission by using bandwidth heuristics:
|
||||
|
||||
| Downstream Bandwidth | Classification | Rust `NetworkContext` |
|
||||
|----------------------|---------------|----------------------|
|
||||
| N/A (WiFi transport) | WiFi | `WiFi` |
|
||||
| >= 100 Mbps | 5G NR | `Cellular5g` |
|
||||
| >= 10 Mbps | LTE | `CellularLte` |
|
||||
| < 10 Mbps | 3G or worse | `Cellular3g` |
|
||||
| Ethernet | WiFi (equivalent) | `WiFi` |
|
||||
| Network lost | None | `Unknown` |
|
||||
|
||||
## Cross-Task Signaling
|
||||
|
||||
The network type is communicated from the JNI thread to the recv task via `AtomicU8` — the same pattern used for `pending_profile` (adaptive quality profile switches):
|
||||
|
||||
```
|
||||
JNI thread recv task (tokio)
|
||||
│ │
|
||||
│ store(type, Release) │
|
||||
│──────────────────────────────►│
|
||||
│ │ swap(0xFF, Acquire)
|
||||
│ │ if != 0xFF:
|
||||
│ │ quality_ctrl.signal_network_change(ctx)
|
||||
│ │
|
||||
```
|
||||
|
||||
Sentinel value `0xFF` means "no change pending". The recv task polls on every received packet (~20-40ms), so latency is bounded by the inter-packet interval.
|
||||
|
||||
## Components
|
||||
|
||||
### New File
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `android/.../net/NetworkMonitor.kt` | ConnectivityManager callback, transport classification, deduplication |
|
||||
|
||||
### Modified Files
|
||||
|
||||
| File | Change |
|
||||
|------|--------|
|
||||
| `android/.../engine/WzpEngine.kt` | Added `onNetworkChanged()` method + `nativeOnNetworkChanged` external |
|
||||
| `android/.../ui/call/CallViewModel.kt` | Instantiates NetworkMonitor, wires callback, register/unregister lifecycle |
|
||||
| `crates/wzp-android/src/jni_bridge.rs` | Added `Java_com_wzp_engine_WzpEngine_nativeOnNetworkChanged` JNI entry |
|
||||
| `crates/wzp-android/src/engine.rs` | Added `pending_network_type: AtomicU8` to EngineState, recv task polls it |
|
||||
|
||||
### Unchanged (already implemented)
|
||||
|
||||
| File | API |
|
||||
|------|-----|
|
||||
| `crates/wzp-proto/src/quality.rs` | `AdaptiveQualityController::signal_network_change(NetworkContext)` |
|
||||
| `crates/wzp-transport/src/path_monitor.rs` | `PathMonitor::detect_handoff()` (available for future use) |
|
||||
|
||||
## Deferred Work
|
||||
|
||||
### Tauri Desktop App (com.wzp.desktop)
|
||||
|
||||
The Tauri engine doesn't use `AdaptiveQualityController` — quality is resolved once at call start. Adding network monitoring requires first adding adaptive quality to the Tauri call engine, which is a larger change.
|
||||
|
||||
### Mid-Call ICE Re-gathering
|
||||
|
||||
When the device's IP address changes, ideally we should:
|
||||
1. Re-gather local host candidates (`local_host_candidates()`)
|
||||
2. Re-probe STUN (`probe_reflect_addr()`)
|
||||
3. Send updated candidates to the peer (`CandidateUpdate` signal message)
|
||||
4. Attempt new dual-path race for path upgrade
|
||||
|
||||
`NetworkMonitor.onIpChanged` fires on `onLinkPropertiesChanged` — the hook is ready, but the signaling and re-racing logic is not yet implemented.
|
||||
|
||||
## Testing
|
||||
|
||||
1. Build native APK
|
||||
2. Start a call on WiFi
|
||||
3. Verify logcat: `quality controller: network context updated` with `ctx=WiFi`
|
||||
4. Disable WiFi → device falls to cellular
|
||||
5. Verify logcat: `ctx=CellularLte` (or `Cellular5g`/`Cellular3g`)
|
||||
6. Verify FEC boost activates (check quality_ctrl logs)
|
||||
7. Verify preemptive quality downgrade (tier drops one level on WiFi→cellular)
|
||||
8. Re-enable WiFi → verify transition back
|
||||
9. Rapid WiFi toggle (5x in 10s) → verify no crashes, deduplication works
|
||||
10. Airplane mode → verify `onLost` fires with `TYPE_NONE`
|
||||
Reference in New Issue
Block a user