@edkimmel/expo-audio-stream 0.6.1 → 0.6.2

package/ios/AudioPipeline.swift

@@ -85,6 +85,15 @@ class AudioPipeline: SharedAudioEngineDelegate {
     /// This prevents duplicate chains and stale callbacks from re-entering after a rebuild.
     private var scheduleGeneration: Int = 0
 
+    /// All `node.scheduleBuffer(...)` calls for this pipeline run on the shared
+    /// engine's serial `engineQueue` (the same queue that owns stop/detach/attach),
+    /// so `scheduleBuffer()` and teardown's `stop()` can never overlap — that
+    /// overlap is the AVAudioPlayerNode deadlock (AttachAndEngineLock ⇄
+    /// RealtimeMessenger). The buffer-completion callback re-arms via
+    /// `engineQueue.async` (returns immediately so `stop()`'s message flush isn't
+    /// blocked); teardown runs on the same queue via `sharedEngine.performSync`,
+    /// so it's serialized after any in-flight scheduling with no explicit barrier.
+
     /// Pending PlaybackStopped dispatch — cancelled on new turn / disconnect.
     /// Always mutate from the main queue to avoid races with the drain timer.
     private var pendingPlaybackStoppedWork: DispatchWorkItem?
@@ -134,12 +143,26 @@ class AudioPipeline: SharedAudioEngineDelegate {
         }
         setState(.connecting)
 
+        guard let sharedEngine = sharedEngine else {
+            setState(.error)
+            throw NSError(domain: "AudioPipeline", code: -1,
+                userInfo: [NSLocalizedDescriptionKey: "SharedAudioEngine not set"])
+        }
+
         do {
-            guard let sharedEngine = sharedEngine else {
-                throw NSError(domain: "AudioPipeline", code: -1,
-                    userInfo: [NSLocalizedDescriptionKey: "SharedAudioEngine not set"])
-            }
+            // All graph setup runs on the engine's serial queue so attach / play /
+            // seed are serialized against route-change, scheduleBuffer and teardown.
+            try sharedEngine.performSync { try self.connectOnQueue(sharedEngine: sharedEngine) }
+        } catch {
+            Logger.debug("[\(AudioPipeline.TAG)] connect() failed: \(error)")
+            setState(.error)
+            disconnect()
+            throw error
+        }
+    }
 
