@edkimmel/expo-audio-stream 0.4.0 → 0.4.2

package/README.md

@@ -79,6 +79,7 @@ const result = await Pipeline.connect({
   channelCount: 1,
   targetBufferMs: 80,
   frequencyBandIntervalMs: 100, // optional: emit frequency bands every 100ms
+  audioMode: "mixWithOthers",   // coexist with other apps (default)
 });
 
 // Subscribe to events
@@ -226,11 +227,23 @@ interface ConnectPipelineOptions {
   sampleRate?: number;              // default 24000
   channelCount?: number;            // default 1 (mono)
   targetBufferMs?: number;          // ms to buffer before priming gate opens (default 80)
+  playbackMode?: "voiceProcessing" | "conversation";
   frequencyBandIntervalMs?: number; // emit PipelineFrequencyBands every N ms (omit to disable)
   frequencyBandConfig?: FrequencyBandConfig; // crossover frequencies (optional)
+  audioMode?: "mixWithOthers" | "duckOthers" | "doNotMix"; // default "mixWithOthers"
 }
 ```
 
+#### `audioMode`
+
+Controls how pipeline playback coexists with audio from other apps on the device. Default: `"mixWithOthers"` (matches expo-audio).
+
+- **`"mixWithOthers"`** — plays alongside other apps without interrupting them. On Android no audio focus is requested; on iOS the session uses the `.mixWithOthers` category option. Best for sound effects and short clips.
+- **`"duckOthers"`** — requests audio focus with ducking. Other apps lower their volume but keep playing.
+- **`"doNotMix"`** — requests exclusive audio focus. Other apps pause.
+
+> **Breaking change:** The default was effectively `"doNotMix"` in prior versions. If you rely on the previous behavior — where connecting the pipeline pauses other apps' audio — pass `audioMode: "doNotMix"` explicitly when calling `Pipeline.connect`.
+
 ### PushPipelineAudioOptions
 
 ```typescript

package/android/src/main/java/expo/modules/audiostream/pipeline/AudioPipeline.kt

