@mentra/glasses-media 3.2.0-dev.225 → 3.2.0-dev.227

package/README.md

@@ -1,6 +1,6 @@
 # Glasses media transport
 
-Native receivers and network helpers shared by media publishers. This library has no ACS SDK dependency. `acs-meeting` is its first consumer; a future Cloudflare publisher can consume the same decoded video and PCM without joining a meeting.
+Native receivers, WHIP publishers and network helpers shared by the Mentra App. This library has no ACS SDK dependency. ACS consumes decoded media for calls; managed WebRTC streams feed the same decoded video and PCM to `PhoneWhipPublisher`.
 
 - Android: the existing `GlassesMediaSource`, local WHIP and WHEP receivers, scoped SoftAP networking, decoded I420/PCM delivery, and transport diagnostics moved here. The ACS session and raw outgoing streams remain in `acs-meeting`.
 - iOS: `DecodedGlassesMediaSource` delivers `CVPixelBuffer` video and interleaved PCM16. `LocalWhipIngestSource` answers the glasses' existing WHIP client; `WhepVideoSource` retains the cloud subscription path.
@@ -12,7 +12,7 @@ The publisher owns its outgoing encoders, audio policy, and destination. Receive
 
 The host signs in, enables the glasses hotspot, joins it, prepares the receiver and publisher, then tells the glasses to publish to the returned `ingestUrl`. A successful listener bind is not a live stream: `live` requires a decoded video frame. iOS waits for full ICE gathering and returns only actual host candidates on the hotspot interface. Requests and queued media are bounded.
 
-Stop the glasses publisher before stopping the receiver and releasing the network. Await `LocalWhipIngestSource.stop(completion:)` before reusing resources. It cancels pending offers, closes the peer and HTTP listener, and drains teardown before completing. A local source must not silently restart onto a new port; the host must coordinate any new URL with the glasses. WHEP can rebuild its existing URL.
+Stop the glasses publisher before stopping the receiver and releasing the network. Await `LocalWhipIngestSource.stop(completion:)` before reusing resources on iOS. Android owners discarding a receiver use `close()` to drain HTTP negotiation and release its retained factory and EGL resources. It cancels pending offers, closes the peer and HTTP listener, and drains teardown before completing. A local source must not silently restart onto a new port; the host must coordinate any new URL with the glasses. WHEP can rebuild its existing URL.
 
 ## Verification
 
@@ -32,4 +32,20 @@ xcodebuild -project mobile/ios/Pods/Pods.xcodeproj -target AcsMeeting \
 
 Before merging/releasing, exercise iPhone + glasses: first-use local-network permission and hotspot prompts; join/admit/mute/leave; music/camera sounds; rapid Start/Cancel/Start during sign-in, hotspot join, and WHIP negotiation; hotspot loss; repeated joins; screen-off/background streaming; and a sustained call while measuring latency, audio/video alignment, and thermal behavior. Screen-off operation and background gallery transfers already exist in the Mentra App; these checks qualify the new media pipeline. A simulator build and loopback HTTP tests cannot establish physical Wi-Fi/cellular routing or camera behavior.
 
-Cloudflare publishing and changes to RTMP/SRT routes are outside this library extraction.
+## Managed WebRTC relay
+
+`PhoneStreamCoordinator` provisions Cloudflare and owns subscribers for the entire route:
+
+```text
+Glasses -- WHIP over SoftAP --> shared receiver -- decoded video/PCM --> phone WHIP publisher --> Cloudflare
+```
+
+Only `ingest: "whip"` selects this route. Default SRT and explicit RTMP continue publishing directly from the glasses. WHIP never falls back to SRT/RTMP when Cloudflare omits its WHIP URL. The phone needs mobile data; the glasses need no internet Wi-Fi credentials. Livestreamer's Stream Here path skips its glasses Wi-Fi setup gate accordingly.
+
+`MentraGlassesMediaRelay.prepare` joins the persistent hotspot, prepares both native peers, and returns a local WHIP URL for the BLE start command. Cloudflare credentials stay on the phone. Video queues hold at most one frame; decoded PCM is downmixed/resampled into a bounded 200ms, 48kHz mono queue. WebRTC re-encodes both tracks. No phone microphone is captured. Android uses the WebRTC library's external AudioRecord buffer mode; iOS uses a custom `RTCAudioDevice`.
+
+Android's process-wide network inventory exposes both the scoped hotspot and real cellular handles during a relay. Per-factory masks keep the receiver on Wi-Fi and the publisher off Wi-Fi; signaling also uses the cellular network's socket factory and DNS. ACS retains its existing hotspot-only inventory. iOS uses corresponding per-factory masks after validating the cellular default route.
+
+An attempt-specific ID isolates late callbacks and glasses status. Reconnect tears down the glasses publisher, both phone peers and hotspot before rebuilding against the same provisioned input. Three retries bound consecutive failures; a minute of stable streaming renews the retry budget. Last-subscriber stop cancels startup/backoff, awaits native cleanup and disables the hotspot. Failed cleanup retains ownership and can be retried by stop. BLE-unreachable stop/hotspot commands are deferred until reconnection. ACS and managed streaming share a hotspot reservation. Native media queues keep running when the UI is backgrounded; Android holds a partial wake lock and uses the engine's background timers for retry/readiness.
+
+Device qualification for this outgoing pipeline must include Android and iPhone: audio/video playback on the provisioned WHEP URL, mute/video-only capture, last-subscriber stop, cancellation at each setup step, cellular/hotspot/BLE loss and recovery, repeated starts, screen-off/background operation and a sustained thermal/audio-sync run. Unit tests and platform compilation cover lifecycle/format contracts; they do not establish those hardware results.

