@akhilpulse/samadhaan-session-replay 0.5.0 → 0.6.1

package/README.md

@@ -123,7 +123,7 @@ if a module is missing that capability is simply skipped (no crash):
 |---------------------------|------------------------------------|------------|
 | Shake detection           | `react-native-shake`               | Use `triggerAssist()` manually |
 | 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) |
+| Agent voice playback      | **built-in on Android (v0.5.0+) and iOS (v0.6.0+)**; custom `PcmAudioPlayer` optional | In Expo Go / stale builds without the native module, agent audio is dropped (arrows + transcript still work) |
 
 ```bash
 npm install react-native-shake react-native-live-audio-stream
@@ -145,11 +145,16 @@ cd ios && pod install
 
 #### 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:
+The agent streams **int16 mono PCM at 16 kHz**. The SDK ships built-in native
+players used automatically when you don't pass `assistantAudioPlayer`:
+
+- **Android (0.5.0+)** — AudioTrack streaming player. Rebuild the app after
+  upgrading (`cd android && ./gradlew clean && cd .. && npx react-native run-android`).
+- **iOS (0.6.0+)** — AVAudioEngine player (autolinked via the bundled
+  `SamadhaanSessionReplay` podspec). After upgrading run
+  `cd ios && pod install`, then rebuild the app.
+
+To override with your own player:
 
 ```tsx
 import type { PcmAudioPlayer } from "@akhilpulse/samadhaan-session-replay";
