@mentra/glasses-media 3.2.1-dev.314 → 3.3.0-beta.1000

package/README.md

@@ -4,7 +4,7 @@ Native receivers, WHIP publishers and network helpers shared by the Mentra App.
 
 - 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.
-- `GlassesHotspotNetwork` uses the same persistent `NEHotspotConfiguration` join as gallery transfers. Wi-Fi carries the glasses link; cellular carries the call. It verifies the joined SSID and `en0` address, reports network loss, and retains a cancelled join until the uncancellable system callback has been cleaned up.
+- `GlassesHotspotNetwork` owns hotspot association for OTA, gallery transfers and media. iPhone uses persistent `NEHotspotConfiguration`; iOS-on-Mac uses public CoreWLAN in the app process and the standard Location permission needed to identify Wi-Fi networks. Wi-Fi carries the glasses link; cellular carries the call. The owner verifies the requested SSID and actual Wi-Fi interface address, retains that interface for loss checks and ACS binding, and serializes network writers across consumers. Cancellation retains custody until blocking native work and cleanup finish. Cleanup preserves a network the user joined afterward; a failed release rejects and retains ownership for a later cleanup attempt.
 
 The publisher owns its outgoing encoders, audio policy, and destination. Receivers do not open the phone microphone or play the glasses microphone locally. iOS uses a receive-only audio device to drive decoded PCM delivery without changing the app's audio session.
 
@@ -53,6 +53,18 @@ The iOS internet publisher posts its offer on the first server-reflexive candida
 
 Android temporarily lifts the cellular process pin while creating the local WHIP listener, then restores it before starting the outgoing publisher. Otherwise the listener inherits the cellular socket mark and cannot reply to the glasses. The outgoing audio callback supplies its own PCM frame clock: WebRTC's external-recording mode does not pace callbacks and reports zero captured bytes, so the callback fills the entire buffer and waits for the next frame interval without opening the phone microphone.
 
-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.
+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. OTA, Gallery, ACS and managed streaming share one hotspot reservation before BLE AP changes or native association. OTA, Gallery and managed relay retain it until their owned cleanup completes. ACS still has an older retirement policy that releases its JavaScript reservation after reporting an unconfirmed stop; native association custody remains retained on failure. Consolidating that ACS retirement is a separate qualification gate. A refused OTA or Gallery caller makes no AP or association changes. 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.
+
+### Incoming OTA server and outgoing media clients
+
+Hotspot association verifies the glasses SSID and the Wi-Fi interface/address for
+both uses. Gallery and relay clients also wait for outgoing Local Network access
+by connecting to the glasses HTTP endpoint. OTA selects `incoming-server`: it
+serves already downloaded artifacts to connections initiated by the glasses, and
+its own listener must become ready before the app sends the OTA manifest URL.
+It does not depend on the Gallery HTTP server being available. Apple TN3179 lists
+accepting incoming TCP as an operation that does not require Local Network
+permission. This does not change outgoing Gallery/relay consent or the shared
+network ownership and teardown rules.

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