@@ -58,6 +58,29 @@ interface PipelineListener {
 // AudioPipeline
 // ────────────────────────────────────────────────────────────────────────────
 
+/**
+ * Controls how pipeline playback coexists with audio from other apps.
+ * Mirrors the `PipelineAudioMode` TS type.
+ */
+enum class AudioMode {
+    /** No focus request — playback mixes freely with other audio. */
+    MIX_WITH_OTHERS,
+
+    /** Request transient focus with ducking — others lower volume but keep playing. */
+    DUCK_OTHERS,
+
+    /** Request exclusive focus — others pause. */
+    DO_NOT_MIX;
+
+    companion object {
+        fun fromString(value: String?): AudioMode = when (value) {
+            "duckOthers" -> DUCK_OTHERS
+            "doNotMix"   -> DO_NOT_MIX
+            else         -> MIX_WITH_OTHERS  // default includes null, "mixWithOthers", and unknown
+        }
+    }
+}
+
 /**
  * Core orchestrator for the native audio pipeline.
  *
@@ -90,6 +113,7 @@ class AudioPipeline(
     private val frequencyBandIntervalMs: Int = 100,
     private val lowCrossoverHz: Float = 300f,
     private val highCrossoverHz: Float = 2000f,
+    private val audioMode: AudioMode = AudioMode.MIX_WITH_OTHERS,
     private val listener: PipelineListener
 ) {
     companion object {
@@ -550,18 +574,46 @@ class AudioPipeline(
     // ════════════════════════════════════════════════════════════════════
 
     private fun requestAudioFocus() {
-        val result = audioManager.requestAudioFocus(
-            focusChangeListener,
-            AudioManager.STREAM_MUSIC,
-            AudioManager.AUDIOFOCUS_GAIN
-        )
-        hasAudioFocus.set(result == AudioManager.AUDIOFOCUS_REQUEST_GRANTED)
-        if (!hasAudioFocus.get()) {
-            Log.w(TAG, "Audio focus request denied")
+        when (audioMode) {
+            AudioMode.MIX_WITH_OTHERS -> {
+                // No focus request — we coexist silently with other apps.
+                // Mark as "has focus" so the write loop proceeds unconditionally.
+                hasAudioFocus.set(true)
+                audioFocusLost.set(false)
+                Log.d(TAG, "Audio focus skipped (mixWithOthers)")
+            }
+            AudioMode.DUCK_OTHERS -> {
+                val result = audioManager.requestAudioFocus(
+                    focusChangeListener,
+                    AudioManager.STREAM_MUSIC,
+                    AudioManager.AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK
+                )
+                hasAudioFocus.set(result == AudioManager.AUDIOFOCUS_REQUEST_GRANTED)
+                if (!hasAudioFocus.get()) {
+                    Log.w(TAG, "Audio focus request (duckOthers) denied")
+                }
+            }
+            AudioMode.DO_NOT_MIX -> {
+                val result = audioManager.requestAudioFocus(
+                    focusChangeListener,
+                    AudioManager.STREAM_MUSIC,
+                    AudioManager.AUDIOFOCUS_GAIN
+                )
+                hasAudioFocus.set(result == AudioManager.AUDIOFOCUS_REQUEST_GRANTED)
+                if (!hasAudioFocus.get()) {
+                    Log.w(TAG, "Audio focus request (doNotMix) denied")
+                }
+            }
         }
     }
 
     private fun abandonAudioFocus() {
+        if (audioMode == AudioMode.MIX_WITH_OTHERS) {
+            // No focus was ever requested — nothing to abandon.
+            hasAudioFocus.set(false)
+            audioFocusLost.set(false)
+            return
+        }
         audioManager.abandonAudioFocus(focusChangeListener)
         hasAudioFocus.set(false)
         audioFocusLost.set(false)

package/android/src/main/java/expo/modules/audiostream/pipeline/PipelineIntegration.kt

@@ -121,6 +121,7 @@ class PipelineIntegration(
             val bandConfig = options["frequencyBandConfig"] as? Map<*, *>
             val lowCrossoverHz = (bandConfig?.get("lowCrossoverHz") as? Number)?.toFloat() ?: 300f
             val highCrossoverHz = (bandConfig?.get("highCrossoverHz") as? Number)?.toFloat() ?: 2000f
+            val audioMode = AudioMode.fromString(options["audioMode"] as? String)
 
             pipeline = AudioPipeline(
                 context = context,
@@ -130,6 +131,7 @@ class PipelineIntegration(
                 frequencyBandIntervalMs = frequencyBandIntervalMs,
                 lowCrossoverHz = lowCrossoverHz,
                 highCrossoverHz = highCrossoverHz,
+                audioMode = audioMode,
                 listener = this
             )
             pipeline!!.connect()

package/build/pipeline/types.d.ts

@@ -1,4 +1,15 @@
 import { PlaybackMode, FrequencyBandConfig, FrequencyBands } from "../types";
+/**
+ * How the pipeline's playback should coexist with other audio on the device.
+ *
+ * - `'mixWithOthers'` (default): plays alongside other apps without
+ *   interrupting them. On Android no audio focus is requested. Best for
+ *   sound effects and short clips.
+ * - `'duckOthers'`: requests audio focus with ducking. Other apps lower
+ *   their volume but keep playing.
+ * - `'doNotMix'`: requests exclusive audio focus. Other apps pause.
+ */
+export type PipelineAudioMode = 'mixWithOthers' | 'duckOthers' | 'doNotMix';
 /** Options passed to `connectPipeline()`. */
 export interface ConnectPipelineOptions {
     /** Sample rate in Hz (default 24000). */
@@ -18,6 +29,15 @@ export interface ConnectPipelineOptions {
     frequencyBandIntervalMs?: number;
     /** Optional frequency band crossover configuration. */
     frequencyBandConfig?: FrequencyBandConfig;
+    /**
+     * How pipeline playback should coexist with other apps' audio.
+     * Default is `'mixWithOthers'` (matches expo-audio).
+     *
+     * Note: this is a **behavior change** vs. prior versions of this library,
+     * which effectively used `'doNotMix'`. Pass `'doNotMix'` explicitly to
+     * preserve that old behavior.
+     */
+    audioMode?: PipelineAudioMode;
 }
 /** Result returned from a successful `connectPipeline()` call. */
 export interface ConnectPipelineResult {

package/build/pipeline/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/pipeline/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/pipeline/types.ts"],"names":[],"mappings":"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"}

package/build/pipeline/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/pipeline/types.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,8CAA8C;AAC9C,+EAA+E","sourcesContent":["// ────────────────────────────────────────────────────────────────────────────\n// Native Audio Pipeline — V3 TypeScript Types\n// ────────────────────────────────────────────────────────────────────────────\n\nimport { PlaybackMode, FrequencyBandConfig, FrequencyBands } from \"../types\";\n\n// ── Connect ─────────────────────────────────────────────────────────────────\n\n/** Options passed to `connectPipeline()`. */\nexport interface ConnectPipelineOptions {\n  /** Sample rate in Hz (default 24000). */\n  sampleRate?: number;\n  /** Number of channels — 1 = mono, 2 = stereo (default 1). */\n  channelCount?: number;\n  /**\n   * How many ms of audio to accumulate in the jitter buffer before the\n   * priming gate opens and audio begins playing (default 80).\n   */\n  targetBufferMs?: number;\n  /**\n   * Playback mode hint for native optimizations. Affects thread priority and\n   */\n  playbackMode?: PlaybackMode;\n  /** Interval in ms for PipelineFrequencyBands events (default 100). */\n  frequencyBandIntervalMs?: number;\n  /** Optional frequency band crossover configuration. */\n  frequencyBandConfig?: FrequencyBandConfig;\n}\n\n/** Result returned from a successful `connectPipeline()` call. */\nexport interface ConnectPipelineResult {\n  sampleRate: number;\n  channelCount: number;\n  targetBufferMs: number;\n  /**\n   * Frame size in samples derived from the device HAL's\n   * `AudioTrack.getMinBufferSize()`. Useful for understanding the write\n   * granularity on the native side.\n   */\n  frameSizeSamples: number;\n}\n\n// ── Push Audio ──────────────────────────────────────────────────────────────\n\n/** Options passed to `pushPipelineAudio()` / `pushPipelineAudioSync()`. */\nexport interface PushPipelineAudioOptions {\n  /** Base64-encoded PCM 16-bit signed LE audio data. */\n  audio: string;\n  /** Conversation turn identifier. */\n  turnId: string;\n  /** True if this is the first chunk of a new turn (resets jitter buffer). */\n  isFirstChunk?: boolean;\n  /** True if this is the final chunk of the current turn (marks end-of-stream). */\n  isLastChunk?: boolean;\n}\n\n// ── Invalidate Turn ─────────────────────────────────────────────────────────\n\n/** Options passed to `invalidatePipelineTurn()`. */\nexport interface InvalidatePipelineTurnOptions {\n  /** The new turn identifier — stale audio for the old turn is discarded. */\n  turnId: string;\n}\n\n// ── State ───────────────────────────────────────────────────────────────────\n\n/**\n * Pipeline states reported via `PipelineStateChanged` events.\n *\n * - `idle`       — connected but no audio flowing\n * - `connecting` — AudioTrack being created, focus being requested\n * - `streaming`  — actively receiving and playing audio\n * - `draining`   — end-of-stream marked, playing remaining buffer\n * - `error`      — unrecoverable error (zombie, write failure, etc.)\n */\nexport type PipelineState =\n  | 'idle'\n  | 'connecting'\n  | 'streaming'\n  | 'draining'\n  | 'error';\n\n// ── Events ──────────────────────────────────────────────────────────────────\n\n/** Payload for `PipelineStateChanged`. */\nexport interface PipelineStateChangedEvent {\n  state: PipelineState;\n}\n\n/** Payload for `PipelinePlaybackStarted`. */\nexport interface PipelinePlaybackStartedEvent {\n  turnId: string;\n}\n\n/** Payload for `PipelineError`. */\nexport interface PipelineErrorEvent {\n  code: string;\n  message: string;\n}\n\n/** Payload for `PipelineZombieDetected`. */\nexport interface PipelineZombieDetectedEvent {\n  playbackHead: number;\n  stalledMs: number;\n}\n\n/** Payload for `PipelineUnderrun`. */\nexport interface PipelineUnderrunEvent {\n  count: number;\n}\n\n/** Payload for `PipelineDrained`. */\nexport interface PipelineDrainedEvent {\n  turnId: string;\n}\n\n/** Payload for `PipelineAudioFocusLost` (empty — presence is the signal). */\nexport type PipelineAudioFocusLostEvent = Record<string, never>;\n\n/** Payload for `PipelineAudioFocusResumed` (empty — presence is the signal). */\nexport type PipelineAudioFocusResumedEvent = Record<string, never>;\n\n/** Payload for `PipelineFrequencyBands`. */\nexport interface PipelineFrequencyBandsEvent extends FrequencyBands {}\n\n/**\n * Map of all pipeline event names to their payload types.\n * Used with `Pipeline.subscribe<K>()` for type-safe event subscriptions.\n */\nexport interface PipelineEventMap {\n  PipelineStateChanged: PipelineStateChangedEvent;\n  PipelinePlaybackStarted: PipelinePlaybackStartedEvent;\n  PipelineError: PipelineErrorEvent;\n  PipelineZombieDetected: PipelineZombieDetectedEvent;\n  PipelineUnderrun: PipelineUnderrunEvent;\n  PipelineDrained: PipelineDrainedEvent;\n  PipelineAudioFocusLost: PipelineAudioFocusLostEvent;\n  PipelineAudioFocusResumed: PipelineAudioFocusResumedEvent;\n  PipelineFrequencyBands: PipelineFrequencyBandsEvent;\n}\n\n/** Union of all pipeline event name strings. */\nexport type PipelineEventName = keyof PipelineEventMap;\n\n// ── Telemetry ───────────────────────────────────────────────────────────────\n\n/** Jitter buffer telemetry counters. */\nexport interface PipelineBufferTelemetry {\n  /** Current buffer level in milliseconds. */\n  bufferMs: number;\n  /** Current buffer level in samples. */\n  bufferSamples: number;\n  /** Whether the priming gate has opened. */\n  primed: boolean;\n  /** Total samples written by the producer since last reset. */\n  totalWritten: number;\n  /** Total samples read by the consumer since last reset. */\n  totalRead: number;\n  /** Number of underrun events. */\n  underrunCount: number;\n  /** Peak buffer level in samples. */\n  peakLevel: number;\n}\n\n/** Full pipeline telemetry snapshot. */\nexport interface PipelineTelemetry extends PipelineBufferTelemetry {\n  /** Current pipeline state. */\n  state: PipelineState;\n  /** Total pushAudio/pushAudioSync calls since connect. */\n  totalPushCalls: number;\n  /** Total bytes pushed since connect. */\n  totalPushBytes: number;\n  /** Total write-loop iterations since connect. */\n  totalWriteLoops: number;\n  /** Current turn identifier. */\n  turnId: string;\n}\n"]}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/pipeline/types.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,8CAA8C;AAC9C,+EAA+E","sourcesContent":["// ────────────────────────────────────────────────────────────────────────────\n// Native Audio Pipeline — V3 TypeScript Types\n// ────────────────────────────────────────────────────────────────────────────\n\nimport { PlaybackMode, FrequencyBandConfig, FrequencyBands } from \"../types\";\n\n// ── Connect ─────────────────────────────────────────────────────────────────\n\n/**\n * How the pipeline's playback should coexist with other audio on the device.\n *\n * - `'mixWithOthers'` (default): plays alongside other apps without\n *   interrupting them. On Android no audio focus is requested. Best for\n *   sound effects and short clips.\n * - `'duckOthers'`: requests audio focus with ducking. Other apps lower\n *   their volume but keep playing.\n * - `'doNotMix'`: requests exclusive audio focus. Other apps pause.\n */\nexport type PipelineAudioMode = 'mixWithOthers' | 'duckOthers' | 'doNotMix';\n\n/** Options passed to `connectPipeline()`. */\nexport interface ConnectPipelineOptions {\n  /** Sample rate in Hz (default 24000). */\n  sampleRate?: number;\n  /** Number of channels — 1 = mono, 2 = stereo (default 1). */\n  channelCount?: number;\n  /**\n   * How many ms of audio to accumulate in the jitter buffer before the\n   * priming gate opens and audio begins playing (default 80).\n   */\n  targetBufferMs?: number;\n  /**\n   * Playback mode hint for native optimizations. Affects thread priority and\n   */\n  playbackMode?: PlaybackMode;\n  /** Interval in ms for PipelineFrequencyBands events (default 100). */\n  frequencyBandIntervalMs?: number;\n  /** Optional frequency band crossover configuration. */\n  frequencyBandConfig?: FrequencyBandConfig;\n  /**\n   * How pipeline playback should coexist with other apps' audio.\n   * Default is `'mixWithOthers'` (matches expo-audio).\n   *\n   * Note: this is a **behavior change** vs. prior versions of this library,\n   * which effectively used `'doNotMix'`. Pass `'doNotMix'` explicitly to\n   * preserve that old behavior.\n   */\n  audioMode?: PipelineAudioMode;\n}\n\n/** Result returned from a successful `connectPipeline()` call. */\nexport interface ConnectPipelineResult {\n  sampleRate: number;\n  channelCount: number;\n  targetBufferMs: number;\n  /**\n   * Frame size in samples derived from the device HAL's\n   * `AudioTrack.getMinBufferSize()`. Useful for understanding the write\n   * granularity on the native side.\n   */\n  frameSizeSamples: number;\n}\n\n// ── Push Audio ──────────────────────────────────────────────────────────────\n\n/** Options passed to `pushPipelineAudio()` / `pushPipelineAudioSync()`. */\nexport interface PushPipelineAudioOptions {\n  /** Base64-encoded PCM 16-bit signed LE audio data. */\n  audio: string;\n  /** Conversation turn identifier. */\n  turnId: string;\n  /** True if this is the first chunk of a new turn (resets jitter buffer). */\n  isFirstChunk?: boolean;\n  /** True if this is the final chunk of the current turn (marks end-of-stream). */\n  isLastChunk?: boolean;\n}\n\n// ── Invalidate Turn ─────────────────────────────────────────────────────────\n\n/** Options passed to `invalidatePipelineTurn()`. */\nexport interface InvalidatePipelineTurnOptions {\n  /** The new turn identifier — stale audio for the old turn is discarded. */\n  turnId: string;\n}\n\n// ── State ───────────────────────────────────────────────────────────────────\n\n/**\n * Pipeline states reported via `PipelineStateChanged` events.\n *\n * - `idle`       — connected but no audio flowing\n * - `connecting` — AudioTrack being created, focus being requested\n * - `streaming`  — actively receiving and playing audio\n * - `draining`   — end-of-stream marked, playing remaining buffer\n * - `error`      — unrecoverable error (zombie, write failure, etc.)\n */\nexport type PipelineState =\n  | 'idle'\n  | 'connecting'\n  | 'streaming'\n  | 'draining'\n  | 'error';\n\n// ── Events ──────────────────────────────────────────────────────────────────\n\n/** Payload for `PipelineStateChanged`. */\nexport interface PipelineStateChangedEvent {\n  state: PipelineState;\n}\n\n/** Payload for `PipelinePlaybackStarted`. */\nexport interface PipelinePlaybackStartedEvent {\n  turnId: string;\n}\n\n/** Payload for `PipelineError`. */\nexport interface PipelineErrorEvent {\n  code: string;\n  message: string;\n}\n\n/** Payload for `PipelineZombieDetected`. */\nexport interface PipelineZombieDetectedEvent {\n  playbackHead: number;\n  stalledMs: number;\n}\n\n/** Payload for `PipelineUnderrun`. */\nexport interface PipelineUnderrunEvent {\n  count: number;\n}\n\n/** Payload for `PipelineDrained`. */\nexport interface PipelineDrainedEvent {\n  turnId: string;\n}\n\n/** Payload for `PipelineAudioFocusLost` (empty — presence is the signal). */\nexport type PipelineAudioFocusLostEvent = Record<string, never>;\n\n/** Payload for `PipelineAudioFocusResumed` (empty — presence is the signal). */\nexport type PipelineAudioFocusResumedEvent = Record<string, never>;\n\n/** Payload for `PipelineFrequencyBands`. */\nexport interface PipelineFrequencyBandsEvent extends FrequencyBands {}\n\n/**\n * Map of all pipeline event names to their payload types.\n * Used with `Pipeline.subscribe<K>()` for type-safe event subscriptions.\n */\nexport interface PipelineEventMap {\n  PipelineStateChanged: PipelineStateChangedEvent;\n  PipelinePlaybackStarted: PipelinePlaybackStartedEvent;\n  PipelineError: PipelineErrorEvent;\n  PipelineZombieDetected: PipelineZombieDetectedEvent;\n  PipelineUnderrun: PipelineUnderrunEvent;\n  PipelineDrained: PipelineDrainedEvent;\n  PipelineAudioFocusLost: PipelineAudioFocusLostEvent;\n  PipelineAudioFocusResumed: PipelineAudioFocusResumedEvent;\n  PipelineFrequencyBands: PipelineFrequencyBandsEvent;\n}\n\n/** Union of all pipeline event name strings. */\nexport type PipelineEventName = keyof PipelineEventMap;\n\n// ── Telemetry ───────────────────────────────────────────────────────────────\n\n/** Jitter buffer telemetry counters. */\nexport interface PipelineBufferTelemetry {\n  /** Current buffer level in milliseconds. */\n  bufferMs: number;\n  /** Current buffer level in samples. */\n  bufferSamples: number;\n  /** Whether the priming gate has opened. */\n  primed: boolean;\n  /** Total samples written by the producer since last reset. */\n  totalWritten: number;\n  /** Total samples read by the consumer since last reset. */\n  totalRead: number;\n  /** Number of underrun events. */\n  underrunCount: number;\n  /** Peak buffer level in samples. */\n  peakLevel: number;\n}\n\n/** Full pipeline telemetry snapshot. */\nexport interface PipelineTelemetry extends PipelineBufferTelemetry {\n  /** Current pipeline state. */\n  state: PipelineState;\n  /** Total pushAudio/pushAudioSync calls since connect. */\n  totalPushCalls: number;\n  /** Total bytes pushed since connect. */\n  totalPushBytes: number;\n  /** Total write-loop iterations since connect. */\n  totalWriteLoops: number;\n  /** Current turn identifier. */\n  turnId: string;\n}\n"]}

package/ios/ExpoPlayAudioStreamModule.swift

@@ -158,20 +158,45 @@ public class ExpoPlayAudioStreamModule: Module, MicrophoneDataDelegate, Pipeline
 
         AsyncFunction("connectPipeline") { (options: [String: Any], promise: Promise) in
             do {
+                // Always ensure the session is set up (no-op if already initialized).
+                // The one-time guard inside ensureAudioSessionInitialized covers
+                // the mic-only path; we re-apply the category below every connect
+                // because audioMode may change between connects.
                 if !self.isAudioSessionInitialized {
                     try self.ensureAudioSessionInitialized()
                 }
 
-                // Parse playback mode from options to configure shared engine
-                let playbackModeString = options["playbackMode"] as? String ?? "regular"
+                // Parse audioMode (default: "mixWithOthers")
+                let audioModeString = options["audioMode"] as? String ?? "mixWithOthers"
+                var categoryOptions: AVAudioSession.CategoryOptions =
+                    [.defaultToSpeaker, .allowBluetooth, .allowBluetoothA2DP]
+                switch audioModeString {
+                case "mixWithOthers":
+                    categoryOptions.insert(.mixWithOthers)
+                case "duckOthers":
+                    categoryOptions.insert(.duckOthers)
+                case "doNotMix":
+                    break  // no additional option
+                default:
+                    categoryOptions.insert(.mixWithOthers)
+                }
+
+                // Reconfigure the session category with the right mix options.
+                // Runtime category changes are supported on iOS.
+                let audioSession = AVAudioSession.sharedInstance()
+                try audioSession.setCategory(
+                    .playAndRecord, mode: .videoChat, options: categoryOptions)
+                try audioSession.setActive(true)
+
+                // Parse playback mode from options to configure shared engine.
+                // Always use VP — this library is meant for mic+speaker combos.
+                let playbackModeString = options["playbackMode"] as? String ?? "conversation"
                 let playbackMode: PlaybackMode
                 switch playbackModeString {
                 case "voiceProcessing":
                     playbackMode = .voiceProcessing
-                case "conversation":
-                    playbackMode = .conversation
                 default:
-                    playbackMode = .regular
+                    playbackMode = .conversation
                 }
 
                 // Configure shared engine (handles voice processing)

package/ios/SharedAudioEngine.swift

@@ -38,18 +38,14 @@ protocol SharedAudioEngineDelegate: AnyObject {
 /// Consumers attach their own AVAudioPlayerNode via `attachNode(_:format:)`.
 /// The mixer handles sample-rate conversion from each node's format to the
 /// hardware output format automatically.
-///
-/// All public methods are serialized on an internal queue to prevent races
-/// between Expo async-function calls, notification handlers, and teardown.
 class SharedAudioEngine {
     private static let TAG = "SharedAudioEngine"
 
-    /// Serial queue that protects all engine / node / state mutations.
-    private let queue = DispatchQueue(label: "expo.audio.SharedAudioEngine")
+    private let lock = NSRecursiveLock()
 
     // ── Engine state ─────────────────────────────────────────────────────
     private(set) var engine: AVAudioEngine?
-    private(set) var playbackMode: PlaybackMode = .regular
+    private(set) var playbackMode: PlaybackMode = .conversation
     private(set) var isConfigured = false
 
     /// All registered consumers receive route-change and interruption callbacks.
@@ -57,11 +53,17 @@ class SharedAudioEngine {
     private let delegates = NSHashTable<AnyObject>.weakObjects()
 
     func addDelegate(_ d: SharedAudioEngineDelegate) {
-        queue.sync { delegates.add(d as AnyObject) }
+        lock.lock()
+        defer { lock.unlock() }
+        if !delegates.contains(d as AnyObject) {
+            delegates.add(d as AnyObject)
+        }
     }
 
     func removeDelegate(_ d: SharedAudioEngineDelegate) {
-        queue.sync { delegates.remove(d as AnyObject) }
+        lock.lock()
+        defer { lock.unlock() }
+        delegates.remove(d as AnyObject)
     }
 
     private func notifyDelegates(_ block: (SharedAudioEngineDelegate) -> Void) {
@@ -90,10 +92,8 @@ class SharedAudioEngine {
     ///
     /// - Parameter playbackMode: Determines whether voice processing is enabled.
     func configure(playbackMode: PlaybackMode) throws {
-        try queue.sync { try _configure(playbackMode: playbackMode) }
-    }
-
-    private func _configure(playbackMode: PlaybackMode) throws {
+        lock.lock()
+        defer { lock.unlock() }
         if isConfigured && self.playbackMode == playbackMode && engine?.isRunning == true {
             Logger.debug("[\(SharedAudioEngine.TAG)] Already configured for \(playbackMode) and engine running, skipping")
             return
@@ -105,7 +105,7 @@ class SharedAudioEngine {
 
         // Tear down existing engine (keeps attachedNodes info for re-attach)
         let previousNodes = attachedNodes
-        _teardown()
+        teardown()
 
         Logger.debug("[\(SharedAudioEngine.TAG)] Configuring engine — playbackMode=\(playbackMode)")
 
@@ -119,12 +119,10 @@ class SharedAudioEngine {
             Logger.debug("[\(SharedAudioEngine.TAG)] Voice processing enabled")
         }
 
-        // Force the output node (and implicitly the graph) to be created
-        // before starting. inputNode/outputNode are lazy — if neither is
-        // accessed, the graph has zero nodes and Initialize crashes with
-        // "inputNode != nullptr || outputNode != nullptr".
-        // The VP path above already accesses both; this covers regular mode.
-        _ = engine.mainMixerNode
+        // VP accesses inputNode/outputNode above, which creates the graph.
+        // Do NOT access mainMixerNode here — inserting the mixer after
+        // setVoiceProcessingEnabled disrupts VoiceProcessingIO's internal
+        // graph and causes scheduleBuffer completions to never fire.
 
         try engine.start()
 
@@ -142,7 +140,7 @@ class SharedAudioEngine {
 
         // Re-attach any nodes that were connected before reconfiguration
         for info in previousNodes {
-            _attachNode(info.node, format: info.format)
+            attachNode(info.node, format: info.format)
             info.node.play()
         }
 
@@ -162,10 +160,8 @@ class SharedAudioEngine {
     /// Connects `node → mainMixerNode` with the given format.
     /// The mixer handles sample-rate conversion to hardware output.
     func attachNode(_ node: AVAudioPlayerNode, format: AVAudioFormat) {
-        queue.sync { _attachNode(node, format: format) }
-    }
-
-    private func _attachNode(_ node: AVAudioPlayerNode, format: AVAudioFormat) {
+        lock.lock()
+        defer { lock.unlock() }
         guard let engine = engine else {
             Logger.debug("[\(SharedAudioEngine.TAG)] attachNode called but engine is nil")
             return
@@ -180,25 +176,23 @@ class SharedAudioEngine {
 
     /// Detach a consumer's player node from the shared engine.
     func detachNode(_ node: AVAudioPlayerNode) {
-        queue.sync { _detachNode(node) }
-    }
-
-    private func _detachNode(_ node: AVAudioPlayerNode) {
+        lock.lock()
+        defer { lock.unlock() }
         guard let engine = engine else { return }
 
+        node.pause()
+        node.stop()
+
+        // Only disconnect/detach if the node is still attached to this engine.
+        // The node may already have been removed (e.g. engine died, concurrent
+        // teardown, or duplicate disconnect call).
         if node.engine === engine {
             engine.disconnectNodeOutput(node)
             engine.detach(node)
         }
         attachedNodes.removeAll { $0.node === node }
 
-        // Stop the engine if no nodes remain — no reason to keep it running.
-        if attachedNodes.isEmpty && engine.isRunning {
-            engine.stop()
-            Logger.debug("[\(SharedAudioEngine.TAG)] Node detached, engine stopped (no remaining nodes)")
-        } else {
-            Logger.debug("[\(SharedAudioEngine.TAG)] Node detached")
-        }
+        Logger.debug("[\(SharedAudioEngine.TAG)] Node detached")
     }
 
     // ════════════════════════════════════════════════════════════════════
@@ -207,31 +201,21 @@ class SharedAudioEngine {
 
     /// Tear down the engine completely. Called on reconfigure or module destroy.
     func teardown() {
-        queue.sync { _teardown() }
-    }
-
-    private func _teardown() {
+        lock.lock()
+        defer { lock.unlock() }
         // Remove observers
         NotificationCenter.default.removeObserver(
             self, name: AVAudioSession.routeChangeNotification, object: nil)
         NotificationCenter.default.removeObserver(
             self, name: AVAudioSession.interruptionNotification, object: nil)
 
-        // Disable voice processing BEFORE stopping so the system begins
-        // swapping VoiceProcessingIO back to RemoteIO while we clean up.
-        // Without this, a new engine created immediately after teardown can
-        // crash in Initialize (inputNode/outputNode both nil) because the
-        // IO unit is still mid-swap.
-        if playbackMode == .conversation || playbackMode == .voiceProcessing {
-            if let engine = engine {
-                try? engine.inputNode.setVoiceProcessingEnabled(false)
-                try? engine.outputNode.setVoiceProcessingEnabled(false)
-            }
-        }
-
-        engine?.stop()
+        // Detach all tracked nodes
         if let engine = engine {
             for info in attachedNodes {
+                info.node.pause()
+                info.node.stop()
+                // Guard against nodes already removed from engine (e.g. engine
+                // died or node was detached by a concurrent disconnect call).
                 if info.node.engine === engine {
                     engine.disconnectNodeOutput(info.node)
                     engine.detach(info.node)
@@ -240,6 +224,15 @@ class SharedAudioEngine {
         }
         attachedNodes.removeAll()
 
+        // Disable voice processing before stopping
+        if playbackMode == .conversation || playbackMode == .voiceProcessing {
+            if let engine = engine {
+                try? engine.inputNode.setVoiceProcessingEnabled(false)
+                try? engine.outputNode.setVoiceProcessingEnabled(false)
+            }
+        }
+
+        engine?.stop()
         engine = nil
         isConfigured = false
 
@@ -260,12 +253,9 @@ class SharedAudioEngine {
             return
         }
 
-        queue.async { [weak self] in
-            self?._handleRouteChange(reason: reason)
-        }
-    }
+        lock.lock()
+        defer { lock.unlock() }
 
-    private func _handleRouteChange(reason: AVAudioSession.RouteChangeReason) {
         let routeDescription = AVAudioSession.sharedInstance().currentRoute.outputs
             .map { "\($0.portName) (\($0.portType.rawValue))" }
             .joined(separator: ", ")
@@ -285,7 +275,14 @@ class SharedAudioEngine {
             // Suppress completion handlers from node.stop() re-entering the scheduling loop
             isRebuildingForRouteChange = true
 
-            // 1. Stop engine
+            // 1. Stop all attached nodes (completion handlers fire but are gated)
+            for info in attachedNodes {
+                Logger.debug("[\(SharedAudioEngine.TAG)] Stopping node — isPlaying=\(info.node.isPlaying)")
+                info.node.pause()
+                info.node.stop()
+            }
+
+            // 2. Stop engine
             if engine.isRunning {
                 engine.stop()
                 Logger.debug("[\(SharedAudioEngine.TAG)] Engine stopped")
@@ -293,7 +290,7 @@ class SharedAudioEngine {
                 Logger.debug("[\(SharedAudioEngine.TAG)] Engine was already stopped")
             }
 
-            // 2. Detach all nodes
+            // 3. Detach all nodes
             for info in attachedNodes {
                 if info.node.engine === engine {
                     engine.disconnectNodeOutput(info.node)
@@ -302,7 +299,7 @@ class SharedAudioEngine {
             }
             Logger.debug("[\(SharedAudioEngine.TAG)] Nodes detached (\(attachedNodes.count))")
 
-            // 3. Re-enable voice processing (resets after engine stop)
+            // 4. Re-enable voice processing (resets after engine stop)
             if playbackMode == .conversation || playbackMode == .voiceProcessing {
                 do {
                     try engine.inputNode.setVoiceProcessingEnabled(true)
@@ -312,14 +309,14 @@ class SharedAudioEngine {
                 }
             }
 
-            // 4. Re-attach all nodes
+            // 5. Re-attach all nodes
             for info in attachedNodes {
                 engine.attach(info.node)
                 engine.connect(info.node, to: engine.mainMixerNode, format: info.format)
             }
             Logger.debug("[\(SharedAudioEngine.TAG)] Nodes re-attached (\(attachedNodes.count))")
 
-            // 5. Reactivate session and restart engine with retry.
+            // 6. Reactivate session and restart engine with retry.
             // Voice processing mode switches the underlying audio unit (RemoteIO ↔
             // VoiceProcessingIO). This swap completes asynchronously — if we call
             // engine.start() immediately, the engine appears to start (isRunning=true)
@@ -330,7 +327,7 @@ class SharedAudioEngine {
                 ? [0.15, 0.3, 0.6]   // 150ms, 300ms, 600ms pre-start delay for VP mode (+100ms post-start verify)
                 : [0.0, 0.1, 0.25]   // immediate, then backoff for non-VP (+50ms post-start verify)
 
-            _attemptRestart(engine: engine, retryDelays: retryDelays, attempt: 0)
+            self.attemptRestart(engine: engine, retryDelays: retryDelays, attempt: 0)
 
         case .categoryChange:
             Logger.debug("[\(SharedAudioEngine.TAG)] Audio session category changed")
@@ -343,14 +340,12 @@ class SharedAudioEngine {
     /// is truly running and nodes are playing before declaring success.
     /// On final failure, falls back to a full rebuild. If that also fails,
     /// tears down everything and notifies delegates via `engineDidDie`.
-    ///
-    /// Must be called on `queue`.
-    private func _attemptRestart(engine: AVAudioEngine, retryDelays: [TimeInterval], attempt: Int) {
+    private func attemptRestart(engine: AVAudioEngine, retryDelays: [TimeInterval], attempt: Int) {
         guard attempt < retryDelays.count else {
             // Exhausted in-place retries — try a full rebuild as last resort
             Logger.debug("[\(SharedAudioEngine.TAG)] All \(retryDelays.count) restart attempts failed — attempting full rebuild")
             isRebuildingForRouteChange = false
-            _rebuildEngine()
+            rebuildEngine()
             return
         }
 
@@ -381,7 +376,7 @@ class SharedAudioEngine {
                 }
             } catch {
                 Logger.debug("[\(SharedAudioEngine.TAG)] engine.start() threw on attempt \(attempt + 1): \(error)")
-                self._attemptRestart(engine: engine, retryDelays: retryDelays, attempt: attempt + 1)
+                self.attemptRestart(engine: engine, retryDelays: retryDelays, attempt: attempt + 1)
                 return
             }
 
@@ -400,14 +395,14 @@ class SharedAudioEngine {
                 // Failed immediately — no point waiting, retry now
                 Logger.debug("[\(SharedAudioEngine.TAG)] Restart attempt \(attempt + 1) failed immediately")
                 if engine.isRunning { engine.stop() }
-                self._attemptRestart(engine: engine, retryDelays: retryDelays, attempt: attempt + 1)
+                self.attemptRestart(engine: engine, retryDelays: retryDelays, attempt: attempt + 1)
                 return
             }
 
             // Voice processing can cause the engine to die asynchronously after
-            // appearing to start. Wait then re-verify before declaring success.
+            // appearing to start. Wait 100ms then re-verify before declaring success.
             let verifyDelay: TimeInterval = (self.playbackMode == .conversation || self.playbackMode == .voiceProcessing) ? 0.1 : 0.05
-            self.queue.asyncAfter(deadline: .now() + verifyDelay) { [weak self] in
+            DispatchQueue.main.asyncAfter(deadline: .now() + verifyDelay) { [weak self] in
                 guard let self = self, let engine = self.engine else {
                     self?.isRebuildingForRouteChange = false
                     return
@@ -436,9 +431,9 @@ class SharedAudioEngine {
                     if isVP {
                         Logger.debug("[\(SharedAudioEngine.TAG)] VP mode — skipping remaining in-place retries, going to full rebuild")
                         self.isRebuildingForRouteChange = false
-                        self._rebuildEngine()
+                        self.rebuildEngine()
                     } else {
-                        self._attemptRestart(engine: engine, retryDelays: retryDelays, attempt: attempt + 1)
+                        self.attemptRestart(engine: engine, retryDelays: retryDelays, attempt: attempt + 1)
                     }
                 }
             }
@@ -446,7 +441,7 @@ class SharedAudioEngine {
 
         if delay > 0 {
             Logger.debug("[\(SharedAudioEngine.TAG)] Waiting \(Int(delay * 1000))ms before attempt \(attempt + 1)")
-            queue.asyncAfter(deadline: .now() + delay, execute: work)
+            DispatchQueue.main.asyncAfter(deadline: .now() + delay, execute: work)
         } else {
             work()
         }
@@ -459,17 +454,15 @@ class SharedAudioEngine {
     ///
     /// If this also fails, declare the engine dead, tear down all state, and
     /// notify delegates so they can report the failure to JS.
-    ///
-    /// Must be called on `queue`.
-    private func _rebuildEngine() {
+    private func rebuildEngine() {
         Logger.debug("[\(SharedAudioEngine.TAG)] rebuildEngine — creating fresh engine (old nodes will NOT be reused)")
         let savedMode = playbackMode
 
         // Full teardown (clears attachedNodes, stops engine, nils it)
-        _teardown()
+        teardown()
 
         do {
-            try _configure(playbackMode: savedMode)
+            try configure(playbackMode: savedMode)
             // Do NOT re-attach old nodes. The VP IO swap can leave old
             // AVAudioPlayerNode instances in a broken state. Delegates must
             // create fresh nodes in their engineDidRebuild() callback.
@@ -478,7 +471,7 @@ class SharedAudioEngine {
         } catch {
             Logger.debug("[\(SharedAudioEngine.TAG)] rebuildEngine FAILED — engine is dead: \(error)")
             // Ensure everything is torn down so a future connect() starts clean
-            _teardown()
+            teardown()
             let reason = "Route change recovery failed after all retries: \(error.localizedDescription)"
             notifyDelegates { $0.engineDidDie(reason: reason) }
         }
@@ -493,12 +486,9 @@ class SharedAudioEngine {
               let typeValue = info[AVAudioSessionInterruptionTypeKey] as? UInt,
               let type = AVAudioSession.InterruptionType(rawValue: typeValue) else { return }
 
-        queue.async { [weak self] in
-            self?._handleInterruption(type: type)
-        }
-    }
+        lock.lock()
+        defer { lock.unlock() }
 
-    private func _handleInterruption(type: AVAudioSession.InterruptionType) {
         if type == .began {
             Logger.debug("[\(SharedAudioEngine.TAG)] Audio session interruption began")
             notifyDelegates { $0.audioSessionInterruptionBegan() }
@@ -521,6 +511,6 @@ class SharedAudioEngine {
     }
 
     deinit {
-        _teardown()
+        teardown()
     }
 }

package/package.json

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

package/src/pipeline/types.ts

@@ -6,6 +6,18 @@ import { PlaybackMode, FrequencyBandConfig, FrequencyBands } from "../types";
 
 // ── Connect ─────────────────────────────────────────────────────────────────
 
+/**
+ * How the pipeline's playback should coexist with other audio on the device.
+ *
+ * - `'mixWithOthers'` (default): plays alongside other apps without
+ *   interrupting them. On Android no audio focus is requested. Best for
+ *   sound effects and short clips.
+ * - `'duckOthers'`: requests audio focus with ducking. Other apps lower
+ *   their volume but keep playing.
+ * - `'doNotMix'`: requests exclusive audio focus. Other apps pause.
+ */
+export type PipelineAudioMode = 'mixWithOthers' | 'duckOthers' | 'doNotMix';
+
 /** Options passed to `connectPipeline()`. */
 export interface ConnectPipelineOptions {
   /** Sample rate in Hz (default 24000). */
@@ -25,6 +37,15 @@ export interface ConnectPipelineOptions {
   frequencyBandIntervalMs?: number;
   /** Optional frequency band crossover configuration. */
   frequencyBandConfig?: FrequencyBandConfig;
+  /**
+   * How pipeline playback should coexist with other apps' audio.
+   * Default is `'mixWithOthers'` (matches expo-audio).
+   *
+   * Note: this is a **behavior change** vs. prior versions of this library,
+   * which effectively used `'doNotMix'`. Pass `'doNotMix'` explicitly to
+   * preserve that old behavior.
+   */
+  audioMode?: PipelineAudioMode;
 }
 
 /** Result returned from a successful `connectPipeline()` call. */