@edkimmel/expo-audio-stream 0.4.1 → 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,10 +158,36 @@ 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 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"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edkimmel/expo-audio-stream",
-  "version": "0.4.1",
+  "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. */