+    /// Graph setup for `connect()`. Runs entirely on `sharedEngine.engineQueue`.
+    private func connectOnQueue(sharedEngine: SharedAudioEngine) throws {
             // ── 1. JitterBuffer ─────────────────────────────────────────
             jitterBuffer = JitterBuffer(
                 sampleRate: sampleRate,
@@ -199,17 +222,26 @@ class AudioPipeline: SharedAudioEngineDelegate {
             Logger.debug("[\(AudioPipeline.TAG)] Connected — sampleRate=\(sampleRate) " +
                 "ch=\(channelCount) frameSamples=\(frameSizeSamples) " +
                 "targetBuffer=\(targetBufferMs)ms")
-        } catch {
-            Logger.debug("[\(AudioPipeline.TAG)] connect() failed: \(error)")
-            setState(.error)
-            disconnect()
-            throw error
-        }
     }
 
     func disconnect() {
+        // Run teardown on the engine's serial queue so it's serialized after any
+        // in-flight scheduleBuffer pass and against route-change/interruption —
+        // no explicit barrier needed. If the shared engine is already gone
+        // (module destroyed), just clean up local state.
+        if let sharedEngine = sharedEngine {
+            sharedEngine.performSync { self.disconnectOnQueue() }
+        } else {
+            disconnectOnQueue()
+        }
+    }
+
+    /// Teardown body. Runs on `sharedEngine.engineQueue` (via `performSync`), so
+    /// `running = false` and `detachNode`'s `stop()` are ordered after any
+    /// scheduling pass; a buffer completion that fires during `stop()` only
+    /// re-enqueues onto the same queue and then bails on `running == false`.
+    private func disconnectOnQueue() {
         // Cancel any pending PlaybackStopped before tearing down.
-        // DispatchWorkItem.cancel is thread-safe; we may be on any queue here.
         pendingPlaybackStoppedWork?.cancel()
         pendingPlaybackStoppedWork = nil
 
@@ -227,7 +259,8 @@ class AudioPipeline: SharedAudioEngineDelegate {
         frequencyBandAnalyzer = nil
         lastEmittedBands = nil
 
-        // Detach node from shared engine (handles pause/stop/disconnect/detach)
+        // Detach node from shared engine (handles pause/stop/disconnect/detach).
+        // detachNode is performSync → runs inline since we're already on the queue.
         if let node = playerNode {
             sharedEngine?.detachNode(node)
         }
@@ -344,6 +377,11 @@ class AudioPipeline: SharedAudioEngineDelegate {
     func audioSessionInterruptionEnded() {
         Logger.debug("[\(AudioPipeline.TAG)] Audio session interruption ended")
         isInterrupted = false
+        // Reset the zombie baseline as we clear the interruption: scheduling was
+        // stalled while interrupted, and the re-seed below runs asynchronously on
+        // the engine queue, so without this the zombie timer could false-positive
+        // in the gap before the first resumed buffer is scheduled.
+        lastScheduleTime = Date()
         // Engine already restarted by SharedAudioEngine. Re-seed scheduling.
         if running {
             scheduleGeneration += 1
@@ -465,7 +503,19 @@ class AudioPipeline: SharedAudioEngineDelegate {
     // Scheduling loop
     // ════════════════════════════════════════════════════════════════════
 
+    /// Request one buffer-scheduling pass. Hops onto the shared engine's serial
+    /// `engineQueue` so the actual `scheduleBuffer()` is serialized against
+    /// teardown's `stop()` and graph mutations. All re-seed call sites (connect,
+    /// route change, rebuild, interruption) use this; the completion handler
+    /// re-arms via `engineQueue.async` directly (see below).
     private func scheduleNextBuffer() {
+        sharedEngine?.engineQueue.async { [weak self] in
+            self?.scheduleNextBufferOnQueue()
+        }
+    }
+
+    /// Build and schedule the next PCM buffer. MUST run on `engineQueue`.
+    private func scheduleNextBufferOnQueue() {
         guard running,
               let se = sharedEngine, !se.isRebuilding,
               let buf = jitterBuffer,
@@ -521,11 +571,21 @@ class AudioPipeline: SharedAudioEngineDelegate {
         lastScheduleTime = Date()
 
         node.scheduleBuffer(pcmBuffer) { [weak self] in
-            guard let self = self, self.running else { return }
-            // Bail if this completion belongs to a previous scheduling generation
-            // (route change rebuilt the engine while this buffer was in flight).
-            guard self.scheduleGeneration == capturedGeneration else { return }
-            self.scheduleNextBuffer()
+            guard let self = self else { return }
+            // Re-arm on the engine queue. Returning from this completion callback
+            // IMMEDIATELY is essential: AVAudioPlayerNode.stop() flushes pending
+            // completion messages synchronously while holding the engine lock, so
+            // calling scheduleBuffer() inline here would deadlock a concurrent
+            // stop() (AttachAndEngineLock ⇄ RealtimeMessenger mutex). Hopping to
+            // engineQueue lets stop() drain us without blocking, and serializes
+            // the next scheduleBuffer() against teardown on the same queue.
+            self.sharedEngine?.engineQueue.async {
+                // Bail if torn down, or if this completion belongs to a previous
+                // scheduling generation (route change rebuilt the engine while
+                // this buffer was in flight).
+                guard self.running, self.scheduleGeneration == capturedGeneration else { return }
+                self.scheduleNextBufferOnQueue()
+            }
         }
     }
 
@@ -631,7 +691,11 @@ class AudioPipeline: SharedAudioEngineDelegate {
         timer.setEventHandler { [weak self] in
             guard let self = self else { return }
             let stalledMs = Int64(Date().timeIntervalSince(self.lastScheduleTime) * 1000)
+            // Don't flag a zombie while interrupted: the engine is stopped, so
+            // scheduling legitimately stalls (no buffers feed) until resume. The
+            // stall is expected, not a dead scheduling loop.
             if stalledMs >= AudioPipeline.ZOMBIE_STALL_THRESHOLD_MS &&
+               !self.isInterrupted &&
                (self.state == .streaming || self.state == .draining) {
                 Logger.debug("[\(AudioPipeline.TAG)] Zombie detected! stalledMs=\(stalledMs)")
                 self.listener?.onZombieDetected(stalledMs: stalledMs)

package/ios/Microphone.swift

@@ -9,6 +9,14 @@ class Microphone: SharedAudioEngineDelegate {
     /// Must be set and configured before calling startRecording.
     weak var sharedAudioEngine: SharedAudioEngine?
 
+    /// Serial queue for mic-input processing. The tap fires on AVFoundation's
+    /// real-time render thread; we copy the buffer and hop here so resampling,
+    /// frequency analysis and the JS `sendEvent` never run on that thread (a
+    /// real-time violation that can stall capture or invert priority). Kept
+    /// separate from the engine queue so a congested JS bridge on the mic path
+    /// can't stall playback scheduling.
+    private let micQueue = DispatchQueue(label: "expo.modules.audio.microphone")
+
     public private(set) var isVoiceProcessingEnabled: Bool = false
 
     internal var lastEmittedSize: Int64 = 0
@@ -214,20 +222,39 @@ class Microphone: SharedAudioEngineDelegate {
             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
-                ))
+                self.micQueue.async {
+                    self.delegate?.onMicrophoneError(MicrophoneErrorInfo(
+                        code: "READ_ERROR",
+                        message: "Received empty audio buffer",
+                        isFatal: false,
+                        autoResuming: false
+                    ))
+                }
                 return
             }
-            self.processAudioBuffer(buffer)
-            self.lastBufferTime = time
+            // Convert on the render thread — the tap buffer is only valid here, and
+            // the conversion yields the `Data` we'd build anyway, so there's no
+            // extra copy. Hand the value-typed result to the serial queue; only the
+            // JS-bridge delivery (sendEvent) runs off the render thread. Nothing
+            // here re-enters the engine, so no separate queue is needed for safety —
+            // micQueue exists purely to keep the bridge call off the render thread
+            // and preserve chunk ordering.
+            guard let payload = self.extractMicData(from: buffer) else { return }
+            self.micQueue.async {
+                self.totalDataSize += Int64(payload.data.count)
+                self.delegate?.onMicrophoneData(payload.data, payload.powerLevel, payload.bands)
+                self.lastEmittedSize = self.totalDataSize
+                self.lastBufferTime = time
+            }
         }
     }
 
-    private func processAudioBuffer(_ buffer: AVAudioPCMBuffer) {
+    /// Convert a tap buffer into the value-typed payload the delegate needs
+    /// (PCM `Data`, power level, frequency bands). Runs on the audio render
+    /// thread — it needs the live buffer — but does no cross-thread work, so the
+    /// caller hands the result to `micQueue` for the JS-bridge delivery. Returns
+    /// nil if the buffer yields no data.
+    private func extractMicData(from buffer: AVAudioPCMBuffer) -> (data: Data, powerLevel: Float, bands: FrequencyBands?)? {
         let targetSampleRate = recordingSettings?.desiredSampleRate ?? buffer.format.sampleRate
         let targetBitDepth = recordingSettings?.bitDepth ?? 16
         var currentBuffer = buffer
@@ -271,7 +298,7 @@ class Microphone: SharedAudioEngineDelegate {
             let audioData = currentBuffer.audioBufferList.pointee.mBuffers
             guard let bufferData = audioData.mData else {
                 Logger.debug("[Microphone] Buffer data is nil.")
-                return
+                return nil
             }
             data = Data(bytes: bufferData, count: Int(audioData.mDataByteSize))
         }
@@ -286,8 +313,6 @@ class Microphone: SharedAudioEngineDelegate {
             bands = nil
         }
 
-        totalDataSize += Int64(data.count)
-        self.delegate?.onMicrophoneData(data, powerLevel, bands)
-        self.lastEmittedSize = totalDataSize
+        return (data, powerLevel, bands)
     }
 }

package/ios/SharedAudioEngine.swift

@@ -49,7 +49,33 @@ extension SharedAudioEngineDelegate {
 class SharedAudioEngine {
     private static let TAG = "SharedAudioEngine"
 
-    private let lock = NSRecursiveLock()
+    /// The single serial queue that owns ALL engine graph work: every
+    /// attach/detach/connect/stop/start/configure/teardown, the playback
+    /// `scheduleBuffer` loop (driven from AudioPipeline), and route/interruption
+    /// handling. Serial ordering here is what makes the AVAudioPlayerNode
+    /// `stop()`/`scheduleBuffer()` deadlock structurally impossible — they can't
+    /// overlap on one serial queue. AVFoundation callbacks hop on via `async`
+    /// (never `sync` — they may run with an AV lock held); Expo functions enter
+    /// via `performSync`. Replaces the former recursive lock.
+    let engineQueue = DispatchQueue(label: "expo.modules.audio.engine")
+    private static let queueKey = DispatchSpecificKey<Void>()
+
+    init() {
+        engineQueue.setSpecific(key: SharedAudioEngine.queueKey, value: ())
+    }
+
+    /// Run `work` synchronously in the engine's serial domain. Re-entrancy-aware:
+    /// if we're already on `engineQueue` (a delegate callback fired from
+    /// `notifyDelegates`, or `configure` calling `teardown`/`attachNode`) we run
+    /// inline instead of dead-locking on `engineQueue.sync`. This is exactly what
+    /// the *recursive* lock used to provide. Callers on AVFoundation callback
+    /// threads must use `engineQueue.async` instead — never this.
+    func performSync<T>(_ work: () throws -> T) rethrows -> T {
+        if DispatchQueue.getSpecific(key: SharedAudioEngine.queueKey) != nil {
+            return try work()
+        }
+        return try engineQueue.sync(execute: work)
+    }
 
     // ── Engine state ─────────────────────────────────────────────────────
     private(set) var engine: AVAudioEngine?
@@ -61,17 +87,17 @@ class SharedAudioEngine {
     private let delegates = NSHashTable<AnyObject>.weakObjects()
 
     func addDelegate(_ d: SharedAudioEngineDelegate) {
-        lock.lock()
-        defer { lock.unlock() }
-        if !delegates.contains(d as AnyObject) {
-            delegates.add(d as AnyObject)
+        performSync {
+            if !delegates.contains(d as AnyObject) {
+                delegates.add(d as AnyObject)
+            }
         }
     }
 
     func removeDelegate(_ d: SharedAudioEngineDelegate) {
-        lock.lock()
-        defer { lock.unlock() }
-        delegates.remove(d as AnyObject)
+        performSync {
+            delegates.remove(d as AnyObject)
+        }
     }
 
     private func notifyDelegates(_ block: (SharedAudioEngineDelegate) -> Void) {
@@ -100,8 +126,10 @@ class SharedAudioEngine {
     ///
     /// - Parameter playbackMode: Determines whether voice processing is enabled.
     func configure(playbackMode: PlaybackMode) throws {
-        lock.lock()
-        defer { lock.unlock() }
+        try performSync { try configureOnQueue(playbackMode: playbackMode) }
+    }
+
+    private func configureOnQueue(playbackMode: PlaybackMode) throws {
         if isConfigured && self.playbackMode == playbackMode && engine?.isRunning == true {
             Logger.debug("[\(SharedAudioEngine.TAG)] Already configured for \(playbackMode) and engine running, skipping")
             return
@@ -168,8 +196,10 @@ class SharedAudioEngine {
     /// Connects `node → mainMixerNode` with the given format.
     /// The mixer handles sample-rate conversion to hardware output.
     func attachNode(_ node: AVAudioPlayerNode, format: AVAudioFormat) {
-        lock.lock()
-        defer { lock.unlock() }
+        performSync { attachNodeOnQueue(node, format: format) }
+    }
+
+    private func attachNodeOnQueue(_ node: AVAudioPlayerNode, format: AVAudioFormat) {
         guard let engine = engine else {
             Logger.debug("[\(SharedAudioEngine.TAG)] attachNode called but engine is nil")
             return
@@ -184,8 +214,10 @@ class SharedAudioEngine {
 
     /// Detach a consumer's player node from the shared engine.
     func detachNode(_ node: AVAudioPlayerNode) {
-        lock.lock()
-        defer { lock.unlock() }
+        performSync { detachNodeOnQueue(node) }
+    }
+
+    private func detachNodeOnQueue(_ node: AVAudioPlayerNode) {
         guard let engine = engine else { return }
 
         node.pause()
@@ -209,8 +241,10 @@ class SharedAudioEngine {
 
     /// Tear down the engine completely. Called on reconfigure or module destroy.
     func teardown() {
-        lock.lock()
-        defer { lock.unlock() }
+        performSync { teardownOnQueue() }
+    }
+
+    private func teardownOnQueue() {
         // Remove observers
         NotificationCenter.default.removeObserver(
             self, name: AVAudioSession.routeChangeNotification, object: nil)
@@ -260,10 +294,15 @@ class SharedAudioEngine {
               let reason = AVAudioSession.RouteChangeReason(rawValue: reasonValue) else {
             return
         }
+        // Hop off AVFoundation's notification thread onto the engine queue before
+        // touching the engine or session — that thread can hold an internal lock
+        // when delivering this, and the queue serializes us against connect/disconnect.
+        engineQueue.async { [weak self] in
+            self?.handleRouteChangeOnQueue(reason: reason)
+        }
+    }
 
-        lock.lock()
-        defer { lock.unlock() }
-
+    private func handleRouteChangeOnQueue(reason: AVAudioSession.RouteChangeReason) {
         let routeDescription = AVAudioSession.sharedInstance().currentRoute.outputs
             .map { "\($0.portName) (\($0.portType.rawValue))" }
             .joined(separator: ", ")
@@ -410,7 +449,7 @@ class SharedAudioEngine {
             // Voice processing can cause the engine to die asynchronously after
             // appearing to start. Wait 100ms then re-verify before declaring success.
             let verifyDelay: TimeInterval = (self.playbackMode == .conversation || self.playbackMode == .voiceProcessing) ? 0.1 : 0.05
-            DispatchQueue.main.asyncAfter(deadline: .now() + verifyDelay) { [weak self] in
+            self.engineQueue.asyncAfter(deadline: .now() + verifyDelay) { [weak self] in
                 guard let self = self, let engine = self.engine else {
                     self?.isRebuildingForRouteChange = false
                     return
@@ -449,7 +488,7 @@ class SharedAudioEngine {
 
         if delay > 0 {
             Logger.debug("[\(SharedAudioEngine.TAG)] Waiting \(Int(delay * 1000))ms before attempt \(attempt + 1)")
-            DispatchQueue.main.asyncAfter(deadline: .now() + delay, execute: work)
+            engineQueue.asyncAfter(deadline: .now() + delay, execute: work)
         } else {
             work()
         }
@@ -493,16 +532,19 @@ class SharedAudioEngine {
         guard let info = notification.userInfo,
               let typeValue = info[AVAudioSessionInterruptionTypeKey] as? UInt,
               let type = AVAudioSession.InterruptionType(rawValue: typeValue) else { return }
+        let optionsValue = info[AVAudioSessionInterruptionOptionKey] as? UInt ?? 0
+        // Hop off AVFoundation's notification thread onto the engine queue.
+        engineQueue.async { [weak self] in
+            self?.handleInterruptionOnQueue(type: type, optionsValue: optionsValue)
+        }
+    }
 
-        lock.lock()
-        defer { lock.unlock() }
-
+    private func handleInterruptionOnQueue(type: AVAudioSession.InterruptionType, optionsValue: UInt) {
         if type == .began {
             Logger.debug("[\(SharedAudioEngine.TAG)] Audio session interruption began")
             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.
@@ -529,6 +571,8 @@ class SharedAudioEngine {
     }
 
     deinit {
-        teardown()
+        // At dealloc there are no other references, so no concurrency — run the
+        // body directly rather than dispatching onto the queue during teardown.
+        teardownOnQueue()
     }
 }

package/package.json

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