@edkimmel/expo-audio-stream 0.4.2 → 0.6.0

package/src/index.ts

@@ -30,6 +30,7 @@ import {
 
 import {
   addAudioEventListener,
+  addMicrophoneErrorListener,
   AudioEventPayload,
   AudioEvents,
   subscribeToEvent,
@@ -59,27 +60,20 @@ export class ExpoPlayAudioStream {
   }> {
     let subscription: Subscription | undefined;
     try {
-      const { onAudioStream, ...options } = recordingConfig;
+      const { onAudioStream, onError, ...options } = recordingConfig;
 
-      if (onAudioStream && typeof onAudioStream == "function") {
-        subscription = addAudioEventListener(
-          async (event: AudioEventPayload) => {
-            const {
-              fileUri,
-              deltaSize,
-              totalSize,
-              position,
-              encoded,
-              soundLevel,
-              frequencyBands,
-            } = event;
+      const subscriptions: EventSubscription[] = [];
+
+      if (onAudioStream && typeof onAudioStream === "function") {
+        subscriptions.push(
+          addAudioEventListener(async (event: AudioEventPayload) => {
+            const { fileUri, deltaSize, totalSize, position, encoded, soundLevel, frequencyBands, error } = event;
+            if (error) return; // handled by MicrophoneError subscription; ignore here
             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,
@@ -88,10 +82,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 };
@@ -240,6 +246,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";
@@ -259,6 +267,7 @@ export type {
   PipelineZombieDetectedEvent,
   PipelineUnderrunEvent,
   PipelineDrainedEvent,
+  PipelinePlaybackStoppedEvent,
   PipelineAudioFocusLostEvent,
   PipelineAudioFocusResumedEvent,
 } from "./pipeline";

package/src/pipeline/index.ts

@@ -103,6 +103,22 @@ export class Pipeline {
     return ExpoPlayAudioStreamModule.getPipelineTelemetry() as PipelineTelemetry;
   }
 
+  /**
+   * Query the platform's current output latency — i.e., how long after a
+   * sample is written to the native buffer before it actually leaves the
+   * speaker.
+   *
+   * Value can change mid-session, notably on audio route changes such as
+   * switching from built-in speaker to Bluetooth (Bluetooth typically adds
+   * 100+ ms). **Always query at the moment you care; do not cache.**
+   *
+   * Returns 0 if the pipeline is not connected or the platform cannot
+   * report a value.
+   */
+  static getOutputLatencyMs(): number {
+    return ExpoPlayAudioStreamModule.getPipelineOutputLatencyMs() as number;
+  }
+
   // ════════════════════════════════════════════════════════════════════════
   // Event subscriptions
   // ════════════════════════════════════════════════════════════════════════
@@ -211,6 +227,7 @@ export type {
   PipelineZombieDetectedEvent,
   PipelineUnderrunEvent,
   PipelineDrainedEvent,
+  PipelinePlaybackStoppedEvent,
   PipelineAudioFocusLostEvent,
   PipelineAudioFocusResumedEvent,
 } from './types';

package/src/pipeline/types.ts

@@ -135,6 +135,20 @@ export interface PipelineDrainedEvent {
   turnId: string;
 }
 
+/**
+ * Payload for `PipelinePlaybackStopped`.
+ *
+ * Fired when the last sample physically leaves the speaker, approximately
+ * `outputLatencyMs` after `PipelineDrained` for the same turn. Pairs with
+ * `PipelinePlaybackStarted` (start-of-emission ↔ end-of-emission).
+ *
+ * Note: this is a physical-world milestone, distinct from `state: 'idle'`
+ * (the pipeline-state-machine value reported via `PipelineStateChanged`).
+ */
+export interface PipelinePlaybackStoppedEvent {
+  turnId: string;
+}
+
 /** Payload for `PipelineAudioFocusLost` (empty — presence is the signal). */
 export type PipelineAudioFocusLostEvent = Record<string, never>;
 
@@ -155,6 +169,7 @@ export interface PipelineEventMap {
   PipelineZombieDetected: PipelineZombieDetectedEvent;
   PipelineUnderrun: PipelineUnderrunEvent;
   PipelineDrained: PipelineDrainedEvent;
+  PipelinePlaybackStopped: PipelinePlaybackStoppedEvent;
   PipelineAudioFocusLost: PipelineAudioFocusLostEvent;
   PipelineAudioFocusResumed: PipelineAudioFocusResumedEvent;
   PipelineFrequencyBands: PipelineFrequencyBandsEvent;

package/src/types.ts

@@ -129,10 +129,32 @@ export interface RecordingConfig {
   enableProcessing?: boolean; // Boolean to enable/disable audio processing (default is false)
   pointsPerSecond?: number; // Number of data points to extract per second of audio (default is 1000)
   onAudioStream?: (event: AudioDataEvent) => Promise<void>; // Callback function to handle audio stream
+  /** Fired when the native layer reports a mid-recording error (e.g. system
+   * interruption like Siri or a phone call). The consumer should treat the
+   * recording session as terminated and clean up. */
+  onError?: (event: MicrophoneErrorEvent) => void;
   /** Optional frequency band crossover configuration. */
   frequencyBandConfig?: FrequencyBandConfig;
 }
 
+export interface MicrophoneErrorEvent {
+  code: string;
+  message: string;
+  /**
+   * True when the recording session has stopped and the caller must call
+   * stopMicrophone() and reconnect to resume. False for transient conditions
+   * where recording continues (READ_ERROR on iOS) or the library will
+   * auto-recover (INTERRUPTED + autoResuming: true).
+   */
+  isFatal: boolean;
+  /**
+   * True only when code is INTERRUPTED — the library is waiting for the
+   * system to return the audio session and will reinstall the tap
+   * automatically. Always false when isFatal is true.
+   */
+  autoResuming: boolean;
+}
+
 export interface Chunk {
   text: string;
   timestamp: [number, number | null];