From 4266be2669a523f5a47ad982a6deb2db851e7603 Mon Sep 17 00:00:00 2001
From: Rares <rarpopa@hotmail.com>
Date: Fri, 28 Nov 2025 14:53:12 -0500
Subject: [PATCH 1/5] feat: Add automatic audio playback, internal state
 tracking for connection, conversation, and agent status, and new audio
 utilities to the `useDeepgramVoiceAgent` hook.

---
 example/src/VoiceAgent.tsx        |  50 ++--
 ios/Deepgram.mm                   | 370 +++++++++++++++---------------
 src/types/deepgram/voice-agent.ts |  16 ++
 src/useDeepgramVoiceAgent.ts      |  27 ++-
 4 files changed, 260 insertions(+), 203 deletions(-)

diff --git a/example/src/VoiceAgent.tsx b/example/src/VoiceAgent.tsx
index 5e8b40b..3b3a399 100644
--- a/example/src/VoiceAgent.tsx
+++ b/example/src/VoiceAgent.tsx
@@ -8,9 +8,13 @@ import {
   TextInput,
   Switch,
 } from 'react-native';
-import { useDeepgramVoiceAgent } from 'react-native-deepgram';
+import { useDeepgramVoiceAgent, Deepgram } from 'react-native-deepgram';
 import OptionSelect from './components/OptionSelect';
 
