@siteed/expo-audio-studio 2.4.1 → 2.5.0

package/src/ExpoAudioStream.types.ts

@@ -145,7 +145,7 @@ export interface StartRecordingResult {
 }
 
 export interface AudioSessionConfig {
-    /** 
+    /**
      * Audio session category that defines the audio behavior
      * - 'Ambient': Audio continues with silent switch, mixes with other audio
      * - 'SoloAmbient': Audio continues with silent switch, interrupts other audio
@@ -219,6 +219,14 @@ export type RecordingInterruptionReason =
     | 'phoneCallEnded'
     /** Recording was stopped by the system or another app */
     | 'recordingStopped'
+    /** Recording device was disconnected */
+    | 'deviceDisconnected'
+    /** Recording switched to default device after disconnection */
+    | 'deviceFallback'
+    /** A new audio device was connected */
+    | 'deviceConnected'
+    /** Device switching failed */
+    | 'deviceSwitchFailed'
 
 // Add new interface for interruption events
 export interface RecordingInterruptionEvent {
@@ -228,6 +236,48 @@ export interface RecordingInterruptionEvent {
     isPaused: boolean
 }
 
+export interface AudioDeviceCapabilities {
+    /** Supported sample rates for the device */
+    sampleRates: number[]
+    /** Supported channel counts for the device */
+    channelCounts: number[]
+    /** Supported bit depths for the device */
+    bitDepths: number[]
+    /** Whether the device supports echo cancellation */
+    hasEchoCancellation?: boolean
+    /** Whether the device supports noise suppression */
+    hasNoiseSuppression?: boolean
+    /** Whether the device supports automatic gain control */
+    hasAutomaticGainControl?: boolean
+}
+
+export interface AudioDevice {
+    /** Unique identifier for the device */
+    id: string
+    /** Human-readable name of the device */
+    name: string
+    /** Device type (builtin_mic, bluetooth, etc.) */
+    type: string
+    /** Whether this is the system default device */
+    isDefault: boolean
+    /** Audio capabilities for the device */
+    capabilities: AudioDeviceCapabilities
+    /** Whether the device is currently available */
+    isAvailable: boolean
+}
+
+/** Defines how recording should behave when a device becomes unavailable */
+export const DeviceDisconnectionBehavior = {
+    /** Pause recording when device disconnects */
+    PAUSE: 'pause',
+    /** Switch to default device and continue recording */
+    FALLBACK: 'fallback',
+} as const
+
+/** Type for DeviceDisconnectionBehavior values */
+export type DeviceDisconnectionBehaviorType =
+    (typeof DeviceDisconnectionBehavior)[keyof typeof DeviceDisconnectionBehavior]
+
 export interface RecordingConfig {
     /** Sample rate for recording in Hz (16000, 44100, or 48000) */
     sampleRate?: SampleRate
@@ -294,6 +344,12 @@ export interface RecordingConfig {
     outputDirectory?: string // If not provided, uses default app directory
     /** Optional filename for the recording (uses UUID if not provided) */
     filename?: string // If not provided, uses UUID
+
+    /** ID of the device to use for recording (if not specified, uses default) */
+    deviceId?: string
+
+    /** How to handle device disconnection during recording */
+    deviceDisconnectionBehavior?: DeviceDisconnectionBehaviorType
 }
 
 export interface NotificationConfig {
@@ -420,6 +476,46 @@ export interface ExtractedAudioData {
 }
 
 export interface UseAudioRecorderState {
+    /**
+     * Prepares recording with the specified configuration without starting it.
+     *
+     * This method eliminates the latency between calling startRecording and the actual recording beginning.
+     * It pre-initializes all audio resources, requests permissions, and sets up audio sessions in advance,
+     * allowing for true zero-latency recording start when startRecording is called later.
+     *
+     * Technical benefits:
+     * - Eliminates audio pipeline initialization delay (50-300ms depending on platform)
+     * - Pre-allocates audio buffers to avoid memory allocation during recording start
+     * - Initializes audio hardware in advance (particularly important on iOS)
+     * - Requests and verifies permissions before the critical recording moment
+     *
+     * Use this method when:
+     * - You need zero-latency recording start (e.g., voice commands, musical applications)
+     * - You're building time-sensitive applications where missing initial audio would be problematic
+     * - You want to prepare resources during app initialization, screen loading, or preceding user interaction
+     * - You need to ensure recording starts reliably and instantly on all platforms
+     *
+     * @param config - The recording configuration, identical to what you would pass to startRecording
+     * @returns A promise that resolves when preparation is complete
+     *
+     * @example
+     * // Prepare during component mounting
+     * useEffect(() => {
+     *   prepareRecording({
+     *     sampleRate: 44100,
+     *     channels: 1,
+     *     encoding: 'pcm_16bit',
+     *   });
+     * }, []);
+     *
+     * // Later when user taps record button, it starts with zero latency
+     * const handleRecordPress = () => startRecording({
+     *   sampleRate: 44100,
+     *   channels: 1,
+     *   encoding: 'pcm_16bit',
+     * });
+     */
+    prepareRecording: (_: RecordingConfig) => Promise<void>
     /** Starts recording with the specified configuration */
     startRecording: (_: RecordingConfig) => Promise<StartRecordingResult>
     /** Stops the current recording and returns the recording data */