@@ -164,14 +169,15 @@ const myPlayer: PcmAudioPlayer = {
 <SessionReplayProvider config={{ appId: "app_xxx", assistantAudioPlayer: myPlayer }}>
 ```
 
-After installing native deps on Android, **rebuild the app**
-(`cd android && ./gradlew clean && cd .. && npx react-native run-android`).
+After installing native deps, **rebuild the app** — Android:
+`cd android && ./gradlew clean && cd .. && npx react-native run-android`;
+iOS: `cd ios && pod install && cd .. && npx react-native run-ios`.
 
 ## What it does
 
 - Creates a session against `POST /api/guided-support/sessions` and persists `sessionId` in AsyncStorage so it can be resumed after relaunch.
 - Captures gestures (tap, swipe) using a passive PanResponder + onTouchEnd bubble listener — host taps still work.
-- Captures screenshots every 10 s in background mode, every 200 ms in live mode, via `react-native-view-shot`. Uploads via `POST /api/guided-support/storage/uploads/request-url` then PUTs to the returned URL.
+- Captures screenshots every 10 s in background mode, every 500 ms (~2 fps) in live/assistant mode, via `react-native-view-shot`. Uploads via `POST /api/guided-support/storage/uploads/request-url` then PUTs to the returned URL.
 - Auto-connects to `WS /ws/guided-support?sessionId=…&role=device&token=…` when the dashboard flips the session to `live`.
 - Streams binary frames as `[ts u32 BE | width u16 BE | height u16 BE] + JPEG bytes`.
 - Renders a remote-control overlay that visualizes incoming taps. Native touch dispatch (iOS UIEvent / Android AccessibilityService) is wired by the integrator via a small custom native module.

package/SamadhaanSessionReplay.podspec

@@ -0,0 +1,17 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "SamadhaanSessionReplay"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = { :type => package["license"] || "UNLICENSED" }
+  s.authors      = { "Akhil / Pulse Energy" => "support@pulseenergy.io" }
+  s.platforms    = { :ios => "12.0" }
+  s.source       = { :git => "https://samadhaan.pulseenergy.io", :tag => s.version.to_s }
+  s.source_files = "ios/**/*.{h,m,mm}"
+  s.frameworks   = "AVFoundation"
+  s.dependency "React-Core"
+end

package/ios/SessionReplayPcmPlayer.h

@@ -0,0 +1,11 @@
+#import <React/RCTBridgeModule.h>
+#import <React/RCTInvalidating.h>
+
+/**
+ * Streaming PCM16 player for the Shake-to-Assist agent voice (iOS).
+ * Mirrors the Android SessionReplayPcmPlayerModule: start(sampleRate),
+ * play(base64 int16 mono chunks), clear() for barge-in, stop().
+ * Backed by AVAudioEngine + AVAudioPlayerNode.
+ */
+@interface SessionReplayPcmPlayer : NSObject <RCTBridgeModule, RCTInvalidating>
+@end

package/ios/SessionReplayPcmPlayer.m

@@ -0,0 +1,161 @@
+#import "SessionReplayPcmPlayer.h"
+#import <React/RCTLog.h>
+#import <AVFoundation/AVFoundation.h>
+
+@implementation SessionReplayPcmPlayer {
+  AVAudioEngine *_engine;
+  AVAudioPlayerNode *_player;
+  AVAudioFormat *_format;
+  double _sampleRate;
+  BOOL _running;
+}
+
+RCT_EXPORT_MODULE(SessionReplayPcmPlayer);
+
+// All calls run on a dedicated serial queue so bridge threads are never blocked
+// and engine state is never touched concurrently.
+- (dispatch_queue_t)methodQueue
+{
+  static dispatch_queue_t queue;
+  static dispatch_once_t onceToken;
+  dispatch_once(&onceToken, ^{
+    queue = dispatch_queue_create("com.akhilpulse.sessionreplay.pcmplayer", DISPATCH_QUEUE_SERIAL);
+  });
+  return queue;
+}
+
++ (BOOL)requiresMainQueueSetup
+{
+  return NO;
+}
+
+- (void)setUpEngineWithSampleRate:(double)sampleRate
+{
+  [self tearDownEngine];
+
+  // Voice assistant runs duplex (mic capture via react-native-live-audio-stream
+  // + agent playback here, simultaneously), so the session must stay
+  // record-capable. Only touch the category if it isn't already PlayAndRecord —
+  // and NEVER downgrade to a playback-only category, which would silently kill
+  // the mic while the UI still says "Listening".
+  AVAudioSession *session = [AVAudioSession sharedInstance];
+  if (![session.category isEqualToString:AVAudioSessionCategoryPlayAndRecord]) {
+    NSError *err = nil;
+    [session setCategory:AVAudioSessionCategoryPlayAndRecord
+             withOptions:(AVAudioSessionCategoryOptionDefaultToSpeaker |
+                          AVAudioSessionCategoryOptionAllowBluetooth |
+                          AVAudioSessionCategoryOptionMixWithOthers)
+                   error:&err];
+    if (err) {
+      // Another library owns the session config — log and continue with
+      // whatever is active rather than fighting over it.
+      RCTLogWarn(@"[session-replay] could not set AVAudioSession category: %@", err);
+    }
+  }
+  NSError *activeErr = nil;
+  [session setActive:YES error:&activeErr];
+  if (activeErr) {
+    RCTLogWarn(@"[session-replay] could not activate AVAudioSession: %@", activeErr);
+  }
+
+  _sampleRate = sampleRate > 0 ? sampleRate : 16000.0;
+  _engine = [[AVAudioEngine alloc] init];
+  _player = [[AVAudioPlayerNode alloc] init];
+  // Float32 non-interleaved mono — AVAudioPlayerNode's native scheduling format.
+  _format = [[AVAudioFormat alloc] initWithCommonFormat:AVAudioPCMFormatFloat32
+                                             sampleRate:_sampleRate
+                                               channels:1
+                                            interleaved:NO];
+  [_engine attachNode:_player];
+  [_engine connect:_player to:_engine.mainMixerNode format:_format];
+
+  NSError *startErr = nil;
+  if (![_engine startAndReturnError:&startErr]) {
+    RCTLogWarn(@"[session-replay] PCM player engine failed to start: %@", startErr);
+    [self tearDownEngine];
+    return;
+  }
+  [_player play];
+  _running = YES;
+}
+
+- (void)tearDownEngine
+{
+  if (_player) {
+    @try { [_player stop]; } @catch (__unused NSException *e) {}
+  }
+  if (_engine) {
+    @try { [_engine stop]; } @catch (__unused NSException *e) {}
+  }
+  _player = nil;
+  _engine = nil;
+  _format = nil;
+  _running = NO;
+}
+
+RCT_EXPORT_METHOD(start:(double)sampleRate)
+{
+  [self setUpEngineWithSampleRate:sampleRate];
+}
+
+RCT_EXPORT_METHOD(play:(NSString *)base64Pcm)
+{
+  if (!base64Pcm.length) return;
+  if (!_running) {
+    // Host called play() before start() (or engine failed) — try a lazy start
+    // at the default assistant rate rather than dropping audio silently.
+    [self setUpEngineWithSampleRate:(_sampleRate > 0 ? _sampleRate : 16000.0)];
+    if (!_running) return;
+  }
+
+  NSData *pcm = [[NSData alloc] initWithBase64EncodedString:base64Pcm
+                                                    options:NSDataBase64DecodingIgnoreUnknownCharacters];
+  if (!pcm || pcm.length < 2) return;
+
+  AVAudioFrameCount frames = (AVAudioFrameCount)(pcm.length / 2);
+  AVAudioPCMBuffer *buffer = [[AVAudioPCMBuffer alloc] initWithPCMFormat:_format
+                                                           frameCapacity:frames];
+  if (!buffer) return;
+  buffer.frameLength = frames;
+
+  const int16_t *src = (const int16_t *)pcm.bytes;
+  float *dst = buffer.floatChannelData[0];
+  for (AVAudioFrameCount i = 0; i < frames; i++) {
+    dst[i] = (float)src[i] / 32768.0f;
+  }
+
+  // Engine can die on route changes (headphones unplugged) — restart once.
+  if (!_engine.isRunning) {
+    NSError *err = nil;
+    if (![_engine startAndReturnError:&err]) return;
+    [_player play];
+  }
+  [_player scheduleBuffer:buffer completionHandler:nil];
+}
+
+RCT_EXPORT_METHOD(clear)
+{
+  // Barge-in: drop everything queued, keep the node ready for new chunks.
+  if (!_running || !_player) return;
+  @try {
+    [_player stop]; // discards all scheduled buffers
+    if (_engine.isRunning) [_player play];
+  } @catch (__unused NSException *e) {}
+}
+
+RCT_EXPORT_METHOD(stop)
+{
+  [self tearDownEngine];
+}
+
+- (void)invalidate
+{
+  [self tearDownEngine];
+}
+
+- (void)dealloc
+{
+  [self tearDownEngine];
+}
+
+@end

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akhilpulse/samadhaan-session-replay",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "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",
@@ -10,6 +10,8 @@
   "files": [
     "src",
     "android",
+    "ios",
+    "SamadhaanSessionReplay.podspec",
     "react-native.config.js",
     "README.md"
   ],

package/src/SessionReplayProvider.tsx

@@ -56,7 +56,7 @@ let pixelCopyDisabled = false; // turned true after repeated runtime failures to
 let pixelCopyFailStreak = 0; // consecutive non-busy failures; resets on success
 
 const STORAGE_KEY = "@akhilpulse/samadhaan-session-replay/sessionId";
-const SDK_VERSION = "0.5.0";
+const SDK_VERSION = "0.6.1";
 
 // ---- Module-level session singleton --------------------------------------
 // Multiple SessionReplayProvider mounts (intentional or via React StrictMode's
@@ -370,9 +370,9 @@ export function SessionReplayProvider({ config, children }: { config: Config; ch
     // waste CPU/battery/network on periodic screenshots.
     if (config.disableScreenshots || !sessionId || !streamActive) return;
     let stopped = false;
-    // ~4 fps target — low device load while still feeling responsive. Capture
+    // ~2 fps target — low device load while still feeling responsive. Capture
     // takes time, so the loop self-paces: next tick is scheduled AFTER the previous capture completes.
-    const liveTargetMs = 250;
+    const liveTargetMs = 500;
     let lastUploadFrameAt = 0;
     const tick = async () => {
       if (stopped) return;

package/src/voice.ts

@@ -288,15 +288,15 @@ export class UltravoxVoiceSession {
   }
 }
 
-// ---- Built-in agent-voice player (Android) ---------------------------------
+// ---- Built-in agent-voice player (Android + iOS) ----------------------------
 /**
- * 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).
+ * Returns a PcmAudioPlayer backed by the SDK's bundled native module
+ * (SessionReplayPcmPlayer): AudioTrack on Android (v0.5.0+), AVAudioEngine on
+ * iOS (v0.6.0+). Returns null when the native module isn't available (Expo Go,
+ * or host app not rebuilt / `pod install` not run 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 {