@siteed/expo-audio-studio 2.4.1 → 2.6.0

package/ios/ExpoAudioStreamModule.swift

@@ -6,12 +6,24 @@ import AVFoundation
 private let audioDataEvent: String = "AudioData"
 private let audioAnalysisEvent: String = "AudioAnalysis"
 private let recordingInterruptedEvent: String = "onRecordingInterrupted"
+private let deviceChangedEvent: String = "deviceChangedEvent"
+private let trimProgressEvent: String = "TrimProgress"
+private let errorEvent: String = "error"
 private let DEFAULT_SEGMENT_DURATION_MS = 100
+private let audioDeviceTypeBuiltinMic = "builtin_mic"
+private let audioDeviceTypeBluetooth = "bluetooth"
+private let audioDeviceTypeUSB = "usb"
+private let audioDeviceTypeWiredHeadset = "wired_headset"
+private let audioDeviceTypeWiredHeadphones = "wired_headphones"
+private let audioDeviceTypeSpeaker = "speaker"
+private let audioDeviceTypeUnknown = "unknown"
 
 public class ExpoAudioStreamModule: Module, AudioStreamManagerDelegate {
     private var streamManager = AudioStreamManager()
     private let notificationCenter = UNUserNotificationCenter.current()
     private let notificationIdentifier = "audio_recording_notification"
+    private var deviceManager = AudioDeviceManager()
+    private var deviceChangeObserver: Any?
         
     public func definition() -> ModuleDefinition {
         Name("ExpoAudioStream")
@@ -20,14 +32,22 @@ public class ExpoAudioStreamModule: Module, AudioStreamManagerDelegate {
         Events([
             audioDataEvent,
             audioAnalysisEvent,
-            recordingInterruptedEvent
+            recordingInterruptedEvent,
+            deviceChangedEvent,
+            trimProgressEvent,
+            errorEvent
         ])
         
         OnCreate {
-            print("Setting streamManager delegate")
+            Logger.debug("[ExpoAudioStreamModule] Module created, setting delegate and starting device monitoring.")
             streamManager.delegate = self
         }
         
+        OnDestroy {
+            Logger.debug("[ExpoAudioStreamModule] Module destroyed, stopping device monitoring.")
+            _ = streamManager.stopRecording()
+        }
+        
         /// Extracts audio analysis data from an audio file.
         ///
         /// - Parameters:
@@ -38,8 +58,10 @@ public class ExpoAudioStreamModule: Module, AudioStreamManagerDelegate {
         ///   - promise: A promise to resolve with the extracted audio analysis data or reject with an error.
         /// - Returns: Promise to be resolved with audio analysis data.
         AsyncFunction("extractAudioAnalysis") { (options: [String: Any], promise: Promise) in
+            Logger.debug("[ExpoAudioStreamModule] extractAudioAnalysis called with options: \(options)")
             guard let fileUri = options["fileUri"] as? String,
                   let url = URL(string: fileUri) else {
+                Logger.error("[ExpoAudioStreamModule] extractAudioAnalysis: Invalid file URI.")
                 promise.reject("INVALID_ARGUMENTS", "Invalid file URI provided")
                 return
             }
@@ -84,10 +106,11 @@ public class ExpoAudioStreamModule: Module, AudioStreamManagerDelegate {
                         effectiveLength = byteLength
                     }
                     
+                    Logger.debug("[ExpoAudioStreamModule] extractAudioAnalysis: Processing started for \(fileUri)")
                     let audioProcessor = try AudioProcessor(url: url, resolve: { result in
-                        promise.resolve(result)
+                        Logger.warn("[ExpoAudioStreamModule] extractAudioAnalysis: AudioProcessor resolve called unexpectedly.")
                     }, reject: { code, message in
-                        promise.reject(code, message)
+                        Logger.warn("[ExpoAudioStreamModule] extractAudioAnalysis: AudioProcessor reject called unexpectedly: \(code) - \(message)")
                     })
                     
                     if let result = audioProcessor.processAudioData(
@@ -101,11 +124,14 @@ public class ExpoAudioStreamModule: Module, AudioStreamManagerDelegate {
                         position: effectivePosition,
                         byteLength: effectiveLength
                     ) {
+                        Logger.debug("[ExpoAudioStreamModule] extractAudioAnalysis: Processing successful for \(fileUri)")
                         promise.resolve(result.toDictionary())
                     } else {
+                        Logger.error("[ExpoAudioStreamModule] extractAudioAnalysis: audioProcessor.processAudioData returned nil for \(fileUri)")
                         promise.reject("PROCESSING_ERROR", "Failed to process audio data")
                     }
                 } catch {
+                    Logger.error("[ExpoAudioStreamModule] extractAudioAnalysis: Error initializing AudioProcessor for \(fileUri): \(error.localizedDescription)")
                     promise.reject("PROCESSING_ERROR", "Failed to initialize audio processor: \(error.localizedDescription)")
                 }
             })
@@ -132,8 +158,10 @@ public class ExpoAudioStreamModule: Module, AudioStreamManagerDelegate {
         ///       - `bitrate`: The compression bitrate in bps (default is 128000).
         ///   - promise: A promise to resolve with the recording settings or reject with an error.
         AsyncFunction("startRecording") { (options: [String: Any], promise: Promise) in
+            Logger.debug("[ExpoAudioStreamModule] startRecording called with options: \(options)")
             self.checkMicrophonePermission { granted in
                 guard granted else {
+                    Logger.warn("[ExpoAudioStreamModule] startRecording: Permission denied.")
                     promise.reject("PERMISSION_DENIED", "Recording permission has not been granted")
                     return
                 }
@@ -143,6 +171,7 @@ public class ExpoAudioStreamModule: Module, AudioStreamManagerDelegate {
                 
                 switch settingsResult {
                 case .success(let settings):
+                    Logger.debug("[ExpoAudioStreamModule] startRecording: Settings parsed successfully. ShowNotification=\(settings.showNotification)")
                     // Initialize notification if enabled
                     if settings.showNotification {
                         Task {
@@ -153,6 +182,7 @@ public class ExpoAudioStreamModule: Module, AudioStreamManagerDelegate {
                         }
                     }
                     
+                    Logger.debug("[ExpoAudioStreamModule] startRecording: Calling streamManager.startRecording")
                     if let result = self.streamManager.startRecording(settings: settings) {
                         var resultDict: [String: Any] = [
                             "fileUri": result.fileUri,
@@ -172,12 +202,15 @@ public class ExpoAudioStreamModule: Module, AudioStreamManagerDelegate {
                             ]
                         }
                         
+                        Logger.info("[ExpoAudioStreamModule] startRecording: Recording started successfully. fileUri: \(result.fileUri)")
                         promise.resolve(resultDict)
                     } else {
+                        Logger.error("[ExpoAudioStreamModule] startRecording: streamManager.startRecording returned nil.")
                         promise.reject("ERROR", "Failed to start recording.")
                     }
                     
                 case .failure(let error):
+                    Logger.error("[ExpoAudioStreamModule] startRecording: Invalid settings - \(error.localizedDescription)")
                     promise.reject("INVALID_SETTINGS", error.localizedDescription)
                 }
             }
@@ -187,16 +220,54 @@ public class ExpoAudioStreamModule: Module, AudioStreamManagerDelegate {
         ///
         /// - Returns: The current status of the audio stream.Ï
         Function("status") {
-            return self.streamManager.getStatus()
+            let currentStatus = self.streamManager.getStatus()
+            Logger.debug("[ExpoAudioStreamModule] status requested: isRecording=\(currentStatus["isRecording"] ?? false), isPaused=\(currentStatus["isPaused"] ?? false)")
+            return currentStatus
+        }
+        
+        /// Prepares audio recording with the specified settings without starting it.
+        ///
+        /// - Parameters:
+        ///   - options: The recording settings to use.
+        ///   - promise: A promise to resolve with true if preparation was successful.
+        /// - Returns: A promise that resolves with a boolean indicating success.
+        AsyncFunction("prepareRecording") { (options: [String: Any], promise: Promise) in
+            Logger.debug("[ExpoAudioStreamModule] prepareRecording called with options: \(options)")
+            self.checkMicrophonePermission { granted in
+                guard granted else {
+                    promise.reject("PERMISSION_DENIED", "Recording permission has not been granted")
+                    return
+                }
+                
+                // Create settings with validation
+                let settingsResult = RecordingSettings.fromDictionary(options)
+                
+                switch settingsResult {
+                case .success(let settings):
+                    Logger.debug("[ExpoAudioStreamModule] prepareRecording: Settings parsed successfully. Calling streamManager.prepareRecording")
+                    if self.streamManager.prepareRecording(settings: settings) {
+                        Logger.info("[ExpoAudioStreamModule] prepareRecording: Preparation successful.")
+                        promise.resolve(true)
+                    } else {
+                        Logger.error("[ExpoAudioStreamModule] prepareRecording: streamManager.prepareRecording returned false.")
+                        promise.reject("ERROR", "Failed to prepare recording.")
+                    }
+                    
+                case .failure(let error):
+                    promise.reject("INVALID_SETTINGS", error.localizedDescription)
+                }
+            }
         }
         
         /// Pauses audio recording.
         Function("pauseRecording") {
+            Logger.debug("[ExpoAudioStreamModule] pauseRecording called.")
             self.streamManager.pauseRecording()
         }
         
         /// Resumes audio recording.
         Function("resumeRecording") {
+            Logger.debug("[ExpoAudioStreamModule] resumeRecording called.")
             self.streamManager.resumeRecording()
         }
         
@@ -205,6 +276,7 @@ public class ExpoAudioStreamModule: Module, AudioStreamManagerDelegate {
         /// - Parameters:
         ///   - promise: A promise to resolve with the recording result or reject with an error.
         AsyncFunction("stopRecording") { (promise: Promise) in
+            Logger.debug("[ExpoAudioStreamModule] stopRecording called.")
             if let recordingResult = self.streamManager.stopRecording() {
                 var resultDict: [String: Any] = [
                     "fileUri": recordingResult.fileUri,
@@ -229,8 +301,10 @@ public class ExpoAudioStreamModule: Module, AudioStreamManagerDelegate {
                     ]
                 }
                 
+                Logger.info("[ExpoAudioStreamModule] stopRecording: Recording stopped successfully. fileUri: \(recordingResult.fileUri), size: \(recordingResult.size)")
                 promise.resolve(resultDict)
             } else {
+                Logger.error("[ExpoAudioStreamModule] stopRecording: streamManager.stopRecording returned nil.")
                 promise.reject("ERROR", "Failed to stop recording or no recording in progress.")
             }
         }
@@ -241,12 +315,15 @@ public class ExpoAudioStreamModule: Module, AudioStreamManagerDelegate {
         ///   - promise: A promise to resolve with the list of audio file URIs or reject with an error.
         /// - Returns: A promise that resolves with the list of audio file URIs or rejects with an error.
         AsyncFunction("listAudioFiles") { (promise: Promise) in
+            Logger.debug("[ExpoAudioStreamModule] listAudioFiles called.")
             let files = listAudioFiles()
+            Logger.debug("[ExpoAudioStreamModule] listAudioFiles returning \(files.count) files.")
             promise.resolve(files)
         }
         
         /// Clears all audio files stored in the document directory.
         Function("clearAudioFiles") {
+            Logger.debug("[ExpoAudioStreamModule] clearAudioFiles called.")
             clearAudioFiles()
         }
         
@@ -335,7 +412,7 @@ public class ExpoAudioStreamModule: Module, AudioStreamManagerDelegate {
             let ranges = options["ranges"] as? [[String: Double]]
             let outputFileName = options["outputFileName"] as? String
             let outputFormat = options["outputFormat"] as? [String: Any]
-            let decodingOptions = options["decodingOptions"] as? [String: Any]
+            let decodingOptions = options["decodingOptions"] as? [String: Any] ?? [:]
 
             // Add detailed logging for filename and format options
             Logger.debug("Trim audio request:")
@@ -378,7 +455,7 @@ public class ExpoAudioStreamModule: Module, AudioStreamManagerDelegate {
                     )
 
                     let progressCallback: (Float, Int64, Int64) -> Void = { progress, bytesProcessed, totalBytes in
-                        self.sendEvent("TrimProgress", [
+                        self.sendEvent(trimProgressEvent, [
                             "progress": progress,
                             "bytesProcessed": bytesProcessed,
                             "totalBytes": totalBytes
@@ -476,6 +553,9 @@ public class ExpoAudioStreamModule: Module, AudioStreamManagerDelegate {
             let position = options["position"] as? Int
             let length = options["length"] as? Int
             let includeWavHeader = options["includeWavHeader"] as? Bool ?? false
+            let includeNormalizedData = options["includeNormalizedData"] as? Bool ?? false
+            let decodingOptions = options["decodingOptions"] as? [String: Any] ?? [:]
+            let includeBase64Data = options["includeBase64Data"] as? Bool ?? false
 
             // Validate that we have either time range or byte range, but not both and not neither
             let hasTimeRange = startTimeMs != nil && endTimeMs != nil
@@ -520,9 +600,6 @@ public class ExpoAudioStreamModule: Module, AudioStreamManagerDelegate {
 
                 let frameCount = AVAudioFrameCount(endFrame - startFrame)
                 
-                // Create decoding config that includes normalization preference
-                var decodingOptions = options["decodingOptions"] as? [String: Any] ?? [:]
-                let includeNormalizedData = options["includeNormalizedData"] as? Bool ?? false
                 
                 // Pass both options separately - normalizeAudio from decodingOptions, and includeNormalizedData as is
                 let decodingConfig = DecodingConfig.fromDictionary(decodingOptions)
@@ -534,7 +611,7 @@ public class ExpoAudioStreamModule: Module, AudioStreamManagerDelegate {
                     format: format,
                     decodingConfig: decodingConfig,
                     includeNormalizedData: includeNormalizedData,
-                    includeBase64Data: options["includeBase64Data"] as? Bool ?? false
+                    includeBase64Data: includeBase64Data
                 )
 
                 var resultDict: [String: Any] = [:]
@@ -602,9 +679,82 @@ public class ExpoAudioStreamModule: Module, AudioStreamManagerDelegate {
                 "Mel spectrogram extraction is currently only available on Android and is experimental"
             )
         }
+        
+        /// Gets available audio input devices with an optional refresh parameter
+        /// - Parameters:
+        ///   - options: Optional dictionary containing a refresh parameter
+        ///   - promise: A promise to resolve with a list of available audio input devices
+        AsyncFunction("getAvailableInputDevices") { (options: [String: Any]?, promise: Promise) in
+            Logger.debug("[ExpoAudioStreamModule] getAvailableInputDevices called. Refresh: \(options?["refresh"] ?? false)")
+            if let options = options, let refresh = options["refresh"] as? Bool, refresh {
+                Logger.debug("Forcing refresh of audio devices")
+                self.deviceManager.forceRefreshAudioSession()
+            }
+            
+            // Call the device manager with the promise
+            self.deviceManager.getAvailableInputDevices(promise: promise)
+        }
+        
+        /// Refreshes the audio session to detect newly connected devices
+        /// - Returns: Boolean indicating success
+        Function("refreshAudioDevices") {
+            Logger.debug("[ExpoAudioStreamModule] refreshAudioDevices called.")
+            let success = self.deviceManager.forceRefreshAudioSession()
+            Logger.debug("[ExpoAudioStreamModule] refreshAudioDevices result: \(success)")
+            return ["success": success]
+        }
+        
+        /// Gets the currently selected audio input device
+        ///
+        /// - Parameters:
+        ///   - promise: A promise to resolve with the currently selected audio input device
+        AsyncFunction("getCurrentInputDevice") { (promise: Promise) in
+            Logger.debug("[ExpoAudioStreamModule] getCurrentInputDevice called.")
+            self.deviceManager.getCurrentInputDevice(promise: promise)
+        }
+        
+        /// Selects a specific audio input device for recording
+        ///
+        /// - Parameters:
+        ///   - deviceId: The ID of the device to select
+        ///   - promise: A promise to resolve with boolean indicating success
+        AsyncFunction("selectInputDevice") { (deviceId: String, promise: Promise) in
+            Logger.debug("[ExpoAudioStreamModule] selectInputDevice called with ID: \(deviceId)")
+            self.deviceManager.selectInputDevice(deviceId, promise: promise)
+            // Update the audio recorder if recording is in progress or prepared
+            if self.streamManager.isRecording || self.streamManager.isPrepared {
+                Logger.debug("[ExpoAudioStreamModule] selectInputDevice: Calling updateAudioSessionWithCurrentSettings because recording/prepared.")
+                self.streamManager.updateAudioSessionWithCurrentSettings()
+            } else {
+                Logger.debug("[ExpoAudioStreamModule] selectInputDevice: Not calling updateAudioSessionWithCurrentSettings because not recording/prepared.")
+            }
+        }
+        
+        /// Resets to the default audio input device
+        ///
+        /// - Parameters:
+        ///   - promise: A promise to resolve with boolean indicating success
+        AsyncFunction("resetToDefaultDevice") { (promise: Promise) in
+            Logger.debug("[ExpoAudioStreamModule] resetToDefaultDevice called.")
+            self.deviceManager.resetToDefaultDevice { success, error in
+                if success {
+                    if self.streamManager.isRecording || self.streamManager.isPrepared {
+                        Logger.debug("[ExpoAudioStreamModule] resetToDefaultDevice: Calling updateAudioSessionWithCurrentSettings because recording/prepared.")
+                        self.streamManager.updateAudioSessionWithCurrentSettings()
+                    } else {
+                        Logger.debug("[ExpoAudioStreamModule] resetToDefaultDevice: Not calling updateAudioSessionWithCurrentSettings because not recording/prepared.")
+                    }
+                    promise.resolve(true)
+                } else {
+                    Logger.error("[ExpoAudioStreamModule] resetToDefaultDevice failed: \(error?.localizedDescription ?? "Unknown error")")
+                    promise.reject("DEVICE_ERROR", "Failed to reset to default device: \(error?.localizedDescription ?? "Unknown error")")
+                }
+            }
+        }
     }
     
     func audioStreamManager(_ manager: AudioStreamManager, didReceiveInterruption info: [String: Any]) {
+        Logger.debug("[ExpoAudioStreamModule] Delegate: didReceiveInterruption: \(info)")
         // Convert iOS interruption events to match the TypeScript types
         var reason: String
         var isPaused: Bool = true
@@ -641,6 +791,7 @@ public class ExpoAudioStreamModule: Module, AudioStreamManagerDelegate {
     }
     
     func audioStreamManager(_ manager: AudioStreamManager, didPauseRecording pauseTime: Date) {
+        Logger.debug("[ExpoAudioStreamModule] Delegate: didPauseRecording")
         sendEvent(recordingInterruptedEvent, [
             "reason": "userPaused",
             "isPaused": true,
@@ -649,6 +800,7 @@ public class ExpoAudioStreamModule: Module, AudioStreamManagerDelegate {
     }
     
     func audioStreamManager(_ manager: AudioStreamManager, didResumeRecording resumeTime: Date) {
+        Logger.debug("[ExpoAudioStreamModule] Delegate: didResumeRecording")
         sendEvent(recordingInterruptedEvent, [
             "reason": "userResumed",
             "isPaused": false,
@@ -657,6 +809,7 @@ public class ExpoAudioStreamModule: Module, AudioStreamManagerDelegate {
     }
     
     func audioStreamManager(_ manager: AudioStreamManager, didUpdateNotificationState isPaused: Bool) {
+        Logger.debug("[ExpoAudioStreamModule] Delegate: didUpdateNotificationState: isPaused=\(isPaused)")
         sendEvent(recordingInterruptedEvent, [
             "reason": "notification",
             "isPaused": isPaused,
@@ -678,6 +831,8 @@ public class ExpoAudioStreamModule: Module, AudioStreamManagerDelegate {
         totalDataSize: Int64,
         compressionInfo: [String: Any]?
     ) {
+        // Reduce log frequency or detail for this potentially high-frequency event
+        // Logger.debug("[ExpoAudioStreamModule] Delegate: didReceiveAudioData: size=\(data.count), totalSize=\(totalDataSize)")
         var resultDict: [String: Any] = [
             "fileUri": manager.recordingFileURL?.absoluteString ?? "",
             "lastEmittedSize": totalDataSize,
@@ -707,10 +862,12 @@ public class ExpoAudioStreamModule: Module, AudioStreamManagerDelegate {
     }
     
     func audioStreamManager(_ manager: AudioStreamManager, didReceiveProcessingResult result: AudioAnalysisData?) {
-        // Handle the processed audio data
-        // Emit the processing result event to JavaScript
-        let resultDict = result?.toDictionary() ?? [:]
-        Logger.debug("emitting \(audioAnalysisEvent) event with \(resultDict)")
+        if let data = result {
+            Logger.debug("[ExpoAudioStreamModule] Delegate: didReceiveProcessingResult: Received \(data.dataPoints.count) data points.")
+        } else {
+            Logger.debug("[ExpoAudioStreamModule] Delegate: didReceiveProcessingResult: Received nil result.")
+        }
+        let resultDict = result?.toDictionary() ?? [:] 
         sendEvent(audioAnalysisEvent, resultDict)
     }
     
@@ -799,9 +956,7 @@ public class ExpoAudioStreamModule: Module, AudioStreamManagerDelegate {
     }
     
     func audioStreamManager(_ manager: AudioStreamManager, didFailWithError error: String) {
-        // Send error event to JavaScript
-        sendEvent("error", [
-            "message": error
-        ])
+        Logger.error("[ExpoAudioStreamModule] Delegate: didFailWithError: \(error)")
+        sendEvent(errorEvent, [ "message": error ])
     }
 }

package/ios/Features.swift

@@ -70,7 +70,7 @@ public struct Features {
 
 extension Features {
     func toDictionary() -> [String: Any] {
-        var dict: [String: Any] = [
+        let dict: [String: Any] = [
             "energy": energy,
             "mfcc": mfcc,
             "rms": rms,

package/ios/ISSUE_IOS.md

@@ -0,0 +1,45 @@
+# iOS Recording Issue: No WAV Data/Analysis When Resampling (e.g., 16kHz) - RESOLVED
+
+## Problem Summary
+
+Initially, the iOS implementation failed to record WAV audio data or perform real-time analysis when the requested `sampleRate` (e.g., 16,000 Hz) differed from the hardware's native sample rate (e.g., 48,000 Hz), requiring resampling. Recording at the native hardware sample rate worked correctly.
+
+The primary symptom was that the tap installed on the `audioEngine.inputNode` using `installTap(onBus:bufferSize:format:)` was **not receiving any audio buffers** when resampling was required (i.e., requested rate != hardware rate). This resulted in:
+
+*   An empty WAV file (only the initial 44-byte header).
+*   No data being sent to the `AudioProcessor` for real-time analysis.
+*   No `AudioData` or `AudioAnalysis` events being emitted for the WAV stream.
+
+Parallel compressed recording (e.g., AAC) functioned correctly even when the WAV stream failed, indicating the audio engine *was* capturing audio but not delivering it to the tap.
+
+## Debugging History & Findings
+
+1.  **Initial State:** Empty WAV file at 16kHz, working AAC at 16kHz. Confirmed 48kHz WAV worked.
+2.  **Tap Installation Format:** Early attempts tried setting the tap format to the *requested* sample rate (16kHz), leading to `AVAudioIONodeImpl.mm:1334 Format mismatch` crashes because the tap format didn't match the actual hardware input format (often 48kHz).
+3.  **Using `inputNode.outputFormat`:** Switched to installing the tap using the format reported by `inputNode.outputFormat(forBus: 0)`, assuming this reflected the actual hardware format. Resampling was handled later in `processAudioBuffer`. This fixed the crash but **did not** fix the original issue – the tap still received no buffers at 16kHz.
+4.  **Race Condition:** Identified and fixed a race condition where `audioEngine.start()` was called before `isRecording` was set to `true`, causing the tap's initial guard check to fail. This allowed buffers to be processed *after* the flag was set, but the WAV file writing was still faulty (only the first buffer was written).
+5.  **Background File I/O Refactor:** Improved WAV file writing by keeping the `FileHandle` open during recording instead of opening/closing for each buffer in the background queue. This fixed the partial file writing issue but didn't solve the core "no buffers received at 16kHz" problem.
+6.  **Removing `setPreferredSampleRate`:** Tried removing the `session.setPreferredSampleRate` call, hoping the session would default to the hardware rate, allowing the 48kHz tap (based on `inputNode.outputFormat`) to receive buffers. This **worked** for the internal microphone but caused crashes with Bluetooth headsets, as the Bluetooth hardware *actually* operated at 16kHz, creating a new format mismatch.
+7.  **Using `session.sampleRate`:** Attempted to use `session.sampleRate` *after* session activation to determine the tap format. This also proved unreliable, sometimes reporting 16kHz for the session while `inputNode.outputFormat` still reported 48kHz, leading back to the format mismatch crash.
+
+## Root Cause
+
+The core issue stems from the unreliability and potential inconsistency between:
+
+*   `AVAudioSession.sampleRate` (especially after `setPreferredSampleRate` or device changes).
+*   `audioEngine.inputNode.outputFormat(forBus: 0)` (which might not immediately reflect the true hardware format).
+*   The actual sample rate the hardware is delivering to the audio engine.
+
+Attempting to force a specific sample rate via `setPreferredSampleRate` or relying solely on `session.sampleRate` post-activation can lead to situations where the format used to install the tap does not match the format the audio engine expects/receives from the hardware input, causing either a crash (`Format mismatch`) or the tap simply not receiving any buffers.
+
+## Final Solution
+
+The most robust solution was found to be:
+
+1.  **Configure Session:** Set up the `AVAudioSession` category, mode, and options as required. **Do not** call `setPreferredSampleRate`. Let the session negotiate the rate with the hardware.
+2.  **Activate Session:** Activate the audio session.
+3.  **Query Input Node Format (Just-In-Time):** Immediately **before** calling `installTap`, query the input node's expected format using `audioEngine.inputNode.outputFormat(forBus: 0)`. This appears to provide the most accurate format that the node *will accept* for the tap at that specific moment.
+4.  **Install Tap:** Install the tap using the exact `AVAudioFormat` obtained from `inputNode.outputFormat(forBus: 0)` in the previous step.
+5.  **Resample in Tap:** Inside the tap's processing closure (`processAudioBuffer`), check if the received `buffer.format.sampleRate` differs from the `settings.sampleRate` requested by the user. If they differ, perform the resampling explicitly using `AVAudioConverter` (or a similar method) before writing the WAV data or performing analysis.
+
+This approach ensures the tap format always matches what the input node requires at the time of installation, regardless of the device (internal mic, Bluetooth) or the requested output sample rate. Subsequent resampling handles the conversion to the user's desired format.

package/ios/Logger.swift

@@ -1,7 +1,19 @@
 class Logger {
     static func debug(_ message: @autoclosure () -> String) {
         #if DEBUG
-        print(message())
+        print("[DEBUG] \(message())")
         #endif
     }
+
+    static func info(_ message: @autoclosure () -> String) {
+        print("[INFO] \(message())")
+    }
+
+    static func warn(_ message: @autoclosure () -> String) {
+        print("[WARN] ⚠️ \(message())")
+    }
+
+    static func error(_ message: @autoclosure () -> String) {
+        print("[ERROR] 🛑 \(message())")
+    }
 }

package/ios/RecordingSettings.swift

@@ -109,6 +109,10 @@ struct RecordingSettings {
     // Update default to 100ms
     var segmentDurationMs: Int = 100  // Default 100ms segments
     
+    // Add these new properties
+    var deviceId: String?
+    var deviceDisconnectionBehavior: String?
+    
     static func fromDictionary(_ dict: [String: Any]) -> Result<RecordingSettings, Error> {
         // Extract compression settings
         let compression = dict["compression"] as? [String: Any]
@@ -127,6 +131,10 @@ struct RecordingSettings {
             }
         }
         
+        // Add extraction of new properties
+        let deviceId = dict["deviceId"] as? String
+        let deviceDisconnectionBehavior = dict["deviceDisconnectionBehavior"] as? String
+        
         // Create settings
         var settings = RecordingSettings(
             sampleRate: dict["sampleRate"] as? Double ?? 44100.0,
@@ -260,6 +268,10 @@ struct RecordingSettings {
         
         settings.filename = dict["filename"] as? String
         
+        // Set new properties
+        settings.deviceId = deviceId
+        settings.deviceDisconnectionBehavior = deviceDisconnectionBehavior
+        
         return .success(settings)
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@siteed/expo-audio-studio",
-  "version": "2.4.1",
+  "version": "2.6.0",
   "description": "Comprehensive audio processing library for React Native and Expo with recording, analysis, visualization, and streaming capabilities across iOS, Android, and web",
   "license": "MIT",
   "main": "build/index.js",
@@ -108,7 +108,7 @@
     "size-limit": "^11.1.4",
     "ts-node": "^10.9.2",
     "typedoc": "^0.27.4",
-    "typedoc-plugin-markdown": "^4.3.2",
+    "typedoc-plugin-markdown": "~4.4.2",
     "typescript": "~5.3.3"
   },
   "peerDependencies": {

package/src/AudioAnalysis/AudioAnalysis.types.ts

@@ -166,7 +166,7 @@ export interface PreviewOptions extends AudioRangeOptions {
 
 /**
  * Options for mel-spectrogram extraction
- * 
+ *
  * @experimental This feature is experimental and currently only available on Android.
  * The API may change in future versions.
  */
@@ -189,7 +189,7 @@ export interface ExtractMelSpectrogramOptions {
 
 /**
  * Return type for mel spectrogram extraction
- * 
+ *
  * @experimental This feature is experimental and currently only available on Android.
  * The API may change in future versions.
  */