+declare const Buffer: {
+  from(data: Uint8Array | string, encoding?: string): { toString(encoding: string): string };
+};
+
 type ConversationEntry = {
   role: string;
   content: string;
@@ -41,9 +45,8 @@ const THINK_MODEL_OPTIONS = [
 ];
 
 const SAMPLE_RATE_OPTIONS = [
-  { label: '48 kHz', value: '48000' },
-  { label: '24 kHz', value: '24000' },
-  { label: '16 kHz', value: '16000' },
+  { label: '16 kHz (recommended)', value: '16000' },
+  { label: '8 kHz (lower quality)', value: '8000' },
 ];
 
 export default function VoiceAgent() {
@@ -64,7 +67,7 @@ export default function VoiceAgent() {
   );
   const [tagsInput, setTagsInput] = useState('demo');
   const [autoStartMic, setAutoStartMic] = useState(true);
-  const [inputSampleRate, setInputSampleRate] = useState('24000');
+  const [inputSampleRate, setInputSampleRate] = useState('16000');
   const [temperature, setTemperature] = useState('0.7');
   const [customMessage, setCustomMessage] = useState('');
 
@@ -75,7 +78,7 @@ export default function VoiceAgent() {
       .filter(Boolean);
     const resolvedListenModel = listenModel.trim() || 'nova-3';
     const resolvedThinkModel = thinkModel.trim() || 'gpt-4o';
-    const inputRate = Number(inputSampleRate) || 24_000;
+    const inputRate = Number(inputSampleRate) || 16_000;
     const parsedTemperature = parseFloat(temperature);
     const boundedTemperature = Number.isFinite(parsedTemperature)
       ? Math.max(0, Math.min(2, parsedTemperature))
@@ -84,6 +87,7 @@ export default function VoiceAgent() {
     return {
       audio: {
         input: { encoding: 'linear16', sample_rate: inputRate },
+        output: { encoding: 'linear16', sample_rate: inputRate, container: 'none' },
       },
       agent: {
         language: language.trim() || 'en',
@@ -117,11 +121,6 @@ export default function VoiceAgent() {
     thinkModel,
   ]);
 
-  const downsampleFactor = useMemo(() => {
-    const rate = Number(inputSampleRate) || 24_000;
-    return Math.max(1, Math.round(48_000 / rate));
-  }, [inputSampleRate]);
-
   const {
     connect,
     disconnect,
@@ -133,18 +132,21 @@ export default function VoiceAgent() {
   } = useDeepgramVoiceAgent({
     defaultSettings: agentSettings,
     autoStartMicrophone: autoStartMic,
-    downsampleFactor,
     onBeforeConnect: () => {
       setStatus('connecting');
       setError(null);
       setWarning(null);
       setConversation([]);
     },
-    onConnect: () => setStatus('connected'),
+    onConnect: () => {
+      setStatus('connected');
+      Deepgram.startPlayer?.(16000, 1);
+    },
     onClose: () => {
       setStatus('idle');
       setThinking(null);
       setLatency(null);
+      Deepgram.stopPlayer?.();
     },
     onError: (err) => {
       setStatus('error');
@@ -173,6 +175,20 @@ export default function VoiceAgent() {
       setStatus('error');
       setError(message.description || message.code || 'Voice agent error');
     },
+    onAudioConfig: (message: { sample_rate?: number; channels?: number }) => {
+      const sampleRate = message.sample_rate || 16000;
+      const channels = message.channels || 1;
+      Deepgram.startPlayer?.(sampleRate, channels);
+    },
+    onAudio: async (audioData: ArrayBuffer) => {
+      try {
+        const bytes = new Uint8Array(audioData);
+        const b64 = Buffer.from(bytes).toString('base64');
+        await Deepgram.feedAudio?.(b64);
+      } catch (err) {
+        console.error('[VoiceAgentDemo] onAudio error:', err);
+      }
+    },
   });
 
   const startAgent = async () => {
@@ -319,8 +335,7 @@ export default function VoiceAgent() {
 
           <View style={styles.infoBox}>
             <Text style={styles.infoText}>
-              🎧 Agent replies are delivered as text only. Speak into the
-              microphone and read the responses below.
+              🎧 The agent will respond with voice. Make sure your volume is up!
             </Text>
           </View>
 
@@ -380,11 +395,10 @@ export default function VoiceAgent() {
         {warning && <Text style={styles.warning}>Warning: {warning}</Text>}
         {error && <Text style={styles.error}>Error: {error}</Text>}
 
-        <Text style={styles.sectionTitle}>Conversation (Text Only)</Text>
+        <Text style={styles.sectionTitle}>Conversation</Text>
         <View style={styles.infoBox}>
           <Text style={styles.infoText}>
-            💬 The agent responds with text transcripts so playback can't echo
-            back into the microphone.
+            💬 Text transcripts of the conversation appear here alongside audio playback.
           </Text>
         </View>
         <View style={styles.conversation}>
diff --git a/ios/Deepgram.mm b/ios/Deepgram.mm
index dbece81..5c3bd7f 100644
--- a/ios/Deepgram.mm
+++ b/ios/Deepgram.mm
@@ -37,7 +37,7 @@
   bool isRunning;
 } DGRecordState;
 
-@interface Deepgram : RCTEventEmitter <AVAudioPlayerDelegate>
+@interface Deepgram : RCTEventEmitter
 {
   DGRecordState _recordState;
 }
@@ -49,8 +49,10 @@ @interface Deepgram : RCTEventEmitter <AVAudioPlayerDelegate>
 @property (atomic, assign) BOOL                    hasListeners;
 @property (atomic, assign) BOOL                    appIsActive;
 
-// Playback / TTS
-@property (nonatomic, strong) AVAudioPlayer      *audioPlayer;
+// Playback / TTS (AVAudioEngine-based with echo cancellation)
+@property (nonatomic, strong) AVAudioEngine      *audioEngine;
+@property (nonatomic, strong) AVAudioPlayerNode  *playerNode;
+@property (nonatomic, strong) AVAudioFormat      *playbackFormat;
 @property (nonatomic, strong) NSMutableData      *audioBuffer;
 @property (nonatomic, assign) BOOL                isPlaying;
 @property (nonatomic, assign) int                 currentSampleRate;
@@ -157,6 +159,12 @@ - (instancetype)init
                 name:AVAudioSessionRouteChangeNotification
               object:nil];
     DGLogDebug(@"[Deepgram] init: registered for AVAudioSessionRouteChangeNotification");
+    [[NSNotificationCenter defaultCenter]
+        addObserver:self
+           selector:@selector(handleAudioInterruption:)
+                name:AVAudioSessionInterruptionNotification
+              object:nil];
+    DGLogDebug(@"[Deepgram] init: registered for AVAudioSessionInterruptionNotification");
   }
   return self;
 }
@@ -353,6 +361,42 @@ - (void)handleAudioRouteChange:(NSNotification *)note
   [self activateAudioSession:NULL];
 }
 
+- (void)handleAudioInterruption:(NSNotification *)note
+{
+  DGLogDebug(@"[Deepgram] handleAudioInterruption: %@", note.userInfo);
+  NSNumber *typeValue = note.userInfo[AVAudioSessionInterruptionTypeKey];
+  AVAudioSessionInterruptionType type = (AVAudioSessionInterruptionType)typeValue.unsignedIntegerValue;
+
+  if (type == AVAudioSessionInterruptionTypeBegan) {
+    DGLogDebug(@"[Deepgram] handleAudioInterruption: interruption began");
+    if (_recordState.isRunning && _recordState.queue) {
+      DGLogDebug(@"[Deepgram] handleAudioInterruption: pausing recording queue");
+      AudioQueuePause(_recordState.queue);
+    }
+    if (self.isPlaying && self.playerNode) {
+      DGLogDebug(@"[Deepgram] handleAudioInterruption: pausing player node");
+      [self.playerNode pause];
+    }
+  } else if (type == AVAudioSessionInterruptionTypeEnded) {
+    DGLogDebug(@"[Deepgram] handleAudioInterruption: interruption ended");
+    NSNumber *optionValue = note.userInfo[AVAudioSessionInterruptionOptionKey];
+    AVAudioSessionInterruptionOptions options = (AVAudioSessionInterruptionOptions)optionValue.unsignedIntegerValue;
+    if (options & AVAudioSessionInterruptionOptionShouldResume) {
+      DGLogDebug(@"[Deepgram] handleAudioInterruption: should resume");
+      [self activateAudioSession:nil];
+      
+      if (_recordState.isRunning && _recordState.queue) {
+        DGLogDebug(@"[Deepgram] handleAudioInterruption: resuming recording queue");
+        AudioQueueStart(_recordState.queue, NULL);
+      }
+      if (self.isPlaying && self.playerNode) {
+        DGLogDebug(@"[Deepgram] handleAudioInterruption: resuming player node");
+        [self.playerNode play];
+      }
+    }
+  }
+}
+
 #if TARGET_OS_IOS
 - (void)handleAppDidBecomeActive:(NSNotification *)note
 {
@@ -697,182 +741,183 @@ - (void)cleanupRecordingQueue
 }
 
 /* ================================================================== */
-/*  2.  SIMPLE AUDIO PLAYBACK (USING AVAUDIOPLAYER)                   */
+/*  2.  AVAUDIOENGINE PLAYBACK WITH VOICE PROCESSING (ECHO CANCEL)    */
 /* ================================================================== */
 
 /**
- * Create a WAV header for PCM data.
- * This allows us to use AVAudioPlayer with raw PCM data.
+ * Setup AVAudioEngine with Voice Processing I/O for echo cancellation.
+ * This enables hardware-level echo cancellation during simultaneous recording + playback.
  */
-- (NSData *)createWAVHeaderForPCMData:(NSData *)pcmData sampleRate:(int)sampleRate {
-  uint32_t dataSize = (uint32_t)pcmData.length;
-  uint32_t fileSize = 36 + dataSize;
-  uint16_t channels = 1;
-  uint16_t bitsPerSample = 16;
-  uint32_t byteRate = sampleRate * channels * (bitsPerSample / 8);
-  uint16_t blockAlign = channels * (bitsPerSample / 8);
+- (BOOL)setupAudioEngineWithSampleRate:(int)sampleRate
+                              channels:(int)channels
+                                 error:(NSError **)outError {
+  if (self.audioEngine && self.audioEngine.isRunning) {
+    [self.audioEngine stop];
+  }
   
-  NSMutableData *wavData = [NSMutableData data];
+  self.audioEngine = [[AVAudioEngine alloc] init];
+  self.playerNode = [[AVAudioPlayerNode alloc] init];
   
-  // RIFF header
-  [wavData appendBytes:"RIFF" length:4];
-  [wavData appendBytes:&fileSize length:4];
-  [wavData appendBytes:"WAVE" length:4];
+  self.playbackFormat = [[AVAudioFormat alloc]
+                         initWithCommonFormat:AVAudioPCMFormatInt16
+                         sampleRate:sampleRate
+                         channels:channels
+                         interleaved:YES];
   
-  // fmt chunk
-  [wavData appendBytes:"fmt " length:4];
-  uint32_t fmtSize = 16;
-  [wavData appendBytes:&fmtSize length:4];
-  uint16_t audioFormat = 1; // PCM
-  [wavData appendBytes:&audioFormat length:2];
-  [wavData appendBytes:&channels length:2];
-  uint32_t sampleRateValue = sampleRate;
-  [wavData appendBytes:&sampleRateValue length:4];
-  [wavData appendBytes:&byteRate length:4];
-  [wavData appendBytes:&blockAlign length:2];
-  [wavData appendBytes:&bitsPerSample length:2];
+  if (!self.playbackFormat) {
+    if (outError) {
+      *outError = [NSError errorWithDomain:@"DeepgramAudioEngine"
+                                      code:-1
+                                  userInfo:@{NSLocalizedDescriptionKey: @"Failed to create audio format"}];
+    }
+    return NO;
+  }
+  
+  [self.audioEngine attachNode:self.playerNode];
+  [self.audioEngine connect:self.playerNode
+                         to:self.audioEngine.mainMixerNode
+                     format:self.playbackFormat];
+  
+  @try {
+    AVAudioInputNode *inputNode = self.audioEngine.inputNode;
+    if (inputNode) {
+      NSError *voiceProcessingError = nil;
+      [inputNode setVoiceProcessingEnabled:YES error:&voiceProcessingError];
+    }
+  } @catch (NSException *exception) {
+    // Continue - voice processing not critical for basic playback
+  }
   
-  // data chunk
-  [wavData appendBytes:"data" length:4];
-  [wavData appendBytes:&dataSize length:4];
-  [wavData appendData:pcmData];
+  [self.audioEngine prepare];
+  NSError *startError = nil;
+  BOOL started = [self.audioEngine startAndReturnError:&startError];
   
-  return wavData;
+  if (!started) {
+    DGLogError(@"[Deepgram] Failed to start audio engine: %@", startError.localizedDescription);
+    if (outError) {
+      *outError = startError;
+    }
+    return NO;
+  }
+  
+  return YES;
 }
 
-RCT_EXPORT_METHOD(startPlayer
-                  :(nonnull NSNumber *)sampleRate
+/**
+ * Create AVAudioPCMBuffer from raw PCM data.
+ */
+- (AVAudioPCMBuffer *)createPCMBufferFromData:(NSData *)data {
+  if (!data || data.length == 0 || !self.playbackFormat) {
+    return nil;
+  }
+  
+  // Calculate frame count (data length / bytes per frame)
+  const AudioStreamBasicDescription *asbd = self.playbackFormat.streamDescription;
+  int bytesPerFrame = asbd->mBytesPerFrame;
+  AVAudioFrameCount frameCount = (AVAudioFrameCount)(data.length / bytesPerFrame);
+  
+  if (frameCount == 0) {
+    return nil;
+  }
+  
+  AVAudioPCMBuffer *buffer = [[AVAudioPCMBuffer alloc]
+                             initWithPCMFormat:self.playbackFormat
+                             frameCapacity:frameCount];
+  
+  buffer.frameLength = frameCount;
+  
+  // Copy audio data to buffer
+  memcpy(buffer.int16ChannelData[0], data.bytes, data.length);
+  
+  return buffer;
+}
+
+RCT_EXPORT_METHOD(startPlayer:(nonnull NSNumber *)sampleRate
                   channels:(nonnull NSNumber *)channels)
 {
-  DGLogDebug(@"[Deepgram] startPlayer: begin sampleRate=%@ channels=%@",
-        sampleRate,
-        channels);
   [self stopPlayer:nil rejecter:nil];
+  
   NSError *sessionError = nil;
   if (![self activateAudioSession:&sessionError]) {
-    DGLogWarn(@"[Deepgram] Unable to activate audio session for playback: %@",
-          sessionError.localizedDescription ?: sessionError);
+    DGLogWarn(@"[Deepgram] Unable to activate audio session: %@", sessionError);
+    return;
+  }
+
+  NSError *engineError = nil;
+  if (![self setupAudioEngineWithSampleRate:sampleRate.intValue
+                                   channels:channels.intValue
+                                      error:&engineError]) {
+    DGLogError(@"[Deepgram] Failed to setup audio engine: %@", engineError);
     return;
   }
 
   self.audioBuffer = [[NSMutableData alloc] init];
   self.isPlaying = NO;
   self.currentSampleRate = sampleRate.intValue;
-  DGLogDebug(@"[Deepgram] startPlayer: initialized buffer sampleRate=%d",
-        self.currentSampleRate);
 }
 
 /**
- * Add audio data to the buffer for streaming playback.
+ * Feed base64-encoded PCM audio data for playback using AVAudioEngine.
+ * Uses real-time PCM buffer streaming instead of WAV files.
  */
 RCT_EXPORT_METHOD(feedAudio:(NSString *)b64)
 {
-  DGLogDebug(@"[Deepgram] feedAudio: begin length=%lu", (unsigned long)b64.length);
-  if (!self.audioBuffer) {
-    // Use default sample rate if not set
-    int defaultSampleRate = self.currentSampleRate > 0 ? self.currentSampleRate : 16000;
-    DGLogDebug(@"[Deepgram] feedAudio: auto startPlayer defaultSampleRate=%d", defaultSampleRate);
-    [self startPlayer:@(defaultSampleRate) channels:@1];
-  }
-
-  NSData *pcmData = [[NSData alloc] initWithBase64EncodedString:b64 options:0];
-  if (!pcmData || pcmData.length == 0) {
-    DGLogDebug(@"[Deepgram] feedAudio: decoded data empty");
-    return;
-  }
-
-  [self.audioBuffer appendData:pcmData];
-  DGLogDebug(@"[Deepgram] feedAudio: appended %lu bytes (buffer=%lu)",
-        (unsigned long)pcmData.length,
-        (unsigned long)self.audioBuffer.length);
-
-  if (!self.isPlaying && self.audioBuffer.length > 1000) {
-    DGLogDebug(@"[Deepgram] feedAudio: triggering playback");
-    [self playAccumulatedAudio];
-  }
-}
-
-/**
- * Play accumulated audio buffer for streaming.
- */
-- (void)playAccumulatedAudio {
-  if (!self.audioBuffer || self.audioBuffer.length == 0) {
-    DGLogDebug(@"[Deepgram] playAccumulatedAudio: no buffered audio");
-    return;
-  }
-
-  NSData *wavData = [self createWAVHeaderForPCMData:self.audioBuffer sampleRate:self.currentSampleRate];
-
-  NSError *error = nil;
-  AVAudioPlayer *player = [[AVAudioPlayer alloc] initWithData:wavData error:&error];
-
-  if (error) {
-    DGLogError(@"[Deepgram] playAccumulatedAudio: player error=%@", error);
-    return;
-  }
-
-  self.audioPlayer = player;
-  self.audioPlayer.delegate = self;
-
-  self.isPlaying = YES;
-  [player prepareToPlay];
-  BOOL success = [player play];
-
-  if (success) {
-    DGLogDebug(@"[Deepgram] playAccumulatedAudio: playback started, clearing buffer");
-    [self.audioBuffer setLength:0];
-  } else {
-    DGLogError(@"[Deepgram] playAccumulatedAudio: failed to start playback");
-    self.isPlaying = NO;
+  @try {
+    if (!self.playerNode || !self.audioEngine || !self.audioEngine.isRunning) {
+      return;
+    }
+    
+    NSData *pcmData = [[NSData alloc] initWithBase64EncodedString:b64 options:0];
+    if (!pcmData || pcmData.length == 0) {
+      return;
+    }
+    
+    AVAudioPCMBuffer *buffer = [self createPCMBufferFromData:pcmData];
+    if (!buffer) {
+      DGLogError(@"[Deepgram] feedAudio: failed to create PCM buffer");
+      return;
+    }
+    
+    [self.playerNode scheduleBuffer:buffer completionHandler:nil];
+    
+    if (!self.playerNode.isPlaying) {
+      [self.playerNode play];
+    }
   }
-}
-
-/**
- * Play PCM data immediately using AVAudioPlayer.
- */
-- (void)playPCMData:(NSData *)pcmData {
-  DGLogDebug(@"[Deepgram] playPCMData: begin length=%lu", (unsigned long)pcmData.length);
-  NSData *wavData = [self createWAVHeaderForPCMData:pcmData sampleRate:self.currentSampleRate];
-
-  NSError *error = nil;
-  AVAudioPlayer *player = [[AVAudioPlayer alloc] initWithData:wavData error:&error];
-
-  if (error) {
-    DGLogError(@"[Deepgram] playPCMData: player error=%@", error);
-    return;
+  @catch (NSException *e) {
+    DGLogError(@"[Deepgram] feedAudio: exception %@", e);
   }
-
-  self.audioPlayer = player;
-  [player prepareToPlay];
-  DGLogDebug(@"[Deepgram] playPCMData: playing");
-  [player play];
-}
-
 /**
- * Stop and cleanup the audio player.
+ * Stop audio playback and cleanup AVAudioEngine.
  */
 RCT_EXPORT_METHOD(stopPlayer
                   :(RCTPromiseResolveBlock)resolve
                   rejecter:(RCTPromiseRejectBlock)reject)
 {
   @try {
-    DGLogDebug(@"[Deepgram] stopPlayer: begin");
-    if (self.audioPlayer) {
-      [self.audioPlayer stop];
-      DGLogDebug(@"[Deepgram] stopPlayer: stopped audioPlayer");
-      self.audioPlayer = nil;
+    
+    // Stop player node
+    if (self.playerNode) {
+      [self.playerNode stop];
     }
-
+    
+    // Stop and cleanup audio engine
+    if (self.audioEngine && self.audioEngine.isRunning) {
+      [self.audioEngine stop];
+    }
+    
+    // Clear properties
+    self.playerNode = nil;
+    self.audioEngine = nil;
+    self.playbackFormat = nil;
     self.audioBuffer = nil;
     self.isPlaying = NO;
 
     [self maybeDeactivateAudioSession];
 
-    DGLogDebug(@"[Deepgram] stopPlayer: success");
     if (resolve) resolve(nil);
   }
   @catch (NSException *e) {
-    DGLogError(@"[Deepgram] Error stopping player: %@", e.reason);
     DGLogError(@"[Deepgram] stopPlayer: exception %@", e);
     if (reject) reject(@"player_stop_error", e.reason, nil);
   }
@@ -889,34 +934,6 @@ - (void)playPCMData:(NSData *)pcmData {
   [self startPlayer:sampleRate channels:channels];
 }
 
-/**
- * Play a single audio chunk (one-shot playback).
- */
-RCT_EXPORT_METHOD(playAudioChunk
-                  :(NSString *)chunk
-                  resolver:(RCTPromiseResolveBlock)resolve
-                  rejecter:(RCTPromiseRejectBlock)reject)
-{
-  @try {
-    DGLogDebug(@"[Deepgram] playAudioChunk: begin");
-    NSData *pcmData = [[NSData alloc] initWithBase64EncodedString:chunk options:0];
-    if (!pcmData) {
-      DGLogError(@"[Deepgram] playAudioChunk: failed to decode base64");
-      if (reject) reject(@"invalid_data", @"Failed to decode audio data", nil);
-      return;
-    }
-
-    [self playPCMData:pcmData];
-
-    DGLogDebug(@"[Deepgram] playAudioChunk: success");
-    if (resolve) resolve(nil);
-  }
-  @catch (NSException *e) {
-    DGLogError(@"[Deepgram] playAudioChunk: exception %@", e);
-    if (reject) reject(@"playback_error", e.reason, nil);
-  }
-}
-
 - (void)invalidate
 {
   DGLogDebug(@"[Deepgram] invalidate: begin");
@@ -929,10 +946,16 @@ - (void)invalidate
 
   self.pendingPCMBuffer = nil;
 
-  if (self.audioPlayer) {
-    [self.audioPlayer stop];
-    self.audioPlayer = nil;
+  if (self.playerNode) {
+    [self.playerNode stop];
+    self.playerNode = nil;
+  }
+  
+  if (self.audioEngine && self.audioEngine.isRunning) {
+    [self.audioEngine stop];
   }
+  self.audioEngine = nil;
+  self.playbackFormat = nil;
 
   self.audioBuffer = nil;
   self.isPlaying = NO;
@@ -945,23 +968,4 @@ - (void)invalidate
   [super invalidate];
 }
 
-/* ================================================================== */
-/*  3.  AVAUDIOPLAYER DELEGATE METHODS                                */
-/* ================================================================== */
-
-- (void)audioPlayerDidFinishPlaying:(AVAudioPlayer *)player successfully:(BOOL)flag {
-  DGLogDebug(@"[Deepgram] audioPlayerDidFinishPlaying: success=%@", flag ? @"YES" : @"NO");
-  self.isPlaying = NO;
-
-  if (self.audioBuffer && self.audioBuffer.length > 0) {
-    DGLogDebug(@"[Deepgram] audioPlayerDidFinishPlaying: playing remaining buffered audio");
-    [self playAccumulatedAudio];
-  }
-}
-
-- (void)audioPlayerDecodeErrorDidOccur:(AVAudioPlayer *)player error:(NSError *)error {
-  DGLogError(@"[Deepgram] audioPlayerDecodeErrorDidOccur: error=%@", error);
-  self.isPlaying = NO;
-}
-
 @end
diff --git a/src/types/deepgram/voice-agent.ts b/src/types/deepgram/voice-agent.ts
index fa076e3..e56b4e3 100644
--- a/src/types/deepgram/voice-agent.ts
+++ b/src/types/deepgram/voice-agent.ts
@@ -243,6 +243,20 @@ export interface DeepgramVoiceAgentWarningMessage {
   [key: string]: unknown;
 }
 
+export interface DeepgramVoiceAgentAudioConfigMessage {
+  type: 'AudioConfig';
+  sample_rate?: number;
+  channels?: number;
+  encoding?: string;
+  [key: string]: unknown;
+}
+
+export interface DeepgramVoiceAgentAudioMessage {
+  type: 'Audio';
+  // Binary audio data will be in the WebSocket message payload
+  [key: string]: unknown;
+}
+
 export type DeepgramVoiceAgentServerMessage =
   | DeepgramVoiceAgentWelcomeMessage
   | DeepgramVoiceAgentSettingsAppliedMessage
@@ -258,6 +272,8 @@ export type DeepgramVoiceAgentServerMessage =
   | DeepgramVoiceAgentInjectionRefusedMessage
   | DeepgramVoiceAgentErrorMessage
   | DeepgramVoiceAgentWarningMessage
+  | DeepgramVoiceAgentAudioConfigMessage
+  | DeepgramVoiceAgentAudioMessage
   | DeepgramVoiceAgentSettingsMessage
   | DeepgramVoiceAgentUpdateSpeakMessage
   | DeepgramVoiceAgentInjectUserMessage
diff --git a/src/useDeepgramVoiceAgent.ts b/src/useDeepgramVoiceAgent.ts
index 3cdce97..20f5747 100644
--- a/src/useDeepgramVoiceAgent.ts
+++ b/src/useDeepgramVoiceAgent.ts
@@ -22,6 +22,7 @@ import type {
   DeepgramVoiceAgentInjectionRefusedMessage,
   DeepgramVoiceAgentWarningMessage,
   DeepgramVoiceAgentErrorMessage,
+  DeepgramVoiceAgentAudioConfigMessage,
 } from './types';
 
 const DEFAULT_AGENT_ENDPOINT = 'wss://agent.deepgram.com/v1/agent/converse';
@@ -203,6 +204,8 @@ export interface UseDeepgramVoiceAgentProps {
   ) => void;
   onWarning?: (message: DeepgramVoiceAgentWarningMessage) => void;
   onServerError?: (message: DeepgramVoiceAgentErrorMessage) => void;
+  onAudioConfig?: (message: DeepgramVoiceAgentAudioConfigMessage) => void;
+  onAudio?: (audioData: ArrayBuffer) => void;
 }
 
 export interface UseDeepgramVoiceAgentReturn {
@@ -245,6 +248,8 @@ export function useDeepgramVoiceAgent({
   onInjectionRefused,
   onWarning,
   onServerError,
+  onAudioConfig,
+  onAudio,
 }: UseDeepgramVoiceAgentProps = {}): UseDeepgramVoiceAgentReturn {
   const ws = useRef<WebSocketLike | null>(null);
   const audioSub = useRef<ReturnType<NativeEventEmitter['addListener']> | null>(
@@ -282,6 +287,8 @@ export function useDeepgramVoiceAgent({
   const onInjectionRefusedRef = useRef(onInjectionRefused);
   const onWarningRef = useRef(onWarning);
   const onServerErrorRef = useRef(onServerError);
+  const onAudioConfigRef = useRef(onAudioConfig);
+  const onAudioRef = useRef(onAudio);
   const autoStartMicRef = useRef(autoStartMicrophone);
 
   const sanitizeAudioSettings = useCallback(
@@ -418,6 +425,8 @@ export function useDeepgramVoiceAgent({
   onInjectionRefusedRef.current = onInjectionRefused;
   onWarningRef.current = onWarning;
   onServerErrorRef.current = onServerError;
+  onAudioConfigRef.current = onAudioConfig;
+  onAudioRef.current = onAudio;
   autoStartMicRef.current = autoStartMicrophone;
   if (downsampleFactor != null) {
     currentDownsample.current = downsampleFactor;
@@ -432,6 +441,9 @@ export function useDeepgramVoiceAgent({
       microphoneActive.current = false;
     }
 
+    // Cleanup audio session for playback
+    Deepgram.stopAudio().catch(() => {});
+
     const socket = ws.current;
     if (socket) {
       ws.current = null;
@@ -587,8 +599,14 @@ export function useDeepgramVoiceAgent({
               );
               break;
             case 'Audio':
+              // Audio binary data will be handled by onmessage binary path
+              break;
             case 'AudioConfig':
-              // Audio responses are ignored in text-only mode.
+              if (hasKeys(message, ['sample_rate'])) {
+                onAudioConfigRef.current?.(
+                  message as DeepgramVoiceAgentAudioConfigMessage
+                );
+              }
               break;
             case 'InjectionRefused':
               if (hasKeys(message, ['message'])) {
@@ -637,7 +655,8 @@ export function useDeepgramVoiceAgent({
 
       const buffer = ensureArrayBuffer(ev.data);
       if (buffer) {
-        // Binary audio responses are ignored in text-only mode.
+        // Binary audio from server
+        onAudioRef.current?.(buffer);
       }
     },
     [
@@ -740,6 +759,10 @@ export function useDeepgramVoiceAgent({
         if (eventName) {
           audioSub.current = emitter.addListener(eventName, handleMicChunk);
         }
+      } else {
+        // Only initialize audio session for playback if not recording
+        // (startRecording already activates the audio session)
+        await Deepgram.startAudio();
       }
 
       const sanitizedDefault = sanitizeSettings(defaultSettingsRef.current);

From 73ff7af6bc56e58e0c35b785fba5c5d25f0e2d9c Mon Sep 17 00:00:00 2001
From: Rares <rarpopa@hotmail.com>
Date: Fri, 28 Nov 2025 16:43:52 -0500
Subject: [PATCH 2/5] feat: add useAsyncCall hook and enhance Deepgram API
 hooks with state tracking

- Introduced `useAsyncCall` hook for managing asynchronous calls with loading and error states.
- Updated `index.ts` to export new helper functions.
- Enhanced `useDeepgramSpeechToText`, `useDeepgramTextIntelligence`, and `useDeepgramTextToSpeech` hooks to support internal state tracking.
- Added `trackState` and `trackTranscript` options to `useDeepgramSpeechToText` for managing transcription state.
- Implemented conversation tracking in `useDeepgramVoiceAgent` with `trackConversation` option.
- Improved type definitions in Deepgram management and speech-to-text interfaces with detailed comments.
- Added support for agent status tracking in `useDeepgramVoiceAgent`.
---
 README.md                               |  45 +++++-
 example/src/SpeechToText.tsx            | 120 ++++++--------
 example/src/TextIntelligence.tsx        |  28 ++--
 example/src/TextToSpeech.tsx            |  80 ++++------
 example/src/VoiceAgent.tsx              | 179 ++++++---------------
 ios/Deepgram.mm                         |  78 +++++++++
 package.json                            |   5 +-
 src/helpers/audioUtils.ts               |  32 ++++
 src/helpers/createAgentSettings.ts      |  76 +++++++++
 src/helpers/index.ts                    |   3 +
 src/helpers/useAsyncCall.ts             |  52 ++++++
 src/index.ts                            |   6 +
 src/types/deepgram/management.ts        |  38 +++++
 src/types/deepgram/shared.ts            |   8 +
 src/types/deepgram/speech-to-text.ts    |  71 +++++++++
 src/types/deepgram/text-intelligence.ts |  35 ++++
 src/types/deepgram/text-to-speech.ts    |  56 +++++++
 src/types/deepgram/voice-agent.ts       |  24 +++
 src/useDeepgramSpeechToText.ts          |  85 +++++++++-
 src/useDeepgramTextIntelligence.ts      |  25 ++-
 src/useDeepgramTextToSpeech.ts          |  74 +++++++--
 src/useDeepgramVoiceAgent.ts            | 202 +++++++++++++++++++++---
 22 files changed, 1006 insertions(+), 316 deletions(-)
 create mode 100644 src/helpers/audioUtils.ts
 create mode 100644 src/helpers/createAgentSettings.ts
 create mode 100644 src/helpers/useAsyncCall.ts

diff --git a/README.md b/README.md
index a676858..7047212 100644
--- a/README.md
+++ b/README.md
@@ -135,22 +135,33 @@ configure({ apiKey: 'YOUR_DEEPGRAM_API_KEY' });
 | `useDeepgramTextIntelligence` | Text analysis (summaries, topics, intents, sentiment) |
 | `useDeepgramManagement`       | Typed wrapper around the Management REST API         |
 
+> 💡 **Pro tip**: All hooks now export a `state` object (and other reactive values) so you can easily track connection status, errors, and transcripts without maintaining your own state.
+
 ---
 
 ## Voice Agent (`useDeepgramVoiceAgent`)
 
 `useDeepgramVoiceAgent` connects to `wss://agent.deepgram.com/v1/agent/converse`, captures microphone audio, and optionally auto-plays the agent's streamed responses. It wraps the full Voice Agent messaging surface so you can react to conversation updates, function calls, warnings, and raw PCM audio.
 
+> 🔊 **Audio Handling**: This hook uses `AVAudioEngine` on iOS for hardware-accelerated echo cancellation, ensuring the agent doesn't hear itself speak. It also manages the audio session automatically.
+
 ### Quick start
 
 ```tsx
 const {
   connect,
   disconnect,
+  state, // { connectionState, error, warning }
+  agentStatus, // { thinking, latency }
+  conversation, // Array<{ role, content }>
   injectUserMessage,
   sendFunctionCallResponse,
   updatePrompt,
 } = useDeepgramVoiceAgent({
+  trackState: true, // Enable reactive state tracking
+  trackConversation: true, // Enable conversation history tracking
+  trackAgentStatus: true, // Enable agent status tracking
+  autoPlayAudio: true, // Automatically play agent audio
   defaultSettings: {
     audio: {
       input: { encoding: 'linear16', sample_rate: 24_000 },
@@ -207,6 +218,7 @@ const rePrompt = () => {
 
 return (
   <>
+    <Text>Status: {state.connectionState}</Text>
     <Button title="Start agent" onPress={begin} />
     <Button title="Ask" onPress={askQuestion} />
     <Button title="Send tool output" onPress={provideTooling} />
@@ -227,6 +239,10 @@ return (
 | `endpoint` | `string` | WebSocket endpoint used for the agent conversation (defaults to `wss://agent.deepgram.com/v1/agent/converse`). |
 | `defaultSettings` | `DeepgramVoiceAgentSettings` | Base `Settings` payload sent on connect; merge per-call overrides via `connect(override)`. |
 | `autoStartMicrophone` | `boolean` | Automatically requests mic access and starts streaming PCM when `true` (default). |
+| `autoPlayAudio` | `boolean` | Automatically plays received audio using the native player (default: `true`). |
+| `trackState` | `boolean` | Enable reactive state tracking (connection, errors, warnings) via the `state` return value (default: `false`). |
+| `trackConversation` | `boolean` | Enable conversation history tracking via the `conversation` return value (default: `false`). |
+| `trackAgentStatus` | `boolean` | Enable agent status tracking (thinking, latency) via the `agentStatus` return value (default: `false`). |
 | `downsampleFactor` | `number` | Manually override the downsample ratio applied to captured audio (defaults to a heuristic based on the requested sample rate). |
 
 #### Callbacks
@@ -268,6 +284,10 @@ return (
 | `updatePrompt` | `(prompt: string) => boolean` | Replaces the active system prompt. |
 | `sendMedia` | `(chunk: ArrayBuffer \| Uint8Array \| number[]) => boolean` | Streams additional PCM audio to the agent (e.g., pre-recorded buffers). |
 | `isConnected` | `() => boolean` | Returns `true` when the socket is open. |
+| `clearConversation` | `() => void` | Clears the internal conversation history. |
+| `state` | `DeepgramVoiceAgentState` | Reactive state object (requires `trackState: true`). |
+| `conversation` | `DeepgramVoiceAgentConversationMessage[]` | Reactive conversation history (requires `trackConversation: true`). |
+| `agentStatus` | `DeepgramVoiceAgentStatus` | Reactive agent status (requires `trackAgentStatus: true`). |
 
 #### Settings payload (`DeepgramVoiceAgentSettings`)
 
@@ -301,7 +321,14 @@ The speech hook streams microphone audio using WebSockets and can also transcrib
 ### Live streaming quick start
 
 ```tsx
-const { startListening, stopListening } = useDeepgramSpeechToText({
+const {
+  startListening,
+  stopListening,
+  state, // { status, error }
+  transcript, // "Hello world..."
+} = useDeepgramSpeechToText({
+  trackState: true,
+  trackTranscript: true,
   onTranscript: console.log,
   live: {
     apiVersion: 'v2',
@@ -311,6 +338,7 @@ const { startListening, stopListening } = useDeepgramSpeechToText({
   },
 });
 
+<Text>Transcript: {transcript}</Text>
 <Button
   title="Start"
   onPress={() => startListening({ keywords: ['Deepgram'] })}
@@ -355,6 +383,8 @@ const pickFile = async () => {
 | `onTranscribeError`    | `(error: unknown) => void`     | Fired if prerecorded transcription fails.                       |
 | `live`                 | `DeepgramLiveListenOptions`    | Default options merged into every live stream.                  |
 | `prerecorded`          | `DeepgramPrerecordedOptions`   | Default options merged into every file transcription.           |
+| `trackState`           | `boolean`                      | Enable reactive state tracking via the `state` return value (default: `false`). |
+| `trackTranscript`      | `boolean`                      | Enable reactive transcript tracking via the `transcript` return value (default: `false`). |
 
 #### Returned methods
 
@@ -363,6 +393,9 @@ const pickFile = async () => {
 | `startListening`   | `(options?: DeepgramLiveListenOptions) => Promise<void>`                         | Requests mic access, starts recording, and streams audio to Deepgram.       |
 | `stopListening`    | `() => void`                                                                     | Stops recording and closes the active WebSocket.                            |
 | `transcribeFile`   | `(file: DeepgramPrerecordedSource, options?: DeepgramPrerecordedOptions) => Promise<void>` | Uploads a file/URI/URL and resolves via the success/error callbacks. |
+| `state`            | `DeepgramSpeechToTextState`                                                      | Reactive state object (requires `trackState: true`).                        |
+| `transcript`       | `string`                                                                         | Reactive final transcript (requires `trackTranscript: true`).               |
+| `interimTranscript`| `string`                                                                         | Reactive interim transcript (requires `trackTranscript: true`).             |
 
 #### Live transcription options (`DeepgramLiveListenOptions`)
 
@@ -487,7 +520,10 @@ const {
   clearStream,
   closeStreamGracefully,
   stopStreaming,
+  state, // { status, error }
 } = useDeepgramTextToSpeech({
+  trackState: true,
+  autoPlayAudio: true, // Automatically play received audio
   options: {
     stream: {
       model: 'aura-2-asteria-en',
@@ -525,6 +561,8 @@ closeStreamGracefully();
 | `onStreamError`      | `(error: unknown) => void`                                            | Fired when the WebSocket errors.                                            |
 | `onStreamEnd`        | `() => void`                                                          | Fired when the stream closes (gracefully or otherwise).                     |
 | `options`            | `UseDeepgramTextToSpeechOptions`                                     | Default configuration merged into HTTP and streaming requests.              |
+| `autoPlayAudio`      | `boolean`                                                             | Automatically plays received audio using the native player (default: `true`). |
+| `trackState`         | `boolean`                                                             | Enable reactive state tracking via the `state` return value (default: `false`). |
 
 #### Returned methods
 
@@ -538,6 +576,7 @@ closeStreamGracefully();
 | `clearStream`         | `() => boolean`                                                           | Clears buffered text/audio without closing the socket.                                         |
 | `closeStreamGracefully` | `() => boolean`                                                         | Asks Deepgram to finish outstanding audio then close the stream.                               |
 | `stopStreaming`       | `() => void`                                                              | Force-closes the socket and releases resources.                                                |
+| `state`               | `DeepgramTextToSpeechState`                                               | Reactive state object (requires `trackState: true`).                                            |
 
 #### Configuration (`UseDeepgramTextToSpeechOptions`)
 
@@ -604,7 +643,8 @@ closeStreamGracefully();
 Run summarisation, topic detection, intent detection, sentiment analysis, and more over plain text or URLs.
 
 ```tsx
-const { analyze } = useDeepgramTextIntelligence({
+const { analyze, state } = useDeepgramTextIntelligence({
+  trackState: true,
   onAnalyzeSuccess: (result) => console.log(result.summary),
   options: {
     summarize: true,
@@ -632,6 +672,7 @@ await analyze({ text: 'Deepgram makes voice data useful.' });
 | `language`         | `DeepgramTextIntelligenceLanguage`          | BCP-47 language hint (defaults to `'en'`).                                   |
 | `callback`         | `string`                                    | Webhook URL invoked after processing completes.                              |
 | `callbackMethod`   | `'POST' \| 'PUT' \| (string & {})`          | HTTP method used for the callback.                                           |
+| `trackState`       | `boolean`                                    | Enable reactive state tracking via the `state` return value (default: `false`). |
 
 ---
 
diff --git a/example/src/SpeechToText.tsx b/example/src/SpeechToText.tsx
index be0b90c..6af5479 100644
--- a/example/src/SpeechToText.tsx
+++ b/example/src/SpeechToText.tsx
@@ -11,76 +11,48 @@ import * as DocumentPicker from 'expo-document-picker';
 import { useDeepgramSpeechToText } from 'react-native-deepgram';
 
 export default function SpeechToText() {
-  // live stream state
   const [liveTranscript, setLiveTranscript] = useState('');
-  const [liveStatus, setLiveStatus] = useState<'idle' | 'listening' | 'error'>(
-    'idle'
-  );
-  const [liveError, setLiveError] = useState<string | null>(null);
   const [liveInterimTranscript, setLiveInterimTranscript] = useState('');
-
-  // file transcription state
   const [fileTranscript, setFileTranscript] = useState('');
-  const [fileStatus, setFileStatus] = useState<
-    'idle' | 'transcribing' | 'error'
-  >('idle');
-  const [fileError, setFileError] = useState<string | null>(null);
 
-  const { startListening, stopListening, transcribeFile } =
-    useDeepgramSpeechToText({
-      onBeforeStart: () => {
-        setLiveStatus('listening');
-        setLiveTranscript('');
-        setLiveInterimTranscript('');
-        setLiveError(null);
-      },
-      onStart: () => {
-        // WebSocket opened
-      },
-      onTranscript: (text, info) => {
-        if (info?.isFinal) {
-          setLiveTranscript((prev) => {
-            const next = prev ? `${prev} ${text}` : text;
-            return next.trim();
-          });
-          setLiveInterimTranscript('');
-        } else {
-          setLiveInterimTranscript(text);
-        }
-      },
-      onError: (err) => {
-        setLiveStatus('error');
-        setLiveError(err instanceof Error ? err.message : String(err));
-        setLiveInterimTranscript('');
-      },
-      onEnd: () => {
-        setLiveStatus('idle');
+  const {
+    startListening,
+    stopListening,
+    state: liveState,
+  } = useDeepgramSpeechToText({
+    trackState: true,
+    onBeforeStart: () => {
+      setLiveTranscript('');
+      setLiveInterimTranscript('');
+    },
+    onTranscript: (text, info) => {
+      if (info?.isFinal) {
+        setLiveTranscript((prev) => {
+          const next = prev ? `${prev} ${text}` : text;
+          return next.trim();
+        });
         setLiveInterimTranscript('');
-      },
-      // file callbacks
-      onBeforeTranscribe: () => {
-        setFileStatus('transcribing');
-        setFileTranscript('');
-        setFileError(null);
-      },
-      onTranscribeSuccess: (text) => {
-        setFileStatus('idle');
-        setFileTranscript(text);
-      },
-      onTranscribeError: (err) => {
-        setFileStatus('error');
-        setFileError(err instanceof Error ? err.message : String(err));
-      },
-      live: {
-        model: 'nova-2',
-        interimResults: true,
-        punctuate: true,
-      },
-      prerecorded: {
-        punctuate: true,
-        summarize: 'v2',
-      },
-    });
+      } else {
+        setLiveInterimTranscript(text);
+      }
+    },
+    onEnd: () => setLiveInterimTranscript(''),
+    live: {
+      model: 'nova-2',
+      interimResults: true,
+      punctuate: true,
+    },
+  });
+
+  const { transcribeFile, state: fileState } = useDeepgramSpeechToText({
+    trackState: true,
+    onBeforeTranscribe: () => setFileTranscript(''),
+    onTranscribeSuccess: setFileTranscript,
+    prerecorded: {
+      punctuate: true,
+      summarize: 'v2',
+    },
+  });
 
   const pickAndTranscribe = async () => {
     try {
@@ -118,18 +90,20 @@ export default function SpeechToText() {
         <Button
           title="Start Listening"
           onPress={() => startListening({ keywords: ['Deepgram'] })}
-          disabled={liveStatus === 'listening'}
+          disabled={liveState?.status === 'listening'}
         />
         <Button
           title="Stop Listening"
           onPress={stopListening}
-          disabled={liveStatus !== 'listening'}
+          disabled={liveState?.status !== 'listening'}
         />
       </View>
-      {liveStatus === 'listening' && (
+      {liveState?.status === 'listening' && (
         <Text style={styles.status}>Listening…</Text>
       )}
-      {liveError && <Text style={styles.error}>Error: {liveError}</Text>}
+      {liveState?.error && (
+        <Text style={styles.error}>Error: {liveState.error.message}</Text>
+      )}
       <ScrollView style={styles.outputContainer}>
         <Text style={styles.transcript}>
           🎤 Live: {combinedLiveTranscript || 'No live transcript yet.'}
@@ -141,13 +115,15 @@ export default function SpeechToText() {
         <Button
           title="Pick & Transcribe File"
           onPress={pickAndTranscribe}
-          disabled={fileStatus === 'transcribing'}
+          disabled={fileState?.status === 'transcribing'}
         />
       </View>
-      {fileStatus === 'transcribing' && (
+      {fileState?.status === 'transcribing' && (
         <Text style={styles.status}>Transcribing file…</Text>
       )}
-      {fileError && <Text style={styles.error}>File error: {fileError}</Text>}
+      {fileState?.error && (
+        <Text style={styles.error}>File error: {fileState.error.message}</Text>
+      )}
       <ScrollView style={styles.outputContainer}>
         <Text style={styles.transcript}>
           📄 File: {fileTranscript || 'No file transcript yet.'}
diff --git a/example/src/TextIntelligence.tsx b/example/src/TextIntelligence.tsx
index 8345b06..960a3b2 100644
--- a/example/src/TextIntelligence.tsx
+++ b/example/src/TextIntelligence.tsx
@@ -12,10 +12,9 @@ import { useDeepgramTextIntelligence } from 'react-native-deepgram';
 export default function TextIntelligence() {
   const [input, setInput] = useState<string>('');
   const [result, setResult] = useState<any>(null);
-  const [error, setError] = useState<string | null>(null);
-  const [loading, setLoading] = useState<boolean>(false);
 
-  const { analyze } = useDeepgramTextIntelligence({
+  const { analyze, state } = useDeepgramTextIntelligence({
+    trackState: true,
     options: {
       summarize: true,
       topics: true,
@@ -27,19 +26,8 @@ export default function TextIntelligence() {
       sentiment: true,
       language: 'en-US',
     },
-    onBeforeAnalyze: () => {
-      setLoading(true);
-      setError(null);
-      setResult(null);
-    },
-    onAnalyzeSuccess: (res) => {
-      setLoading(false);
-      setResult(res);
-    },
-    onAnalyzeError: (err) => {
-      setLoading(false);
-      setError(err.message);
-    },
+    onBeforeAnalyze: () => setResult(null),
+    onAnalyzeSuccess: setResult,
   });
 
   const handleAnalyze = () => {
@@ -58,8 +46,12 @@ export default function TextIntelligence() {
 
       <Button title="Analyze Text" onPress={handleAnalyze} />
 
-      {loading && <Text style={styles.status}>Analyzing...</Text>}
-      {error && <Text style={styles.error}>Error: {error}</Text>}
+      {state?.status === 'analyzing' && (
+        <Text style={styles.status}>Analyzing...</Text>
+      )}
+      {state?.error && (
+        <Text style={styles.error}>Error: {state.error.message}</Text>
+      )}
 
       {result && (
         <ScrollView style={styles.outputContainer}>
diff --git a/example/src/TextToSpeech.tsx b/example/src/TextToSpeech.tsx
index 5e2c01f..288fcc4 100644
--- a/example/src/TextToSpeech.tsx
+++ b/example/src/TextToSpeech.tsx
@@ -111,14 +111,7 @@ const parseNumber = (value: string): number | undefined => {
 export default function TextToSpeech() {
   const [text, setText] = useState('');
   const [streamText, setStreamText] = useState('');
-  const [httpStatus, setHttpStatus] = useState<'idle' | 'working' | 'error'>(
-    'idle'
-  );
-  const [httpError, setHttpError] = useState<string | null>(null);
-  const [streamStatus, setStreamStatus] = useState<
-    'idle' | 'streaming' | 'error'
-  >('idle');
-  const [streamError, setStreamError] = useState<string | null>(null);
+  // Removed manual status/error states in favor of trackState
   const [lastMetadata, setLastMetadata] =
     useState<DeepgramTextToSpeechStreamMetadataMessage | null>(null);
   const [lastFlushedSequence, setLastFlushedSequence] = useState<number | null>(
@@ -179,57 +172,44 @@ export default function TextToSpeech() {
     | DeepgramTextToSpeechSampleRate
     | undefined;
 
+  const { synthesize, state: httpState } = useDeepgramTextToSpeech({
+    trackState: true,
+    options: {
+      http: {
+        model: httpModelValue,
+        encoding: httpEncodingValue,
+        sampleRate: httpSampleRateValue,
+        container: httpContainerValue,
+        bitRate: httpBitRateValue,
+        callback: httpCallbackValue,
+        callbackMethod: httpCallbackMethodValue,
+        mipOptOut: httpMipOptOut,
+      },
+    },
+  });
+
   const {
-    synthesize,
     startStreaming,
     sendText,
     flushStream,
     clearStream,
     closeStreamGracefully,
     stopStreaming,
+    state: streamState,
   } = useDeepgramTextToSpeech({
-    onBeforeSynthesize: () => {
-      setHttpStatus('working');
-      setHttpError(null);
-    },
-    onSynthesizeSuccess: () => {
-      setHttpStatus('idle');
-    },
-    onSynthesizeError: (err) => {
-      setHttpStatus('error');
-      setHttpError(err instanceof Error ? err.message : String(err));
-    },
+    trackState: true,
     onBeforeStream: () => {
-      setStreamStatus('streaming');
-      setStreamError(null);
       setLastMetadata(null);
       setWarnings([]);
       setLastFlushedSequence(null);
       setLastClearedSequence(null);
     },
-    onStreamError: (err) => {
-      setStreamStatus('error');
-      setStreamError(err instanceof Error ? err.message : String(err));
-    },
-    onStreamEnd: () => {
-      setStreamStatus('idle');
-    },
     onStreamMetadata: setLastMetadata,
     onStreamFlushed: (event) => setLastFlushedSequence(event.sequence_id),
     onStreamCleared: (event) => setLastClearedSequence(event.sequence_id),
     onStreamWarning: (warning) =>
       setWarnings((prev) => [warning, ...prev].slice(0, 3)),
     options: {
-      http: {
-        model: httpModelValue,
-        encoding: httpEncodingValue,
-        sampleRate: httpSampleRateValue,
-        container: httpContainerValue,
-        bitRate: httpBitRateValue,
-        callback: httpCallbackValue,
-        callbackMethod: httpCallbackMethodValue,
-        mipOptOut: httpMipOptOut,
-      },
       stream: {
         model: streamModelValue,
         encoding: streamEncodingValue,
@@ -399,36 +379,40 @@ export default function TextToSpeech() {
           <Button
             title="Synthesize (HTTP)"
             onPress={handleSynthesize}
-            disabled={httpStatus === 'working' || !text.trim()}
+            disabled={httpState?.status === 'loading' || !text.trim()}
           />
         </View>
-        {httpStatus === 'working' && (
+        {httpState?.status === 'loading' && (
           <Text style={styles.status}>Synthesizing…</Text>
         )}
-        {httpError && <Text style={styles.error}>Error: {httpError}</Text>}
+        {httpState?.error && (
+          <Text style={styles.error}>Error: {httpState.error.message}</Text>
+        )}
 
         {/* streaming */}
         <View style={[styles.buttonRow, styles.streamingSection]}>
           <Button
             title="Start Stream"
             onPress={handleStream}
-            disabled={streamStatus === 'streaming' || !text.trim()}
+            disabled={streamState?.status === 'connected' || !text.trim()}
           />
           <Button
             title="Stop Stream"
             onPress={stopStreaming}
-            disabled={streamStatus !== 'streaming'}
+            disabled={streamState?.status !== 'connected'}
           />
         </View>
-        {streamStatus === 'streaming' && (
+        {streamState?.status === 'connected' && (
           <Text style={styles.status}>Streaming…</Text>
         )}
-        {streamError && (
-          <Text style={styles.error}>Stream error: {streamError}</Text>
+        {streamState?.error && (
+          <Text style={styles.error}>
+            Stream error: {streamState.error.message}
+          </Text>
         )}
 
         {/* Continuous streaming - send additional text to active stream */}
-        {streamStatus === 'streaming' && (
+        {streamState?.status === 'connected' && (
           <View style={[styles.continuousSection, styles.continuousMargin]}>
             <Text style={styles.sectionTitle}>Continuous Streaming</Text>
             <TextInput
diff --git a/example/src/VoiceAgent.tsx b/example/src/VoiceAgent.tsx
index 3b3a399..aea7f47 100644
--- a/example/src/VoiceAgent.tsx
+++ b/example/src/VoiceAgent.tsx
@@ -8,24 +8,12 @@ import {
   TextInput,
   Switch,
 } from 'react-native';
-import { useDeepgramVoiceAgent, Deepgram } from 'react-native-deepgram';
+import {
+  useDeepgramVoiceAgent,
+  createAgentSettings,
+} from 'react-native-deepgram';
 import OptionSelect from './components/OptionSelect';
 
-declare const Buffer: {
-  from(data: Uint8Array | string, encoding?: string): { toString(encoding: string): string };
-};
-
-type ConversationEntry = {
-  role: string;
-  content: string;
-};
-
-type AgentLatency = {
-  total?: number;
-  tts?: number;
-  ttt?: number;
-};
-
 const LANGUAGE_OPTIONS = [
   { label: 'English (US)', value: 'en' },
   { label: 'Spanish (ES)', value: 'es' },
@@ -50,14 +38,6 @@ const SAMPLE_RATE_OPTIONS = [
 ];
 
 export default function VoiceAgent() {
-  const [status, setStatus] = useState<
-    'idle' | 'connecting' | 'connected' | 'error'
-  >('idle');
-  const [conversation, setConversation] = useState<ConversationEntry[]>([]);
-  const [thinking, setThinking] = useState<string | null>(null);
-  const [latency, setLatency] = useState<AgentLatency | null>(null);
-  const [warning, setWarning] = useState<string | null>(null);
-  const [error, setError] = useState<string | null>(null);
   const [language, setLanguage] = useState('en');
   const [listenModel, setListenModel] = useState('nova-3');
   const [thinkModel, setThinkModel] = useState('gpt-4o');
@@ -72,44 +52,16 @@ export default function VoiceAgent() {
   const [customMessage, setCustomMessage] = useState('');
 
   const agentSettings = useMemo(() => {
-    const tags = tagsInput
-      .split(',')
-      .map((tag) => tag.trim())
-      .filter(Boolean);
-    const resolvedListenModel = listenModel.trim() || 'nova-3';
-    const resolvedThinkModel = thinkModel.trim() || 'gpt-4o';
-    const inputRate = Number(inputSampleRate) || 16_000;
-    const parsedTemperature = parseFloat(temperature);
-    const boundedTemperature = Number.isFinite(parsedTemperature)
-      ? Math.max(0, Math.min(2, parsedTemperature))
-      : 0.7;
-
-    return {
-      audio: {
-        input: { encoding: 'linear16', sample_rate: inputRate },
-        output: { encoding: 'linear16', sample_rate: inputRate, container: 'none' },
-      },
-      agent: {
-        language: language.trim() || 'en',
-        greeting: greeting.trim() || 'Hello! How can I help you today?',
-        listen: {
-          provider: {
-            type: 'deepgram',
-            model: resolvedListenModel,
-            smart_format: true,
-          },
-        },
-        think: {
-          provider: {
-            type: 'open_ai',
-            model: resolvedThinkModel,
-            temperature: boundedTemperature,
-          },
-          prompt: prompt.trim(),
-        },
-      },
-      ...(tags.length ? { tags } : {}),
-    };
+    return createAgentSettings({
+      language,
+      greeting,
+      listenModel,
+      thinkModel,
+      prompt,
+      temperature,
+      tags: tagsInput,
+      sampleRate: inputSampleRate,
+    });
   }, [
     greeting,
     inputSampleRate,
@@ -129,74 +81,24 @@ export default function VoiceAgent() {
     updatePrompt,
     sendKeepAlive,
     isConnected,
+    state,
+    conversation,
+    agentStatus,
   } = useDeepgramVoiceAgent({
     defaultSettings: agentSettings,
     autoStartMicrophone: autoStartMic,
-    onBeforeConnect: () => {
-      setStatus('connecting');
-      setError(null);
-      setWarning(null);
-      setConversation([]);
-    },
-    onConnect: () => {
-      setStatus('connected');
-      Deepgram.startPlayer?.(16000, 1);
-    },
-    onClose: () => {
-      setStatus('idle');
-      setThinking(null);
-      setLatency(null);
-      Deepgram.stopPlayer?.();
-    },
-    onError: (err) => {
-      setStatus('error');
-      setError(err instanceof Error ? err.message : String(err));
-    },
-    onConversationText: (message) => {
-      setConversation((prev) => [
-        ...prev,
-        { role: message.role, content: message.content },
-      ]);
-    },
-    onAgentThinking: (message) => setThinking(message.content),
-    onAgentStartedSpeaking: (message) =>
-      setLatency({
-        total: message.total_latency,
-        tts: message.tts_latency,
-        ttt: message.ttt_latency,
-      }),
-    onAgentAudioDone: () => {
-      setThinking(null);
-      setLatency(null);
-    },
-    onUserStartedSpeaking: () => setThinking('User is speaking…'),
-    onWarning: (message) => setWarning(message.description),
-    onServerError: (message) => {
-      setStatus('error');
-      setError(message.description || message.code || 'Voice agent error');
-    },
-    onAudioConfig: (message: { sample_rate?: number; channels?: number }) => {
-      const sampleRate = message.sample_rate || 16000;
-      const channels = message.channels || 1;
-      Deepgram.startPlayer?.(sampleRate, channels);
-    },
-    onAudio: async (audioData: ArrayBuffer) => {
-      try {
-        const bytes = new Uint8Array(audioData);
-        const b64 = Buffer.from(bytes).toString('base64');
-        await Deepgram.feedAudio?.(b64);
-      } catch (err) {
-        console.error('[VoiceAgentDemo] onAudio error:', err);
-      }
-    },
+    autoPlayAudio: true,
+    trackState: true,
+    trackConversation: true,
+    trackAgentStatus: true,
   });
 
   const startAgent = async () => {
     try {
       await connect();
     } catch (err) {
-      setStatus('error');
-      setError(err instanceof Error ? err.message : String(err));
+      // Error handled by hook state
+      console.error('Start agent failed', err);
     }
   };
 
@@ -243,9 +145,13 @@ export default function VoiceAgent() {
       >
         <View style={styles.buttonRow}>
           <Button
-            title={status === 'connected' ? 'Connected' : 'Start Agent'}
+            title={
+              state?.connectionState === 'connected'
+                ? 'Connected'
+                : 'Start Agent'
+            }
             onPress={startAgent}
-            disabled={status === 'connecting' || isConnected()}
+            disabled={state?.connectionState === 'connecting' || isConnected()}
           />
           <Button title="Stop" onPress={stopAgent} disabled={!isConnected()} />
         </View>
@@ -381,34 +287,39 @@ export default function VoiceAgent() {
           />
         </View>
 
-        {status === 'connecting' && (
+        {state?.connectionState === 'connecting' && (
           <Text style={styles.status}>Connecting to Deepgram…</Text>
         )}
-        {thinking && <Text style={styles.status}>🤔 {thinking}</Text>}
-        {latency && (
+        {agentStatus?.thinking && (
+          <Text style={styles.status}>🤔 {agentStatus.thinking}</Text>
+        )}
+        {agentStatus?.latency && (
           <Text style={styles.status}>
-            Latency: total {latency.total?.toFixed(2) ?? '–'}s · TTS{' '}
-            {latency.tts?.toFixed(2) ?? '–'}s · TTT{' '}
-            {latency.ttt?.toFixed(2) ?? '–'}s
+            Latency: total {agentStatus.latency.total?.toFixed(2) ?? '–'}s · TTS{' '}
+            {agentStatus.latency.tts?.toFixed(2) ?? '–'}s · TTT{' '}
+            {agentStatus.latency.ttt?.toFixed(2) ?? '–'}s
           </Text>
         )}
-        {warning && <Text style={styles.warning}>Warning: {warning}</Text>}
-        {error && <Text style={styles.error}>Error: {error}</Text>}
+        {state?.warning && (
+          <Text style={styles.warning}>Warning: {state.warning}</Text>
+        )}
+        {state?.error && <Text style={styles.error}>Error: {state.error}</Text>}
 
         <Text style={styles.sectionTitle}>Conversation</Text>
         <View style={styles.infoBox}>
           <Text style={styles.infoText}>
-            💬 Text transcripts of the conversation appear here alongside audio playback.
+            💬 Text transcripts of the conversation appear here alongside audio
+            playback.
           </Text>
         </View>
         <View style={styles.conversation}>
-          {conversation.map((entry, index) => (
+          {conversation?.map((entry, index) => (
             <View key={`${entry.role}-${index}`} style={styles.messageRow}>
               <Text style={styles.messageRole}>{entry.role}:</Text>
               <Text style={styles.messageContent}>{entry.content}</Text>
             </View>
           ))}
-          {conversation.length === 0 && (
+          {(conversation?.length ?? 0) === 0 && (
             <Text style={styles.placeholder}>
               Conversation will appear here once the agent responds.
             </Text>
diff --git a/ios/Deepgram.mm b/ios/Deepgram.mm
index 5c3bd7f..769d8d9 100644
--- a/ios/Deepgram.mm
+++ b/ios/Deepgram.mm
@@ -887,6 +887,8 @@ - (AVAudioPCMBuffer *)createPCMBufferFromData:(NSData *)data {
   @catch (NSException *e) {
     DGLogError(@"[Deepgram] feedAudio: exception %@", e);
   }
+}
+
 /**
  * Stop audio playback and cleanup AVAudioEngine.
  */
@@ -934,6 +936,82 @@ - (AVAudioPCMBuffer *)createPCMBufferFromData:(NSData *)data {
   [self startPlayer:sampleRate channels:channels];
 }
 
+/**
+ * Play a single audio chunk (base64-encoded PCM).
+ * This is used for one-shot TTS playback (HTTP mode).
+ */
+RCT_EXPORT_METHOD(playAudioChunk:(NSString *)b64
+                  resolver:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+{
+  @try {
+    if (!b64 || b64.length == 0) {
+      if (reject) reject(@"audio_chunk_error", @"Empty audio chunk", nil);
+      return;
+    }
+    
+    NSData *pcmData = [[NSData alloc] initWithBase64EncodedString:b64 options:0];
+    if (!pcmData || pcmData.length == 0) {
+      if (reject) reject(@"audio_chunk_error", @"Failed to decode audio chunk", nil);
+      return;
+    }
+    
+    // Activate audio session
+    NSError *sessionError = nil;
+    if (![self activateAudioSession:&sessionError]) {
+      NSString *message = sessionError.localizedDescription ?: @"Failed to activate audio session";
+      DGLogError(@"[Deepgram] playAudioChunk: activation failed %@", message);
+      if (reject) reject(@"audio_chunk_error", message, sessionError);
+      return;
+    }
+    
+    // Determine sample rate and channels from the audio data
+    // For linear16 PCM, assume 24kHz mono (2 bytes per sample)
+    int sampleRate = self.currentSampleRate > 0 ? self.currentSampleRate : 24000;
+    int channels = 1;
+    
+    // Setup audio engine if needed
+    if (!self.audioEngine || !self.audioEngine.isRunning) {
+      NSError *engineError = nil;
+      if (![self setupAudioEngineWithSampleRate:sampleRate
+                                       channels:channels
+                                          error:&engineError]) {
+        DGLogError(@"[Deepgram] playAudioChunk: failed to setup audio engine: %@", engineError);
+        if (reject) reject(@"audio_chunk_error", @"Failed to setup audio engine", engineError);
+        return;
+      }
+    }
+    
+    // Create PCM buffer and schedule for playback
+    AVAudioPCMBuffer *buffer = [self createPCMBufferFromData:pcmData];
+    if (!buffer) {
+      DGLogError(@"[Deepgram] playAudioChunk: failed to create PCM buffer");
+      if (reject) reject(@"audio_chunk_error", @"Failed to create PCM buffer", nil);
+      return;
+    }
+    
+    self.isPlaying = YES;
+    
+    // Schedule buffer with completion handler to resolve promise
+    [self.playerNode scheduleBuffer:buffer completionHandler:^{
+      self.isPlaying = NO;
+      [self maybeDeactivateAudioSession];
+      if (resolve) resolve(nil);
+    }];
+    
+    // Start playing if not already playing
+    if (!self.playerNode.isPlaying) {
+      [self.playerNode play];
+    }
+    
+    DGLogDebug(@"[Deepgram] playAudioChunk: scheduled %lu bytes for playback", (unsigned long)pcmData.length);
+  }
+  @catch (NSException *e) {
+    DGLogError(@"[Deepgram] playAudioChunk: exception %@", e);
+    if (reject) reject(@"audio_chunk_error", e.reason, nil);
+  }
+}
+
 - (void)invalidate
 {
   DGLogDebug(@"[Deepgram] invalidate: begin");
diff --git a/package.json b/package.json
index 87e1094..669c14e 100644
--- a/package.json
+++ b/package.json
@@ -1,10 +1,11 @@
 {
   "name": "react-native-deepgram",
-  "version": "1.0.5",
+  "version": "2.0.0",
   "description": "React Native SDK for Deepgram's AI-powered speech-to-text, real-time transcription, and text intelligence APIs. Supports live audio streaming, file transcription, sentiment analysis, and topic detection for iOS and Android.",
   "source": "./src/index.tsx",
   "main": "./lib/commonjs/index.js",
   "module": "./lib/module/index.js",
+  "types": "./lib/typescript/commonjs/src/index.d.ts",
   "exports": {
     ".": {
       "import": {
@@ -225,4 +226,4 @@
     "metro-symbolicate": "0.81.5",
     "metro-transform-worker": "0.81.5"
   }
-}
+}
\ No newline at end of file
diff --git a/src/helpers/audioUtils.ts b/src/helpers/audioUtils.ts
new file mode 100644
index 0000000..94b84a2
--- /dev/null
+++ b/src/helpers/audioUtils.ts
@@ -0,0 +1,32 @@
+import { Buffer } from 'buffer';
+
+export function arrayBufferToBase64(buffer: ArrayBuffer): string {
+  const bytes = new Uint8Array(buffer);
+  return Buffer.from(bytes).toString('base64');
+}
+
+export function createAudioPlayerController() {
+  let isActive = false;
+
+  return {
+    start: async (sampleRate = 16000, channels: 1 | 2 = 1) => {
+      const { Deepgram } = await import('../NativeDeepgram');
+      Deepgram.startPlayer?.(sampleRate, channels);
+      isActive = true;
+    },
+
+    feed: async (audio: ArrayBuffer | string) => {
+      const { Deepgram } = await import('../NativeDeepgram');
+      const b64 = typeof audio === 'string' ? audio : arrayBufferToBase64(audio);
+      await Deepgram.feedAudio?.(b64);
+    },
+
+    stop: async () => {
+      const { Deepgram } = await import('../NativeDeepgram');
+      Deepgram.stopPlayer?.();
+      isActive = false;
+    },
+
+    isActive: () => isActive,
+  };
+}
diff --git a/src/helpers/createAgentSettings.ts b/src/helpers/createAgentSettings.ts
new file mode 100644
index 0000000..b8437fa
--- /dev/null
+++ b/src/helpers/createAgentSettings.ts
@@ -0,0 +1,76 @@
+import type { DeepgramVoiceAgentSettings } from '../types';
+
+export function createAgentSettings(opts: {
+  language?: string;
+  greeting?: string;
+  listenModel?: string;
+  thinkModel?: string;
+  prompt?: string;
+  temperature?: number | string;
+  tags?: string | string[];
+  sampleRate?: number | string;
+} = {}): DeepgramVoiceAgentSettings {
+  const temperature = (() => {
+    if (typeof opts.temperature === 'string') {
+      const parsed = parseFloat(opts.temperature);
+      return Number.isFinite(parsed) ? Math.max(0, Math.min(2, parsed)) : 0.7;
+    }
+    if (typeof opts.temperature === 'number') {
+      return Math.max(0, Math.min(2, opts.temperature));
+    }
+    return 0.7;
+  })();
+
+  const tags = (() => {
+    if (typeof opts.tags === 'string') {
+      return opts.tags
+        .split(',')
+        .map((t) => t.trim())
+        .filter(Boolean);
+    }
+    return opts.tags ?? [];
+  })();
+
+  const sampleRate = (() => {
+    if (typeof opts.sampleRate === 'string') {
+      const parsed = parseInt(opts.sampleRate);
+      return Number.isFinite(parsed) && parsed > 0 ? parsed : 16000;
+    }
+    if (typeof opts.sampleRate === 'number' && opts.sampleRate > 0) {
+      return opts.sampleRate;
+    }
+    return 16000;
+  })();
+
+  const settings: DeepgramVoiceAgentSettings = {
+    audio: {
+      input: { encoding: 'linear16', sample_rate: sampleRate },
+      output: { encoding: 'linear16', sample_rate: sampleRate, container: 'none' },
+    },
+    agent: {
+      language: opts.language?.trim() || 'en',
+      greeting: opts.greeting?.trim() || 'Hello! How can I help you today?',
+      listen: {
+        provider: {
+          type: 'deepgram',
+          model: opts.listenModel?.trim() || 'nova-3',
+          smart_format: true,
+        },
+      },
+      think: {
+        provider: {
+          type: 'open_ai',
+          model: opts.thinkModel?.trim() || 'gpt-4o',
+          temperature,
+        },
+        prompt: opts.prompt?.trim() || 'You are a helpful assistant.',
+      },
+    },
+  };
+
+  if (tags.length > 0) {
+    settings.tags = tags;
+  }
+
+  return settings;
+}
diff --git a/src/helpers/index.ts b/src/helpers/index.ts
index 5bc2428..f4d0f17 100644
--- a/src/helpers/index.ts
+++ b/src/helpers/index.ts
@@ -1,2 +1,5 @@
 export * from './askMicPermission';
 export * from './url';
+export * from './audioUtils';
+export * from './useAsyncCall';
+export * from './createAgentSettings';
diff --git a/src/helpers/useAsyncCall.ts b/src/helpers/useAsyncCall.ts
new file mode 100644
index 0000000..d42108b
--- /dev/null
+++ b/src/helpers/useAsyncCall.ts
@@ -0,0 +1,52 @@
+import { useState, useCallback } from 'react';
+
+export interface UseAsyncCallReturn<T> {
+  data: T | null;
+  status: 'idle' | 'loading' | 'error';
+  error: Error | null;
+  execute: () => Promise<T>;
+  reset: () => void;
+  isLoading: boolean;
+  isError: boolean;
+  isSuccess: boolean;
+}
+
+export function useAsyncCall<T>(
+  asyncFn: () => Promise<T>
+): UseAsyncCallReturn<T> {
+  const [data, setData] = useState<T | null>(null);
+  const [status, setStatus] = useState<'idle' | 'loading' | 'error'>('idle');
+  const [error, setError] = useState<Error | null>(null);
+
+  const execute = useCallback(async () => {
+    setStatus('loading');
+    setError(null);
+    try {
+      const result = await asyncFn();
+      setData(result);
+      setStatus('idle');
+      return result;
+    } catch (err) {
+      setStatus('error');
+      setError(err instanceof Error ? err : new Error(String(err)));
+      throw err;
+    }
+  }, [asyncFn]);
+
+  const reset = useCallback(() => {
+    setData(null);
+    setStatus('idle');
+    setError(null);
+  }, []);
+
+  return {
+    data,
+    status,
+    error,
+    execute,
+    reset,
+    isLoading: status === 'loading',
+    isError: status === 'error',
+    isSuccess: status === 'idle' && data !== null,
+  };
+}
diff --git a/src/index.ts b/src/index.ts
index ae08b7d..2f09ddc 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -4,6 +4,12 @@ export { useDeepgramManagement } from './useDeepgramManagement';
 export { useDeepgramTextToSpeech } from './useDeepgramTextToSpeech';
 export { useDeepgramVoiceAgent } from './useDeepgramVoiceAgent';
 export { Deepgram } from './NativeDeepgram';
+export {
+  arrayBufferToBase64,
+  createAudioPlayerController,
+  useAsyncCall,
+  createAgentSettings,
+} from './helpers';
 export type {
   DeepgramTextToSpeechModel,
   DeepgramTextToSpeechEncoding,
diff --git a/src/types/deepgram/management.ts b/src/types/deepgram/management.ts
index 5274f87..7dbbd89 100644
--- a/src/types/deepgram/management.ts
+++ b/src/types/deepgram/management.ts
@@ -1,4 +1,8 @@
 /* ---------- models ---------- */
+
+/**
+ * Represents a Deepgram Speech-to-Text model.
+ */
 export interface DeepgramSttModel {
   name: string;
   canonical_name: string;
@@ -11,6 +15,9 @@ export interface DeepgramSttModel {
   formatted_output: boolean;
 }
 
+/**
+ * Represents a Deepgram Text-to-Speech model.
+ */
 export interface DeepgramTtsModel {
   name: string;
   canonical_name: string;
@@ -29,11 +36,17 @@ export interface DeepgramTtsModel {
   };
 }
 
+/**
+ * Response from listing available models.
+ */
 export interface DeepgramListModelsResponse {
   stt: DeepgramSttModel[] | null;
   tts: DeepgramTtsModel[] | null;
 }
 
+/**
+ * Represents a Deepgram Project.
+ */
 export interface DeepgramProject {
   project_id: string;
   name: string;
@@ -41,6 +54,9 @@ export interface DeepgramProject {
   balance?: number;
 }
 
+/**
+ * Represents a Deepgram API Key.
+ */
 export interface DeepgramKey {
   key_id: string;
   project_id: string;
@@ -49,6 +65,9 @@ export interface DeepgramKey {
   created?: string;
 }
 
+/**
+ * Represents a member of a Deepgram Project.
+ */
 export interface DeepgramMember {
   member_id: string;
   email: string;
@@ -58,6 +77,9 @@ export interface DeepgramMember {
 
 export type DeepgramScope = string;
 
+/**
+ * Represents an invitation to join a Deepgram Project.
+ */
 export interface DeepgramInvitation {
   invitation_id: string;
   project_id: string;
@@ -66,6 +88,9 @@ export interface DeepgramInvitation {
   created?: string;
 }
 
+/**
+ * Represents a usage request log.
+ */
 export interface DeepgramRequest {
   request_id: string;
   project_id: string;
@@ -78,11 +103,17 @@ export interface DeepgramUsageField {
   description?: string;
 }
 
+/**
+ * Breakdown of usage statistics.
+ */
 export interface DeepgramUsageBreakdown {
   total: number;
   breakdown: Record<string, number>;
 }
 
+/**
+ * Represents a purchase or balance credit.
+ */
 export interface DeepgramPurchase {
   purchase_id: string;
   project_id: string;
@@ -90,6 +121,9 @@ export interface DeepgramPurchase {
   created?: string;
 }
 
+/**
+ * Represents the current balance of a project.
+ */
 export interface DeepgramBalance {
   balance_id: string;
   project_id: string;
@@ -97,6 +131,10 @@ export interface DeepgramBalance {
   currency?: string;
 }
 
+/**
+ * Return value of the `useDeepgramManagement` hook.
+ * Provides access to various management APIs grouped by resource.
+ */
 export interface UseDeepgramManagementReturn {
   models: {
     list(includeOutdated?: boolean): Promise<DeepgramListModelsResponse>;
diff --git a/src/types/deepgram/shared.ts b/src/types/deepgram/shared.ts
index 018c0b3..a6d3752 100644
--- a/src/types/deepgram/shared.ts
+++ b/src/types/deepgram/shared.ts
@@ -1,3 +1,11 @@
+/**
+ * HTTP methods supported for callback URLs.
+ */
 export type DeepgramCallbackMethod = 'POST' | 'PUT' | (string & {});
 
+/**
+ * Mode for handling custom vocabulary/topics/intents.
+ * - `extended`: Augments the base model's knowledge.
+ * - `strict`: Limits the model to only the provided vocabulary.
+ */
 export type DeepgramCustomMode = 'extended' | 'strict';
diff --git a/src/types/deepgram/speech-to-text.ts b/src/types/deepgram/speech-to-text.ts
index b2b7a18..2568fdc 100644
--- a/src/types/deepgram/speech-to-text.ts
+++ b/src/types/deepgram/speech-to-text.ts
@@ -1,5 +1,9 @@
 import type { DeepgramCallbackMethod, DeepgramCustomMode } from './shared';
 
+/**
+ * Audio encoding formats supported by Deepgram's Live Listen API.
+ * @see https://developers.deepgram.com/docs/encoding
+ */
 export type DeepgramLiveListenEncoding =
   | 'linear16'
   | 'linear32'
@@ -14,6 +18,11 @@ export type DeepgramLiveListenEncoding =
   | 'g729'
   | (string & {});
 
+/**
+ * Deepgram speech-to-text models for live streaming.
+ * Includes Nova (fast, accurate), Enhanced (better accuracy), and Base models.
+ * @see https://developers.deepgram.com/docs/models-overview
+ */
 export type DeepgramLiveListenModel =
   | 'nova-3'
   | 'nova-3-general'
@@ -48,6 +57,9 @@ export type DeepgramLiveListenModel =
   | 'flux-general-en'
   | (string & {});
 
+/**
+ * Types of sensitive information that can be redacted from transcripts.
+ */
 export type DeepgramLiveListenRedaction =
   | 'pci'
   | 'numbers'
@@ -63,6 +75,18 @@ export type DeepgramLiveListenCallbackMethod =
   | 'PUT'
   | 'DELETE';
 
+/**
+ * Configuration options for Deepgram Live Listen (Streaming) sessions.
+ * @example
+ * ```typescript
+ * const options: DeepgramLiveListenOptions = {
+ *   model: 'nova-2',
+ *   smartFormat: true,
+ *   interimResults: true,
+ *   language: 'en-US'
+ * };
+ * ```
+ */
 export type DeepgramLiveListenOptions = {
   /** Deepgram real-time API version to use. Defaults to v1. */
   apiVersion?: 'v1' | 'v2';
@@ -142,6 +166,9 @@ export type DeepgramLiveListenOptions = {
 
 export type DeepgramPrerecordedCallbackMethod = DeepgramCallbackMethod;
 
+/**
+ * Audio encoding formats supported by Deepgram's Pre-recorded API.
+ */
 export type DeepgramPrerecordedEncoding =
   | 'linear16'
   | 'flac'
@@ -176,6 +203,18 @@ export type DeepgramPrerecordedExtra =
   | string[]
   | Record<string, string | number | boolean>;
 
+/**
+ * Configuration options for Deepgram Pre-recorded (File) Transcription.
+ * @example
+ * ```typescript
+ * const options: DeepgramPrerecordedOptions = {
+ *   model: 'nova-2',
+ *   smartFormat: true,
+ *   diarize: true,
+ *   summarize: 'v2'
+ * };
+ * ```
+ */
 export type DeepgramPrerecordedOptions = {
   /** URL to receive a webhook callback with the completed transcription. */
   callback?: string;
@@ -249,19 +288,31 @@ export type DeepgramPrerecordedOptions = {
   version?: DeepgramPrerecordedVersion;
 };
 
+/**
+ * Source input for pre-recorded transcription.
+ * Can be a File/Blob, a local file URI, or a remote URL.
+ */
 export type DeepgramPrerecordedSource =
   | Blob
   | { uri: string; name?: string; type?: string }
   | { url: string }
   | string;
 
+/**
+ * Event data accompanying a transcript update.
+ */
 export type DeepgramTranscriptEvent = {
   /** Indicates whether the transcript represents a finalized utterance. */
   isFinal?: boolean;
   /** Raw payload received from Deepgram for custom handling or inspection. */
   raw?: unknown;
+  /** Metadata about the transcript (e.g. confidence, timing). */
+  metadata?: Record<string, unknown>;
 };
 
+/**
+ * Props for the `useDeepgramSpeechToText` hook.
+ */
 export type UseDeepgramSpeechToTextProps = {
   /** Called before any setup (e.g. before permission prompt) */
   onBeforeStart?: () => void;
@@ -283,8 +334,17 @@ export type UseDeepgramSpeechToTextProps = {
   live?: DeepgramLiveListenOptions;
   /** Default options for pre-recorded transcription requests. */
   prerecorded?: DeepgramPrerecordedOptions;
+
+  /** Enable internal state tracking. @default false */
+  trackState?: boolean;
+
+  /** Automatically accumulate transcript results. @default false */
+  trackTranscript?: boolean;
 };
 
+/**
+ * Return value of the `useDeepgramSpeechToText` hook.
+ */
 export type UseDeepgramSpeechToTextReturn = {
   /** Begin capturing mic audio and streaming to Deepgram STT */
   startListening: (options?: DeepgramLiveListenOptions) => Promise<void>;
@@ -295,4 +355,15 @@ export type UseDeepgramSpeechToTextReturn = {
     file: DeepgramPrerecordedSource,
     options?: DeepgramPrerecordedOptions
   ) => Promise<void>;
+
+  /** Current state of the transcription session (if trackState is enabled) */
+  state?: {
+    status: 'idle' | 'loading' | 'listening' | 'transcribing' | 'error';
+    error: Error | null;
+  };
+
+  /** Final accumulated transcript (only returned when trackTranscript is enabled) */
+  transcript?: string;
+  /** Interim/partial transcript (only returned when trackTranscript is enabled for live) */
+  interimTranscript?: string;
 };
diff --git a/src/types/deepgram/text-intelligence.ts b/src/types/deepgram/text-intelligence.ts
index 06125d9..1789ee7 100644
--- a/src/types/deepgram/text-intelligence.ts
+++ b/src/types/deepgram/text-intelligence.ts
@@ -4,6 +4,10 @@ export type DeepgramTextIntelligenceCallbackMethod = DeepgramCallbackMethod;
 
 export type DeepgramTextIntelligenceCustomMode = DeepgramCustomMode;
 
+/**
+ * Supported languages for text intelligence analysis.
+ * @see https://developers.deepgram.com/docs/language-support
+ */
 export type DeepgramTextIntelligenceLanguage =
   | 'bg'
   | 'ca'
@@ -63,10 +67,26 @@ export type DeepgramTextIntelligenceLanguage =
   | 'vi'
   | (string & {});
 
+/**
+ * Input for text intelligence analysis.
+ * Can be raw text or a URL to a text resource.
+ */
 export type DeepgramTextIntelligenceInput =
   | { text: string; url?: string }
   | { text?: string; url: string };
 
+/**
+ * Configuration options for text intelligence analysis.
+ * @example
+ * ```typescript
+ * const options: UseDeepgramTextIntelligenceOptions = {
+ *   summarize: true,
+ *   topics: true,
+ *   sentiment: true,
+ *   language: 'en'
+ * };
+ * ```
+ */
 export interface UseDeepgramTextIntelligenceOptions {
   /** Whether to run summarization on the input */
   summarize?: boolean;
@@ -92,6 +112,9 @@ export interface UseDeepgramTextIntelligenceOptions {
   callbackMethod?: DeepgramTextIntelligenceCallbackMethod;
 }
 
+/**
+ * Props for the `useDeepgramTextIntelligence` hook.
+ */
 export interface UseDeepgramTextIntelligenceProps {
   /** Called before analysis begins (e.g. show spinner) */
   onBeforeAnalyze?: () => void;
@@ -101,12 +124,24 @@ export interface UseDeepgramTextIntelligenceProps {
   onAnalyzeError?: (error: Error) => void;
   /** Configuration for which analyses to run */
   options?: UseDeepgramTextIntelligenceOptions;
+  /** Whether to track the internal state of the analysis */
+  trackState?: boolean;
 }
 
+/**
+ * Return value of the `useDeepgramTextIntelligence` hook.
+ */
 export interface UseDeepgramTextIntelligenceReturn {
   /**
    * Analyze the provided input.
    * Pass an object with either `text` (raw string) or `url` (link to text resource).
    */
   analyze: (input: DeepgramTextIntelligenceInput) => Promise<void>;
+  /**
+   * Current state of the analysis (only if trackState is true).
+   */
+  state?: {
+    status: 'idle' | 'loading' | 'analyzing' | 'error';
+    error: Error | null;
+  };
 }
diff --git a/src/types/deepgram/text-to-speech.ts b/src/types/deepgram/text-to-speech.ts
index 22fd6cf..250ebd5 100644
--- a/src/types/deepgram/text-to-speech.ts
+++ b/src/types/deepgram/text-to-speech.ts
@@ -1,5 +1,9 @@
 import type { DeepgramCallbackMethod } from './shared';
 
+/**
+ * Deepgram Aura text-to-speech models.
+ * @see https://developers.deepgram.com/docs/tts-models
+ */
 export type DeepgramTextToSpeechModel =
   | 'aura-asteria-en'
   | 'aura-luna-en'
@@ -105,6 +109,16 @@ export type DeepgramTextToSpeechContainer =
 
 export type DeepgramTextToSpeechBitRate = 32000 | 48000 | (number & {});
 
+/**
+ * Options for HTTP (REST) text-to-speech requests.
+ * @example
+ * ```typescript
+ * const options: DeepgramTextToSpeechHttpOptions = {
+ *   model: 'aura-asteria-en',
+ *   encoding: 'mp3'
+ * };
+ * ```
+ */
 export interface DeepgramTextToSpeechHttpOptions {
   model?: DeepgramTextToSpeechModel | (string & {});
   encoding?: DeepgramTextToSpeechHttpEncoding;
@@ -119,6 +133,17 @@ export interface DeepgramTextToSpeechHttpOptions {
   queryParams?: Record<string, string | number | boolean>;
 }
 
+/**
+ * Options for WebSocket streaming text-to-speech.
+ * @example
+ * ```typescript
+ * const options: DeepgramTextToSpeechStreamOptions = {
+ *   model: 'aura-asteria-en',
+ *   encoding: 'linear16',
+ *   sampleRate: 48000
+ * };
+ * ```
+ */
 export interface DeepgramTextToSpeechStreamOptions {
   model?: DeepgramTextToSpeechModel | (string & {});
   encoding?: DeepgramTextToSpeechStreamEncoding;
@@ -130,6 +155,10 @@ export interface DeepgramTextToSpeechStreamOptions {
   autoFlush?: boolean;
 }
 
+/**
+ * Configuration for the `useDeepgramTextToSpeech` hook.
+ * Supports both HTTP and WebSocket streaming configurations.
+ */
 export interface UseDeepgramTextToSpeechOptions {
   /** @deprecated Use `http.model` / `stream.model` for granular control. */
   model?: DeepgramTextToSpeechModel | (string & {});
@@ -157,6 +186,9 @@ export interface UseDeepgramTextToSpeechOptions {
   stream?: DeepgramTextToSpeechStreamOptions;
 }
 
+/**
+ * Message sent to the TTS WebSocket stream.
+ */
 export type DeepgramTextToSpeechStreamTextMessage = {
   type: 'Text';
   text: string;
@@ -176,6 +208,9 @@ export type DeepgramTextToSpeechStreamCloseMessage = {
   type: 'Close';
 };
 
+/**
+ * Union of all possible messages sent to the TTS WebSocket.
+ */
 export type DeepgramTextToSpeechStreamInputMessage =
   | DeepgramTextToSpeechStreamTextMessage
   | DeepgramTextToSpeechStreamFlushMessage
@@ -216,6 +251,9 @@ export interface DeepgramTextToSpeechStreamErrorMessage {
   code?: string;
 }
 
+/**
+ * Union of all possible messages received from the TTS WebSocket.
+ */
 export type DeepgramTextToSpeechStreamResponseMessage =
   | DeepgramTextToSpeechStreamMetadataMessage
   | DeepgramTextToSpeechStreamFlushedMessage
@@ -224,6 +262,9 @@ export type DeepgramTextToSpeechStreamResponseMessage =
   | DeepgramTextToSpeechStreamErrorMessage
   | ({ type: string } & Record<string, unknown>);
 
+/**
+ * Props for the `useDeepgramTextToSpeech` hook.
+ */
 export type UseDeepgramTextToSpeechProps = {
   /* ---------- Synchronous HTTP (`synthesize`) ---------- */
 
@@ -259,8 +300,17 @@ export type UseDeepgramTextToSpeechProps = {
 
   /** Shared options that apply to both HTTP and WebSocket flows. */
   options?: UseDeepgramTextToSpeechOptions;
+
+  /** Automatically handle audio playback (speaker output). @default true */
+  autoPlayAudio?: boolean;
+
+  /** Enable internal state tracking. @default false */
+  trackState?: boolean;
 };
 
+/**
+ * Return value of the `useDeepgramTextToSpeech` hook.
+ */
 export type UseDeepgramTextToSpeechReturn = {
   /** One-shot HTTP request that resolves when the full audio is ready. */
   synthesize: (text: string) => Promise<ArrayBuffer>;
@@ -284,4 +334,10 @@ export type UseDeepgramTextToSpeechReturn = {
   closeStreamGracefully: () => boolean;
   /** Forcefully close the WebSocket stream and release resources. */
   stopStreaming: () => void;
+  
+  /** Current state of the TTS session (if trackState is enabled) */
+  state?: {
+    status: 'idle' | 'loading' | 'connecting' | 'connected' | 'error';
+    error: Error | null;
+  };
 };
diff --git a/src/types/deepgram/voice-agent.ts b/src/types/deepgram/voice-agent.ts
index e56b4e3..796eb5e 100644
--- a/src/types/deepgram/voice-agent.ts
+++ b/src/types/deepgram/voice-agent.ts
@@ -1,3 +1,6 @@
+/**
+ * Message in the conversation history.
+ */
 export interface DeepgramVoiceAgentContextMessage {
   type: string;
   role?: 'user' | 'assistant' | 'system';
@@ -94,6 +97,21 @@ export interface DeepgramVoiceAgentAgentConfig {
   [key: string]: unknown;
 }
 
+/**
+ * Configuration for the Voice Agent.
+ * @example
+ * ```typescript
+ * const settings: DeepgramVoiceAgentSettings = {
+ *   agent: {
+ *     think: {
+ *       provider: { type: 'open_ai' },
+ *       model: 'gpt-4o'
+ *     }
+ *   }
+ * };
+ * ```
+ * @see https://developers.deepgram.com/docs/voice-agent
+ */
 export interface DeepgramVoiceAgentSettings {
   tags?: string[];
   experimental?: boolean;
@@ -147,6 +165,9 @@ export interface DeepgramVoiceAgentUpdatePromptMessage {
   [key: string]: unknown;
 }
 
+/**
+ * Union of all messages that can be sent from the Client to the Voice Agent.
+ */
 export type DeepgramVoiceAgentClientMessage =
   | DeepgramVoiceAgentSettingsMessage
   | DeepgramVoiceAgentUpdateSpeakMessage
@@ -257,6 +278,9 @@ export interface DeepgramVoiceAgentAudioMessage {
   [key: string]: unknown;
 }
 
+/**
+ * Union of all messages that can be received from the Voice Agent Server.
+ */
 export type DeepgramVoiceAgentServerMessage =
   | DeepgramVoiceAgentWelcomeMessage
   | DeepgramVoiceAgentSettingsAppliedMessage
diff --git a/src/useDeepgramSpeechToText.ts b/src/useDeepgramSpeechToText.ts
index 0326fd1..2970dcc 100644
--- a/src/useDeepgramSpeechToText.ts
+++ b/src/useDeepgramSpeechToText.ts
@@ -1,4 +1,4 @@
-import { useRef, useCallback } from 'react';
+import { useRef, useCallback, useState } from 'react';
 import { NativeEventEmitter, NativeModules, Platform } from 'react-native';
 import { Deepgram } from './NativeDeepgram';
 import { askMicPermission } from './helpers/askMicPermission';
@@ -57,7 +57,16 @@ export function useDeepgramSpeechToText({
   onTranscribeError = () => {},
   live = {},
   prerecorded = {},
+  trackState = false,
+  trackTranscript = false,
 }: UseDeepgramSpeechToTextProps = {}): UseDeepgramSpeechToTextReturn {
+  const [internalState, setInternalState] = useState<{
+    status: 'idle' | 'loading' | 'listening' | 'transcribing' | 'error';
+    error: Error | null;
+  }>({
+    status: 'idle',
+    error: null,
+  });
   const ws = useRef<WebSocket | null>(null);
   const audioSub = useRef<ReturnType<NativeEventEmitter['addListener']> | null>(
     null
@@ -69,6 +78,10 @@ export function useDeepgramSpeechToText({
   const lastPartialTranscriptRef = useRef('');
   const lastFinalTranscriptRef = useRef('');
 
+  // Transcript tracking state
+  const [internalTranscript, setInternalTranscript] = useState('');
+  const [internalInterimTranscript, setInternalInterimTranscript] = useState('');
+
   const closeEverything = () => {
     if (audioSub.current) {
       audioSub.current.remove();
@@ -93,6 +106,13 @@ export function useDeepgramSpeechToText({
     ws.current?.close(1000, 'cleanup');
     ws.current = null;
     apiVersionRef.current = 'v1';
+    if (trackState) {
+      setInternalState((prev) => ({ ...prev, status: 'idle' }));
+    }
+    if (trackTranscript) {
+      setInternalTranscript('');
+      setInternalInterimTranscript('');
+    }
   };
 
   const emitTranscript = useCallback(
@@ -123,8 +143,21 @@ export function useDeepgramSpeechToText({
         lastPartialTranscriptRef.current = normalized;
       }
 
-      const event: DeepgramTranscriptEvent = { isFinal, raw };
-      onTranscript(normalized, event);
+      const info: DeepgramTranscriptEvent = { isFinal: !!isFinal, raw };
+
+      if (trackTranscript) {
+        if (isFinal) {
+          setInternalTranscript((prev) => {
+            const next = prev ? `${prev} ${normalized}` : normalized;
+            return next.trim();
+          });
+          setInternalInterimTranscript('');
+        } else {
+          setInternalInterimTranscript(normalized);
+        }
+      }
+
+      onTranscript(normalized, info);
 
       if (isFinal) {
         lastPartialTranscriptRef.current = '';
@@ -137,6 +170,9 @@ export function useDeepgramSpeechToText({
     async (overrideOptions: DeepgramLiveListenOptions = {}) => {
       try {
         onBeforeStart();
+        if (trackState) {
+          setInternalState({ status: 'loading', error: null });
+        }
         lastPartialTranscriptRef.current = '';
         lastFinalTranscriptRef.current = '';
 
@@ -238,7 +274,12 @@ export function useDeepgramSpeechToText({
           headers: { Authorization: `Token ${apiKey}` },
         });
 
-        ws.current.onopen = () => onStart();
+        ws.current.onopen = () => {
+          onStart();
+          if (trackState) {
+            setInternalState({ status: 'listening', error: null });
+          }
+        };
 
         const emitter = new NativeEventEmitter(NativeModules.Deepgram);
         audioSub.current = emitter.addListener(
@@ -301,6 +342,9 @@ export function useDeepgramSpeechToText({
                   const description =
                     msg.description || 'Deepgram stream error';
                   onError(new Error(description));
+                  if (trackState) {
+                    setInternalState({ status: 'error', error: new Error(description) });
+                  }
                   closeEverything();
                   return;
                 }
@@ -336,13 +380,21 @@ export function useDeepgramSpeechToText({
           }
         };
 
-        ws.current.onerror = onError;
+        ws.current.onerror = (err) => {
+          onError(err);
+          if (trackState) {
+            setInternalState({ status: 'error', error: err instanceof Error ? err : new Error(String(err)) });
+          }
+        };
         ws.current.onclose = () => {
           onEnd();
           closeEverything();
         };
       } catch (err) {
         onError(err);
+        if (trackState) {
+          setInternalState({ status: 'error', error: err instanceof Error ? err : new Error(String(err)) });
+        }
         closeEverything();
       }
     },
@@ -355,6 +407,9 @@ export function useDeepgramSpeechToText({
       onEnd();
     } catch (err) {
       onError(err);
+      if (trackState) {
+        setInternalState({ status: 'error', error: err instanceof Error ? err : new Error(String(err)) });
+      }
     }
   }, [onEnd, onError]);
 
@@ -364,6 +419,9 @@ export function useDeepgramSpeechToText({
       overrideOptions: DeepgramPrerecordedOptions = {}
     ) => {
       onBeforeTranscribe();
+      if (trackState) {
+        setInternalState({ status: 'transcribing', error: null });
+      }
       try {
         const apiKey = (globalThis as any).__DEEPGRAM_API_KEY__;
         if (!apiKey) throw new Error('Deepgram API key missing');
@@ -492,15 +550,30 @@ export function useDeepgramSpeechToText({
           json.results?.channels?.[0]?.alternatives?.[0]?.transcript;
         if (transcript) {
           onTranscribeSuccess(transcript);
+          if (trackState) {
+            setInternalState({ status: 'idle', error: null });
+          }
         } else {
           throw new Error('No transcript present in Deepgram response');
         }
       } catch (err) {
         onTranscribeError(err);
+        if (trackState) {
+          setInternalState({ status: 'error', error: err instanceof Error ? err : new Error(String(err)) });
+        }
       }
     },
     [onBeforeTranscribe, onTranscribeSuccess, onTranscribeError, prerecorded]
   );
 
-  return { startListening, stopListening, transcribeFile };
+  return { 
+    startListening, 
+    stopListening, 
+    transcribeFile,
+    ...(trackState ? { state: internalState } : {}),
+    ...(trackTranscript ? { 
+      transcript: internalTranscript,
+      interimTranscript: internalInterimTranscript 
+    } : {}),
+  };
 }
diff --git a/src/useDeepgramTextIntelligence.ts b/src/useDeepgramTextIntelligence.ts
index d3d508d..4818fdd 100644
--- a/src/useDeepgramTextIntelligence.ts
+++ b/src/useDeepgramTextIntelligence.ts
@@ -1,4 +1,4 @@
-import { useRef, useCallback, useEffect } from 'react';
+import { useRef, useCallback, useEffect, useState } from 'react';
 import type {
   UseDeepgramTextIntelligenceProps,
   UseDeepgramTextIntelligenceReturn,
@@ -12,7 +12,15 @@ export function useDeepgramTextIntelligence({
   onAnalyzeSuccess = () => {},
   onAnalyzeError = () => {},
   options = {},
+  trackState = false,
 }: UseDeepgramTextIntelligenceProps = {}): UseDeepgramTextIntelligenceReturn {
+  const [internalState, setInternalState] = useState<{
+    status: 'idle' | 'loading' | 'analyzing' | 'error';
+    error: Error | null;
+  }>({
+    status: 'idle',
+    error: null,
+  });
   const abortCtrl = useRef<AbortController | null>(null);
 
   const {
@@ -33,6 +41,10 @@ export function useDeepgramTextIntelligence({
     async (input: DeepgramTextIntelligenceInput) => {
       onBeforeAnalyze();
 
+      if (trackState) {
+        setInternalState({ status: 'analyzing', error: null });
+      }
+
       try {
         const apiKey = (globalThis as any).__DEEPGRAM_API_KEY__;
         if (!apiKey) throw new Error('Deepgram API key missing');
@@ -85,9 +97,15 @@ export function useDeepgramTextIntelligence({
 
         const json = await res.json();
         onAnalyzeSuccess(json);
+        if (trackState) {
+          setInternalState({ status: 'idle', error: null });
+        }
       } catch (err: any) {
         if (err.name === 'AbortError') return;
         onAnalyzeError(err);
+        if (trackState) {
+          setInternalState({ status: 'error', error: err instanceof Error ? err : new Error(String(err)) });
+        }
       }
     },
     [
@@ -114,5 +132,8 @@ export function useDeepgramTextIntelligence({
     };
   }, []);
 
-  return { analyze };
+  return { 
+    analyze,
+    ...(trackState ? { state: internalState } : {}),
+  };
 }
diff --git a/src/useDeepgramTextToSpeech.ts b/src/useDeepgramTextToSpeech.ts
index c325e4b..f2c3bf7 100644
--- a/src/useDeepgramTextToSpeech.ts
+++ b/src/useDeepgramTextToSpeech.ts
@@ -1,6 +1,6 @@
 import { Buffer } from 'buffer';
 if (!globalThis.Buffer) globalThis.Buffer = Buffer;
-import { useRef, useCallback, useEffect, useMemo } from 'react';
+import { useRef, useCallback, useEffect, useMemo, useState } from 'react';
 import { NativeModules } from 'react-native';
 import type {
   UseDeepgramTextToSpeechProps,
@@ -159,7 +159,16 @@ export function useDeepgramTextToSpeech({
   onStreamCleared = () => {},
   onStreamWarning = () => {},
   options = {},
+  autoPlayAudio = true,
+  trackState = false,
 }: UseDeepgramTextToSpeechProps = {}): UseDeepgramTextToSpeechReturn {
+  const [internalState, setInternalState] = useState<{
+    status: 'idle' | 'loading' | 'connecting' | 'connected' | 'error';
+    error: Error | null;
+  }>({
+    status: 'idle',
+    error: null,
+  });
   const resolvedHttpOptions = useMemo(() => {
     const encoding =
       options.http?.encoding ?? options.encoding ?? DEFAULT_TTS_HTTP_ENCODING;
@@ -246,6 +255,9 @@ export function useDeepgramTextToSpeech({
   const synthesize = useCallback(
     async (text: string) => {
       onBeforeSynthesize();
+      if (trackState) {
+        setInternalState({ status: 'loading', error: null });
+      }
       try {
         const apiKey = (globalThis as any).__DEEPGRAM_API_KEY__;
         if (!apiKey) throw new Error('Deepgram API key missing');
@@ -309,6 +321,9 @@ export function useDeepgramTextToSpeech({
         await Deepgram.playAudioChunk(audio);
 
         onSynthesizeSuccess(audio);
+        if (trackState) {
+          setInternalState({ status: 'idle', error: null });
+        }
         return audio;
       } catch (err: any) {
         if (err?.name === 'AbortError') {
@@ -316,6 +331,9 @@ export function useDeepgramTextToSpeech({
         }
 
         onSynthesizeError(err);
+        if (trackState) {
+          setInternalState({ status: 'error', error: err instanceof Error ? err : new Error(String(err)) });
+        }
         throw err;
       }
     },
@@ -333,7 +351,12 @@ export function useDeepgramTextToSpeech({
   const closeStream = () => {
     ws.current?.close(1000, 'cleanup');
     ws.current = null;
-    Deepgram.stopPlayer();
+    if (autoPlayAudio) {
+      Deepgram.stopPlayer();
+    }
+    if (trackState) {
+      setInternalState((prev) => ({ ...prev, status: 'idle' }));
+    }
   };
 
   const sendMessage = useCallback(
@@ -347,6 +370,9 @@ export function useDeepgramTextToSpeech({
         return true;
       } catch (err) {
         onStreamError(err);
+        if (trackState) {
+          setInternalState({ status: 'error', error: err instanceof Error ? err : new Error(String(err)) });
+        }
         return false;
       }
     },
@@ -401,6 +427,9 @@ export function useDeepgramTextToSpeech({
   const startStreaming = useCallback(
     async (text: string) => {
       onBeforeStream();
+      if (trackState) {
+        setInternalState({ status: 'connecting', error: null });
+      }
       try {
         const apiKey = (globalThis as any).__DEEPGRAM_API_KEY__;
         if (!apiKey) throw new Error('Deepgram API key missing');
@@ -435,21 +464,30 @@ export function useDeepgramTextToSpeech({
         ws.current.binaryType = 'arraybuffer';
 
         ws.current.onopen = () => {
-          Deepgram.startPlayer(
-            Number(resolvedStreamOptions.sampleRate) || DEFAULT_TTS_SAMPLE_RATE,
-            1
-          );
+          if (autoPlayAudio) {
+            Deepgram.startPlayer(
+              Number(resolvedStreamOptions.sampleRate) || DEFAULT_TTS_SAMPLE_RATE,
+              1
+            );
+          }
           sendText(text);
           onStreamStart();
+          if (trackState) {
+            setInternalState({ status: 'connected', error: null });
+          }
         };
 
         ws.current.onmessage = (ev) => {
           if (ev.data instanceof ArrayBuffer) {
-            Deepgram.feedAudio(ev.data);
+            if (autoPlayAudio) {
+              Deepgram.feedAudio(ev.data);
+            }
             onAudioChunk(ev.data);
           } else if (ev.data instanceof Blob) {
             ev.data.arrayBuffer().then((buffer) => {
-              Deepgram.feedAudio(buffer);
+              if (autoPlayAudio) {
+                Deepgram.feedAudio(buffer);
+              }
               onAudioChunk(buffer);
             });
           } else if (typeof ev.data === 'string') {
@@ -489,6 +527,12 @@ export function useDeepgramTextToSpeech({
                     err && typeof err.code === 'string' ? err.code : undefined;
 
                   onStreamError(new Error(description ?? code ?? 'TTS error'));
+                  if (trackState) {
+                    setInternalState({
+                      status: 'error',
+                      error: new Error(description ?? code ?? 'TTS error'),
+                    });
+                  }
                   break;
                 }
                 default:
@@ -501,13 +545,21 @@ export function useDeepgramTextToSpeech({
           }
         };
 
-        ws.current.onerror = onStreamError;
+        ws.current.onerror = (err) => {
+          onStreamError(err);
+          if (trackState) {
+            setInternalState({ status: 'error', error: err instanceof Error ? err : new Error(String(err)) });
+          }
+        };
         ws.current.onclose = () => {
           onStreamEnd();
           closeStream();
         };
       } catch (err) {
         onStreamError(err);
+        if (trackState) {
+          setInternalState({ status: 'error', error: err instanceof Error ? err : new Error(String(err)) });
+        }
         closeStream();
         throw err;
       }
@@ -533,6 +585,9 @@ export function useDeepgramTextToSpeech({
       onStreamEnd();
     } catch (err) {
       onStreamError(err);
+      if (trackState) {
+        setInternalState({ status: 'error', error: err instanceof Error ? err : new Error(String(err)) });
+      }
     }
   }, [onStreamEnd, onStreamError]);
 
@@ -554,5 +609,6 @@ export function useDeepgramTextToSpeech({
     clearStream,
     closeStreamGracefully,
     stopStreaming,
+    ...(trackState ? { state: internalState } : {}),
   };
 }
diff --git a/src/useDeepgramVoiceAgent.ts b/src/useDeepgramVoiceAgent.ts
index 20f5747..ab856b8 100644
--- a/src/useDeepgramVoiceAgent.ts
+++ b/src/useDeepgramVoiceAgent.ts
@@ -1,5 +1,6 @@
-import { useRef, useCallback, useEffect } from 'react';
+import { useRef, useCallback, useEffect, useState } from 'react';
 import { NativeEventEmitter, NativeModules, Platform } from 'react-native';
+import { Buffer } from 'buffer';
 import { Deepgram } from './NativeDeepgram';
 import { askMicPermission } from './helpers/askMicPermission';
 import type {
@@ -171,6 +172,10 @@ export interface UseDeepgramVoiceAgentProps {
   defaultSettings?: DeepgramVoiceAgentSettings;
   autoStartMicrophone?: boolean;
   downsampleFactor?: number;
+  autoPlayAudio?: boolean;
+  trackState?: boolean;
+  trackConversation?: boolean;
+  trackAgentStatus?: boolean;
   onBeforeConnect?: () => void;
   onConnect?: () => void;
   onClose?: (event?: any) => void;
@@ -222,12 +227,27 @@ export interface UseDeepgramVoiceAgentReturn {
   updatePrompt: (prompt: string) => boolean;
   sendMedia: (chunk: ArrayBuffer | Uint8Array | number[]) => boolean;
   isConnected: () => boolean;
+  state?: {
+    connectionState: 'idle' | 'connecting' | 'connected' | 'disconnected';
+    error: string | null;
+    warning: string | null;
+  };
+  conversation?: Array<{ role: string; content: string }>;
+  clearConversation?: () => void;
+  agentStatus?: {
+    thinking: string | null;
+    latency: { total?: number; tts?: number; ttt?: number } | null;
+  };
 }
 
 export function useDeepgramVoiceAgent({
   endpoint = DEFAULT_AGENT_ENDPOINT,
   defaultSettings,
   autoStartMicrophone = true,
+  autoPlayAudio = true,
+  trackState = false,
+  trackConversation = false,
+  trackAgentStatus = false,
   downsampleFactor,
   onBeforeConnect,
   onConnect,
@@ -291,6 +311,28 @@ export function useDeepgramVoiceAgent({
   const onAudioRef = useRef(onAudio);
   const autoStartMicRef = useRef(autoStartMicrophone);
 
+  const [internalState, setInternalState] = useState<{
+    connectionState: 'idle' | 'connecting' | 'connected' | 'disconnected';
+    error: string | null;
+    warning: string | null;
+  }>(() => ({
+    connectionState: 'idle',
+    error: null,
+    warning: null,
+  }));
+
+  const [internalConversation, setInternalConversation] = useState<
+    Array<{ role: string; content: string }>
+  >([]);
+
+  const [internalAgentStatus, setInternalAgentStatus] = useState<{
+    thinking: string | null;
+    latency: { total?: number; tts?: number; ttt?: number } | null;
+  }>(() => ({
+    thinking: null,
+    latency: null,
+  }));
+
   const sanitizeAudioSettings = useCallback(
     (audio?: DeepgramVoiceAgentSettings['audio']) => {
       if (!audio) {
@@ -547,27 +589,63 @@ export function useDeepgramVoiceAgent({
               break;
             case 'ConversationText':
               if (hasKeys(message, ['role', 'content'])) {
-                onConversationTextRef.current?.(
-                  message as DeepgramVoiceAgentConversationTextMessage
-                );
+                const convMsg = message as DeepgramVoiceAgentConversationTextMessage;
+                
+                if (trackConversation) {
+                  setInternalConversation((prev) => [
+                    ...prev,
+                    { role: convMsg.role, content: convMsg.content },
+                  ]);
+                }
+                
+                onConversationTextRef.current?.(convMsg);
               }
               break;
             case 'AgentThinking':
               if (hasKeys(message, ['content'])) {
-                onAgentThinkingRef.current?.(
-                  message as DeepgramVoiceAgentAgentThinkingMessage
-                );
+                const thinkMsg = message as DeepgramVoiceAgentAgentThinkingMessage;
+                
+                if (trackAgentStatus) {
+                  setInternalAgentStatus((prev) => ({
+                    ...prev,
+                    thinking: thinkMsg.content,
+                  }));
+                }
+                
+                onAgentThinkingRef.current?.(thinkMsg);
               }
               break;
             case 'AgentStartedSpeaking':
-              onAgentStartedSpeakingRef.current?.(
-                message as DeepgramVoiceAgentAgentStartedSpeakingMessage
-              );
+              {
+                const speakMsg = message as DeepgramVoiceAgentAgentStartedSpeakingMessage;
+                
+                if (trackAgentStatus) {
+                  setInternalAgentStatus((prev) => ({
+                    ...prev,
+                    latency: {
+                      total: speakMsg.total_latency,
+                      tts: speakMsg.tts_latency,
+                      ttt: speakMsg.ttt_latency,
+                    },
+                  }));
+                }
+                
+                onAgentStartedSpeakingRef.current?.(speakMsg);
+              }
               break;
             case 'AgentAudioDone':
-              onAgentAudioDoneRef.current?.(
-                message as DeepgramVoiceAgentAgentAudioDoneMessage
-              );
+              {
+                const doneMsg = message as DeepgramVoiceAgentAgentAudioDoneMessage;
+                
+                if (trackAgentStatus) {
+                  setInternalAgentStatus({
+                    thinking: null,
+                    latency: null,
+                  });
+                }
+                
+                onAgentAudioDoneRef.current?.(doneMsg);
+              }
               break;
             case 'UserStartedSpeaking':
               onUserStartedSpeakingRef.current?.(
@@ -603,9 +681,15 @@ export function useDeepgramVoiceAgent({
               break;
             case 'AudioConfig':
               if (hasKeys(message, ['sample_rate'])) {
-                onAudioConfigRef.current?.(
-                  message as DeepgramVoiceAgentAudioConfigMessage
-                );
+                const configMsg = message as DeepgramVoiceAgentAudioConfigMessage;
+                
+                if (autoPlayAudio) {
+                  const sampleRate = configMsg.sample_rate || DEFAULT_INPUT_SAMPLE_RATE;
+                  const channels = configMsg.channels || 1;
+                  Deepgram.startPlayer?.(sampleRate, channels);
+                }
+                
+                onAudioConfigRef.current?.(configMsg);
               }
               break;
             case 'InjectionRefused':
@@ -617,9 +701,16 @@ export function useDeepgramVoiceAgent({
               break;
             case 'Warning':
               if (hasKeys(message, ['description'])) {
-                onWarningRef.current?.(
-                  message as DeepgramVoiceAgentWarningMessage
-                );
+                const warnMsg = message as DeepgramVoiceAgentWarningMessage;
+                
+                if (trackState) {
+                  setInternalState((prev) => ({
+                    ...prev,
+                    warning: warnMsg.description,
+                  }));
+                }
+                
+                onWarningRef.current?.(warnMsg);
               }
               break;
             case 'Error':
@@ -633,15 +724,23 @@ export function useDeepgramVoiceAgent({
                     ? (message as any).code
                     : undefined;
 
+                const errorMsg = description ?? code ?? 'Voice agent error';
+                
+                if (trackState) {
+                  setInternalState((prev) => ({
+                    ...prev,
+                    connectionState: 'disconnected',
+                    error: errorMsg,
+                  }));
+                }
+
                 if (description || code) {
                   onServerErrorRef.current?.(
                     message as DeepgramVoiceAgentErrorMessage
                   );
                 }
 
-                onErrorRef.current?.(
-                  new Error(description ?? code ?? 'Voice agent error')
-                );
+                onErrorRef.current?.(new Error(errorMsg));
               }
               break;
             default:
@@ -655,7 +754,16 @@ export function useDeepgramVoiceAgent({
 
       const buffer = ensureArrayBuffer(ev.data);
       if (buffer) {
-        // Binary audio from server
+        if (autoPlayAudio) {
+          try {
+            const bytes = new Uint8Array(buffer);
+            const b64 = Buffer.from(bytes).toString('base64');
+            Deepgram.feedAudio?.(b64);
+          } catch (err) {
+            console.warn('[VoiceAgent] Auto-feed audio error:', err);
+          }
+        }
+        
         onAudioRef.current?.(buffer);
       }
     },
@@ -741,6 +849,22 @@ export function useDeepgramVoiceAgent({
   const connect = useCallback(
     async (overrideSettings?: DeepgramVoiceAgentSettings) => {
       cleanup();
+      
+      if (trackState) {
+        setInternalState({
+          connectionState: 'connecting',
+          error: null,
+          warning: null,
+        });
+      }
+      
+      if (trackConversation) {
+        setInternalConversation([]);
+      }
+      if (trackAgentStatus) {
+        setInternalAgentStatus({ thinking: null, latency: null });
+      }
+      
       onBeforeConnectRef.current?.();
 
       const apiKey = (globalThis as any).__DEEPGRAM_API_KEY__;
@@ -795,6 +919,22 @@ export function useDeepgramVoiceAgent({
 
       socket.onopen = () => {
         sendJsonMessage(mergedSettings);
+        
+        if (trackState) {
+          setInternalState((prev) => ({
+            ...prev,
+            connectionState: 'connected',
+          }));
+        }
+        
+        if (autoPlayAudio) {
+          const sampleRate =
+            merged?.audio?.output?.sample_rate ??
+            DEFAULT_INPUT_SAMPLE_RATE;
+          const channels = 1;
+          Deepgram.startPlayer?.(sampleRate, channels);
+        }
+        
         onConnectRef.current?.();
       };
 
@@ -803,6 +943,13 @@ export function useDeepgramVoiceAgent({
         onErrorRef.current?.(err);
       };
       socket.onclose = (event: any) => {
+        if (trackState) {
+          setInternalState((prev) => ({
+            ...prev,
+            connectionState: 'disconnected',
+          }));
+        }
+        
         cleanup();
         onCloseRef.current?.(event);
       };
@@ -871,6 +1018,12 @@ export function useDeepgramVoiceAgent({
     []
   );
 
+  const clearConversation = useCallback(() => {
+    if (trackConversation) {
+      setInternalConversation([]);
+    }
+  }, [trackConversation]);
+
   return {
     connect,
     disconnect,
@@ -883,5 +1036,8 @@ export function useDeepgramVoiceAgent({
     updatePrompt,
     sendMedia: sendBinary,
     isConnected,
+    ...(trackState ? { state: internalState } : {}),
+    ...(trackConversation ? { conversation: internalConversation, clearConversation } : {}),
+    ...(trackAgentStatus ? { agentStatus: internalAgentStatus } : {}),
   };
 }

From 1bb2d4894e42163d36ec55c9c80ddf15cf3ce05b Mon Sep 17 00:00:00 2001
From: Rares <rarpopa@hotmail.com>
Date: Fri, 28 Nov 2025 16:54:52 -0500
Subject: [PATCH 3/5] feat: Add iOS simulator warning for voice processing and
 simplify example sample rate options.

---
 example/src/TextToSpeech.tsx | 9 ++-------
 ios/Deepgram.mm              | 4 ++++
 2 files changed, 6 insertions(+), 7 deletions(-)

diff --git a/example/src/TextToSpeech.tsx b/example/src/TextToSpeech.tsx
index 288fcc4..77519e3 100644
--- a/example/src/TextToSpeech.tsx
+++ b/example/src/TextToSpeech.tsx
@@ -54,11 +54,6 @@ const STREAM_ENCODING_OPTIONS: Option[] = [
 const SAMPLE_RATE_OPTIONS: Option[] = [
   '8000',
   '16000',
-  '22050',
-  '24000',
-  '32000',
-  '44100',
-  '48000',
 ].map((value) => ({ label: `${value} Hz`, value }));
 
 const CONTAINER_OPTIONS: Option[] = [
@@ -127,7 +122,7 @@ export default function TextToSpeech() {
 
   const [httpModel, setHttpModel] = useState('aura-2-asteria-en');
   const [httpEncoding, setHttpEncoding] = useState('linear16');
-  const [httpSampleRate, setHttpSampleRate] = useState('24000');
+  const [httpSampleRate, setHttpSampleRate] = useState('16000');
   const [httpContainer, setHttpContainer] = useState('none');
   const [httpBitRate, setHttpBitRate] = useState('48000');
   const [httpCallbackUrl, setHttpCallbackUrl] = useState('');
@@ -136,7 +131,7 @@ export default function TextToSpeech() {
 
   const [streamModel, setStreamModel] = useState('aura-2-asteria-en');
   const [streamEncoding, setStreamEncoding] = useState('linear16');
-  const [streamSampleRate, setStreamSampleRate] = useState('24000');
+  const [streamSampleRate, setStreamSampleRate] = useState('16000');
   const [streamMipOptOut, setStreamMipOptOut] = useState(false);
   const modelOptions = useModelOptions();
 
diff --git a/ios/Deepgram.mm b/ios/Deepgram.mm
index 769d8d9..6829f31 100644
--- a/ios/Deepgram.mm
+++ b/ios/Deepgram.mm
@@ -787,6 +787,10 @@ - (BOOL)setupAudioEngineWithSampleRate:(int)sampleRate
   } @catch (NSException *exception) {
     // Continue - voice processing not critical for basic playback
   }
+
+#if TARGET_IPHONE_SIMULATOR
+  DGLogWarn(@"[Deepgram] NOTE: Voice Processing I/O (Echo Cancellation) is NOT supported on the iOS Simulator. Audio output may be picked up by the microphone. Please test on a physical device for proper AEC behavior.");
+#endif
   
   [self.audioEngine prepare];
   NSError *startError = nil;

From e2cb7bac958c69a5af2ed6c65cc011cad7255b60 Mon Sep 17 00:00:00 2001
From: Rares <rarpopa@hotmail.com>
Date: Fri, 28 Nov 2025 17:18:00 -0500
Subject: [PATCH 4/5] feat: Update Deepgram SDK to v2.0.0 and improve audio
 playback buffer management by removing `audioBuffer` and adding
 `_scheduledBufferCount`.

---
 example/ios/Podfile.lock |  4 +--
 ios/Deepgram.mm          | 60 +++++++++++++++++++++++++---------------
 package.json             |  2 +-
 3 files changed, 41 insertions(+), 25 deletions(-)

diff --git a/example/ios/Podfile.lock b/example/ios/Podfile.lock
index a24c59a..5fb78d3 100644
--- a/example/ios/Podfile.lock
+++ b/example/ios/Podfile.lock
@@ -1,6 +1,6 @@
 PODS:
   - boost (1.84.0)
-  - Deepgram (1.0.5):
+  - Deepgram (2.0.0):
     - DoubleConversion
     - glog
     - hermes-engine
@@ -1799,7 +1799,7 @@ EXTERNAL SOURCES:
 
 SPEC CHECKSUMS:
   boost: 1dca942403ed9342f98334bf4c3621f011aa7946
-  Deepgram: 234b0f4e42380dc2129dbc9d10533eb4019b5df0
+  Deepgram: 43333e852b373355fe2bec14eeaa43ba1e72f9ab
   DoubleConversion: f16ae600a246532c4020132d54af21d0ddb2a385
   EXConstants: fcfc75800824ac2d5c592b5bc74130bad17b146b
   Expo: 1687edb10c76b0c0f135306d6ae245379f50ed54
diff --git a/ios/Deepgram.mm b/ios/Deepgram.mm
index 6829f31..29eeb0d 100644
--- a/ios/Deepgram.mm
+++ b/ios/Deepgram.mm
@@ -9,6 +9,7 @@
 #endif
 #include <math.h>
 #include <string.h>
+#include <atomic>
 
 #define DGNumberBuffers 3
 
@@ -40,6 +41,7 @@
 @interface Deepgram : RCTEventEmitter
 {
   DGRecordState _recordState;
+  std::atomic<int> _scheduledBufferCount;
 }
 
 // Recording
@@ -53,7 +55,6 @@ @interface Deepgram : RCTEventEmitter
 @property (nonatomic, strong) AVAudioEngine      *audioEngine;
 @property (nonatomic, strong) AVAudioPlayerNode  *playerNode;
 @property (nonatomic, strong) AVAudioFormat      *playbackFormat;
-@property (nonatomic, strong) NSMutableData      *audioBuffer;
 @property (nonatomic, assign) BOOL                isPlaying;
 @property (nonatomic, assign) int                 currentSampleRate;
 @property (nonatomic, assign) BOOL                audioSessionConfigured;
@@ -138,6 +139,7 @@ - (instancetype)init
     _emitterQueue = dispatch_queue_create("com.deepgram.liveaudiostream",
                                           DISPATCH_QUEUE_SERIAL);
     memset(&_recordState, 0, sizeof(DGRecordState));
+    _scheduledBufferCount = 0;
     _appIsActive = YES;
 #if TARGET_OS_IOS
     [[NSNotificationCenter defaultCenter]
@@ -183,10 +185,8 @@ - (BOOL)activateAudioSession:(NSError **)outError
   __block BOOL success = YES;
   __block NSError *activationError = nil;
 
-  RCTUnsafeExecuteOnMainQueueSync(^{
-    DGLogDebug(@"[Deepgram] activateAudioSession: configuring on main queue");
-    success = [self configureAudioSessionIfNeeded:&activationError];
-  });
+  DGLogDebug(@"[Deepgram] activateAudioSession: configuring on current queue");
+  success = [self configureAudioSessionIfNeeded:&activationError];
 
   if (!success && activationError) {
     DGLogError(@"[Deepgram] Failed to activate audio session: %@",
@@ -205,13 +205,11 @@ - (BOOL)activateAudioSession:(NSError **)outError
 - (void)deactivateAudioSession
 {
   DGLogDebug(@"[Deepgram] deactivateAudioSession: begin");
-  RCTUnsafeExecuteOnMainQueueSync(^{
-    NSError *error = nil;
-    if (![[AVAudioSession sharedInstance] setActive:NO error:&error] && error) {
-      DGLogError(@"[Deepgram] Failed to deactivate audio session: %@",
-            error.localizedDescription ?: error);
-    }
-  });
+  NSError *error = nil;
+  if (![[AVAudioSession sharedInstance] setActive:NO error:&error] && error) {
+    DGLogError(@"[Deepgram] Failed to deactivate audio session: %@",
+          error.localizedDescription ?: error);
+  }
   self.audioSessionConfigured = NO;
 }
 
@@ -707,10 +705,6 @@ - (void)cleanupRecordingQueue
       if (reject) reject(@"audio_start_error", message, sessionError);
       return;
     }
-    if (!self.audioBuffer) {
-      self.audioBuffer = [[NSMutableData alloc] init];
-      DGLogDebug(@"[Deepgram] startAudio: created audioBuffer");
-    }
     if (self.currentSampleRate <= 0) {
       self.currentSampleRate = 16000;
       DGLogDebug(@"[Deepgram] startAudio: default sample rate applied %d", self.currentSampleRate);
@@ -855,7 +849,6 @@ - (AVAudioPCMBuffer *)createPCMBufferFromData:(NSData *)data {
     return;
   }
 
-  self.audioBuffer = [[NSMutableData alloc] init];
   self.isPlaying = NO;
   self.currentSampleRate = sampleRate.intValue;
 }
@@ -870,6 +863,17 @@ - (AVAudioPCMBuffer *)createPCMBufferFromData:(NSData *)data {
     if (!self.playerNode || !self.audioEngine || !self.audioEngine.isRunning) {
       return;
     }
+
+    // Safety: prevent unbounded memory growth if JS sends faster than playback
+    // 500 chunks * 200ms approx = 100 seconds of buffered audio.
+    // If we exceed this, we are likely leaking or hopelessly behind.
+    if (_scheduledBufferCount > 500) {
+      static dispatch_once_t onceToken;
+      dispatch_once(&onceToken, ^{
+        DGLogWarn(@"[Deepgram] feedAudio: dropping audio chunks (buffer full > 500). App might be receiving audio faster than playback.");
+      });
+      return;
+    }
     
     NSData *pcmData = [[NSData alloc] initWithBase64EncodedString:b64 options:0];
     if (!pcmData || pcmData.length == 0) {
@@ -882,7 +886,14 @@ - (AVAudioPCMBuffer *)createPCMBufferFromData:(NSData *)data {
       return;
     }
     
-    [self.playerNode scheduleBuffer:buffer completionHandler:nil];
+    _scheduledBufferCount++;
+    __weak Deepgram *weakSelf = self;
+    [self.playerNode scheduleBuffer:buffer completionHandler:^{
+      Deepgram *strongSelf = weakSelf;
+      if (strongSelf) {
+        strongSelf->_scheduledBufferCount--;
+      }
+    }];
     
     if (!self.playerNode.isPlaying) {
       [self.playerNode play];
@@ -905,19 +916,25 @@ - (AVAudioPCMBuffer *)createPCMBufferFromData:(NSData *)data {
     // Stop player node
     if (self.playerNode) {
       [self.playerNode stop];
+      if (self.audioEngine) {
+        [self.audioEngine detachNode:self.playerNode];
+      }
     }
     
     // Stop and cleanup audio engine
-    if (self.audioEngine && self.audioEngine.isRunning) {
-      [self.audioEngine stop];
+    if (self.audioEngine) {
+      if (self.audioEngine.isRunning) {
+        [self.audioEngine stop];
+      }
+      [self.audioEngine reset];
     }
     
     // Clear properties
     self.playerNode = nil;
     self.audioEngine = nil;
     self.playbackFormat = nil;
-    self.audioBuffer = nil;
     self.isPlaying = NO;
+    _scheduledBufferCount = 0;
 
     [self maybeDeactivateAudioSession];
 
@@ -1039,7 +1056,6 @@ - (void)invalidate
   self.audioEngine = nil;
   self.playbackFormat = nil;
 
-  self.audioBuffer = nil;
   self.isPlaying = NO;
   self.hasListeners = NO;
   self.appIsActive = NO;
diff --git a/package.json b/package.json
index 669c14e..8b61566 100644
--- a/package.json
+++ b/package.json
@@ -226,4 +226,4 @@
     "metro-symbolicate": "0.81.5",
     "metro-transform-worker": "0.81.5"
   }
-}
\ No newline at end of file
+}

From 349765ca40f41043edba90e91e555a9d73115824 Mon Sep 17 00:00:00 2001
From: Rares <rarpopa@hotmail.com>
Date: Fri, 28 Nov 2025 17:24:50 -0500
Subject: [PATCH 5/5] refactor: Clean up code formatting and improve
 readability across multiple files

---
 example/src/TextToSpeech.tsx         |  8 +--
 package.json                         |  4 +-
 src/helpers/audioUtils.ts            |  3 +-
 src/helpers/createAgentSettings.ts   | 30 ++++++-----
 src/types/deepgram/text-to-speech.ts |  2 +-
 src/useDeepgramSpeechToText.ts       | 71 +++++++++++++++++++-------
 src/useDeepgramTextIntelligence.ts   |  8 ++-
 src/useDeepgramTextToSpeech.ts       | 42 ++++++++++++----
 src/useDeepgramVoiceAgent.ts         | 75 +++++++++++++++++-----------
 9 files changed, 161 insertions(+), 82 deletions(-)

diff --git a/example/src/TextToSpeech.tsx b/example/src/TextToSpeech.tsx
index 77519e3..823076f 100644
--- a/example/src/TextToSpeech.tsx
+++ b/example/src/TextToSpeech.tsx
@@ -51,10 +51,10 @@ const STREAM_ENCODING_OPTIONS: Option[] = [
   { label: 'A-law (alaw)', value: 'alaw' },
 ];
 
-const SAMPLE_RATE_OPTIONS: Option[] = [
-  '8000',
-  '16000',
-].map((value) => ({ label: `${value} Hz`, value }));
+const SAMPLE_RATE_OPTIONS: Option[] = ['8000', '16000'].map((value) => ({
+  label: `${value} Hz`,
+  value,
+}));
 
 const CONTAINER_OPTIONS: Option[] = [
   { label: 'None', value: 'none' },
diff --git a/package.json b/package.json
index 8b61566..f5058d7 100644
--- a/package.json
+++ b/package.json
@@ -44,7 +44,7 @@
   "scripts": {
     "test": "jest",
     "typecheck": "tsc",
-    "lint": "eslint \"**/*.{js,ts,tsx}\"",
+    "lint": "eslint \"**/*.{js,ts,tsx}\" --fix",
     "clean": "del-cli android/build example/android/build example/android/app/build example/ios/build lib",
     "prepare": "bob build",
     "release": "release-it --only-version",
@@ -226,4 +226,4 @@
     "metro-symbolicate": "0.81.5",
     "metro-transform-worker": "0.81.5"
   }
-}
+}
\ No newline at end of file
diff --git a/src/helpers/audioUtils.ts b/src/helpers/audioUtils.ts
index 94b84a2..4cf0362 100644
--- a/src/helpers/audioUtils.ts
+++ b/src/helpers/audioUtils.ts
@@ -17,7 +17,8 @@ export function createAudioPlayerController() {
 
     feed: async (audio: ArrayBuffer | string) => {
       const { Deepgram } = await import('../NativeDeepgram');
-      const b64 = typeof audio === 'string' ? audio : arrayBufferToBase64(audio);
+      const b64 =
+        typeof audio === 'string' ? audio : arrayBufferToBase64(audio);
       await Deepgram.feedAudio?.(b64);
     },
 
diff --git a/src/helpers/createAgentSettings.ts b/src/helpers/createAgentSettings.ts
index b8437fa..da5631a 100644
--- a/src/helpers/createAgentSettings.ts
+++ b/src/helpers/createAgentSettings.ts
@@ -1,15 +1,17 @@
 import type { DeepgramVoiceAgentSettings } from '../types';
 
-export function createAgentSettings(opts: {
-  language?: string;
-  greeting?: string;
-  listenModel?: string;
-  thinkModel?: string;
-  prompt?: string;
-  temperature?: number | string;
-  tags?: string | string[];
-  sampleRate?: number | string;
-} = {}): DeepgramVoiceAgentSettings {
+export function createAgentSettings(
+  opts: {
+    language?: string;
+    greeting?: string;
+    listenModel?: string;
+    thinkModel?: string;
+    prompt?: string;
+    temperature?: number | string;
+    tags?: string | string[];
+    sampleRate?: number | string;
+  } = {}
+): DeepgramVoiceAgentSettings {
   const temperature = (() => {
     if (typeof opts.temperature === 'string') {
       const parsed = parseFloat(opts.temperature);
@@ -33,7 +35,7 @@ export function createAgentSettings(opts: {
 
   const sampleRate = (() => {
     if (typeof opts.sampleRate === 'string') {
-      const parsed = parseInt(opts.sampleRate);
+      const parsed = parseInt(opts.sampleRate, 10);
       return Number.isFinite(parsed) && parsed > 0 ? parsed : 16000;
     }
     if (typeof opts.sampleRate === 'number' && opts.sampleRate > 0) {
@@ -45,7 +47,11 @@ export function createAgentSettings(opts: {
   const settings: DeepgramVoiceAgentSettings = {
     audio: {
       input: { encoding: 'linear16', sample_rate: sampleRate },
-      output: { encoding: 'linear16', sample_rate: sampleRate, container: 'none' },
+      output: {
+        encoding: 'linear16',
+        sample_rate: sampleRate,
+        container: 'none',
+      },
     },
     agent: {
       language: opts.language?.trim() || 'en',
diff --git a/src/types/deepgram/text-to-speech.ts b/src/types/deepgram/text-to-speech.ts
index 250ebd5..ef6db97 100644
--- a/src/types/deepgram/text-to-speech.ts
+++ b/src/types/deepgram/text-to-speech.ts
@@ -334,7 +334,7 @@ export type UseDeepgramTextToSpeechReturn = {
   closeStreamGracefully: () => boolean;
   /** Forcefully close the WebSocket stream and release resources. */
   stopStreaming: () => void;
-  
+
   /** Current state of the TTS session (if trackState is enabled) */
   state?: {
     status: 'idle' | 'loading' | 'connecting' | 'connected' | 'error';
diff --git a/src/useDeepgramSpeechToText.ts b/src/useDeepgramSpeechToText.ts
index 2970dcc..1db98ed 100644
--- a/src/useDeepgramSpeechToText.ts
+++ b/src/useDeepgramSpeechToText.ts
@@ -80,9 +80,10 @@ export function useDeepgramSpeechToText({
 
   // Transcript tracking state
   const [internalTranscript, setInternalTranscript] = useState('');
-  const [internalInterimTranscript, setInternalInterimTranscript] = useState('');
+  const [internalInterimTranscript, setInternalInterimTranscript] =
+    useState('');
 
-  const closeEverything = () => {
+  const closeEverything = useCallback(() => {
     if (audioSub.current) {
       audioSub.current.remove();
       audioSub.current = null;
@@ -113,7 +114,7 @@ export function useDeepgramSpeechToText({
       setInternalTranscript('');
       setInternalInterimTranscript('');
     }
-  };
+  }, [trackState, trackTranscript]);
 
   const emitTranscript = useCallback(
     (transcript: unknown, isFinal: boolean, raw: unknown) => {
@@ -163,7 +164,7 @@ export function useDeepgramSpeechToText({
         lastPartialTranscriptRef.current = '';
       }
     },
-    [onTranscript]
+    [onTranscript, trackTranscript]
   );
 
   const startListening = useCallback(
@@ -343,7 +344,10 @@ export function useDeepgramSpeechToText({
                     msg.description || 'Deepgram stream error';
                   onError(new Error(description));
                   if (trackState) {
-                    setInternalState({ status: 'error', error: new Error(description) });
+                    setInternalState({
+                      status: 'error',
+                      error: new Error(description),
+                    });
                   }
                   closeEverything();
                   return;
@@ -383,7 +387,10 @@ export function useDeepgramSpeechToText({
         ws.current.onerror = (err) => {
           onError(err);
           if (trackState) {
-            setInternalState({ status: 'error', error: err instanceof Error ? err : new Error(String(err)) });
+            setInternalState({
+              status: 'error',
+              error: err instanceof Error ? err : new Error(String(err)),
+            });
           }
         };
         ws.current.onclose = () => {
@@ -393,12 +400,24 @@ export function useDeepgramSpeechToText({
       } catch (err) {
         onError(err);
         if (trackState) {
-          setInternalState({ status: 'error', error: err instanceof Error ? err : new Error(String(err)) });
+          setInternalState({
+            status: 'error',
+            error: err instanceof Error ? err : new Error(String(err)),
+          });
         }
         closeEverything();
       }
     },
-    [emitTranscript, onBeforeStart, onStart, onError, onEnd, live]
+    [
+      emitTranscript,
+      onBeforeStart,
+      onStart,
+      onError,
+      onEnd,
+      live,
+      closeEverything,
+      trackState,
+    ]
   );
 
   const stopListening = useCallback(() => {
@@ -408,10 +427,13 @@ export function useDeepgramSpeechToText({
     } catch (err) {
       onError(err);
       if (trackState) {
-        setInternalState({ status: 'error', error: err instanceof Error ? err : new Error(String(err)) });
+        setInternalState({
+          status: 'error',
+          error: err instanceof Error ? err : new Error(String(err)),
+        });
       }
     }
-  }, [onEnd, onError]);
+  }, [onEnd, onError, closeEverything, trackState]);
 
   const transcribeFile = useCallback(
     async (
@@ -559,21 +581,32 @@ export function useDeepgramSpeechToText({
       } catch (err) {
         onTranscribeError(err);
         if (trackState) {
-          setInternalState({ status: 'error', error: err instanceof Error ? err : new Error(String(err)) });
+          setInternalState({
+            status: 'error',
+            error: err instanceof Error ? err : new Error(String(err)),
+          });
         }
       }
     },
-    [onBeforeTranscribe, onTranscribeSuccess, onTranscribeError, prerecorded]
+    [
+      onBeforeTranscribe,
+      onTranscribeSuccess,
+      onTranscribeError,
+      prerecorded,
+      trackState,
+    ]
   );
 
-  return { 
-    startListening, 
-    stopListening, 
+  return {
+    startListening,
+    stopListening,
     transcribeFile,
     ...(trackState ? { state: internalState } : {}),
-    ...(trackTranscript ? { 
-      transcript: internalTranscript,
-      interimTranscript: internalInterimTranscript 
-    } : {}),
+    ...(trackTranscript
+      ? {
+          transcript: internalTranscript,
+          interimTranscript: internalInterimTranscript,
+        }
+      : {}),
   };
 }
diff --git a/src/useDeepgramTextIntelligence.ts b/src/useDeepgramTextIntelligence.ts
index 4818fdd..23a5061 100644
--- a/src/useDeepgramTextIntelligence.ts
+++ b/src/useDeepgramTextIntelligence.ts
@@ -104,7 +104,10 @@ export function useDeepgramTextIntelligence({
         if (err.name === 'AbortError') return;
         onAnalyzeError(err);
         if (trackState) {
-          setInternalState({ status: 'error', error: err instanceof Error ? err : new Error(String(err)) });
+          setInternalState({
+            status: 'error',
+            error: err instanceof Error ? err : new Error(String(err)),
+          });
         }
       }
     },
@@ -123,6 +126,7 @@ export function useDeepgramTextIntelligence({
       language,
       callback,
       callbackMethod,
+      trackState,
     ]
   );
 
@@ -132,7 +136,7 @@ export function useDeepgramTextIntelligence({
     };
   }, []);
 
-  return { 
+  return {
     analyze,
     ...(trackState ? { state: internalState } : {}),
   };
diff --git a/src/useDeepgramTextToSpeech.ts b/src/useDeepgramTextToSpeech.ts
index f2c3bf7..d82020e 100644
--- a/src/useDeepgramTextToSpeech.ts
+++ b/src/useDeepgramTextToSpeech.ts
@@ -332,7 +332,10 @@ export function useDeepgramTextToSpeech({
 
         onSynthesizeError(err);
         if (trackState) {
-          setInternalState({ status: 'error', error: err instanceof Error ? err : new Error(String(err)) });
+          setInternalState({
+            status: 'error',
+            error: err instanceof Error ? err : new Error(String(err)),
+          });
         }
         throw err;
       }
@@ -342,13 +345,14 @@ export function useDeepgramTextToSpeech({
       onSynthesizeSuccess,
       onSynthesizeError,
       resolvedHttpOptions,
+      trackState,
     ]
   );
 
   /* ---------- WebSocket (streaming synth) ---------- */
   const ws = useRef<WebSocket | null>(null);
 
-  const closeStream = () => {
+  const closeStream = useCallback(() => {
     ws.current?.close(1000, 'cleanup');
     ws.current = null;
     if (autoPlayAudio) {
@@ -357,7 +361,7 @@ export function useDeepgramTextToSpeech({
     if (trackState) {
       setInternalState((prev) => ({ ...prev, status: 'idle' }));
     }
-  };
+  }, [autoPlayAudio, trackState]);
 
   const sendMessage = useCallback(
     (message: DeepgramTextToSpeechStreamInputMessage) => {
@@ -371,12 +375,15 @@ export function useDeepgramTextToSpeech({
       } catch (err) {
         onStreamError(err);
         if (trackState) {
-          setInternalState({ status: 'error', error: err instanceof Error ? err : new Error(String(err)) });
+          setInternalState({
+            status: 'error',
+            error: err instanceof Error ? err : new Error(String(err)),
+          });
         }
         return false;
       }
     },
-    [onStreamError]
+    [onStreamError, trackState]
   );
 
   const flushStream = useCallback(
@@ -466,7 +473,8 @@ export function useDeepgramTextToSpeech({
         ws.current.onopen = () => {
           if (autoPlayAudio) {
             Deepgram.startPlayer(
-              Number(resolvedStreamOptions.sampleRate) || DEFAULT_TTS_SAMPLE_RATE,
+              Number(resolvedStreamOptions.sampleRate) ||
+                DEFAULT_TTS_SAMPLE_RATE,
               1
             );
           }
@@ -548,7 +556,10 @@ export function useDeepgramTextToSpeech({
         ws.current.onerror = (err) => {
           onStreamError(err);
           if (trackState) {
-            setInternalState({ status: 'error', error: err instanceof Error ? err : new Error(String(err)) });
+            setInternalState({
+              status: 'error',
+              error: err instanceof Error ? err : new Error(String(err)),
+            });
           }
         };
         ws.current.onclose = () => {
@@ -558,7 +569,10 @@ export function useDeepgramTextToSpeech({
       } catch (err) {
         onStreamError(err);
         if (trackState) {
-          setInternalState({ status: 'error', error: err instanceof Error ? err : new Error(String(err)) });
+          setInternalState({
+            status: 'error',
+            error: err instanceof Error ? err : new Error(String(err)),
+          });
         }
         closeStream();
         throw err;
@@ -576,6 +590,9 @@ export function useDeepgramTextToSpeech({
       onStreamWarning,
       resolvedStreamOptions,
       sendText,
+      autoPlayAudio,
+      closeStream,
+      trackState,
     ]
   );
 
@@ -586,10 +603,13 @@ export function useDeepgramTextToSpeech({
     } catch (err) {
       onStreamError(err);
       if (trackState) {
-        setInternalState({ status: 'error', error: err instanceof Error ? err : new Error(String(err)) });
+        setInternalState({
+          status: 'error',
+          error: err instanceof Error ? err : new Error(String(err)),
+        });
       }
     }
-  }, [onStreamEnd, onStreamError]);
+  }, [onStreamEnd, onStreamError, closeStream, trackState]);
 
   /* ---------- cleanup on unmount ---------- */
   useEffect(
@@ -597,7 +617,7 @@ export function useDeepgramTextToSpeech({
       abortCtrl.current?.abort();
       closeStream();
     },
-    []
+    [closeStream]
   );
 
   return {
diff --git a/src/useDeepgramVoiceAgent.ts b/src/useDeepgramVoiceAgent.ts
index ab856b8..e7da6a9 100644
--- a/src/useDeepgramVoiceAgent.ts
+++ b/src/useDeepgramVoiceAgent.ts
@@ -589,36 +589,39 @@ export function useDeepgramVoiceAgent({
               break;
             case 'ConversationText':
               if (hasKeys(message, ['role', 'content'])) {
-                const convMsg = message as DeepgramVoiceAgentConversationTextMessage;
-                
+                const convMsg =
+                  message as DeepgramVoiceAgentConversationTextMessage;
+
                 if (trackConversation) {
                   setInternalConversation((prev) => [
                     ...prev,
                     { role: convMsg.role, content: convMsg.content },
                   ]);
                 }
-                
+
                 onConversationTextRef.current?.(convMsg);
               }
               break;
             case 'AgentThinking':
               if (hasKeys(message, ['content'])) {
-                const thinkMsg = message as DeepgramVoiceAgentAgentThinkingMessage;
-                
+                const thinkMsg =
+                  message as DeepgramVoiceAgentAgentThinkingMessage;
+
                 if (trackAgentStatus) {
                   setInternalAgentStatus((prev) => ({
                     ...prev,
                     thinking: thinkMsg.content,
                   }));
                 }
-                
+
                 onAgentThinkingRef.current?.(thinkMsg);
               }
               break;
             case 'AgentStartedSpeaking':
               {
-                const speakMsg = message as DeepgramVoiceAgentAgentStartedSpeakingMessage;
-                
+                const speakMsg =
+                  message as DeepgramVoiceAgentAgentStartedSpeakingMessage;
+
                 if (trackAgentStatus) {
                   setInternalAgentStatus((prev) => ({
                     ...prev,
@@ -629,21 +632,22 @@ export function useDeepgramVoiceAgent({
                     },
                   }));
                 }
-                
+
                 onAgentStartedSpeakingRef.current?.(speakMsg);
               }
               break;
             case 'AgentAudioDone':
               {
-                const doneMsg = message as DeepgramVoiceAgentAgentAudioDoneMessage;
-                
+                const doneMsg =
+                  message as DeepgramVoiceAgentAgentAudioDoneMessage;
+
                 if (trackAgentStatus) {
                   setInternalAgentStatus({
                     thinking: null,
                     latency: null,
                   });
                 }
-                
+
                 onAgentAudioDoneRef.current?.(doneMsg);
               }
               break;
@@ -681,14 +685,16 @@ export function useDeepgramVoiceAgent({
               break;
             case 'AudioConfig':
               if (hasKeys(message, ['sample_rate'])) {
-                const configMsg = message as DeepgramVoiceAgentAudioConfigMessage;
-                
+                const configMsg =
+                  message as DeepgramVoiceAgentAudioConfigMessage;
+
                 if (autoPlayAudio) {
-                  const sampleRate = configMsg.sample_rate || DEFAULT_INPUT_SAMPLE_RATE;
+                  const sampleRate =
+                    configMsg.sample_rate || DEFAULT_INPUT_SAMPLE_RATE;
                   const channels = configMsg.channels || 1;
                   Deepgram.startPlayer?.(sampleRate, channels);
                 }
-                
+
                 onAudioConfigRef.current?.(configMsg);
               }
               break;
@@ -702,14 +708,14 @@ export function useDeepgramVoiceAgent({
             case 'Warning':
               if (hasKeys(message, ['description'])) {
                 const warnMsg = message as DeepgramVoiceAgentWarningMessage;
-                
+
                 if (trackState) {
                   setInternalState((prev) => ({
                     ...prev,
                     warning: warnMsg.description,
                   }));
                 }
-                
+
                 onWarningRef.current?.(warnMsg);
               }
               break;
@@ -725,7 +731,7 @@ export function useDeepgramVoiceAgent({
                     : undefined;
 
                 const errorMsg = description ?? code ?? 'Voice agent error';
-                
+
                 if (trackState) {
                   setInternalState((prev) => ({
                     ...prev,
@@ -763,7 +769,7 @@ export function useDeepgramVoiceAgent({
             console.warn('[VoiceAgent] Auto-feed audio error:', err);
           }
         }
-        
+
         onAudioRef.current?.(buffer);
       }
     },
@@ -783,6 +789,10 @@ export function useDeepgramVoiceAgent({
       onSpeakUpdatedRef,
       onUserStartedSpeakingRef,
       onWarningRef,
+      autoPlayAudio,
+      trackAgentStatus,
+      trackConversation,
+      trackState,
     ]
   );
 
@@ -849,7 +859,7 @@ export function useDeepgramVoiceAgent({
   const connect = useCallback(
     async (overrideSettings?: DeepgramVoiceAgentSettings) => {
       cleanup();
-      
+
       if (trackState) {
         setInternalState({
           connectionState: 'connecting',
@@ -857,14 +867,14 @@ export function useDeepgramVoiceAgent({
           warning: null,
         });
       }
-      
+
       if (trackConversation) {
         setInternalConversation([]);
       }
       if (trackAgentStatus) {
         setInternalAgentStatus({ thinking: null, latency: null });
       }
-      
+
       onBeforeConnectRef.current?.();
 
       const apiKey = (globalThis as any).__DEEPGRAM_API_KEY__;
@@ -919,22 +929,21 @@ export function useDeepgramVoiceAgent({
 
       socket.onopen = () => {
         sendJsonMessage(mergedSettings);
-        
+
         if (trackState) {
           setInternalState((prev) => ({
             ...prev,
             connectionState: 'connected',
           }));
         }
-        
+
         if (autoPlayAudio) {
           const sampleRate =
-            merged?.audio?.output?.sample_rate ??
-            DEFAULT_INPUT_SAMPLE_RATE;
+            merged?.audio?.output?.sample_rate ?? DEFAULT_INPUT_SAMPLE_RATE;
           const channels = 1;
           Deepgram.startPlayer?.(sampleRate, channels);
         }
-        
+
         onConnectRef.current?.();
       };
 
@@ -949,7 +958,7 @@ export function useDeepgramVoiceAgent({
             connectionState: 'disconnected',
           }));
         }
-        
+
         cleanup();
         onCloseRef.current?.(event);
       };
@@ -962,6 +971,10 @@ export function useDeepgramVoiceAgent({
       mergeSettings,
       sanitizeSettings,
       sendJsonMessage,
+      autoPlayAudio,
+      trackAgentStatus,
+      trackConversation,
+      trackState,
     ]
   );
 
@@ -1037,7 +1050,9 @@ export function useDeepgramVoiceAgent({
     sendMedia: sendBinary,
     isConnected,
     ...(trackState ? { state: internalState } : {}),
-    ...(trackConversation ? { conversation: internalConversation, clearConversation } : {}),
+    ...(trackConversation
+      ? { conversation: internalConversation, clearConversation }
+      : {}),
     ...(trackAgentStatus ? { agentStatus: internalAgentStatus } : {}),
   };
 }