@akhilpulse/samadhaan-session-replay 0.4.2 → 0.5.0

package/README.md

@@ -122,15 +122,34 @@ if a module is missing that capability is simply skipped (no crash):
 | Capability                | Package                            | If missing |
 |---------------------------|------------------------------------|------------|
 | Shake detection           | `react-native-shake`               | Use `triggerAssist()` manually |
-| Microphone (voice input)  | `react-native-live-audio-stream`   | Assistant can still speak + draw arrows; just can't hear the user |
-| Agent voice playback      | provide a `PcmAudioPlayer` (see below) | Agent audio is dropped (arrows + transcript still work) |
+| Microphone (voice input)  | `react-native-live-audio-stream`   | Voice bar shows "Mic unavailable" — assistant can still speak + draw arrows |
+| Agent voice playback      | **built-in on Android (v0.5.0+)**; custom `PcmAudioPlayer` optional | On iOS without a custom player, agent audio is dropped (arrows + transcript still work) |
 
 ```bash
 npm install react-native-shake react-native-live-audio-stream
 cd ios && pod install
 ```
 
-The agent streams **int16 mono PCM at 16 kHz**. Plug in your own player to hear it:
+#### Microphone permission (required for voice input)
+
+- **Android** — declare in your app's `AndroidManifest.xml`:
+  ```xml
+  <uses-permission android:name="android.permission.RECORD_AUDIO" />
+  ```
+  Starting in **0.5.0 the SDK requests the runtime permission automatically**
+  the first time the assistant opens. If the user denies it, the voice bar
+  shows "Mic blocked — allow microphone access in Settings" instead of
+  pretending to listen.
+- **iOS** — add `NSMicrophoneUsageDescription` to `Info.plist` or the OS will
+  kill the app when recording starts.
+
+#### Agent voice playback
+
+The agent streams **int16 mono PCM at 16 kHz**. Starting in **0.5.0 the SDK
+ships a built-in Android AudioTrack player** (part of the bundled native
+module — rebuild the Android app after upgrading). It's used automatically
+when you don't pass `assistantAudioPlayer`. On iOS (or to override), plug in
+your own player:
 
 ```tsx
 import type { PcmAudioPlayer } from "@akhilpulse/samadhaan-session-replay";
@@ -167,6 +186,7 @@ After installing native deps on Android, **rebuild the app**
 4. Pause screenshot capture while the iOS keyboard is visible.
 5. Auto-mount the guided-tour overlay inside the provider, and singleton-guard it.
 6. **Android elevated views & screenshots.** `react-native-view-shot` uses a software canvas draw on Android (`view.draw(canvas)`) which silently skips any view promoted to a hardware compositor layer (anything with `elevation > 0` or `zIndex > 0` — RN implements `zIndex` via `setElevation` on Android). To work around this, **starting in 0.3.0 the SDK ships its own native module that captures via Android's `PixelCopy` API** (real on-screen pixels, including hardware layers, modals, FABs, and native `SurfaceView`s like `react-native-maps`). This module is autolinked — **after upgrading the SDK on Android you must rebuild the app** (`cd android && ./gradlew clean && cd .. && npx react-native run-android`) for the new screenshot path to activate. If the native module isn't present at runtime (older build, Expo Go), the SDK transparently falls back to `captureScreen` and the elevation limitation re-applies. Requires Android 7.0+ (API 24).
+7. **GPU-busy crash hardening (0.4.3).** On some Adreno devices, queueing PixelCopy readbacks while the GPU is saturated (maps / navigation animations) can crash the host app inside the vendor driver (`vulkan.adreno.so`) — a native fault that cannot be caught from Java or JS. Starting in 0.4.3 the native module: captures directly into a small (target-width) reused bitmap instead of a full-screen one (~20x smaller GPU readback per frame); reuses a single handler thread instead of spawning one per frame; allows only ONE capture in flight at a time (a busy driver makes the JS loop skip frames via `E_BUSY` rather than pile up readbacks); and keeps a crash-loop breaker — if the process previously died mid-capture twice, PixelCopy is permanently disabled on that device (`E_DISABLED`) and the SDK falls back to view-shot instead of crashing the app again. **Rebuild the Android app after upgrading** for these fixes to take effect.
 
 ## Publishing
 

package/android/src/main/java/com/akhilpulse/sessionreplay/SessionReplayPcmPlayerModule.kt

@@ -0,0 +1,119 @@
+package com.akhilpulse.sessionreplay
+
+import android.media.AudioAttributes
+import android.media.AudioFormat
+import android.media.AudioTrack
+import android.os.Handler
+import android.os.HandlerThread
+import android.util.Base64
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReactContextBaseJavaModule
+import com.facebook.react.bridge.ReactMethod
+
+/**
+ * Built-in streaming PCM player for the Shake-to-Assist agent voice
+ * (v0.5.0+). Plays int16 mono PCM chunks (base64 over the bridge) through
+ * a single reused AudioTrack in streaming mode, so host apps get agent
+ * audio out of the box without wiring their own PcmAudioPlayer.
+ *
+ * All AudioTrack work happens on a dedicated HandlerThread — never on the
+ * React native-modules thread — because AudioTrack.write() in blocking
+ * mode can stall for the duration of the buffered audio.
+ */
+class SessionReplayPcmPlayerModule(reactContext: ReactApplicationContext) :
+    ReactContextBaseJavaModule(reactContext) {
+
+  override fun getName() = "SessionReplayPcmPlayer"
+
+  private var track: AudioTrack? = null
+  private var thread: HandlerThread? = null
+  private var handler: Handler? = null
+
+  private fun ensureHandler(): Handler {
+    val alive = thread
+    val h = handler
+    if (alive != null && alive.isAlive && h != null) return h
+    val nt = HandlerThread("SessionReplayPcmPlayer")
+    nt.start()
+    thread = nt
+    val nh = Handler(nt.looper)
+    handler = nh
+    return nh
+  }
+
+  private fun releaseTrack() {
+    try { track?.stop() } catch (_: Throwable) {}
+    try { track?.release() } catch (_: Throwable) {}
+    track = null
+  }
+
+  @ReactMethod
+  fun start(sampleRateIn: Int) {
+    ensureHandler().post {
+      try {
+        releaseTrack()
+        val sampleRate = if (sampleRateIn > 0) sampleRateIn else 16000
+        val minBuf = AudioTrack.getMinBufferSize(
+            sampleRate, AudioFormat.CHANNEL_OUT_MONO, AudioFormat.ENCODING_PCM_16BIT)
+        // ~0.5 s of 16-bit mono headroom, never below the platform minimum.
+        val bufBytes = maxOf(minBuf, sampleRate)
+        val t = AudioTrack.Builder()
+            .setAudioAttributes(
+                AudioAttributes.Builder()
+                    .setUsage(AudioAttributes.USAGE_MEDIA)
+                    .setContentType(AudioAttributes.CONTENT_TYPE_SPEECH)
+                    .build())
+            .setAudioFormat(
+                AudioFormat.Builder()
+                    .setEncoding(AudioFormat.ENCODING_PCM_16BIT)
+                    .setSampleRate(sampleRate)
+                    .setChannelMask(AudioFormat.CHANNEL_OUT_MONO)
+                    .build())
+            .setBufferSizeInBytes(bufBytes)
+            .setTransferMode(AudioTrack.MODE_STREAM)
+            .build()
+        t.play()
+        track = t
+      } catch (_: Throwable) {
+        track = null
+      }
+    }
+  }
+
+  @ReactMethod
+  fun play(base64Pcm: String) {
+    ensureHandler().post {
+      val t = track ?: return@post
+      try {
+        val bytes = Base64.decode(base64Pcm, Base64.DEFAULT)
+        if (bytes.isNotEmpty()) t.write(bytes, 0, bytes.size)
+      } catch (_: Throwable) {}
+    }
+  }
+
+  /** Barge-in: drop any queued agent audio immediately. */
+  @ReactMethod
+  fun clear() {
+    ensureHandler().post {
+      val t = track ?: return@post
+      try {
+        t.pause()
+        t.flush()
+        t.play()
+      } catch (_: Throwable) {}
+    }
+  }
+
+  @ReactMethod
+  fun stop() {
+    ensureHandler().post { releaseTrack() }
+  }
+
+  override fun invalidate() {
+    super.invalidate()
+    try { handler?.post { releaseTrack() } } catch (_: Throwable) {}
+    try { thread?.quitSafely() } catch (_: Throwable) {}
+    thread = null
+    handler = null
+  }
+}

package/android/src/main/java/com/akhilpulse/sessionreplay/SessionReplayPixelCopyModule.kt

@@ -1,6 +1,7 @@
 package com.akhilpulse.sessionreplay
 
 import android.app.Activity
+import android.content.Context
 import android.graphics.Bitmap
 import android.os.Build
 import android.os.Handler
@@ -25,6 +26,27 @@ import java.util.concurrent.atomic.AtomicBoolean
  *
  * Requires API 24 (Android 7.0). Falls back to view-shot in JS otherwise.
  *
+ * Efficiency / crash-hardening notes (v0.4.3):
+ *  - PixelCopy scales into the destination bitmap, so we capture DIRECTLY
+ *    into a small (targetWidth-sized) bitmap instead of a full-screen
+ *    ARGB_8888 one (~10 MB/frame at 1080p, 4 fps). This cuts the GPU
+ *    readback size ~20x, which both saves battery and dramatically narrows
+ *    the window in which a busy GPU driver (maps, nav animations) can fault.
+ *  - The destination bitmap and the HandlerThread are reused across frames
+ *    instead of being allocated/started/torn down 4x per second.
+ *  - Only ONE capture may be in flight at a time. If JS asks for a frame
+ *    while the previous PixelCopy is still queued in the driver (typical
+ *    when the GPU is saturated), we reject with E_BUSY and JS simply skips
+ *    that frame — queueing readbacks against a saturated Adreno driver is
+ *    the known crash scenario (native fault in vulkan.adreno.so, which
+ *    cannot be caught from Java/Kotlin).
+ *  - Crash-loop breaker: a SharedPreferences sentinel is set while a copy
+ *    is in flight and cleared when it settles. If the process died mid-copy
+ *    (i.e. the driver crashed the app), the next launch sees the sentinel,
+ *    increments a crash counter, and after MAX_DRIVER_CRASHES the module
+ *    permanently rejects with E_DISABLED on this device so JS uses the
+ *    safe view-shot fallback instead of crashing the host app again.
+ *
  * Note: Dialog windows (react-native `Modal`, react-native-modal, many
  * bottom-sheet libraries) live on a separate Window and are not included
  * in this capture. A future version will composite those in via reflection.
@@ -32,89 +54,211 @@ import java.util.concurrent.atomic.AtomicBoolean
 class SessionReplayPixelCopyModule(reactContext: ReactApplicationContext) :
     ReactContextBaseJavaModule(reactContext) {
 
+  companion object {
+    private const val PREFS = "session_replay_pixelcopy"
+    private const val KEY_IN_FLIGHT = "capture_in_flight"
+    private const val KEY_DRIVER_CRASHES = "driver_crash_count"
+    private const val MAX_DRIVER_CRASHES = 2
+    private const val TIMEOUT_MS = 1200L
+  }
+
   override fun getName(): String = "SessionReplayPixelCopy"
 
+  private val inFlight = AtomicBoolean(false)
+
+  // Lazily-created, reused across frames. Never torn down per capture.
+  @Volatile private var handlerThread: HandlerThread? = null
+  @Volatile private var handler: Handler? = null
+
+  // Reused destination bitmap (small: targetWidth x scaled height).
+  // Guarded by bitmapLock — touched from the UI thread (obtain), the capture
+  // handler thread (timeout orphaning) and arbitrary threads (invalidate).
+  private val bitmapLock = Any()
+  private var reusableBitmap: Bitmap? = null
+
+  // Cached crash-history verdict (null = not checked yet this process).
+  @Volatile private var disabledOnThisDevice: Boolean? = null
+
+  private fun prefs() =
+      reactApplicationContext.getSharedPreferences(PREFS, Context.MODE_PRIVATE)
+
+  /**
+   * Returns true when PixelCopy must not be used on this device because a
+   * previous process died while a copy was in flight (native driver crash).
+   */
+  private fun isDisabledByCrashHistory(): Boolean {
+    disabledOnThisDevice?.let { return it }
+    synchronized(this) {
+      disabledOnThisDevice?.let { return it }
+      val p = prefs()
+      var crashes = p.getInt(KEY_DRIVER_CRASHES, 0)
+      if (p.getBoolean(KEY_IN_FLIGHT, false)) {
+        // Previous process died mid-capture — treat as a driver crash.
+        crashes += 1
+        p.edit()
+            .putInt(KEY_DRIVER_CRASHES, crashes)
+            .putBoolean(KEY_IN_FLIGHT, false)
+            .apply()
+      }
+      val disabled = crashes >= MAX_DRIVER_CRASHES
+      disabledOnThisDevice = disabled
+      return disabled
+    }
+  }
+
+  private fun captureHandler(): Handler {
+    handler?.let { return it }
+    synchronized(this) {
+      handler?.let { return it }
+      val t = HandlerThread("SessionReplayPixelCopy")
+      t.start()
+      handlerThread = t
+      val h = Handler(t.looper)
+      handler = h
+      return h
+    }
+  }
+
+  private fun obtainBitmap(w: Int, h: Int): Bitmap {
+    synchronized(bitmapLock) {
+      val existing = reusableBitmap
+      if (existing != null && !existing.isRecycled && existing.width == w && existing.height == h) {
+        return existing
+      }
+      existing?.recycle()
+      val fresh = Bitmap.createBitmap(w, h, Bitmap.Config.ARGB_8888)
+      reusableBitmap = fresh
+      return fresh
+    }
+  }
+
+  /** Drop the cached bitmap WITHOUT recycling (a late driver write may still land in it). */
+  private fun orphanBitmap() {
+    synchronized(bitmapLock) { reusableBitmap = null }
+  }
+
+  private fun markInFlight(active: Boolean) {
+    try {
+      prefs().edit().putBoolean(KEY_IN_FLIGHT, active).apply()
+    } catch (_: Throwable) {}
+  }
+
   @ReactMethod
   fun capture(targetWidth: Double, quality: Double, promise: Promise) {
     if (Build.VERSION.SDK_INT < Build.VERSION_CODES.N) {
       promise.reject("E_API", "PixelCopy requires Android 7.0+ (API 24)")
       return
     }
+    if (isDisabledByCrashHistory()) {
+      promise.reject(
+          "E_DISABLED",
+          "PixelCopy disabled on this device after previous GPU driver crashes")
+      return
+    }
+    // Single in-flight capture: if the driver is still working on the last
+    // readback (GPU busy — maps, animations), skip this frame instead of
+    // queueing more work against a saturated driver.
+    if (!inFlight.compareAndSet(false, true)) {
+      promise.reject("E_BUSY", "Previous capture still in flight")
+      return
+    }
+
     val activity: Activity? = currentActivity
     if (activity == null) {
+      inFlight.set(false)
       promise.reject("E_NO_ACTIVITY", "No current activity")
       return
     }
 
     activity.runOnUiThread {
       val settled = AtomicBoolean(false)
-      val handlerThread = HandlerThread("SessionReplayPixelCopy")
-      handlerThread.start()
-      val handler = Handler(handlerThread.looper)
+      val h = captureHandler()
 
-      // Safety net: if PixelCopy never invokes its callback (rare driver
-      // bug on some vendor ROMs), reject after 1.5s instead of leaving the
-      // JS promise pending forever and freezing the capture loop.
-      handler.postDelayed({
+      fun settle(block: () -> Unit) {
         if (settled.compareAndSet(false, true)) {
-          try { promise.reject("E_TIMEOUT", "PixelCopy timed out") } catch (_: Throwable) {}
-          handlerThread.quitSafely()
+          try {
+            block()
+          } catch (_: Throwable) {}
+          markInFlight(false)
+          inFlight.set(false)
+        }
+      }
+
+      // Safety net: if PixelCopy never invokes its callback (rare driver
+      // bug on some vendor ROMs), reject instead of leaving the JS promise
+      // pending forever and freezing the capture loop.
+      h.postDelayed({
+        settle {
+          // The driver may still write into the destination bitmap after a
+          // timeout — orphan it (without recycling) so the next capture
+          // allocates a fresh one instead of racing the late writer.
+          orphanBitmap()
+          promise.reject("E_TIMEOUT", "PixelCopy timed out")
         }
-      }, 1500)
+      }, TIMEOUT_MS)
 
       try {
         val window = activity.window
         val decor = window.decorView
         val srcW = decor.width
         val srcH = decor.height
-        if (srcW <= 0 || srcH <= 0) {
-          if (settled.compareAndSet(false, true)) {
-            promise.reject("E_NO_SIZE", "Decor view has zero size")
-            handlerThread.quitSafely()
-          }
+        if (srcW <= 0 || srcH <= 0 || !decor.isAttachedToWindow) {
+          settle { promise.reject("E_NO_SIZE", "Decor view not ready") }
           return@runOnUiThread
         }
-        val bitmap = Bitmap.createBitmap(srcW, srcH, Bitmap.Config.ARGB_8888)
+
+        // Capture directly at the downscaled size — PixelCopy scales the
+        // window contents to fit the destination bitmap, so there is no
+        // need for a full-resolution intermediate bitmap + scale pass.
+        val tw = targetWidth.toInt().coerceAtLeast(1).coerceAtMost(srcW)
+        val th = (srcH.toDouble() / srcW.toDouble() * tw).toInt().coerceAtLeast(1)
+        val bitmap = obtainBitmap(tw, th)
+
+        // Sentinel: if the process dies inside the driver during this copy,
+        // the next launch will see it and count a crash (see
+        // isDisabledByCrashHistory).
+        markInFlight(true)
 
         PixelCopy.request(
             window,
             bitmap,
             { result ->
-              if (!settled.compareAndSet(false, true)) return@request
-              try {
+              settle {
                 if (result == PixelCopy.SUCCESS) {
-                  val tw = targetWidth.toInt().coerceAtLeast(1)
-                  val scaled = if (tw < srcW) {
-                    val th = (srcH.toDouble() / srcW.toDouble() * tw).toInt().coerceAtLeast(1)
-                    Bitmap.createScaledBitmap(bitmap, tw, th, true)
-                  } else bitmap
-
                   val q = (quality * 100).toInt().coerceIn(1, 100)
                   val baos = ByteArrayOutputStream()
-                  scaled.compress(Bitmap.CompressFormat.JPEG, q, baos)
-                  if (scaled !== bitmap) scaled.recycle()
-                  bitmap.recycle()
-
+                  bitmap.compress(Bitmap.CompressFormat.JPEG, q, baos)
                   val b64 = Base64.encodeToString(baos.toByteArray(), Base64.NO_WRAP)
                   promise.resolve(b64)
                 } else {
-                  bitmap.recycle()
                   promise.reject("E_PIXELCOPY", "PixelCopy failed: $result")
                 }
-              } catch (e: Throwable) {
-                promise.reject("E_INNER", e)
-              } finally {
-                handlerThread.quitSafely()
               }
             },
-            handler
+            h
         )
       } catch (e: Throwable) {
-        if (settled.compareAndSet(false, true)) {
-          promise.reject("E_OUTER", e)
-          handlerThread.quitSafely()
-        }
+        settle { promise.reject("E_OUTER", e) }
       }
     }
   }
+
+  override fun invalidate() {
+    // Called when the React instance is torn down — release resources.
+    // Clear the crash sentinel: a teardown mid-capture is a CLEAN shutdown,
+    // not a driver crash, and must not count toward the crash-loop breaker.
+    if (inFlight.getAndSet(false)) {
+      markInFlight(false)
+    }
+    try {
+      handlerThread?.quitSafely()
+    } catch (_: Throwable) {}
+    handlerThread = null
+    handler = null
+    synchronized(bitmapLock) {
+      // Don't recycle — a late driver write could still land in it.
+      reusableBitmap = null
+    }
+    super.invalidate()
+  }
 }

package/android/src/main/java/com/akhilpulse/sessionreplay/SessionReplayPixelCopyPackage.kt

@@ -7,7 +7,10 @@ import com.facebook.react.uimanager.ViewManager
 
 class SessionReplayPixelCopyPackage : ReactPackage {
   override fun createNativeModules(reactContext: ReactApplicationContext): List<NativeModule> =
-      listOf(SessionReplayPixelCopyModule(reactContext))
+      listOf(
+          SessionReplayPixelCopyModule(reactContext),
+          SessionReplayPcmPlayerModule(reactContext),
+      )
 
   override fun createViewManagers(reactContext: ReactApplicationContext): List<ViewManager<*, *>> =
       emptyList()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akhilpulse/samadhaan-session-replay",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "React Native SDK for Samadhaan Guided Support — session recording, live remote screen-share, take-control, guided-tour overlays, and Shake-to-Assist AI voice guide.",
   "main": "src/index.ts",
   "module": "src/index.ts",

package/src/SessionReplayProvider.tsx

@@ -38,6 +38,8 @@ import { captureRef, captureScreen } from "react-native-view-shot";
 import {
   subscribeShake,
   UltravoxVoiceSession,
+  createDefaultPcmPlayer,
+  type MicStatus,
   type PcmAudioPlayer,
   type VoiceState,
 } from "./voice";
@@ -50,10 +52,11 @@ import {
 type PixelCopyNative = { capture: (targetWidth: number, quality: number) => Promise<string> };
 const SessionReplayPixelCopy: PixelCopyNative | undefined =
   Platform.OS === "android" ? (NativeModules as any).SessionReplayPixelCopy : undefined;
-let pixelCopyDisabled = false; // turned true after a runtime failure to avoid retrying every frame
+let pixelCopyDisabled = false; // turned true after repeated runtime failures to avoid retrying every frame
+let pixelCopyFailStreak = 0; // consecutive non-busy failures; resets on success
 
 const STORAGE_KEY = "@akhilpulse/samadhaan-session-replay/sessionId";
-const SDK_VERSION = "0.4.2";
+const SDK_VERSION = "0.5.0";
 
 // ---- Module-level session singleton --------------------------------------
 // Multiple SessionReplayProvider mounts (intentional or via React StrictMode's
@@ -157,6 +160,7 @@ export function SessionReplayProvider({ config, children }: { config: Config; ch
 
   // ---- Shake-to-Assist (AI voice guide) state ----
   const [assistantPhase, setAssistantPhase] = useState<AssistantPhase>("idle");
+  const [assistMicStatus, setAssistMicStatus] = useState<MicStatus | null>(null);
   const [assistantArrow, setAssistantArrow] = useState<
     { nx: number; ny: number; label?: string; instruction?: string } | null
   >(null);
@@ -392,15 +396,32 @@ export function SessionReplayProvider({ config, children }: { config: Config; ch
             result: "base64" as const,
             width: 360,
           };
-          let uri: string;
+          let uri: string | null = null;
           if (Platform.OS === "android") {
             if (SessionReplayPixelCopy && !pixelCopyDisabled) {
               try {
                 uri = await SessionReplayPixelCopy.capture(360, 0.25);
-              } catch (err) {
-                if (__DEV__) console.warn("[session-replay] PixelCopy failed, falling back to view-shot:", err);
-                pixelCopyDisabled = true;
-                uri = await captureScreen(captureOpts);
+                pixelCopyFailStreak = 0;
+              } catch (err: any) {
+                const code = err?.code;
+                if (code === "E_BUSY") {
+                  // Previous capture still in flight — the GPU is saturated
+                  // (maps, nav animations). Skip this frame entirely rather
+                  // than piling more readback work onto a busy driver.
+                  uri = null;
+                } else {
+                  pixelCopyFailStreak++;
+                  if (code === "E_DISABLED" || code === "E_API" || pixelCopyFailStreak >= 3) {
+                    // Native module says never use PixelCopy on this device
+                    // (previous GPU driver crashes / API too old), or it has
+                    // failed repeatedly — stop trying.
+                    if (__DEV__) console.warn("[session-replay] PixelCopy disabled, using view-shot:", err);
+                    pixelCopyDisabled = true;
+                  } else if (__DEV__) {
+                    console.warn("[session-replay] PixelCopy failed, falling back to view-shot for this frame:", err);
+                  }
+                  uri = await captureScreen(captureOpts);
+                }
               }
             } else {
               uri = await captureScreen(captureOpts);
@@ -408,6 +429,12 @@ export function SessionReplayProvider({ config, children }: { config: Config; ch
           } else {
             uri = await captureRef(ref as any, captureOpts);
           }
+          if (!uri) {
+            // Frame intentionally skipped (GPU busy) — try again next tick.
+            const elapsedSkip = Date.now() - startedAt;
+            setTimeout(tick, Math.max(0, liveTargetMs - elapsedSkip));
+            return;
+          }
           const blob = base64ToUint8Array(uri);
           // Stream binary over WS — no REST upload in the hot path.
           if (wsRef.current && wsRef.current.readyState === WebSocket.OPEN) {
@@ -543,6 +570,7 @@ export function SessionReplayProvider({ config, children }: { config: Config; ch
     try { voice?.stop(); } catch {}
     setAssistantArrow(null);
     setAssistantPhase("idle");
+    setAssistMicStatus(null);
     if (asid && sessionId && ingestToken) {
       fetch(`${serverUrl}/api/guided-support/assistant/end`, {
         method: "POST",
@@ -586,15 +614,20 @@ export function SessionReplayProvider({ config, children }: { config: Config; ch
         return;
       }
       assistantSessionIdRef.current = j.assistantSessionId;
+      setAssistMicStatus(null);
       const voice = new UltravoxVoiceSession({
         joinUrl: j.joinUrl,
         sampleRate: 16000,
-        audioPlayer: config.assistantAudioPlayer,
+        // Prefer the host-supplied player; otherwise fall back to the SDK's
+        // built-in Android AudioTrack player (v0.5.0+) so the agent's voice
+        // is audible out of the box.
+        audioPlayer: config.assistantAudioPlayer ?? createDefaultPcmPlayer() ?? undefined,
         onState: (s) => {
           // Natural socket close ("ended") tears the whole assistant down.
           if (s === "ended") { endAssist(); return; }
           setAssistantPhase(s);
         },
+        onMicStatus: (status) => setAssistMicStatus(status),
         onError: () => setAssistantPhase("error"),
       });
       voiceRef.current = voice;
@@ -879,7 +912,9 @@ export function SessionReplayProvider({ config, children }: { config: Config; ch
           <View style={styles.assistDock} pointerEvents="box-none">
             <View style={styles.assistDockCard}>
               <VoiceWave phase={assistantPhase} />
-              <Text style={styles.assistStatusText}>{assistantStatusLabel(assistantPhase)}</Text>
+              <Text style={styles.assistStatusText}>
+                {assistantStatusLabel(assistantPhase, assistMicStatus)}
+              </Text>
               <Pressable
                 onPress={endAssist}
                 style={({ pressed }) => [styles.assistClose, pressed && styles.btnPressed]}
@@ -896,7 +931,15 @@ export function SessionReplayProvider({ config, children }: { config: Config; ch
 }
 
 // ---- Shake-to-Assist UI bits ----
-function assistantStatusLabel(phase: AssistantPhase): string {
+function assistantStatusLabel(phase: AssistantPhase, micStatus?: MicStatus | null): string {
+  // Be honest when we can't actually hear the user — a fake "Listening…"
+  // with a dead mic is the worst possible UX (bar stuck forever).
+  if (phase === "listening" && micStatus === "permission_denied") {
+    return "Mic blocked — allow microphone access in Settings";
+  }
+  if (phase === "listening" && micStatus === "unavailable") {
+    return "Mic unavailable — voice input is off";
+  }
   switch (phase) {
     case "connecting": return "Connecting…";
     case "listening": return "Listening… ask me anything";

package/src/index.ts

@@ -9,9 +9,11 @@ export {
 export {
   subscribeShake,
   UltravoxVoiceSession,
+  createDefaultPcmPlayer,
 } from "./voice";
 export type {
   PcmAudioPlayer,
   VoiceState,
+  MicStatus,
   StartVoiceOpts,
 } from "./voice";

package/src/voice.ts

@@ -21,6 +21,8 @@
  * matching server/ultravox.ts (serverWebSocket inputSampleRate/outputSampleRate).
  */
 
+import { NativeModules, PermissionsAndroid, Platform } from "react-native";
+
 // Loads an optional native module without crashing Metro when it's absent.
 function loadOptional<T = any>(name: string): T | null {
   try {
@@ -31,6 +33,34 @@ function loadOptional<T = any>(name: string): T | null {
   }
 }
 
+// ---- Mic permission --------------------------------------------------------
+/**
+ * Android requires a runtime RECORD_AUDIO grant — react-native-live-audio-stream
+ * does NOT request it itself; without it the recorder silently captures nothing
+ * and the assistant can never hear the user. iOS shows its own prompt when the
+ * recorder starts (host app must have NSMicrophoneUsageDescription in Info.plist).
+ */
+async function ensureMicPermission(): Promise<boolean> {
+  if (Platform.OS !== "android") return true;
+  try {
+    const perm = PermissionsAndroid.PERMISSIONS.RECORD_AUDIO;
+    const already = await PermissionsAndroid.check(perm);
+    if (already) return true;
+    const res = await PermissionsAndroid.request(perm, {
+      title: "Microphone access",
+      message: "Needed so the voice assistant can hear you.",
+      buttonPositive: "Allow",
+      buttonNegative: "Not now",
+    });
+    return res === PermissionsAndroid.RESULTS.GRANTED;
+  } catch {
+    return false;
+  }
+}
+
+/** Why voice input isn't working (surfaced so the UI can tell the user). */
+export type MicStatus = "ok" | "permission_denied" | "unavailable";
+
 // ---- Shake detection -----------------------------------------------------
 /**
  * Subscribe to phone-shake events. Returns an unsubscribe function.
@@ -106,6 +136,8 @@ export type StartVoiceOpts = {
   /** Live transcript text (both user + agent), with role + final flag. */
   onTranscript?: (t: { role: string; text: string; final: boolean }) => void;
   onError?: (e: Error) => void;
+  /** Reports whether the microphone actually started (module + permission). */
+  onMicStatus?: (status: MicStatus) => void;
 };
 
 /**
@@ -140,7 +172,7 @@ export class UltravoxVoiceSession {
     ws.onopen = () => {
       if (this.stopped) return;
       this.opts.audioPlayer?.start?.(this.sampleRate);
-      this.startMic();
+      void this.startMic(); // async: requests mic permission, reports onMicStatus
       this.opts.onState?.("listening");
     };
     ws.onmessage = (ev: any) => {
@@ -184,9 +216,21 @@ export class UltravoxVoiceSession {
     }
   }
 
-  private startMic() {
+  private async startMic() {
     const audioMod: any = loadOptional("react-native-live-audio-stream");
-    if (!audioMod) return; // No mic module — assistant can still speak/guide.
+    if (!audioMod) {
+      // No mic module — assistant can still speak/guide, but tell the UI.
+      if (__DEV__) console.warn("[session-replay] react-native-live-audio-stream not installed — voice input disabled");
+      this.opts.onMicStatus?.("unavailable");
+      return;
+    }
+    const granted = await ensureMicPermission();
+    if (this.stopped) return;
+    if (!granted) {
+      if (__DEV__) console.warn("[session-replay] RECORD_AUDIO permission denied — voice input disabled");
+      this.opts.onMicStatus?.("permission_denied");
+      return;
+    }
     const LiveAudioStream = audioMod.default || audioMod;
     try {
       LiveAudioStream.init({
@@ -209,9 +253,12 @@ export class UltravoxVoiceSession {
       LiveAudioStream.start();
       this.audioStream = LiveAudioStream;
       this.micActive = true;
+      this.opts.onMicStatus?.("ok");
     } catch (e) {
       // Mic failed — keep the session alive for agent audio + arrows.
+      if (__DEV__) console.warn("[session-replay] mic capture failed to start:", e);
       this.audioStream = null;
+      this.opts.onMicStatus?.("unavailable");
     }
   }
 
@@ -241,4 +288,23 @@ export class UltravoxVoiceSession {
   }
 }
 
+// ---- Built-in agent-voice player (Android) ---------------------------------
+/**
+ * Returns a PcmAudioPlayer backed by the SDK's bundled Android AudioTrack
+ * module (SessionReplayPcmPlayer, v0.5.0+), or null when the native module
+ * isn't available (iOS, Expo Go, or host app not rebuilt after upgrading).
+ * Used automatically when the integrator doesn't pass `assistantAudioPlayer`.
+ */
+export function createDefaultPcmPlayer(): PcmAudioPlayer | null {
+  if (Platform.OS !== "android") return null;
+  const native: any = (NativeModules as any).SessionReplayPcmPlayer;
+  if (!native || typeof native.play !== "function") return null;
+  return {
+    start: (sampleRate: number) => { try { native.start(sampleRate); } catch {} },
+    play: (pcm: ArrayBuffer) => { try { native.play(arrayBufferToBase64(pcm)); } catch {} },
+    clear: () => { try { native.clear(); } catch {} },
+    stop: () => { try { native.stop(); } catch {} },
+  };
+}
+
 export { arrayBufferToBase64 };