fix(ios audio): pin .voiceChat before override(.none) so earpiece is reachable

Root cause (WebKit source MediaSessionManagerCocoa.mm + Apple DTS, confirmed by
telemetry): WKWebView's WebRTC re-pins the session to mode .videoChat while capture
is active, and .videoChat auto-implies .defaultToSpeaker. So override(.none) reverts
to the mode default = LOUDSPEAKER, and .none alone can never reach the earpiece once
WebKit flips the mode. Our first override won only because .voiceChat was still active.

Fix: for earpiece, setMode(.voiceChat) (its default route IS the receiver) before
override(.none) in both setSpeaker and the debounced route-change re-assert. Add an
accessory guard so a connected BT/wired headset isn't yanked to the built-in receiver.
Reconcile the launch patch: drop .defaultToSpeaker from inject-audio.js so it stops
contradicting the plugin. native marker 1.0.4-mode.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

mobile/plugins/audio-route/ios/Sources/AudioRoutePlugin/AudioRoutePlugin.swift

@@ -5,17 +5,20 @@ import AVFoundation
 // Earpiece <-> speaker toggle for calls. Registered by cap sync as a real Capacitor plugin package, so it
 // shows up as window.Capacitor.Plugins.AudioRoute (an app-embedded class gets stripped in release builds).
 //
-// THE PROBLEM (from device telemetry): overrideOutputAudioPort(.none) routes to the receiver ONCE, then the
-// route latches to the built-in Speaker on every later toggle — even though the category has NO
-// .defaultToSpeaker. That fingerprints WebKit's WebRTC engine re-forcing the loudspeaker AFTER our override.
-// The earlier build ignored .override-reason route changes (to avoid a feedback loop) and so never corrected
-// WebKit's re-force → stuck on speaker → earpiece silent.
+// ROOT CAUSE (WebKit source: Source/WebCore/platform/audio/cocoa/MediaSessionManagerCocoa.mm, confirmed by
+// device telemetry): in a WKWebView the app does NOT own the AVAudioSession — WebKit's media process does.
+// While WebRTC capture is active it re-pins the session to .playAndRecord with mode .videoChat, and
+// .videoChat auto-implies .defaultToSpeaker. overrideOutputAudioPort(.none) means "revert to the mode
+// default", which under .videoChat is the LOUDSPEAKER — so .none alone can never reach the earpiece once
+// WebKit has flipped the mode. Our first .none won only because our .voiceChat mode was still in effect
+// (voiceChat's default route IS the receiver); after WebKit's reconfigure it latched to speaker.
 //