@@ -447,13 +447,6 @@ class InternetHold(private val context: Context) {
     private fun cellularIsValidated(manager: ConnectivityManager): Boolean =
         findValidatedCellular(manager) != null
 
-    private fun findValidatedCellular(manager: ConnectivityManager): Network? =
-        manager.allNetworks.firstOrNull { network ->
-            val capabilities = manager.getNetworkCapabilities(network) ?: return@firstOrNull false
-            capabilities.hasTransport(NetworkCapabilities.TRANSPORT_CELLULAR) &&
-                isValidatedInternet(capabilities)
-        }
-
     private fun connectivityManager(): ConnectivityManager? =
         context.applicationContext.getSystemService(ConnectivityManager::class.java)
 
@@ -466,6 +459,14 @@ class InternetHold(private val context: Context) {
 
         private const val DEFAULT_POLL_MS = 200L
 
+        /** Exclude validated carrier IMS/DUN networks that do not provide app internet. */
+        internal fun findValidatedCellular(manager: ConnectivityManager): Network? =
+            manager.allNetworks.firstOrNull { network ->
+                val capabilities = manager.getNetworkCapabilities(network) ?: return@firstOrNull false
+                capabilities.hasTransport(NetworkCapabilities.TRANSPORT_CELLULAR) &&
+                    isValidatedInternet(capabilities)
+            }
+
         fun isValidatedInternet(capabilities: NetworkCapabilities): Boolean =
             capabilities.hasCapability(NetworkCapabilities.NET_CAPABILITY_INTERNET) &&
                 capabilities.hasCapability(NetworkCapabilities.NET_CAPABILITY_VALIDATED)

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

@@ -2,9 +2,10 @@ 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.network.InternetHold
+import com.mentra.glassesmedia.trace.SoftApTrace
 import com.mentra.glassesmedia.source.I420Planes
 import java.io.IOException
 import java.util.concurrent.CountDownLatch
@@ -65,12 +66,9 @@ class PhoneWhipPublisher(
         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")
+        val internet = InternetHold.findValidatedCellular(manager)
+          ?: error("Phone mobile data is unavailable")
+        SoftApTrace.stage("whip_uplink_network", "network" to internet)
         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()
@@ -167,7 +165,12 @@ class PhoneWhipPublisher(
     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 onFailure(call: Call, error: IOException) {
+        // Exception messages can contain the credential-bearing publish URL. Record types only.
+        SoftApTrace.failure("whip_uplink_signaling", "error" to error.javaClass.simpleName,
+          "cause" to error.cause?.javaClass?.simpleName)
+        queue.post { fail("WHIP signaling failed (${error.javaClass.simpleName})") }
+      }
       override fun onResponse(call: Call, response: Response) {
         response.use {
           val location = response.header("Location")?.let { request.url.resolve(it) }

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

@@ -0,0 +1,224 @@
+package com.mentra.glassesmedia.source
+
+import android.util.Log
+
+/**
+ * A second, optional consumer of decoded glasses video, sitting beside the ACS sender.
+ *
+ * The call owns this pipeline; the preview is a guest. [offer] therefore never blocks, never lets
+ * a `Throwable` reach the decoder thread, and never does real work — a sink may only decide
+ * whether it wants the frame, retain it, and schedule bounded work elsewhere. A preview that
+ * crashes, stalls, or falls behind must cost the call nothing.
+ *
+ * [detach] is generation-checked because sessions overlap: a call ending late must not tear down
+ * the subscription a newer call already installed.
+ *
+ * ## Cost with nothing attached
+ *
+ * With no sink and telemetry off, [offer] is one volatile read and a return. Sink, error handler
+ * and the telemetry flag live in one immutable [State] so that read is the only thing the decoder
+ * thread pays.
+ *
+ * ## Why the metrics live here
+ *
+ * These describe the call, not the preview. With [setTelemetryEnabled] on they are collected even
+ * with no sink attached, so a preview-off run is a usable baseline for the same numbers with the
+ * preview on.
+ */
+object DecodedFrameTap {
+  private const val TAG = "FRAME-PREVIEW"
+
+  /**
+   * A snapshot of decoder-thread observations, drained by the reader.
+   *
+   * Sums rather than a percentile ring because this object cannot depend on the preview module,
+   * and because the two questions here are "is the mean cost negligible" and "was there ever a
+   * bad one" — a mean and a max answer both.
+   */
+  data class Metrics(
+    val framesOffered: Long,
+    val framesWithSink: Long,
+    val offerTotalNs: Long,
+    val offerMaxNs: Long,
+    val cadenceSamples: Long,
+    val cadenceTotalNs: Long,
+    val cadenceMaxNs: Long,
+    val sinkExceptions: Long,
+    /** Frames the ACS sender accepted, recorded at its call sites after [offer]. */
+    val acsFramesSent: Long = 0,
+  ) {
+    /** Mean time inside [offer] over every timed frame, with or without a sink. */
+    val offerMeanUs: Double get() = if (framesOffered > 0) offerTotalNs.toDouble() / framesOffered / 1000.0 else 0.0
+    val offerMaxUs: Double get() = offerMaxNs / 1000.0
+    val cadenceMeanMs: Double get() = if (cadenceSamples > 0) cadenceTotalNs.toDouble() / cadenceSamples / 1_000_000.0 else 0.0
+    val cadenceMaxMs: Double get() = cadenceMaxNs / 1_000_000.0
+  }
+
+  private class State(
+    val sink: VideoFrameListener?,
+    val onSinkError: ((Throwable) -> Unit)?,
+    val generation: Long,
+  )
+
+  @Volatile
+  private var state: State? = null
+
+  private var generation: Long = 0
+  private var currentSink: VideoFrameListener? = null
+  private var currentOnSinkError: ((Throwable) -> Unit)? = null
+
+  @Volatile
+  var telemetryEnabled: Boolean = false
+    private set
+
+  private val metricsLock = Any()
+  private var framesOffered = 0L
+  private var framesWithSink = 0L
+  private var offerTotalNs = 0L
+  private var offerMaxNs = 0L
+  private var cadenceSamples = 0L
+  private var cadenceTotalNs = 0L
+  private var cadenceMaxNs = 0L
+  private var sinkExceptions = 0L
+  private var acsFramesSent = 0L
+  private var lastOfferAtNs = 0L
+
+  /**
+   * Install [listener] and return the generation that owns it. [onSinkError] runs on the decoder
+   * thread after a throw has been caught and counted; it must only schedule work elsewhere.
+   */
+  @Synchronized
+  fun attach(listener: VideoFrameListener, onSinkError: ((Throwable) -> Unit)? = null): Long {
+    generation += 1
+    currentSink = listener
+    currentOnSinkError = onSinkError
+    publish()
+    Log.i(TAG, "tap attached generation=$generation")
+    return generation
+  }
+
+  /** Remove the sink only if it is still the one [generation] installed. */
+  @Synchronized
+  fun detach(generation: Long): Boolean {
+    if (generation != this.generation || currentSink == null) return false
+    currentSink = null
+    currentOnSinkError = null
+    publish()
+    Log.i(TAG, "tap detached generation=$generation")
+    return true
+  }
+
+  /** True while [generation] still owns the installed sink. */
+  @Synchronized
+  fun isCurrent(generation: Long): Boolean = generation == this.generation && currentSink != null
+
+  /** Collect cadence and offer cost even with no sink, so preview off/on can be compared. */
+  @Synchronized
+  fun setTelemetryEnabled(enabled: Boolean) {
+    telemetryEnabled = enabled
+    publish()
+  }
+
+  fun hasSink(): Boolean = state?.sink != null
+
+  private fun publish() {
+    val wasCollecting = state != null
+    state = if (currentSink == null && !telemetryEnabled) {
+      null
+    } else {
+      State(currentSink, currentOnSinkError, generation)
+    }
+    if (!wasCollecting && state != null) {
+      // The first gap after collection resumes would span the whole idle period.
+      synchronized(metricsLock) { lastOfferAtNs = 0L }
+    }
+  }
+
+  /** Read and clear the accumulated observations. Called about once a second by the reporter. */
+  fun drainMetrics(): Metrics = synchronized(metricsLock) {
+    val snapshot = Metrics(
+      framesOffered = framesOffered,
+      framesWithSink = framesWithSink,
+      offerTotalNs = offerTotalNs,
+      offerMaxNs = offerMaxNs,
+      cadenceSamples = cadenceSamples,
+      cadenceTotalNs = cadenceTotalNs,
+      cadenceMaxNs = cadenceMaxNs,
+      sinkExceptions = sinkExceptions,
+      acsFramesSent = acsFramesSent,
+    )
+    framesOffered = 0
+    framesWithSink = 0
+    offerTotalNs = 0
+    offerMaxNs = 0
+    cadenceSamples = 0
+    cadenceTotalNs = 0
+    cadenceMaxNs = 0
+    sinkExceptions = 0
+    acsFramesSent = 0
+    snapshot
+  }
+
+  /**
+   * The ACS sender accepted a frame. Counted under the same gate as [offer], so the send rate is
+   * available whenever the tap's other call metrics are, including preview-off baselines.
+   */
+  fun recordAcsSend() {
+    if (state == null) return
+    synchronized(metricsLock) { acsFramesSent += 1 }
+  }
+
+  /**
+   * Called on libwebrtc's decode thread, immediately before the frame goes to ACS.
+   *
+   * The catch is not defensive padding: the alternative is a preview bug throwing on the decoder
+   * thread and taking the wearer's call video with it.
+   */
+  fun offer(planes: I420Planes) {
+    val current = state ?: return
+    val started = System.nanoTime()
+    val listener = current.sink
+
+    var failure: Throwable? = null
+    if (listener != null) {
+      try {
+        listener.onVideoFrame(planes)
+      } catch (error: Throwable) {
+        failure = error
+      }
+    }
+
+    val elapsed = System.nanoTime() - started
+    val firstFailure: Boolean
+    synchronized(metricsLock) {
+      framesOffered += 1
+      if (lastOfferAtNs > 0) {
+        val gap = started - lastOfferAtNs
+        cadenceSamples += 1
+        cadenceTotalNs += gap
+        if (gap > cadenceMaxNs) cadenceMaxNs = gap
+      }
+      lastOfferAtNs = started
+      offerTotalNs += elapsed
+      if (elapsed > offerMaxNs) offerMaxNs = elapsed
+      if (listener != null) framesWithSink += 1
+      firstFailure = failure != null && sinkExceptions == 0L
+      if (failure != null) sinkExceptions += 1
+    }
+
+    if (failure != null) {
+      if (firstFailure) {
+        try {
+          Log.w(TAG, "preview sink threw generation=${current.generation}; call frame unaffected", failure)
+        } catch (ignored: Throwable) {
+          // Logging renders the sink's throwable, whose message and stack are preview code too.
+        }
+      }
+      try {
+        current.onSinkError?.invoke(failure)
+      } catch (ignored: Throwable) {
+        // The handler is preview code too; it gets no more access to this thread than the sink.
+      }
+    }
+  }
+}

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

@@ -0,0 +1,50 @@
+package com.mentra.glassesmedia.source
+
+import java.util.concurrent.CompletableFuture
+import java.util.concurrent.ConcurrentHashMap
+
+/**
+ * Stills the glasses upload to the phone's ingest listener during a Direct-link call.
+ *
+ * A still is only accepted for a request id the host registered with [expect] before it asked the
+ * glasses to shoot, so nothing else on the hotspot can push an image onto the outgoing Teams tile.
+ * Process-wide because the listener is rebuilt on every SoftAP recovery while the photo request
+ * belongs to the meeting.
+ */
+object StillPhotoInbox {
+
+  /** Largest still accepted. A full-size Mentra Live JPEG is 1-3 MB. */
+  const val MAX_BYTES = 16L * 1024 * 1024
+
+  private val pending = ConcurrentHashMap<String, CompletableFuture<ByteArray>>()
+
+  /** Register [requestId]. Replaces an earlier registration of the same id. */
+  fun expect(requestId: String): CompletableFuture<ByteArray> {
+    val future = CompletableFuture<ByteArray>()
+    pending.put(requestId, future)?.cancel(false)
+    return future
+  }
+
+  /** True when a POST for [requestId] should be read. */
+  fun isExpected(requestId: String): Boolean = pending[requestId]?.isDone == false
+
+  /** Hand over a still. False when nothing is waiting for [requestId]. */
+  fun deliver(requestId: String, bytes: ByteArray): Boolean {
+    val future = pending[requestId] ?: return false
+    return future.complete(bytes)
+  }
+
+  /** The registration for [requestId], if any. */
+  fun lookup(requestId: String): CompletableFuture<ByteArray>? = pending[requestId]
+
+  /** Forget [requestId]; a waiter sees cancellation. */
+  fun cancel(requestId: String) {
+    pending.remove(requestId)?.cancel(false)
+  }
+
+  /** Leave, End, or a new join. */
+  fun cancelAll() {
+    val all = pending.keys.toList()
+    all.forEach { cancel(it) }
+  }
+}

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

@@ -43,11 +43,33 @@ object WhipIngestProtocol {
    */
   data class State(val activeSessionId: String? = null, val stopped: Boolean = false)
 
+  /**
+   * Base of the still endpoint on the same listener. During a call the glasses POST a full-size
+   * JPEG to `/photo/<requestId>` instead of the cloud, since their own hotspot has no internet.
+   */
+  const val STILL_PATH = "/photo"
+
   /** Where to point the `Location` header. WHIP clients DELETE against exactly this URL. */
   data class Endpoint(val host: String, val port: Int) {
     fun sessionUrl(sessionId: String) = "http://$host:$port$BASE_PATH/$sessionId"
+
+    /** Where the glasses upload the still for [requestId]. */
+    fun stillUrl(requestId: String) = "http://$host:$port$STILL_PATH/$requestId"
   }
 
+  private val STILL_ID = Regex("[A-Za-z0-9_-]{1,64}")
+
+  /** `/photo/<id>` -> `<id>` for a well-formed id; null for every other target. */
+  fun stillRequestIdOf(target: String): String? {
+    val path = target.substringBefore('?')
+    if (!path.startsWith("$STILL_PATH/")) return null
+    val id = path.removePrefix("$STILL_PATH/")
+    return id.takeIf { STILL_ID.matches(it) }
+  }
+
+  /** True for an id the still endpoint could ever accept, so the host can mint compatible ones. */
+  fun isValidStillRequestId(requestId: String): Boolean = STILL_ID.matches(requestId)
+
   data class Response(
     val status: Int,
     val reason: String,

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

@@ -2,6 +2,7 @@ package com.mentra.glassesmedia.source
 
 import android.util.Log
 import com.mentra.glassesmedia.trace.SoftApTrace
+import java.io.BufferedInputStream
 import java.io.BufferedOutputStream
 import java.io.IOException
 import java.io.InputStream
@@ -231,12 +232,18 @@ class WhipIngestServer(
         socket.soTimeout = READ_TIMEOUT_MS
         val output = BufferedOutputStream(socket.getOutputStream())
         try {
-          val request = readRequest(socket.getInputStream())
-          if (request == null) {
+          val input = BufferedInputStream(socket.getInputStream())
+          val head = readHead(input)
+          if (head == null) {
             write(output, WhipIngestProtocol.Response(400, "Bad Request", body = "malformed request"))
             return
           }
-          write(output, handle(request))
+          val stillId = WhipIngestProtocol.stillRequestIdOf(head.target)
+          if (stillId != null) {
+            write(output, receiveStill(head, stillId, input))
+            return
+          }
+          write(output, handle(readBody(head, input)))
         } catch (error: Exception) {
           Log.w(TAG, "connection failed", error)
           runCatching {
@@ -336,6 +343,54 @@ class WhipIngestServer(
     }
   }
 
+  /**
+   * `POST /photo/<id>`: a full-size still from the glasses. Read only for an id the host is
+   * waiting on, so an unsolicited upload never costs the phone a multi-megabyte buffer.
+   */
+  private fun receiveStill(head: Head, requestId: String, input: InputStream): WhipIngestProtocol.Response {
+    if (!head.method.equals("POST", ignoreCase = true)) {
+      return WhipIngestProtocol.Response(405, "Method Not Allowed", mapOf("Allow" to "POST"), "POST a JPEG")
+    }
+    if (!StillPhotoInbox.isExpected(requestId)) {
+      SoftApTrace.stage("still_upload_unexpected", "requestId" to requestId)
+      return WhipIngestProtocol.Response(404, "Not Found", body = "no still pending for $requestId")
+    }
+    val length = head.contentLength
+    if (length == null || length <= 0) {
+      return WhipIngestProtocol.Response(411, "Length Required", body = "Content-Length required")
+    }
+    if (length > StillPhotoInbox.MAX_BYTES) {
+      return WhipIngestProtocol.Response(413, "Content Too Large", body = "still exceeds ${StillPhotoInbox.MAX_BYTES} bytes")
+    }
+    val startedAt = System.nanoTime() / 1_000_000
+    val bytes = ByteArray(length.toInt())
+    var read = 0
+    while (read < bytes.size) {
+      val count = input.read(bytes, read, bytes.size - read)
+      if (count < 0) break
+      read += count
+    }
+    if (read < bytes.size) {
+      SoftApTrace.failure("still_upload_truncated", "requestId" to requestId, "read" to read, "expected" to bytes.size)
+      return WhipIngestProtocol.Response(400, "Bad Request", body = "body ended after $read of ${bytes.size} bytes")
+    }
+    val delivered = StillPhotoInbox.deliver(requestId, bytes)
+    SoftApTrace.stage(
+      "still_upload_received",
+      "requestId" to requestId,
+      "bytes" to bytes.size,
+      "readMs" to (System.nanoTime() / 1_000_000 - startedAt),
+      "delivered" to delivered,
+    )
+    if (!delivered) return WhipIngestProtocol.Response(410, "Gone", body = "still for $requestId is no longer wanted")
+    return WhipIngestProtocol.Response(
+      200,
+      "OK",
+      mapOf("Content-Type" to "application/json"),
+      "{\"ok\":true,\"bytes\":${bytes.size}}",
+    )
+  }
+
   /** Frees the slot only if this session still holds it, so a newer publisher is not evicted. */
   private fun releaseSlot(sessionId: String) {
     synchronized(lock) {
@@ -362,21 +417,41 @@ class WhipIngestServer(
      */
     const val TOMBSTONE_MS = 3_000L
 
+    /** Request line and headers, read without consuming any of the body. */
+    internal class Head(
+      val method: String,
+      val target: String,
+      val contentType: String?,
+      val contentLength: Long?,
+    )
+
+    /** Longest request line or header line accepted; real ones are well under 200 bytes. */
+    private const val MAX_HEADER_LINE = 8 * 1024
+
     /**
      * Reads a request into [WhipIngestProtocol.Request]. Only `Content-Length` bodies are
      * supported: the glasses' WHIP client sends one, and `chunked` would be a silent 400 otherwise,
      * so it is rejected explicitly by the missing-length path below.
      */
     fun readRequest(stream: InputStream): WhipIngestProtocol.Request? {
-      val reader = stream.bufferedReader(Charsets.UTF_8)
+      val input = if (stream is BufferedInputStream) stream else BufferedInputStream(stream)
+      val head = readHead(input) ?: return null
+      return readBody(head, input)
+    }
+
+    /**
+     * Header parsing is byte-exact so the body that follows can be binary: the still endpoint
+     * reads a JPEG off the same stream, which a character reader would have buffered and decoded.
+     */
+    internal fun readHead(input: InputStream): Head? {
       val (method, target) = WhipIngestProtocol.parseRequestLine(
-        reader.readLine() ?: return null,
+        readLine(input) ?: return null,
       ) ?: return null
       SoftApTrace.stage("whip_request_line_read", "method" to method)
 
       val headers = mutableMapOf<String, String>()
       while (true) {
-        val line = reader.readLine() ?: break
+        val line = readLine(input) ?: break
         if (line.isEmpty()) break
         val separator = line.indexOf(':')
         if (separator <= 0) continue
@@ -386,24 +461,49 @@ class WhipIngestServer(
       val contentType = WhipIngestProtocol.headerValue(headers, "Content-Type")
       val contentLength = WhipIngestProtocol.headerValue(headers, "Content-Length")?.toLongOrNull()
       SoftApTrace.stage("whip_request_headers_read", "contentLength" to contentLength)
+      return Head(method, target, contentType, contentLength)
+    }
 
+    internal fun readBody(head: Head, input: InputStream): WhipIngestProtocol.Request {
+      val contentLength = head.contentLength
       // Do not read a body we have already decided to refuse. decide() checks the length first for
       // exactly this reason.
       if (contentLength == null || contentLength <= 0 ||
         contentLength > WhipIngestProtocol.MAX_BODY_BYTES
       ) {
-        return WhipIngestProtocol.Request(method, target, contentType, contentLength)
+        return WhipIngestProtocol.Request(head.method, head.target, head.contentType, contentLength)
       }
 
-      val body = CharArray(contentLength.toInt())
+      val body = ByteArray(contentLength.toInt())
       var read = 0
       while (read < body.size) {
-        val count = reader.read(body, read, body.size - read)
+        val count = input.read(body, read, body.size - read)
         if (count < 0) break
         read += count
         SoftApTrace.stage("whip_request_body_read", "read" to read, "expected" to body.size)
       }
-      return WhipIngestProtocol.Request(method, target, contentType, contentLength, String(body, 0, read))
+      return WhipIngestProtocol.Request(
+        head.method,
+        head.target,
+        head.contentType,
+        contentLength,
+        String(body, 0, read, Charsets.UTF_8),
+      )
+    }
+
+    /** One CRLF- or LF-terminated line, or null at end of stream before any byte. */
+    private fun readLine(input: InputStream): String? {
+      val line = java.io.ByteArrayOutputStream()
+      while (true) {
+        val next = input.read()
+        if (next < 0) return if (line.size() == 0) null else line.toString(Charsets.ISO_8859_1.name())
+        if (next == '\n'.code) break
+        line.write(next)
+        if (line.size() > MAX_HEADER_LINE) throw IOException("header line too long")
+      }
+      val bytes = line.toByteArray()
+      val end = if (bytes.isNotEmpty() && bytes.last() == '\r'.code.toByte()) bytes.size - 1 else bytes.size
+      return String(bytes, 0, end, Charsets.ISO_8859_1)
     }
 
     /** Convenience for tests and teardown paths that must not outlive the tombstone. */

package/index.d.ts

@@ -0,0 +1,11 @@
+/** Shared native association owner for the local glasses hotspot. */
+export const glassesHotspot: {
+  join(
+    id: string,
+    ssid: string,
+    password: string,
+    gateway?: string,
+    purpose?: "outgoing-client" | "incoming-server",
+  ): Promise<string>
+  leave(id: string): Promise<void>
+}

package/index.js

@@ -1 +1,10 @@
 // Native library. Media stays in native code; publishers consume decoded frames and PCM.
+
+// Load only when this transport is requested. Importing the package does not
+// start a native session or require Expo's application entry point.
+const native = () => require("expo-modules-core").requireNativeModule("MentraGlassesMediaRelay")
+export const glassesHotspot = Object.freeze({
+  join: (id, ssid, password, gateway, purpose = "outgoing-client") =>
+    native().joinLocalHotspot(id, ssid, password, gateway ?? null, purpose),
+  leave: (id) => native().leaveLocalHotspot(id),
+})