package/android/src/main/AndroidManifest.xml

@@ -3,4 +3,5 @@
   <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
   <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
   <uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
+  <uses-permission android:name="android.permission.WAKE_LOCK" />
 </manifest>

package/android/src/main/java/com/mentra/glassesmedia/GlassesMediaRelayModule.kt

@@ -0,0 +1,113 @@
+package com.mentra.glassesmedia
+
+import android.content.Intent
+import android.os.Handler
+import android.os.Looper
+import android.os.PowerManager
+import android.provider.Settings
+import com.mentra.glassesmedia.network.*
+import com.mentra.glassesmedia.publisher.PhoneWhipPublisher
+import com.mentra.glassesmedia.source.*
+import expo.modules.kotlin.Promise
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
+import java.util.concurrent.Executors
+
+/** Native resources for one coordinator-owned relay attempt. All transitions use one executor. */
+class GlassesMediaRelayModule : Module() {
+  private val worker = Executors.newSingleThreadExecutor()
+  private var activeId: String? = null
+  private var network: ScopedSoftApNetwork? = null
+  private var internet: InternetHold? = null
+  private var source: LocalWhipIngestSource? = null
+  private var publisher: PhoneWhipPublisher? = null
+  private var wakeLock: PowerManager.WakeLock? = null
+
+  override fun definition() = ModuleDefinition {
+    Name("MentraGlassesMediaRelay")
+    Events("onRelayState")
+
+    AsyncFunction("prepare") { options: Map<String, Any?>, promise: Promise ->
+      worker.execute {
+        try {
+          check(activeId == null) { "Previous relay has not stopped" }
+          val id = requireNotNull(options["attemptId"] as? String)
+          val endpoint = requireNotNull(options["ingestUrl"] as? String)
+          val ssid = requireNotNull(options["ssid"] as? String)
+          val password = requireNotNull(options["password"] as? String)
+          val context = requireNotNull(appContext.reactContext).applicationContext
+          activeId = id
+          val hold = InternetHold(context).also { internet = it }
+          check(hold.awaitValidatedCellular().validated) { "Turn on phone mobile data to stream through the glasses hotspot" }
+          val scoped = ScopedSoftApNetwork(context).also { network = it }
+          if (!scoped.isWifiEnabled()) {
+            Handler(Looper.getMainLooper()).post {
+              appContext.currentActivity?.startActivity(Intent(Settings.Panel.ACTION_WIFI))
+            }
+            check(scoped.awaitWifiEnabled()) { "Phone Wi-Fi is disabled" }
+            Thread.sleep(ScopedSoftApNetwork.WIFI_ENABLE_SETTLE_MS)
+          }
+          val listener = object : ScopedSoftApNetwork.Listener {
+            override fun onAvailable(network: android.net.Network, localIpv4: String) = Unit
+            override fun onLost(error: ScopedNetworkError) { emit(id, "failed", "Glasses hotspot connection was lost") }
+          }
+          try {
+            scoped.join(ssid, password, listener)
+          } catch (error: ScopedNetworkError.Unavailable) {
+            // Same recovery as ACS: the first specifier can reject while leaving office Wi-Fi.
+            Thread.sleep(ScopedSoftApNetwork.UNAVAILABLE_RETRY_SETTLE_MS)
+            scoped.join(ssid, password, listener)
+          }
+          ScopedNetworkChangeDetector.registerRelayNetwork(scoped)
+          val outgoing = PhoneWhipPublisher(context, endpoint, options["captureAudio"] != false,
+            (options["bitrate"] as? Number)?.toInt() ?: 2_000_000) { state, reason -> emit(id, state, reason) }
+          publisher = outgoing
+          val incoming = LocalWhipIngestSource(context, VideoFrameListener(outgoing::onVideoFrame),
+            PcmListener(outgoing::onPcm), scopedNetwork = scoped)
+          source = incoming
+          incoming.setStateListener { state, reason ->
+            if (state == SourceState.FAILED) emit(id, "failed", "Glasses receiver: $reason")
+          }
+          incoming.setPcmDeliveryEnabled(options["captureAudio"] != false)
+          incoming.start(SourceConfig("", SourceKind.SOFTAP, scoped.localIpv4()))
+          wakeLock = context.getSystemService(PowerManager::class.java)
+            .newWakeLock(PowerManager.PARTIAL_WAKE_LOCK, "Mentra:managed-relay").apply { acquire() }
+          outgoing.start()
+          promise.resolve(requireNotNull(incoming.ingestUrl))
+        } catch (error: Exception) {
+          // The owner still calls stop: preserve ownership until every acquired resource is gone.
+          promise.reject("RELAY_PREPARE_FAILED", error.message, error)
+        }
+      }
+    }
+
+    AsyncFunction("stop") { attemptId: String, promise: Promise ->
+      worker.execute {
+        try {
+          if (activeId == attemptId) cleanup()
+          promise.resolve(null)
+        } catch (error: Exception) { promise.reject("RELAY_STOP_FAILED", error.message, error) }
+      }
+    }
+
+    OnDestroy { worker.execute { runCatching { cleanup() }; worker.shutdown() } }
+  }
+
+  private fun emit(id: String, state: String, reason: String) {
+    sendEvent("onRelayState", mapOf("attemptId" to id, "state" to state, "reason" to reason))
+  }
+
+  private fun cleanup() {
+    source?.setStateListener(null)
+    // Try every cleanup even if one fails. Keep the slot occupied on any failure.
+    var failure: Exception? = null
+    fun step(action: () -> Unit) { try { action() } catch (e: Exception) { failure = failure ?: e } }
+    step { source?.close(); source = null }
+    step { publisher?.close(); publisher = null }
+    step { network?.let { it.release(); ScopedNetworkChangeDetector.releaseRelayNetwork(it) }; network = null }
+    step { internet?.close(); internet = null }
+    step { wakeLock?.let { if (it.isHeld) it.release() }; wakeLock = null }
+    failure?.let { throw it }
+    activeId = null
+  }
+}