-// THE FIX: re-assert the chosen port AFTER each route change settles (debounced 0.25s), reacting to ALL
-// changes but acting ONLY on a real mismatch — so our own override (which also fires a change) finds the
-// route already correct and does nothing, terminating the loop. Capped per toggle so a persistent adversary
-// can't thrash the audio. A ring-buffer route log (reason -> port) rides back in setSpeaker's result so the
-// telemetry shows the exact battle.
+// THE FIX: for earpiece, set mode .voiceChat FIRST, then overrideOutputAudioPort(.none). overrideOutputAudioPort
+// is a *transient* override (Apple QA1754) that every route/category change resets, and WebKit reconfigures on
+// capture start / setLocalDescription / ICE-connected / renegotiation — so we also observe routeChangeNotification
+// and re-assert (debounced, mismatch-only, capped) after WebKit's change settles. This reactive re-assert is the
+// only lever a WKWebView host has (WebKit's internal RTCAudioSession / useManualAudio is unreachable; WebKit bug
+// 167788 has left the app unable to disable WebKit's session management for 8+ years).
 @objc(AudioRoutePlugin)
 public class AudioRoutePlugin: CAPPlugin, CAPBridgedPlugin {
     public let identifier = "AudioRoutePlugin"
@@ -25,16 +28,22 @@ public class AudioRoutePlugin: CAPPlugin, CAPBridgedPlugin {
     ]
 
     // Bump on every native change so telemetry identifies the running binary unambiguously.
-    private static let nativeTag = "1.0.3-reassert"
+    private static let nativeTag = "1.0.4-mode"
 
     private var wantSpeaker = false          // desired output; source of truth, re-applied on route changes
     private var pending: DispatchWorkItem?   // debounced re-assert
     private var asserts = 0                   // re-assert count this toggle (capped, anti-thrash)
     private var routeLog: [String] = []       // reason->port trail, returned to JS for diagnosis
 
+    // Real external outputs — when one of these is active and the user wants "earpiece", we must NOT force the
+    // built-in receiver (that would yank audio off the user's headset). Only correct the speaker<->receiver axis.
+    private let accessoryPorts: [AVAudioSession.Port] = [
+        .bluetoothHFP, .bluetoothA2DP, .bluetoothLE, .headphones, .headsetMic, .usbAudio, .carAudio, .airPlay
+    ]
+
     override public func load() {
         let session = AVAudioSession.sharedInstance()
-        // NO .defaultToSpeaker — the port is driven explicitly so .none means the earpiece/receiver.
+        // NO .defaultToSpeaker — .voiceChat's default route is the receiver, so the port override decides output.
         try? session.setCategory(.playAndRecord, mode: .voiceChat, options: [.allowBluetooth, .allowBluetoothA2DP])
         try? session.setActive(true)
         NotificationCenter.default.addObserver(self, selector: #selector(routeChanged(_:)),
@@ -71,15 +80,31 @@ public class AudioRoutePlugin: CAPPlugin, CAPBridgedPlugin {
         DispatchQueue.main.asyncAfter(deadline: .now() + 0.25, execute: work)
     }
 
+    // Nudge the route toward the desired output, acting ONLY on a real built-in speaker<->receiver mismatch so
+    // our own override (which itself fires a route change) self-terminates instead of looping.
     private func applyRoute() {
         guard asserts < 6 else { log("cap"); return }   // anti-thrash: give up rather than ping-pong forever
-        let session = AVAudioSession.sharedInstance()
-        let onSpeaker = session.currentRoute.outputs.contains { $0.portType == .builtInSpeaker }
+        let s = AVAudioSession.sharedInstance()
+        let outs = s.currentRoute.outputs
+        let onSpeaker = outs.contains { $0.portType == .builtInSpeaker }
+        let onAccessory = outs.contains { accessoryPorts.contains($0.portType) }
+        if onAccessory && !wantSpeaker { log("skipAcc"); return }   // leave a real headset/BT alone
         do {
-            if wantSpeaker && !onSpeaker {
-                asserts += 1; try session.overrideOutputAudioPort(.speaker); log("assert>spk")
-            } else if !wantSpeaker && onSpeaker {
-                asserts += 1; try session.overrideOutputAudioPort(.none); log("assert>none")
+            if wantSpeaker {
+                if !onSpeaker { asserts += 1; try s.overrideOutputAudioPort(.speaker); log("assert>spk") }
+            } else if onSpeaker {
+                asserts += 1
+                // .none alone can't beat WebKit's .videoChat default (= speaker). Re-pin voiceChat first so the
+                // "revert to default" the override does actually resolves to the RECEIVER.
+                if s.category != .playAndRecord {
+                    try s.setCategory(.playAndRecord, mode: .voiceChat, options: [.allowBluetooth, .allowBluetoothA2DP])
+                    log("repinCat")
+                } else if s.mode != .voiceChat {
+                    try s.setMode(.voiceChat)
+                    log("repinMode")
+                }
+                try s.overrideOutputAudioPort(.none)
+                log("assert>rcv")
             }
         } catch { log("assertErr") }
     }
@@ -100,9 +125,14 @@ public class AudioRoutePlugin: CAPPlugin, CAPBridgedPlugin {
     @objc func setSpeaker(_ call: CAPPluginCall) {
         wantSpeaker = call.getBool("on") ?? true
         asserts = 0
-        let session = AVAudioSession.sharedInstance()
+        let s = AVAudioSession.sharedInstance()
         do {
-            try session.overrideOutputAudioPort(wantSpeaker ? .speaker : .none)
+            // Earpiece: pin .voiceChat first so the very first press is correct even if WebKit already flipped
+            // the mode to .videoChat. Speaker: override(.speaker) works under any mode, no mode change needed.
+            if !wantSpeaker && s.category == .playAndRecord && s.mode != .voiceChat {
+                try s.setMode(.voiceChat)
+            }
+            try s.overrideOutputAudioPort(wantSpeaker ? .speaker : .none)
             let out = diag(wantSpeaker ? "speaker" : "earpiece")
             routeLog.removeAll()   // reset the trail; next toggle reports what happened in between
             call.resolve(out)

mobile/plugins/audio-route/package.json

@@ -1,6 +1,6 @@
 {
   "name": "audio-route",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "iOS earpiece/speaker audio route toggle for Biz Connect",
   "main": "dist/plugin.cjs.js",
   "module": "dist/esm/index.js",