diff --git a/CHANGELOG.md b/CHANGELOG.md
index a47194f..a8761e0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,11 +9,64 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **Recording to file.** `useDeepgramSpeechToText` now supports `recordToFile`
+  option to persist microphone audio to a WAV file while simultaneously streaming
+  to Deepgram. The resulting `file://` URI is delivered via `onRecordingComplete`
+  callback and `recordingUri` state property once `stopListening` completes.
+  Recording format is uncompressed WAV (16 kHz PCM16 mono), mirroring the audio
+  streamed to Deepgram.
+- **Audio-level metering.** Added microphone audio-level (RMS amplitude 0..1)
+  support via `metering` configuration in `useDeepgramSpeechToText`. When enabled,
+  the native module emits normalized audio levels at configurable intervals,
+  surfaced through `audioLevel` state and `onAudioLevel` callback. Useful for
+  implementing visual feedback like waveforms or voice activity indicators.
+- **Auto-reconnect for live streaming.** Introduced `DeepgramReconnectOptions` for
+  automatic reconnection on unexpected socket close in Speech-to-Text and Voice
+  Agent. Configure max retries, initial/max backoff delays via `reconnect` prop.
+  Includes `onReconnecting` and `onReconnected` callbacks for monitoring reconnect
+  attempts.
+- **Pause/resume streaming.** `useDeepgramSpeechToText` now exposes `pause()` and
+  `resume()` methods to temporarily stop forwarding microphone frames without
+  tearing down the WebSocket. Sends `Finalize` once (v1) to flush buffered audio
+  and starts periodic `KeepAlive` to maintain the connection during pause. State
+  tracked via `isPaused` property when `trackState` is enabled.
+- **Mute/unmute for Voice Agent.** `useDeepgramVoiceAgent` now supports
+  `setMuted(boolean)` to control microphone input while maintaining an active
+  session. Keep-alive messages are sent while muted to prevent timeout.
+- **Text-to-Speech `synthesizeToBytes` method.** Added method to fetch synthesized
+  audio as raw bytes (`ArrayBuffer`) with MIME type without automatically playing
+  it, enabling audio caching/persistence. Results are cached in-memory (LRU) keyed
+  by text + format to avoid duplicate network requests for identical prompts.
+  Accepts optional per-call `options` to override HTTP format.
+- **Token-based authentication.** Introduced global `__DEEPGRAM_GET_TOKEN__`
+  function alongside existing `__DEEPGRAM_API_KEY__` for dynamic token
+  provisioning. The SDK automatically caches tokens with TTL-aware refresh and
+  deduplicates concurrent token requests. New `clearCachedAuthToken()` helper
+  forces fresh token retrieval. See `src/helpers/auth.ts`.
+- **Audio device enumeration and selection.** Added `getAudioDevices()` and
+  `selectAudioDevice(deviceId)` methods for managing audio output devices,
+  including Bluetooth headsets and built-in options. Event listeners notify of
+  audio device changes. Requires Bluetooth permissions on Android 12+.
+  _(Note: audio route management methods were later removed in a refactor.)_
+- **Structured error handling.** Introduced `DeepgramError` class with typed
+  `DeepgramErrorCode` for consistent error handling across all hooks. Native
+  rejections now use stable error codes (`permission_denied`, `init_failed`,
+  `start_error`, `stop_error`, `audio_start_error`, `audio_stop_error`,
+  `stop_player_error`, `invalid_data`, `playback_error`) so consumers can branch
+  programmatically instead of string-matching messages.
+- **Configuration overrides.** New `configure()` function accepts `baseUrl`,
+  `websocketUrl`, and `agentUrl` overrides for custom endpoints or proxying.
+  Hooks dynamically resolve URLs based on configuration.
 - **Live `measurements` option.** `DeepgramLiveListenOptions` now supports the
   `measurements` flag, mirroring the existing prerecorded option. When enabled it
   is serialized into the live/streaming query (`measurements=true`) for both the
   v1 and v2 (Flux) realtime paths, converting spoken measurements into
   abbreviated forms during live transcription.
+- **iOS audio session management.** Comprehensive audio session lifecycle
+  management including activation, deactivation, configuration for recording and
+  playback, handling for audio route changes, media services resets, and audio
+  interruptions. Enhanced playback with AVAudioPlayerNode for TTS and Voice Agent
+  with echo cancellation support when voice processing is enabled.
 
 ### Fixed
 
diff --git a/README.md b/README.md
index a0a7938..5f78d95 100644
--- a/README.md
+++ b/README.md
@@ -14,12 +14,12 @@ yarn add react-native-deepgram
 | | |
 | --- | --- |
 | 🗣️ **Voice Agent** | Full-duplex agents over Deepgram's WebSocket. Hardware AEC on iOS (VPIO) and Android (`VOICE_COMMUNICATION` + `MODE_IN_COMMUNICATION`). Function calling, prompt updates, latency telemetry. |
-| 🎙️ **Speech-to-Text** | Live PCM streaming over WebSocket on STT v1 *or* Flux v2 (`flux-general-en`). File transcription with summarisation, topics, intents, entities. |
+| 🎙️ **Speech-to-Text** | Live PCM streaming over WebSocket on STT v1 *or* Flux v2 (`flux-general-en`). File transcription with summarisation, topics, intents, entities. Optionally record the mic to a WAV file while you stream. |
 | 🔊 **Text-to-Speech** | One-shot HTTP synthesis or low-latency WebSocket streaming with `Speak` / `Flush` / `Clear` / `Close` controls. |
 | 🧠 **Text Intelligence** | Summaries, topics, intents, sentiment over text or URLs. |
 | 🛠️ **Management API** | Typed wrapper for projects, models, keys, usage, balances, members, invitations, scopes, purchases, and temporary tokens. |
 | ⚙️ **Expo plugin** | One-line install — handles permissions, background-audio modes, and Android foreground service automatically. |
-| 🧰 **Resilient by default** | Audio interruptions, route changes, headphone unplugging, mediaserverd resets, audio-focus loss, and queue overflow are all handled. |
+| 🧰 **Resilient by default** | Audio interruptions, route changes, headphone unplugging, mediaserverd resets, audio-focus loss, and queue overflow are all handled — plus opt-in WebSocket auto-reconnect with exponential backoff. |
 | 🆕 **Modern iOS APIs** | `AVAudioApplication.requestRecordPermission` and `AllowBluetoothHFP` on iOS 17+, with safe fallbacks. |
 
 ---
@@ -232,6 +232,51 @@ configure({ apiKey: process.env.EXPO_PUBLIC_DEEPGRAM_API_KEY! });
 
 > **Never ship raw API keys.** Use `EXPO_PUBLIC_*` env vars, secrets storage, or a backend proxy that mints scoped keys.
 
+#### Custom endpoints (regional, Dedicated & self-hosted)
+
+Point the SDK at a non-default Deepgram deployment by passing base URLs to `configure`. Every override is optional and falls back to the public Deepgram endpoints.
+
+```ts
+configure({
+  apiKey: process.env.EXPO_PUBLIC_DEEPGRAM_API_KEY!,
+  baseUrl: 'https://api.beta.deepgram.com/v1', // REST (must include the version segment)
+  baseWss: 'wss://api.beta.deepgram.com/v1',   // live STT + streaming TTS sockets
+  agentUrl: 'wss://agent.deepgram.com/v1/agent/converse', // Voice Agent socket
+});
+```
+
+| Option | Applies to | Default |
+| ------ | ---------- | ------- |
+| `baseUrl` | REST calls (file STT, TTS, Text Intelligence, Management) | `https://api.deepgram.com/v1` |
+| `baseWss` | Live STT + streaming TTS sockets | `wss://api.deepgram.com/v1` |
+| `agentUrl` | Voice Agent socket | `wss://agent.deepgram.com/v1/agent/converse` |
+
+`baseUrl`/`baseWss` **must include the version segment** (`/v1`). Flux v2 endpoints are derived automatically by swapping the trailing `/v1` for `/v2`. See Deepgram's [custom endpoints reference](https://developers.deepgram.com/reference/custom-endpoints).
+
+#### Ephemeral / scoped tokens (keep your API key off-device)
+
+Instead of shipping a long-lived `apiKey`, you can hand `configure` a `getToken` provider that returns a short-lived Deepgram token minted by your backend (which proxies Deepgram's [`/v1/auth/grant`](https://developers.deepgram.com/reference/token-based-auth-api/grant-token)). The SDK caches the token, refreshes it before it expires, and de-duplicates concurrent refreshes — so a burst of requests never triggers multiple grants.
+
+```ts
+configure({
+  // No raw apiKey on the device. `getToken` takes precedence when provided.
+  getToken: async () => {
+    const res = await fetch('https://your-backend.example.com/deepgram-token');
+    const { access_token, expires_in } = await res.json();
+    return { token: access_token, expiresInSeconds: expires_in };
+  },
+});
+```
+
+| Field | Type | Description |
+| ----- | ---- | ----------- |
+| `token` | `string` | The short-lived token. Sent as `Authorization: Bearer <token>`. |
+| `expiresInSeconds` | `number` (optional) | TTL hint used to refresh ahead of expiry. Defaults to `30`. |
+
+- When both `getToken` and `apiKey` are set, `getToken` wins; the API key is the fallback.
+- The token only needs to be valid at connection time — live STT / Voice Agent sockets keep running after it expires.
+- **Exception:** the Management API (`useDeepgramManagement`) cannot authenticate with temporary tokens, so it always uses the configured `apiKey`.
+
 ### 2. Hooks return reactive state — opt in
 
 Every hook supports `track*` flags that turn on a reactive return value. Without them, the hook stays event-driven (callbacks only) so it never causes unnecessary re-renders.
@@ -266,6 +311,26 @@ For tuning details, see [Audio session, AEC & background](#audio-session-aec--ba
 | `useDeepgramTextIntelligence` | Summaries, topics, intents, sentiment | `https://api.deepgram.com/v1/read` |
 | `useDeepgramManagement` | Projects / keys / usage REST API | `https://api.deepgram.com/v1` |
 
+### 5. Typed errors
+
+Every error the hooks surface — mic-permission denials, native start/stop failures, fetch and WebSocket errors — is normalized to a `DeepgramError` with a typed `code`, so you can branch on a stable enum instead of string-matching messages. The original failure is preserved on `cause`.
+
+```ts
+import { DeepgramError, type DeepgramErrorCode } from 'react-native-deepgram';
+
+useDeepgramSpeechToText({
+  onError: (err) => {
+    if (err instanceof DeepgramError && err.code === 'permission_denied') {
+      promptForMicAccess();
+    }
+  },
+});
+```
+
+The `code` is one of the native reject codes (or `'unknown'` when it can't be mapped):
+
+`permission_denied` · `init_failed` · `start_error` · `stop_error` · `audio_start_error` · `audio_stop_error` · `stop_player_error` · `invalid_data` · `playback_error`
+
 ---
 
 ## Audio session, AEC & background
@@ -411,6 +476,8 @@ return (
 const {
   // Connection
   connect, disconnect, isConnected,
+  // Mic control
+  mute, unmute, isMuted,
   // Messaging
   sendMessage, sendSettings, sendMedia, sendKeepAlive,
   injectUserMessage, injectAgentMessage, updatePrompt,
@@ -432,6 +499,7 @@ const {
 | `autoStartMicrophone` | `boolean` | `true` | Automatically requests mic access and starts streaming PCM. |
 | `autoPlayAudio` | `boolean` | `true` | Plays received audio using the native player. |
 | `downsampleFactor` | `number` | heuristic | Manually override the downsample ratio applied to captured audio. |
+| `reconnect` | `DeepgramReconnectOptions` | `{ enabled: false }` | Auto-reconnect config for the agent socket. The stored `Settings` payload is re-sent on every successful reconnect. |
 
 **Reactive tracking flags** (opt-in — extra renders only when set)
 
@@ -452,6 +520,8 @@ const {
 | `onConnect` | `() => void` | Socket opens and the initial settings payload is delivered. |
 | `onClose` | `(event?: any) => void` | Socket closes (manual disconnect or remote). |
 | `onError` | `(error: unknown) => void` | Unexpected client-side error (mic, playback, socket send). |
+| `onReconnecting` | `(attempt: number) => void` | A reconnect attempt begins (1-based attempt number). Requires `reconnect.enabled`. |
+| `onReconnected` | `() => void` | The socket reconnects and the stored settings are re-sent. |
 | `onServerError` | `(message: DeepgramVoiceAgentErrorMessage) => void` | API reports a structured error (`description` + `code`). |
 | `onWarning` | `(message: DeepgramVoiceAgentWarningMessage) => void` | Non-fatal warning (e.g. degraded audio quality). |
 
@@ -499,6 +569,8 @@ const {
 | `connect` | `(settings?: DeepgramVoiceAgentSettings) => Promise<void>` | Opens the socket, optionally merges settings, starts mic streaming. |
 | `disconnect` | `() => void` | Tears down the socket, stops recording, removes listeners. |
 | `isConnected` | `() => boolean` | Returns `true` when the socket is open. |
+| `mute` | `() => void` | Stops forwarding mic audio while keeping the socket alive with periodic `KeepAlive` frames. |
+| `unmute` | `() => void` | Resumes forwarding microphone audio. |
 
 **Messaging**
 
@@ -528,6 +600,7 @@ Each value is `undefined` unless its corresponding `track*` flag is `true`.
 | Return | Type | Requires |
 | ------ | ---- | -------- |
 | `state` | `{ connectionState: 'idle' \| 'connecting' \| 'connected' \| 'disconnected'; error: string \| null; warning: string \| null }` | `trackState: true` |
+| `isMuted` | `boolean` | `trackState: true` |
 | `conversation` | `Array<{ role: string; content: string }>` | `trackConversation: true` |
 | `agentStatus` | `{ thinking: string \| null; latency: { total?: number; tts?: number; ttt?: number } \| null }` | `trackAgentStatus: true` |
 | `clearConversation` | `() => void` | `trackConversation: true` |
@@ -619,11 +692,11 @@ const pickFile = async () => {
 ```ts
 const {
   // Live streaming
-  startListening, stopListening,
+  startListening, stopListening, pause, resume,
   // File transcription
   transcribeFile,
   // Reactive state (opt-in)
-  state, transcript, interimTranscript,
+  state, transcript, interimTranscript, isPaused, audioLevel, recordingUri,
 } = useDeepgramSpeechToText(props);
 ```
 
@@ -635,6 +708,9 @@ const {
 | ---- | ---- | ----------- |
 | `live` | `DeepgramLiveListenOptions` | Default options merged into every live stream. |
 | `prerecorded` | `DeepgramPrerecordedOptions` | Default options merged into every file transcription. |
+| `reconnect` | `DeepgramReconnectOptions` | Auto-reconnect config for the live socket. Disabled unless `reconnect.enabled` is `true`. |
+| `metering` | `{ enabled?: boolean; intervalMs?: number }` | Microphone audio-level (VU meter) events. Disabled by default; set `enabled: true` to emit a normalized RMS level (~10 Hz, tune with `intervalMs`). |
+| `recordToFile` | `{ enabled?: boolean; path?: string; format?: 'wav' }` | Persist the captured mic audio to a WAV file while it streams. Disabled by default. Omit `path` to let the native module pick an app-specific location. |
 
 **Live streaming callbacks**
 
@@ -644,7 +720,11 @@ const {
 | `onStart` | `() => void` | The WebSocket opens. |
 | `onTranscript` | `(transcript: string, event?: DeepgramTranscriptEvent) => void` | Every transcript update (partial and final). |
 | `onError` | `(error: unknown) => void` | A streaming error occurs. |
-| `onEnd` | `() => void` | The socket closes. |
+| `onAudioLevel` | `(level: number) => void` | A new mic audio level (`0..1` normalized RMS) is available. Requires `metering.enabled`. |
+| `onRecordingComplete` | `(uri: string) => void` | A `recordToFile` session finished; receives the `file://` URI of the saved WAV. Requires `recordToFile.enabled`. |
+| `onReconnecting` | `(attempt: number) => void` | A reconnect attempt begins (1-based attempt number). Requires `reconnect.enabled`. |
+| `onReconnected` | `() => void` | The live socket successfully reconnects. |
+| `onEnd` | `() => void` | The socket closes (manual stop, or after reconnect attempts are exhausted). |
 
 **File transcription callbacks**
 
@@ -667,6 +747,8 @@ const {
 | ------ | --------- | ----------- |
 | `startListening` | `(options?: DeepgramLiveListenOptions) => Promise<void>` | Requests mic access, starts recording, streams audio to Deepgram. |
 | `stopListening` | `() => void` | Stops recording and closes the active WebSocket. |
+| `pause` | `() => void` | Pauses mic streaming while keeping the socket alive via `KeepAlive`. On v1 a `Finalize` is sent first to flush buffered audio. |
+| `resume` | `() => void` | Resumes mic streaming after a `pause`. |
 | `transcribeFile` | `(file: DeepgramPrerecordedSource, options?: DeepgramPrerecordedOptions) => Promise<void>` | Uploads a file/URI/URL and resolves via the success/error callbacks. |
 
 #### Reactive state
@@ -674,6 +756,9 @@ const {
 | Return | Type | Requires |
 | ------ | ---- | -------- |
 | `state` | `{ status: 'idle' \| 'loading' \| 'listening' \| 'transcribing' \| 'error'; error: Error \| null }` | `trackState: true` |
+| `isPaused` | `boolean` | `trackState: true` |
+| `audioLevel` | `number` (0..1 normalized RMS) | `trackState: true` + `metering.enabled` |
+| `recordingUri` | `string` (last saved `file://` WAV) | `trackState: true` + `recordToFile.enabled` |
 | `transcript` | `string` | `trackTranscript: true` |
 | `interimTranscript` | `string` | `trackTranscript: true` |
 
@@ -926,7 +1011,7 @@ closeStreamGracefully();
 ```ts
 const {
   // HTTP synthesis
-  synthesize,
+  synthesize, synthesizeToBytes,
   // Streaming
   startStreaming, sendText, sendMessage,
   flushStream, clearStream,
@@ -975,6 +1060,7 @@ const {
 | Method | Signature | Description |
 | ------ | --------- | ----------- |
 | `synthesize` | `(text: string) => Promise<ArrayBuffer>` | Single-shot REST call; resolves with the full audio buffer. |
+| `synthesizeToBytes` | `(text: string, options?: DeepgramTextToSpeechHttpOptions) => Promise<{ data: ArrayBuffer; mimeType: string }>` | Like `synthesize` but **does not play** the audio — returns the raw bytes + MIME type for saving/caching. Results are cached in-memory (LRU) keyed by text + format, so repeated identical prompts skip the network. Pass `options` to override the format per call. |
 
 **Streaming**
 
@@ -1277,6 +1363,54 @@ const stt = useDeepgramSpeechToText({
 });
 ```
 
+### Pause and resume a live stream
+
+```tsx
+const { startListening, pause, resume, isPaused } = useDeepgramSpeechToText({
+  trackState: true,
+  live: { punctuate: true, interimResults: true },
+});
+
+// Stop forwarding mic audio without dropping the socket. Deepgram is kept warm
+// with periodic KeepAlive frames, so resume() continues the same session.
+<Button
+  title={isPaused ? 'Resume' : 'Pause'}
+  onPress={() => (isPaused ? resume() : pause())}
+/>;
+```
+
+### Auto-reconnect a dropped live stream
+
+```tsx
+const stt = useDeepgramSpeechToText({
+  trackState: true,
+  reconnect: {
+    enabled: true,
+    maxRetries: 5, // give up after 5 attempts
+    initialDelayMs: 500, // 0.5s, doubling each retry
+    maxDelayMs: 10_000, // capped at 10s (+ jitter)
+  },
+  onReconnecting: (attempt) => console.log(`reconnecting… (#${attempt})`),
+  onReconnected: () => console.log('back online'),
+});
+```
+
+> The Voice Agent hook accepts the same `reconnect` options and re-sends its `Settings` payload automatically on every successful reconnect.
+
+### Point at a regional or self-hosted endpoint
+
+```ts
+import { configure } from 'react-native-deepgram';
+
+configure({
+  apiKey: process.env.EXPO_PUBLIC_DEEPGRAM_API_KEY!,
+  baseUrl: 'https://api.beta.deepgram.com/v1', // REST (include the /v1 segment)
+  baseWss: 'wss://api.beta.deepgram.com/v1', // live STT + streaming TTS
+});
+```
+
+> Flux v2 URLs are derived automatically by swapping the trailing `/v1` for `/v2`.
+
 ### Transcribe a picked file with summaries + topics
 
 ```tsx
@@ -1295,6 +1429,33 @@ const pick = async () => {
 };
 ```
 
+### Record the mic to a file while transcribing
+
+Persist the captured audio to a WAV file *and* get the live transcript at the
+same time. The `file://` URI arrives via `onRecordingComplete` (and, with
+`trackState`, as `recordingUri`) once `stopListening()` finishes writing.
+
+```tsx
+import { useDeepgramSpeechToText } from 'react-native-deepgram';
+
+const { startListening, stopListening, recordingUri } =
+  useDeepgramSpeechToText({
+    trackState: true,
+    recordToFile: { enabled: true }, // omit `path` to use an app-specific file
+    onTranscript: (text) => console.log(text),
+    onRecordingComplete: (uri) => {
+      console.log('saved recording at', uri); // file:///.../deepgram-….wav
+    },
+  });
+
+// start, talk, then:
+stopListening(); // onRecordingComplete fires with the finalized WAV
+```
+
+> Want a specific destination? Pass a `path` (with or without a `file://`
+> prefix) — e.g. from `expo-file-system`'s `documentDirectory`. Only
+> uncompressed `wav` is supported today.
+
 ### Voice Agent with a client-side function
 
 ```tsx
@@ -1359,6 +1520,9 @@ closeStreamGracefully(); // finish remaining audio then close
 
 ### One-shot HTTP TTS as MP3
 
+`synthesize` plays the audio through the device speaker **and** resolves with
+the buffer:
+
 ```tsx
 const { synthesize } = useDeepgramTextToSpeech({
   options: {
@@ -1372,7 +1536,36 @@ const { synthesize } = useDeepgramTextToSpeech({
 });
 
 const buffer = await synthesize('Hello from Deepgram.');
-// `buffer` is an ArrayBuffer of MP3 bytes — write to disk, upload, etc.
+// `buffer` is an ArrayBuffer of MP3 bytes — also played out loud.
+```
+
+### Save TTS to a file without playing it
+
+Use `synthesizeToBytes` when you only want the bytes (to cache, upload, or write
+to disk). Unlike `synthesize`, it **does not** play the audio, and identical
+prompts are served from an in-memory LRU cache:
+
+```tsx
+import { arrayBufferToBase64 } from 'react-native-deepgram';
+import * as FileSystem from 'expo-file-system';
+
+const { synthesizeToBytes } = useDeepgramTextToSpeech({
+  options: {
+    http: {
+      model: 'aura-2-asteria-en',
+      encoding: 'mp3',
+      bitRate: 48000,
+      container: 'none',
+    },
+  },
+});
+
+const { data, mimeType } = await synthesizeToBytes('Hello from Deepgram.');
+const uri = `${FileSystem.documentDirectory}greeting.mp3`;
+await FileSystem.writeAsStringAsync(uri, arrayBufferToBase64(data), {
+  encoding: FileSystem.EncodingType.Base64,
+});
+// `uri` now points to a saved MP3 file; `mimeType` is "audio/mpeg".
 ```
 
 ### Run text intelligence on a transcript
@@ -1399,6 +1592,29 @@ const newKey = await dg.keys.create('project_id', {
 console.log('temp token =', newKey.key);
 ```
 
+### Handle errors by typed code
+
+```tsx
+import { useDeepgramVoiceAgent, DeepgramError } from 'react-native-deepgram';
+
+useDeepgramVoiceAgent({
+  onError: (err) => {
+    const code = err instanceof DeepgramError ? err.code : 'unknown';
+    switch (code) {
+      case 'permission_denied':
+        return promptForMicAccess();
+      case 'playback_error':
+        return toast('Audio output failed — check the route and volume.');
+      default:
+        return console.error('Deepgram error', code, err);
+    }
+  },
+});
+```
+
+> `DeepgramError.code` is a `DeepgramErrorCode | 'unknown'`, and the underlying
+> failure is always kept on `DeepgramError.cause`.
+
 ---
 
 ## Troubleshooting
@@ -1458,6 +1674,10 @@ You ran `yarn prebuild` from `example/` but the workspace symlink wasn't created
 
 The repository includes an Expo-managed playground under `example/` that wires up every hook in this package. It is configured for a tight inner-dev loop: edits to the library's TypeScript sources are hot-reloaded into the running app — no rebuild required.
 
+<p align="center">
+  <img src="assets/example.webp" alt="react-native-deepgram example app showing the Voice Agent, Speech-to-Text, Text-to-Speech, Text Intelligence, and Management screens" width="100%" />
+</p>
+
 ### 1. Install workspace dependencies
 
 ```bash
@@ -1538,6 +1758,10 @@ If the app gets into a weird state, `yarn example:clean` wipes the generated nat
 - ✅ Hardware echo cancellation (iOS VPIO + Android `VOICE_COMMUNICATION`)
 - ✅ Background-audio support (iOS `UIBackgroundModes` + Android foreground service)
 - ✅ iOS 17+ permission API (`AVAudioApplication`) and Bluetooth option (`AllowBluetoothHFP`)
+- ✅ Microphone audio-level / metering events
+- ✅ Record the microphone to a WAV file while streaming
+- ✅ Audio output route control (speaker / earpiece / Bluetooth) with route-change events
+- ✅ Typed error codes (`DeepgramError` / `DeepgramErrorCode`)
 - 🚧 Detox E2E tests for the example app
 
 ---
diff --git a/android/src/main/java/com/deepgram/AudioFocusManager.kt b/android/src/main/java/com/deepgram/AudioFocusManager.kt
new file mode 100644
index 0000000..57931d8
--- /dev/null
+++ b/android/src/main/java/com/deepgram/AudioFocusManager.kt
@@ -0,0 +1,125 @@
+package com.deepgram
+
+import android.content.Context
+import android.media.AudioAttributes
+import android.media.AudioFocusRequest
+import android.media.AudioManager
+import android.os.Build
+import android.os.Handler
+import android.util.Log
+
+/**
+ * Owns system audio-focus arbitration for the Deepgram module.
+ *
+ * Focus is requested with `AUDIOFOCUS_GAIN_TRANSIENT` so other audio apps
+ * (Spotify, podcasts, navigation, etc.) pause/duck and then automatically
+ * resume when we abandon focus. Focus-change events are forwarded to the owner
+ * through [Listener] so it can stop/pause the right audio components.
+ */
+internal class AudioFocusManager(
+  private val context: Context,
+  private val handler: Handler,
+  private val listener: Listener,
+) {
+  /** Routes system focus transitions back to the owning module. */
+  interface Listener {
+    /** Permanent loss (another app took focus): tear everything down. */
+    fun onFocusLostPermanently()
+
+    /** Transient loss (e.g. incoming call): pause playback but keep state. */
+    fun onFocusLostTransiently()
+
+    /** Focus regained: resume playback if it was active. */
+    fun onFocusGained()
+  }
+
+  @Volatile
+  var hasFocus: Boolean = false
+    private set
+
+  private var audioManager: AudioManager? = null
+  private var audioFocusRequest: AudioFocusRequest? = null
+
+  private val focusChangeListener = AudioManager.OnAudioFocusChangeListener { focusChange ->
+    when (focusChange) {
+      AudioManager.AUDIOFOCUS_LOSS -> {
+        Log.i(TAG, "AUDIOFOCUS_LOSS — stopping Deepgram audio")
+        hasFocus = false
+        listener.onFocusLostPermanently()
+      }
+      AudioManager.AUDIOFOCUS_LOSS_TRANSIENT,
+      AudioManager.AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK -> {
+        Log.i(TAG, "AUDIOFOCUS_LOSS_TRANSIENT — pausing playback")
+        listener.onFocusLostTransiently()
+      }
+      AudioManager.AUDIOFOCUS_GAIN -> {
+        Log.i(TAG, "AUDIOFOCUS_GAIN — resuming playback if active")
+        hasFocus = true
+        listener.onFocusGained()
+      }
+    }
+  }
+
+  fun requestFocus(): Boolean {
+    if (hasFocus) return true
+    try {
+      val manager = context.getSystemService(Context.AUDIO_SERVICE) as? AudioManager
+        ?: return false
+      audioManager = manager
+
+      val result = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+        val request = AudioFocusRequest.Builder(AudioManager.AUDIOFOCUS_GAIN_TRANSIENT)
+          .setAudioAttributes(
+            AudioAttributes.Builder()
+              .setUsage(AudioAttributes.USAGE_VOICE_COMMUNICATION)
+              .setContentType(AudioAttributes.CONTENT_TYPE_SPEECH)
+              .build()
+          )
+          .setOnAudioFocusChangeListener(focusChangeListener, handler)
+          .setWillPauseWhenDucked(true)
+          .build()
+        audioFocusRequest = request
+        manager.requestAudioFocus(request)
+      } else {
+        @Suppress("DEPRECATION")
+        manager.requestAudioFocus(
+          focusChangeListener,
+          AudioManager.STREAM_VOICE_CALL,
+          AudioManager.AUDIOFOCUS_GAIN_TRANSIENT
+        )
+      }
+
+      hasFocus = result == AudioManager.AUDIOFOCUS_REQUEST_GRANTED
+      if (!hasFocus) {
+        Log.w(TAG, "Audio focus request not granted (result=$result)")
+      }
+      return hasFocus
+    } catch (e: Exception) {
+      Log.w(TAG, "requestAudioFocus error", e)
+      hasFocus = false
+      return false
+    }
+  }
+
+  fun abandonFocus() {
+    if (!hasFocus) return
+    try {
+      val manager = audioManager ?: return
+      if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+        audioFocusRequest?.let { manager.abandonAudioFocusRequest(it) }
+      } else {
+        @Suppress("DEPRECATION")
+        manager.abandonAudioFocus(focusChangeListener)
+      }
+    } catch (e: Exception) {
+      Log.w(TAG, "abandonAudioFocus error", e)
+    } finally {
+      hasFocus = false
+      audioFocusRequest = null
+    }
+  }
+
+  companion object {
+    private const val TAG = "DeepgramFocus"
+  }
+}
diff --git a/android/src/main/java/com/deepgram/AudioPlayer.kt b/android/src/main/java/com/deepgram/AudioPlayer.kt
new file mode 100644
index 0000000..4c489c6
--- /dev/null
+++ b/android/src/main/java/com/deepgram/AudioPlayer.kt
@@ -0,0 +1,512 @@
+package com.deepgram
+
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import android.content.IntentFilter
+import android.media.AudioAttributes
+import android.media.AudioFormat
+import android.media.AudioManager
+import android.media.AudioRecord
+import android.media.AudioTrack
+import android.os.Build
+import android.os.Handler
+import android.util.Base64
+import android.util.Log
+import java.util.Collections
+import java.util.concurrent.LinkedBlockingQueue
+import java.util.concurrent.TimeUnit
+import java.util.concurrent.atomic.AtomicBoolean
+import java.util.concurrent.atomic.AtomicInteger
+
+/**
+ * TTS audio output. Supports two modes:
+ *   - Streaming ([startPlayer] / [feedAudio]): base64 PCM chunks are queued and
+ *     drained on a dedicated thread through a `MODE_STREAM` AudioTrack.
+ *   - One-shot ([playAudioChunk]): a single buffer is played through a
+ *     `MODE_STATIC` AudioTrack and the caller is notified on completion.
+ *
+ * Audio focus is delegated to [focusManager]; foreground-service coordination
+ * is delegated to the owner via the two callbacks.
+ */
+internal class AudioPlayer(
+  private val context: Context,
+  private val mainHandler: Handler,
+  private val focusManager: AudioFocusManager,
+  private val onForegroundServiceRequest: () -> Unit,
+  private val onForegroundServiceRelease: () -> Unit,
+) {
+  // `streamingActive` drives the streaming playback loop and its teardown.
+  // The simple play/stop path is tracked independently via `simpleActive`, and
+  // one-shot playbacks via `oneShotPlaybacks`, so none of the three paths can
+  // tear down another's AudioTrack or shared focus/foreground-service state.
+  @Volatile
+  private var streamingActive: Boolean = false
+
+  // The simple "prepare for playback" path (mirrors iOS `startAudio`, which only
+  // activates the audio session). It owns no AudioTrack — it just keeps audio
+  // focus + the foreground service alive until `stopAudio` is called.
+  @Volatile
+  private var simpleActive: Boolean = false
+
+  private val oneShotPlaybacks =
+    Collections.synchronizedSet(mutableSetOf<OneShotPlayback>())
+
+  /** True while streaming, simple, or any one-shot playback is running. */
+  val isActive: Boolean
+    get() = streamingActive || simpleActive || oneShotPlaybacks.isNotEmpty()
+
+  private var playbackSampleRate: Int = DEFAULT_PLAYBACK_SAMPLE_RATE
+  private var currentOutputChannels: Int = 1
+
+  private var audioTrack: AudioTrack? = null
+  private val audioQueue = LinkedBlockingQueue<ByteArray>()
+  private var playbackThread: Thread? = null
+  private val playbackThreshold = 1024
+  private val queuedBytes = AtomicInteger(0)
+
+  // ACTION_AUDIO_BECOMING_NOISY — fires when wired headset is unplugged or A2DP
+  // disconnects. Without handling this, our AudioTrack would silently re-route
+  // to the loudspeaker and surprise the user. Standard Android best practice.
+  private var noisyReceiverRegistered = false
+  private val becomingNoisyReceiver = object : BroadcastReceiver() {
+    override fun onReceive(context: Context?, intent: Intent?) {
+      if (intent?.action == AudioManager.ACTION_AUDIO_BECOMING_NOISY) {
+        Log.i(TAG, "AUDIO_BECOMING_NOISY — pausing playback")
+        try { audioTrack?.pause() } catch (_: Exception) {}
+      }
+    }
+  }
+
+  // The streaming AudioTrack is sized to at least 4x the microphone min-buffer.
+  // Preserved verbatim from the original single-class implementation to keep
+  // latency / under-run characteristics identical across releases.
+  private val streamingBufferFloor: Int
+    get() {
+      val recMin = AudioRecord.getMinBufferSize(
+        RECORD_SAMPLE_RATE, AudioFormat.CHANNEL_IN_MONO, AUDIO_FORMAT
+      )
+      val base = if (recMin > 0) recMin else maxOf((RECORD_SAMPLE_RATE / 5) * 2, 4096)
+      return base * 4
+    }
+
+  private fun outputChannelMask(): Int {
+    return if (currentOutputChannels >= 2) {
+      AudioFormat.CHANNEL_OUT_STEREO
+    } else {
+      AudioFormat.CHANNEL_OUT_MONO
+    }
+  }
+
+  private fun minTrackBufferSize(channelMask: Int): Int {
+    val min = AudioTrack.getMinBufferSize(playbackSampleRate, channelMask, AUDIO_FORMAT)
+    if (min > 0) return min
+
+    val bytesPerFrame = if (currentOutputChannels >= 2) 4 else 2
+    val fallback = maxOf((playbackSampleRate / 5) * bytesPerFrame, 4096)
+    Log.w(TAG, "Invalid AudioTrack min buffer ($min), using fallback=$fallback")
+    return fallback
+  }
+
+  private fun ensureAudioTrack() {
+    if (audioTrack != null) return
+
+    val channelMask = outputChannelMask()
+    val minBuf = minTrackBufferSize(channelMask)
+
+    audioTrack = AudioTrack.Builder()
+      .setAudioAttributes(
+        AudioAttributes.Builder()
+          .setUsage(AudioAttributes.USAGE_VOICE_COMMUNICATION)
+          .setContentType(AudioAttributes.CONTENT_TYPE_SPEECH)
+          .build()
+      )
+      .setAudioFormat(
+        AudioFormat.Builder()
+          .setEncoding(AUDIO_FORMAT)
+          .setSampleRate(playbackSampleRate)
+          .setChannelMask(channelMask)
+          .build()
+      )
+      .setBufferSizeInBytes(maxOf(minBuf, streamingBufferFloor))
+      .setTransferMode(AudioTrack.MODE_STREAM)
+      .build()
+  }
+
+  // -------------------------------------------------------------------
+  // Simple play/stop (kept for API compatibility)
+  // -------------------------------------------------------------------
+
+  fun startAudio() {
+    // Mirror iOS `startAudio`: only prepare the session for playback (request
+    // focus + keep-alive service). Do NOT create/play the streaming AudioTrack
+    // here — the streaming player owns that track, and sharing it would let a
+    // later `stopAudio`/`startPlayer` tear down the other path's playback.
+    focusManager.requestFocus()
+    simpleActive = true
+    onForegroundServiceRequest()
+  }
+
+  fun stopAudio() {
+    // Mirror iOS `stopAudio` -> `stopPlayer`: end the simple session and stop
+    // any streaming playback, then release shared resources once nothing is
+    // left active.
+    simpleActive = false
+    stopStreamingPlayback(throwOnError = true)
+  }
+
+  private fun releaseStreamingTrack(throwOnError: Boolean) {
+    try {
+      audioTrack?.stop()
+    } catch (e: Exception) {
+      Log.w(TAG, "releaseStreamingTrack: error stopping AudioTrack", e)
+      if (throwOnError) throw e
+    }
+
+    try {
+      audioTrack?.release()
+    } catch (e: Exception) {
+      Log.w(TAG, "releaseStreamingTrack: error releasing AudioTrack", e)
+      if (throwOnError) throw e
+    }
+
+    audioTrack = null
+    streamingActive = false
+    releaseSharedResourcesIfIdle()
+  }
+
+  /**
+   * Abandon audio focus and release the foreground service only when none of
+   * the streaming, simple, or one-shot playback paths remain active, so a
+   * finishing path cannot tear down shared resources still in use by another.
+   */
+  private fun releaseSharedResourcesIfIdle() {
+    if (isActive) return
+    focusManager.abandonFocus()
+    onForegroundServiceRelease()
+  }
+
+  // -------------------------------------------------------------------
+  // Streaming player. Uses a proper queue instead of O(n²) concatenation.
+  // -------------------------------------------------------------------
+
+  fun startPlayer(sampleRate: Int, channels: Int) {
+    stopStreamingPlayback()
+    playbackSampleRate = if (sampleRate > 0) sampleRate else DEFAULT_PLAYBACK_SAMPLE_RATE
+    currentOutputChannels = if (channels >= 2) 2 else 1
+    audioQueue.clear()
+    queuedBytes.set(0)
+    streamingActive = false
+  }
+
+  fun setAudioConfig(sampleRate: Int, channels: Int) {
+    startPlayer(sampleRate, channels)
+  }
+
+  fun feedAudio(base64Audio: String) {
+    try {
+      val audioData = Base64.decode(base64Audio, Base64.DEFAULT)
+      if (audioData.isEmpty()) return
+
+      // Bound the queue to prevent unbounded memory growth if JS is producing
+      // audio faster than the device can play it. Drop the oldest chunk first
+      // (so we always favor newer audio) when at the limit.
+      while (queuedBytes.get() + audioData.size > MAX_QUEUED_PLAYBACK_BYTES) {
+        val dropped = audioQueue.poll() ?: break
+        queuedBytes.addAndGet(-dropped.size)
+        Log.w(TAG, "feedAudio: dropping ${dropped.size} bytes — playback queue full")
+      }
+
+      audioQueue.offer(audioData)
+      queuedBytes.addAndGet(audioData.size)
+
+      // Start playback when we have enough buffered data
+      if (!streamingActive && queuedBytes.get() >= playbackThreshold) {
+        startStreamingPlayback()
+      }
+    } catch (e: Exception) {
+      Log.e(TAG, "feedAudio error", e)
+    }
+  }
+
+  fun interruptAudio() {
+    try {
+      stopStreamingPlayback(throwOnError = false)
+    } catch (e: Exception) {
+      Log.w(TAG, "interruptAudio error", e)
+    }
+  }
+
+  private fun startStreamingPlayback() {
+    if (streamingActive) return
+
+    streamingActive = true
+    registerNoisyReceiver()
+    playbackThread = Thread({
+      try {
+        android.os.Process.setThreadPriority(android.os.Process.THREAD_PRIORITY_URGENT_AUDIO)
+        focusManager.requestFocus()
+        onForegroundServiceRequest()
+        ensureAudioTrack()
+        audioTrack?.play()
+
+        while (streamingActive) {
+          // Block until data is available (up to 100ms), avoids busy-wait
+          val chunk = audioQueue.poll(100, TimeUnit.MILLISECONDS)
+            ?: continue
+
+          queuedBytes.addAndGet(-chunk.size)
+          val written = audioTrack?.write(chunk, 0, chunk.size) ?: 0
+          if (written < 0) {
+            Log.e(TAG, "AudioTrack write error: $written")
+            break
+          }
+        }
+      } catch (e: InterruptedException) {
+        // Normal shutdown
+      } catch (e: Exception) {
+        Log.e(TAG, "Streaming playback error", e)
+      } finally {
+        streamingActive = false
+        releaseSharedResourcesIfIdle()
+      }
+    }, "Deepgram-Playback")
+
+    playbackThread?.start()
+  }
+
+  fun stopStreamingPlayback(throwOnError: Boolean = true) {
+    streamingActive = false
+    playbackThread?.let { thread ->
+      thread.interrupt()
+      try {
+        thread.join(500)
+      } catch (_: InterruptedException) {
+        Thread.currentThread().interrupt()
+      }
+    }
+    playbackThread = null
+
+    try {
+      releaseStreamingTrack(throwOnError)
+    } catch (e: Exception) {
+      if (throwOnError) throw e else Log.w(TAG, "stopStreamingPlayback: error stopping audio", e)
+    } finally {
+      audioQueue.clear()
+      queuedBytes.set(0)
+      unregisterNoisyReceiver()
+    }
+  }
+
+  // -------------------------------------------------------------------
+  // Focus transitions (driven by the owning module)
+  // -------------------------------------------------------------------
+
+  /** Pause output on a transient focus loss without discarding state. */
+  fun pauseForFocusLoss() {
+    try { audioTrack?.pause() } catch (_: Exception) {}
+  }
+
+  /** Resume output after regaining focus, if playback is still active. */
+  fun resumeForFocusGain() {
+    if (streamingActive) {
+      try { audioTrack?.play() } catch (_: Exception) {}
+    }
+  }
+
+  // -------------------------------------------------------------------
+  // One-shot playback (for HTTP synthesis)
+  // -------------------------------------------------------------------
+
+  fun playAudioChunk(
+    base64: String,
+    onSuccess: () -> Unit,
+    onError: (code: String, message: String?) -> Unit,
+  ) {
+    val audioData = try {
+      Base64.decode(base64, Base64.DEFAULT)
+    } catch (e: Exception) {
+      Log.e(TAG, "playAudioChunk decode error", e)
+      onError("invalid_data", "Failed to decode audio data")
+      return
+    }
+
+    if (audioData.isEmpty()) {
+      onError("invalid_data", "Failed to decode audio data")
+      return
+    }
+
+    // Reject malformed / oversized PCM before building the AudioTrack. A
+    // sub-frame buffer would make frameCount (and notificationMarkerPosition)
+    // 0, so onMarkerReached would never fire — the promise would hang forever
+    // while leaking audio focus + the foreground service. The upper bound
+    // mirrors the streaming queue cap.
+    val bytesPerFrame = if (currentOutputChannels >= 2) 4 else 2 // PCM16 mono/stereo
+    if (audioData.size < bytesPerFrame || audioData.size % bytesPerFrame != 0) {
+      onError("invalid_data", "Audio data must contain whole PCM16 frames")
+      return
+    }
+    if (audioData.size > MAX_QUEUED_PLAYBACK_BYTES) {
+      onError("invalid_data", "Audio data exceeds the maximum one-shot size")
+      return
+    }
+
+    focusManager.requestFocus()
+    onForegroundServiceRequest()
+
+    var playback: OneShotPlayback? = null
+    try {
+      val channelMask = outputChannelMask()
+      val minBuf = minTrackBufferSize(channelMask)
+
+      val tempAudioTrack = AudioTrack.Builder()
+        .setAudioAttributes(
+          AudioAttributes.Builder()
+            .setUsage(AudioAttributes.USAGE_VOICE_COMMUNICATION)
+            .setContentType(AudioAttributes.CONTENT_TYPE_SPEECH)
+            .build()
+        )
+        .setAudioFormat(
+          AudioFormat.Builder()
+            .setEncoding(AUDIO_FORMAT)
+            .setSampleRate(playbackSampleRate)
+            .setChannelMask(channelMask)
+            .build()
+        )
+        .setBufferSizeInBytes(maxOf(minBuf, audioData.size))
+        .setTransferMode(AudioTrack.MODE_STATIC)
+        .build()
+
+      tempAudioTrack.write(audioData, 0, audioData.size)
+
+      // Use a notification marker to know when playback finishes (instead of
+      // polling with Thread.sleep). Track the one-shot so it contributes to
+      // isActive and can be torn down on focus loss / invalidate.
+      val frameCount = audioData.size / bytesPerFrame
+      tempAudioTrack.notificationMarkerPosition = frameCount
+
+      val created = OneShotPlayback(tempAudioTrack, onSuccess, onError)
+      playback = created
+      oneShotPlaybacks.add(created)
+
+      // minSdk is 24, the Handler-aware overload is always available.
+      tempAudioTrack.setPlaybackPositionUpdateListener(
+        object : AudioTrack.OnPlaybackPositionUpdateListener {
+          override fun onMarkerReached(track: AudioTrack?) = created.complete()
+          override fun onPeriodicNotification(track: AudioTrack?) {}
+        },
+        mainHandler,
+      )
+
+      tempAudioTrack.play()
+    } catch (e: Exception) {
+      Log.e(TAG, "playAudioChunk error", e)
+      val created = playback
+      if (created != null) {
+        created.fail("playback_error", e.message)
+      } else {
+        releaseSharedResourcesIfIdle()
+        onError("playback_error", e.message)
+      }
+    }
+  }
+
+  /**
+   * A single MODE_STATIC one-shot playback. Guarantees the JS promise settles
+   * exactly once (via [complete] or [fail]), tears the AudioTrack down, and
+   * releases the shared focus / foreground service only when nothing else is
+   * still playing.
+   */
+  private inner class OneShotPlayback(
+    private val track: AudioTrack,
+    private val onSuccess: () -> Unit,
+    private val onError: (code: String, message: String?) -> Unit,
+  ) {
+    private val settled = AtomicBoolean(false)
+
+    fun complete() {
+      if (!settled.compareAndSet(false, true)) return
+      teardown()
+      onSuccess()
+    }
+
+    fun fail(code: String, message: String?) {
+      if (!settled.compareAndSet(false, true)) return
+      teardown()
+      onError(code, message)
+    }
+
+    private fun teardown() {
+      try {
+        track.stop()
+        track.release()
+      } catch (e: Exception) {
+        Log.w(TAG, "playAudioChunk cleanup error", e)
+      }
+      oneShotPlaybacks.remove(this)
+      releaseSharedResourcesIfIdle()
+    }
+  }
+
+  /** Stop every in-flight one-shot playback, rejecting their pending promises. */
+  fun stopOneShotPlayback() {
+    val pending = synchronized(oneShotPlaybacks) { oneShotPlaybacks.toList() }
+    pending.forEach { it.fail("playback_error", "Playback interrupted") }
+  }
+
+  /** Tear down all playback resources (called from the module's invalidate). */
+  fun release() {
+    simpleActive = false
+    try {
+      stopStreamingPlayback(throwOnError = false)
+    } catch (e: Exception) {
+      Log.w(TAG, "Error stopping playback on release", e)
+    }
+    stopOneShotPlayback()
+    unregisterNoisyReceiver()
+  }
+
+  private fun registerNoisyReceiver() {
+    if (noisyReceiverRegistered) return
+    try {
+      val filter = IntentFilter(AudioManager.ACTION_AUDIO_BECOMING_NOISY)
+      if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
+        context.registerReceiver(
+          becomingNoisyReceiver,
+          filter,
+          Context.RECEIVER_NOT_EXPORTED
+        )
+      } else {
+        @Suppress("UnspecifiedRegisterReceiverFlag")
+        context.registerReceiver(becomingNoisyReceiver, filter)
+      }
+      noisyReceiverRegistered = true
+    } catch (e: Exception) {
+      Log.w(TAG, "registerNoisyReceiver failed", e)
+    }
+  }
+
+  private fun unregisterNoisyReceiver() {
+    if (!noisyReceiverRegistered) return
+    try {
+      context.unregisterReceiver(becomingNoisyReceiver)
+    } catch (e: Exception) {
+      Log.w(TAG, "unregisterNoisyReceiver failed", e)
+    } finally {
+      noisyReceiverRegistered = false
+    }
+  }
+
+  companion object {
+    private const val TAG = "DeepgramPlayer"
+
+    private const val DEFAULT_PLAYBACK_SAMPLE_RATE = 16000
+    private const val RECORD_SAMPLE_RATE = 16000
+    private const val AUDIO_FORMAT = AudioFormat.ENCODING_PCM_16BIT
+
+    // Cap the streaming playback queue to prevent unbounded memory growth when
+    // JS feeds audio faster than the device can play it. ~5 s of 24 kHz PCM16
+    // mono is roughly 240 KB — we allow a little more headroom.
+    private const val MAX_QUEUED_PLAYBACK_BYTES = 1_500_000
+  }
+}
diff --git a/android/src/main/java/com/deepgram/AudioRecorder.kt b/android/src/main/java/com/deepgram/AudioRecorder.kt
new file mode 100644
index 0000000..f16932a
--- /dev/null
+++ b/android/src/main/java/com/deepgram/AudioRecorder.kt
@@ -0,0 +1,499 @@
+package com.deepgram
+
+import android.content.Context
+import android.media.AudioFormat
+import android.media.AudioManager
+import android.media.AudioRecord
+import android.media.MediaRecorder
+import android.media.audiofx.AcousticEchoCanceler
+import android.media.audiofx.AutomaticGainControl
+import android.media.audiofx.NoiseSuppressor
+import android.net.Uri
+import android.util.Log
+import java.io.File
+import java.io.RandomAccessFile
+import java.nio.ByteBuffer
+import java.nio.ByteOrder
+
+/**
+ * Microphone capture. Records 16 kHz PCM16 mono and streams the raw bytes back
+ * to the owner via [onAudioChunk]; the JS side downsamples to whatever Deepgram
+ * is configured for.
+ *
+ * Two capture profiles are supported:
+ *   - STT-only (`enableVoiceProcessing = false`): `VOICE_RECOGNITION`, which
+ *     gives the rawest possible signal (platform AEC/NS/AGC disabled).
+ *   - Voice Agent / duplex (`enableVoiceProcessing = true`): `VOICE_COMMUNICATION`
+ *     plus `MODE_IN_COMMUNICATION` so the platform's telephony-grade AEC engages
+ *     against the active playback signal as its reference.
+ */
+internal class AudioRecorder(
+  private val context: Context,
+  private val onAudioChunk: (ByteArray, Int) -> Unit,
+  private val onForegroundServiceRequest: () -> Unit,
+  private val onForegroundServiceRelease: () -> Unit,
+  private val onAudioLevel: (Double) -> Unit = {},
+) {
+  /** Thrown when AudioRecord fails to initialize (mapped to "init_failed"). */
+  class InitializationException(message: String) : Exception(message)
+
+  @Volatile
+  var isActive: Boolean = false
+    private set
+
+  @Volatile
+  private var audioRecord: AudioRecord? = null
+  private var recordingThread: Thread? = null
+
+  // Microphone metering (audio-level events). Purely additive — when
+  // [meteringEnabled] is true the recording loop computes a normalized RMS
+  // amplitude (0..1) over the same PCM that feeds transcription and forwards it
+  // via [onAudioLevel], throttled to [meteringIntervalMs].
+  @Volatile
+  private var meteringEnabled: Boolean = false
+
+  @Volatile
+  private var meteringIntervalMs: Long = 100L
+  private var lastMeterEmit: Long = 0L
+
+  // Record-to-file. When [start] is given a destination path the recording loop
+  // tees the same PCM it streams to JS into a WAV file; the RIFF/`data` sizes
+  // are patched into the header on stop. Writes happen on the recording thread
+  // (single producer) and finalization runs after it joins, so no lock needed.
+  @Volatile
+  private var fileOutput: RandomAccessFile? = null
+  private var fileDataBytes: Long = 0L
+  private var recordFilePath: String? = null
+
+  /** `file://` URI of the most recently completed record-to-file session. */
+  @Volatile
+  var lastRecordingUri: String? = null
+    private set
+
+  private var acousticEchoCanceler: AcousticEchoCanceler? = null
+  private var noiseSuppressor: NoiseSuppressor? = null
+  private var automaticGainControl: AutomaticGainControl? = null
+
+  // When `enableVoiceProcessing = true`, we set the system into
+  // MODE_IN_COMMUNICATION so the platform engages telephony-grade AEC. We
+  // remember the prior mode so we can restore it on stop and not strand the
+  // device in voice-call routing.
+  private var voiceProcessingActive = false
+  private var savedAudioMode: Int = AudioManager.MODE_NORMAL
+  private var audioManager: AudioManager? = null
+
+  private val minRecordBufferSize: Int
+    get() {
+      val min = AudioRecord.getMinBufferSize(RECORD_SAMPLE_RATE, CHANNEL_CONFIG, AUDIO_FORMAT)
+      if (min > 0) return min
+
+      val fallback = maxOf((RECORD_SAMPLE_RATE / 5) * 2, 4096)
+      Log.w(TAG, "Invalid AudioRecord min buffer ($min), using fallback=$fallback")
+      return fallback
+    }
+
+  private val bufferSize: Int
+    get() = minRecordBufferSize * 4
+
+  /**
+   * Start capturing. On failure the recorder is left fully cleaned up and the
+   * exception is propagated: [InitializationException] for a failed
+   * `AudioRecord` init, `SecurityException` for a missing permission, or the
+   * original exception otherwise.
+   */
+  fun start(enableVoiceProcessing: Boolean, recordToFilePath: String? = null) {
+    lastRecordingUri = null
+
+    // Voice Agent / duplex usage: route capture through the telephony stack so
+    // the platform's hardware AEC engages with the active playback signal as
+    // its reference. VOICE_RECOGNITION explicitly disables AEC/NS/AGC and is
+    // therefore the *wrong* source for full-duplex — it's only correct for
+    // one-way ASR where you want the rawest possible signal.
+    val audioSource = if (enableVoiceProcessing) {
+      MediaRecorder.AudioSource.VOICE_COMMUNICATION
+    } else {
+      MediaRecorder.AudioSource.VOICE_RECOGNITION
+    }
+
+    if (enableVoiceProcessing) {
+      applyVoiceCommunicationMode()
+    }
+
+    try {
+      val recorder = AudioRecord.Builder()
+        .setAudioSource(audioSource)
+        .setAudioFormat(
+          AudioFormat.Builder()
+            .setEncoding(AUDIO_FORMAT)
+            .setSampleRate(RECORD_SAMPLE_RATE)
+            .setChannelMask(CHANNEL_CONFIG)
+            .build()
+        )
+        .setBufferSizeInBytes(bufferSize)
+        .build()
+      audioRecord = recorder
+
+      if (recorder.state != AudioRecord.STATE_INITIALIZED) {
+        recorder.release()
+        audioRecord = null
+        releaseAudioEffects()
+        restoreAudioModeIfNeeded()
+        throw InitializationException("AudioRecord initialization failed")
+      }
+
+      // Open the WAV target before we start capturing so a file-system failure
+      // aborts the whole start (mapped to "start_error") instead of silently
+      // dropping the recording.
+      if (recordToFilePath != null) {
+        openRecordingFile(recordToFilePath)
+      }
+
+      enableAudioEffects(recorder)
+      recorder.startRecording()
+      isActive = true
+      onForegroundServiceRequest()
+
+      startRecordingThread()
+    } catch (e: SecurityException) {
+      Log.e(TAG, "startRecording security error", e)
+      audioRecord?.release()
+      audioRecord = null
+      releaseAudioEffects()
+      restoreAudioModeIfNeeded()
+      discardRecordingFile()
+      throw e
+    } catch (e: InitializationException) {
+      throw e
+    } catch (e: Exception) {
+      Log.e(TAG, "startRecording error", e)
+      audioRecord?.release()
+      audioRecord = null
+      releaseAudioEffects()
+      restoreAudioModeIfNeeded()
+      discardRecordingFile()
+      throw e
+    }
+  }
+
+  fun stop(throwOnError: Boolean = true) {
+    isActive = false
+    recordingThread?.let { thread ->
+      thread.interrupt()
+      try {
+        thread.join(500)
+      } catch (_: InterruptedException) {
+        Thread.currentThread().interrupt()
+      }
+    }
+    recordingThread = null
+
+    // The recording thread has joined, so no writer can race the finalize.
+    val finalizedUri = finalizeRecordingFile()
+    if (finalizedUri != null) {
+      lastRecordingUri = finalizedUri
+    }
+
+    try {
+      audioRecord?.stop()
+    } catch (e: Exception) {
+      Log.w(TAG, "stop: error stopping AudioRecord", e)
+      if (throwOnError) throw e
+    }
+
+    try {
+      audioRecord?.release()
+    } catch (e: Exception) {
+      Log.w(TAG, "stop: error releasing AudioRecord", e)
+      if (throwOnError) throw e
+    }
+
+    audioRecord = null
+    releaseAudioEffects()
+    restoreAudioModeIfNeeded()
+    onForegroundServiceRelease()
+  }
+
+  /**
+   * Enable / disable microphone audio-level metering. When enabled the
+   * recording loop emits a normalized RMS amplitude (0..1) via [onAudioLevel]
+   * at most once per [intervalMs] (clamped to a sane minimum). Safe to call
+   * before or during recording.
+   */
+  fun setMetering(enabled: Boolean, intervalMs: Long) {
+    meteringEnabled = enabled
+    meteringIntervalMs = if (intervalMs > 0) intervalMs else 100L
+    lastMeterEmit = 0L
+  }
+
+  private fun applyVoiceCommunicationMode() {
+    if (voiceProcessingActive) return
+    try {
+      val manager = audioManager
+        ?: (context.getSystemService(Context.AUDIO_SERVICE) as? AudioManager)
+      if (manager == null) {
+        Log.w(TAG, "applyVoiceCommunicationMode: AudioManager unavailable")
+        return
+      }
+      audioManager = manager
+      savedAudioMode = manager.mode
+      manager.mode = AudioManager.MODE_IN_COMMUNICATION
+      voiceProcessingActive = true
+      Log.i(TAG, "Switched audio mode to IN_COMMUNICATION (was $savedAudioMode) for AEC")
+    } catch (e: Exception) {
+      Log.w(TAG, "applyVoiceCommunicationMode failed", e)
+    }
+  }
+
+  private fun restoreAudioModeIfNeeded() {
+    if (!voiceProcessingActive) return
+    try {
+      val manager = audioManager
+        ?: (context.getSystemService(Context.AUDIO_SERVICE) as? AudioManager)
+      manager?.mode = savedAudioMode
+      Log.i(TAG, "Restored audio mode to $savedAudioMode")
+    } catch (e: Exception) {
+      Log.w(TAG, "restoreAudioModeIfNeeded failed", e)
+    } finally {
+      voiceProcessingActive = false
+    }
+  }
+
+  private fun enableAudioEffects(recorder: AudioRecord) {
+    val sessionId = recorder.audioSessionId
+    if (sessionId == AudioRecord.ERROR || sessionId == AudioRecord.ERROR_BAD_VALUE) {
+      return
+    }
+
+    releaseAudioEffects()
+
+    if (AcousticEchoCanceler.isAvailable()) {
+      try {
+        acousticEchoCanceler = AcousticEchoCanceler.create(sessionId)?.apply {
+          enabled = true
+        }
+      } catch (e: Exception) {
+        Log.w(TAG, "Unable to enable AcousticEchoCanceler", e)
+      }
+    }
+
+    if (NoiseSuppressor.isAvailable()) {
+      try {
+        noiseSuppressor = NoiseSuppressor.create(sessionId)?.apply {
+          enabled = true
+        }
+      } catch (e: Exception) {
+        Log.w(TAG, "Unable to enable NoiseSuppressor", e)
+      }
+    }
+
+    if (AutomaticGainControl.isAvailable()) {
+      try {
+        automaticGainControl = AutomaticGainControl.create(sessionId)?.apply {
+          enabled = true
+        }
+      } catch (e: Exception) {
+        Log.w(TAG, "Unable to enable AutomaticGainControl", e)
+      }
+    }
+  }
+
+  private fun releaseAudioEffects() {
+    try {
+      acousticEchoCanceler?.release()
+    } catch (e: Exception) {
+      Log.w(TAG, "Error releasing AcousticEchoCanceler", e)
+    } finally {
+      acousticEchoCanceler = null
+    }
+
+    try {
+      noiseSuppressor?.release()
+    } catch (e: Exception) {
+      Log.w(TAG, "Error releasing NoiseSuppressor", e)
+    } finally {
+      noiseSuppressor = null
+    }
+
+    try {
+      automaticGainControl?.release()
+    } catch (e: Exception) {
+      Log.w(TAG, "Error releasing AutomaticGainControl", e)
+    } finally {
+      automaticGainControl = null
+    }
+  }
+
+  private fun startRecordingThread() {
+    recordingThread = Thread({
+      try {
+        android.os.Process.setThreadPriority(android.os.Process.THREAD_PRIORITY_URGENT_AUDIO)
+        val buffer = ByteArray(bufferSize)
+        while (isActive) {
+          val recorder = audioRecord ?: break
+          val read = recorder.read(buffer, 0, buffer.size)
+          if (read > 0) {
+            onAudioChunk(buffer, read)
+            writeRecordingFile(buffer, read)
+            emitAudioLevelIfNeeded(buffer, read)
+          } else if (read < 0) {
+            // ERROR_INVALID_OPERATION / ERROR_BAD_VALUE / ERROR_DEAD_OBJECT —
+            // bail rather than spin in a tight loop.
+            Log.w(TAG, "AudioRecord.read returned $read — stopping thread")
+            break
+          }
+        }
+      } catch (e: Exception) {
+        Log.e(TAG, "recording thread error", e)
+      }
+    }, "Deepgram-Recording")
+    recordingThread?.start()
+  }
+
+  /**
+   * Compute a normalized RMS amplitude (0..1) over a PCM16 little-endian buffer
+   * and forward it via [onAudioLevel], throttled to [meteringIntervalMs]. No-op
+   * unless metering is enabled.
+   */
+  private fun emitAudioLevelIfNeeded(buffer: ByteArray, length: Int) {
+    if (!meteringEnabled || length < 2) return
+
+    val now = System.currentTimeMillis()
+    if (lastMeterEmit != 0L && now - lastMeterEmit < meteringIntervalMs) return
+    lastMeterEmit = now
+
+    var sumSquares = 0.0
+    var sampleCount = 0
+    var i = 0
+    while (i + 1 < length) {
+      val lo = buffer[i].toInt() and 0xFF
+      val hi = buffer[i + 1].toInt() // signed high byte → sign-extends sample
+      val sample = (hi shl 8) or lo
+      val norm = sample / 32768.0
+      sumSquares += norm * norm
+      sampleCount++
+      i += 2
+    }
+    if (sampleCount == 0) return
+
+    val rms = Math.sqrt(sumSquares / sampleCount)
+    onAudioLevel(if (rms > 1.0) 1.0 else rms)
+  }
+
+  /**
+   * Open [path] (with or without a `file://` scheme) and write a placeholder
+   * WAV header. Throws if the file cannot be created so [start] can surface the
+   * failure as "start_error".
+   */
+  private fun openRecordingFile(path: String) {
+    val clean = if (path.startsWith("file://")) {
+      Uri.parse(path).path ?: path.removePrefix("file://")
+    } else {
+      path
+    }
+    val file = File(clean)
+    file.parentFile?.let { if (!it.exists()) it.mkdirs() }
+
+    val raf = RandomAccessFile(file, "rw")
+    try {
+      raf.setLength(0)
+      raf.write(buildWavHeader(0))
+    } catch (e: Exception) {
+      try { raf.close() } catch (_: Exception) {}
+      throw e
+    }
+    fileOutput = raf
+    fileDataBytes = 0L
+    recordFilePath = file.absolutePath
+    Log.i(TAG, "record-to-file: writing to ${file.absolutePath}")
+  }
+
+  /** Append captured PCM to the open WAV file. Stops teeing on a write error. */
+  private fun writeRecordingFile(buffer: ByteArray, length: Int) {
+    val out = fileOutput ?: return
+    try {
+      out.write(buffer, 0, length)
+      fileDataBytes += length
+    } catch (e: Exception) {
+      Log.w(TAG, "record-to-file write failed", e)
+      discardRecordingFile()
+    }
+  }
+
+  /**
+   * Patch the RIFF/`data` sizes into the header, close the file and return its
+   * `file://` URI. Returns null when no record-to-file session was active.
+   */
+  private fun finalizeRecordingFile(): String? {
+    val out = fileOutput ?: return null
+    val path = recordFilePath
+    val dataBytes = fileDataBytes
+    fileOutput = null
+    fileDataBytes = 0L
+    recordFilePath = null
+
+    try {
+      out.seek(4)
+      out.write(intToLittleEndian((36 + dataBytes).toInt()))
+      out.seek(40)
+      out.write(intToLittleEndian(dataBytes.toInt()))
+      out.close()
+    } catch (e: Exception) {
+      Log.w(TAG, "record-to-file finalize failed", e)
+      try { out.close() } catch (_: Exception) {}
+    }
+
+    return path?.let { Uri.fromFile(File(it)).toString() }
+  }
+
+  /** Close and delete any partially written file without producing a URI. */
+  private fun discardRecordingFile() {
+    val out = fileOutput
+    val path = recordFilePath
+    fileOutput = null
+    fileDataBytes = 0L
+    recordFilePath = null
+
+    if (out != null) {
+      try { out.close() } catch (_: Exception) {}
+    }
+    if (path != null) {
+      try { File(path).delete() } catch (_: Exception) {}
+    }
+  }
+
+  private fun buildWavHeader(dataBytes: Int): ByteArray {
+    val channels = 1
+    val bitsPerSample = 16
+    val byteRate = RECORD_SAMPLE_RATE * channels * bitsPerSample / 8
+    val blockAlign = channels * bitsPerSample / 8
+
+    return ByteBuffer.allocate(44).order(ByteOrder.LITTLE_ENDIAN).apply {
+      put("RIFF".toByteArray(Charsets.US_ASCII))
+      putInt(36 + dataBytes)
+      put("WAVE".toByteArray(Charsets.US_ASCII))
+      put("fmt ".toByteArray(Charsets.US_ASCII))
+      putInt(16) // PCM fmt chunk size
+      putShort(1) // PCM
+      putShort(channels.toShort())
+      putInt(RECORD_SAMPLE_RATE)
+      putInt(byteRate)
+      putShort(blockAlign.toShort())
+      putShort(bitsPerSample.toShort())
+      put("data".toByteArray(Charsets.US_ASCII))
+      putInt(dataBytes)
+    }.array()
+  }
+
+  private fun intToLittleEndian(value: Int): ByteArray =
+    ByteBuffer.allocate(4).order(ByteOrder.LITTLE_ENDIAN).putInt(value).array()
+
+  companion object {
+    private const val TAG = "DeepgramRecorder"
+
+    // Recording is locked to 16 kHz PCM16 mono — exposed so the module can tag
+    // the `AudioChunk` event it emits to JS with the matching sample rate.
+    const val RECORD_SAMPLE_RATE = 16000
+    private const val CHANNEL_CONFIG = AudioFormat.CHANNEL_IN_MONO
+    private const val AUDIO_FORMAT = AudioFormat.ENCODING_PCM_16BIT
+  }
+}
diff --git a/android/src/main/java/com/deepgram/DeepgramAudioService.kt b/android/src/main/java/com/deepgram/DeepgramAudioService.kt
index c2d0170..ffeeec7 100644
--- a/android/src/main/java/com/deepgram/DeepgramAudioService.kt
+++ b/android/src/main/java/com/deepgram/DeepgramAudioService.kt
@@ -6,17 +6,22 @@ import android.app.NotificationManager
 import android.app.Service
 import android.content.Context
 import android.content.Intent
+import android.content.pm.ServiceInfo
 import android.os.Build
 import android.os.IBinder
+import android.util.Log
 
 class DeepgramAudioService : Service() {
   companion object {
+    private const val TAG = "DeepgramAudioService"
     private const val CHANNEL_ID = "deepgram_audio_channel"
     private const val CHANNEL_NAME = "Deepgram Audio"
     private const val NOTIFICATION_ID = 43123
+    private const val EXTRA_WITH_MICROPHONE = "with_microphone"
 
-    fun start(context: Context) {
+    fun start(context: Context, withMicrophone: Boolean) {
       val intent = Intent(context, DeepgramAudioService::class.java)
+      intent.putExtra(EXTRA_WITH_MICROPHONE, withMicrophone)
       if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
         context.startForegroundService(intent)
       } else {
@@ -38,16 +43,28 @@ class DeepgramAudioService : Service() {
   }
 
   override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
+    val withMicrophone = intent?.getBooleanExtra(EXTRA_WITH_MICROPHONE, false) ?: false
     val notification = buildNotification()
-    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
-      startForeground(
-        NOTIFICATION_ID,
-        notification,
-        android.content.pm.ServiceInfo.FOREGROUND_SERVICE_TYPE_MICROPHONE or
-          android.content.pm.ServiceInfo.FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK
-      )
-    } else {
-      startForeground(NOTIFICATION_ID, notification)
+    try {
+      if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
+        // Always allow media playback; only advertise the microphone type when
+        // we are actually capturing. Declaring FOREGROUND_SERVICE_TYPE_MICROPHONE
+        // for a playback-only session throws a SecurityException on Android 14+
+        // when the RECORD_AUDIO permission has not been granted.
+        var serviceType = ServiceInfo.FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK
+        if (withMicrophone) {
+          serviceType = serviceType or ServiceInfo.FOREGROUND_SERVICE_TYPE_MICROPHONE
+        }
+        startForeground(NOTIFICATION_ID, notification, serviceType)
+      } else {
+        startForeground(NOTIFICATION_ID, notification)
+      }
+    } catch (e: Exception) {
+      // e.g. a missing-permission or background-start restriction. Don't crash
+      // the host app over the keep-alive notification — just bail out cleanly.
+      Log.w(TAG, "startForeground failed", e)
+      stopSelf()
+      return START_NOT_STICKY
     }
 
     return START_STICKY
diff --git a/android/src/main/java/com/deepgram/DeepgramModule.kt b/android/src/main/java/com/deepgram/DeepgramModule.kt
index 6f8ab25..dd3336a 100644
--- a/android/src/main/java/com/deepgram/DeepgramModule.kt
+++ b/android/src/main/java/com/deepgram/DeepgramModule.kt
@@ -1,22 +1,7 @@
 package com.deepgram
 
 import android.Manifest
-import android.content.BroadcastReceiver
-import android.content.Context
-import android.content.Intent
-import android.content.IntentFilter
 import android.content.pm.PackageManager
-import android.media.AudioAttributes
-import android.media.AudioFormat
-import android.media.AudioManager
-import android.media.AudioFocusRequest
-import android.media.AudioRecord
-import android.media.AudioTrack
-import android.media.MediaRecorder
-import android.media.audiofx.AcousticEchoCanceler
-import android.media.audiofx.AutomaticGainControl
-import android.media.audiofx.NoiseSuppressor
-import android.os.Build
 import android.os.Handler
 import android.os.Looper
 import android.util.Base64
@@ -29,150 +14,86 @@ import com.facebook.react.bridge.ReactMethod
 import com.facebook.react.bridge.ReadableMap
 import com.facebook.react.bridge.WritableNativeMap
 import com.facebook.react.modules.core.DeviceEventManagerModule
-import java.util.concurrent.LinkedBlockingQueue
-import java.util.concurrent.atomic.AtomicInteger
 
 /**
- * Native module that records raw PCM audio and plays back base64 encoded
- * PCM chunks. Audio data recorded from the microphone is emitted to JS as the
- * `AudioChunk` event with base64-encoded PCM.
+ * React Native bridge for Deepgram audio.
+ *
+ * This class is intentionally thin: it owns the JS-facing `@ReactMethod`
+ * surface, the foreground-service lifecycle, and audio-focus arbitration, and
+ * delegates the actual audio work to three focused collaborators:
+ *
+ *   - [AudioRecorder]     microphone capture (emitted to JS as the `AudioChunk` event)
+ *   - [AudioPlayer]       TTS streaming + one-shot playback
+ *   - [AudioFocusManager] system audio-focus arbitration
+ *
+ * Microphone audio is emitted to JS as the `AudioChunk` event with
+ * base64-encoded 16 kHz PCM16.
  */
 class DeepgramModule(private val reactContext: ReactApplicationContext) :
-  ReactContextBaseJavaModule(reactContext) {
-
-  companion object {
-    const val NAME = "Deepgram"
-    private const val TAG = "DeepgramModule"
-    // Recording is locked to 16 kHz PCM16 mono — the JS side downsamples from
-    // here to whatever Deepgram is configured for. Do NOT mix this with the
-    // playback rate (which can vary, e.g. 24 kHz for Aura TTS).
-    private const val RECORD_SAMPLE_RATE = 16000
-    private const val DEFAULT_PLAYBACK_SAMPLE_RATE = 16000
-    private const val CHANNEL_CONFIG = AudioFormat.CHANNEL_IN_MONO
-    private const val AUDIO_FORMAT = AudioFormat.ENCODING_PCM_16BIT
-    // Cap the streaming playback queue to prevent unbounded memory growth
-    // when JS feeds audio faster than the device can play it. ~5 s of 24 kHz
-    // PCM16 mono is roughly 240 KB — we allow a little more headroom.
-    private const val MAX_QUEUED_PLAYBACK_BYTES = 1_500_000
-  }
-
-  private var playbackSampleRate: Int = DEFAULT_PLAYBACK_SAMPLE_RATE
-  private var currentOutputChannels: Int = 1
+  ReactContextBaseJavaModule(reactContext), AudioFocusManager.Listener {
 
   private val mainHandler by lazy { Handler(Looper.getMainLooper()) }
 
-  private val minRecordBufferSize: Int
-    get() {
-      val min = AudioRecord.getMinBufferSize(RECORD_SAMPLE_RATE, CHANNEL_CONFIG, AUDIO_FORMAT)
-      if (min > 0) return min
+  private val focusManager = AudioFocusManager(reactContext, mainHandler, this)
 
-      val fallback = maxOf((RECORD_SAMPLE_RATE / 5) * 2, 4096)
-      Log.w(TAG, "Invalid AudioRecord min buffer ($min), using fallback=$fallback")
-      return fallback
-    }
+  private val recorder = AudioRecorder(
+    context = reactContext,
+    onAudioChunk = { data, length -> sendAudioChunk(data, length) },
+    onForegroundServiceRequest = { startForegroundAudioService() },
+    onForegroundServiceRelease = { stopForegroundAudioServiceIfInactive() },
+    onAudioLevel = { level -> sendAudioLevel(level) },
+  )
 
-  private val bufferSize: Int
-    get() = minRecordBufferSize * 4
-
-  @Volatile
-  private var audioRecord: AudioRecord? = null
-  private var recordingThread: Thread? = null
-  @Volatile
-  private var isRecording = false
-  private var acousticEchoCanceler: AcousticEchoCanceler? = null
-  private var noiseSuppressor: NoiseSuppressor? = null
-  private var automaticGainControl: AutomaticGainControl? = null
-
-  // When `enableVoiceProcessing=true`, we set the system into
-  // MODE_IN_COMMUNICATION so the platform engages telephony-grade AEC.
-  // We remember the prior mode so we can restore it on stop and not
-  // strand the device in voice-call routing.
-  private var voiceProcessingActive = false
-  private var savedAudioMode: Int = AudioManager.MODE_NORMAL
-
-  // TTS Streaming Playback
-  private var audioTrack: AudioTrack? = null
-  private val audioQueue = LinkedBlockingQueue<ByteArray>()
-  @Volatile
-  private var isPlaying = false
-  private var playbackThread: Thread? = null
-  private val playbackThreshold = 1024
-  private val queuedBytes = AtomicInteger(0)
-
-  // Audio focus
-  private var audioManager: AudioManager? = null
-  private var audioFocusRequest: AudioFocusRequest? = null
-  private var hasAudioFocus = false
-
-  // ACTION_AUDIO_BECOMING_NOISY — fires when wired headset is unplugged or A2DP
-  // disconnects. Without handling this, our AudioTrack would silently re-route
-  // to the loudspeaker and surprise the user. Standard Android best practice.
-  private var noisyReceiverRegistered = false
-  private val becomingNoisyReceiver = object : BroadcastReceiver() {
-    override fun onReceive(context: Context?, intent: Intent?) {
-      if (intent?.action == AudioManager.ACTION_AUDIO_BECOMING_NOISY) {
-        Log.i(TAG, "AUDIO_BECOMING_NOISY — pausing playback")
-        try { audioTrack?.pause() } catch (_: Exception) {}
-      }
-    }
-  }
-
-  private val audioFocusListener = AudioManager.OnAudioFocusChangeListener { focusChange ->
-    when (focusChange) {
-      AudioManager.AUDIOFOCUS_LOSS -> {
-        // Permanent loss (e.g. another app took focus). Tear down so we don't
-        // fight other audio packages and so we release the microphone.
-        Log.i(TAG, "AUDIOFOCUS_LOSS — stopping Deepgram audio")
-        hasAudioFocus = false
-        try { stopStreamingPlayback(throwOnError = false) } catch (_: Exception) {}
-        try { stopRecordingInternal(throwOnError = false) } catch (_: Exception) {}
-      }
-      AudioManager.AUDIOFOCUS_LOSS_TRANSIENT,
-      AudioManager.AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK -> {
-        // Transient loss (e.g. incoming call) — pause playback but keep state.
-        Log.i(TAG, "AUDIOFOCUS_LOSS_TRANSIENT — pausing playback")
-        try { audioTrack?.pause() } catch (_: Exception) {}
-      }
-      AudioManager.AUDIOFOCUS_GAIN -> {
-        Log.i(TAG, "AUDIOFOCUS_GAIN — resuming playback if active")
-        hasAudioFocus = true
-        if (isPlaying) {
-          try { audioTrack?.play() } catch (_: Exception) {}
-        }
-      }
-    }
-  }
+  private val player = AudioPlayer(
+    context = reactContext,
+    mainHandler = mainHandler,
+    focusManager = focusManager,
+    onForegroundServiceRequest = { startForegroundAudioService() },
+    onForegroundServiceRelease = { stopForegroundAudioServiceIfInactive() },
+  )
 
   override fun getName() = NAME
 
-  private fun outputChannelMask(): Int {
-    return if (currentOutputChannels >= 2) {
-      AudioFormat.CHANNEL_OUT_STEREO
-    } else {
-      AudioFormat.CHANNEL_OUT_MONO
-    }
+  // -------------------------------------------------------------------
+  // Audio focus (AudioFocusManager.Listener)
+  // -------------------------------------------------------------------
+
+  override fun onFocusLostPermanently() {
+    // Permanent loss (e.g. another app took focus). Tear down so we don't fight
+    // other audio packages and so we release the microphone. Order matches the
+    // original: stop playback first, then recording.
+    try { player.stopStreamingPlayback(throwOnError = false) } catch (_: Exception) {}
+    try { player.stopOneShotPlayback() } catch (_: Exception) {}
+    try { recorder.stop(throwOnError = false) } catch (_: Exception) {}
   }
 
-  private fun minTrackBufferSize(channelMask: Int): Int {
-    val min = AudioTrack.getMinBufferSize(playbackSampleRate, channelMask, AUDIO_FORMAT)
-    if (min > 0) return min
+  override fun onFocusLostTransiently() {
+    // Transient loss (e.g. incoming call) — pause playback but keep state.
+    player.pauseForFocusLoss()
+  }
 
-    val bytesPerFrame = if (currentOutputChannels >= 2) 4 else 2
-    val fallback = maxOf((playbackSampleRate / 5) * bytesPerFrame, 4096)
-    Log.w(TAG, "Invalid AudioTrack min buffer ($min), using fallback=$fallback")
-    return fallback
+  override fun onFocusGained() {
+    player.resumeForFocusGain()
   }
 
+  // -------------------------------------------------------------------
+  // Foreground service coordination
+  //
+  // The keep-alive foreground service is shared by recording and playback: it
+  // is (re)started whenever either becomes active and stopped only once BOTH
+  // are inactive. It advertises the microphone type only while capturing.
+  // -------------------------------------------------------------------
+
   private fun startForegroundAudioService() {
     try {
-      DeepgramAudioService.start(reactContext)
+      DeepgramAudioService.start(reactContext, withMicrophone = recorder.isActive)
     } catch (e: Exception) {
       Log.w(TAG, "Unable to start foreground audio service", e)
     }
   }
 
   private fun stopForegroundAudioServiceIfInactive() {
-    if (isRecording || isPlaying) return
+    if (recorder.isActive || player.isActive) return
     try {
       DeepgramAudioService.stop(reactContext)
     } catch (e: Exception) {
@@ -186,7 +107,7 @@ class DeepgramModule(private val reactContext: ReactApplicationContext) :
 
   @ReactMethod
   fun startRecording(options: ReadableMap?, promise: Promise) {
-    if (isRecording) {
+    if (recorder.isActive) {
       promise.resolve(null)
       return
     }
@@ -206,352 +127,68 @@ class DeepgramModule(private val reactContext: ReactApplicationContext) :
         it.getBoolean("enableVoiceProcessing")
     } ?: false
 
-    // Voice Agent / duplex usage: route capture through the telephony stack so
-    // the platform's hardware AEC engages with the active playback signal as
-    // its reference. VOICE_RECOGNITION explicitly disables AEC/NS/AGC and is
-    // therefore the *wrong* source for full-duplex — it's only correct for
-    // one-way ASR where you want the rawest possible signal.
-    val audioSource = if (enableVoiceProcessing) {
-      MediaRecorder.AudioSource.VOICE_COMMUNICATION
-    } else {
-      MediaRecorder.AudioSource.VOICE_RECOGNITION
-    }
-
-    if (enableVoiceProcessing) {
-      applyVoiceCommunicationMode()
-    }
+    val recordToFilePath = resolveRecordToFilePath(options)
 
     try {
-      val recorder = AudioRecord.Builder()
-        .setAudioSource(audioSource)
-        .setAudioFormat(
-          AudioFormat.Builder()
-            .setEncoding(AUDIO_FORMAT)
-            .setSampleRate(RECORD_SAMPLE_RATE)
-            .setChannelMask(CHANNEL_CONFIG)
-            .build()
-        )
-        .setBufferSizeInBytes(bufferSize)
-        .build()
-      audioRecord = recorder
-
-      if (recorder.state != AudioRecord.STATE_INITIALIZED) {
-        recorder.release()
-        audioRecord = null
-        releaseAudioEffects()
-        restoreAudioModeIfNeeded()
-        promise.reject("init_failed", "AudioRecord initialization failed")
-        return
-      }
-
-      enableAudioEffects(recorder)
-      recorder.startRecording()
-      isRecording = true
-      startForegroundAudioService()
-
-      startRecordingThread()
+      recorder.start(enableVoiceProcessing, recordToFilePath)
       promise.resolve(null)
     } catch (e: SecurityException) {
-      Log.e(TAG, "startRecording security error", e)
-      audioRecord?.release()
-      audioRecord = null
-      releaseAudioEffects()
-      restoreAudioModeIfNeeded()
       promise.reject("permission_denied", e)
+    } catch (e: AudioRecorder.InitializationException) {
+      promise.reject("init_failed", e.message)
     } catch (e: Exception) {
-      Log.e(TAG, "startRecording error", e)
-      audioRecord?.release()
-      audioRecord = null
-      releaseAudioEffects()
-      restoreAudioModeIfNeeded()
       promise.reject("start_error", e)
     }
   }
 
-  private fun applyVoiceCommunicationMode() {
-    if (voiceProcessingActive) return
-    try {
-      val manager = audioManager
-        ?: (reactContext.getSystemService(Context.AUDIO_SERVICE) as? AudioManager)
-      if (manager == null) {
-        Log.w(TAG, "applyVoiceCommunicationMode: AudioManager unavailable")
-        return
-      }
-      audioManager = manager
-      savedAudioMode = manager.mode
-      manager.mode = AudioManager.MODE_IN_COMMUNICATION
-      voiceProcessingActive = true
-      Log.i(TAG, "Switched audio mode to IN_COMMUNICATION (was $savedAudioMode) for AEC")
-    } catch (e: Exception) {
-      Log.w(TAG, "applyVoiceCommunicationMode failed", e)
-    }
-  }
-
-  private fun restoreAudioModeIfNeeded() {
-    if (!voiceProcessingActive) return
-    try {
-      val manager = audioManager
-        ?: (reactContext.getSystemService(Context.AUDIO_SERVICE) as? AudioManager)
-      manager?.mode = savedAudioMode
-      Log.i(TAG, "Restored audio mode to $savedAudioMode")
-    } catch (e: Exception) {
-      Log.w(TAG, "restoreAudioModeIfNeeded failed", e)
-    } finally {
-      voiceProcessingActive = false
-    }
-  }
-
-  private fun stopRecordingInternal(throwOnError: Boolean = true) {
-    isRecording = false
-    recordingThread?.let { thread ->
-      thread.interrupt()
-      try {
-        thread.join(500)
-      } catch (_: InterruptedException) {
-        Thread.currentThread().interrupt()
-      }
-    }
-    recordingThread = null
+  /**
+   * Resolve the WAV destination for a record-to-file session, or null when the
+   * caller did not request one. A caller-supplied `path` wins; otherwise we
+   * generate an app-specific cache path so the result is a shareable file URI.
+   */
+  private fun resolveRecordToFilePath(options: ReadableMap?): String? {
+    val rtf = options?.takeIf { it.hasKey("recordToFile") && !it.isNull("recordToFile") }
+      ?.getMap("recordToFile")
+      ?: return null
 
-    try {
-      audioRecord?.stop()
-    } catch (e: Exception) {
-      Log.w(TAG, "stopRecordingInternal: error stopping AudioRecord", e)
-      if (throwOnError) throw e
-    }
+    val enabled = rtf.hasKey("enabled") && !rtf.isNull("enabled") && rtf.getBoolean("enabled")
+    if (!enabled) return null
 
-    try {
-      audioRecord?.release()
-    } catch (e: Exception) {
-      Log.w(TAG, "stopRecordingInternal: error releasing AudioRecord", e)
-      if (throwOnError) throw e
-    }
+    val custom = if (rtf.hasKey("path") && !rtf.isNull("path")) rtf.getString("path") else null
+    if (!custom.isNullOrEmpty()) return custom
 
-    audioRecord = null
-    releaseAudioEffects()
-    restoreAudioModeIfNeeded()
-    stopForegroundAudioServiceIfInactive()
+    return java.io.File(
+      reactContext.cacheDir,
+      "deepgram-recording-${System.currentTimeMillis()}.wav"
+    ).absolutePath
   }
 
   @ReactMethod
   fun stopRecording(promise: Promise) {
     try {
-      stopRecordingInternal()
-      promise.resolve(null)
+      recorder.stop()
+      val uri = recorder.lastRecordingUri
+      if (uri != null) {
+        val map = WritableNativeMap()
+        map.putString("recordingUri", uri)
+        promise.resolve(map)
+      } else {
+        promise.resolve(null)
+      }
     } catch (e: Exception) {
       Log.e(TAG, "stopRecording error", e)
       promise.reject("stop_error", e)
     }
   }
 
-  private fun enableAudioEffects(recorder: AudioRecord) {
-    val sessionId = recorder.audioSessionId
-    if (sessionId == AudioRecord.ERROR || sessionId == AudioRecord.ERROR_BAD_VALUE) {
-      return
-    }
-
-    releaseAudioEffects()
-
-    if (AcousticEchoCanceler.isAvailable()) {
-      try {
-        acousticEchoCanceler = AcousticEchoCanceler.create(sessionId)?.apply {
-          enabled = true
-        }
-      } catch (e: Exception) {
-        Log.w(TAG, "Unable to enable AcousticEchoCanceler", e)
-      }
-    }
-
-    if (NoiseSuppressor.isAvailable()) {
-      try {
-        noiseSuppressor = NoiseSuppressor.create(sessionId)?.apply {
-          enabled = true
-        }
-      } catch (e: Exception) {
-        Log.w(TAG, "Unable to enable NoiseSuppressor", e)
-      }
-    }
-
-    if (AutomaticGainControl.isAvailable()) {
-      try {
-        automaticGainControl = AutomaticGainControl.create(sessionId)?.apply {
-          enabled = true
-        }
-      } catch (e: Exception) {
-        Log.w(TAG, "Unable to enable AutomaticGainControl", e)
-      }
-    }
-  }
-
-  private fun releaseAudioEffects() {
-    try {
-      acousticEchoCanceler?.release()
-    } catch (e: Exception) {
-      Log.w(TAG, "Error releasing AcousticEchoCanceler", e)
-    } finally {
-      acousticEchoCanceler = null
-    }
-
-    try {
-      noiseSuppressor?.release()
-    } catch (e: Exception) {
-      Log.w(TAG, "Error releasing NoiseSuppressor", e)
-    } finally {
-      noiseSuppressor = null
-    }
-
-    try {
-      automaticGainControl?.release()
-    } catch (e: Exception) {
-      Log.w(TAG, "Error releasing AutomaticGainControl", e)
-    } finally {
-      automaticGainControl = null
-    }
-  }
-
-  private fun startRecordingThread() {
-    recordingThread = Thread({
-      try {
-        android.os.Process.setThreadPriority(android.os.Process.THREAD_PRIORITY_URGENT_AUDIO)
-        val buffer = ByteArray(bufferSize)
-        while (isRecording) {
-          val recorder = audioRecord ?: break
-          val read = recorder.read(buffer, 0, buffer.size)
-          if (read > 0) {
-            sendAudioChunk(buffer, read)
-          } else if (read < 0) {
-            // ERROR_INVALID_OPERATION / ERROR_BAD_VALUE / ERROR_DEAD_OBJECT —
-            // bail rather than spin in a tight loop.
-            Log.w(TAG, "AudioRecord.read returned $read — stopping thread")
-            break
-          }
-        }
-      } catch (e: Exception) {
-        Log.e(TAG, "recording thread error", e)
-      }
-    }, "Deepgram-Recording")
-    recordingThread?.start()
-  }
-
-  /**
-   * Emit audio data to JS as base64-encoded PCM (matches iOS format).
-   * This is far more efficient than sending individual byte values.
-   */
-  private fun sendAudioChunk(data: ByteArray, length: Int) {
-    if (!reactContext.hasActiveReactInstance()) return
-    val b64 = Base64.encodeToString(data, 0, length, Base64.NO_WRAP)
-    val map = WritableNativeMap()
-    map.putString("b64", b64)
-    map.putInt("sampleRate", RECORD_SAMPLE_RATE)
-    try {
-      reactContext
-        .getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter::class.java)
-        .emit("AudioChunk", map)
-    } catch (e: Exception) {
-      // Catalyst tearing down or JS bundle not ready — drop silently.
-      Log.w(TAG, "sendAudioChunk emit failed", e)
-    }
-  }
-
   // -------------------------------------------------------------------
   // Playback
   // -------------------------------------------------------------------
 
-  private fun ensureAudioTrack() {
-    if (audioTrack != null) return
-
-    val channelMask = outputChannelMask()
-    val minBuf = minTrackBufferSize(channelMask)
-
-    audioTrack = AudioTrack.Builder()
-      .setAudioAttributes(
-        AudioAttributes.Builder()
-          .setUsage(AudioAttributes.USAGE_VOICE_COMMUNICATION)
-          .setContentType(AudioAttributes.CONTENT_TYPE_SPEECH)
-          .build()
-      )
-      .setAudioFormat(
-        AudioFormat.Builder()
-          .setEncoding(AUDIO_FORMAT)
-          .setSampleRate(playbackSampleRate)
-          .setChannelMask(channelMask)
-          .build()
-      )
-      .setBufferSizeInBytes(maxOf(minBuf, bufferSize))
-      .setTransferMode(AudioTrack.MODE_STREAM)
-      .build()
-  }
-
-  private fun requestAudioFocus(): Boolean {
-    if (hasAudioFocus) return true
-    try {
-      val manager = reactContext.getSystemService(android.content.Context.AUDIO_SERVICE) as? AudioManager
-        ?: return false
-      audioManager = manager
-
-      // Use AUDIOFOCUS_GAIN_TRANSIENT so other audio apps (Spotify, podcasts,
-      // navigation, etc.) pause/duck and then automatically resume when we
-      // abandon focus. AUDIOFOCUS_GAIN would permanently stop them.
-      val result = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
-        val request = AudioFocusRequest.Builder(AudioManager.AUDIOFOCUS_GAIN_TRANSIENT)
-          .setAudioAttributes(
-            AudioAttributes.Builder()
-              .setUsage(AudioAttributes.USAGE_VOICE_COMMUNICATION)
-              .setContentType(AudioAttributes.CONTENT_TYPE_SPEECH)
-              .build()
-          )
-          .setOnAudioFocusChangeListener(audioFocusListener, mainHandler)
-          .setWillPauseWhenDucked(true)
-          .build()
-        audioFocusRequest = request
-        manager.requestAudioFocus(request)
-      } else {
-        @Suppress("DEPRECATION")
-        manager.requestAudioFocus(
-          audioFocusListener,
-          AudioManager.STREAM_VOICE_CALL,
-          AudioManager.AUDIOFOCUS_GAIN_TRANSIENT
-        )
-      }
-
-      hasAudioFocus = result == AudioManager.AUDIOFOCUS_REQUEST_GRANTED
-      if (!hasAudioFocus) {
-        Log.w(TAG, "Audio focus request not granted (result=$result)")
-      }
-      return hasAudioFocus
-    } catch (e: Exception) {
-      Log.w(TAG, "requestAudioFocus error", e)
-      hasAudioFocus = false
-      return false
-    }
-  }
-
-  private fun abandonAudioFocus() {
-    if (!hasAudioFocus) return
-    try {
-      val manager = audioManager ?: return
-      if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
-        audioFocusRequest?.let { manager.abandonAudioFocusRequest(it) }
-      } else {
-        @Suppress("DEPRECATION")
-        manager.abandonAudioFocus(audioFocusListener)
-      }
-    } catch (e: Exception) {
-      Log.w(TAG, "abandonAudioFocus error", e)
-    } finally {
-      hasAudioFocus = false
-      audioFocusRequest = null
-    }
-  }
-
   @ReactMethod
   fun startAudio(promise: Promise) {
     try {
-      requestAudioFocus()
-      ensureAudioTrack()
-      audioTrack?.play()
-      isPlaying = true
-      startForegroundAudioService()
+      player.startAudio()
       promise.resolve(null)
     } catch (e: Exception) {
       Log.e(TAG, "startAudio error", e)
@@ -559,31 +196,10 @@ class DeepgramModule(private val reactContext: ReactApplicationContext) :
     }
   }
 
-  private fun stopAudioInternal(throwOnError: Boolean = true) {
-    try {
-      audioTrack?.stop()
-    } catch (e: Exception) {
-      Log.w(TAG, "stopAudioInternal: error stopping AudioTrack", e)
-      if (throwOnError) throw e
-    }
-
-    try {
-      audioTrack?.release()
-    } catch (e: Exception) {
-      Log.w(TAG, "stopAudioInternal: error releasing AudioTrack", e)
-      if (throwOnError) throw e
-    }
-
-    audioTrack = null
-    isPlaying = false
-    abandonAudioFocus()
-    stopForegroundAudioServiceIfInactive()
-  }
-
   @ReactMethod
   fun stopAudio(promise: Promise) {
     try {
-      stopAudioInternal()
+      player.stopAudio()
       promise.resolve(null)
     } catch (e: Exception) {
       Log.e(TAG, "stopAudio error", e)
@@ -591,128 +207,35 @@ class DeepgramModule(private val reactContext: ReactApplicationContext) :
     }
   }
 
-  // -------------------------------------------------------------------
-  // TTS Streaming Audio Player
-  // Uses a proper queue instead of O(n²) array concatenation.
-  // -------------------------------------------------------------------
-
   @ReactMethod
   fun startPlayer(sampleRate: Int, channels: Int) {
-    stopStreamingPlayback()
-    playbackSampleRate = if (sampleRate > 0) sampleRate else DEFAULT_PLAYBACK_SAMPLE_RATE
-    currentOutputChannels = if (channels >= 2) 2 else 1
-    audioQueue.clear()
-    queuedBytes.set(0)
-    isPlaying = false
+    player.startPlayer(sampleRate, channels)
   }
 
   @ReactMethod
   fun setAudioConfig(sampleRate: Int, channels: Int) {
-    startPlayer(sampleRate, channels)
+    player.setAudioConfig(sampleRate, channels)
   }
 
   @ReactMethod
-  fun feedAudio(base64Audio: String) {
-    try {
-      val audioData = Base64.decode(base64Audio, Base64.DEFAULT)
-      if (audioData.isEmpty()) return
-
-      // Bound the queue to prevent unbounded memory growth if JS is producing
-      // audio faster than the device can play it. Drop the oldest chunk first
-      // (so we always favor newer audio) when at the limit.
-      while (queuedBytes.get() + audioData.size > MAX_QUEUED_PLAYBACK_BYTES) {
-        val dropped = audioQueue.poll() ?: break
-        queuedBytes.addAndGet(-dropped.size)
-        Log.w(TAG, "feedAudio: dropping ${dropped.size} bytes — playback queue full")
-      }
-
-      audioQueue.offer(audioData)
-      queuedBytes.addAndGet(audioData.size)
-
-      // Start playback when we have enough buffered data
-      if (!isPlaying && queuedBytes.get() >= playbackThreshold) {
-        startStreamingPlayback()
-      }
-    } catch (e: Exception) {
-      Log.e(TAG, "feedAudio error", e)
-    }
+  fun setMeteringEnabled(enabled: Boolean, intervalMs: Double) {
+    recorder.setMetering(enabled, intervalMs.toLong())
   }
 
   @ReactMethod
-  fun interruptAudio() {
-    try {
-      stopStreamingPlayback(throwOnError = false)
-    } catch (e: Exception) {
-      Log.w(TAG, "interruptAudio error", e)
-    }
-  }
-
-  private fun startStreamingPlayback() {
-    if (isPlaying) return
-
-    isPlaying = true
-    registerNoisyReceiver()
-    playbackThread = Thread({
-      try {
-        android.os.Process.setThreadPriority(android.os.Process.THREAD_PRIORITY_URGENT_AUDIO)
-        requestAudioFocus()
-        startForegroundAudioService()
-        ensureAudioTrack()
-        audioTrack?.play()
-
-        while (isPlaying) {
-          // Block until data is available (up to 100ms), avoids busy-wait
-          val chunk = audioQueue.poll(100, java.util.concurrent.TimeUnit.MILLISECONDS)
-            ?: continue
-
-          queuedBytes.addAndGet(-chunk.size)
-          val written = audioTrack?.write(chunk, 0, chunk.size) ?: 0
-          if (written < 0) {
-            Log.e(TAG, "AudioTrack write error: $written")
-            break
-          }
-        }
-      } catch (e: InterruptedException) {
-        // Normal shutdown
-      } catch (e: Exception) {
-        Log.e(TAG, "Streaming playback error", e)
-      } finally {
-        isPlaying = false
-        stopForegroundAudioServiceIfInactive()
-      }
-    }, "Deepgram-Playback")
-
-    playbackThread?.start()
+  fun feedAudio(base64Audio: String) {
+    player.feedAudio(base64Audio)
   }
 
-  private fun stopStreamingPlayback(throwOnError: Boolean = true) {
-    isPlaying = false
-    playbackThread?.let { thread ->
-      thread.interrupt()
-      try {
-        thread.join(500)
-      } catch (_: InterruptedException) {
-        Thread.currentThread().interrupt()
-      }
-    }
-    playbackThread = null
-
-    try {
-      stopAudioInternal(throwOnError)
-    } catch (e: Exception) {
-      if (throwOnError) throw e else Log.w(TAG, "stopStreamingPlayback: error stopping audio", e)
-    } finally {
-      audioQueue.clear()
-      queuedBytes.set(0)
-      unregisterNoisyReceiver()
-      stopForegroundAudioServiceIfInactive()
-    }
+  @ReactMethod
+  fun interruptAudio() {
+    player.interruptAudio()
   }
 
   @ReactMethod
   fun stopPlayer(promise: Promise?) {
     try {
-      stopStreamingPlayback()
+      player.stopStreamingPlayback()
       promise?.resolve(null)
     } catch (e: Exception) {
       Log.e(TAG, "stopPlayer error", e)
@@ -720,124 +243,77 @@ class DeepgramModule(private val reactContext: ReactApplicationContext) :
     }
   }
 
+  // -------------------------------------------------------------------
+  // One-shot playback (for HTTP synthesis)
+  // -------------------------------------------------------------------
+
+  @ReactMethod
+  fun playAudioChunk(chunk: String, promise: Promise) {
+    player.playAudioChunk(
+      chunk,
+      onSuccess = { promise.resolve(null) },
+      onError = { code, message -> promise.reject(code, message) },
+    )
+  }
+
   override fun invalidate() {
     try {
-      stopRecordingInternal(false)
+      recorder.stop(false)
     } catch (e: Exception) {
       Log.w(TAG, "Error stopping recording on invalidate", e)
     }
 
     try {
-      stopStreamingPlayback(false)
+      player.release()
     } catch (e: Exception) {
       Log.w(TAG, "Error stopping playback on invalidate", e)
     }
 
-    abandonAudioFocus()
-    unregisterNoisyReceiver()
+    focusManager.abandonFocus()
     super.invalidate()
   }
 
-  private fun registerNoisyReceiver() {
-    if (noisyReceiverRegistered) return
+  /**
+   * Emit microphone audio to JS as base64-encoded PCM (matches the iOS
+   * `DeepgramAudioPCM` payload shape). Far more efficient than sending
+   * individual byte values.
+   */
+  private fun sendAudioChunk(data: ByteArray, length: Int) {
+    if (!reactContext.hasActiveReactInstance()) return
+    val b64 = Base64.encodeToString(data, 0, length, Base64.NO_WRAP)
+    val map = WritableNativeMap()
+    map.putString("b64", b64)
+    map.putInt("sampleRate", AudioRecorder.RECORD_SAMPLE_RATE)
     try {
-      val filter = IntentFilter(AudioManager.ACTION_AUDIO_BECOMING_NOISY)
-      if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
-        reactContext.registerReceiver(
-          becomingNoisyReceiver,
-          filter,
-          Context.RECEIVER_NOT_EXPORTED
-        )
-      } else {
-        @Suppress("UnspecifiedRegisterReceiverFlag")
-        reactContext.registerReceiver(becomingNoisyReceiver, filter)
-      }
-      noisyReceiverRegistered = true
+      reactContext
+        .getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter::class.java)
+        .emit("AudioChunk", map)
     } catch (e: Exception) {
-      Log.w(TAG, "registerNoisyReceiver failed", e)
+      // Catalyst tearing down or JS bundle not ready — drop silently.
+      Log.w(TAG, "sendAudioChunk emit failed", e)
     }
   }
 
-  private fun unregisterNoisyReceiver() {
-    if (!noisyReceiverRegistered) return
+  /**
+   * Emit a microphone audio level (normalized RMS, 0..1) to JS as the
+   * `AudioLevel` event (matches the iOS `DeepgramAudioLevel` payload shape).
+   */
+  private fun sendAudioLevel(level: Double) {
+    if (!reactContext.hasActiveReactInstance()) return
+    val map = WritableNativeMap()
+    map.putDouble("level", level)
     try {
-      reactContext.unregisterReceiver(becomingNoisyReceiver)
+      reactContext
+        .getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter::class.java)
+        .emit("AudioLevel", map)
     } catch (e: Exception) {
-      Log.w(TAG, "unregisterNoisyReceiver failed", e)
-    } finally {
-      noisyReceiverRegistered = false
+      // Catalyst tearing down or JS bundle not ready — drop silently.
+      Log.w(TAG, "sendAudioLevel emit failed", e)
     }
   }
 
-  // -------------------------------------------------------------------
-  // One-shot playback (for HTTP synthesis)
-  // -------------------------------------------------------------------
-
-  @ReactMethod
-  fun playAudioChunk(chunk: String, promise: Promise) {
-    try {
-      val audioData = Base64.decode(chunk, Base64.DEFAULT)
-      if (audioData.isEmpty()) {
-        promise.reject("invalid_data", "Failed to decode audio data")
-        return
-      }
-
-      requestAudioFocus()
-      startForegroundAudioService()
-
-      val channelMask = outputChannelMask()
-      val minBuf = minTrackBufferSize(channelMask)
-
-      val tempAudioTrack = AudioTrack.Builder()
-        .setAudioAttributes(
-          AudioAttributes.Builder()
-            .setUsage(AudioAttributes.USAGE_VOICE_COMMUNICATION)
-            .setContentType(AudioAttributes.CONTENT_TYPE_SPEECH)
-            .build()
-        )
-        .setAudioFormat(
-          AudioFormat.Builder()
-            .setEncoding(AUDIO_FORMAT)
-            .setSampleRate(playbackSampleRate)
-            .setChannelMask(channelMask)
-            .build()
-        )
-        .setBufferSizeInBytes(maxOf(minBuf, audioData.size))
-        .setTransferMode(AudioTrack.MODE_STATIC)
-        .build()
-
-      tempAudioTrack.write(audioData, 0, audioData.size)
-
-      // Use notification marker to know when playback finishes,
-      // then resolve the promise (instead of polling with Thread.sleep).
-      val bytesPerFrame = if (currentOutputChannels >= 2) 4 else 2 // PCM16 mono/stereo
-      val frameCount = audioData.size / bytesPerFrame
-      tempAudioTrack.notificationMarkerPosition = frameCount
-      val listener = object : AudioTrack.OnPlaybackPositionUpdateListener {
-        override fun onMarkerReached(track: AudioTrack?) {
-          try {
-            track?.stop()
-            track?.release()
-          } catch (e: Exception) {
-            Log.w(TAG, "playAudioChunk cleanup error", e)
-          }
-          abandonAudioFocus()
-          stopForegroundAudioServiceIfInactive()
-          promise.resolve(null)
-        }
-
-        override fun onPeriodicNotification(track: AudioTrack?) {}
-      }
-
-      // minSdk is 24, the Handler-aware overload is always available.
-      tempAudioTrack.setPlaybackPositionUpdateListener(listener, mainHandler)
-
-      tempAudioTrack.play()
-    } catch (e: Exception) {
-      Log.e(TAG, "playAudioChunk error", e)
-      abandonAudioFocus()
-      stopForegroundAudioServiceIfInactive()
-      promise.reject("playback_error", e.message)
-    }
+  companion object {
+    const val NAME = "Deepgram"
+    private const val TAG = "DeepgramModule"
   }
 }
diff --git a/assets/example.webp b/assets/example.webp
new file mode 100644
index 0000000..d32daed
Binary files /dev/null and b/assets/example.webp differ
diff --git a/example/app.json b/example/app.json
index a3223c7..3fecd6d 100644
--- a/example/app.json
+++ b/example/app.json
@@ -4,10 +4,7 @@
     "slug": "react-native-deepgram-example",
     "version": "1.0.0",
     "orientation": "portrait",
-    "platforms": [
-      "ios",
-      "android"
-    ],
+    "platforms": ["ios", "android"],
     "jsEngine": "hermes",
     "newArchEnabled": true,
     "ios": {
@@ -19,6 +16,14 @@
         {
           "microphonePermission": "Allow $(PRODUCT_NAME) to access your microphone"
         }
+      ],
+      [
+        "expo-build-properties",
+        {
+          "android": {
+            "kotlinVersion": "1.9.24"
+          }
+        }
       ]
     ],
     "android": {
diff --git a/example/package.json b/example/package.json
index f730d96..cd3d348 100644
--- a/example/package.json
+++ b/example/package.json
@@ -16,7 +16,9 @@
   "dependencies": {
     "@expo/metro-runtime": "~4.0.1",
     "expo": "~52.0.27",
+    "expo-build-properties": "~0.13.3",
     "expo-document-picker": "^12.0.2",
+    "expo-file-system": "~18.0.12",
     "react": "18.3.1",
     "react-dom": "18.3.1",
     "react-native": "0.76.6",
diff --git a/example/src/App.tsx b/example/src/App.tsx
index e2c6f31..b763498 100644
--- a/example/src/App.tsx
+++ b/example/src/App.tsx
@@ -17,8 +17,38 @@ import VoiceAgent from './VoiceAgent';
 import { colors, radius, spacing, type } from './theme';
 
 // Initialize Deepgram once at startup. Provide your key via .env (EXPO_PUBLIC_DEEPGRAM_API_KEY).
+//
+// Custom endpoints (regional, Dedicated, or self-hosted) are opt-in: set any of
+// the EXPO_PUBLIC_DEEPGRAM_BASE_URL / BASE_WSS / AGENT_URL vars in .env and they
+// flow straight into configure(). Leave them unset to use Deepgram's defaults.
+//
+// Auth: for production, prefer ephemeral tokens over a raw API key. Set
+// EXPO_PUBLIC_DEEPGRAM_TOKEN_URL to a backend endpoint that proxies Deepgram's
+// /v1/auth/grant and returns { access_token, expires_in }. When set, `getToken`
+// is used (and takes precedence over apiKey) so the key never ships in the app.
+// See README → "Ephemeral / scoped tokens".
+const tokenUrl = process.env.EXPO_PUBLIC_DEEPGRAM_TOKEN_URL;
+
 configure({
   apiKey: process.env.EXPO_PUBLIC_DEEPGRAM_API_KEY || 'YOUR_DEEPGRAM_API_KEY',
+  ...(tokenUrl
+    ? {
+        getToken: async () => {
+          const res = await fetch(tokenUrl);
+          const { access_token, expires_in } = await res.json();
+          return { token: access_token, expiresInSeconds: expires_in };
+        },
+      }
+    : {}),
+  ...(process.env.EXPO_PUBLIC_DEEPGRAM_BASE_URL
+    ? { baseUrl: process.env.EXPO_PUBLIC_DEEPGRAM_BASE_URL }
+    : {}),
+  ...(process.env.EXPO_PUBLIC_DEEPGRAM_BASE_WSS
+    ? { baseWss: process.env.EXPO_PUBLIC_DEEPGRAM_BASE_WSS }
+    : {}),
+  ...(process.env.EXPO_PUBLIC_DEEPGRAM_AGENT_URL
+    ? { agentUrl: process.env.EXPO_PUBLIC_DEEPGRAM_AGENT_URL }
+    : {}),
 });
 
 type ScreenKey = 'voice' | 'speech' | 'tts' | 'text' | 'management';
diff --git a/example/src/SpeechToText.tsx b/example/src/SpeechToText.tsx
index 4db2def..fb69083 100644
--- a/example/src/SpeechToText.tsx
+++ b/example/src/SpeechToText.tsx
@@ -4,13 +4,17 @@ import {
   Animated,
   ScrollView,
   StyleSheet,
+  Switch,
   Text,
   View,
 } from 'react-native';
 import * as DocumentPicker from 'expo-document-picker';
-import { useDeepgramSpeechToText } from 'react-native-deepgram';
+import * as FileSystem from 'expo-file-system';
+import { DeepgramError, useDeepgramSpeechToText } from 'react-native-deepgram';
 import Button from './components/Button';
 import Card from './components/Card';
+import Field from './components/Field';
+import OptionSelect from './components/OptionSelect';
 import StatusBadge from './components/StatusBadge';
 import { colors, radius, spacing, type } from './theme';
 
@@ -19,16 +23,43 @@ export default function SpeechToText() {
   const [liveInterimTranscript, setLiveInterimTranscript] = useState('');
   const [fileTranscript, setFileTranscript] = useState('');
   const [pickedFileName, setPickedFileName] = useState<string | null>(null);
+  const [reconnectAttempt, setReconnectAttempt] = useState<number | null>(null);
+
+  // Record-to-file is opt-in: the user chooses whether to save and where.
+  const [recordEnabled, setRecordEnabled] = useState(false);
+  const [recordFolder, setRecordFolder] = useState<'documents' | 'cache'>(
+    'documents'
+  );
+  const [recordFileName, setRecordFileName] = useState(
+    'deepgram-recording.wav'
+  );
+
+  const recordDir =
+    recordFolder === 'cache'
+      ? FileSystem.cacheDirectory
+      : FileSystem.documentDirectory;
+  const safeRecordName =
+    recordFileName.trim().replace(/[/\\]/g, '') || 'deepgram-recording.wav';
+  const recordPath = `${recordDir ?? ''}${safeRecordName}`;
 
   const {
     startListening,
     stopListening,
+    pause,
+    resume,
     state: liveState,
+    isPaused,
+    audioLevel,
+    recordingUri,
   } = useDeepgramSpeechToText({
     trackState: true,
+    reconnect: { enabled: true },
+    metering: { enabled: true },
+    recordToFile: { enabled: recordEnabled, path: recordPath },
     onBeforeStart: () => {
       setLiveTranscript('');
       setLiveInterimTranscript('');
+      setReconnectAttempt(null);
     },
     onTranscript: (text, info) => {
       if (info?.isFinal) {
@@ -41,7 +72,19 @@ export default function SpeechToText() {
     onError: (err) => {
       console.error('Live STT error', err);
     },
-    onEnd: () => setLiveInterimTranscript(''),
+    onReconnecting: (attempt) => {
+      setReconnectAttempt(attempt);
+    },
+    onReconnected: () => {
+      setReconnectAttempt(null);
+    },
+    onEnd: () => {
+      setLiveInterimTranscript('');
+      setReconnectAttempt(null);
+    },
+    onRecordingComplete: (uri) => {
+      console.log('Saved mic recording to', uri);
+    },
     live: {
       model: 'nova-3',
       interimResults: true,
@@ -61,13 +104,16 @@ export default function SpeechToText() {
     },
   });
 
+  const isReconnecting = reconnectAttempt !== null;
   const isListening = liveState?.status === 'listening';
   const isTranscribing = fileState?.status === 'transcribing';
+  const sessionActive = isListening || isReconnecting;
+  const isCapturing = sessionActive && !isPaused;
 
   // Mic pulse
   const pulse = useRef(new Animated.Value(0)).current;
   useEffect(() => {
-    if (!isListening) {
+    if (!isCapturing) {
       pulse.stopAnimation();
       pulse.setValue(0);
       return undefined;
@@ -88,7 +134,22 @@ export default function SpeechToText() {
     );
     loop.start();
     return () => loop.stop();
-  }, [isListening, pulse]);
+  }, [isCapturing, pulse]);
+
+  // Mic level meter
+  const levelAnim = useRef(new Animated.Value(0)).current;
+  useEffect(() => {
+    Animated.timing(levelAnim, {
+      toValue: isCapturing ? Math.min(1, Math.max(0, audioLevel ?? 0)) : 0,
+      duration: 90,
+      useNativeDriver: false,
+    }).start();
+  }, [audioLevel, isCapturing, levelAnim]);
+  const meterWidth = levelAnim.interpolate({
+    inputRange: [0, 1],
+    outputRange: ['0%', '100%'],
+    extrapolate: 'clamp',
+  });
 
   const pickAndTranscribe = async () => {
     try {
@@ -113,12 +174,29 @@ export default function SpeechToText() {
     }
   };
 
-  const tone = liveState?.error ? 'error' : isListening ? 'live' : 'idle';
+  const stopLive = () => {
+    setReconnectAttempt(null);
+    stopListening();
+  };
+
+  const tone = liveState?.error
+    ? 'error'
+    : isReconnecting
+      ? 'connecting'
+      : isPaused
+        ? 'warning'
+        : isListening
+          ? 'live'
+          : 'idle';
   const toneLabel = liveState?.error
     ? 'Error'
-    : isListening
-      ? 'Listening'
-      : 'Ready';
+    : isReconnecting
+      ? 'Reconnecting'
+      : isPaused
+        ? 'Paused'
+        : isListening
+          ? 'Listening'
+          : 'Ready';
 
   const combinedLiveTranscript = [liveTranscript, liveInterimTranscript]
     .filter(Boolean)
@@ -143,7 +221,7 @@ export default function SpeechToText() {
           </View>
 
           <View style={styles.micWrap}>
-            {isListening && (
+            {isCapturing && (
               <Animated.View
                 style={[
                   styles.pulse,
@@ -152,29 +230,113 @@ export default function SpeechToText() {
               />
             )}
             <View
-              style={[styles.micCircle, isListening && styles.micCircleActive]}
+              style={[
+                styles.micCircle,
+                isCapturing && styles.micCircleActive,
+                isPaused && styles.micCirclePaused,
+              ]}
             >
-              <Text style={styles.micIcon}>🎤</Text>
+              <Text style={styles.micIcon}>{isPaused ? '🔇' : '🎤'}</Text>
             </View>
           </View>
 
           <Text style={styles.heroTitle}>
-            {isListening ? 'Listening…' : 'Live transcription'}
+            {isReconnecting
+              ? 'Reconnecting…'
+              : isPaused
+                ? 'Paused'
+                : isListening
+                  ? 'Listening…'
+                  : 'Live transcription'}
           </Text>
           <Text style={styles.heroSubtitle}>
-            {isListening
-              ? 'Tap stop when you are done.'
-              : 'Tap start and speak to see live transcripts.'}
+            {isReconnecting
+              ? 'Connection dropped — retrying automatically.'
+              : isListening
+                ? isPaused
+                  ? 'Mic muted — tap resume to continue.'
+                  : 'Tap stop when you are done.'
+                : 'Tap start and speak to see live transcripts.'}
           </Text>
 
-          <View style={styles.heroActions}>
-            {isListening ? (
-              <Button
-                title="Stop"
-                variant="danger"
-                size="lg"
-                onPress={stopListening}
+          {isCapturing ? (
+            <View style={styles.meterTrack}>
+              <Animated.View
+                style={[styles.meterFill, { width: meterWidth }]}
               />
+            </View>
+          ) : null}
+
+          <View style={styles.capabilityRow}>
+            <View style={styles.capabilityChip}>
+              <Text style={styles.capabilityChipText}>⏸ Pause / resume</Text>
+            </View>
+            <View
+              style={[
+                styles.capabilityChip,
+                isReconnecting && styles.capabilityChipActive,
+              ]}
+            >
+              <Text
+                style={[
+                  styles.capabilityChipText,
+                  isReconnecting && styles.capabilityChipTextActive,
+                ]}
+              >
+                ↻ Auto-reconnect
+              </Text>
+            </View>
+            <View
+              style={[
+                styles.capabilityChip,
+                isCapturing && styles.capabilityChipActive,
+              ]}
+            >
+              <Text
+                style={[
+                  styles.capabilityChipText,
+                  isCapturing && styles.capabilityChipTextActive,
+                ]}
+              >
+                🎚 Live level
+              </Text>
+            </View>
+            <View
+              style={[
+                styles.capabilityChip,
+                recordEnabled && styles.capabilityChipActive,
+              ]}
+            >
+              <Text
+                style={[
+                  styles.capabilityChipText,
+                  recordEnabled && styles.capabilityChipTextActive,
+                ]}
+              >
+                💾 Record to file
+              </Text>
+            </View>
+          </View>
+
+          <View style={styles.heroActions}>
+            {sessionActive ? (
+              <View style={styles.heroButtonRow}>
+                {isListening ? (
+                  <Button
+                    title={isPaused ? 'Resume' : 'Pause'}
+                    variant="secondary"
+                    size="lg"
+                    iconLeft={isPaused ? '▶' : '⏸'}
+                    onPress={() => (isPaused ? resume() : pause())}
+                  />
+                ) : null}
+                <Button
+                  title="Stop"
+                  variant="danger"
+                  size="lg"
+                  onPress={stopLive}
+                />
+              </View>
             ) : (
               <Button
                 title="Start listening"
@@ -187,9 +349,83 @@ export default function SpeechToText() {
           </View>
         </View>
 
+        {/* Record-to-file: opt in and choose where to save */}
+        <Card
+          title="Record to file"
+          subtitle="Optionally save the mic audio to a WAV while you stream"
+        >
+          <View style={styles.switchRow}>
+            <Text style={styles.switchLabel}>Save this session to a file</Text>
+            <Switch
+              value={recordEnabled}
+              onValueChange={setRecordEnabled}
+              disabled={sessionActive}
+              thumbColor={recordEnabled ? colors.success : '#888'}
+              trackColor={{
+                false: colors.surfaceMuted,
+                true: colors.accentMuted,
+              }}
+            />
+          </View>
+
+          {recordEnabled ? (
+            <>
+              <OptionSelect
+                label="Destination folder"
+                value={recordFolder}
+                onChange={(v) =>
+                  setRecordFolder(v === 'cache' ? 'cache' : 'documents')
+                }
+                options={[
+                  { label: 'App documents', value: 'documents' },
+                  { label: 'App cache', value: 'cache' },
+                ]}
+              />
+              <Field
+                label="File name"
+                value={recordFileName}
+                onChangeText={setRecordFileName}
+                editable={!sessionActive}
+                autoCapitalize="none"
+                autoCorrect={false}
+                placeholder="deepgram-recording.wav"
+                hint={`Saves to: ${recordPath}`}
+              />
+            </>
+          ) : (
+            <Text style={styles.recordHint}>
+              Off by default — turn this on to keep a copy of the audio. You
+              pick the folder and file name before you start listening.
+            </Text>
+          )}
+        </Card>
+
+        {isReconnecting ? (
+          <View style={styles.reconnectBanner}>
+            <Text style={styles.reconnectText}>
+              ↻ Reconnecting… (attempt {reconnectAttempt})
+            </Text>
+          </View>
+        ) : null}
+
         {liveState?.error ? (
           <View style={styles.errorBanner}>
-            <Text style={styles.errorText}>⚠ {liveState.error.message}</Text>
+            <Text style={styles.errorText}>
+              ⚠{' '}
+              {liveState.error instanceof DeepgramError
+                ? `[${liveState.error.code}] `
+                : ''}
+              {liveState.error.message}
+            </Text>
+          </View>
+        ) : null}
+
+        {recordingUri && !sessionActive ? (
+          <View style={styles.recordingBanner}>
+            <Text style={styles.recordingBannerTitle}>💾 Recording saved</Text>
+            <Text style={styles.recordingBannerPath} numberOfLines={1}>
+              {recordingUri}
+            </Text>
           </View>
         ) : null}
 
@@ -310,6 +546,10 @@ const styles = StyleSheet.create({
     backgroundColor: colors.primary,
     borderColor: colors.primary,
   },
+  micCirclePaused: {
+    backgroundColor: colors.surfaceMuted,
+    borderColor: colors.warning,
+  },
   micIcon: { fontSize: 36 },
   heroTitle: {
     ...type.h2,
@@ -322,7 +562,64 @@ const styles = StyleSheet.create({
     marginBottom: spacing.lg,
     textAlign: 'center',
   },
+  meterTrack: {
+    width: '70%',
+    height: 8,
+    borderRadius: radius.pill,
+    backgroundColor: colors.surfaceMuted,
+    overflow: 'hidden',
+    marginBottom: spacing.lg,
+  },
+  meterFill: {
+    height: '100%',
+    borderRadius: radius.pill,
+    backgroundColor: colors.accent,
+  },
   heroActions: { width: '100%' },
+  heroButtonRow: {
+    flexDirection: 'row',
+    justifyContent: 'center',
+    gap: spacing.md,
+  },
+  capabilityRow: {
+    flexDirection: 'row',
+    flexWrap: 'wrap',
+    justifyContent: 'center',
+    gap: spacing.sm,
+    marginBottom: spacing.lg,
+  },
+  capabilityChip: {
+    paddingHorizontal: spacing.sm,
+    paddingVertical: 5,
+    borderRadius: radius.pill,
+    backgroundColor: colors.surfaceMuted,
+    borderWidth: 1,
+    borderColor: colors.border,
+  },
+  capabilityChipActive: {
+    backgroundColor: colors.accentMuted,
+    borderColor: colors.accent,
+  },
+  capabilityChipText: {
+    ...type.small,
+    color: colors.textMuted,
+    fontSize: 12,
+  },
+  capabilityChipTextActive: {
+    color: colors.accent,
+  },
+  reconnectBanner: {
+    backgroundColor: colors.accentMuted,
+    borderColor: colors.accent,
+    borderWidth: 1,
+    borderRadius: radius.md,
+    padding: spacing.md,
+    marginBottom: spacing.md,
+  },
+  reconnectText: {
+    color: colors.accent,
+    ...type.smallMedium,
+  },
   errorBanner: {
     backgroundColor: '#3a1418',
     borderColor: colors.danger,
@@ -335,6 +632,39 @@ const styles = StyleSheet.create({
     color: colors.danger,
     ...type.smallMedium,
   },
+  recordingBanner: {
+    backgroundColor: '#10241c',
+    borderColor: colors.success,
+    borderWidth: 1,
+    borderRadius: radius.md,
+    padding: spacing.md,
+    marginBottom: spacing.md,
+  },
+  recordingBannerTitle: {
+    color: colors.success,
+    ...type.smallMedium,
+    marginBottom: 2,
+  },
+  recordingBannerPath: {
+    ...type.mono,
+    color: colors.textMuted,
+  },
+  switchRow: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'space-between',
+    marginBottom: spacing.md,
+  },
+  switchLabel: {
+    ...type.body,
+    color: colors.text,
+    flex: 1,
+    marginRight: spacing.md,
+  },
+  recordHint: {
+    ...type.small,
+    color: colors.textDim,
+  },
   transcript: {
     ...type.body,
     color: colors.text,
diff --git a/example/src/TextToSpeech.tsx b/example/src/TextToSpeech.tsx
index 4496abb..33231ec 100644
--- a/example/src/TextToSpeech.tsx
+++ b/example/src/TextToSpeech.tsx
@@ -1,7 +1,17 @@
 import { useMemo, useState } from 'react';
-import { ScrollView, StyleSheet, Switch, Text, View } from 'react-native';
+import {
+  Platform,
+  ScrollView,
+  Share,
+  StyleSheet,
+  Switch,
+  Text,
+  View,
+} from 'react-native';
+import * as FileSystem from 'expo-file-system';
 import {
   useDeepgramTextToSpeech,
+  arrayBufferToBase64,
   type DeepgramTextToSpeechStreamMetadataMessage,
   type DeepgramTextToSpeechStreamWarningMessage,
   type DeepgramTextToSpeechCallbackMethod,
@@ -100,6 +110,39 @@ const parseNumber = (value: string): number | undefined => {
   return Number.isFinite(parsed) ? parsed : undefined;
 };
 
+const extensionForAudio = (
+  mimeType: string,
+  encoding?: string,
+  container?: string
+): string => {
+  const mt = mimeType.toLowerCase();
+  if (mt.includes('mpeg') || mt.includes('mp3')) return 'mp3';
+  if (mt.includes('wav')) return 'wav';
+  if (mt.includes('aac')) return 'aac';
+  if (mt.includes('ogg') || mt.includes('opus')) return 'ogg';
+  if (mt.includes('flac')) return 'flac';
+  if (container === 'wav') return 'wav';
+  if (container === 'ogg') return 'ogg';
+  switch (encoding) {
+    case 'mp3':
+      return 'mp3';
+    case 'aac':
+      return 'aac';
+    case 'opus':
+      return 'ogg';
+    case 'flac':
+      return 'flac';
+    case 'mulaw':
+      return 'ulaw';
+    case 'alaw':
+      return 'alaw';
+    case 'linear16':
+      return 'pcm';
+    default:
+      return 'audio';
+  }
+};
+
 export default function TextToSpeech() {
   const [text, setText] = useState('');
   const [streamText, setStreamText] = useState('');
@@ -116,6 +159,14 @@ export default function TextToSpeech() {
   >([]);
   const [streamAutoFlush, setStreamAutoFlush] = useState(true);
 
+  const [bytesResult, setBytesResult] = useState<{
+    size: number;
+    mimeType: string;
+    ms: number;
+    uri: string;
+  } | null>(null);
+  const [isFetchingBytes, setIsFetchingBytes] = useState(false);
+
   const [httpModel, setHttpModel] = useState('aura-2-asteria-en');
   const [httpEncoding, setHttpEncoding] = useState('linear16');
   const [httpSampleRate, setHttpSampleRate] = useState('16000');
@@ -165,7 +216,11 @@ export default function TextToSpeech() {
     | DeepgramTextToSpeechSampleRate
     | undefined;
 
-  const { synthesize, state: httpState } = useDeepgramTextToSpeech({
+  const {
+    synthesize,
+    synthesizeToBytes,
+    state: httpState,
+  } = useDeepgramTextToSpeech({
     trackState: true,
     options: {
       http: {
@@ -235,6 +290,76 @@ export default function TextToSpeech() {
     }
   };
 
+  const handleSaveToFile = async () => {
+    setIsFetchingBytes(true);
+    try {
+      const startedAt = Date.now();
+      // The in-app HTTP player only decodes linear16 PCM, so this screen
+      // defaults to raw PCM — which has no container and isn't a self-contained
+      // file (you'd get a .pcm most apps can't open). For the export we upgrade
+      // raw PCM to a portable MP3; a real container/codec is saved as-is.
+      const isRawPcm =
+        (!httpEncodingValue ||
+          httpEncodingValue === 'linear16' ||
+          httpEncodingValue === 'mulaw' ||
+          httpEncodingValue === 'alaw') &&
+        httpContainerValue !== 'wav';
+      // synthesizeToBytes returns the audio WITHOUT playing it, so it's the
+      // right call for saving/caching. Identical prompts hit the in-memory LRU.
+      // mp3 takes only encoding + bit_rate (container/sample_rate are N/A).
+      const { data, mimeType } = await synthesizeToBytes(
+        text,
+        isRawPcm
+          ? {
+              encoding: 'mp3',
+              bitRate: 48000,
+              container: undefined,
+              sampleRate: undefined,
+            }
+          : undefined
+      );
+      const ext = extensionForAudio(
+        mimeType,
+        httpEncodingValue,
+        httpContainerValue
+      );
+      const base64 = arrayBufferToBase64(data);
+      const stamp = Date.now();
+      const ms = stamp - startedAt;
+
+      if (Platform.OS === 'android') {
+        // Let the user choose a destination folder via the Storage Access
+        // Framework, then write the bytes into the file they picked.
+        const perm =
+          await FileSystem.StorageAccessFramework.requestDirectoryPermissionsAsync();
+        if (!perm.granted) return;
+        const baseMime = mimeType.split(';')[0] || 'application/octet-stream';
+        const destUri = await FileSystem.StorageAccessFramework.createFileAsync(
+          perm.directoryUri,
+          `deepgram-tts-${stamp}`,
+          baseMime
+        );
+        await FileSystem.writeAsStringAsync(destUri, base64, {
+          encoding: FileSystem.EncodingType.Base64,
+        });
+        setBytesResult({ size: data.byteLength, mimeType, ms, uri: destUri });
+      } else {
+        // iOS: write to a temp file, then open the share sheet so the user can
+        // “Save to Files” (or send it to any app) and choose the location.
+        const tmpUri = `${FileSystem.cacheDirectory}deepgram-tts-${stamp}.${ext}`;
+        await FileSystem.writeAsStringAsync(tmpUri, base64, {
+          encoding: FileSystem.EncodingType.Base64,
+        });
+        setBytesResult({ size: data.byteLength, mimeType, ms, uri: tmpUri });
+        await Share.share({ url: tmpUri });
+      }
+    } catch (err) {
+      console.warn('Save to file failed', err);
+    } finally {
+      setIsFetchingBytes(false);
+    }
+  };
+
   const handleStartStream = async () => {
     try {
       await startStreaming(text);
@@ -298,7 +423,36 @@ export default function TextToSpeech() {
                 iconLeft="🎧"
               />
             )}
+            <Button
+              title="Save to file"
+              variant="ghost"
+              onPress={handleSaveToFile}
+              loading={isFetchingBytes}
+              disabled={isFetchingBytes || !text.trim()}
+              iconLeft="💾"
+            />
           </View>
+          {bytesResult ? (
+            <View style={styles.bytesBanner}>
+              <Text style={styles.bytesTitle}>
+                💾 {bytesResult.size.toLocaleString()} bytes ·{' '}
+                {bytesResult.mimeType}
+              </Text>
+              <Text style={styles.bytesPath} selectable numberOfLines={2}>
+                {bytesResult.uri}
+              </Text>
+              <Text style={styles.bytesHint}>
+                Synthesized in {bytesResult.ms} ms via synthesizeToBytes (no
+                playback).{' '}
+                {bytesResult.mimeType.includes('mpeg')
+                  ? 'Exported as MP3 so it plays anywhere. '
+                  : ''}
+                {Platform.OS === 'ios'
+                  ? 'Pick “Save to Files” in the share sheet to choose where it lands.'
+                  : 'Saved to the folder you selected.'}
+              </Text>
+            </View>
+          ) : null}
           {httpState?.error ? (
             <View style={styles.errorBanner}>
               <Text style={styles.errorText}>⚠ {httpState.error.message}</Text>
@@ -605,6 +759,25 @@ const styles = StyleSheet.create({
     marginTop: spacing.md,
   },
   errorText: { color: colors.danger, ...type.smallMedium },
+  bytesBanner: {
+    backgroundColor: colors.surfaceMuted,
+    borderColor: colors.border,
+    borderWidth: 1,
+    borderRadius: radius.md,
+    padding: spacing.md,
+    marginTop: spacing.md,
+  },
+  bytesTitle: { color: colors.text, ...type.smallMedium },
+  bytesPath: {
+    ...type.small,
+    color: colors.accent,
+    marginTop: 4,
+  },
+  bytesHint: {
+    ...type.small,
+    color: colors.textMuted,
+    marginTop: 4,
+  },
   kvBlock: {},
   kvTitle: {
     ...type.smallMedium,
diff --git a/example/src/VoiceAgent.tsx b/example/src/VoiceAgent.tsx
index ef79fc7..66906dc 100644
--- a/example/src/VoiceAgent.tsx
+++ b/example/src/VoiceAgent.tsx
@@ -10,6 +10,7 @@ import {
 import {
   useDeepgramVoiceAgent,
   createAgentSettings,
+  DeepgramError,
 } from 'react-native-deepgram';
 import OptionSelect from './components/OptionSelect';
 import Button from './components/Button';
@@ -54,6 +55,8 @@ export default function VoiceAgent() {
   const [inputSampleRate, setInputSampleRate] = useState('16000');
   const [temperature, setTemperature] = useState('0.7');
   const [customMessage, setCustomMessage] = useState('');
+  const [reconnectAttempt, setReconnectAttempt] = useState<number | null>(null);
+  const [errorCode, setErrorCode] = useState<string | null>(null);
 
   const agentSettings = useMemo(
     () =>
@@ -82,6 +85,8 @@ export default function VoiceAgent() {
   const {
     connect,
     disconnect,
+    mute,
+    unmute,
     injectUserMessage,
     sendFunctionCallResponse,
     updatePrompt,
@@ -91,6 +96,7 @@ export default function VoiceAgent() {
     state,
     conversation,
     agentStatus,
+    isMuted,
   } = useDeepgramVoiceAgent({
     defaultSettings: agentSettings,
     autoStartMicrophone: autoStartMic,
@@ -98,11 +104,22 @@ export default function VoiceAgent() {
     trackState: true,
     trackConversation: true,
     trackAgentStatus: true,
+    reconnect: { enabled: true },
+    onReconnecting: (attempt) => {
+      setReconnectAttempt(attempt);
+    },
+    onReconnected: () => {
+      setReconnectAttempt(null);
+    },
+    onError: (err) => {
+      setErrorCode(err instanceof DeepgramError ? err.code : 'unknown');
+    },
   });
 
   const connectionState = state?.connectionState ?? 'idle';
   const connecting = connectionState === 'connecting';
   const connected = connectionState === 'connected';
+  const isReconnecting = reconnectAttempt !== null;
   const conversationRef = useRef<ScrollView | null>(null);
 
   // Mic pulse animation
@@ -140,13 +157,18 @@ export default function VoiceAgent() {
 
   const startAgent = async () => {
     try {
+      setReconnectAttempt(null);
+      setErrorCode(null);
       await connect();
     } catch (err) {
       console.error('Start agent failed', err);
     }
   };
 
-  const stopAgent = () => disconnect();
+  const stopAgent = () => {
+    setReconnectAttempt(null);
+    disconnect();
+  };
 
   const sendCustomUserMessage = () => {
     const message = customMessage.trim();
@@ -180,18 +202,26 @@ export default function VoiceAgent() {
 
   const tone = state?.error
     ? 'error'
-    : connecting
+    : isReconnecting
       ? 'connecting'
-      : connected
-        ? 'live'
-        : 'idle';
+      : connecting
+        ? 'connecting'
+        : isMuted
+          ? 'warning'
+          : connected
+            ? 'live'
+            : 'idle';
   const toneLabel = state?.error
     ? 'Error'
-    : connecting
-      ? 'Connecting'
-      : connected
-        ? 'Live'
-        : 'Disconnected';
+    : isReconnecting
+      ? 'Reconnecting'
+      : connecting
+        ? 'Connecting'
+        : isMuted
+          ? 'Muted'
+          : connected
+            ? 'Live'
+            : 'Disconnected';
 
   const pulseScale = pulse.interpolate({
     inputRange: [0, 1],
@@ -244,21 +274,79 @@ export default function VoiceAgent() {
 
           <Text style={styles.heroTitle}>
             {connected
-              ? 'Listening — talk to the agent'
-              : connecting
-                ? 'Connecting…'
-                : 'Voice Agent'}
+              ? isMuted
+                ? 'Muted'
+                : 'Listening — talk to the agent'
+              : isReconnecting
+                ? 'Reconnecting…'
+                : connecting
+                  ? 'Connecting…'
+                  : 'Voice Agent'}
           </Text>
           <Text style={styles.heroSubtitle}>
             {connected
               ? `Model · ${thinkModel}`
-              : 'Configure below and tap Start'}
+              : isReconnecting
+                ? 'Connection dropped — retrying automatically.'
+                : 'Configure below and tap Start'}
           </Text>
 
+          <View style={styles.capabilityRow}>
+            <View
+              style={[
+                styles.capabilityChip,
+                isMuted && styles.capabilityChipActive,
+              ]}
+            >
+              <Text
+                style={[
+                  styles.capabilityChipText,
+                  isMuted && styles.capabilityChipTextActive,
+                ]}
+              >
+                🔇 Mute
+              </Text>
+            </View>
+            <View
+              style={[
+                styles.capabilityChip,
+                isReconnecting && styles.capabilityChipActive,
+              ]}
+            >
+              <Text
+                style={[
+                  styles.capabilityChipText,
+                  isReconnecting && styles.capabilityChipTextActive,
+                ]}
+              >
+                ↻ Auto-reconnect
+              </Text>
+            </View>
+            <View style={styles.capabilityChip}>
+              <Text style={styles.capabilityChipText}>✎ Live updates</Text>
+            </View>
+          </View>
+
           <View style={styles.heroActions}>
             {connected ? (
+              <View style={styles.heroButtonRow}>
+                <Button
+                  title={isMuted ? 'Unmute' : 'Mute'}
+                  variant="secondary"
+                  size="lg"
+                  iconLeft={isMuted ? '🎤' : '🔇'}
+                  onPress={() => (isMuted ? unmute() : mute())}
+                />
+                <Button
+                  title="Disconnect"
+                  variant="danger"
+                  size="lg"
+                  onPress={stopAgent}
+                />
+              </View>
+            ) : isReconnecting ? (
               <Button
-                title="Disconnect"
+                title="Cancel reconnect"
                 variant="danger"
                 size="lg"
                 onPress={stopAgent}
@@ -277,9 +365,20 @@ export default function VoiceAgent() {
           </View>
         </View>
 
+        {isReconnecting ? (
+          <View style={styles.reconnectBanner}>
+            <Text style={styles.reconnectText}>
+              ↻ Reconnecting… (attempt {reconnectAttempt})
+            </Text>
+          </View>
+        ) : null}
+
         {state?.error ? (
           <View style={styles.errorBanner}>
-            <Text style={styles.errorText}>⚠ {state.error}</Text>
+            <Text style={styles.errorText}>
+              ⚠ {errorCode ? `[${errorCode}] ` : ''}
+              {state.error}
+            </Text>
           </View>
         ) : null}
         {state?.warning ? (
@@ -571,6 +670,50 @@ const styles = StyleSheet.create({
     width: '100%',
     alignItems: 'stretch',
   },
+  heroButtonRow: {
+    flexDirection: 'row',
+    justifyContent: 'center',
+    gap: spacing.md,
+  },
+  capabilityRow: {
+    flexDirection: 'row',
+    flexWrap: 'wrap',
+    justifyContent: 'center',
+    gap: spacing.sm,
+    marginBottom: spacing.lg,
+  },
+  capabilityChip: {
+    paddingHorizontal: spacing.sm,
+    paddingVertical: 5,
+    borderRadius: radius.pill,
+    backgroundColor: colors.surfaceMuted,
+    borderWidth: 1,
+    borderColor: colors.border,
+  },
+  capabilityChipActive: {
+    backgroundColor: colors.accentMuted,
+    borderColor: colors.accent,
+  },
+  capabilityChipText: {
+    ...type.small,
+    color: colors.textMuted,
+    fontSize: 12,
+  },
+  capabilityChipTextActive: {
+    color: colors.accent,
+  },
+  reconnectBanner: {
+    backgroundColor: colors.accentMuted,
+    borderColor: colors.accent,
+    borderWidth: 1,
+    borderRadius: radius.md,
+    padding: spacing.md,
+    marginBottom: spacing.md,
+  },
+  reconnectText: {
+    color: colors.accent,
+    ...type.smallMedium,
+  },
   errorBanner: {
     backgroundColor: '#3a1418',
     borderColor: colors.danger,
diff --git a/ios/DGSupport.h b/ios/DGSupport.h
new file mode 100644
index 0000000..fac2ae2
--- /dev/null
+++ b/ios/DGSupport.h
@@ -0,0 +1,77 @@
+#import <AudioToolbox/AudioToolbox.h>
+#import <Foundation/Foundation.h>
+#import <React/RCTBridgeModule.h>
+#import <React/RCTLog.h>
+
+/**
+ * Shared, state-free support for the Deepgram native module: logging macros,
+ * error helpers and the recording-state struct. Kept in one header so the main
+ * implementation and its category files (`Deepgram+AudioSession.mm`,
+ * `Deepgram+Recording.mm`, `Deepgram+Playback.mm`) all share a single copy.
+ */
+
+#define DGNumberBuffers 3
+
+#ifndef DG_ENABLE_DEBUG_LOGS
+#define DG_ENABLE_DEBUG_LOGS 0
+#endif
+
+#if DG_ENABLE_DEBUG_LOGS
+#define DGLogDebug(...) NSLog(__VA_ARGS__)
+#else
+#define DGLogDebug(...)
+#endif
+
+#define DGLogWarn(...) RCTLogWarn(__VA_ARGS__)
+#define DGLogError(...) RCTLogError(__VA_ARGS__)
+
+@class Deepgram;
+
+/** Backing state for the AudioQueue-based microphone capture path. */
+typedef struct {
+  __unsafe_unretained Deepgram *mSelf;
+  AudioStreamBasicDescription dataFormat;
+  AudioQueueRef queue;
+  AudioQueueBufferRef buffers[DGNumberBuffers];
+  UInt32 bufferByteSize;
+  SInt64 currentPacket;
+  bool isRunning;
+} DGRecordState;
+
+/** Build a generic native error with a localized description. */
+static inline NSError *DGNativeError(NSString *domain, NSInteger code,
+                                     NSString *message) {
+  return [NSError errorWithDomain:domain
+                             code:code
+                         userInfo:@{
+                           NSLocalizedDescriptionKey : message
+                               ?: @"Unknown Deepgram native error"
+                         }];
+}
+
+/** Wrap an OSStatus failure from a named CoreAudio operation. */
+static inline NSError *DGOSStatusError(NSString *operation, OSStatus status) {
+  NSString *message = [NSString
+      stringWithFormat:@"%@ failed with OSStatus %d", operation, (int)status];
+  return DGNativeError(NSOSStatusErrorDomain, (NSInteger)status, message);
+}
+
+/**
+ * Reject a promise with a guaranteed-concrete `NSError`. Passing `nil` for the
+ * error synthesizes one so JS never sees a generic "unknown error from native
+ * module" that hides the real cause.
+ */
+static inline void DGRejectPromise(RCTPromiseRejectBlock reject, NSString *code,
+                                   NSString *message, NSError *error) {
+  if (!reject) {
+    return;
+  }
+
+  NSString *safeCode = code ?: @"deepgram_native_error";
+  NSString *safeMessage = message ?: error.localizedDescription
+                              ?: @"Deepgram native error";
+  NSError *safeError =
+      error ?: DGNativeError(@"DeepgramNativeError", 0, safeMessage);
+  DGLogError(@"[Deepgram] reject: code=%@ message=%@", safeCode, safeMessage);
+  reject(safeCode, safeMessage, safeError);
+}
diff --git a/ios/Deepgram+AudioSession.h b/ios/Deepgram+AudioSession.h
new file mode 100644
index 0000000..ad07c1f
--- /dev/null
+++ b/ios/Deepgram+AudioSession.h
@@ -0,0 +1,28 @@
+#import "Deepgram.h"
+
+#import <AVFoundation/AVFoundation.h>
+
+/**
+ * Audio-session lifecycle: activation/deactivation, the category fallback
+ * ladder (sensitive to OSStatus -50) and the route-change / interruption /
+ * media-services-reset notification handlers.
+ */
+@interface Deepgram (AudioSession)
+
+- (BOOL)activateAudioSession:(NSError **)outError;
+- (void)deactivateAudioSession;
+- (BOOL)configureAudioSessionIfNeeded:(NSError **)outError;
+- (BOOL)configureAudioSession:(NSError **)outError;
+- (BOOL)configureAudioSessionForRecording:(BOOL)needsMicrophone
+                                    error:(NSError **)outError;
+- (AVAudioSessionCategoryOptions)bluetoothHFPOption;
+- (BOOL)applyAudioSessionCategory:(AVAudioSessionCategory)category
+                             mode:(NSString *)mode
+                          options:(AVAudioSessionCategoryOptions)options
+                            error:(NSError **)outError;
+- (void)maybeDeactivateAudioSession;
+- (void)handleAudioRouteChange:(NSNotification *)note;
+- (void)handleMediaServicesReset:(NSNotification *)note;
+- (void)handleAudioInterruption:(NSNotification *)note;
+
+@end
diff --git a/ios/Deepgram+AudioSession.mm b/ios/Deepgram+AudioSession.mm
new file mode 100644
index 0000000..26b3098
--- /dev/null
+++ b/ios/Deepgram+AudioSession.mm
@@ -0,0 +1,438 @@
+#import "Deepgram+AudioSession.h"
+#import "Deepgram+Private.h"
+#import "Deepgram+Recording.h"
+
+#import <AVFoundation/AVFoundation.h>
+#import <AudioToolbox/AudioQueue.h>
+
+/**
+ * Audio-session lifecycle for the Deepgram module: activation/deactivation, the
+ * category fallback ladder (which is highly sensitive to OSStatus -50), and the
+ * route-change / interruption / media-services-reset notification handlers.
+ */
+@implementation Deepgram (AudioSession)
+
+- (BOOL)activateAudioSession:(NSError **)outError {
+  DGLogDebug(@"[Deepgram] activateAudioSession: begin (configured=%@)",
+             self.audioSessionConfigured ? @"YES" : @"NO");
+  __block BOOL success = YES;
+  __block NSError *activationError = nil;
+
+  DGLogDebug(@"[Deepgram] activateAudioSession: configuring on current queue");
+  success = [self configureAudioSessionIfNeeded:&activationError];
+
+  if (!success && activationError) {
+    DGLogError(@"[Deepgram] Failed to activate audio session: %@",
+               activationError.localizedDescription ?: activationError);
+  } else {
+    DGLogDebug(@"[Deepgram] activateAudioSession: success=%@",
+               success ? @"YES" : @"NO");
+  }
+
+  if (outError) {
+    *outError = activationError;
+  }
+
+  return success;
+}
+
+- (void)deactivateAudioSession {
+  DGLogDebug(@"[Deepgram] deactivateAudioSession: begin");
+  if (!self.audioSessionConfigured) {
+    DGLogDebug(@"[Deepgram] deactivateAudioSession: skipped (not configured)");
+    return;
+  }
+
+  NSError *error = nil;
+  // Use NotifyOthersOnDeactivation so other audio sessions (expo-av, etc.)
+  // know they can resume.
+  BOOL success = NO;
+  @try {
+    success = [[AVAudioSession sharedInstance]
+                  setActive:NO
+                withOptions:AVAudioSessionSetActiveOptionNotifyOthersOnDeactivation
+                      error:&error];
+  }
+  @catch (NSException *e) {
+    DGLogWarn(@"[Deepgram] deactivateAudioSession threw exception: %@",
+              e.reason ?: e);
+    self.audioSessionConfigured = NO;
+    return;
+  }
+
+  if (!success && error) {
+    // Deactivation can legitimately fail during competing audio-route
+    // transitions; treat as a warning rather than an error.
+    DGLogWarn(@"[Deepgram] Failed to deactivate audio session: %@",
+              error.localizedDescription ?: error);
+  }
+  self.audioSessionConfigured = NO;
+}
+
+- (BOOL)configureAudioSessionIfNeeded:(NSError **)outError
+{
+  BOOL needsMic = _recordState.isRunning || self.audioQueueCaptureRequested ||
+                  self.engineCaptureActive || self.voiceProcessingRequested;
+  AVAudioSession *session = [AVAudioSession sharedInstance];
+
+  if (self.audioSessionConfigured) {
+    BOOL isCurrentlyPlayAndRecord = [session.category isEqualToString:AVAudioSessionCategoryPlayAndRecord];
+    if (isCurrentlyPlayAndRecord == needsMic) {
+      DGLogDebug(@"[Deepgram] configureAudioSessionIfNeeded: already configured correctly, ensuring active");
+      NSError *activeError = nil;
+      BOOL success = [[AVAudioSession sharedInstance] setActive:YES error:&activeError];
+      if (success && !activeError) {
+        return YES;
+      }
+    }
+  }
+
+  DGLogDebug(@"[Deepgram] configureAudioSessionIfNeeded: configuring (needsMic=%@)", needsMic ? @"YES" : @"NO");
+  return [self configureAudioSession:outError];
+}
+
+- (BOOL)configureAudioSession:(NSError **)outError {
+  BOOL needsMic = _recordState.isRunning || self.audioQueueCaptureRequested ||
+                  self.engineCaptureActive || self.voiceProcessingRequested;
+  return [self configureAudioSessionForRecording:needsMic error:outError];
+}
+
+/**
+ * Build the Bluetooth input option appropriate for the running OS.
+ * iOS 17 deprecated `AllowBluetooth` (HFP route) in favor of
+ * `AllowBluetoothHFP`. Prefer the new symbol when building against the iOS
+ * 17+ SDK and fall back to the legacy spelling on older toolchains.
+ */
+- (AVAudioSessionCategoryOptions)bluetoothHFPOption {
+#if defined(__IPHONE_17_0) && (__IPHONE_OS_VERSION_MAX_ALLOWED >= __IPHONE_17_0)
+  if (@available(iOS 17.0, *)) {
+    return AVAudioSessionCategoryOptionAllowBluetoothHFP;
+  }
+#endif
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wdeprecated-declarations"
+  return AVAudioSessionCategoryOptionAllowBluetooth;
+#pragma clang diagnostic pop
+}
+
+/**
+ * Attempt to apply a single category/mode/options tuple and activate the
+ * session. Returns YES on success. On failure, populates `outError` so the
+ * caller can decide whether to try a more conservative configuration.
+ */
+- (BOOL)applyAudioSessionCategory:(AVAudioSessionCategory)category
+                             mode:(NSString *)mode
+                          options:(AVAudioSessionCategoryOptions)options
+                            error:(NSError **)outError {
+  AVAudioSession *session = [AVAudioSession sharedInstance];
+  NSError *error = nil;
+
+  DGLogDebug(@"[Deepgram] configureAudioSession: setCategory %@ mode %@ "
+             @"options 0x%lx",
+             category, mode, (unsigned long)options);
+
+  if (![session setCategory:category
+                       mode:mode
+                    options:options
+                      error:&error] ||
+      error) {
+    DGLogError(@"[Deepgram] configureAudioSession: category failed error=%@",
+               error.localizedDescription ?: error);
+    if (outError) {
+      *outError = error;
+    }
+    return NO;
+  }
+
+  NSError *activeError = nil;
+  if (![session setActive:YES error:&activeError]) {
+    DGLogError(@"[Deepgram] configureAudioSession: setActive failed error=%@",
+               activeError.localizedDescription ?: activeError);
+    if (outError) {
+      *outError = activeError;
+    }
+    return NO;
+  }
+
+  return YES;
+}
+
+/**
+ * Configure audio session with mode appropriate to current usage.
+ *
+ * The configuration is attempted from most- to least-capable. If a richer
+ * setup is rejected we automatically fall back to a simpler one so audio still
+ * works instead of hard-failing.
+ *
+ * Two subtle rules drive the ordering below; getting them wrong yields
+ * OSStatus -50 (kAudioSession/paramErr) on `setCategory`, which then leaves the
+ * session in a half-configured state and makes a later AudioQueueStart fail
+ * with 'what' (kAudioSessionUnspecifiedError):
+ *
+ *   1. `DefaultToSpeaker` forces output to the built-in speaker, while
+ *      `AllowBluetoothA2DP` / `AllowAirPlay` route output to external devices.
+ *      Combining them is contradictory and is rejected with -50, so those
+ *      output-routing options are NEVER mixed with a recording configuration.
+ *      A2DP/AirPlay devices are output-only and can't supply a mic input
+ *      anyway — Bluetooth input uses the HFP route instead.
+ *   2. `MixWithOthers` lets us coexist with other audio packages (expo-av,
+ *      etc.) but can prevent us from acquiring the input on some routes. We try
+ *      it first to be a good citizen, then degrade to exclusive access so
+ *      recording still starts reliably.
+ *
+ * VoiceChat mode (which engages Apple's hardware AEC / VPIO) is used only when
+ * echo cancellation is required and only on a device — VPIO is unavailable on
+ * the Simulator and requesting it there guarantees a -50.
+ */
+- (BOOL)configureAudioSessionForRecording:(BOOL)needsMicrophone
+                                    error:(NSError **)outError {
+  DGLogDebug(@"[Deepgram] configureAudioSession: begin (mic=%@)",
+             needsMicrophone ? @"YES" : @"NO");
+
+  const AVAudioSessionCategoryOptions mixOption =
+      AVAudioSessionCategoryOptionMixWithOthers;
+
+  // Build an ordered list of attempts, best first.
+  NSMutableArray<NSDictionary *> *attempts = [NSMutableArray array];
+
+  if (needsMicrophone) {
+    BOOL needsAEC = self.engineCaptureActive || self.voiceProcessingRequested ||
+                    self.isPlaying;
+
+    // Input-safe options for PlayAndRecord. DefaultToSpeaker + HFP are valid
+    // here; A2DP/AirPlay are intentionally excluded (see rule 1 above).
+    AVAudioSessionCategoryOptions recordOptions =
+        AVAudioSessionCategoryOptionDefaultToSpeaker | [self bluetoothHFPOption];
+
+#if !TARGET_OS_SIMULATOR
+    // Preferred: hardware AEC via VoiceChat (device only). VoiceChat mode
+    // manages the route itself, so DefaultToSpeaker / HFP must NOT be combined
+    // with it — doing so is rejected with -50 on some iOS versions. Only
+    // MixWithOthers is safe to layer on top.
+    if (needsAEC) {
+      [attempts addObject:@{
+        @"category" : AVAudioSessionCategoryPlayAndRecord,
+        @"mode" : AVAudioSessionModeVoiceChat,
+        @"options" : @(mixOption),
+      }];
+      [attempts addObject:@{
+        @"category" : AVAudioSessionCategoryPlayAndRecord,
+        @"mode" : AVAudioSessionModeVoiceChat,
+        @"options" : @(0),
+      }];
+    }
+#endif
+
+    // PlayAndRecord without VoiceChat (no hardware AEC). Try with MixWithOthers
+    // first to coexist with other packages, then exclusively.
+    [attempts addObject:@{
+      @"category" : AVAudioSessionCategoryPlayAndRecord,
+      @"mode" : AVAudioSessionModeDefault,
+      @"options" : @(recordOptions | mixOption),
+    }];
+    [attempts addObject:@{
+      @"category" : AVAudioSessionCategoryPlayAndRecord,
+      @"mode" : AVAudioSessionModeDefault,
+      @"options" : @(recordOptions),
+    }];
+
+    // Last resort: bare PlayAndRecord with no options. Always valid.
+    [attempts addObject:@{
+      @"category" : AVAudioSessionCategoryPlayAndRecord,
+      @"mode" : AVAudioSessionModeDefault,
+      @"options" : @(0),
+    }];
+  } else {
+    // Playback already supports AirPlay and A2DP routes; the explicit route
+    // options are for PlayAndRecord and can be rejected with OSStatus -50.
+    AVAudioSessionCategoryOptions playbackOptions = mixOption;
+    [attempts addObject:@{
+      @"category" : AVAudioSessionCategoryPlayback,
+      @"mode" : AVAudioSessionModeDefault,
+      @"options" : @(playbackOptions),
+    }];
+
+    // Last resort: bare Playback with no options.
+    [attempts addObject:@{
+      @"category" : AVAudioSessionCategoryPlayback,
+      @"mode" : AVAudioSessionModeDefault,
+      @"options" : @(0),
+    }];
+  }
+
+  NSError *lastError = nil;
+  NSUInteger attemptIndex = 0;
+  for (NSDictionary *attempt in attempts) {
+    attemptIndex++;
+    NSError *attemptError = nil;
+    BOOL success = [self
+        applyAudioSessionCategory:attempt[@"category"]
+                             mode:attempt[@"mode"]
+                          options:(AVAudioSessionCategoryOptions)
+                                      [attempt[@"options"] unsignedIntegerValue]
+                            error:&attemptError];
+    if (success) {
+      if (attemptIndex > 1) {
+        DGLogDebug(@"[Deepgram] configureAudioSession: succeeded on fallback "
+                   @"attempt %lu/%lu",
+                   (unsigned long)attemptIndex, (unsigned long)attempts.count);
+      }
+      self.audioSessionConfigured = YES;
+      DGLogDebug(@"[Deepgram] configureAudioSession: success");
+      return YES;
+    }
+    lastError = attemptError;
+    DGLogDebug(@"[Deepgram] configureAudioSession: attempt %lu/%lu failed, "
+               @"trying next configuration",
+               (unsigned long)attemptIndex, (unsigned long)attempts.count);
+  }
+
+  DGLogError(@"[Deepgram] configureAudioSession: all %lu configurations failed; "
+             @"last error=%@",
+             (unsigned long)attempts.count,
+             lastError.localizedDescription ?: lastError);
+  if (outError) {
+    *outError = lastError;
+  }
+  self.audioSessionConfigured = NO;
+  return NO;
+}
+
+- (void)maybeDeactivateAudioSession {
+  DGLogDebug(@"[Deepgram] maybeDeactivateAudioSession: running=%@ playing=%@ "
+             @"engineCapture=%@",
+             _recordState.isRunning ? @"YES" : @"NO",
+             self.isPlaying ? @"YES" : @"NO",
+             self.engineCaptureActive ? @"YES" : @"NO");
+  if (!_recordState.isRunning && !self.isPlaying && !self.engineCaptureActive) {
+    DGLogDebug(@"[Deepgram] maybeDeactivateAudioSession: deactivating");
+    [self deactivateAudioSession];
+  }
+}
+
+- (void)handleAudioRouteChange:(NSNotification *)note {
+  DGLogDebug(@"[Deepgram] handleAudioRouteChange: %@", note.userInfo);
+  NSNumber *reasonValue = note.userInfo[AVAudioSessionRouteChangeReasonKey];
+  AVAudioSessionRouteChangeReason reason =
+      reasonValue
+          ? (AVAudioSessionRouteChangeReason)reasonValue.unsignedIntegerValue
+          : AVAudioSessionRouteChangeReasonUnknown;
+
+  // Headphones / Bluetooth headset unplugged — pause playback so we don't
+  // surprise the user by suddenly blasting through the loud speaker.
+  // (System would route audio to the speaker automatically; that's the point
+  // of this notification.) Matches expo-audio behavior and Apple's guidance.
+  if (reason == AVAudioSessionRouteChangeReasonOldDeviceUnavailable) {
+    DGLogDebug(@"[Deepgram] handleAudioRouteChange: old device unavailable — "
+               @"pausing playback");
+    if (self.isPlaying && self.playerNode) {
+      [self.playerNode pause];
+    }
+  }
+
+  BOOL causedByCategory =
+      reason == AVAudioSessionRouteChangeReasonCategoryChange ||
+      reason == AVAudioSessionRouteChangeReasonNoSuitableRouteForCategory;
+
+  if (!causedByCategory) {
+    self.audioSessionConfigured = NO;
+  }
+
+  if (!_recordState.isRunning && !self.isPlaying) {
+    DGLogDebug(@"[Deepgram] handleAudioRouteChange: ignoring (inactive)");
+    return;
+  }
+
+  if (!self.appIsActive) {
+    DGLogDebug(@"[Deepgram] handleAudioRouteChange: app inactive, skipping");
+    return;
+  }
+
+  if (causedByCategory) {
+    DGLogDebug(@"[Deepgram] handleAudioRouteChange: category change detected, "
+               @"keeping session");
+    return;
+  }
+
+  DGLogDebug(@"[Deepgram] handleAudioRouteChange: reactivating session");
+  [self activateAudioSession:NULL];
+}
+
+// AVAudioSession can post this when mediaserverd restarts (e.g. after a
+// rare system audio HAL hiccup). Once it fires, every AudioQueue /
+// AVAudioEngine instance becomes a zombie. Apple's documented fix is to throw
+// everything away and rebuild on demand. Match expo-audio's approach.
+- (void)handleMediaServicesReset:(NSNotification *)note {
+  DGLogDebug(@"[Deepgram] handleMediaServicesReset: tearing down audio stack");
+  self.audioSessionConfigured = NO;
+
+  // Recording queue must be torn down — it's a zombie after a media services
+  // reset.
+  if (_recordState.isRunning || _recordState.queue) {
+    [self cleanupRecordingQueue];
+  }
+
+  // Engine-based capture path also dies with mediaserverd; force a full
+  // teardown so the next startRecording rebuilds VPIO from scratch.
+  self.engineCaptureActive = NO;
+  self.captureConverter = nil;
+  self.captureOutputFormat = nil;
+
+  // AVAudioEngine + player node are no longer valid. Stop and discard so the
+  // next setup call rebuilds from scratch.
+  @try {
+    if (self.playerNode) {
+      [self.playerNode stop];
+    }
+    if (self.audioEngine) {
+      [self.audioEngine stop];
+    }
+  } @catch (NSException *e) {
+    DGLogError(@"[Deepgram] handleMediaServicesReset: teardown exception %@",
+               e);
+  }
+  self.playerNode = nil;
+  self.audioEngine = nil;
+  self.isPlaying = NO;
+}
+
+- (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];
+      }
+    }
+  }
+}
+
+@end
diff --git a/ios/Deepgram+Playback.h b/ios/Deepgram+Playback.h
new file mode 100644
index 0000000..850bf57
--- /dev/null
+++ b/ios/Deepgram+Playback.h
@@ -0,0 +1,21 @@
+#import "Deepgram.h"
+
+#import <AVFoundation/AVFoundation.h>
+
+/**
+ * TTS / Voice Agent audio output through an `AVAudioPlayerNode` on the shared
+ * `AVAudioEngine`. When voice processing is requested the same engine drives
+ * both output and capture so the VPIO Audio Unit can cancel our own output out
+ * of the captured input (hardware echo cancellation).
+ */
+@interface Deepgram (Playback)
+
+- (void)stopAndDetachPlayerNode;
+- (void)interruptPlayerPlayback;
+- (BOOL)setupAudioEngineWithSampleRate:(int)sampleRate
+                              channels:(int)channels
+                 enableVoiceProcessing:(BOOL)enableVoiceProcessing
+                                 error:(NSError **)outError;
+- (AVAudioPCMBuffer *)createPCMBufferFromData:(NSData *)data;
+
+@end
diff --git a/ios/Deepgram+Playback.mm b/ios/Deepgram+Playback.mm
new file mode 100644
index 0000000..30e9aa3
--- /dev/null
+++ b/ios/Deepgram+Playback.mm
@@ -0,0 +1,211 @@
+#import "Deepgram+Playback.h"
+#import "Deepgram+Private.h"
+
+#import <AVFoundation/AVFoundation.h>
+
+#include <string.h>
+
+/**
+ * TTS / Voice Agent audio output for the Deepgram module. Playback runs through
+ * an `AVAudioPlayerNode` on a shared `AVAudioEngine`. When voice processing is
+ * requested the same engine drives both output and microphone capture so the
+ * VPIO Audio Unit can cancel our own output out of the captured input
+ * (hardware echo cancellation).
+ */
+@implementation Deepgram (Playback)
+
+/* ================================================================== */
+/*  2.  AVAUDIOENGINE PLAYBACK WITH VOICE PROCESSING (ECHO CANCEL)    */
+/* ================================================================== */
+
+/**
+ * Setup AVAudioEngine for output. When `enableVoiceProcessing` is YES we also
+ * configure the input node for hardware echo cancellation (Voice Agent /
+ * duplex use case). When NO (pure TTS playback), we deliberately avoid
+ * touching `inputNode` so we don't request the microphone or interfere with
+ * other audio libraries.
+ */
+- (void)stopAndDetachPlayerNode {
+  if (self.playerNode) {
+    _playbackGeneration.fetch_add(1);
+
+    @try {
+      [self.playerNode stop];
+    } @catch (NSException *e) {
+      DGLogWarn(@"[Deepgram] playerNode stop exception: %@", e);
+    }
+
+    if (self.audioEngine) {
+      @try {
+        [self.audioEngine detachNode:self.playerNode];
+      } @catch (NSException *e) {
+        DGLogWarn(@"[Deepgram] playerNode detach exception: %@", e);
+      }
+    }
+  }
+
+  self.playerNode = nil;
+  self.playbackFormat = nil;
+  self.isPlaying = NO;
+  _scheduledBufferCount = 0;
+}
+
+- (void)interruptPlayerPlayback {
+  if (self.playerNode) {
+    _playbackGeneration.fetch_add(1);
+
+    @try {
+      [self.playerNode stop];
+    } @catch (NSException *e) {
+      DGLogWarn(@"[Deepgram] playerNode interrupt exception: %@", e);
+    }
+  }
+
+  self.isPlaying = NO;
+  _scheduledBufferCount = 0;
+}
+
+- (BOOL)setupAudioEngineWithSampleRate:(int)sampleRate
+                              channels:(int)channels
+                 enableVoiceProcessing:(BOOL)enableVoiceProcessing
+                                 error:(NSError **)outError {
+  BOOL reuseCaptureEngine = self.audioEngine && self.engineCaptureActive;
+
+  if (self.audioEngine && self.audioEngine.isRunning) {
+    [self.audioEngine stop];
+  }
+
+  [self stopAndDetachPlayerNode];
+
+  if (!reuseCaptureEngine) {
+    if (self.audioEngine) {
+      [self.audioEngine reset];
+    }
+    self.audioEngine = [[AVAudioEngine alloc] init];
+  }
+
+  if (!self.audioEngine) {
+    self.audioEngine = [[AVAudioEngine alloc] init];
+  }
+
+  self.playerNode = [[AVAudioPlayerNode alloc] init];
+
+  self.playbackFormat =
+      [[AVAudioFormat alloc] initWithCommonFormat:AVAudioPCMFormatInt16
+                                       sampleRate:sampleRate
+                                         channels:channels
+                                      interleaved:YES];
+
+  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];
+
+  if (enableVoiceProcessing) {
+#if TARGET_IPHONE_SIMULATOR
+    // VPIO is not implemented on the simulator. Calling
+    // setVoiceProcessingEnabled:YES there raises an internal AVAEInternal
+    // exception about IsFormatSampleRateAndChannelCountValid because the
+    // simulator's input node cannot satisfy the VPIO format constraints.
+    // Skip VP entirely; AEC has to be tested on a physical device.
+    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.");
+#else
+    @try {
+      AVAudioInputNode *inputNode = self.audioEngine.inputNode;
+      AVAudioOutputNode *outputNode = self.audioEngine.outputNode;
+      // Apple's hardware AEC (VPIO Audio Unit) only engages when *both*
+      // input and output flow through a voice-processing-enabled audio
+      // unit. Enabling VP only on the input node is a no-op for capture
+      // unless rendering goes through the same unit, so we enable both.
+      if (inputNode) {
+        NSError *voiceProcessingError = nil;
+        if (![inputNode setVoiceProcessingEnabled:YES
+                                            error:&voiceProcessingError]) {
+          DGLogWarn(@"[Deepgram] inputNode VP enable failed: %@",
+                    voiceProcessingError);
+        }
+      }
+      if (outputNode) {
+        NSError *voiceProcessingError = nil;
+        if (![outputNode setVoiceProcessingEnabled:YES
+                                             error:&voiceProcessingError]) {
+          DGLogWarn(@"[Deepgram] outputNode VP enable failed: %@",
+                    voiceProcessingError);
+        }
+      }
+    } @catch (NSException *exception) {
+      // Continue - voice processing not critical for basic playback
+      DGLogWarn(@"[Deepgram] VP enable threw: %@", exception);
+    }
+#endif
+  }
+
+  [self.audioEngine prepare];
+  NSError *startError = nil;
+  BOOL started = [self.audioEngine startAndReturnError:&startError];
+
+  if (!started) {
+    DGLogError(@"[Deepgram] Failed to start audio engine: %@",
+               startError.localizedDescription);
+    if (outError) {
+      *outError = startError;
+    }
+    return NO;
+  }
+
+  return YES;
+}
+
+/**
+ * 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 ? (int)asbd->mBytesPerFrame : 0;
+  if (bytesPerFrame <= 0) {
+    return nil;
+  }
+  AVAudioFrameCount frameCount =
+      (AVAudioFrameCount)(data.length / bytesPerFrame);
+
+  if (frameCount == 0) {
+    return nil;
+  }
+
+  AVAudioPCMBuffer *buffer =
+      [[AVAudioPCMBuffer alloc] initWithPCMFormat:self.playbackFormat
+                                    frameCapacity:frameCount];
+
+  buffer.frameLength = frameCount;
+
+  // Copy only whole frames. `data.length` may not be an exact multiple of
+  // bytesPerFrame (e.g. a truncated network chunk); copying the raw length
+  // would write past the buffer, which is sized for `frameCount` frames.
+  NSUInteger usableBytes = (NSUInteger)frameCount * (NSUInteger)bytesPerFrame;
+  memcpy(buffer.int16ChannelData[0], data.bytes, usableBytes);
+
+  return buffer;
+}
+
+@end
diff --git a/ios/Deepgram+Private.h b/ios/Deepgram+Private.h
new file mode 100644
index 0000000..a60fe45
--- /dev/null
+++ b/ios/Deepgram+Private.h
@@ -0,0 +1,85 @@
+#import "DGSupport.h"
+#import "Deepgram.h"
+
+#import <AVFoundation/AVFoundation.h>
+#import <AudioToolbox/AudioQueue.h>
+#import <React/RCTEventEmitter.h>
+
+#include <atomic>
+
+/**
+ * Shared instance state for the `Deepgram` module. The class is deliberately
+ * kept as a single unit (rather than split into collaborator objects) because
+ * the audio session, the `AVAudioEngine` and the record/playback state are
+ * mutually dependent — the session configuration, for example, has to reason
+ * about recording and playback at the same time.
+ *
+ * Behaviour is split across category files for readability; each declares its
+ * own methods in a matching category header:
+ *   - Deepgram+AudioSession.h / .mm : audio session lifecycle
+ *   - Deepgram+Recording.h    / .mm : microphone capture
+ *   - Deepgram+Playback.h     / .mm : TTS / Voice Agent playback
+ *
+ * Only the shared state lives here, in a class extension, so it auto-synthesizes
+ * in the primary `@implementation` while remaining visible to every category.
+ */
+@interface Deepgram () {
+@protected
+  DGRecordState _recordState;
+  std::atomic<int> _scheduledBufferCount;
+  std::atomic<int> _playbackGeneration;
+}
+
+// Recording
+@property(nonatomic, strong) NSMutableData *pendingPCMBuffer;
+@property(nonatomic, strong) dispatch_queue_t emitterQueue;
+@property(nonatomic, assign) NSUInteger chunkSizeBytes;
+@property(atomic, assign) BOOL hasListeners;
+@property(atomic, assign) BOOL appIsActive;
+
+// Microphone metering (audio-level events). Purely additive — when
+// `meteringEnabled` is YES the recording sink computes a normalized RMS
+// amplitude (0..1) and emits a `DeepgramAudioLevel` event at most once per
+// `meteringIntervalSeconds`. `lastMeterEmitTime` is a CACurrentMediaTime()
+// timestamp used to throttle emission.
+@property(atomic, assign) BOOL meteringEnabled;
+@property(atomic, assign) NSTimeInterval meteringIntervalSeconds;
+@property(atomic, assign) NSTimeInterval lastMeterEmitTime;
+
+// Record-to-file. When `recordToFileEnabled` is YES the shared
+// capture sink tees every captured 16 kHz PCM16 mono buffer into a WAV file
+// alongside the live Deepgram stream. The RIFF/`data` sizes (and the final
+// sample rate) are patched into the 44-byte header when recording stops.
+// Writes happen on the capture thread (single producer); finalization runs
+// after the capture queue/engine has been stopped, so no lock is required.
+@property(nonatomic, strong) NSFileHandle *recordFileHandle;
+@property(nonatomic, copy) NSString *recordFilePath;
+@property(atomic, assign) BOOL recordToFileEnabled;
+@property(atomic, assign) unsigned long long recordFileDataBytes;
+
+// Playback / TTS (AVAudioEngine-based with echo cancellation)
+@property(nonatomic, strong) AVAudioEngine *audioEngine;
+@property(nonatomic, strong) AVAudioPlayerNode *playerNode;
+@property(nonatomic, strong) AVAudioFormat *playbackFormat;
+@property(atomic, assign) BOOL isPlaying;
+@property(atomic, assign) int currentSampleRate;
+@property(nonatomic, assign) BOOL audioSessionConfigured;
+// YES while we're capturing the microphone through `audioEngine.inputNode`
+// (Voice Agent / duplex). When YES, the AudioQueue path is bypassed and the
+// session must use VoiceChat mode so Apple's Voice-Processing I/O Audio Unit
+// engages and performs hardware echo cancellation.
+@property(atomic, assign) BOOL engineCaptureActive;
+@property(atomic, assign) BOOL voiceProcessingRequested;
+@property(atomic, assign) BOOL audioQueueCaptureRequested;
+@property(nonatomic, strong) AVAudioConverter *captureConverter;
+@property(nonatomic, strong) AVAudioFormat *captureOutputFormat;
+
+// Exported workers implemented in Deepgram.mm (via RCT_EXPORT_METHOD) but
+// invoked from other methods before their textual definition. Declared here so
+// those call sites don't trip -Wundeclared-selector.
+- (void)startPlayer:(nonnull NSNumber *)sampleRate
+           channels:(nonnull NSNumber *)channels;
+- (void)stopPlayer:(nullable RCTPromiseResolveBlock)resolve
+          rejecter:(nullable RCTPromiseRejectBlock)reject;
+
+@end
diff --git a/ios/Deepgram+Recording.h b/ios/Deepgram+Recording.h
new file mode 100644
index 0000000..bc7d5ed
--- /dev/null
+++ b/ios/Deepgram+Recording.h
@@ -0,0 +1,36 @@
+#import "DGSupport.h"
+#import "Deepgram.h"
+
+#import <AudioToolbox/AudioQueue.h>
+#import <Foundation/Foundation.h>
+
+/**
+ * Microphone capture. Two capture paths live in the implementation: the
+ * AudioQueue path (STT-only, no echo cancellation) and the `AVAudioEngine`
+ * path (Voice Agent / duplex, with VPIO hardware AEC).
+ */
+@interface Deepgram (Recording)
+
+- (void)emitPCMChunk:(NSData *)chunk sampleRate:(int)sampleRate;
+- (void)appendPCMDataAndEmitIfNeeded:(NSData *)pcmData;
+- (void)flushPendingPCM;
+- (void)cleanupRecordingQueue;
+- (BOOL)startEngineCaptureAndReturnError:(NSError **)outError;
+- (void)stopEngineCapture;
+
+- (BOOL)beginRecordingToFileIfRequested:(nullable NSDictionary *)options
+                                  error:(NSError *_Nullable *_Nullable)outError;
+- (nullable NSString *)finishRecordingToFile;
+- (void)discardRecordingFile;
+
+@end
+
+/**
+ * AudioQueue input callback. Defined in `Deepgram+Recording.mm`; referenced by
+ * `startRecording` in `Deepgram.mm`, so it must have external linkage.
+ */
+extern void DGHandleInputBuffer(void *inUserData, AudioQueueRef inAQ,
+                                AudioQueueBufferRef inBuffer,
+                                const AudioTimeStamp *inStartTime,
+                                UInt32 inNumPackets,
+                                const AudioStreamPacketDescription *inPacketDesc);
diff --git a/ios/Deepgram+Recording.mm b/ios/Deepgram+Recording.mm
new file mode 100644
index 0000000..85938d4
--- /dev/null
+++ b/ios/Deepgram+Recording.mm
@@ -0,0 +1,647 @@
+#import "Deepgram+Recording.h"
+#import "Deepgram+AudioSession.h"
+#import "Deepgram+Playback.h"
+#import "Deepgram+Private.h"
+
+#import <AVFoundation/AVFoundation.h>
+#import <AudioToolbox/AudioQueue.h>
+
+#include <math.h>
+#include <string.h>
+
+/**
+ * Microphone capture for the Deepgram module. Two capture paths share this
+ * file:
+ *
+ *   - The AudioQueue path (`DGHandleInputBuffer` + `cleanupRecordingQueue`),
+ *     used for STT-only recording where hardware echo cancellation is not
+ *     wanted.
+ *   - The `AVAudioEngine` path (`startEngineCaptureAndReturnError:`), used for
+ *     Voice Agent / duplex where VPIO hardware AEC is required. It shares the
+ *     same `AVAudioEngine` instance as playback so the Voice-Processing I/O
+ *     unit can cancel our own output from the captured input.
+ */
+
+void DGHandleInputBuffer(
+    void *inUserData, __unused AudioQueueRef inAQ, AudioQueueBufferRef inBuffer,
+    __unused const AudioTimeStamp *inStartTime, __unused UInt32 inNumPackets,
+    __unused const AudioStreamPacketDescription *inPacketDesc) {
+  @autoreleasepool {
+    DGRecordState *state = (DGRecordState *)inUserData;
+    if (!state || !state->isRunning) {
+      DGLogDebug(@"[Deepgram] DGHandleInputBuffer: inactive state");
+      return;
+    }
+
+    Deepgram *strongSelf = state->mSelf;
+    if (!strongSelf) {
+      DGLogDebug(@"[Deepgram] DGHandleInputBuffer: missing self");
+      return;
+    }
+
+    if (!inBuffer || inBuffer->mAudioDataByteSize == 0) {
+      DGLogDebug(@"[Deepgram] DGHandleInputBuffer: empty buffer");
+      return;
+    }
+
+    DGLogDebug(@"[Deepgram] DGHandleInputBuffer: received %u bytes",
+               (unsigned int)inBuffer->mAudioDataByteSize);
+    NSData *data = [NSData dataWithBytes:inBuffer->mAudioData
+                                  length:inBuffer->mAudioDataByteSize];
+    [strongSelf appendPCMDataAndEmitIfNeeded:data];
+
+    if (state->queue) {
+      DGLogDebug(@"[Deepgram] DGHandleInputBuffer: re-enqueue buffer");
+      AudioQueueEnqueueBuffer(state->queue, inBuffer, 0, NULL);
+    }
+  }
+}
+
+/**
+ * Build a canonical 44-byte little-endian WAV/RIFF header for `dataBytes` of
+ * uncompressed PCM. Apple platforms are little-endian so the integer fields are
+ * written directly. Used both for the placeholder header (dataBytes = 0) and to
+ * patch the real sizes when recording stops.
+ */
+static NSData *DGMakeWavHeader(uint32_t sampleRate, uint16_t channels,
+                               uint16_t bitsPerSample, uint32_t dataBytes) {
+  uint32_t byteRate = sampleRate * channels * (bitsPerSample / 8);
+  uint16_t blockAlign = (uint16_t)(channels * (bitsPerSample / 8));
+  uint32_t chunkSize = 36 + dataBytes;
+  uint32_t subchunk1Size = 16;
+  uint16_t audioFormat = 1; // PCM
+
+  NSMutableData *header = [NSMutableData dataWithCapacity:44];
+  [header appendBytes:"RIFF" length:4];
+  [header appendBytes:&chunkSize length:4];
+  [header appendBytes:"WAVE" length:4];
+  [header appendBytes:"fmt " length:4];
+  [header appendBytes:&subchunk1Size length:4];
+  [header appendBytes:&audioFormat length:2];
+  [header appendBytes:&channels length:2];
+  [header appendBytes:&sampleRate length:4];
+  [header appendBytes:&byteRate length:4];
+  [header appendBytes:&blockAlign length:2];
+  [header appendBytes:&bitsPerSample length:2];
+  [header appendBytes:"data" length:4];
+  [header appendBytes:&dataBytes length:4];
+  return header;
+}
+
+@implementation Deepgram (Recording)
+
+- (void)emitPCMChunk:(NSData *)chunk sampleRate:(int)sampleRate {
+  if (!chunk || chunk.length == 0) {
+    DGLogDebug(@"[Deepgram] emitPCMChunk: empty chunk, skipping");
+    return;
+  }
+
+  __weak __typeof(self) weakSelf = self;
+  NSData *chunkCopy = [chunk copy];
+  dispatch_queue_t queue = self.emitterQueue ?: dispatch_get_main_queue();
+  dispatch_async(queue, ^{
+    if (!weakSelf) {
+      DGLogDebug(@"[Deepgram] emitPCMChunk: self released, aborting");
+      return;
+    }
+
+    if (!weakSelf.hasListeners) {
+      DGLogDebug(@"[Deepgram] emitPCMChunk: no listeners, dropping %lu bytes",
+                 (unsigned long)chunkCopy.length);
+      return;
+    }
+
+    if (!weakSelf.bridge || !weakSelf.callableJSModules) {
+      DGLogDebug(
+          @"[Deepgram] Skipping DeepgramAudioPCM event (bridge not ready)");
+      return;
+    }
+
+    DGLogDebug(@"[Deepgram] emitPCMChunk: sending %lu bytes sampleRate=%d",
+               (unsigned long)chunkCopy.length, sampleRate);
+    NSString *b64 = [chunkCopy base64EncodedStringWithOptions:0];
+    [weakSelf sendEventWithName:@"DeepgramAudioPCM"
+                           body:@{
+                             @"b64" : b64,
+                             @"sampleRate" : @(sampleRate)
+                           }];
+  });
+}
+
+/**
+ * Compute a normalized RMS amplitude (0..1) over a PCM16 buffer and emit it as
+ * a `DeepgramAudioLevel` event, throttled to `meteringIntervalSeconds`. No-op
+ * unless metering is enabled and JS listeners are attached. Called from the
+ * shared capture sink so both the AudioQueue (STT) and AVAudioEngine (Voice
+ * Agent) paths are metered with identical semantics.
+ */
+- (void)emitAudioLevelForPCM:(NSData *)pcmData {
+  if (!self.meteringEnabled || !self.hasListeners) {
+    return;
+  }
+  if (!pcmData || pcmData.length < sizeof(int16_t)) {
+    return;
+  }
+
+  // Throttle to the configured interval (default ~100 ms / 10 Hz).
+  NSTimeInterval now = [NSProcessInfo processInfo].systemUptime;
+  NSTimeInterval interval =
+      self.meteringIntervalSeconds > 0 ? self.meteringIntervalSeconds : 0.1;
+  NSTimeInterval last = self.lastMeterEmitTime;
+  if (last > 0 && (now - last) < interval) {
+    return;
+  }
+  self.lastMeterEmitTime = now;
+
+  const int16_t *samples = (const int16_t *)pcmData.bytes;
+  NSUInteger count = pcmData.length / sizeof(int16_t);
+  if (count == 0) {
+    return;
+  }
+
+  double sumSquares = 0.0;
+  for (NSUInteger i = 0; i < count; i++) {
+    double s = (double)samples[i] / 32768.0;
+    sumSquares += s * s;
+  }
+  double level = sqrt(sumSquares / (double)count);
+  if (level > 1.0) {
+    level = 1.0;
+  }
+
+  __weak __typeof(self) weakSelf = self;
+  dispatch_queue_t queue = self.emitterQueue ?: dispatch_get_main_queue();
+  dispatch_async(queue, ^{
+    __typeof(self) strongSelf = weakSelf;
+    if (!strongSelf || !strongSelf.hasListeners) {
+      return;
+    }
+    if (!strongSelf.bridge || !strongSelf.callableJSModules) {
+      return;
+    }
+    [strongSelf sendEventWithName:@"DeepgramAudioLevel"
+                             body:@{@"level" : @(level)}];
+  });
+}
+
+- (void)appendPCMDataAndEmitIfNeeded:(NSData *)pcmData {
+  if (!pcmData || pcmData.length == 0) {
+    DGLogDebug(@"[Deepgram] appendPCMDataAndEmitIfNeeded: empty PCM, skipping");
+    return;
+  }
+
+  // Audio-level metering is computed on the same captured PCM that feeds the
+  // transcription stream, so it reflects exactly what Deepgram receives. It is
+  // throttled and gated independently and never alters the PCM payload.
+  [self emitAudioLevelForPCM:pcmData];
+
+  // Tee the captured PCM to the WAV file. On a write failure (e.g. disk full)
+  // we stop teeing but keep streaming so transcription is unaffected.
+  if (self.recordToFileEnabled && self.recordFileHandle) {
+    @try {
+      [self.recordFileHandle writeData:pcmData];
+      self.recordFileDataBytes += (unsigned long long)pcmData.length;
+    } @catch (NSException *e) {
+      DGLogWarn(
+          @"[Deepgram] appendPCMDataAndEmitIfNeeded: file write failed %@", e);
+      self.recordToFileEnabled = NO;
+    }
+  }
+
+  if (!self.pendingPCMBuffer) {
+    DGLogDebug(
+        @"[Deepgram] appendPCMDataAndEmitIfNeeded: allocate pending buffer");
+    self.pendingPCMBuffer = [[NSMutableData alloc] init];
+  }
+
+  DGLogDebug(@"[Deepgram] appendPCMDataAndEmitIfNeeded: append %lu bytes "
+             @"(pending=%lu)",
+             (unsigned long)pcmData.length,
+             (unsigned long)self.pendingPCMBuffer.length);
+  [self.pendingPCMBuffer appendData:pcmData];
+
+  NSUInteger chunkSize =
+      self.chunkSizeBytes > 0 ? self.chunkSizeBytes : pcmData.length;
+
+  while (self.pendingPCMBuffer.length >= chunkSize) {
+    NSData *chunk =
+        [self.pendingPCMBuffer subdataWithRange:NSMakeRange(0, chunkSize)];
+    [self.pendingPCMBuffer replaceBytesInRange:NSMakeRange(0, chunkSize)
+                                     withBytes:NULL
+                                        length:0];
+    DGLogDebug(@"[Deepgram] appendPCMDataAndEmitIfNeeded: emitting chunk %lu "
+               @"bytes remaining=%lu",
+               (unsigned long)chunk.length,
+               (unsigned long)self.pendingPCMBuffer.length);
+    [self emitPCMChunk:chunk sampleRate:self.currentSampleRate];
+  }
+}
+
+- (void)flushPendingPCM {
+  if (self.pendingPCMBuffer.length == 0) {
+    DGLogDebug(@"[Deepgram] flushPendingPCM: nothing to flush");
+    return;
+  }
+
+  NSData *remaining = [self.pendingPCMBuffer copy];
+  [self.pendingPCMBuffer setLength:0];
+  DGLogDebug(@"[Deepgram] flushPendingPCM: flushing %lu bytes",
+             (unsigned long)remaining.length);
+  [self emitPCMChunk:remaining sampleRate:self.currentSampleRate];
+}
+
+- (void)cleanupRecordingQueue {
+  DGLogDebug(@"[Deepgram] cleanupRecordingQueue: begin");
+  self.audioQueueCaptureRequested = NO;
+  _recordState.isRunning = false;
+
+  if (_recordState.queue) {
+    DGLogDebug(@"[Deepgram] cleanupRecordingQueue: stopping queue");
+    AudioQueueStop(_recordState.queue, true);
+
+    for (int i = 0; i < DGNumberBuffers; i++) {
+      if (_recordState.buffers[i]) {
+        DGLogDebug(@"[Deepgram] cleanupRecordingQueue: freeing buffer %d", i);
+        AudioQueueFreeBuffer(_recordState.queue, _recordState.buffers[i]);
+        _recordState.buffers[i] = NULL;
+      }
+    }
+
+    DGLogDebug(@"[Deepgram] cleanupRecordingQueue: disposing queue");
+    AudioQueueDispose(_recordState.queue, true);
+  }
+
+  memset(&_recordState, 0, sizeof(DGRecordState));
+  DGLogDebug(@"[Deepgram] cleanupRecordingQueue: state cleared");
+  [self maybeDeactivateAudioSession];
+}
+
+- (BOOL)beginRecordingToFileIfRequested:(NSDictionary *)options
+                                  error:(NSError **)outError {
+  if (![options isKindOfClass:[NSDictionary class]]) {
+    return YES; // nothing requested
+  }
+  id enabledRaw = options[@"enabled"];
+  BOOL enabled =
+      [enabledRaw isKindOfClass:[NSNumber class]] && [enabledRaw boolValue];
+  if (!enabled) {
+    return YES;
+  }
+
+  // Close any stale handle from a previous, incompletely stopped session.
+  [self discardRecordingFile];
+
+  // Resolve the destination path. A caller-supplied `path` (with or without a
+  // file:// scheme) wins; otherwise write to an app-specific temporary file.
+  NSString *path = nil;
+  id rawPath = options[@"path"];
+  if ([rawPath isKindOfClass:[NSString class]] &&
+      [(NSString *)rawPath length] > 0) {
+    NSString *candidate = (NSString *)rawPath;
+    if ([candidate hasPrefix:@"file://"]) {
+      NSURL *url = [NSURL URLWithString:candidate];
+      candidate = url.path ?: [candidate substringFromIndex:7];
+    }
+    path = candidate;
+  } else {
+    NSString *name =
+        [NSString stringWithFormat:@"deepgram-recording-%.0f.wav",
+                                   [[NSDate date] timeIntervalSince1970] * 1000];
+    path = [NSTemporaryDirectory() stringByAppendingPathComponent:name];
+  }
+
+  NSFileManager *fm = [NSFileManager defaultManager];
+  NSString *dir = [path stringByDeletingLastPathComponent];
+  NSError *dirError = nil;
+  if (dir.length > 0 && ![fm fileExistsAtPath:dir]) {
+    [fm createDirectoryAtPath:dir
+        withIntermediateDirectories:YES
+                         attributes:nil
+                              error:&dirError];
+  }
+
+  // (Re)create the file and write the placeholder header (data size = 0).
+  NSData *header = DGMakeWavHeader((uint32_t)MAX(1, self.currentSampleRate), 1,
+                                   16, 0);
+  if (![fm createFileAtPath:path contents:header attributes:nil]) {
+    if (outError) {
+      *outError = DGNativeError(
+          @"DeepgramRecordToFile", -1,
+          [NSString stringWithFormat:@"Unable to create recording file at %@",
+                                     path]);
+    }
+    return NO;
+  }
+
+  NSFileHandle *handle = [NSFileHandle fileHandleForWritingAtPath:path];
+  if (!handle) {
+    if (outError) {
+      *outError = DGNativeError(
+          @"DeepgramRecordToFile", -2,
+          [NSString stringWithFormat:@"Unable to open recording file at %@",
+                                     path]);
+    }
+    return NO;
+  }
+  [handle seekToEndOfFile];
+
+  self.recordFilePath = path;
+  self.recordFileHandle = handle;
+  self.recordFileDataBytes = 0;
+  self.recordToFileEnabled = YES;
+  DGLogDebug(@"[Deepgram] beginRecordingToFile: writing to %@", path);
+  return YES;
+}
+
+- (NSString *)finishRecordingToFile {
+  NSFileHandle *handle = self.recordFileHandle;
+  NSString *path = self.recordFilePath;
+  self.recordToFileEnabled = NO;
+  self.recordFileHandle = nil;
+  self.recordFilePath = nil;
+
+  if (!handle || path.length == 0) {
+    self.recordFileDataBytes = 0;
+    return nil;
+  }
+
+  uint32_t dataBytes = (uint32_t)self.recordFileDataBytes;
+  self.recordFileDataBytes = 0;
+
+  @try {
+    // Rewrite the full header now that the final size and sample rate are known.
+    NSData *header =
+        DGMakeWavHeader((uint32_t)MAX(1, self.currentSampleRate), 1, 16,
+                        dataBytes);
+    [handle seekToFileOffset:0];
+    [handle writeData:header];
+    [handle closeFile];
+  } @catch (NSException *e) {
+    DGLogWarn(@"[Deepgram] finishRecordingToFile: header patch failed %@", e);
+    @try {
+      [handle closeFile];
+    } @catch (__unused NSException *ignored) {
+    }
+  }
+
+  NSString *uri = [[NSURL fileURLWithPath:path] absoluteString];
+  DGLogDebug(@"[Deepgram] finishRecordingToFile: %@ (%u data bytes)", uri,
+             (unsigned int)dataBytes);
+  return uri;
+}
+
+- (void)discardRecordingFile {
+  NSFileHandle *handle = self.recordFileHandle;
+  NSString *path = self.recordFilePath;
+  self.recordToFileEnabled = NO;
+  self.recordFileHandle = nil;
+  self.recordFilePath = nil;
+  self.recordFileDataBytes = 0;
+
+  if (handle) {
+    @try {
+      [handle closeFile];
+    } @catch (__unused NSException *e) {
+    }
+  }
+  if (path.length > 0) {
+    [[NSFileManager defaultManager] removeItemAtPath:path error:NULL];
+  }
+}
+
+
+
+/**
+ * Engine-based microphone capture path used when the JS side opts in to
+ * hardware voice processing (Voice Agent / duplex). This routes through
+ * `AVAudioEngine.inputNode` with `setVoiceProcessingEnabled:YES` on both
+ * input and output nodes — the only Apple-supported way to actually engage
+ * the VPIO Audio Unit's hardware echo cancellation on iOS. The legacy
+ * AudioQueue path is preserved for STT-only usage where AEC is undesirable.
+ */
+- (BOOL)startEngineCaptureAndReturnError:(NSError **)outError {
+  self.currentSampleRate = 16000;
+
+  if (!self.audioEngine) {
+    NSError *engineError = nil;
+    if (![self setupAudioEngineWithSampleRate:self.currentSampleRate
+                                     channels:1
+                        enableVoiceProcessing:YES
+                                        error:&engineError]) {
+      if (outError)
+        *outError = engineError;
+      return NO;
+    }
+  } else {
+#if TARGET_IPHONE_SIMULATOR
+    // VPIO is unsupported on the simulator and toggling VP corrupts the
+    // input node's format (sampleRate becomes 0), which would later fail
+    // the IsFormatSampleRateAndChannelCountValid check. Skip entirely.
+    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.");
+#else
+    @try {
+      NSError *vpError = nil;
+      if (self.audioEngine.inputNode &&
+          ![self.audioEngine.inputNode setVoiceProcessingEnabled:YES
+                                                           error:&vpError]) {
+        DGLogWarn(@"[Deepgram] inputNode VP enable failed: %@", vpError);
+      }
+      if (self.audioEngine.outputNode &&
+          ![self.audioEngine.outputNode setVoiceProcessingEnabled:YES
+                                                            error:&vpError]) {
+        DGLogWarn(@"[Deepgram] outputNode VP enable failed: %@", vpError);
+      }
+    } @catch (NSException *e) {
+      DGLogWarn(@"[Deepgram] VP enable threw: %@", e);
+    }
+#endif
+  }
+
+  AVAudioInputNode *inputNode = self.audioEngine.inputNode;
+  if (!inputNode) {
+    if (outError) {
+      *outError = [NSError
+          errorWithDomain:@"DeepgramAudioEngine"
+                     code:-2
+                 userInfo:@{
+                   NSLocalizedDescriptionKey : @"No input node available"
+                 }];
+    }
+    return NO;
+  }
+
+  AVAudioFormat *hwFormat = [inputNode inputFormatForBus:0];
+  if (!hwFormat || hwFormat.sampleRate <= 0) {
+    if (outError) {
+      *outError =
+          [NSError errorWithDomain:@"DeepgramAudioEngine"
+                              code:-3
+                          userInfo:@{
+                            NSLocalizedDescriptionKey : @"Invalid input format"
+                          }];
+    }
+    return NO;
+  }
+
+  AVAudioFormat *outputFormat =
+      [[AVAudioFormat alloc] initWithCommonFormat:AVAudioPCMFormatInt16
+                                       sampleRate:self.currentSampleRate
+                                         channels:1
+                                      interleaved:YES];
+  self.captureOutputFormat = outputFormat;
+  self.captureConverter =
+      [[AVAudioConverter alloc] initFromFormat:hwFormat toFormat:outputFormat];
+  if (!self.captureConverter) {
+    if (outError) {
+      *outError = [NSError errorWithDomain:@"DeepgramAudioEngine"
+                                      code:-4
+                                  userInfo:@{
+                                    NSLocalizedDescriptionKey :
+                                        @"Failed to build AVAudioConverter"
+                                  }];
+    }
+    return NO;
+  }
+
+  AVAudioFrameCount tapFrames = (AVAudioFrameCount)MAX(
+      1024, (NSUInteger)round(hwFormat.sampleRate * 0.2));
+
+  __weak __typeof(self) weakSelf = self;
+  @try {
+    [inputNode removeTapOnBus:0];
+  } @catch (__unused NSException *e) {
+    // No prior tap — fine.
+  }
+
+  @try {
+    [inputNode
+        installTapOnBus:0
+             bufferSize:tapFrames
+                 format:hwFormat
+                  block:^(AVAudioPCMBuffer *_Nonnull inBuf,
+                          __unused AVAudioTime *_Nonnull when) {
+                    __strong __typeof(weakSelf) strongSelf = weakSelf;
+                    if (!strongSelf || !strongSelf.engineCaptureActive)
+                      return;
+                    AVAudioConverter *converter = strongSelf.captureConverter;
+                    AVAudioFormat *outFmt = strongSelf.captureOutputFormat;
+                    if (!converter || !outFmt || inBuf.frameLength == 0)
+                      return;
+
+                    AVAudioFrameCount outCapacity =
+                        (AVAudioFrameCount)ceil((double)inBuf.frameLength *
+                                                outFmt.sampleRate /
+                                                inBuf.format.sampleRate) +
+                        16;
+                    AVAudioPCMBuffer *outBuf = [[AVAudioPCMBuffer alloc]
+                        initWithPCMFormat:outFmt
+                            frameCapacity:outCapacity];
+                    if (!outBuf)
+                      return;
+
+                    __block BOOL provided = NO;
+                    NSError *cvtError = nil;
+                    AVAudioConverterInputBlock inputBlock =
+                        ^AVAudioBuffer *_Nullable(
+                            __unused AVAudioPacketCount inNumPackets,
+                            AVAudioConverterInputStatus *_Nonnull outStatus) {
+                      if (provided) {
+                        *outStatus = AVAudioConverterInputStatus_NoDataNow;
+                        return nil;
+                      }
+                      provided = YES;
+                      *outStatus = AVAudioConverterInputStatus_HaveData;
+                      return inBuf;
+                    };
+
+                    AVAudioConverterOutputStatus status =
+                        [converter convertToBuffer:outBuf
+                                             error:&cvtError
+                                withInputFromBlock:inputBlock];
+                    if (status == AVAudioConverterOutputStatus_Error ||
+                        cvtError) {
+                      DGLogWarn(@"[Deepgram] capture convert failed: %@",
+                                cvtError);
+                      return;
+                    }
+                    if (outBuf.frameLength == 0 || !outBuf.int16ChannelData)
+                      return;
+
+                    NSUInteger byteCount = (NSUInteger)outBuf.frameLength * 2;
+                    NSData *pcm =
+                        [NSData dataWithBytes:outBuf.int16ChannelData[0]
+                                       length:byteCount];
+                    [strongSelf appendPCMDataAndEmitIfNeeded:pcm];
+                  }];
+  } @catch (NSException *e) {
+    DGLogError(@"[Deepgram] installTapOnBus exception: %@", e);
+    if (outError) {
+      *outError = [NSError
+          errorWithDomain:@"DeepgramAudioEngine"
+                     code:-5
+                 userInfo:@{
+                   NSLocalizedDescriptionKey : e.reason ?: @"Tap install failed"
+                 }];
+    }
+    return NO;
+  }
+
+  self.chunkSizeBytes =
+      (NSUInteger)MAX(1, (int)round(self.currentSampleRate * 2 * 0.2));
+  self.engineCaptureActive = YES;
+
+  if (!self.audioEngine.isRunning) {
+    NSError *startError = nil;
+    if (![self.audioEngine startAndReturnError:&startError]) {
+      DGLogError(@"[Deepgram] engine start failed: %@", startError);
+      @try {
+        [inputNode removeTapOnBus:0];
+      } @catch (__unused NSException *e) {
+      }
+      self.engineCaptureActive = NO;
+      if (outError)
+        *outError = startError;
+      return NO;
+    }
+  }
+  return YES;
+}
+
+- (void)stopEngineCapture {
+  if (!self.engineCaptureActive && !self.captureConverter)
+    return;
+  DGLogDebug(@"[Deepgram] stopEngineCapture");
+  self.engineCaptureActive = NO;
+
+  @try {
+    [self.audioEngine.inputNode removeTapOnBus:0];
+  } @catch (NSException *e) {
+    DGLogWarn(@"[Deepgram] removeTapOnBus exception: %@", e);
+  }
+
+#if !TARGET_IPHONE_SIMULATOR
+  @try {
+    NSError *vpError = nil;
+    if (self.audioEngine.inputNode) {
+      [self.audioEngine.inputNode setVoiceProcessingEnabled:NO error:&vpError];
+    }
+  } @catch (__unused NSException *e) {
+    // best-effort
+  }
+#endif
+
+  self.captureConverter = nil;
+  self.captureOutputFormat = nil;
+
+  if (!self.isPlaying && self.audioEngine.isRunning) {
+    @try {
+      [self.audioEngine stop];
+    } @catch (__unused NSException *e) {
+    }
+  }
+}
+
+@end
diff --git a/ios/Deepgram.mm b/ios/Deepgram.mm
index 42650c3..a9fa875 100644
--- a/ios/Deepgram.mm
+++ b/ios/Deepgram.mm
@@ -1,154 +1,45 @@
+#import "Deepgram.h"
+#import "Deepgram+Private.h"
+#import "Deepgram+AudioSession.h"
+#import "Deepgram+Recording.h"
+#import "Deepgram+Playback.h"
+
 #import <AVFoundation/AVFoundation.h>
 #import <AudioToolbox/AudioQueue.h>
-#import <React/RCTEventEmitter.h>
-#import <React/RCTLog.h>
 #import <React/RCTUtils.h>
 #import <TargetConditionals.h>
 #if TARGET_OS_IOS
 #import <UIKit/UIKit.h>
 #endif
-#include <atomic>
+
 #include <math.h>
 #include <string.h>
 
-#define DGNumberBuffers 3
-
-#ifndef DG_ENABLE_DEBUG_LOGS
-#define DG_ENABLE_DEBUG_LOGS 0
-#endif
-
-#if DG_ENABLE_DEBUG_LOGS
-#define DGLogDebug(...) NSLog(__VA_ARGS__)
-#else
-#define DGLogDebug(...)
-#endif
-
-#define DGLogWarn(...) RCTLogWarn(__VA_ARGS__)
-#define DGLogError(...) RCTLogError(__VA_ARGS__)
-
-static NSError *DGNativeError(NSString *domain, NSInteger code,
-                              NSString *message) {
-  return [NSError errorWithDomain:domain
-                             code:code
-                         userInfo:@{
-                           NSLocalizedDescriptionKey : message
-                               ?: @"Unknown Deepgram native error"
-                         }];
-}
-
-static NSError *DGOSStatusError(NSString *operation, OSStatus status) {
-  NSString *message = [NSString
-      stringWithFormat:@"%@ failed with OSStatus %d", operation, (int)status];
-  return DGNativeError(NSOSStatusErrorDomain, (NSInteger)status, message);
-}
-
-static void DGRejectPromise(RCTPromiseRejectBlock reject, NSString *code,
-                            NSString *message, NSError *error) {
-  if (!reject) {
-    return;
-  }
-
-  NSString *safeCode = code ?: @"deepgram_native_error";
-  NSString *safeMessage = message ?: error.localizedDescription
-                              ?: @"Deepgram native error";
-  NSError *safeError = error ?: DGNativeError(@"DeepgramNativeError", 0,
-                                             safeMessage);
-  DGLogError(@"[Deepgram] reject: code=%@ message=%@", safeCode,
-             safeMessage);
-  reject(safeCode, safeMessage, safeError);
-}
-
-@class Deepgram;
-
-typedef struct {
-  __unsafe_unretained Deepgram *mSelf;
-  AudioStreamBasicDescription dataFormat;
-  AudioQueueRef queue;
-  AudioQueueBufferRef buffers[DGNumberBuffers];
-  UInt32 bufferByteSize;
-  SInt64 currentPacket;
-  bool isRunning;
-} DGRecordState;
-
-@interface Deepgram : RCTEventEmitter {
-  DGRecordState _recordState;
-  std::atomic<int> _scheduledBufferCount;
-  std::atomic<int> _playbackGeneration;
-}
-
-// Recording
-@property(nonatomic, strong) NSMutableData *pendingPCMBuffer;
-@property(nonatomic, strong) dispatch_queue_t emitterQueue;
-@property(nonatomic, assign) NSUInteger chunkSizeBytes;
-@property(atomic, assign) BOOL hasListeners;
-@property(atomic, assign) BOOL appIsActive;
-
-// Playback / TTS (AVAudioEngine-based with echo cancellation)
-@property(nonatomic, strong) AVAudioEngine *audioEngine;
-@property(nonatomic, strong) AVAudioPlayerNode *playerNode;
-@property(nonatomic, strong) AVAudioFormat *playbackFormat;
-@property(atomic, assign) BOOL isPlaying;
-@property(atomic, assign) int currentSampleRate;
-@property(nonatomic, assign) BOOL audioSessionConfigured;
-// YES while we're capturing the microphone through `audioEngine.inputNode`
-// (Voice Agent / duplex). When YES, the AudioQueue path is bypassed and the
-// session must use VoiceChat mode so Apple's Voice-Processing I/O Audio Unit
-// engages and performs hardware echo cancellation.
-@property(atomic, assign) BOOL engineCaptureActive;
-@property(atomic, assign) BOOL voiceProcessingRequested;
-@property(atomic, assign) BOOL audioQueueCaptureRequested;
-@property(nonatomic, strong) AVAudioConverter *captureConverter;
-@property(nonatomic, strong) AVAudioFormat *captureOutputFormat;
-@end
-
-@interface Deepgram (RecordingPrivate)
-- (void)appendPCMDataAndEmitIfNeeded:(NSData *)pcmData;
-- (BOOL)activateAudioSession:(NSError **)outError;
-- (BOOL)configureAudioSessionIfNeeded:(NSError **)outError;
-- (BOOL)configureAudioSession:(NSError **)outError;
-- (AVAudioSessionCategoryOptions)bluetoothHFPOption;
-- (BOOL)applyAudioSessionCategory:(AVAudioSessionCategory)category
-                             mode:(NSString *)mode
-                          options:(AVAudioSessionCategoryOptions)options
-                            error:(NSError **)outError;
-- (void)stopAndDetachPlayerNode;
-- (void)interruptPlayerPlayback;
-- (void)maybeDeactivateAudioSession;
-@end
+// The class state (ivars + properties), the shared C helpers, the
+// `DGRecordState` struct and the `DGHandleInputBuffer` AudioQueue callback now
+// live in the shared headers and category files:
+//   - DGSupport.h            : logging macros, error helpers, DGRecordState
+//   - Deepgram+Private.h     : class extension (state) + cross-file decls
+//   - Deepgram+AudioSession.mm : audio session lifecycle
+//   - Deepgram+Recording.mm    : microphone capture (+ DGHandleInputBuffer)
+//   - Deepgram+Playback.mm     : TTS / Voice Agent playback
+// This file keeps the module registration, lifecycle and the exported
+// RCT_EXPORT_METHOD entry points (kept here so the macros register on the
+// concrete class rather than a category).
 
-static void DGHandleInputBuffer(
-    void *inUserData, __unused AudioQueueRef inAQ, AudioQueueBufferRef inBuffer,
-    __unused const AudioTimeStamp *inStartTime, __unused UInt32 inNumPackets,
-    __unused const AudioStreamPacketDescription *inPacketDesc) {
-  @autoreleasepool {
-    DGRecordState *state = (DGRecordState *)inUserData;
-    if (!state || !state->isRunning) {
-      DGLogDebug(@"[Deepgram] DGHandleInputBuffer: inactive state");
-      return;
-    }
-
-    Deepgram *strongSelf = state->mSelf;
-    if (!strongSelf) {
-      DGLogDebug(@"[Deepgram] DGHandleInputBuffer: missing self");
-      return;
-    }
-
-    if (!inBuffer || inBuffer->mAudioDataByteSize == 0) {
-      DGLogDebug(@"[Deepgram] DGHandleInputBuffer: empty buffer");
-      return;
-    }
-
-    DGLogDebug(@"[Deepgram] DGHandleInputBuffer: received %u bytes",
-               (unsigned int)inBuffer->mAudioDataByteSize);
-    NSData *data = [NSData dataWithBytes:inBuffer->mAudioData
-                                  length:inBuffer->mAudioDataByteSize];
-    [strongSelf appendPCMDataAndEmitIfNeeded:data];
-
-    if (state->queue) {
-      DGLogDebug(@"[Deepgram] DGHandleInputBuffer: re-enqueue buffer");
-      AudioQueueEnqueueBuffer(state->queue, inBuffer, 0, NULL);
-    }
-  }
+/**
+ * Whether the user has explicitly granted microphone record permission. Read
+ * via the deprecated `AVAudioSession` accessor (still functional on iOS 17+)
+ * with the deprecation warning suppressed locally — mirroring MicPermission.m.
+ * Lets `startRecording` fail fast with the contract `permission_denied` code,
+ * matching the Android module.
+ */
+static BOOL DGHasRecordPermission(void) {
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wdeprecated-declarations"
+  return [AVAudioSession sharedInstance].recordPermission ==
+         AVAudioSessionRecordPermissionGranted;
+#pragma clang diagnostic pop
 }
 
 @implementation Deepgram
@@ -159,7 +50,7 @@ + (BOOL)requiresMainQueueSetup {
 }
 
 - (NSArray<NSString *> *)supportedEvents {
-  return @[ @"DeepgramAudioPCM" ];
+  return @[ @"DeepgramAudioPCM", @"DeepgramAudioLevel" ];
 }
 
 - (void)startObserving {
@@ -233,428 +124,7 @@ - (void)dealloc {
   [[NSNotificationCenter defaultCenter] removeObserver:self];
 }
 
-- (BOOL)activateAudioSession:(NSError **)outError {
-  DGLogDebug(@"[Deepgram] activateAudioSession: begin (configured=%@)",
-             self.audioSessionConfigured ? @"YES" : @"NO");
-  __block BOOL success = YES;
-  __block NSError *activationError = nil;
-
-  DGLogDebug(@"[Deepgram] activateAudioSession: configuring on current queue");
-  success = [self configureAudioSessionIfNeeded:&activationError];
-
-  if (!success && activationError) {
-    DGLogError(@"[Deepgram] Failed to activate audio session: %@",
-               activationError.localizedDescription ?: activationError);
-  } else {
-    DGLogDebug(@"[Deepgram] activateAudioSession: success=%@",
-               success ? @"YES" : @"NO");
-  }
-
-  if (outError) {
-    *outError = activationError;
-  }
-
-  return success;
-}
-
-- (void)deactivateAudioSession {
-  DGLogDebug(@"[Deepgram] deactivateAudioSession: begin");
-  if (!self.audioSessionConfigured) {
-    DGLogDebug(@"[Deepgram] deactivateAudioSession: skipped (not configured)");
-    return;
-  }
-
-  NSError *error = nil;
-  // Use NotifyOthersOnDeactivation so other audio sessions (expo-av, etc.)
-  // know they can resume.
-  BOOL success = NO;
-  @try {
-    success = [[AVAudioSession sharedInstance]
-                  setActive:NO
-                withOptions:AVAudioSessionSetActiveOptionNotifyOthersOnDeactivation
-                      error:&error];
-  }
-  @catch (NSException *e) {
-    DGLogWarn(@"[Deepgram] deactivateAudioSession threw exception: %@",
-              e.reason ?: e);
-    self.audioSessionConfigured = NO;
-    return;
-  }
-
-  if (!success && error) {
-    // Deactivation can legitimately fail during competing audio-route
-    // transitions; treat as a warning rather than an error.
-    DGLogWarn(@"[Deepgram] Failed to deactivate audio session: %@",
-              error.localizedDescription ?: error);
-  }
-  self.audioSessionConfigured = NO;
-}
-
-- (BOOL)configureAudioSessionIfNeeded:(NSError **)outError
-{
-  BOOL needsMic = _recordState.isRunning || self.audioQueueCaptureRequested ||
-                  self.engineCaptureActive || self.voiceProcessingRequested;
-  AVAudioSession *session = [AVAudioSession sharedInstance];
-
-  if (self.audioSessionConfigured) {
-    BOOL isCurrentlyPlayAndRecord = [session.category isEqualToString:AVAudioSessionCategoryPlayAndRecord];
-    if (isCurrentlyPlayAndRecord == needsMic) {
-      DGLogDebug(@"[Deepgram] configureAudioSessionIfNeeded: already configured correctly, ensuring active");
-      NSError *activeError = nil;
-      BOOL success = [[AVAudioSession sharedInstance] setActive:YES error:&activeError];
-      if (success && !activeError) {
-        return YES;
-      }
-    }
-  }
-
-  DGLogDebug(@"[Deepgram] configureAudioSessionIfNeeded: configuring (needsMic=%@)", needsMic ? @"YES" : @"NO");
-  return [self configureAudioSession:outError];
-}
-
-- (BOOL)configureAudioSession:(NSError **)outError {
-  BOOL needsMic = _recordState.isRunning || self.audioQueueCaptureRequested ||
-                  self.engineCaptureActive || self.voiceProcessingRequested;
-  return [self configureAudioSessionForRecording:needsMic error:outError];
-}
-
-/**
- * Build the Bluetooth input option appropriate for the running OS.
- * iOS 17 deprecated `AllowBluetooth` (HFP route) in favor of
- * `AllowBluetoothHFP`. Prefer the new symbol when building against the iOS
- * 17+ SDK and fall back to the legacy spelling on older toolchains.
- */
-- (AVAudioSessionCategoryOptions)bluetoothHFPOption {
-#if defined(__IPHONE_17_0) && (__IPHONE_OS_VERSION_MAX_ALLOWED >= __IPHONE_17_0)
-  if (@available(iOS 17.0, *)) {
-    return AVAudioSessionCategoryOptionAllowBluetoothHFP;
-  }
-#endif
-#pragma clang diagnostic push
-#pragma clang diagnostic ignored "-Wdeprecated-declarations"
-  return AVAudioSessionCategoryOptionAllowBluetooth;
-#pragma clang diagnostic pop
-}
-
-/**
- * Attempt to apply a single category/mode/options tuple and activate the
- * session. Returns YES on success. On failure, populates `outError` so the
- * caller can decide whether to try a more conservative configuration.
- */
-- (BOOL)applyAudioSessionCategory:(AVAudioSessionCategory)category
-                             mode:(NSString *)mode
-                          options:(AVAudioSessionCategoryOptions)options
-                            error:(NSError **)outError {
-  AVAudioSession *session = [AVAudioSession sharedInstance];
-  NSError *error = nil;
-
-  DGLogDebug(@"[Deepgram] configureAudioSession: setCategory %@ mode %@ "
-             @"options 0x%lx",
-             category, mode, (unsigned long)options);
-
-  if (![session setCategory:category
-                       mode:mode
-                    options:options
-                      error:&error] ||
-      error) {
-    DGLogError(@"[Deepgram] configureAudioSession: category failed error=%@",
-               error.localizedDescription ?: error);
-    if (outError) {
-      *outError = error;
-    }
-    return NO;
-  }
-
-  NSError *activeError = nil;
-  if (![session setActive:YES error:&activeError]) {
-    DGLogError(@"[Deepgram] configureAudioSession: setActive failed error=%@",
-               activeError.localizedDescription ?: activeError);
-    if (outError) {
-      *outError = activeError;
-    }
-    return NO;
-  }
-
-  return YES;
-}
-
-/**
- * Configure audio session with mode appropriate to current usage.
- *
- * The configuration is attempted from most- to least-capable. If a richer
- * setup is rejected we automatically fall back to a simpler one so audio still
- * works instead of hard-failing.
- *
- * Two subtle rules drive the ordering below; getting them wrong yields
- * OSStatus -50 (kAudioSession/paramErr) on `setCategory`, which then leaves the
- * session in a half-configured state and makes a later AudioQueueStart fail
- * with 'what' (kAudioSessionUnspecifiedError):
- *
- *   1. `DefaultToSpeaker` forces output to the built-in speaker, while
- *      `AllowBluetoothA2DP` / `AllowAirPlay` route output to external devices.
- *      Combining them is contradictory and is rejected with -50, so those
- *      output-routing options are NEVER mixed with a recording configuration.
- *      A2DP/AirPlay devices are output-only and can't supply a mic input
- *      anyway — Bluetooth input uses the HFP route instead.
- *   2. `MixWithOthers` lets us coexist with other audio packages (expo-av,
- *      etc.) but can prevent us from acquiring the input on some routes. We try
- *      it first to be a good citizen, then degrade to exclusive access so
- *      recording still starts reliably.
- *
- * VoiceChat mode (which engages Apple's hardware AEC / VPIO) is used only when
- * echo cancellation is required and only on a device — VPIO is unavailable on
- * the Simulator and requesting it there guarantees a -50.
- */
-- (BOOL)configureAudioSessionForRecording:(BOOL)needsMicrophone
-                                    error:(NSError **)outError {
-  DGLogDebug(@"[Deepgram] configureAudioSession: begin (mic=%@)",
-             needsMicrophone ? @"YES" : @"NO");
-
-  const AVAudioSessionCategoryOptions mixOption =
-      AVAudioSessionCategoryOptionMixWithOthers;
-
-  // Build an ordered list of attempts, best first.
-  NSMutableArray<NSDictionary *> *attempts = [NSMutableArray array];
-
-  if (needsMicrophone) {
-    BOOL needsAEC = self.engineCaptureActive || self.voiceProcessingRequested ||
-                    self.isPlaying;
-
-    // Input-safe options for PlayAndRecord. DefaultToSpeaker + HFP are valid
-    // here; A2DP/AirPlay are intentionally excluded (see rule 1 above).
-    AVAudioSessionCategoryOptions recordOptions =
-        AVAudioSessionCategoryOptionDefaultToSpeaker | [self bluetoothHFPOption];
-
-#if !TARGET_OS_SIMULATOR
-    // Preferred: hardware AEC via VoiceChat (device only). VoiceChat mode
-    // manages the route itself, so DefaultToSpeaker / HFP must NOT be combined
-    // with it — doing so is rejected with -50 on some iOS versions. Only
-    // MixWithOthers is safe to layer on top.
-    if (needsAEC) {
-      [attempts addObject:@{
-        @"category" : AVAudioSessionCategoryPlayAndRecord,
-        @"mode" : AVAudioSessionModeVoiceChat,
-        @"options" : @(mixOption),
-      }];
-      [attempts addObject:@{
-        @"category" : AVAudioSessionCategoryPlayAndRecord,
-        @"mode" : AVAudioSessionModeVoiceChat,
-        @"options" : @(0),
-      }];
-    }
-#endif
-
-    // PlayAndRecord without VoiceChat (no hardware AEC). Try with MixWithOthers
-    // first to coexist with other packages, then exclusively.
-    [attempts addObject:@{
-      @"category" : AVAudioSessionCategoryPlayAndRecord,
-      @"mode" : AVAudioSessionModeDefault,
-      @"options" : @(recordOptions | mixOption),
-    }];
-    [attempts addObject:@{
-      @"category" : AVAudioSessionCategoryPlayAndRecord,
-      @"mode" : AVAudioSessionModeDefault,
-      @"options" : @(recordOptions),
-    }];
-
-    // Last resort: bare PlayAndRecord with no options. Always valid.
-    [attempts addObject:@{
-      @"category" : AVAudioSessionCategoryPlayAndRecord,
-      @"mode" : AVAudioSessionModeDefault,
-      @"options" : @(0),
-    }];
-  } else {
-    // Playback already supports AirPlay and A2DP routes; the explicit route
-    // options are for PlayAndRecord and can be rejected with OSStatus -50.
-    AVAudioSessionCategoryOptions playbackOptions = mixOption;
-    [attempts addObject:@{
-      @"category" : AVAudioSessionCategoryPlayback,
-      @"mode" : AVAudioSessionModeDefault,
-      @"options" : @(playbackOptions),
-    }];
-
-    // Last resort: bare Playback with no options.
-    [attempts addObject:@{
-      @"category" : AVAudioSessionCategoryPlayback,
-      @"mode" : AVAudioSessionModeDefault,
-      @"options" : @(0),
-    }];
-  }
-
-  NSError *lastError = nil;
-  NSUInteger attemptIndex = 0;
-  for (NSDictionary *attempt in attempts) {
-    attemptIndex++;
-    NSError *attemptError = nil;
-    BOOL success = [self
-        applyAudioSessionCategory:attempt[@"category"]
-                             mode:attempt[@"mode"]
-                          options:(AVAudioSessionCategoryOptions)
-                                      [attempt[@"options"] unsignedIntegerValue]
-                            error:&attemptError];
-    if (success) {
-      if (attemptIndex > 1) {
-        DGLogDebug(@"[Deepgram] configureAudioSession: succeeded on fallback "
-                   @"attempt %lu/%lu",
-                   (unsigned long)attemptIndex, (unsigned long)attempts.count);
-      }
-      self.audioSessionConfigured = YES;
-      DGLogDebug(@"[Deepgram] configureAudioSession: success");
-      return YES;
-    }
-    lastError = attemptError;
-    DGLogDebug(@"[Deepgram] configureAudioSession: attempt %lu/%lu failed, "
-               @"trying next configuration",
-               (unsigned long)attemptIndex, (unsigned long)attempts.count);
-  }
-
-  DGLogError(@"[Deepgram] configureAudioSession: all %lu configurations failed; "
-             @"last error=%@",
-             (unsigned long)attempts.count,
-             lastError.localizedDescription ?: lastError);
-  if (outError) {
-    *outError = lastError;
-  }
-  self.audioSessionConfigured = NO;
-  return NO;
-}
-
-- (void)maybeDeactivateAudioSession {
-  DGLogDebug(@"[Deepgram] maybeDeactivateAudioSession: running=%@ playing=%@ "
-             @"engineCapture=%@",
-             _recordState.isRunning ? @"YES" : @"NO",
-             self.isPlaying ? @"YES" : @"NO",
-             self.engineCaptureActive ? @"YES" : @"NO");
-  if (!_recordState.isRunning && !self.isPlaying && !self.engineCaptureActive) {
-    DGLogDebug(@"[Deepgram] maybeDeactivateAudioSession: deactivating");
-    [self deactivateAudioSession];
-  }
-}
-
-- (void)handleAudioRouteChange:(NSNotification *)note {
-  DGLogDebug(@"[Deepgram] handleAudioRouteChange: %@", note.userInfo);
-  NSNumber *reasonValue = note.userInfo[AVAudioSessionRouteChangeReasonKey];
-  AVAudioSessionRouteChangeReason reason =
-      reasonValue
-          ? (AVAudioSessionRouteChangeReason)reasonValue.unsignedIntegerValue
-          : AVAudioSessionRouteChangeReasonUnknown;
-
-  // Headphones / Bluetooth headset unplugged — pause playback so we don't
-  // surprise the user by suddenly blasting through the loud speaker.
-  // (System would route audio to the speaker automatically; that's the point
-  // of this notification.) Matches expo-audio behavior and Apple's guidance.
-  if (reason == AVAudioSessionRouteChangeReasonOldDeviceUnavailable) {
-    DGLogDebug(@"[Deepgram] handleAudioRouteChange: old device unavailable — "
-               @"pausing playback");
-    if (self.isPlaying && self.playerNode) {
-      [self.playerNode pause];
-    }
-  }
-
-  BOOL causedByCategory =
-      reason == AVAudioSessionRouteChangeReasonCategoryChange ||
-      reason == AVAudioSessionRouteChangeReasonNoSuitableRouteForCategory;
-
-  if (!causedByCategory) {
-    self.audioSessionConfigured = NO;
-  }
-
-  if (!_recordState.isRunning && !self.isPlaying) {
-    DGLogDebug(@"[Deepgram] handleAudioRouteChange: ignoring (inactive)");
-    return;
-  }
-
-  if (!self.appIsActive) {
-    DGLogDebug(@"[Deepgram] handleAudioRouteChange: app inactive, skipping");
-    return;
-  }
-
-  if (causedByCategory) {
-    DGLogDebug(@"[Deepgram] handleAudioRouteChange: category change detected, "
-               @"keeping session");
-    return;
-  }
-
-  DGLogDebug(@"[Deepgram] handleAudioRouteChange: reactivating session");
-  [self activateAudioSession:NULL];
-}
-
-// AVAudioSession can post this when mediaserverd restarts (e.g. after a
-// rare system audio HAL hiccup). Once it fires, every AudioQueue /
-// AVAudioEngine instance becomes a zombie. Apple's documented fix is to throw
-// everything away and rebuild on demand. Match expo-audio's approach.
-- (void)handleMediaServicesReset:(NSNotification *)note {
-  DGLogDebug(@"[Deepgram] handleMediaServicesReset: tearing down audio stack");
-  self.audioSessionConfigured = NO;
-
-  // Recording queue must be torn down — it's a zombie after a media services
-  // reset.
-  if (_recordState.isRunning || _recordState.queue) {
-    [self cleanupRecordingQueue];
-  }
-
-  // Engine-based capture path also dies with mediaserverd; force a full
-  // teardown so the next startRecording rebuilds VPIO from scratch.
-  self.engineCaptureActive = NO;
-  self.captureConverter = nil;
-  self.captureOutputFormat = nil;
-
-  // AVAudioEngine + player node are no longer valid. Stop and discard so the
-  // next setup call rebuilds from scratch.
-  @try {
-    if (self.playerNode) {
-      [self.playerNode stop];
-    }
-    if (self.audioEngine) {
-      [self.audioEngine stop];
-    }
-  } @catch (NSException *e) {
-    DGLogError(@"[Deepgram] handleMediaServicesReset: teardown exception %@",
-               e);
-  }
-  self.playerNode = nil;
-  self.audioEngine = nil;
-  self.isPlaying = NO;
-}
-
-- (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];
-      }
-    }
-  }
-}
+// MARK: - Audio session lifecycle lives in Deepgram+AudioSession.mm
 
 #if TARGET_OS_IOS
 - (void)handleAppDidBecomeActive:(NSNotification *)note {
@@ -673,362 +143,27 @@ - (void)handleAppDidEnterBackground:(NSNotification *)note {
 }
 #endif
 
-- (void)emitPCMChunk:(NSData *)chunk sampleRate:(int)sampleRate {
-  if (!chunk || chunk.length == 0) {
-    DGLogDebug(@"[Deepgram] emitPCMChunk: empty chunk, skipping");
-    return;
-  }
-
-  __weak __typeof(self) weakSelf = self;
-  NSData *chunkCopy = [chunk copy];
-  dispatch_queue_t queue = self.emitterQueue ?: dispatch_get_main_queue();
-  dispatch_async(queue, ^{
-    if (!weakSelf) {
-      DGLogDebug(@"[Deepgram] emitPCMChunk: self released, aborting");
-      return;
-    }
-
-    if (!weakSelf.hasListeners) {
-      DGLogDebug(@"[Deepgram] emitPCMChunk: no listeners, dropping %lu bytes",
-                 (unsigned long)chunkCopy.length);
-      return;
-    }
-
-    if (!weakSelf.bridge || !weakSelf.callableJSModules) {
-      DGLogDebug(
-          @"[Deepgram] Skipping DeepgramAudioPCM event (bridge not ready)");
-      return;
-    }
-
-    DGLogDebug(@"[Deepgram] emitPCMChunk: sending %lu bytes sampleRate=%d",
-               (unsigned long)chunkCopy.length, sampleRate);
-    NSString *b64 = [chunkCopy base64EncodedStringWithOptions:0];
-    [weakSelf sendEventWithName:@"DeepgramAudioPCM"
-                           body:@{
-                             @"b64" : b64,
-                             @"sampleRate" : @(sampleRate)
-                           }];
-  });
-}
-
-- (void)appendPCMDataAndEmitIfNeeded:(NSData *)pcmData {
-  if (!pcmData || pcmData.length == 0) {
-    DGLogDebug(@"[Deepgram] appendPCMDataAndEmitIfNeeded: empty PCM, skipping");
-    return;
-  }
-
-  if (!self.pendingPCMBuffer) {
-    DGLogDebug(
-        @"[Deepgram] appendPCMDataAndEmitIfNeeded: allocate pending buffer");
-    self.pendingPCMBuffer = [[NSMutableData alloc] init];
-  }
-
-  DGLogDebug(@"[Deepgram] appendPCMDataAndEmitIfNeeded: append %lu bytes "
-             @"(pending=%lu)",
-             (unsigned long)pcmData.length,
-             (unsigned long)self.pendingPCMBuffer.length);
-  [self.pendingPCMBuffer appendData:pcmData];
-
-  NSUInteger chunkSize =
-      self.chunkSizeBytes > 0 ? self.chunkSizeBytes : pcmData.length;
-
-  while (self.pendingPCMBuffer.length >= chunkSize) {
-    NSData *chunk =
-        [self.pendingPCMBuffer subdataWithRange:NSMakeRange(0, chunkSize)];
-    [self.pendingPCMBuffer replaceBytesInRange:NSMakeRange(0, chunkSize)
-                                     withBytes:NULL
-                                        length:0];
-    DGLogDebug(@"[Deepgram] appendPCMDataAndEmitIfNeeded: emitting chunk %lu "
-               @"bytes remaining=%lu",
-               (unsigned long)chunk.length,
-               (unsigned long)self.pendingPCMBuffer.length);
-    [self emitPCMChunk:chunk sampleRate:self.currentSampleRate];
-  }
-}
-
-- (void)flushPendingPCM {
-  if (self.pendingPCMBuffer.length == 0) {
-    DGLogDebug(@"[Deepgram] flushPendingPCM: nothing to flush");
-    return;
-  }
-
-  NSData *remaining = [self.pendingPCMBuffer copy];
-  [self.pendingPCMBuffer setLength:0];
-  DGLogDebug(@"[Deepgram] flushPendingPCM: flushing %lu bytes",
-             (unsigned long)remaining.length);
-  [self emitPCMChunk:remaining sampleRate:self.currentSampleRate];
-}
-
-- (void)cleanupRecordingQueue {
-  DGLogDebug(@"[Deepgram] cleanupRecordingQueue: begin");
-  self.audioQueueCaptureRequested = NO;
-  _recordState.isRunning = false;
-
-  if (_recordState.queue) {
-    DGLogDebug(@"[Deepgram] cleanupRecordingQueue: stopping queue");
-    AudioQueueStop(_recordState.queue, true);
-
-    for (int i = 0; i < DGNumberBuffers; i++) {
-      if (_recordState.buffers[i]) {
-        DGLogDebug(@"[Deepgram] cleanupRecordingQueue: freeing buffer %d", i);
-        AudioQueueFreeBuffer(_recordState.queue, _recordState.buffers[i]);
-        _recordState.buffers[i] = NULL;
-      }
-    }
-
-    DGLogDebug(@"[Deepgram] cleanupRecordingQueue: disposing queue");
-    AudioQueueDispose(_recordState.queue, true);
-  }
-
-  memset(&_recordState, 0, sizeof(DGRecordState));
-  DGLogDebug(@"[Deepgram] cleanupRecordingQueue: state cleared");
-  [self maybeDeactivateAudioSession];
-}
-
-/* ================================================================== */
-/*  1.  MICROPHONE CAPTURE (16 kHz PCM16 emission)                     */
-/* ================================================================== */
-
-/**
- * Engine-based microphone capture path used when the JS side opts in to
- * hardware voice processing (Voice Agent / duplex). This routes through
- * `AVAudioEngine.inputNode` with `setVoiceProcessingEnabled:YES` on both
- * input and output nodes — the only Apple-supported way to actually engage
- * the VPIO Audio Unit's hardware echo cancellation on iOS. The legacy
- * AudioQueue path is preserved for STT-only usage where AEC is undesirable.
- */
-- (BOOL)startEngineCaptureAndReturnError:(NSError **)outError {
-  self.currentSampleRate = 16000;
-
-  if (!self.audioEngine) {
-    NSError *engineError = nil;
-    if (![self setupAudioEngineWithSampleRate:self.currentSampleRate
-                                     channels:1
-                        enableVoiceProcessing:YES
-                                        error:&engineError]) {
-      if (outError)
-        *outError = engineError;
-      return NO;
-    }
-  } else {
-#if TARGET_IPHONE_SIMULATOR
-    // VPIO is unsupported on the simulator and toggling VP corrupts the
-    // input node's format (sampleRate becomes 0), which would later fail
-    // the IsFormatSampleRateAndChannelCountValid check. Skip entirely.
-    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.");
-#else
-    @try {
-      NSError *vpError = nil;
-      if (self.audioEngine.inputNode &&
-          ![self.audioEngine.inputNode setVoiceProcessingEnabled:YES
-                                                           error:&vpError]) {
-        DGLogWarn(@"[Deepgram] inputNode VP enable failed: %@", vpError);
-      }
-      if (self.audioEngine.outputNode &&
-          ![self.audioEngine.outputNode setVoiceProcessingEnabled:YES
-                                                            error:&vpError]) {
-        DGLogWarn(@"[Deepgram] outputNode VP enable failed: %@", vpError);
-      }
-    } @catch (NSException *e) {
-      DGLogWarn(@"[Deepgram] VP enable threw: %@", e);
-    }
-#endif
-  }
-
-  AVAudioInputNode *inputNode = self.audioEngine.inputNode;
-  if (!inputNode) {
-    if (outError) {
-      *outError = [NSError
-          errorWithDomain:@"DeepgramAudioEngine"
-                     code:-2
-                 userInfo:@{
-                   NSLocalizedDescriptionKey : @"No input node available"
-                 }];
-    }
-    return NO;
-  }
-
-  AVAudioFormat *hwFormat = [inputNode inputFormatForBus:0];
-  if (!hwFormat || hwFormat.sampleRate <= 0) {
-    if (outError) {
-      *outError =
-          [NSError errorWithDomain:@"DeepgramAudioEngine"
-                              code:-3
-                          userInfo:@{
-                            NSLocalizedDescriptionKey : @"Invalid input format"
-                          }];
-    }
-    return NO;
-  }
-
-  AVAudioFormat *outputFormat =
-      [[AVAudioFormat alloc] initWithCommonFormat:AVAudioPCMFormatInt16
-                                       sampleRate:self.currentSampleRate
-                                         channels:1
-                                      interleaved:YES];
-  self.captureOutputFormat = outputFormat;
-  self.captureConverter =
-      [[AVAudioConverter alloc] initFromFormat:hwFormat toFormat:outputFormat];
-  if (!self.captureConverter) {
-    if (outError) {
-      *outError = [NSError errorWithDomain:@"DeepgramAudioEngine"
-                                      code:-4
-                                  userInfo:@{
-                                    NSLocalizedDescriptionKey :
-                                        @"Failed to build AVAudioConverter"
-                                  }];
-    }
-    return NO;
-  }
-
-  AVAudioFrameCount tapFrames = (AVAudioFrameCount)MAX(
-      1024, (NSUInteger)round(hwFormat.sampleRate * 0.2));
-
-  __weak __typeof(self) weakSelf = self;
-  @try {
-    [inputNode removeTapOnBus:0];
-  } @catch (__unused NSException *e) {
-    // No prior tap — fine.
-  }
-
-  @
-  try {
-    [inputNode
-        installTapOnBus:0
-             bufferSize:tapFrames
-                 format:hwFormat
-                  block:^(AVAudioPCMBuffer *_Nonnull inBuf,
-                          __unused AVAudioTime *_Nonnull when) {
-                    __strong __typeof(weakSelf) strongSelf = weakSelf;
-                    if (!strongSelf || !strongSelf.engineCaptureActive)
-                      return;
-                    AVAudioConverter *converter = strongSelf.captureConverter;
-                    AVAudioFormat *outFmt = strongSelf.captureOutputFormat;
-                    if (!converter || !outFmt || inBuf.frameLength == 0)
-                      return;
-
-                    AVAudioFrameCount outCapacity =
-                        (AVAudioFrameCount)ceil((double)inBuf.frameLength *
-                                                outFmt.sampleRate /
-                                                inBuf.format.sampleRate) +
-                        16;
-                    AVAudioPCMBuffer *outBuf = [[AVAudioPCMBuffer alloc]
-                        initWithPCMFormat:outFmt
-                            frameCapacity:outCapacity];
-                    if (!outBuf)
-                      return;
-
-                    __block BOOL provided = NO;
-                    NSError *cvtError = nil;
-                    AVAudioConverterInputBlock inputBlock =
-                        ^AVAudioBuffer *_Nullable(
-                            __unused AVAudioPacketCount inNumPackets,
-                            AVAudioConverterInputStatus *_Nonnull outStatus) {
-                      if (provided) {
-                        *outStatus = AVAudioConverterInputStatus_NoDataNow;
-                        return nil;
-                      }
-                      provided = YES;
-                      *outStatus = AVAudioConverterInputStatus_HaveData;
-                      return inBuf;
-                    };
-
-                    AVAudioConverterOutputStatus status =
-                        [converter convertToBuffer:outBuf
-                                             error:&cvtError
-                                withInputFromBlock:inputBlock];
-                    if (status == AVAudioConverterOutputStatus_Error ||
-                        cvtError) {
-                      DGLogWarn(@"[Deepgram] capture convert failed: %@",
-                                cvtError);
-                      return;
-                    }
-                    if (outBuf.frameLength == 0 || !outBuf.int16ChannelData)
-                      return;
-
-                    NSUInteger byteCount = (NSUInteger)outBuf.frameLength * 2;
-                    NSData *pcm =
-                        [NSData dataWithBytes:outBuf.int16ChannelData[0]
-                                       length:byteCount];
-                    [strongSelf appendPCMDataAndEmitIfNeeded:pcm];
-                  }];
-  } @catch (NSException *e) {
-    DGLogError(@"[Deepgram] installTapOnBus exception: %@", e);
-    if (outError) {
-      *outError = [NSError
-          errorWithDomain:@"DeepgramAudioEngine"
-                     code:-5
-                 userInfo:@{
-                   NSLocalizedDescriptionKey : e.reason ?: @"Tap install failed"
-                 }];
-    }
-    return NO;
-  }
-
-  self.chunkSizeBytes =
-      (NSUInteger)MAX(1, (int)round(self.currentSampleRate * 2 * 0.2));
-  self.engineCaptureActive = YES;
-
-  if (!self.audioEngine.isRunning) {
-    NSError *startError = nil;
-    if (![self.audioEngine startAndReturnError:&startError]) {
-      DGLogError(@"[Deepgram] engine start failed: %@", startError);
-      @try {
-        [inputNode removeTapOnBus:0];
-      } @catch (__unused NSException *e) {
-      }
-      self.engineCaptureActive = NO;
-      if (outError)
-        *outError = startError;
-      return NO;
-    }
-  }
-  return YES;
-}
-
-- (void)stopEngineCapture {
-  if (!self.engineCaptureActive && !self.captureConverter)
-    return;
-  DGLogDebug(@"[Deepgram] stopEngineCapture");
-  self.engineCaptureActive = NO;
-
-  @try {
-    [self.audioEngine.inputNode removeTapOnBus:0];
-  } @catch (NSException *e) {
-    DGLogWarn(@"[Deepgram] removeTapOnBus exception: %@", e);
-  }
-
-#if !TARGET_IPHONE_SIMULATOR
-  @
-  try {
-    NSError *vpError = nil;
-    if (self.audioEngine.inputNode) {
-      [self.audioEngine.inputNode setVoiceProcessingEnabled:NO error:&vpError];
-    }
-  } @catch (__unused NSException *e) {
-    // best-effort
-  }
-#endif
-
-  self.captureConverter = nil;
-  self.captureOutputFormat = nil;
-
-  if (!self.isPlaying && self.audioEngine.isRunning) {
-    @try {
-      [self.audioEngine stop];
-    } @catch (__unused NSException *e) {
-    }
-  }
-}
+// MARK: - Microphone capture lives in Deepgram+Recording.mm
+//         (emitPCMChunk / appendPCMDataAndEmitIfNeeded / flushPendingPCM /
+//          cleanupRecordingQueue / startEngineCaptureAndReturnError /
+//          stopEngineCapture, plus the DGHandleInputBuffer callback)
 
 RCT_EXPORT_METHOD(startRecording : (NSDictionary *)options resolver : (
     RCTPromiseResolveBlock)resolve rejecter : (RCTPromiseRejectBlock)reject) {
   @try {
     DGLogDebug(@"[Deepgram] startRecording: begin");
 
+    if (!DGHasRecordPermission()) {
+      DGLogError(
+          @"[Deepgram] startRecording: microphone permission not granted");
+      DGRejectPromise(
+          reject, @"permission_denied",
+          @"Microphone permission has not been granted. Request it from JS "
+          @"(MicPermission.request) before calling startRecording.",
+          nil);
+      return;
+    }
+
     BOOL enableVoiceProcessing = NO;
     if ([options isKindOfClass:[NSDictionary class]]) {
       id raw = options[@"enableVoiceProcessing"];
@@ -1039,6 +174,16 @@ - (void)stopEngineCapture {
     self.voiceProcessingRequested = enableVoiceProcessing;
     self.audioQueueCaptureRequested = !enableVoiceProcessing;
 
+    NSDictionary *recordToFileOptions = nil;
+    if ([options isKindOfClass:[NSDictionary class]]) {
+      id rtf = options[@"recordToFile"];
+      if ([rtf isKindOfClass:[NSDictionary class]]) {
+        recordToFileOptions = (NSDictionary *)rtf;
+      }
+    }
+    // Drop any file left open by a previous, incompletely stopped session.
+    [self discardRecordingFile];
+
     self.currentSampleRate = 16000;
     DGLogDebug(@"[Deepgram] startRecording: targetSampleRate=%d vp=%@",
                self.currentSampleRate, enableVoiceProcessing ? @"YES" : @"NO");
@@ -1049,7 +194,7 @@ - (void)stopEngineCapture {
       DGLogError(@"[Deepgram] startRecording: activation failed %@", message);
       self.voiceProcessingRequested = NO;
       self.audioQueueCaptureRequested = NO;
-      DGRejectPromise(reject, @"record_start_error", message, sessionError);
+      DGRejectPromise(reject, @"start_error", message, sessionError);
       return;
     }
 
@@ -1060,14 +205,29 @@ - (void)stopEngineCapture {
       [self stopEngineCapture];
       self.pendingPCMBuffer = [[NSMutableData alloc] init];
 
+      // Open the WAV target before capture starts so the first buffers are
+      // teed to disk and any file-open failure is surfaced before the mic opens.
+      NSError *fileError = nil;
+      if (![self beginRecordingToFileIfRequested:recordToFileOptions
+                                           error:&fileError]) {
+        DGLogError(@"[Deepgram] startRecording: record-to-file failed %@",
+                   fileError);
+        self.voiceProcessingRequested = NO;
+        [self maybeDeactivateAudioSession];
+        DGRejectPromise(reject, @"start_error", fileError.localizedDescription,
+                        fileError);
+        return;
+      }
+
       NSError *engineError = nil;
       if (![self startEngineCaptureAndReturnError:&engineError]) {
         NSString *message = engineError.localizedDescription
                                 ?: @"Failed to start engine capture";
         DGLogError(@"[Deepgram] startRecording: %@", message);
+        [self discardRecordingFile];
         self.voiceProcessingRequested = NO;
         [self maybeDeactivateAudioSession];
-        DGRejectPromise(reject, @"record_start_error", message, engineError);
+        DGRejectPromise(reject, @"start_error", message, engineError);
         return;
       }
       DGLogDebug(@"[Deepgram] startRecording: engine capture started");
@@ -1124,7 +284,7 @@ - (void)stopEngineCapture {
       NSString *message = error.localizedDescription;
       DGLogError(@"[Deepgram] startRecording: %@", message);
       [self cleanupRecordingQueue];
-      DGRejectPromise(reject, @"record_start_error", message, error);
+      DGRejectPromise(reject, @"start_error", message, error);
       return;
     }
 
@@ -1168,7 +328,7 @@ - (void)stopEngineCapture {
         NSString *message = error.localizedDescription;
         DGLogError(@"[Deepgram] startRecording: %@", message);
         [self cleanupRecordingQueue];
-        DGRejectPromise(reject, @"record_start_error", message, error);
+        DGRejectPromise(reject, @"start_error", message, error);
         return;
       }
 
@@ -1179,18 +339,32 @@ - (void)stopEngineCapture {
         NSString *message = error.localizedDescription;
         DGLogError(@"[Deepgram] startRecording: %@", message);
         [self cleanupRecordingQueue];
-        DGRejectPromise(reject, @"record_start_error", message, error);
+        DGRejectPromise(reject, @"start_error", message, error);
         return;
       }
     }
 
+    // Open the WAV target before capture starts so the first buffers are teed
+    // to disk and any file-open failure is surfaced before the mic opens.
+    NSError *fileError = nil;
+    if (![self beginRecordingToFileIfRequested:recordToFileOptions
+                                         error:&fileError]) {
+      DGLogError(@"[Deepgram] startRecording: record-to-file failed %@",
+                 fileError);
+      [self cleanupRecordingQueue];
+      DGRejectPromise(reject, @"start_error", fileError.localizedDescription,
+                      fileError);
+      return;
+    }
+
     status = AudioQueueStart(_recordState.queue, NULL);
     if (status != noErr) {
       NSError *error = DGOSStatusError(@"AudioQueueStart", status);
       NSString *message = error.localizedDescription;
       DGLogError(@"[Deepgram] startRecording: %@", message);
+      [self discardRecordingFile];
       [self cleanupRecordingQueue];
-      DGRejectPromise(reject, @"record_start_error", message, error);
+      DGRejectPromise(reject, @"start_error", message, error);
       return;
     }
 
@@ -1203,7 +377,7 @@ - (void)stopEngineCapture {
     [self cleanupRecordingQueue];
     NSString *message = e.reason ?: @"Deepgram native exception";
     NSError *error = DGNativeError(@"DeepgramNativeException", 0, message);
-    DGRejectPromise(reject, @"record_start_error", message, error);
+    DGRejectPromise(reject, @"start_error", message, error);
   }
 }
 
@@ -1216,14 +390,15 @@ - (void)stopEngineCapture {
     [self flushPendingPCM];
     self.pendingPCMBuffer = nil;
     self.voiceProcessingRequested = NO;
+    NSString *recordingUri = [self finishRecordingToFile];
     [self maybeDeactivateAudioSession];
     DGLogDebug(@"[Deepgram] stopRecording: finished");
     if (resolve)
-      resolve(nil);
+      resolve(recordingUri ? @{@"recordingUri" : recordingUri} : nil);
   } @catch (NSException *e) {
     DGLogError(@"[Deepgram] stopRecording: exception %@", e);
-    if (reject)
-      reject(@"record_stop_error", e.reason, nil);
+    [self discardRecordingFile];
+    DGRejectPromise(reject, @"stop_error", e.reason, nil);
   }
 }
 
@@ -1250,8 +425,7 @@ - (void)stopEngineCapture {
       resolve(nil);
   } @catch (NSException *e) {
     DGLogError(@"[Deepgram] startAudio: exception %@", e);
-    if (reject)
-      reject(@"audio_start_error", e.reason, nil);
+    DGRejectPromise(reject, @"audio_start_error", e.reason, nil);
   }
 }
 
@@ -1265,198 +439,13 @@ - (void)stopEngineCapture {
       resolve(nil);
   } @catch (NSException *e) {
     DGLogError(@"[Deepgram] stopAudio: exception %@", e);
-    if (reject)
-      reject(@"audio_stop_error", e.reason, nil);
-  }
-}
-
-/* ================================================================== */
-/*  2.  AVAUDIOENGINE PLAYBACK WITH VOICE PROCESSING (ECHO CANCEL)    */
-/* ================================================================== */
-
-/**
- * Setup AVAudioEngine for output. When `enableVoiceProcessing` is YES we also
- * configure the input node for hardware echo cancellation (Voice Agent /
- * duplex use case). When NO (pure TTS playback), we deliberately avoid
- * touching `inputNode` so we don't request the microphone or interfere with
- * other audio libraries.
- */
-- (void)stopAndDetachPlayerNode {
-  if (self.playerNode) {
-    _playbackGeneration.fetch_add(1);
-
-    @try {
-      [self.playerNode stop];
-    } @catch (NSException *e) {
-      DGLogWarn(@"[Deepgram] playerNode stop exception: %@", e);
-    }
-
-    if (self.audioEngine) {
-      @try {
-        [self.audioEngine detachNode:self.playerNode];
-      } @catch (NSException *e) {
-        DGLogWarn(@"[Deepgram] playerNode detach exception: %@", e);
-      }
-    }
-  }
-
-  self.playerNode = nil;
-  self.playbackFormat = nil;
-  self.isPlaying = NO;
-  _scheduledBufferCount = 0;
-}
-
-- (void)interruptPlayerPlayback {
-  if (self.playerNode) {
-    _playbackGeneration.fetch_add(1);
-
-    @try {
-      [self.playerNode stop];
-    } @catch (NSException *e) {
-      DGLogWarn(@"[Deepgram] playerNode interrupt exception: %@", e);
-    }
-  }
-
-  self.isPlaying = NO;
-  _scheduledBufferCount = 0;
-}
-
-- (BOOL)setupAudioEngineWithSampleRate:(int)sampleRate
-                              channels:(int)channels
-                 enableVoiceProcessing:(BOOL)enableVoiceProcessing
-                                 error:(NSError **)outError {
-  BOOL reuseCaptureEngine = self.audioEngine && self.engineCaptureActive;
-
-  if (self.audioEngine && self.audioEngine.isRunning) {
-    [self.audioEngine stop];
-  }
-
-  [self stopAndDetachPlayerNode];
-
-  if (!reuseCaptureEngine) {
-    if (self.audioEngine) {
-      [self.audioEngine reset];
-    }
-    self.audioEngine = [[AVAudioEngine alloc] init];
-  }
-
-  if (!self.audioEngine) {
-    self.audioEngine = [[AVAudioEngine alloc] init];
-  }
-
-  self.playerNode = [[AVAudioPlayerNode alloc] init];
-
-  self.playbackFormat =
-      [[AVAudioFormat alloc] initWithCommonFormat:AVAudioPCMFormatInt16
-                                       sampleRate:sampleRate
-                                         channels:channels
-                                      interleaved:YES];
-
-  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];
-
-  if (enableVoiceProcessing) {
-#if TARGET_IPHONE_SIMULATOR
-    // VPIO is not implemented on the simulator. Calling
-    // setVoiceProcessingEnabled:YES there raises an internal AVAEInternal
-    // exception about IsFormatSampleRateAndChannelCountValid because the
-    // simulator's input node cannot satisfy the VPIO format constraints.
-    // Skip VP entirely; AEC has to be tested on a physical device.
-    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.");
-#else
-    @try {
-      AVAudioInputNode *inputNode = self.audioEngine.inputNode;
-      AVAudioOutputNode *outputNode = self.audioEngine.outputNode;
-      // Apple's hardware AEC (VPIO Audio Unit) only engages when *both*
-      // input and output flow through a voice-processing-enabled audio
-      // unit. Enabling VP only on the input node is a no-op for capture
-      // unless rendering goes through the same unit, so we enable both.
-      if (inputNode) {
-        NSError *voiceProcessingError = nil;
-        if (![inputNode setVoiceProcessingEnabled:YES
-                                            error:&voiceProcessingError]) {
-          DGLogWarn(@"[Deepgram] inputNode VP enable failed: %@",
-                    voiceProcessingError);
-        }
-      }
-      if (outputNode) {
-        NSError *voiceProcessingError = nil;
-        if (![outputNode setVoiceProcessingEnabled:YES
-                                             error:&voiceProcessingError]) {
-          DGLogWarn(@"[Deepgram] outputNode VP enable failed: %@",
-                    voiceProcessingError);
-        }
-      }
-    } @catch (NSException *exception) {
-      // Continue - voice processing not critical for basic playback
-      DGLogWarn(@"[Deepgram] VP enable threw: %@", exception);
-    }
-#endif
+    DGRejectPromise(reject, @"audio_stop_error", e.reason, nil);
   }
-
-  [self.audioEngine prepare];
-  NSError *startError = nil;
-  BOOL started = [self.audioEngine startAndReturnError:&startError];
-
-  if (!started) {
-    DGLogError(@"[Deepgram] Failed to start audio engine: %@",
-               startError.localizedDescription);
-    if (outError) {
-      *outError = startError;
-    }
-    return NO;
-  }
-
-  return YES;
 }
 
-/**
- * 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;
-}
+// MARK: - TTS / Voice Agent playback lives in Deepgram+Playback.mm
+//         (stopAndDetachPlayerNode / interruptPlayerPlayback /
+//          setupAudioEngineWithSampleRate / createPCMBufferFromData)
 
 RCT_EXPORT_METHOD(startPlayer : (nonnull NSNumber *)
                       sampleRate channels : (nonnull NSNumber *)channels) {
@@ -1600,8 +589,7 @@ - (AVAudioPCMBuffer *)createPCMBufferFromData:(NSData *)data {
       resolve(nil);
   } @catch (NSException *e) {
     DGLogError(@"[Deepgram] stopPlayer: exception %@", e);
-    if (reject)
-      reject(@"player_stop_error", e.reason, nil);
+    DGRejectPromise(reject, @"stop_player_error", e.reason, nil);
   }
 }
 
@@ -1615,6 +603,25 @@ - (AVAudioPCMBuffer *)createPCMBufferFromData:(NSData *)data {
   [self startPlayer:sampleRate channels:channels];
 }
 
+/**
+ * Enable / disable microphone audio-level (metering) events. When enabled the
+ * module emits `DeepgramAudioLevel` events with a normalized RMS amplitude
+ * (0..1) at most once per `intervalMs` (default 100 ms). Purely additive — the
+ * mic capture path and PCM emission are unaffected.
+ */
+RCT_EXPORT_METHOD(setMeteringEnabled : (BOOL)enabled intervalMs : (nonnull NSNumber *)
+                      intervalMs) {
+  double ms = [intervalMs doubleValue];
+  if (ms <= 0) {
+    ms = 100.0; // sensible ~10 Hz default
+  }
+  self.meteringEnabled = enabled;
+  self.meteringIntervalSeconds = ms / 1000.0;
+  self.lastMeterEmitTime = 0;
+  DGLogDebug(@"[Deepgram] setMeteringEnabled: enabled=%@ intervalMs=%.0f",
+             enabled ? @"YES" : @"NO", ms);
+}
+
 /**
  * Play a single audio chunk (base64-encoded PCM).
  * This is used for one-shot TTS playback (HTTP mode).
@@ -1624,7 +631,7 @@ - (AVAudioPCMBuffer *)createPCMBufferFromData:(NSData *)data {
   @try {
     if (!b64 || b64.length == 0) {
       if (reject)
-        reject(@"audio_chunk_error", @"Empty audio chunk", nil);
+        reject(@"invalid_data", @"Empty audio chunk", nil);
       return;
     }
 
@@ -1632,7 +639,7 @@ - (AVAudioPCMBuffer *)createPCMBufferFromData:(NSData *)data {
                                                           options:0];
     if (!pcmData || pcmData.length == 0) {
       if (reject)
-        reject(@"audio_chunk_error", @"Failed to decode audio chunk", nil);
+        reject(@"invalid_data", @"Failed to decode audio chunk", nil);
       return;
     }
 
@@ -1643,7 +650,7 @@ - (AVAudioPCMBuffer *)createPCMBufferFromData:(NSData *)data {
                               ?: @"Failed to activate audio session";
       DGLogError(@"[Deepgram] playAudioChunk: activation failed %@", message);
       if (reject)
-        reject(@"audio_chunk_error", message, sessionError);
+        reject(@"playback_error", message, sessionError);
       return;
     }
 
@@ -1665,7 +672,7 @@ - (AVAudioPCMBuffer *)createPCMBufferFromData:(NSData *)data {
             @"[Deepgram] playAudioChunk: failed to setup audio engine: %@",
             engineError);
         if (reject)
-          reject(@"audio_chunk_error", @"Failed to setup audio engine",
+          reject(@"playback_error", @"Failed to setup audio engine",
                  engineError);
         return;
       }
@@ -1676,20 +683,30 @@ - (AVAudioPCMBuffer *)createPCMBufferFromData:(NSData *)data {
     if (!buffer) {
       DGLogError(@"[Deepgram] playAudioChunk: failed to create PCM buffer");
       if (reject)
-        reject(@"audio_chunk_error", @"Failed to create PCM buffer", nil);
+        reject(@"invalid_data", @"Failed to create PCM buffer", nil);
       return;
     }
 
     self.isPlaying = YES;
+    _scheduledBufferCount++;
+    int playbackGeneration = _playbackGeneration.load();
 
-    // Schedule buffer with completion handler to resolve promise
+    // Schedule buffer with completion handler to resolve promise. The session
+    // teardown is guarded by the playback generation and remaining buffer count
+    // (mirroring feedAudio) so a one-shot finishing mid-stream cannot deactivate
+    // the audio session while streaming playback is still active.
     __weak Deepgram *weakSelf = self;
     [self.playerNode scheduleBuffer:buffer
                   completionHandler:^{
                     Deepgram *strongSelf = weakSelf;
-                    if (strongSelf) {
-                      strongSelf.isPlaying = NO;
-                      [strongSelf maybeDeactivateAudioSession];
+                    if (strongSelf &&
+                        strongSelf->_playbackGeneration.load() ==
+                            playbackGeneration) {
+                      int remaining = --strongSelf->_scheduledBufferCount;
+                      if (remaining <= 0) {
+                        strongSelf.isPlaying = NO;
+                        [strongSelf maybeDeactivateAudioSession];
+                      }
                     }
                     if (resolve)
                       resolve(nil);
@@ -1704,8 +721,7 @@ - (AVAudioPCMBuffer *)createPCMBufferFromData:(NSData *)data {
                (unsigned long)pcmData.length);
   } @catch (NSException *e) {
     DGLogError(@"[Deepgram] playAudioChunk: exception %@", e);
-    if (reject)
-      reject(@"audio_chunk_error", e.reason, nil);
+    DGRejectPromise(reject, @"playback_error", e.reason, nil);
   }
 }
 
@@ -1718,6 +734,8 @@ - (void)invalidate {
     DGLogError(@"[Deepgram] invalidate: cleanupRecordingQueue exception %@", e);
   }
 
+  [self discardRecordingFile];
+
   self.pendingPCMBuffer = nil;
 
   if (self.playerNode) {
diff --git a/package.json b/package.json
index 3e5512d..97d567c 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "react-native-deepgram",
-  "version": "2.1.1",
+  "version": "2.2.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.ts",
   "main": "./lib/commonjs/index.js",
diff --git a/src/NativeDeepgram.ts b/src/NativeDeepgram.ts
index b491827..a54f5dd 100644
--- a/src/NativeDeepgram.ts
+++ b/src/NativeDeepgram.ts
@@ -1,5 +1,26 @@
 import { NativeModules } from 'react-native';
 
+/**
+ * Options for persisting the captured microphone audio to a file while it is
+ * simultaneously streamed to Deepgram.
+ */
+export interface RecordToFileOptions {
+  /** Enable writing the live microphone capture to a file. */
+  enabled: boolean;
+  /**
+   * Absolute destination path (with or without a `file://` prefix). When
+   * omitted, the native module writes to an app-specific location and returns
+   * the generated `file://` URI from {@link DeepgramNative.stopRecording}.
+   */
+  path?: string;
+  /**
+   * Container format for the recording. Only uncompressed `wav` (16 kHz PCM16
+   * mono) is currently supported; this mirrors the audio that is streamed to
+   * Deepgram.
+   */
+  format?: 'wav';
+}
+
 export interface StartRecordingOptions {
   /**
    * When `true`, the native module configures the platform's hardware echo
@@ -13,11 +34,27 @@ export interface StartRecordingOptions {
    * handling and prefer the unprocessed signal.
    */
   enableVoiceProcessing?: boolean;
+  /**
+   * When provided with `enabled: true`, the native module tees every captured
+   * PCM buffer into an audio file alongside the live Deepgram stream. The
+   * resulting `file://` URI is returned when recording stops via
+   * {@link DeepgramNative.stopRecording}.
+   */
+  recordToFile?: RecordToFileOptions;
+}
+
+/**
+ * Resolved value of {@link DeepgramNative.stopRecording}. Contains the captured
+ * file URI when `recordToFile` was enabled for the session; otherwise `null`.
+ */
+export interface DeepgramRecordingResult {
+  /** `file://` URI of the recorded audio file, when one was produced. */
+  recordingUri?: string;
 }
 
 interface DeepgramNative {
   startRecording(options?: StartRecordingOptions): Promise<void>;
-  stopRecording(): Promise<void>;
+  stopRecording(): Promise<DeepgramRecordingResult | null>;
   startAudio(): Promise<void>;
   stopAudio(): Promise<void>;
   playAudioChunk(chunk: string): Promise<void>;
@@ -26,6 +63,7 @@ interface DeepgramNative {
   interruptAudio?: () => void;
   stopPlayer(): void;
   startPlayer(sampleRate: number, channels?: number): void;
+  setMeteringEnabled?: (enabled: boolean, intervalMs?: number) => void;
 }
 
 const LINKING_ERROR = `react-native-deepgram: Native code not linked—did you run “pod install” & rebuild?`;
@@ -75,4 +113,9 @@ export const Deepgram: DeepgramNative = {
   startPlayer(sampleRate: number, channels?: number) {
     return NativeDeepgramModule.startPlayer(sampleRate, channels);
   },
+  setMeteringEnabled(enabled: boolean, intervalMs?: number) {
+    if (typeof NativeDeepgramModule.setMeteringEnabled === 'function') {
+      return NativeDeepgramModule.setMeteringEnabled(enabled, intervalMs);
+    }
+  },
 };
diff --git a/src/constants/deepgram.ts b/src/constants/deepgram.ts
index cfe2690..d0e9332 100644
--- a/src/constants/deepgram.ts
+++ b/src/constants/deepgram.ts
@@ -3,3 +3,43 @@ export const DEEPGRAM_BASEWSS = 'wss://api.deepgram.com/v1';
 
 export const DEEPGRAM_V2_BASEURL = 'https://api.deepgram.com/v2';
 export const DEEPGRAM_V2_BASEWSS = 'wss://api.deepgram.com/v2';
+
+export const DEEPGRAM_AGENT_URL = 'wss://agent.deepgram.com/v1/agent/converse';
+
+const stripTrailingSlashes = (value: string): string =>
+  value.replace(/\/+$/, '');
+
+const readOverride = (key: string): string | undefined => {
+  const value = (globalThis as any)[key];
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+};
+
+const deriveV2 = (v1: string): string =>
+  /\/v1$/.test(v1) ? v1.replace(/\/v1$/, '/v2') : v1;
+
+export const getBaseUrl = (): string =>
+  stripTrailingSlashes(
+    readOverride('__DEEPGRAM_BASE_URL__') ?? DEEPGRAM_BASEURL
+  );
+
+export const getBaseWss = (): string =>
+  stripTrailingSlashes(
+    readOverride('__DEEPGRAM_BASE_WSS__') ?? DEEPGRAM_BASEWSS
+  );
+
+export const getV2BaseUrl = (): string => {
+  const override = readOverride('__DEEPGRAM_BASE_URL__');
+  return stripTrailingSlashes(
+    override ? deriveV2(override) : DEEPGRAM_V2_BASEURL
+  );
+};
+
+export const getV2BaseWss = (): string => {
+  const override = readOverride('__DEEPGRAM_BASE_WSS__');
+  return stripTrailingSlashes(
+    override ? deriveV2(override) : DEEPGRAM_V2_BASEWSS
+  );
+};
+
+export const getAgentUrl = (): string =>
+  readOverride('__DEEPGRAM_AGENT_URL__') ?? DEEPGRAM_AGENT_URL;
diff --git a/src/helpers/auth.ts b/src/helpers/auth.ts
new file mode 100644
index 0000000..b820407
--- /dev/null
+++ b/src/helpers/auth.ts
@@ -0,0 +1,92 @@
+export type DeepgramTokenResult = {
+  token: string;
+  expiresInSeconds?: number;
+};
+
+export type DeepgramGetToken = () => Promise<DeepgramTokenResult>;
+
+const DEFAULT_TOKEN_TTL_SECONDS = 30;
+const REFRESH_RATIO = 0.8;
+
+type CachedToken = { header: string; expiresAt: number };
+
+let cachedToken: CachedToken | null = null;
+let inflight: Promise<string> | null = null;
+let tokenEpoch = 0;
+
+const withScheme = (raw: string, defaultScheme: 'Token' | 'Bearer'): string => {
+  const trimmed = raw.trim();
+  if (/^(Token|Bearer)\s+/i.test(trimmed)) {
+    return trimmed;
+  }
+  return `${defaultScheme} ${trimmed}`;
+};
+
+const readGetToken = (): DeepgramGetToken | undefined => {
+  const fn = (globalThis as any).__DEEPGRAM_GET_TOKEN__;
+  return typeof fn === 'function' ? (fn as DeepgramGetToken) : undefined;
+};
+
+const readApiKey = (): string | undefined => {
+  const key = (globalThis as any).__DEEPGRAM_API_KEY__;
+  return typeof key === 'string' && key.length > 0 ? key : undefined;
+};
+
+export const hasAuthConfigured = (): boolean =>
+  readGetToken() != null || readApiKey() != null;
+
+export const clearCachedAuthToken = (): void => {
+  cachedToken = null;
+  inflight = null;
+  tokenEpoch += 1;
+};
+
+export const resolveAuthHeader = async (): Promise<string> => {
+  const getToken = readGetToken();
+  if (getToken) {
+    const now = Date.now();
+    if (cachedToken && cachedToken.expiresAt > now) {
+      return cachedToken.header;
+    }
+    // Single-flight: concurrent callers share one in-flight token refresh.
+    if (!inflight) {
+      const epoch = tokenEpoch;
+      inflight = (async () => {
+        const result = await getToken();
+        const token = result?.token;
+        if (typeof token !== 'string' || token.length === 0) {
+          throw new Error('getToken did not return a token');
+        }
+        const ttlSeconds =
+          typeof result.expiresInSeconds === 'number' &&
+          result.expiresInSeconds > 0
+            ? result.expiresInSeconds
+            : DEFAULT_TOKEN_TTL_SECONDS;
+        const header = withScheme(token, 'Bearer');
+        // Refresh at 80% of the TTL to absorb clock skew / latency. Skip the
+        // write if the cache was cleared (re-configure/logout) mid-flight.
+        if (epoch === tokenEpoch) {
+          cachedToken = {
+            header,
+            expiresAt: Date.now() + ttlSeconds * REFRESH_RATIO * 1000,
+          };
+        }
+        return header;
+      })();
+    }
+    const current = inflight;
+    try {
+      return await current;
+    } finally {
+      if (inflight === current) {
+        inflight = null;
+      }
+    }
+  }
+
+  const apiKey = readApiKey();
+  if (!apiKey) {
+    throw new Error('Deepgram API key missing');
+  }
+  return withScheme(apiKey, 'Token');
+};
diff --git a/src/helpers/index.ts b/src/helpers/index.ts
index f4d0f17..95c3d66 100644
--- a/src/helpers/index.ts
+++ b/src/helpers/index.ts
@@ -3,3 +3,4 @@ export * from './url';
 export * from './audioUtils';
 export * from './useAsyncCall';
 export * from './createAgentSettings';
+export * from './auth';
diff --git a/src/index.ts b/src/index.ts
index d283863..9a6b3aa 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -4,14 +4,59 @@ export { useDeepgramManagement } from './useDeepgramManagement';
 export { useDeepgramTextToSpeech } from './useDeepgramTextToSpeech';
 export { useDeepgramVoiceAgent } from './useDeepgramVoiceAgent';
 export { Deepgram } from './NativeDeepgram';
+import type { DeepgramGetToken } from './helpers';
+import { clearCachedAuthToken } from './helpers';
 export {
   arrayBufferToBase64,
   createAudioPlayerController,
   useAsyncCall,
   createAgentSettings,
 } from './helpers';
+export type { DeepgramGetToken, DeepgramTokenResult } from './helpers';
+export { DeepgramError } from './types/errors';
 export type * from './types';
 
-export const configure = (opts: { apiKey: string }) => {
-  (globalThis as any).__DEEPGRAM_API_KEY__ = opts.apiKey;
+/**
+ * Options accepted by {@link configure}.
+ */
+export type DeepgramConfigureOptions = {
+  /**
+   * Deepgram API key used to authenticate REST and WebSocket requests. Optional
+   * when {@link DeepgramConfigureOptions.getToken} is provided.
+   */
+  apiKey?: string;
+  /**
+   * Override the REST base URL (must include the version segment, e.g.
+   * `https://api.beta.deepgram.com/v1` or a self-hosted host). Used for
+   * regional, Dedicated, and self-hosted deployments.
+   * @see https://developers.deepgram.com/reference/custom-endpoints
+   */
+  baseUrl?: string;
+  /**
+   * Override the streaming (WebSocket) base URL, e.g. `wss://my-host:8080/v1`.
+   */
+  baseWss?: string;
+  /** Override the Voice Agent socket URL. */
+  agentUrl?: string;
+  /**
+   * Provide short-lived tokens instead of embedding a long-lived API key in the
+   * app. Called on demand; the returned token is cached and refreshed before
+   * expiry. Takes precedence over `apiKey` when set.
+   *
+   * Typically fetches a token from your backend, which proxies Deepgram's
+   * `/auth/grant` endpoint. Note: the Management API does not accept temporary
+   * tokens, so `useDeepgramManagement` still requires `apiKey`.
+   * @see https://developers.deepgram.com/guides/fundamentals/token-based-authentication
+   */
+  getToken?: DeepgramGetToken;
+};
+
+export const configure = (opts: DeepgramConfigureOptions) => {
+  const g = globalThis as any;
+  g.__DEEPGRAM_API_KEY__ = opts.apiKey;
+  g.__DEEPGRAM_BASE_URL__ = opts.baseUrl;
+  g.__DEEPGRAM_BASE_WSS__ = opts.baseWss;
+  g.__DEEPGRAM_AGENT_URL__ = opts.agentUrl;
+  g.__DEEPGRAM_GET_TOKEN__ = opts.getToken;
+  clearCachedAuthToken();
 };
diff --git a/src/types/deepgram/shared.ts b/src/types/deepgram/shared.ts
index a6d3752..7e6d43f 100644
--- a/src/types/deepgram/shared.ts
+++ b/src/types/deepgram/shared.ts
@@ -9,3 +9,19 @@ export type DeepgramCallbackMethod = 'POST' | 'PUT' | (string & {});
  * - `strict`: Limits the model to only the provided vocabulary.
  */
 export type DeepgramCustomMode = 'extended' | 'strict';
+
+/**
+ * Auto-reconnect configuration for live streaming sockets (STT & Voice Agent).
+ * Opt-in and non-breaking: reconnect is disabled unless `enabled` is set.
+ * @see https://developers.deepgram.com/docs/recovering-from-connection-errors-and-timeouts-when-live-streaming-audio
+ */
+export type DeepgramReconnectOptions = {
+  /** Enable automatic reconnect on unexpected socket close. @default false */
+  enabled?: boolean;
+  /** Maximum number of reconnect attempts before giving up. @default 5 */
+  maxRetries?: number;
+  /** Initial backoff delay in milliseconds. @default 500 */
+  initialDelayMs?: number;
+  /** Maximum backoff delay in milliseconds. @default 10000 */
+  maxDelayMs?: number;
+};
diff --git a/src/types/deepgram/speech-to-text.ts b/src/types/deepgram/speech-to-text.ts
index ecf6326..17cba80 100644
--- a/src/types/deepgram/speech-to-text.ts
+++ b/src/types/deepgram/speech-to-text.ts
@@ -1,4 +1,8 @@
-import type { DeepgramCallbackMethod, DeepgramCustomMode } from './shared';
+import type {
+  DeepgramCallbackMethod,
+  DeepgramCustomMode,
+  DeepgramReconnectOptions,
+} from './shared';
 
 /**
  * Audio encoding formats supported by Deepgram's Live Listen API.
@@ -390,6 +394,63 @@ export type UseDeepgramSpeechToTextProps = {
 
   /** Automatically accumulate transcript results. @default false */
   trackTranscript?: boolean;
+
+  /**
+   * Microphone audio-level (metering) configuration. When enabled the native
+   * module emits a normalized RMS amplitude (0..1) while recording, surfaced
+   * via {@link UseDeepgramSpeechToTextReturn.audioLevel} (when `trackState` is
+   * on) and the {@link onAudioLevel} callback. Disabled by default.
+   */
+  metering?: {
+    /** Enable audio-level events while listening. @default false */
+    enabled?: boolean;
+    /** Minimum interval between level events, in ms. @default 100 */
+    intervalMs?: number;
+  };
+  /**
+   * Called with the latest microphone audio level (normalized RMS, 0..1) while
+   * listening. Only invoked when `metering.enabled` is true.
+   */
+  onAudioLevel?: (level: number) => void;
+
+  /**
+   * Persist the captured microphone audio to a file while it is simultaneously
+   * streamed to Deepgram. The resulting `file://` URI is delivered via
+   * {@link onRecordingComplete} and
+   * {@link UseDeepgramSpeechToTextReturn.recordingUri} (when `trackState` is on)
+   * once {@link UseDeepgramSpeechToTextReturn.stopListening} completes.
+   */
+  recordToFile?: {
+    /** Enable writing the live capture to a file. @default false */
+    enabled?: boolean;
+    /**
+     * Absolute destination path (with or without a `file://` prefix). When
+     * omitted, the native module writes to an app-specific location and reports
+     * the generated `file://` URI.
+     */
+    path?: string;
+    /**
+     * Container format. Only uncompressed `wav` (16 kHz PCM16 mono, mirroring
+     * the streamed audio) is currently supported.
+     */
+    format?: 'wav';
+  };
+  /**
+   * Called once a record-to-file session finishes (after `stopListening`) with
+   * the `file://` URI of the captured WAV. Only invoked when
+   * `recordToFile.enabled` is true and a file was produced.
+   */
+  onRecordingComplete?: (uri: string) => void;
+
+  /**
+   * Auto-reconnect configuration for the live streaming socket. Disabled by
+   * default; set `reconnect.enabled` to opt in.
+   */
+  reconnect?: DeepgramReconnectOptions;
+  /** Called when a reconnect attempt begins (1-based attempt number). */
+  onReconnecting?: (attempt: number) => void;
+  /** Called once the live socket has successfully reconnected. */
+  onReconnected?: () => void;
 };
 
 /**
@@ -405,13 +466,33 @@ export type UseDeepgramSpeechToTextReturn = {
     file: DeepgramPrerecordedSource,
     options?: DeepgramPrerecordedOptions
   ) => Promise<void>;
-
+  /**
+   * Pause streaming: stop forwarding mic frames without tearing down the
+   * socket. Sends `Finalize` once (v1) to flush buffered audio and starts a
+   * periodic `KeepAlive` so the connection survives the pause.
+   */
+  pause: () => void;
+  /** Resume streaming after {@link pause}: forward mic frames again. */
+  resume: () => void;
   /** Current state of the transcription session (if trackState is enabled) */
   state?: {
     status: 'idle' | 'loading' | 'listening' | 'transcribing' | 'error';
     error: Error | null;
   };
-
+  /** Whether streaming is currently paused (only returned when trackState is enabled) */
+  isPaused?: boolean;
+  /**
+   * Latest microphone audio level (normalized RMS, 0..1). Only returned when
+   * both `trackState` and `metering.enabled` are on; updates at most once per
+   * `metering.intervalMs` while listening.
+   */
+  audioLevel?: number;
+  /**
+   * `file://` URI of the most recent record-to-file capture. Only returned when
+   * `trackState` is on; populated once `stopListening` completes for a session
+   * started with `recordToFile.enabled`.
+   */
+  recordingUri?: string;
   /** Final accumulated transcript (only returned when trackTranscript is enabled) */
   transcript?: string;
   /** Interim/partial transcript (only returned when trackTranscript is enabled for live) */
diff --git a/src/types/deepgram/text-to-speech.ts b/src/types/deepgram/text-to-speech.ts
index 2aa92c4..0fedb89 100644
--- a/src/types/deepgram/text-to-speech.ts
+++ b/src/types/deepgram/text-to-speech.ts
@@ -287,6 +287,18 @@ export type DeepgramTextToSpeechStreamResponseMessage =
   | DeepgramTextToSpeechStreamErrorMessage
   | ({ type: string } & Record<string, unknown>);
 
+/**
+ * Synthesized audio returned by `synthesizeToBytes`: the raw audio bytes plus
+ * the MIME type describing their container/encoding (from the response
+ * `Content-Type`, or derived from the requested format).
+ */
+export type DeepgramTextToSpeechBytes = {
+  /** The synthesized audio as raw bytes. */
+  data: ArrayBuffer;
+  /** MIME type describing the audio container/encoding (e.g. `audio/mpeg`). */
+  mimeType: string;
+};
+
 /**
  * Props for the `useDeepgramTextToSpeech` hook.
  */
@@ -339,6 +351,17 @@ export type UseDeepgramTextToSpeechProps = {
 export type UseDeepgramTextToSpeechReturn = {
   /** One-shot HTTP request that resolves when the full audio is ready. */
   synthesize: (text: string) => Promise<ArrayBuffer>;
+  /**
+   * Synthesize speech and return the raw audio bytes (plus MIME type) without
+   * playing them — useful for persisting/caching audio. Results are cached
+   * in-memory (LRU) keyed by the text + resolved format, so repeated identical
+   * prompts avoid a duplicate network request. Pass `options` to override the
+   * hook's HTTP format per call.
+   */
+  synthesizeToBytes: (
+    text: string,
+    options?: DeepgramTextToSpeechHttpOptions
+  ) => Promise<DeepgramTextToSpeechBytes>;
   /** Opens a WebSocket and begins streaming audio chunks in real-time. */
   startStreaming: (text: string) => Promise<void>;
   /** Send arbitrary control messages to the active WebSocket stream. */
diff --git a/src/types/errors.ts b/src/types/errors.ts
new file mode 100644
index 0000000..749668c
--- /dev/null
+++ b/src/types/errors.ts
@@ -0,0 +1,96 @@
+/**
+ * Stable error-code contract shared by the native module (iOS + Android) and
+ * the JS hooks. Every native promise rejection uses one of these codes, so
+ * consumers can branch on a typed `code` instead of string-matching messages.
+ *
+ * Keep this union in lock-step with the native reject codes:
+ *   - iOS:     `DGRejectPromise(reject, "<code>", ...)` (ios/DGSupport.h)
+ *   - Android: `promise.reject("<code>", ...)` (DeepgramModule.kt / AudioPlayer.kt)
+ *
+ * @see https://developers.deepgram.com/docs/errors
+ */
+export type DeepgramErrorCode =
+  | 'permission_denied'
+  | 'init_failed'
+  | 'start_error'
+  | 'stop_error'
+  | 'audio_start_error'
+  | 'audio_stop_error'
+  | 'stop_player_error'
+  | 'invalid_data'
+  | 'playback_error';
+
+const DEEPGRAM_ERROR_CODES: ReadonlySet<string> = new Set<DeepgramErrorCode>([
+  'permission_denied',
+  'init_failed',
+  'start_error',
+  'stop_error',
+  'audio_start_error',
+  'audio_stop_error',
+  'stop_player_error',
+  'invalid_data',
+  'playback_error',
+]);
+
+/**
+ * Error surfaced by the Deepgram hooks. Wraps native promise rejections, fetch
+ * failures and WebSocket errors with a typed {@link DeepgramErrorCode} so apps
+ * can handle failures programmatically. The original failure is preserved on
+ * {@link DeepgramError.cause}.
+ *
+ * @example
+ * ```ts
+ * onError: (err) => {
+ *   if (err instanceof DeepgramError && err.code === 'permission_denied') {
+ *     // prompt the user to grant microphone access
+ *   }
+ * }
+ * ```
+ */
+export class DeepgramError extends Error {
+  /** Typed reject code, or `'unknown'` when it can't be mapped to the contract. */
+  readonly code: DeepgramErrorCode | 'unknown';
+
+  constructor(
+    message: string,
+    code: DeepgramErrorCode | 'unknown' = 'unknown',
+    options?: { cause?: unknown }
+  ) {
+    super(message, options);
+    this.name = 'DeepgramError';
+    this.code = code;
+    // Restore the prototype chain so `instanceof DeepgramError` holds even when
+    // the library is transpiled below ES2015 (react-native-builder-bob/Babel).
+    Object.setPrototypeOf(this, DeepgramError.prototype);
+  }
+}
+
+const isDeepgramErrorCode = (value: unknown): value is DeepgramErrorCode =>
+  typeof value === 'string' && DEEPGRAM_ERROR_CODES.has(value);
+
+/**
+ * Normalize an unknown error into a {@link DeepgramError}. React Native surfaces
+ * native promise rejections as an `Error`-like object carrying the reject
+ * `code` (e.g. `'start_error'`); this reads that code when present, otherwise
+ * falls back to `'unknown'`. The original value is preserved as `cause`.
+ *
+ * Idempotent: passing an existing {@link DeepgramError} returns it unchanged.
+ */
+export const toDeepgramError = (err: unknown): DeepgramError => {
+  if (err instanceof DeepgramError) {
+    return err;
+  }
+
+  if (err != null && typeof err === 'object') {
+    const maybe = err as { code?: unknown; message?: unknown };
+    const code = isDeepgramErrorCode(maybe.code) ? maybe.code : 'unknown';
+    const message =
+      typeof maybe.message === 'string' && maybe.message.length > 0
+        ? maybe.message
+        : String(err);
+    return new DeepgramError(message, code, { cause: err });
+  }
+
+  const message = typeof err === 'string' && err.length > 0 ? err : String(err);
+  return new DeepgramError(message, 'unknown', { cause: err });
+};
diff --git a/src/types/index.ts b/src/types/index.ts
index f2b4d3d..2b8d331 100644
--- a/src/types/index.ts
+++ b/src/types/index.ts
@@ -1 +1,2 @@
 export * from './deepgram';
+export * from './errors';
diff --git a/src/useDeepgramManagement.ts b/src/useDeepgramManagement.ts
index 412432b..9b7aa01 100644
--- a/src/useDeepgramManagement.ts
+++ b/src/useDeepgramManagement.ts
@@ -18,7 +18,7 @@ import type {
   DeepgramGrantTokenResponse,
   UseDeepgramManagementReturn,
 } from './types/deepgram';
-import { DEEPGRAM_BASEURL } from './constants';
+import { getBaseUrl } from './constants';
 import { dgPath } from './helpers';
 
 /**
@@ -48,7 +48,7 @@ export function useDeepgramManagement(): UseDeepgramManagementReturn {
       if (!key) throw new Error('Deepgram API key missing');
 
       try {
-        const res = await fetch(`${DEEPGRAM_BASEURL}${path}`, {
+        const res = await fetch(`${getBaseUrl()}${path}`, {
           signal: ctrl.signal,
           headers: { Authorization: `Token ${key}`, ...(init.headers || {}) },
           ...init,
diff --git a/src/useDeepgramSpeechToText.ts b/src/useDeepgramSpeechToText.ts
index 896b415..2285d54 100644
--- a/src/useDeepgramSpeechToText.ts
+++ b/src/useDeepgramSpeechToText.ts
@@ -10,16 +10,22 @@ import type {
   UseDeepgramSpeechToTextProps,
   UseDeepgramSpeechToTextReturn,
 } from './types';
-import {
-  DEEPGRAM_BASEURL,
-  DEEPGRAM_BASEWSS,
-  DEEPGRAM_V2_BASEWSS,
-} from './constants';
-import { buildParams } from './helpers';
+import { getBaseUrl, getBaseWss, getV2BaseWss } from './constants';
+import { buildParams, resolveAuthHeader, hasAuthConfigured } from './helpers';
+import { toDeepgramError } from './types';
 
 const DEFAULT_SAMPLE_RATE = 16_000;
 const BASE_NATIVE_SAMPLE_RATE = 16_000;
 
+const KEEPALIVE_INTERVAL_MS = 5_000;
+
+const DEFAULT_RECONNECT = {
+  enabled: false,
+  maxRetries: 5,
+  initialDelayMs: 500,
+  maxDelayMs: 10_000,
+};
+
 let cachedEmitter: NativeEventEmitter | null = null;
 const getEmitter = (): NativeEventEmitter => {
   if (!cachedEmitter) {
@@ -32,6 +38,12 @@ const AUDIO_EVENT = Platform.select({
   android: 'AudioChunk',
   default: 'DeepgramAudioPCM',
 }) as string;
+const AUDIO_LEVEL_EVENT = Platform.select({
+  ios: 'DeepgramAudioLevel',
+  android: 'AudioLevel',
+  default: 'DeepgramAudioLevel',
+}) as string;
+const DEFAULT_METERING_INTERVAL_MS = 100;
 
 const computeDownsampleFactor = (
   target: number | undefined,
@@ -72,6 +84,13 @@ export function useDeepgramSpeechToText({
   prerecorded = {},
   trackState = false,
   trackTranscript = false,
+  metering = {},
+  onAudioLevel = () => {},
+  recordToFile = {},
+  onRecordingComplete = () => {},
+  reconnect = {},
+  onReconnecting = () => {},
+  onReconnected = () => {},
 }: UseDeepgramSpeechToTextProps = {}): UseDeepgramSpeechToTextReturn {
   const [internalState, setInternalState] = useState<{
     status: 'idle' | 'loading' | 'listening' | 'transcribing' | 'error';
@@ -84,7 +103,20 @@ export function useDeepgramSpeechToText({
   const audioSub = useRef<ReturnType<NativeEventEmitter['addListener']> | null>(
     null
   );
+  const meterSub = useRef<ReturnType<NativeEventEmitter['addListener']> | null>(
+    null
+  );
   const apiVersionRef = useRef<'v1' | 'v2'>('v1');
+  const pausedRef = useRef(false);
+  const keepAliveTimerRef = useRef<ReturnType<typeof setInterval> | null>(null);
+  const userClosedRef = useRef(false);
+  const reconnectAttemptRef = useRef(0);
+  const reconnectingRef = useRef(false);
+  const reconnectTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const wsGenerationRef = useRef(0);
+  const liveUrlRef = useRef('');
+  const reconnectConfigRef = useRef({ ...DEFAULT_RECONNECT });
+  const connectSocketRef = useRef<() => void>(() => {});
   const nativeInputSampleRateRef = useRef(BASE_NATIVE_SAMPLE_RATE);
   const targetSampleRateRef = useRef(DEFAULT_SAMPLE_RATE);
   const downsampleFactorRef = useRef(1);
@@ -99,6 +131,8 @@ export function useDeepgramSpeechToText({
   const onBeforeTranscribeRef = useRef(onBeforeTranscribe);
   const onTranscribeSuccessRef = useRef(onTranscribeSuccess);
   const onTranscribeErrorRef = useRef(onTranscribeError);
+  const onReconnectingRef = useRef(onReconnecting);
+  const onReconnectedRef = useRef(onReconnected);
 
   onTranscriptRef.current = onTranscript;
   onErrorRef.current = onError;
@@ -108,19 +142,64 @@ export function useDeepgramSpeechToText({
   onBeforeTranscribeRef.current = onBeforeTranscribe;
   onTranscribeSuccessRef.current = onTranscribeSuccess;
   onTranscribeErrorRef.current = onTranscribeError;
+  onReconnectingRef.current = onReconnecting;
+  onReconnectedRef.current = onReconnected;
+  reconnectConfigRef.current = { ...DEFAULT_RECONNECT, ...reconnect };
+
+  const onAudioLevelRef = useRef(onAudioLevel);
+  onAudioLevelRef.current = onAudioLevel;
+  const onRecordingCompleteRef = useRef(onRecordingComplete);
+  onRecordingCompleteRef.current = onRecordingComplete;
+  const recordToFileRef = useRef(recordToFile);
+  recordToFileRef.current = recordToFile;
+  const meteringEnabled = metering.enabled === true;
+  const meteringIntervalMs =
+    typeof metering.intervalMs === 'number' && metering.intervalMs > 0
+      ? metering.intervalMs
+      : DEFAULT_METERING_INTERVAL_MS;
 
   const [internalTranscript, setInternalTranscript] = useState('');
   const [internalInterimTranscript, setInternalInterimTranscript] =
     useState('');
+  const [internalIsPaused, setInternalIsPaused] = useState(false);
+  const [internalAudioLevel, setInternalAudioLevel] = useState(0);
+  const [internalRecordingUri, setInternalRecordingUri] = useState<
+    string | undefined
+  >(undefined);
 
   const endFiredRef = useRef(false);
 
   const closeResources = useCallback(() => {
+    if (keepAliveTimerRef.current != null) {
+      clearInterval(keepAliveTimerRef.current);
+      keepAliveTimerRef.current = null;
+    }
+    if (reconnectTimerRef.current != null) {
+      clearTimeout(reconnectTimerRef.current);
+      reconnectTimerRef.current = null;
+    }
+    reconnectingRef.current = false;
+    pausedRef.current = false;
     if (audioSub.current) {
       audioSub.current.remove();
       audioSub.current = null;
     }
-    Deepgram.stopRecording().catch(() => {});
+    if (meterSub.current) {
+      meterSub.current.remove();
+      meterSub.current = null;
+    }
+    Deepgram.setMeteringEnabled?.(false, 0);
+    Deepgram.stopRecording()
+      .then((result) => {
+        const uri = result?.recordingUri;
+        if (uri) {
+          onRecordingCompleteRef.current?.(uri);
+          if (trackState) {
+            setInternalRecordingUri(uri);
+          }
+        }
+      })
+      .catch(() => {});
     nativeInputSampleRateRef.current = BASE_NATIVE_SAMPLE_RATE;
     targetSampleRateRef.current = DEFAULT_SAMPLE_RATE;
     downsampleFactorRef.current = 1;
@@ -139,6 +218,8 @@ export function useDeepgramSpeechToText({
     apiVersionRef.current = 'v1';
     if (trackState) {
       setInternalState((prev) => ({ ...prev, status: 'idle' }));
+      setInternalIsPaused(false);
+      setInternalAudioLevel(0);
     }
     if (trackTranscript) {
       setInternalTranscript('');
@@ -199,13 +280,194 @@ export function useDeepgramSpeechToText({
     [trackTranscript]
   );
 
+  const handleDisconnect = useCallback(
+    (event?: { code?: number }, failureError?: Error) => {
+      const cfg = reconnectConfigRef.current;
+      const shouldReconnect =
+        !userClosedRef.current &&
+        cfg.enabled &&
+        event?.code !== 1000 &&
+        reconnectAttemptRef.current < cfg.maxRetries;
+
+      if (shouldReconnect) {
+        const attempt = reconnectAttemptRef.current;
+        reconnectAttemptRef.current = attempt + 1;
+        reconnectingRef.current = true;
+
+        const backoff = Math.min(
+          cfg.maxDelayMs,
+          cfg.initialDelayMs * 2 ** attempt
+        );
+        const delay = backoff + Math.random() * backoff * 0.25;
+
+        if (trackState) {
+          setInternalState({ status: 'loading', error: null });
+        }
+        onReconnectingRef.current(attempt + 1);
+
+        if (reconnectTimerRef.current != null) {
+          clearTimeout(reconnectTimerRef.current);
+        }
+        reconnectTimerRef.current = setTimeout(() => {
+          reconnectTimerRef.current = null;
+          connectSocketRef.current();
+        }, delay);
+        return;
+      }
+
+      const exhausted =
+        !userClosedRef.current &&
+        cfg.enabled &&
+        reconnectAttemptRef.current >= cfg.maxRetries;
+
+      closeResources();
+
+      if (exhausted) {
+        const err = toDeepgramError(
+          new Error(
+            `Deepgram reconnect failed after ${cfg.maxRetries} attempts`
+          )
+        );
+        onErrorRef.current(err);
+        if (trackState) {
+          setInternalState({ status: 'error', error: err });
+        }
+      } else if (failureError && trackState) {
+        setInternalState({
+          status: 'error',
+          error: toDeepgramError(failureError),
+        });
+      }
+
+      fireEnd();
+    },
+    [closeResources, fireEnd, trackState]
+  );
+
+  const connectSocket = useCallback(() => {
+    const isV2 = apiVersionRef.current === 'v2';
+    const generation = wsGenerationRef.current + 1;
+    wsGenerationRef.current = generation;
+
+    resolveAuthHeader()
+      .then((authHeader) => {
+        // A newer connection attempt superseded this one while the auth token
+        // was resolving — abandon this stale socket setup.
+        if (generation !== wsGenerationRef.current) {
+          return;
+        }
+
+        let socket: WebSocket;
+        try {
+          socket = new (WebSocket as any)(liveUrlRef.current, undefined, {
+            headers: { Authorization: authHeader },
+          });
+        } catch {
+          handleDisconnect();
+          return;
+        }
+        ws.current = socket;
+
+        socket.onopen = () => {
+          if (generation !== wsGenerationRef.current) return;
+          const wasReconnecting = reconnectingRef.current;
+          reconnectingRef.current = false;
+          reconnectAttemptRef.current = 0;
+          onStartRef.current();
+          if (wasReconnecting) {
+            onReconnectedRef.current();
+          }
+          if (trackState) {
+            setInternalState({ status: 'listening', error: null });
+          }
+        };
+
+        socket.onmessage = (ev: any) => {
+          if (generation !== wsGenerationRef.current) return;
+          if (typeof ev.data === 'string') {
+            try {
+              const msg = JSON.parse(ev.data);
+              if (isV2) {
+                // Flux (v2) message envelope reference:
+                // https://developers.deepgram.com/reference/speech-to-text-api/listen-flux
+                // - "Connected"        — handshake ack (no transcript)
+                // - "TurnInfo"         — carries transcript + an `event` field
+                //   ("Update" | "StartOfTurn" | "EagerEndOfTurn"
+                //    | "TurnResumed" | "EndOfTurn")
+                // - "ConfigureSuccess" / "ConfigureFailure"
+                // - "Error"            — fatal stream error
+                if (msg.type === 'Error') {
+                  const description =
+                    msg.description || 'Deepgram stream error';
+                  const streamError = toDeepgramError(new Error(description));
+                  onErrorRef.current(streamError);
+                  // Fatal stream error: tear down without auto-reconnecting.
+                  userClosedRef.current = true;
+                  closeResources();
+                  if (trackState) {
+                    setInternalState({
+                      status: 'error',
+                      error: streamError,
+                    });
+                  }
+                  fireEnd();
+                  return;
+                }
+
+                if (msg.type !== 'TurnInfo') {
+                  return;
+                }
+
+                const transcript = msg.transcript;
+                if (typeof transcript === 'string' && transcript.length > 0) {
+                  const isFinal = msg.event === 'EndOfTurn';
+                  emitTranscript(transcript, isFinal, msg);
+                }
+                return;
+              }
+
+              const transcript = msg.channel?.alternatives?.[0]?.transcript;
+              if (typeof transcript === 'string') {
+                const isFinal =
+                  msg.is_final === true || msg.speech_final === true;
+                emitTranscript(transcript, Boolean(isFinal), msg);
+              }
+            } catch {}
+          }
+        };
+
+        socket.onerror = (err: any) => {
+          if (generation !== wsGenerationRef.current) return;
+          onErrorRef.current(toDeepgramError(err));
+        };
+
+        socket.onclose = (event: any) => {
+          if (generation !== wsGenerationRef.current) return;
+          handleDisconnect(event);
+        };
+      })
+      .catch((err) => {
+        if (generation !== wsGenerationRef.current) return;
+        const authError = toDeepgramError(err);
+        onErrorRef.current(authError);
+        handleDisconnect(undefined, authError);
+      });
+  }, [closeResources, emitTranscript, fireEnd, handleDisconnect, trackState]);
+
+  connectSocketRef.current = connectSocket;
+
   const startListening = useCallback(
     async (overrideOptions: DeepgramLiveListenOptions = {}) => {
       try {
         onBeforeStartRef.current();
         endFiredRef.current = false;
+        pausedRef.current = false;
+        userClosedRef.current = false;
+        reconnectAttemptRef.current = 0;
+        reconnectingRef.current = false;
         if (trackState) {
           setInternalState({ status: 'loading', error: null });
+          setInternalIsPaused(false);
         }
         lastPartialTranscriptRef.current = '';
         lastFinalTranscriptRef.current = '';
@@ -213,10 +475,27 @@ export function useDeepgramSpeechToText({
         const granted = await askMicPermission();
         if (!granted) throw new Error('Microphone permission denied');
 
-        await Deepgram.startRecording();
+        const rtf = recordToFileRef.current;
+        if (trackState) {
+          setInternalRecordingUri(undefined);
+        }
+        await Deepgram.startRecording(
+          rtf.enabled === true
+            ? {
+                recordToFile: {
+                  enabled: true,
+                  path: rtf.path,
+                  format: rtf.format,
+                },
+              }
+            : undefined
+        );
+
+        if (!hasAuthConfigured()) throw new Error('Deepgram API key missing');
 
-        const apiKey = (globalThis as any).__DEEPGRAM_API_KEY__;
-        if (!apiKey) throw new Error('Deepgram API key missing');
+        if (meteringEnabled) {
+          Deepgram.setMeteringEnabled?.(true, meteringIntervalMs);
+        }
 
         const requestedVersion: 'v1' | 'v2' =
           overrideOptions.apiVersion ?? live.apiVersion ?? 'v1';
@@ -322,23 +601,18 @@ export function useDeepgramSpeechToText({
 
         const params = buildParams(query);
 
-        const baseWss = isV2 ? DEEPGRAM_V2_BASEWSS : DEEPGRAM_BASEWSS;
+        const baseWss = isV2 ? getV2BaseWss() : getBaseWss();
         const baseListenUrl = `${baseWss}/listen`;
         const url = params ? `${baseListenUrl}?${params}` : baseListenUrl;
 
-        ws.current = new (WebSocket as any)(url, undefined, {
-          headers: { Authorization: `Token ${apiKey}` },
-        });
-        const socket = ws.current as WebSocket;
+        liveUrlRef.current = url;
 
-        socket.onopen = () => {
-          onStartRef.current();
-          if (trackState) {
-            setInternalState({ status: 'listening', error: null });
-          }
-        };
+        connectSocket();
 
         audioSub.current = getEmitter().addListener(AUDIO_EVENT, (ev: any) => {
+          if (pausedRef.current) {
+            return;
+          }
           if (typeof ev?.sampleRate === 'number' && ev.sampleRate > 0) {
             if (ev.sampleRate !== nativeInputSampleRateRef.current) {
               nativeInputSampleRateRef.current = ev.sampleRate;
@@ -363,97 +637,111 @@ export function useDeepgramSpeechToText({
           }
         });
 
-        socket.onmessage = (ev: any) => {
-          if (typeof ev.data === 'string') {
-            try {
-              const msg = JSON.parse(ev.data);
-              if (isV2) {
-                // Flux (v2) message envelope reference:
-                // https://developers.deepgram.com/reference/speech-to-text-api/listen-flux
-                // - "Connected"        — handshake ack (no transcript)
-                // - "TurnInfo"         — carries transcript + an `event` field
-                //   ("Update" | "StartOfTurn" | "EagerEndOfTurn"
-                //    | "TurnResumed" | "EndOfTurn")
-                // - "ConfigureSuccess" / "ConfigureFailure"
-                // - "Error"            — fatal stream error
-                if (msg.type === 'Error') {
-                  const description =
-                    msg.description || 'Deepgram stream error';
-                  onErrorRef.current(new Error(description));
-                  if (trackState) {
-                    setInternalState({
-                      status: 'error',
-                      error: new Error(description),
-                    });
-                  }
-                  closeResources();
-                  return;
-                }
-
-                if (msg.type !== 'TurnInfo') {
-                  return;
-                }
-
-                const transcript = msg.transcript;
-                if (typeof transcript === 'string' && transcript.length > 0) {
-                  const isFinal = msg.event === 'EndOfTurn';
-                  emitTranscript(transcript, isFinal, msg);
-                }
-                return;
-              }
-
-              const transcript = msg.channel?.alternatives?.[0]?.transcript;
-              if (typeof transcript === 'string') {
-                const isFinal =
-                  msg.is_final === true || msg.speech_final === true;
-                emitTranscript(transcript, Boolean(isFinal), msg);
+        if (meteringEnabled) {
+          meterSub.current = getEmitter().addListener(
+            AUDIO_LEVEL_EVENT,
+            (ev: any) => {
+              const level =
+                typeof ev?.level === 'number' && Number.isFinite(ev.level)
+                  ? ev.level
+                  : 0;
+              if (trackState) {
+                setInternalAudioLevel(level);
               }
-            } catch {}
-          }
-        };
-
-        socket.onerror = (err: any) => {
-          onErrorRef.current(err);
-          if (trackState) {
-            setInternalState({
-              status: 'error',
-              error: err instanceof Error ? err : new Error(String(err)),
-            });
-          }
-        };
-        socket.onclose = () => {
-          closeResources();
-          fireEnd();
-        };
+              onAudioLevelRef.current(level);
+            }
+          );
+        }
       } catch (err) {
-        onErrorRef.current(err);
+        const dgError = toDeepgramError(err);
+        onErrorRef.current(dgError);
         if (trackState) {
           setInternalState({
             status: 'error',
-            error: err instanceof Error ? err : new Error(String(err)),
+            error: dgError,
           });
         }
         closeResources();
       }
     },
-    [emitTranscript, live, closeResources, trackState, fireEnd]
+    [
+      connectSocket,
+      live,
+      trackState,
+      closeResources,
+      meteringEnabled,
+      meteringIntervalMs,
+    ]
   );
 
   const stopListening = useCallback(() => {
     try {
+      userClosedRef.current = true;
       closeResources();
       fireEnd();
     } catch (err) {
-      onErrorRef.current(err);
+      const dgError = toDeepgramError(err);
+      onErrorRef.current(dgError);
       if (trackState) {
         setInternalState({
           status: 'error',
-          error: err instanceof Error ? err : new Error(String(err)),
+          error: dgError,
         });
       }
     }
   }, [closeResources, trackState, fireEnd]);
 
+  const pause = useCallback(() => {
+    if (pausedRef.current) {
+      return;
+    }
+    pausedRef.current = true;
+
+    const socket = ws.current;
+    if (socket && socket.readyState === WebSocket.OPEN) {
+      // Finalize flushes buffered audio so trailing words come back as a final
+      // result. Flux (v2) is turn-based and has no Finalize control message, so
+      // only send it on the v1 streaming API.
+      if (apiVersionRef.current !== 'v2') {
+        try {
+          socket.send(JSON.stringify({ type: 'Finalize' }));
+        } catch {}
+      }
+    }
+
+    if (keepAliveTimerRef.current == null) {
+      keepAliveTimerRef.current = setInterval(() => {
+        const s = ws.current;
+        if (!s || s.readyState !== WebSocket.OPEN) {
+          return;
+        }
+        try {
+          s.send(JSON.stringify({ type: 'KeepAlive' }));
+        } catch {}
+      }, KEEPALIVE_INTERVAL_MS);
+    }
+
+    if (trackState) {
+      setInternalIsPaused(true);
+    }
+  }, [trackState]);
+
+  const resume = useCallback(() => {
+    if (!pausedRef.current) {
+      return;
+    }
+    pausedRef.current = false;
+
+    if (keepAliveTimerRef.current != null) {
+      clearInterval(keepAliveTimerRef.current);
+      keepAliveTimerRef.current = null;
+    }
+
+    if (trackState) {
+      setInternalIsPaused(false);
+    }
+  }, [trackState]);
+
   const transcribeFile = useCallback(
     async (
       file: DeepgramPrerecordedSource,
@@ -464,8 +752,7 @@ export function useDeepgramSpeechToText({
         setInternalState({ status: 'transcribing', error: null });
       }
       try {
-        const apiKey = (globalThis as any).__DEEPGRAM_API_KEY__;
-        if (!apiKey) throw new Error('Deepgram API key missing');
+        const authHeader = await resolveAuthHeader();
 
         const merged: DeepgramPrerecordedOptions = {
           ...prerecorded,
@@ -545,11 +832,11 @@ export function useDeepgramSpeechToText({
         }
 
         const params = buildParams(query);
-        const baseUrl = `${DEEPGRAM_BASEURL}/listen`;
+        const baseUrl = `${getBaseUrl()}/listen`;
         const url = params ? `${baseUrl}?${params}` : baseUrl;
 
         const headers: Record<string, string> = {
-          Authorization: `Token ${apiKey}`,
+          Authorization: authHeader,
         };
 
         let body: FormData | string;
@@ -596,11 +883,12 @@ export function useDeepgramSpeechToText({
           throw new Error('No transcript present in Deepgram response');
         }
       } catch (err) {
-        onTranscribeErrorRef.current(err);
+        const dgError = toDeepgramError(err);
+        onTranscribeErrorRef.current(dgError);
         if (trackState) {
           setInternalState({
             status: 'error',
-            error: err instanceof Error ? err : new Error(String(err)),
+            error: dgError,
           });
         }
       }
@@ -608,13 +896,30 @@ export function useDeepgramSpeechToText({
     [prerecorded, trackState]
   );
 
-  useEffect(() => () => closeResources(), [closeResources]);
+  useEffect(
+    () => () => {
+      userClosedRef.current = true;
+      closeResources();
+    },
+    [closeResources]
+  );
 
   return {
     startListening,
     stopListening,
     transcribeFile,
-    ...(trackState ? { state: internalState } : {}),
+    pause,
+    resume,
+    ...(trackState
+      ? {
+          state: internalState,
+          isPaused: internalIsPaused,
+          ...(meteringEnabled ? { audioLevel: internalAudioLevel } : {}),
+          ...(internalRecordingUri !== undefined
+            ? { recordingUri: internalRecordingUri }
+            : {}),
+        }
+      : {}),
     ...(trackTranscript
       ? {
           transcript: internalTranscript,
diff --git a/src/useDeepgramTextIntelligence.ts b/src/useDeepgramTextIntelligence.ts
index 0f107e0..0d15e89 100644
--- a/src/useDeepgramTextIntelligence.ts
+++ b/src/useDeepgramTextIntelligence.ts
@@ -4,8 +4,9 @@ import type {
   UseDeepgramTextIntelligenceReturn,
   DeepgramTextIntelligenceInput,
 } from './types';
-import { DEEPGRAM_BASEURL } from './constants';
-import { buildParams } from './helpers';
+import { getBaseUrl } from './constants';
+import { buildParams, resolveAuthHeader } from './helpers';
+import { toDeepgramError } from './types';
 
 export function useDeepgramTextIntelligence({
   onBeforeAnalyze = () => {},
@@ -57,8 +58,7 @@ export function useDeepgramTextIntelligence({
       }
 
       try {
-        const apiKey = (globalThis as any).__DEEPGRAM_API_KEY__;
-        if (!apiKey) throw new Error('Deepgram API key missing');
+        const authHeader = await resolveAuthHeader();
 
         const { text, url: sourceUrl } = input;
 
@@ -85,7 +85,7 @@ export function useDeepgramTextIntelligence({
 
         const params = buildParams(paramMap);
 
-        const url = `${DEEPGRAM_BASEURL}/read${params ? `?${params}` : ''}`;
+        const url = `${getBaseUrl()}/read${params ? `?${params}` : ''}`;
         abortCtrl.current?.abort();
         abortCtrl.current = new AbortController();
 
@@ -93,7 +93,7 @@ export function useDeepgramTextIntelligence({
           method: 'POST',
           headers: {
             'Content-Type': 'application/json',
-            'Authorization': `Token ${apiKey}`,
+            'Authorization': authHeader,
           },
           body: JSON.stringify({
             ...(text ? { text } : {}),
@@ -114,11 +114,12 @@ export function useDeepgramTextIntelligence({
         }
       } catch (err: any) {
         if (err.name === 'AbortError') return;
-        onAnalyzeErrorRef.current(err);
+        const dgError = toDeepgramError(err);
+        onAnalyzeErrorRef.current(dgError);
         if (trackState) {
           setInternalState({
             status: 'error',
-            error: err instanceof Error ? err : new Error(String(err)),
+            error: dgError,
           });
         }
       }
diff --git a/src/useDeepgramTextToSpeech.ts b/src/useDeepgramTextToSpeech.ts
index 6f462c4..74774e5 100644
--- a/src/useDeepgramTextToSpeech.ts
+++ b/src/useDeepgramTextToSpeech.ts
@@ -12,9 +12,12 @@ import type {
   DeepgramTextToSpeechStreamErrorMessage,
   DeepgramTextToSpeechHttpEncoding,
   DeepgramTextToSpeechStreamEncoding,
+  DeepgramTextToSpeechHttpOptions,
+  DeepgramTextToSpeechBytes,
 } from './types';
-import { DEEPGRAM_BASEURL, DEEPGRAM_BASEWSS } from './constants';
-import { buildParams, arrayBufferToBase64 } from './helpers';
+import { getBaseUrl, getBaseWss } from './constants';
+import { buildParams, arrayBufferToBase64, resolveAuthHeader } from './helpers';
+import { toDeepgramError } from './types';
 
 const DEFAULT_TTS_MODEL = 'aura-2-asteria-en';
 const DEFAULT_TTS_SAMPLE_RATE = 24_000;
@@ -24,6 +27,26 @@ const DEFAULT_TTS_STREAM_ENCODING: DeepgramTextToSpeechStreamEncoding =
 const DEFAULT_TTS_CONTAINER = 'none';
 const DEFAULT_TTS_MP3_BITRATE = 48_000;
 
+const TTS_BYTES_CACHE_MAX = 50;
+
+const deriveTtsMimeType = (encoding?: string, container?: string): string => {
+  if (container === 'wav') return 'audio/wav';
+  if (container === 'ogg') return 'audio/ogg';
+  switch (encoding) {
+    case 'mp3':
+      return 'audio/mpeg';
+    case 'aac':
+      return 'audio/aac';
+    case 'flac':
+      return 'audio/flac';
+    case 'opus':
+      return 'audio/ogg';
+    default:
+      // linear16 / mulaw / alaw and other raw PCM payloads have no container.
+      return 'application/octet-stream';
+  }
+};
+
 type QueryParamPrimitive = string | number | boolean | null | undefined;
 type QueryParamValue = QueryParamPrimitive | Array<QueryParamPrimitive>;
 
@@ -55,14 +78,6 @@ const ensureQueryParam = (
   params[key] = value;
 };
 
-const getAuthorizationHeader = (apiKeyOrToken: string): string => {
-  const trimmed = apiKeyOrToken.trim();
-  if (/^(Token|Bearer)\s+/i.test(trimmed)) {
-    return trimmed;
-  }
-  return `Token ${trimmed}`;
-};
-
 const isMetadataMessage = (
   message: DeepgramTextToSpeechStreamResponseMessage
 ): message is DeepgramTextToSpeechStreamMetadataMessage =>
@@ -263,6 +278,9 @@ export function useDeepgramTextToSpeech({
 
   /* ---------- HTTP (one-shot synth) ---------- */
   const abortCtrl = useRef<AbortController | null>(null);
+  const ttsBytesCacheRef = useRef<Map<string, DeepgramTextToSpeechBytes>>(
+    new Map()
+  );
 
   const synthesize = useCallback(
     async (text: string) => {
@@ -271,9 +289,8 @@ export function useDeepgramTextToSpeech({
         setInternalState({ status: 'loading', error: null });
       }
       try {
-        const apiKey = (globalThis as any).__DEEPGRAM_API_KEY__;
-        if (!apiKey) throw new Error('Deepgram API key missing');
         if (!text?.trim()) throw new Error('Text is empty');
+        const authHeader = await resolveAuthHeader();
 
         const httpParams: Record<string, QueryParamValue> = {
           ...resolvedHttpOptions.queryParams,
@@ -309,16 +326,15 @@ export function useDeepgramTextToSpeech({
 
         const params = buildParams(httpParams);
 
-        const url = params
-          ? `${DEEPGRAM_BASEURL}/speak?${params}`
-          : `${DEEPGRAM_BASEURL}/speak`;
+        const baseUrl = getBaseUrl();
+        const url = params ? `${baseUrl}/speak?${params}` : `${baseUrl}/speak`;
         abortCtrl.current?.abort();
         abortCtrl.current = new AbortController();
 
         const res = await fetch(url, {
           method: 'POST',
           headers: {
-            'Authorization': getAuthorizationHeader(apiKey),
+            'Authorization': authHeader,
             'Content-Type': 'application/json',
             'Accept': 'application/octet-stream',
           },
@@ -344,19 +360,93 @@ export function useDeepgramTextToSpeech({
           throw err;
         }
 
-        onSynthesizeErrorRef.current(err);
+        const dgError = toDeepgramError(err);
+        onSynthesizeErrorRef.current(dgError);
         if (trackState) {
           setInternalState({
             status: 'error',
-            error: err instanceof Error ? err : new Error(String(err)),
+            error: dgError,
           });
         }
-        throw err;
+        throw dgError;
       }
     },
     [resolvedHttpOptions, trackState]
   );
 
+  /* ---------- HTTP (synth to bytes + cache) ---------- */
+  const synthesizeToBytes = useCallback(
+    async (
+      text: string,
+      opts?: DeepgramTextToSpeechHttpOptions
+    ): Promise<DeepgramTextToSpeechBytes> => {
+      if (!text?.trim()) throw new Error('Text is empty');
+
+      // Per-call overrides win over the hook's resolved HTTP options.
+      const merged = { ...resolvedHttpOptions, ...(opts ?? {}) };
+
+      const httpParams: Record<string, QueryParamValue> = {
+        ...resolvedHttpOptions.queryParams,
+        ...(opts?.queryParams ?? {}),
+      };
+      ensureQueryParam(httpParams, 'model', merged.model);
+      ensureQueryParam(httpParams, 'encoding', merged.encoding);
+      ensureQueryParam(httpParams, 'sample_rate', merged.sampleRate);
+      ensureQueryParam(httpParams, 'container', merged.container);
+      ensureQueryParam(httpParams, 'format', merged.format);
+      ensureQueryParam(httpParams, 'bit_rate', merged.bitRate);
+      ensureQueryParam(httpParams, 'speed', merged.speed);
+      ensureQueryParam(httpParams, 'tag', merged.tag);
+      ensureQueryParam(httpParams, 'mip_opt_out', merged.mipOptOut);
+
+      const cache = ttsBytesCacheRef.current;
+      const cacheKey = JSON.stringify({ text, params: httpParams });
+      const cached = cache.get(cacheKey);
+      if (cached) {
+        // LRU touch: re-insert to mark as most-recently-used.
+        cache.delete(cacheKey);
+        cache.set(cacheKey, cached);
+        return { data: cached.data.slice(0), mimeType: cached.mimeType };
+      }
+
+      const authHeader = await resolveAuthHeader();
+      const params = buildParams(httpParams);
+      const baseUrl = getBaseUrl();
+      const url = params ? `${baseUrl}/speak?${params}` : `${baseUrl}/speak`;
+
+      const res = await fetch(url, {
+        method: 'POST',
+        headers: {
+          'Authorization': authHeader,
+          'Content-Type': 'application/json',
+          'Accept': 'application/octet-stream',
+        },
+        body: JSON.stringify({ text }),
+      });
+
+      if (!res.ok) {
+        // Don't cache error responses.
+        const errText = await res.text();
+        throw new Error(`HTTP ${res.status}: ${errText}`);
+      }
+
+      const data = await res.arrayBuffer();
+      const mimeType =
+        res.headers?.get?.('Content-Type') ||
+        deriveTtsMimeType(merged.encoding, merged.container);
+
+      const result: DeepgramTextToSpeechBytes = { data, mimeType };
+      cache.set(cacheKey, { data: data.slice(0), mimeType });
+      while (cache.size > TTS_BYTES_CACHE_MAX) {
+        const oldest = cache.keys().next().value;
+        if (oldest === undefined) break;
+        cache.delete(oldest);
+      }
+      return result;
+    },
+    [resolvedHttpOptions]
+  );
+
   /* ---------- WebSocket (streaming synth) ---------- */
   const ws = useRef<WebSocket | null>(null);
 
@@ -385,11 +475,12 @@ export function useDeepgramTextToSpeech({
         ws.current.send(JSON.stringify(normalizedMessage));
         return true;
       } catch (err) {
-        onStreamErrorRef.current(err);
+        const dgError = toDeepgramError(err);
+        onStreamErrorRef.current(dgError);
         if (trackState) {
           setInternalState({
             status: 'error',
-            error: err instanceof Error ? err : new Error(String(err)),
+            error: dgError,
           });
         }
         return false;
@@ -451,9 +542,8 @@ export function useDeepgramTextToSpeech({
         setInternalState({ status: 'connecting', error: null });
       }
       try {
-        const apiKey = (globalThis as any).__DEEPGRAM_API_KEY__;
-        if (!apiKey) throw new Error('Deepgram API key missing');
         if (!text?.trim()) throw new Error('Text is empty');
+        const authHeader = await resolveAuthHeader();
 
         const wsParams: Record<string, QueryParamValue> = {
           ...resolvedStreamOptions.queryParams,
@@ -474,11 +564,12 @@ export function useDeepgramTextToSpeech({
         );
 
         const wsParamString = buildParams(wsParams);
+        const baseWss = getBaseWss();
         const url = wsParamString
-          ? `${DEEPGRAM_BASEWSS}/speak?${wsParamString}`
-          : `${DEEPGRAM_BASEWSS}/speak`;
+          ? `${baseWss}/speak?${wsParamString}`
+          : `${baseWss}/speak`;
         ws.current = new (WebSocket as any)(url, undefined, {
-          headers: { Authorization: getAuthorizationHeader(apiKey) },
+          headers: { Authorization: authHeader },
         });
         const socket = ws.current as WebSocket;
 
@@ -549,13 +640,14 @@ export function useDeepgramTextToSpeech({
                   const code =
                     err && typeof err.code === 'string' ? err.code : undefined;
 
-                  onStreamErrorRef.current(
+                  const dgError = toDeepgramError(
                     new Error(description ?? code ?? 'TTS error')
                   );
+                  onStreamErrorRef.current(dgError);
                   if (trackState) {
                     setInternalState({
                       status: 'error',
-                      error: new Error(description ?? code ?? 'TTS error'),
+                      error: dgError,
                     });
                   }
                   break;
@@ -571,11 +663,12 @@ export function useDeepgramTextToSpeech({
         };
 
         socket.onerror = (err) => {
-          onStreamErrorRef.current(err);
+          const dgError = toDeepgramError(err);
+          onStreamErrorRef.current(dgError);
           if (trackState) {
             setInternalState({
               status: 'error',
-              error: err instanceof Error ? err : new Error(String(err)),
+              error: dgError,
             });
           }
         };
@@ -587,15 +680,16 @@ export function useDeepgramTextToSpeech({
           closeStream();
         };
       } catch (err) {
-        onStreamErrorRef.current(err);
+        const dgError = toDeepgramError(err);
+        onStreamErrorRef.current(dgError);
         if (trackState) {
           setInternalState({
             status: 'error',
-            error: err instanceof Error ? err : new Error(String(err)),
+            error: dgError,
           });
         }
         closeStream();
-        throw err;
+        throw dgError;
       }
     },
     [resolvedStreamOptions, sendText, autoPlayAudio, closeStream, trackState]
@@ -609,11 +703,12 @@ export function useDeepgramTextToSpeech({
         onStreamEndRef.current();
       }
     } catch (err) {
-      onStreamErrorRef.current(err);
+      const dgError = toDeepgramError(err);
+      onStreamErrorRef.current(dgError);
       if (trackState) {
         setInternalState({
           status: 'error',
-          error: err instanceof Error ? err : new Error(String(err)),
+          error: dgError,
         });
       }
     }
@@ -630,6 +725,7 @@ export function useDeepgramTextToSpeech({
 
   return {
     synthesize,
+    synthesizeToBytes,
     startStreaming,
     sendMessage,
     sendText,
diff --git a/src/useDeepgramVoiceAgent.ts b/src/useDeepgramVoiceAgent.ts
index 823d4c4..9dd6d51 100644
--- a/src/useDeepgramVoiceAgent.ts
+++ b/src/useDeepgramVoiceAgent.ts
@@ -2,7 +2,13 @@ import { useRef, useCallback, useEffect, useState } from 'react';
 import { NativeEventEmitter, NativeModules, Platform } from 'react-native';
 import { Deepgram } from './NativeDeepgram';
 import { askMicPermission } from './helpers/askMicPermission';
-import { arrayBufferToBase64 } from './helpers';
+import {
+  arrayBufferToBase64,
+  resolveAuthHeader,
+  hasAuthConfigured,
+} from './helpers';
+import { getAgentUrl } from './constants';
+import { toDeepgramError } from './types';
 import type {
   DeepgramVoiceAgentSettings,
   DeepgramVoiceAgentSettingsMessage,
@@ -30,12 +36,22 @@ import type {
   DeepgramVoiceAgentListenConfig,
   DeepgramVoiceAgentThinkConfig,
   DeepgramVoiceAgentSpeakConfig,
+  DeepgramVoiceAgentAgentConfig,
+  DeepgramReconnectOptions,
 } from './types';
 
-const DEFAULT_AGENT_ENDPOINT = 'wss://agent.deepgram.com/v1/agent/converse';
 const DEFAULT_INPUT_SAMPLE_RATE = 16_000;
 const BASE_NATIVE_SAMPLE_RATE = 16_000;
 
+const AGENT_KEEPALIVE_INTERVAL_MS = 5_000;
+
+const DEFAULT_AGENT_RECONNECT = {
+  enabled: false,
+  maxRetries: 5,
+  initialDelayMs: 500,
+  maxDelayMs: 10_000,
+};
+
 const eventName = Platform.select({
   ios: 'DeepgramAudioPCM',
   android: 'AudioChunk',
@@ -190,6 +206,16 @@ export interface UseDeepgramVoiceAgentProps {
   trackState?: boolean;
   trackConversation?: boolean;
   trackAgentStatus?: boolean;
+  /**
+   * Auto-reconnect configuration for the agent socket. Disabled by default;
+   * set `reconnect.enabled` to opt in. On reconnect the stored `Settings`
+   * message is automatically re-sent.
+   */
+  reconnect?: DeepgramReconnectOptions;
+  /** Called when a reconnect attempt begins (1-based attempt number). */
+  onReconnecting?: (attempt: number) => void;
+  /** Called once the agent socket has successfully reconnected. */
+  onReconnected?: () => void;
   onBeforeConnect?: () => void;
   onConnect?: () => void;
   onClose?: (event?: any) => void;
@@ -246,12 +272,18 @@ export interface UseDeepgramVoiceAgentReturn {
   updateThink: (think: DeepgramVoiceAgentThinkConfig) => boolean;
   updateSpeak: (speak: DeepgramVoiceAgentSpeakConfig) => boolean;
   sendMedia: (chunk: ArrayBuffer | Uint8Array | number[]) => boolean;
+  /** Stop forwarding mic frames; keep the socket alive with KeepAlive. */
+  mute: () => void;
+  /** Resume forwarding mic frames after {@link mute}. */
+  unmute: () => void;
   isConnected: () => boolean;
   state?: {
     connectionState: 'idle' | 'connecting' | 'connected' | 'disconnected';
     error: string | null;
     warning: string | null;
   };
+  /** Whether the microphone is currently muted (only when trackState is enabled). */
+  isMuted?: boolean;
   conversation?: Array<{ role: string; content: string }>;
   clearConversation?: () => void;
   agentStatus?: {
@@ -261,7 +293,7 @@ export interface UseDeepgramVoiceAgentReturn {
 }
 
 export function useDeepgramVoiceAgent({
-  endpoint = DEFAULT_AGENT_ENDPOINT,
+  endpoint,
   defaultSettings,
   autoStartMicrophone = true,
   autoPlayAudio = true,
@@ -269,6 +301,9 @@ export function useDeepgramVoiceAgent({
   trackConversation = false,
   trackAgentStatus = false,
   downsampleFactor,
+  reconnect = {},
+  onReconnecting = () => {},
+  onReconnected = () => {},
   onBeforeConnect,
   onConnect,
   onClose,
@@ -308,13 +343,30 @@ export function useDeepgramVoiceAgent({
     )
   );
   const microphoneActive = useRef(false);
+  const mutedRef = useRef(false);
+  const muteKeepAliveTimerRef = useRef<ReturnType<typeof setInterval> | null>(
+    null
+  );
   const defaultSettingsRef = useRef(defaultSettings);
   const endpointRef = useRef(endpoint);
 
+  const userDisconnectedRef = useRef(false);
+  const reconnectAttemptRef = useRef(0);
+  const reconnectingRef = useRef(false);
+  const reconnectTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const wsGenerationRef = useRef(0);
+  const mergedSettingsRef = useRef<DeepgramVoiceAgentSettingsMessage | null>(
+    null
+  );
+  const reconnectConfigRef = useRef({ ...DEFAULT_AGENT_RECONNECT });
+  const openSocketRef = useRef<() => void>(() => {});
+
   const onBeforeConnectRef = useRef(onBeforeConnect);
   const onConnectRef = useRef(onConnect);
   const onCloseRef = useRef(onClose);
   const onErrorRef = useRef(onError);
+  const onReconnectingRef = useRef(onReconnecting);
+  const onReconnectedRef = useRef(onReconnected);
   const onMessageRef = useRef(onMessage);
   const onWelcomeRef = useRef(onWelcome);
   const onSettingsAppliedRef = useRef(onSettingsApplied);
@@ -359,6 +411,8 @@ export function useDeepgramVoiceAgent({
     latency: null,
   }));
 
+  const [internalIsMuted, setInternalIsMuted] = useState(false);
+
   const sanitizeAudioSettings = useCallback(
     (audio?: DeepgramVoiceAgentSettings['audio']) => {
       if (!audio) {
@@ -474,10 +528,13 @@ export function useDeepgramVoiceAgent({
 
   defaultSettingsRef.current = defaultSettings;
   endpointRef.current = endpoint;
+  reconnectConfigRef.current = { ...DEFAULT_AGENT_RECONNECT, ...reconnect };
   onBeforeConnectRef.current = onBeforeConnect;
   onConnectRef.current = onConnect;
   onCloseRef.current = onClose;
   onErrorRef.current = onError;
+  onReconnectingRef.current = onReconnecting;
+  onReconnectedRef.current = onReconnected;
   onMessageRef.current = onMessage;
   onWelcomeRef.current = onWelcome;
   onSettingsAppliedRef.current = onSettingsApplied;
@@ -504,6 +561,19 @@ export function useDeepgramVoiceAgent({
   }
 
   const cleanup = useCallback(() => {
+    if (muteKeepAliveTimerRef.current != null) {
+      clearInterval(muteKeepAliveTimerRef.current);
+      muteKeepAliveTimerRef.current = null;
+    }
+    mutedRef.current = false;
+    setInternalIsMuted(false);
+
+    if (reconnectTimerRef.current != null) {
+      clearTimeout(reconnectTimerRef.current);
+      reconnectTimerRef.current = null;
+    }
+    reconnectingRef.current = false;
+
     audioSub.current?.remove();
     audioSub.current = null;
 
@@ -533,10 +603,19 @@ export function useDeepgramVoiceAgent({
     }
   }, []);
 
-  useEffect(() => () => cleanup(), [cleanup]);
+  useEffect(
+    () => () => {
+      userDisconnectedRef.current = true;
+      cleanup();
+    },
+    [cleanup]
+  );
 
   const handleMicChunk = useCallback(
     (ev: any) => {
+      if (mutedRef.current) {
+        return;
+      }
       const socket = ws.current;
       if (!socket || socket.readyState !== WebSocket.OPEN) {
         return;
@@ -576,7 +655,7 @@ export function useDeepgramVoiceAgent({
       try {
         socket.send(chunk);
       } catch (err) {
-        onErrorRef.current?.(err);
+        onErrorRef.current?.(toDeepgramError(err));
       }
     },
     [downsampleFactor]
@@ -784,14 +863,14 @@ export function useDeepgramVoiceAgent({
                   );
                 }
 
-                onErrorRef.current?.(new Error(errorMsg));
+                onErrorRef.current?.(toDeepgramError(new Error(errorMsg)));
               }
               break;
             default:
               break;
           }
         } catch (err) {
-          onErrorRef.current?.(err);
+          onErrorRef.current?.(toDeepgramError(err));
         }
         return;
       }
@@ -824,7 +903,7 @@ export function useDeepgramVoiceAgent({
         socket.send(JSON.stringify(message));
         return true;
       } catch (err) {
-        onErrorRef.current?.(err);
+        onErrorRef.current?.(toDeepgramError(err));
         return false;
       }
     },
@@ -866,16 +945,171 @@ export function useDeepgramVoiceAgent({
         socket.send(payload);
         return true;
       } catch (err) {
-        onErrorRef.current?.(err);
+        onErrorRef.current?.(toDeepgramError(err));
         return false;
       }
     },
     []
   );
 
+  const handleAgentDisconnect = useCallback(
+    (event?: { code?: number }, failureError?: Error) => {
+      const cfg = reconnectConfigRef.current;
+      const shouldReconnect =
+        !userDisconnectedRef.current &&
+        cfg.enabled &&
+        event?.code !== 1000 &&
+        reconnectAttemptRef.current < cfg.maxRetries;
+
+      if (shouldReconnect) {
+        const attempt = reconnectAttemptRef.current;
+        reconnectAttemptRef.current = attempt + 1;
+        reconnectingRef.current = true;
+
+        const backoff = Math.min(
+          cfg.maxDelayMs,
+          cfg.initialDelayMs * 2 ** attempt
+        );
+        const delay = backoff + Math.random() * backoff * 0.25;
+
+        if (trackState) {
+          setInternalState((prev) => ({
+            ...prev,
+            connectionState: 'connecting',
+          }));
+        }
+        onReconnectingRef.current?.(attempt + 1);
+
+        if (reconnectTimerRef.current != null) {
+          clearTimeout(reconnectTimerRef.current);
+        }
+        reconnectTimerRef.current = setTimeout(() => {
+          reconnectTimerRef.current = null;
+          openSocketRef.current();
+        }, delay);
+        return;
+      }
+
+      const exhausted =
+        !userDisconnectedRef.current &&
+        cfg.enabled &&
+        reconnectAttemptRef.current >= cfg.maxRetries;
+
+      cleanup();
+
+      if (exhausted) {
+        const err = new Error(
+          `Deepgram reconnect failed after ${cfg.maxRetries} attempts`
+        );
+        if (trackState) {
+          setInternalState((prev) => ({
+            ...prev,
+            connectionState: 'disconnected',
+            error: err.message,
+          }));
+        }
+        onErrorRef.current?.(toDeepgramError(err));
+      } else if (trackState) {
+        setInternalState((prev) => ({
+          ...prev,
+          connectionState: 'disconnected',
+          error: failureError ? failureError.message : prev.error,
+        }));
+      }
+
+      onCloseRef.current?.(event);
+    },
+    [cleanup, trackState]
+  );
+
+  const openSocket = useCallback(() => {
+    const generation = wsGenerationRef.current + 1;
+    wsGenerationRef.current = generation;
+
+    resolveAuthHeader()
+      .then((authHeader) => {
+        // A newer connection attempt superseded this one while the auth token
+        // was resolving — abandon this stale socket setup.
+        if (generation !== wsGenerationRef.current) {
+          return;
+        }
+
+        const socket = new (WebSocket as any)(
+          endpointRef.current ?? getAgentUrl(),
+          undefined,
+          {
+            headers: { Authorization: authHeader },
+          }
+        );
+
+        socket.binaryType = 'arraybuffer';
+        ws.current = socket;
+
+        socket.onopen = () => {
+          if (generation !== wsGenerationRef.current) return;
+
+          const wasReconnecting = reconnectingRef.current;
+          reconnectingRef.current = false;
+          reconnectAttemptRef.current = 0;
+
+          if (mergedSettingsRef.current) {
+            sendJsonMessage(mergedSettingsRef.current);
+          }
+
+          if (trackState) {
+            setInternalState((prev) => ({
+              ...prev,
+              connectionState: 'connected',
+            }));
+          }
+
+          if (autoPlayAudio) {
+            const sampleRate =
+              mergedSettingsRef.current?.audio?.output?.sample_rate ??
+              DEFAULT_INPUT_SAMPLE_RATE;
+            const channels = 1;
+            Deepgram.startPlayer(sampleRate, channels);
+          }
+
+          if (wasReconnecting) {
+            onReconnectedRef.current?.();
+          } else {
+            onConnectRef.current?.();
+          }
+        };
+
+        socket.onmessage = handleSocketMessage;
+        socket.onerror = (err: any) => {
+          if (generation !== wsGenerationRef.current) return;
+          onErrorRef.current?.(toDeepgramError(err));
+        };
+        socket.onclose = (event: any) => {
+          if (generation !== wsGenerationRef.current) return;
+          handleAgentDisconnect(event);
+        };
+      })
+      .catch((err) => {
+        if (generation !== wsGenerationRef.current) return;
+        const authError = toDeepgramError(err);
+        onErrorRef.current?.(authError);
+        handleAgentDisconnect(undefined, authError);
+      });
+  }, [
+    autoPlayAudio,
+    handleAgentDisconnect,
+    handleSocketMessage,
+    sendJsonMessage,
+    trackState,
+  ]);
+
+  openSocketRef.current = openSocket;
+
   const connect = useCallback(
     async (overrideSettings?: DeepgramVoiceAgentSettings) => {
       cleanup();
+      userDisconnectedRef.current = false;
+      reconnectAttemptRef.current = 0;
+      reconnectingRef.current = false;
 
       if (trackState) {
         setInternalState({
@@ -883,6 +1117,7 @@ export function useDeepgramVoiceAgent({
           error: null,
           warning: null,
         });
+        setInternalIsMuted(false);
       }
 
       if (trackConversation) {
@@ -894,8 +1129,7 @@ export function useDeepgramVoiceAgent({
 
       onBeforeConnectRef.current?.();
 
-      const apiKey = (globalThis as any).__DEEPGRAM_API_KEY__;
-      if (!apiKey) throw new Error('Deepgram API key missing');
+      if (!hasAuthConfigured()) throw new Error('Deepgram API key missing');
 
       const shouldCaptureMic = autoStartMicRef.current;
       if (shouldCaptureMic) {
@@ -923,7 +1157,7 @@ export function useDeepgramVoiceAgent({
 
       const merged = mergeSettings(sanitizedDefault, sanitizedOverride);
 
-      const mergedSettings: DeepgramVoiceAgentSettingsMessage = {
+      mergedSettingsRef.current = {
         type: 'Settings',
         ...(merged ?? {}),
       };
@@ -939,58 +1173,15 @@ export function useDeepgramVoiceAgent({
         nativeInputSampleRate.current
       );
 
-      const socket = new (WebSocket as any)(endpointRef.current, undefined, {
-        headers: { Authorization: `Token ${apiKey}` },
-      });
-
-      socket.binaryType = 'arraybuffer';
-      ws.current = socket;
-
-      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?.();
-      };
-
-      socket.onmessage = handleSocketMessage;
-      socket.onerror = (err: any) => {
-        onErrorRef.current?.(err);
-      };
-      socket.onclose = (event: any) => {
-        if (trackState) {
-          setInternalState((prev) => ({
-            ...prev,
-            connectionState: 'disconnected',
-          }));
-        }
-
-        cleanup();
-        onCloseRef.current?.(event);
-      };
+      openSocket();
     },
     [
       cleanup,
       downsampleFactor,
       handleMicChunk,
-      handleSocketMessage,
       mergeSettings,
+      openSocket,
       sanitizeSettings,
-      sendJsonMessage,
-      autoPlayAudio,
       trackAgentStatus,
       trackConversation,
       trackState,
@@ -998,13 +1189,22 @@ export function useDeepgramVoiceAgent({
   );
 
   const disconnect = useCallback(() => {
+    userDisconnectedRef.current = true;
     cleanup();
   }, [cleanup]);
 
   const sendSettings = useCallback(
     (settings: DeepgramVoiceAgentSettings) => {
       const sanitized = sanitizeSettings(settings);
-      return sendJsonMessage({ type: 'Settings', ...(sanitized ?? {}) });
+      const message: DeepgramVoiceAgentSettingsMessage = {
+        type: 'Settings',
+        ...(sanitized ?? {}),
+      };
+      const sent = sendJsonMessage(message);
+      if (sent) {
+        mergedSettingsRef.current = message;
+      }
+      return sent;
     },
     [sanitizeSettings, sendJsonMessage]
   );
@@ -1039,27 +1239,102 @@ export function useDeepgramVoiceAgent({
     [sendJsonMessage]
   );
 
+  const mute = useCallback(() => {
+    if (mutedRef.current) {
+      return;
+    }
+    mutedRef.current = true;
+
+    if (muteKeepAliveTimerRef.current == null) {
+      muteKeepAliveTimerRef.current = setInterval(() => {
+        const socket = ws.current;
+        if (!socket || socket.readyState !== WebSocket.OPEN) {
+          return;
+        }
+        try {
+          socket.send(JSON.stringify({ type: 'KeepAlive' }));
+        } catch {}
+      }, AGENT_KEEPALIVE_INTERVAL_MS);
+    }
+
+    if (trackState) {
+      setInternalIsMuted(true);
+    }
+  }, [trackState]);
+
+  const unmute = useCallback(() => {
+    if (!mutedRef.current) {
+      return;
+    }
+    mutedRef.current = false;
+
+    if (muteKeepAliveTimerRef.current != null) {
+      clearInterval(muteKeepAliveTimerRef.current);
+      muteKeepAliveTimerRef.current = null;
+    }
+
+    if (trackState) {
+      setInternalIsMuted(false);
+    }
+  }, [trackState]);
+
+  const patchAgentSettings = useCallback(
+    (patch: Partial<DeepgramVoiceAgentAgentConfig>) => {
+      const current = mergedSettingsRef.current;
+      if (!current) {
+        return;
+      }
+      mergedSettingsRef.current = {
+        ...current,
+        agent: { ...(current.agent ?? {}), ...patch },
+      };
+    },
+    []
+  );
+
   const updatePrompt = useCallback(
-    (prompt: string) => sendJsonMessage({ type: 'UpdatePrompt', prompt }),
-    [sendJsonMessage]
+    (prompt: string) => {
+      const sent = sendJsonMessage({ type: 'UpdatePrompt', prompt });
+      if (sent) {
+        const currentThink = mergedSettingsRef.current?.agent?.think ?? {};
+        patchAgentSettings({ think: { ...currentThink, prompt } });
+      }
+      return sent;
+    },
+    [patchAgentSettings, sendJsonMessage]
   );
 
   const updateListen = useCallback(
-    (listen: DeepgramVoiceAgentListenConfig) =>
-      sendJsonMessage({ type: 'UpdateListen', listen }),
-    [sendJsonMessage]
+    (listen: DeepgramVoiceAgentListenConfig) => {
+      const sent = sendJsonMessage({ type: 'UpdateListen', listen });
+      if (sent) {
+        patchAgentSettings({ listen });
+      }
+      return sent;
+    },
+    [patchAgentSettings, sendJsonMessage]
   );
 
   const updateThink = useCallback(
-    (think: DeepgramVoiceAgentThinkConfig) =>
-      sendJsonMessage({ type: 'UpdateThink', think }),
-    [sendJsonMessage]
+    (think: DeepgramVoiceAgentThinkConfig) => {
+      const sent = sendJsonMessage({ type: 'UpdateThink', think });
+      if (sent) {
+        patchAgentSettings({ think });
+      }
+      return sent;
+    },
+    [patchAgentSettings, sendJsonMessage]
   );
 
   const updateSpeak = useCallback(
-    (speak: DeepgramVoiceAgentSpeakConfig) =>
-      sendJsonMessage({ type: 'UpdateSpeak', speak }),
-    [sendJsonMessage]
+    (speak: DeepgramVoiceAgentSpeakConfig) => {
+      const sent = sendJsonMessage({ type: 'UpdateSpeak', speak });
+      if (sent) {
+        patchAgentSettings({ speak });
+      }
+      return sent;
+    },
+    [patchAgentSettings, sendJsonMessage]
   );
 
   const sendMessage = useCallback(
@@ -1092,8 +1367,10 @@ export function useDeepgramVoiceAgent({
     updateThink,
     updateSpeak,
     sendMedia: sendBinary,
+    mute,
+    unmute,
     isConnected,
-    ...(trackState ? { state: internalState } : {}),
+    ...(trackState ? { state: internalState, isMuted: internalIsMuted } : {}),
     ...(trackConversation
       ? { conversation: internalConversation, clearConversation }
       : {}),
diff --git a/yarn.lock b/yarn.lock
index bea4983..82a2210 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -8232,6 +8232,18 @@ __metadata:
   languageName: node
   linkType: hard
 
+"expo-build-properties@npm:~0.13.3":
+  version: 0.13.3
+  resolution: "expo-build-properties@npm:0.13.3"
+  dependencies:
+    ajv: ^8.11.0
+    semver: ^7.6.0
+  peerDependencies:
+    expo: "*"
+  checksum: 65b97a82dc46b5d92f7ed7e1d4e85bb441ac719a6dacea54ba0ae0c9080ae5c465b5ccab6e41cc8bdca63a26128a72d73ed6901e5c38793fd95fac0fa6dc2588
+  languageName: node
+  linkType: hard
+
 "expo-constants@npm:~17.0.8":
   version: 17.0.8
   resolution: "expo-constants@npm:17.0.8"
@@ -13649,7 +13661,9 @@ __metadata:
     "@react-native/typescript-config": ^0.81.1
     babel-plugin-module-resolver: ^5.0.2
     expo: ~52.0.27
+    expo-build-properties: ~0.13.3
     expo-document-picker: ^12.0.2
+    expo-file-system: ~18.0.12
     react: 18.3.1
     react-dom: 18.3.1
     react-native: 0.76.6