@edkimmel/expo-audio-stream 0.5.0 → 0.6.1

package/ios/Microphone.swift

@@ -2,215 +2,142 @@ import AVFoundation
 import ExpoModulesCore
 
 
-class Microphone {
+class Microphone: SharedAudioEngineDelegate {
     weak var delegate: MicrophoneDataDelegate?
-    
-    private var audioEngine: AVAudioEngine!
-    private var audioConverter: AVAudioConverter!
-    private var inputNode: AVAudioInputNode!
-    
+
+    /// The shared engine whose VP-enabled input node this microphone taps.
+    /// Must be set and configured before calling startRecording.
+    weak var sharedAudioEngine: SharedAudioEngine?
+
     public private(set) var isVoiceProcessingEnabled: Bool = false
-    
-    
+
     internal var lastEmittedSize: Int64 = 0
     private var totalDataSize: Int64 = 0
     internal var recordingSettings: RecordingSettings?
 
     internal var mimeType: String = "audio/wav"
     private var lastBufferTime: AVAudioTime?
-    
+
     private var startTime: Date?
-    private var pauseStartTime: Date?
-    
 
-    private var inittedAudioSession = false
     private var isRecording: Bool = false
     private var isSilent: Bool = false
     private var frequencyBandAnalyzer: FrequencyBandAnalyzer?
     private var frequencyBandConfig: (lowCrossoverHz: Float, highCrossoverHz: Float)?
 
-    /// Interval (in ms) the consumer last requested. Used to rebuild the tap
-    /// with the same cadence when resuming after an interruption.
     private var lastIntervalMs: Int = 100
-    /// Set when an audio session interruption begins while recording is active.
-    /// Cleared either by `stopRecording` (consumer chose disconnect) or by the
-    /// `.ended` handler after a successful auto-resume.
     private var pendingInterruptionResume: Bool = false
-    
-    init() {
-        NotificationCenter.default.addObserver(
-            self,
-            selector: #selector(handleRouteChange),
-            name: AVAudioSession.routeChangeNotification,
-            object: nil
-        )
-        NotificationCenter.default.addObserver(
-            self,
-            selector: #selector(handleInterruption),
-            name: AVAudioSession.interruptionNotification,
-            object: nil
-        )
-    }
 
-    deinit {
-        NotificationCenter.default.removeObserver(self)
-    }
+    // ── SharedAudioEngineDelegate ────────────────────────────────────────
 
-    /// Handles audio route changes (e.g. headphones connected/disconnected)
-    /// - Parameter notification: The notification object containing route change information
-    @objc private func handleRouteChange(notification: Notification) {
-        guard let info = notification.userInfo,
-              let reasonValue = info[AVAudioSessionRouteChangeReasonKey] as? UInt,
-              let reason = AVAudioSession.RouteChangeReason(rawValue: reasonValue) else {
-            return
-        }
-
-        Logger.debug("[Microphone] Route is changed \(reason)")
-
-        switch reason {
-        case .newDeviceAvailable, .oldDeviceUnavailable:
-            if isRecording {
-                stopRecording(resolver: nil)
-                DispatchQueue.main.asyncAfter(deadline: .now() + 0.5) { [weak self] in
-                    guard let self = self, let settings = self.recordingSettings else { return }
-
-                    _ = startRecording(settings: self.recordingSettings!, intervalMilliseconds: 100, frequencyBandConfig: self.frequencyBandConfig)
-                }
-            }
-        case .categoryChange:
-            Logger.debug("[Microphone] Audio Session category changed")
-        default:
-            break
+    func engineDidRestartAfterRouteChange() {
+        guard isRecording else { return }
+        // Engine restarted in-place; tap was removed on stop — reinstall.
+        do {
+            try installTap(intervalMilliseconds: lastIntervalMs)
+        } catch {
+            Logger.debug("[Microphone] Failed to reinstall tap after route change: \(error)")
+            failRecording(MicrophoneErrorInfo(
+                code: "RESTART_FAILED",
+                message: "Could not reinstall microphone tap after route change: \(error.localizedDescription)",
+                isFatal: true,
+                autoResuming: false
+            ))
         }
     }
 
-    /// Handles audio session interruptions (e.g. Siri, phone call, alarm).
-    ///
-    /// On `.began` we stop the engine (iOS deactivates the session regardless)
-    /// but keep `isRecording = true` and emit an `INTERRUPTED` error so the
-    /// consumer can decide:
-    ///   - Call `stopRecording` to disconnect explicitly (clears the resume flag).
-    ///   - Do nothing to let the library auto-resume when the system gives the
-    ///     mic back on `.ended`.
-    @objc private func handleInterruption(notification: Notification) {
-        guard let info = notification.userInfo,
-              let typeValue = info[AVAudioSessionInterruptionTypeKey] as? UInt,
-              let type = AVAudioSession.InterruptionType(rawValue: typeValue) else {
-            return
-        }
-
-        switch type {
-        case .began:
-            Logger.debug("[Microphone] Audio session interruption began")
-            guard isRecording else { return }
-            // Tear down the engine but leave isRecording true so the consumer's
-            // intent is preserved. The .ended branch will decide whether to
-            // resume based on whether stopRecording was called in between.
-            pendingInterruptionResume = true
-            if let engine = audioEngine {
-                engine.inputNode.removeTap(onBus: 0)
-                engine.stop()
-            }
-            delegate?.onMicrophoneError("INTERRUPTED", "Audio session interrupted by system")
-        case .ended:
-            Logger.debug("[Microphone] Audio session interruption ended")
-            guard pendingInterruptionResume else { return }
-            pendingInterruptionResume = false
-            // iOS uses AVAudioSessionInterruptionOptionKey.shouldResume to hint
-            // whether the app can safely reactivate. Absent means another app
-            // took over (e.g. an ongoing call) — in that case we surface a
-            // terminal error instead of attempting a doomed restart.
-            let optionsValue = info[AVAudioSessionInterruptionOptionKey] as? UInt ?? 0
-            let options = AVAudioSession.InterruptionOptions(rawValue: optionsValue)
-            guard options.contains(.shouldResume) else {
-                Logger.debug("[Microphone] System did not signal shouldResume — treating as terminal stop")
-                isRecording = false
-                delegate?.onMicrophoneError(
-                    "RESUME_DENIED",
-                    "System did not permit microphone resume after interruption"
-                )
-                return
-            }
-            do {
-                try AVAudioSession.sharedInstance().setActive(true)
-                try installTapAndStartEngine(intervalMilliseconds: lastIntervalMs)
-                Logger.debug("[Microphone] Auto-resumed after interruption")
-            } catch {
-                Logger.debug("[Microphone] Auto-resume failed: \(error.localizedDescription)")
-                // Engine couldn't restart — surface as terminal stop.
-                isRecording = false
-                delegate?.onMicrophoneError(
-                    "RESUME_FAILED",
-                    "Could not restart microphone after interruption: \(error.localizedDescription)"
-                )
-            }
-        @unknown default:
-            break
+    func engineDidRebuild() {
+        guard isRecording else { return }
+        // New AVAudioEngine instance — installTap picks up the new inputNode automatically.
+        do {
+            try installTap(intervalMilliseconds: lastIntervalMs)
+        } catch {
+            Logger.debug("[Microphone] Failed to reinstall tap after engine rebuild: \(error)")
+            failRecording(MicrophoneErrorInfo(
+                code: "RESTART_FAILED",
+                message: "Could not reinstall microphone tap after engine rebuild: \(error.localizedDescription)",
+                isFatal: true,
+                autoResuming: false
+            ))
         }
     }
 
-    /// Installs the audio tap on the input node and starts the engine.
-    /// Shared between fresh `startRecording` and post-interruption resume.
-    private func installTapAndStartEngine(intervalMilliseconds: Int) throws {
-        let hardwareFormat = audioEngine.inputNode.inputFormat(forBus: 0)
-        let intervalSamples = AVAudioFrameCount(
-            Double(intervalMilliseconds) / 1000.0 * hardwareFormat.sampleRate
-        )
-        let tapBufferSize = max(intervalSamples, 256)
-
-        audioEngine.inputNode.installTap(onBus: 0, bufferSize: tapBufferSize, format: nil) { [weak self] (buffer, time) in
-            guard let self = self else { return }
+    func audioSessionResumeDenied() {
+        guard isRecording else { return }
+        failRecording(MicrophoneErrorInfo(
+            code: "RESUME_DENIED",
+            message: "System did not permit microphone resume after interruption",
+            isFatal: true,
+            autoResuming: false
+        ))
+    }
 
-            guard buffer.frameLength > 0 else {
-                Logger.debug("Error: received empty buffer in tap callback")
-                self.delegate?.onMicrophoneError("READ_ERROR", "Received empty audio buffer")
-                return
-            }
+    func audioSessionInterruptionBegan() {
+        guard isRecording else { return }
+        pendingInterruptionResume = true
+        delegate?.onMicrophoneError(MicrophoneErrorInfo(
+            code: "INTERRUPTED",
+            message: "Audio session interrupted by system",
+            isFatal: false,
+            autoResuming: true
+        ))
+    }
 
-            self.processAudioBuffer(buffer)
-            self.lastBufferTime = time
+    func audioSessionInterruptionEnded() {
+        guard pendingInterruptionResume else { return }
+        pendingInterruptionResume = false
+        do {
+            try installTap(intervalMilliseconds: lastIntervalMs)
+        } catch {
+            Logger.debug("[Microphone] Failed to reinstall tap after interruption resume: \(error)")
+            failRecording(MicrophoneErrorInfo(
+                code: "RESUME_FAILED",
+                message: "Could not reinstall microphone tap after interruption: \(error.localizedDescription)",
+                isFatal: true,
+                autoResuming: false
+            ))
         }
+    }
 
-        try audioEngine.start()
+    func engineDidDie(reason: String) {
+        guard isRecording else { return }
+        failRecording(MicrophoneErrorInfo(
+            code: "ENGINE_DIED",
+            message: reason,
+            isFatal: true,
+            autoResuming: false
+        ))
     }
-    
+
+    // ── Core recording API ───────────────────────────────────────────────
+
     func toggleSilence(isSilent: Bool) {
         Logger.debug("[Microphone] toggleSilence")
         self.isSilent = isSilent
     }
-    
+
     func startRecording(settings: RecordingSettings, intervalMilliseconds: Int,
                         frequencyBandConfig: (lowCrossoverHz: Float, highCrossoverHz: Float)? = nil) -> StartRecordingResult? {
         guard !isRecording else {
-            Logger.debug("Debug: Recording is already in progress.")
+            Logger.debug("[Microphone] Recording is already in progress.")
             return StartRecordingResult(error: "Recording is already in progress.")
         }
-        
-        if self.audioEngine == nil {
-            self.audioEngine = AVAudioEngine()
+        guard let shared = sharedAudioEngine, shared.isConfigured, let engine = shared.engine else {
+            Logger.debug("[Microphone] Shared audio engine is not configured.")
+            return StartRecordingResult(error: "Shared audio engine is not configured.")
         }
-        
-        if self.audioEngine != nil && audioEngine.isRunning  {
-            Logger.debug("Debug: Audio engine already running.")
-            audioEngine.stop()
-        }
-       
-        var newSettings = settings  // Make settings mutable
 
+        var newSettings = settings
         totalDataSize = 0
-        
-        // Use the hardware's native format for the tap to avoid Core Audio format mismatch crashes.
-        // The inputNode delivers audio in the hardware format (e.g. 48kHz Float32).
-        // Resampling and format conversion to the desired settings happens in processAudioBuffer.
-        let hardwareFormat = audioEngine.inputNode.inputFormat(forBus: 0)
-        newSettings.sampleRate = hardwareFormat.sampleRate
-        Logger.debug("Debug: Hardware sample rate is \(hardwareFormat.sampleRate) Hz, desired sample rate is \(settings.sampleRate) Hz")
 
-        recordingSettings = newSettings  // Update the class property with the new settings
+        let hardwareFormat = engine.inputNode.inputFormat(forBus: 0)
+        newSettings.sampleRate = hardwareFormat.sampleRate
+        Logger.debug("[Microphone] Hardware sample rate: \(hardwareFormat.sampleRate) Hz, desired: \(settings.sampleRate) Hz")
 
+        recordingSettings = newSettings
         self.frequencyBandConfig = frequencyBandConfig
         self.lastIntervalMs = intervalMilliseconds
-        // Analyzer uses the desired (target) sample rate, not hardware rate
+
         let targetRate = Int(settings.desiredSampleRate ?? settings.sampleRate)
         let fbConfig = frequencyBandConfig ?? (lowCrossoverHz: Float(300), highCrossoverHz: Float(2000))
         frequencyBandAnalyzer = FrequencyBandAnalyzer(
@@ -219,11 +146,12 @@ class Microphone {
             highCrossoverHz: fbConfig.highCrossoverHz
         )
 
+        sharedAudioEngine?.addDelegate(self)
         do {
             startTime = Date()
-            try installTapAndStartEngine(intervalMilliseconds: intervalMilliseconds)
+            try installTap(intervalMilliseconds: intervalMilliseconds)
             isRecording = true
-            Logger.debug("Debug: Recording started successfully.")
+            Logger.debug("[Microphone] Recording started successfully.")
             return StartRecordingResult(
                 fileUri: "",
                 mimeType: mimeType,
@@ -232,49 +160,81 @@ class Microphone {
                 sampleRate: settings.sampleRate
             )
         } catch {
-            Logger.debug("Error: Could not start the audio engine: \(error.localizedDescription)")
+            Logger.debug("[Microphone] Could not start recording: \(error.localizedDescription)")
+            sharedAudioEngine?.removeDelegate(self)
             isRecording = false
-            return StartRecordingResult(error: "Error: Could not start the audio engine: \(error.localizedDescription)")
+            return StartRecordingResult(error: "Could not start recording: \(error.localizedDescription)")
         }
     }
-    
+
     public func stopRecording(resolver promise: Promise?) {
-        // Clear resume intent up-front so a stopRecording call during an
-        // active interruption window cancels the auto-resume on .ended.
         pendingInterruptionResume = false
-        guard self.isRecording else {
-            if let promiseResolver = promise {
-                promiseResolver.resolve(nil)
-            }
+        guard isRecording else {
+            promise?.resolve(nil)
             return
         }
-        self.isRecording = false
-        self.isVoiceProcessingEnabled = false
-       
-        // Remove tap before stopping the engine
-        if audioEngine != nil {
-            audioEngine.inputNode.removeTap(onBus: 0)
-            audioEngine.stop()
-            frequencyBandAnalyzer = nil
+        isRecording = false
+        isVoiceProcessingEnabled = false
+        sharedAudioEngine?.engine?.inputNode.removeTap(onBus: 0)
+        sharedAudioEngine?.removeDelegate(self)
+        frequencyBandAnalyzer = nil
+        promise?.resolve(nil)
+    }
+
+    // ── Private helpers ──────────────────────────────────────────────────
+
+    private func failRecording(_ error: MicrophoneErrorInfo) {
+        isRecording = false
+        pendingInterruptionResume = false
+        sharedAudioEngine?.engine?.inputNode.removeTap(onBus: 0)
+        sharedAudioEngine?.removeDelegate(self)
+        frequencyBandAnalyzer = nil
+        delegate?.onMicrophoneError(error)
+    }
+
+    private func installTap(intervalMilliseconds: Int) throws {
+        guard let inputNode = sharedAudioEngine?.engine?.inputNode else {
+            throw NSError(domain: "Microphone", code: -1,
+                          userInfo: [NSLocalizedDescriptionKey: "Shared engine input node unavailable"])
         }
 
-        if let promiseResolver = promise {
-            promiseResolver.resolve(nil)
+        // Remove any stale tap before installing — AVAudioEngine crashes if a tap
+        // is already present on the bus. Engine restarts do not guarantee tap removal.
+        inputNode.removeTap(onBus: 0)
+
+        let hardwareFormat = inputNode.inputFormat(forBus: 0)
+        recordingSettings?.sampleRate = hardwareFormat.sampleRate
+
+        let intervalSamples = AVAudioFrameCount(
+            Double(intervalMilliseconds) / 1000.0 * hardwareFormat.sampleRate
+        )
+        let tapBufferSize = max(intervalSamples, 256)
+
+        inputNode.installTap(onBus: 0, bufferSize: tapBufferSize, format: nil) { [weak self] (buffer, time) in
+            guard let self = self else { return }
+            guard buffer.frameLength > 0 else {
+                Logger.debug("[Microphone] Received empty buffer in tap callback")
+                self.delegate?.onMicrophoneError(MicrophoneErrorInfo(
+                    code: "READ_ERROR",
+                    message: "Received empty audio buffer",
+                    isFatal: false,
+                    autoResuming: false
+                ))
+                return
+            }
+            self.processAudioBuffer(buffer)
+            self.lastBufferTime = time
         }
     }
-    
-    /// Processes the audio buffer and writes data to the file. Also handles audio processing if enabled.
-    /// - Parameters:
-    ///   - buffer: The audio buffer to process.
-    ///   - fileURL: The URL of the file to write the data to.
+
     private func processAudioBuffer(_ buffer: AVAudioPCMBuffer) {
         let targetSampleRate = recordingSettings?.desiredSampleRate ?? buffer.format.sampleRate
         let targetBitDepth = recordingSettings?.bitDepth ?? 16
         var currentBuffer = buffer
 
-        // Resample if needed
         if currentBuffer.format.sampleRate != targetSampleRate {
-            if let resampledBuffer = AudioUtils.resampleAudioBuffer(currentBuffer, from: currentBuffer.format.sampleRate, to: targetSampleRate) {
+            if let resampledBuffer = AudioUtils.resampleAudioBuffer(
+                currentBuffer, from: currentBuffer.format.sampleRate, to: targetSampleRate) {
                 currentBuffer = resampledBuffer
             } else if let convertedBuffer = AudioUtils.tryConvertToFormat(
                 inputBuffer: currentBuffer,
@@ -284,13 +244,12 @@ class Microphone {
             ) {
                 currentBuffer = convertedBuffer
             } else {
-                Logger.debug("Failed to resample audio buffer.")
+                Logger.debug("[Microphone] Failed to resample audio buffer.")
             }
         }
 
         let powerLevel: Float = self.isSilent ? -160.0 : AudioUtils.calculatePowerLevel(from: currentBuffer)
 
-        // Convert Float32 → Int16 PCM if needed (the tap delivers hardware-native Float32)
         let data: Data
         if isSilent {
             let byteCount = Int(currentBuffer.frameCapacity) * Int(currentBuffer.format.streamDescription.pointee.mBytesPerFrame)
@@ -311,13 +270,12 @@ class Microphone {
         } else {
             let audioData = currentBuffer.audioBufferList.pointee.mBuffers
             guard let bufferData = audioData.mData else {
-                Logger.debug("Buffer data is nil.")
+                Logger.debug("[Microphone] Buffer data is nil.")
                 return
             }
             data = Data(bytes: bufferData, count: Int(audioData.mDataByteSize))
         }
 
-        // Compute frequency bands from the Int16 PCM data
         let bands: FrequencyBands?
         if isSilent {
             bands = .zero
@@ -329,8 +287,6 @@ class Microphone {
         }
 
         totalDataSize += Int64(data.count)
-
-        // Emit immediately — tap buffer size is already interval-aligned
         self.delegate?.onMicrophoneData(data, powerLevel, bands)
         self.lastEmittedSize = totalDataSize
     }

package/ios/MicrophoneDataDelegate.swift

@@ -1,4 +1,13 @@
+struct MicrophoneErrorInfo {
+    let code: String
+    let message: String
+    /// True when the recording has stopped and the caller must reconnect to resume.
+    let isFatal: Bool
+    /// True only for INTERRUPTED — the library will reinstall the tap automatically.
+    let autoResuming: Bool
+}
+
 protocol MicrophoneDataDelegate: AnyObject {
     func onMicrophoneData(_ microphoneData: Data, _ soundLevel: Float?, _ frequencyBands: FrequencyBands?)
-    func onMicrophoneError(_ error: String, _ errorMessage: String)
+    func onMicrophoneError(_ error: MicrophoneErrorInfo)
 }

package/ios/SharedAudioEngine.swift

@@ -21,12 +21,20 @@ protocol SharedAudioEngineDelegate: AnyObject {
     /// Consumer should restart playback.
     func audioSessionInterruptionEnded()
 
+    /// Audio session interruption ended but the system did not signal shouldResume.
+    /// Recording has been stopped. Consumer should clean up and wait for the user to reconnect.
+    func audioSessionResumeDenied()
+
     /// Engine failed to restart after exhausting all retry attempts.
     /// All state has been torn down. Consumer should report the failure
     /// to JS and clean up its own state so a fresh connect can succeed.
     func engineDidDie(reason: String)
 }
 
+extension SharedAudioEngineDelegate {
+    func audioSessionResumeDenied() {}
+}
+
 /// Owns the single AVAudioEngine shared between AudioPipeline consumers.
 ///
 /// Responsibilities:
@@ -494,6 +502,16 @@ class SharedAudioEngine {
             notifyDelegates { $0.audioSessionInterruptionBegan() }
         } else if type == .ended {
             Logger.debug("[\(SharedAudioEngine.TAG)] Audio session interruption ended")
+            let optionsValue = info[AVAudioSessionInterruptionOptionKey] as? UInt ?? 0
+            let options = AVAudioSession.InterruptionOptions(rawValue: optionsValue)
+            guard options.contains(.shouldResume) else {
+                // shouldResume absent — system hints we should not restart yet.
+                // Note: this flag is advisory; may be worth revisiting if it causes
+                // false negatives in practice.
+                Logger.debug("[\(SharedAudioEngine.TAG)] shouldResume not set — skipping restart")
+                notifyDelegates { $0.audioSessionResumeDenied() }
+                return
+            }
             // Reactivate session and restart engine
             try? AVAudioSession.sharedInstance().setActive(true)
             if let engine = engine, !engine.isRunning {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edkimmel/expo-audio-stream",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Expo Play Audio Stream module",
   "main": "build/index.js",
   "types": "build/index.d.ts",

package/src/events.ts

@@ -42,6 +42,7 @@ export type DeviceReconnectedEventPayload = {
 
 export const AudioEvents = {
   AudioData: "AudioData",
+  MicrophoneError: "MicrophoneError",
   DeviceReconnected: "DeviceReconnected",
 };
 
@@ -51,6 +52,33 @@ export function addAudioEventListener(
   return (emitter as any).addListener("AudioData", listener);
 }
 
+export interface MicrophoneErrorEventPayload {
+  code: string;
+  message: string;
+  isFatal: boolean;
+  autoResuming: boolean;
+}
+
+/**
+ * Subscribe to the dedicated MicrophoneError native event.
+ *
+ * OTA safe: if the running native binary predates this feature, the event is
+ * never emitted and this listener is never called. Apps that also subscribe to
+ * AudioData errors via addAudioEventListener continue to work unchanged.
+ *
+ * @example
+ * const sub = addMicrophoneErrorListener((e) => {
+ *   if (e.isFatal) { stopMicrophone(); reconnect(); }
+ *   else if (e.autoResuming) { showPausedUI(); }
+ * })
+ * // cleanup: sub.remove()
+ */
+export function addMicrophoneErrorListener(
+  listener: (event: MicrophoneErrorEventPayload) => void
+): EventSubscription {
+  return (emitter as any).addListener("MicrophoneError", listener);
+}
+
 export function subscribeToEvent<T extends unknown>(
   eventName: string,
   listener: (event: T | undefined) => Promise<void>

package/src/index.ts

@@ -30,6 +30,7 @@ import {
 
 import {
   addAudioEventListener,
+  addMicrophoneErrorListener,
   AudioEventPayload,
   AudioEvents,
   subscribeToEvent,
@@ -61,34 +62,22 @@ export class ExpoPlayAudioStream {
     try {
       const { onAudioStream, onError, ...options } = recordingConfig;
 
-      if (
-        (onAudioStream && typeof onAudioStream == "function") ||
-        (onError && typeof onError == "function")
-      ) {
-        subscription = addAudioEventListener(
-          async (event: AudioEventPayload) => {
-            const {
-              fileUri,
-              deltaSize,
-              totalSize,
-              position,
-              encoded,
-              soundLevel,
-              frequencyBands,
-              error,
-              errorMessage,
-            } = event;
-            if (error) {
-              onError?.({ code: error, message: errorMessage ?? "" });
-              return;
-            }
+      const subscriptions: EventSubscription[] = [];
+
+      if (onAudioStream && typeof onAudioStream === "function") {
+        subscriptions.push(
+          addAudioEventListener(async (event: AudioEventPayload) => {
+            const { fileUri, deltaSize, totalSize, position, encoded, soundLevel, frequencyBands, error } = event;
+            // Only suppress AudioData error events when onError is wired up — the
+            // MicrophoneError subscription will handle them. Without onError (old
+            // integration or old native binary), fall through so the missing-encoded
+            // path below preserves the pre-v0.6.0 behavior.
+            if (error && onError) return;
             if (!encoded) {
-              console.error(
-                `[ExpoPlayAudioStream] Encoded audio data is missing`
-              );
+              console.error(`[ExpoPlayAudioStream] Encoded audio data is missing`);
               throw new Error("Encoded audio data is missing");
             }
-            onAudioStream?.({
+            onAudioStream({
               data: encoded,
               position,
               fileUri,
@@ -97,10 +86,22 @@ export class ExpoPlayAudioStream {
               soundLevel,
               frequencyBands,
             });
-          }
+          })
+        );
+      }
+
+      if (onError && typeof onError === "function") {
+        subscriptions.push(
+          addMicrophoneErrorListener((event) => {
+            onError(event);
+          })
         );
       }
 
+      if (subscriptions.length > 0) {
+        subscription = { remove: () => subscriptions.forEach((s) => s.remove()) };
+      }
+
       const result = await ExpoPlayAudioStreamModule.startMicrophone(options);
 
       return { recordingResult: result, subscription };
@@ -249,6 +250,8 @@ export {
 // Re-export Subscription type for backwards compatibility
 export type { EventSubscription } from "expo-modules-core";
 export type { Subscription } from "./events";
+export { addMicrophoneErrorListener } from "./events";
+export type { MicrophoneErrorEventPayload } from "./events";
 
 // Export native audio pipeline V3
 export { Pipeline } from "./pipeline";