package/android/src/main/java/com/mentra/glassesmedia/network/ScopedNetworkChangeDetector.kt

@@ -142,7 +142,7 @@ internal constructor(
             )
         }
 
-        val merged = mergeScopedNetwork(stock, scoped)
+        val merged = mergeScopedNetwork(stock, scoped, registry.includesInternet())
         lastPublished = snapshotOf(merged)
         SoftApTrace.stage(
             "webrtc_network_inventory",
@@ -235,12 +235,39 @@ internal constructor(
             context: Context,
             scoped: () -> ScopedInterface?,
         ): Wired {
-            val filter = ScopedNetworkObserver(downstream, scoped)
+            val filter = ScopedNetworkObserver(downstream, scoped) { registry.includesInternet() }
             return Wired(NetworkMonitorAutoDetect(filter, context), scoped, filter)
         }
 
         @JvmStatic
         fun install(scopedNetworkSupplier: () -> ScopedSoftApNetwork?) {
+            registry.registerAcs(scopedNetworkSupplier)
+            installMonitor()
+        }
+
+        private val registry = ScopedNetworkRegistry<ScopedSoftApNetwork>()
+
+        /** Receiver fallback for standalone users; never replaces ACS's live supplier. */
+        @JvmStatic
+        fun registerReceiverNetwork(network: ScopedSoftApNetwork) {
+            registry.registerReceiver(network)
+            installMonitor()
+        }
+
+        @JvmStatic
+        fun releaseReceiverNetwork(network: ScopedSoftApNetwork) { registry.releaseReceiver(network) }
+
+        /** Keep real internet handles visible for the outgoing peer; each factory masks its leg. */
+        @JvmStatic
+        fun registerRelayNetwork(network: ScopedSoftApNetwork) {
+            registry.registerRelay(network)
+            installMonitor()
+        }
+
+        @JvmStatic
+        fun releaseRelayNetwork(network: ScopedSoftApNetwork) { registry.releaseRelay(network) }
+
+        private fun installMonitor() {
             val monitor = NetworkMonitor.getInstance()
             // A live detector was built by an earlier factory (or the stock one) and will not be
             // replaced until monitoring restarts; say so in the trace so a missing host candidate
@@ -252,7 +279,7 @@ internal constructor(
             monitor.setNetworkChangeDetectorFactory { observer, context ->
                 val wired =
                     wire(observer, context) {
-                        scopedNetworkSupplier()?.let { resolveScopedInterface(context, it) }
+                        registry.current()?.let { resolveScopedInterface(context, it) }
                     }
                 ScopedNetworkChangeDetector(wired.delegate, wired.scoped, wired.observer)
             }
@@ -300,9 +327,12 @@ internal constructor(
         fun mergeScopedNetwork(
             detected: List<NetworkChangeDetector.NetworkInformation>?,
             scoped: ScopedInterface?,
+            includeInternet: Boolean = false,
         ): List<NetworkChangeDetector.NetworkInformation> {
             val hotspot = scoped?.let { toNetworkInformation(it) } ?: return detected.orEmpty()
-            return listOf(hotspot)
+            return if (includeInternet) {
+                detected.orEmpty().filter { it.handle != hotspot.handle && it.name != hotspot.name } + hotspot
+            } else listOf(hotspot)
         }
 
         /** Dotted-quad for the inventory trace. */

package/android/src/main/java/com/mentra/glassesmedia/network/ScopedNetworkObserver.kt

@@ -33,6 +33,7 @@ import org.webrtc.NetworkChangeDetector
 internal class ScopedNetworkObserver(
     private val downstream: NetworkChangeDetector.Observer,
     private val scoped: () -> ScopedNetworkChangeDetector.ScopedInterface?,
+    private val includeInternet: () -> Boolean = { false },
 ) : NetworkChangeDetector.Observer() {
 
     private val lock = Any()
@@ -114,17 +115,20 @@ internal class ScopedNetworkObserver(
     }
 
     override fun onConnectionTypeChanged(connectionType: NetworkChangeDetector.ConnectionType) {
-        if (scoped() != null) {
+        if (scoped() != null && !includeInternet()) {
             downstream.onConnectionTypeChanged(NetworkChangeDetector.ConnectionType.CONNECTION_WIFI)
             return
         }
-        restore()
+        if (scoped() == null) restore()
         downstream.onConnectionTypeChanged(connectionType)
     }
 
     override fun onNetworkConnect(networkInfo: NetworkChangeDetector.NetworkInformation) {
         if (scoped() != null) {
-            synchronized(lock) { stock[networkInfo.handle] = networkInfo }
+            synchronized(lock) {
+                stock[networkInfo.handle] = networkInfo
+                if (includeInternet()) publish(ScopedNetworkChangeDetector.mergeScopedNetwork(stock.values.toList(), scoped(), true))
+            }
             SoftApTrace.stage(
                 "webrtc_stock_connect_suppressed",
                 "name" to networkInfo.name,
@@ -141,7 +145,10 @@ internal class ScopedNetworkObserver(
 
     override fun onNetworkDisconnect(networkHandle: Long) {
         if (scoped() != null) {
-            synchronized(lock) { stock.remove(networkHandle) }
+            synchronized(lock) {
+                stock.remove(networkHandle)
+                if (includeInternet()) publish(ScopedNetworkChangeDetector.mergeScopedNetwork(stock.values.toList(), scoped(), true))
+            }
             return
         }
         restore()

package/android/src/main/java/com/mentra/glassesmedia/network/ScopedNetworkRegistry.kt

@@ -0,0 +1,16 @@
+package com.mentra.glassesmedia.network
+
+/** Separate registrations keep a receiver from replacing the call owner's live network supplier. */
+internal class ScopedNetworkRegistry<T : Any> {
+  private var acs: () -> T? = { null }
+  private var receiver: T? = null
+  private var relay: T? = null
+
+  @Synchronized fun registerAcs(supplier: () -> T?) { acs = supplier }
+  @Synchronized fun registerReceiver(network: T) { receiver = network }
+  @Synchronized fun releaseReceiver(network: T) { if (receiver === network) receiver = null }
+  @Synchronized fun registerRelay(network: T) { relay = network }
+  @Synchronized fun releaseRelay(network: T) { if (relay === network) relay = null }
+  @Synchronized fun current(): T? = relay ?: acs() ?: receiver
+  @Synchronized fun includesInternet(): Boolean = relay != null
+}

package/android/src/main/java/com/mentra/glassesmedia/publisher/PhoneWhipPublisher.kt

@@ -0,0 +1,263 @@
+package com.mentra.glassesmedia.publisher
+
+import android.content.Context
+import android.net.ConnectivityManager
+import android.net.NetworkCapabilities
+import android.os.Handler
+import android.os.HandlerThread
+import com.mentra.glassesmedia.source.I420Planes
+import java.io.IOException
+import java.util.concurrent.CountDownLatch
+import java.util.concurrent.TimeUnit
+import java.util.concurrent.atomic.AtomicBoolean
+import okhttp3.Call
+import okhttp3.Callback
+import okhttp3.HttpUrl
+import okhttp3.HttpUrl.Companion.toHttpUrl
+import okhttp3.MediaType.Companion.toMediaType
+import okhttp3.OkHttpClient
+import okhttp3.Request
+import okhttp3.RequestBody.Companion.toRequestBody
+import okhttp3.Response
+import org.webrtc.*
+import org.webrtc.audio.JavaAudioDeviceModule
+
+/**
+ * ASG WhipStreamingService's full-ICE offer/POST/answer/Location lifecycle, with decoded glasses
+ * tracks instead of camera/mic capture. One instance per attempt; the coordinator owns retries.
+ */
+class PhoneWhipPublisher(
+  private val context: Context,
+  private val endpoint: String,
+  private val captureAudio: Boolean,
+  private val bitrate: Int,
+  private val onState: (String, String) -> Unit,
+) {
+  private val thread = HandlerThread("Mentra WHIP uplink").apply { start() }
+  private val queue = Handler(thread.looper)
+  private val closed = AtomicBoolean(false)
+  private val frameBusy = AtomicBoolean(false)
+  private val closeDone = CountDownLatch(1)
+  @Volatile private var cleanupFailure: Throwable? = null
+  private val pcm = RelayPcmBuffer()
+  private var factory: PeerConnectionFactory? = null
+  private var egl: EglBase? = null
+  private var adm: JavaAudioDeviceModule? = null
+  private var peer: PeerConnection? = null
+  private var videoSource: VideoSource? = null
+  private var videoTrack: VideoTrack? = null
+  private var audioSource: AudioSource? = null
+  private var audioTrack: AudioTrack? = null
+  private var client: OkHttpClient? = null
+  private var resource: HttpUrl? = null
+  private var posted = false
+  private var localSet = false
+  private var connected = false
+  private var failureSent = false
+  private var lastTimestamp = 0L
+  private val disconnectDeadline = Runnable { fail("Phone internet connection was lost") }
+
+  fun start() {
+    queue.post {
+      if (closed.get()) return@post
+      try {
+        val url = endpoint.toHttpUrl()
+        require(url.isHttps) { "Managed WHIP requires HTTPS" }
+        val manager = context.getSystemService(ConnectivityManager::class.java)
+        val internet = manager.allNetworks.firstOrNull { network ->
+          manager.getNetworkCapabilities(network)?.let {
+            it.hasTransport(NetworkCapabilities.TRANSPORT_CELLULAR) &&
+              it.hasCapability(NetworkCapabilities.NET_CAPABILITY_VALIDATED)
+          } == true
+        } ?: error("Phone mobile data is unavailable")
+        client = OkHttpClient.Builder().socketFactory(internet.socketFactory)
+          .dns(object : okhttp3.Dns { override fun lookup(hostname: String) = internet.getAllByName(hostname).toList() })
+          .callTimeout(20, TimeUnit.SECONDS).followRedirects(false).build()
+        PeerConnectionFactory.initialize(PeerConnectionFactory.InitializationOptions.builder(context).createInitializationOptions())
+        egl = EglBase.create()
+        adm = JavaAudioDeviceModule.builder(context)
+          .setInputSampleRate(48_000).setUseStereoInput(false)
+          .setUseHardwareAcousticEchoCanceler(false).setUseHardwareNoiseSuppressor(false)
+          .setAudioBufferCallback { buffer, _, channels, sampleRate, bytes, _ ->
+            if (channels == 1 && sampleRate == 48_000) pcm.read(buffer, bytes)
+            else for (i in 0 until minOf(bytes, buffer.capacity())) buffer.put(i, 0)
+            System.nanoTime()
+          }.createAudioDeviceModule().also {
+            // WebRTC's external-buffer mode: paced callbacks without AudioRecord/microphone.
+            it.setAudioRecordEnabled(false)
+          }
+        factory = PeerConnectionFactory.builder()
+          .setOptions(PeerConnectionFactory.Options().apply {
+            // The receiver keeps Wi-Fi; this peer uses real cellular handles from the inventory.
+            networkIgnoreMask = 2 or 8 or 16 // WIFI, VPN, LOOPBACK
+          })
+          .setAudioDeviceModule(adm)
+          .setVideoEncoderFactory(DefaultVideoEncoderFactory(egl!!.eglBaseContext, true, true))
+          .setVideoDecoderFactory(DefaultVideoDecoderFactory(egl!!.eglBaseContext))
+          .createPeerConnectionFactory()
+        val config = PeerConnection.RTCConfiguration(listOf(
+          PeerConnection.IceServer.builder("stun:stun.cloudflare.com:3478").createIceServer(),
+        )).apply { sdpSemantics = PeerConnection.SdpSemantics.UNIFIED_PLAN }
+        peer = factory!!.createPeerConnection(config, observer) ?: error("Could not create WHIP peer")
+        videoSource = factory!!.createVideoSource(false).also { it.capturerObserver.onCapturerStarted(true) }
+        videoTrack = factory!!.createVideoTrack("glasses-video", videoSource)
+        val transceiver = peer!!.addTransceiver(videoTrack, RtpTransceiver.RtpTransceiverInit(RtpTransceiver.RtpTransceiverDirection.SEND_ONLY))
+        val codecs = factory!!.getRtpSenderCapabilities(MediaStreamTrack.MediaType.MEDIA_TYPE_VIDEO).codecs
+        val h264 = codecs.filter { it.name.equals("H264", ignoreCase = true) }
+        if (h264.isNotEmpty()) transceiver.setCodecPreferences(h264)
+        val parameters = transceiver.sender.parameters
+        parameters.encodings.forEach { it.maxBitrateBps = bitrate.coerceIn(250_000, 12_000_000) }
+        transceiver.sender.parameters = parameters
+        if (captureAudio) {
+          val constraints = MediaConstraints().apply {
+            for (key in listOf("googEchoCancellation", "googNoiseSuppression", "googAutoGainControl"))
+              mandatory.add(MediaConstraints.KeyValuePair(key, "false"))
+          }
+          audioSource = factory!!.createAudioSource(constraints)
+          audioTrack = factory!!.createAudioTrack("glasses-audio", audioSource)
+          peer!!.addTransceiver(audioTrack, RtpTransceiver.RtpTransceiverInit(RtpTransceiver.RtpTransceiverDirection.SEND_ONLY))
+        }
+        peer!!.createOffer(sdpObserver(onCreate = { offer ->
+          peer?.setLocalDescription(sdpObserver(onSet = { localSet = true; maybePost() }), offer)
+        }), MediaConstraints())
+        queue.postDelayed({ if (!connected && !closed.get()) fail("WHIP connection timed out") }, 35_000)
+      } catch (error: Exception) { fail(error.message ?: "WHIP startup failed") }
+    }
+  }
+
+  fun onPcm(bytes: ByteArray, rate: Int, channels: Int) {
+    if (!closed.get() && captureAudio) pcm.push(bytes, rate, channels)
+  }
+
+  fun onVideoFrame(planes: I420Planes) {
+    if (closed.get() || !planes.planesReadable() || !frameBusy.compareAndSet(false, true)) return
+    // Copy before returning to the receiver. At most one frame is waiting on the publisher queue.
+    val buffer = JavaI420Buffer.allocate(planes.width, planes.height)
+    fun copy(src: java.nio.ByteBuffer, srcStride: Int, dst: java.nio.ByteBuffer, dstStride: Int, width: Int, height: Int) {
+      val source = src.duplicate()
+      val base = source.position()
+      val destination = dst.duplicate()
+      for (row in 0 until height) {
+        source.limit(source.capacity()).position(base + row * srcStride)
+        source.limit(base + row * srcStride + width)
+        destination.position(row * dstStride)
+        destination.put(source)
+      }
+    }
+    try {
+      copy(planes.y, planes.strideY, buffer.dataY, buffer.strideY, planes.width, planes.height)
+      copy(planes.u, planes.strideU, buffer.dataU, buffer.strideU, (planes.width + 1) / 2, (planes.height + 1) / 2)
+      copy(planes.v, planes.strideV, buffer.dataV, buffer.strideV, (planes.width + 1) / 2, (planes.height + 1) / 2)
+      if (!queue.post {
+        try {
+          if (!closed.get()) {
+            lastTimestamp = maxOf(System.nanoTime(), lastTimestamp + 1)
+            val frame = VideoFrame(buffer, 0, lastTimestamp)
+            videoSource?.capturerObserver?.onFrameCaptured(frame)
+          }
+        } finally { buffer.release(); frameBusy.set(false) }
+      }) { buffer.release(); frameBusy.set(false) }
+    } catch (_: Exception) { buffer.release(); frameBusy.set(false) }
+  }
+
+  private fun maybePost() {
+    val pc = peer ?: return
+    if (closed.get() || posted || !localSet || pc.iceGatheringState() != PeerConnection.IceGatheringState.COMPLETE) return
+    posted = true
+    val http = client ?: return
+    val request = Request.Builder().url(endpoint)
+      .post(pc.localDescription.description.toRequestBody("application/sdp".toMediaType())).build()
+    http.newCall(request).enqueue(object : Callback {
+      override fun onFailure(call: Call, error: IOException) { queue.post { fail("WHIP signaling failed") } }
+      override fun onResponse(call: Call, response: Response) {
+        response.use {
+          val location = response.header("Location")?.let { request.url.resolve(it) }
+          val answer = response.body?.string().orEmpty()
+          // A late successful POST still owns a remote resource and must DELETE it after stop.
+          if (closed.get()) { location?.let { delete(http, it) }; return }
+          queue.post {
+            if (closed.get()) { location?.let { delete(http, it) }; return@post }
+            if (response.code != 201 || location == null || !location.isHttps || answer.isBlank()) {
+              location?.takeIf { it.isHttps }?.let { delete(http, it) }
+              fail("WHIP server rejected publish (HTTP ${response.code})")
+              return@post
+            }
+            resource = location
+            peer?.setRemoteDescription(sdpObserver(), SessionDescription(SessionDescription.Type.ANSWER, answer))
+          }
+        }
+      }
+    })
+  }
+
+  private fun fail(reason: String) {
+    if (closed.get() || failureSent) return
+    failureSent = true
+    onState("failed", reason)
+  }
+
+  private fun sdpObserver(onCreate: (SessionDescription) -> Unit = {}, onSet: () -> Unit = {}) = object : SdpObserver {
+    override fun onCreateSuccess(sdp: SessionDescription) { queue.post { if (!closed.get()) onCreate(sdp) } }
+    override fun onSetSuccess() { queue.post { if (!closed.get()) onSet() } }
+    override fun onCreateFailure(error: String) { queue.post { fail("WHIP offer failed") } }
+    override fun onSetFailure(error: String) { queue.post { fail("WHIP description failed") } }
+  }
+
+  private val observer = object : PeerConnection.Observer {
+    override fun onIceConnectionChange(state: PeerConnection.IceConnectionState) { queue.post {
+      if (closed.get()) return@post
+      when (state) {
+        PeerConnection.IceConnectionState.CONNECTED, PeerConnection.IceConnectionState.COMPLETED -> {
+          connected = true; queue.removeCallbacks(disconnectDeadline); onState("connected", "Phone publisher connected")
+        }
+        PeerConnection.IceConnectionState.DISCONNECTED -> { queue.removeCallbacks(disconnectDeadline); queue.postDelayed(disconnectDeadline, 10_000) }
+        PeerConnection.IceConnectionState.FAILED -> fail("WHIP ICE failed")
+        else -> Unit
+      }
+    } }
+    override fun onIceGatheringChange(state: PeerConnection.IceGatheringState) { queue.post { maybePost() } }
+    override fun onSignalingChange(state: PeerConnection.SignalingState) = Unit
+    override fun onIceConnectionReceivingChange(receiving: Boolean) = Unit
+    override fun onIceCandidate(candidate: IceCandidate) = Unit
+    override fun onIceCandidatesRemoved(candidates: Array<out IceCandidate>) = Unit
+    override fun onAddStream(stream: MediaStream) = Unit
+    override fun onRemoveStream(stream: MediaStream) = Unit
+    override fun onDataChannel(channel: DataChannel) = Unit
+    override fun onRenegotiationNeeded() = Unit
+    override fun onAddTrack(receiver: RtpReceiver, streams: Array<out MediaStream>) = Unit
+  }
+
+  /** Called off WebRTC threads. Drains callbacks before disposing factory/ADM/encoder resources. */
+  fun close() {
+    if (closed.compareAndSet(false, true)) {
+      queue.post {
+        fun step(action: () -> Unit) {
+          try { action() } catch (error: Throwable) { cleanupFailure = cleanupFailure ?: error }
+        }
+        try {
+          step { resource?.let { url -> client?.let { delete(it, url) } }; resource = null }
+          step { peer?.close() }
+          step { peer?.dispose(); peer = null }
+          step { videoSource?.capturerObserver?.onCapturerStopped() }
+          step { videoTrack?.dispose() }
+          step { videoSource?.dispose() }
+          step { audioTrack?.dispose() }
+          step { audioSource?.dispose() }
+          step { factory?.dispose() }
+          step { adm?.release() }
+          step { egl?.release() }
+        } finally { closeDone.countDown(); thread.quitSafely() }
+      }
+    }
+    check(closeDone.await(20, TimeUnit.SECONDS)) { "Phone publisher cleanup is still pending" }
+    cleanupFailure?.let { throw IllegalStateException("Phone publisher cleanup failed", it) }
+  }
+
+  private fun delete(http: OkHttpClient, url: HttpUrl) {
+    if (!url.isHttps) return
+    http.newCall(Request.Builder().url(url).delete().build()).enqueue(object : Callback {
+      override fun onFailure(call: Call, e: IOException) = Unit
+      override fun onResponse(call: Call, response: Response) { response.close() }
+    })
+  }
+}

package/android/src/main/java/com/mentra/glassesmedia/publisher/RelayPcmBuffer.kt

@@ -0,0 +1,54 @@
+package com.mentra.glassesmedia.publisher
+
+import java.nio.ByteBuffer
+
+/** Bounded 200ms mono PCM queue. Downmix/resample decoded audio to WebRTC's 48kHz clock. */
+class RelayPcmBuffer(private val capacity: Int = 9_600) {
+  private val samples = ShortArray(capacity)
+  private var head = 0
+  private var count = 0
+  private var phase = 0.0
+  private var rate = 0
+  private var channels = 0
+  private var previous: Double? = null
+
+  @Synchronized fun push(bytes: ByteArray, sampleRate: Int, channelCount: Int) {
+    if (sampleRate !in 8_000..192_000 || channelCount !in 1..8) return
+    if (rate != sampleRate || channels != channelCount) {
+      rate = sampleRate; channels = channelCount; phase = 0.0; previous = null
+    }
+    val step = sampleRate / 48_000.0
+    for (frame in 0 until bytes.size / (2 * channelCount)) {
+      var sum = 0.0
+      for (channel in 0 until channelCount) {
+        val offset = (frame * channelCount + channel) * 2
+        sum += ((bytes[offset].toInt() and 255) or (bytes[offset + 1].toInt() shl 8)).toShort()
+      }
+      val value = sum / channelCount
+      val prior = previous
+      if (prior != null) {
+        while (phase < 1.0) {
+          append((prior + (value - prior) * phase).toInt().toShort())
+          phase += step
+        }
+        phase -= 1.0
+      }
+      previous = value
+    }
+  }
+
+  private fun append(value: Short) {
+    if (count == capacity) { head = (head + 1) % capacity; count-- }
+    samples[(head + count) % capacity] = value
+    count++
+  }
+
+  /** Always fills the requested buffer. Underruns are silence, never stale microphone data. */
+  @Synchronized fun read(output: ByteBuffer, byteCount: Int) {
+    for (offset in 0 until minOf(byteCount, output.capacity()) step 2) {
+      val value = if (count > 0) samples[head].also { head = (head + 1) % capacity; count-- } else 0
+      output.put(offset, (value.toInt() and 255).toByte())
+      if (offset + 1 < output.capacity()) output.put(offset + 1, (value.toInt() shr 8).toByte())
+    }
+  }
+}

package/android/src/main/java/com/mentra/glassesmedia/source/LocalWhipIngestSource.kt

@@ -161,6 +161,18 @@ class LocalWhipIngestSource(
     server?.let { runCatching { it.stop() } }
     server = null
     disposePeer()
+    scopedNetwork?.let { ScopedNetworkChangeDetector.releaseReceiverNetwork(it) }
+  }
+
+  /** Terminal teardown for owners that discard this receiver instead of reusing its factory. */
+  fun close() {
+    generation++
+    check(server?.closeAndAwait() != false) { "Local WHIP requests are still draining" }
+    stop()
+    factory?.dispose()
+    factory = null
+    egl?.release()
+    egl = null
   }
 
   // -----------------------------------------------------------------
@@ -226,9 +238,11 @@ class LocalWhipIngestSource(
     peer.setRemoteDescription(
       object : SdpAdapter() {
         override fun onSetSuccess() {
+          if (gen != generation) { answered.countDown(); return }
           peer.createAnswer(
             object : SdpAdapter() {
               override fun onCreateSuccess(sdp: SessionDescription) {
+                if (gen != generation) { answered.countDown(); return }
                 peer.setLocalDescription(
                   object : SdpAdapter() {
                     override fun onSetSuccess() = answered.countDown()
@@ -404,10 +418,9 @@ class LocalWhipIngestSource(
   }
 
   private fun ensureFactory() {
+    // Standalone receivers can supply a fallback without replacing the owner's live registration.
+    scopedNetwork?.let { ScopedNetworkChangeDetector.registerReceiverNetwork(it) }
     if (factory != null) return
-    // Normally already installed by the module at creation; repeating it here is idempotent and
-    // covers a factory built from a code path that bypassed the module (tests, future callers).
-    scopedNetwork?.let { scoped -> ScopedNetworkChangeDetector.install { scoped } }
     PeerConnectionFactory.initialize(
       PeerConnectionFactory.InitializationOptions.builder(context).createInitializationOptions(),
     )