@siteed/expo-audio-studio 2.6.3 → 2.7.0

package/CHANGELOG.md

@@ -8,6 +8,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 
+## [2.7.0] - 2025-05-04
+### Changed
+- fix: Enhance iOS Background Audio Recording and Audio Format Conversion (#228) ([c17169b](https://github.com/deeeed/expo-audio-stream/commit/c17169bf9275706abf287712acc30df2f1814ed7))
+- chore(expo-audio-studio): improve build script for cjs esm conversion ([767dfbe](https://github.com/deeeed/expo-audio-stream/commit/767dfbe5da0f1550b689f6859e2e5fccf7f8141c))
 ## [2.6.3] - 2025-05-03
 ### Changed
 - chore: update readme with store download information (#224) ([c404d86](https://github.com/deeeed/expo-audio-stream/commit/c404d860cdb1c4c4bbc3767214f56bf547acec33))
@@ -213,7 +217,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Feature: Audio features extraction during recording.
 - Feature: Consistent WAV PCM recording format across all platforms.
 
-[unreleased]: https://github.com/deeeed/expo-audio-stream/compare/@siteed/expo-audio-studio@2.6.3...HEAD
+[unreleased]: https://github.com/deeeed/expo-audio-stream/compare/@siteed/expo-audio-studio@2.7.0...HEAD
+[2.7.0]: https://github.com/deeeed/expo-audio-stream/compare/@siteed/expo-audio-studio@2.6.3...@siteed/expo-audio-studio@2.7.0
 [2.6.3]: https://github.com/deeeed/expo-audio-stream/compare/@siteed/expo-audio-studio@2.6.2...@siteed/expo-audio-studio@2.6.3
 [2.6.2]: https://github.com/deeeed/expo-audio-stream/compare/@siteed/expo-audio-studio@2.6.1...@siteed/expo-audio-studio@2.6.2
 [2.6.1]: https://github.com/deeeed/expo-audio-stream/compare/@siteed/expo-audio-studio@2.6.0...@siteed/expo-audio-studio@2.6.1

package/app.plugin.cjs

@@ -0,0 +1,2 @@
+// Simply export the plugin - this is a CommonJS file (.cjs)
+module.exports = require('./plugin/build/index.cjs')

package/ios/AudioProcessor.swift

@@ -801,7 +801,16 @@ public class AudioProcessor {
                         try audioFile.read(into: buffer, frameCount: frameCount)
                         let converter = AVAudioConverter(from: inputFormat, to: targetFormat)!
                         let convertedBuffer = AVAudioPCMBuffer(pcmFormat: targetFormat, frameCapacity: frameCount)!
-                        try converter.convert(to: convertedBuffer, from: buffer)
+                        var error: NSError?
+                        _ = converter.convert(to: convertedBuffer, error: &error) { inNumPackets, outStatus in
+                            outStatus.pointee = .haveData
+                            return buffer
+                        }
+                        if let error = error {
+                            Logger.debug("AudioProcessor", "Format conversion failed: \(error.localizedDescription)")
+                            reject("CONVERSION_ERROR", "Failed to convert audio format: \(error.localizedDescription)")
+                            return nil
+                        }
                         try outputFile.write(from: convertedBuffer)
                         cumulativeFrames += Int64(frameCount)
                         let progress = Float(cumulativeFrames) / Float(totalFrames) * 100
@@ -933,7 +942,7 @@ public class AudioProcessor {
                                 let convertedBuffer = AVAudioPCMBuffer(pcmFormat: targetFormat, frameCapacity: framesToRead)!
                                 
                                 var error: NSError?
-                                let conversionStatus = converter.convert(to: convertedBuffer, error: &error) { inNumPackets, outStatus in
+                                _ = converter.convert(to: convertedBuffer, error: &error) { inNumPackets, outStatus in
                                     outStatus.pointee = .haveData
                                     return buffer
                                 }

package/ios/AudioStreamManager.swift

@@ -363,9 +363,15 @@ class AudioStreamManager: NSObject, AudioDeviceManagerDelegate {
     
     @objc private func handleAppDidEnterBackground(_ notification: Notification) {
         if isRecording {
-            // If keepAwake is false, we should track this as a pause
+            // If keepAwake is false, we should track this as a pause and actually pause the engine
             if let settings = recordingSettings, !settings.keepAwake {
+                Logger.debug("AudioStreamManager", "App entering background with keepAwake=false, pausing recording")
                 currentPauseStart = Date()
+                // Explicitly pause the engine but don't change isPaused state
+                // so we can automatically resume when returning to foreground
+                audioEngine.pause()
+            } else {
+                Logger.debug("AudioStreamManager", "App entering background with keepAwake=true, continuing recording")
             }
             
             DispatchQueue.main.asyncAfter(deadline: .now() + 0.5) { [weak self] in
@@ -382,6 +388,23 @@ class AudioStreamManager: NSObject, AudioDeviceManagerDelegate {
                 totalPausedDuration += pauseDuration
                 currentPauseStart = nil
                 Logger.debug("AudioStreamManager", "Added background pause duration: \(pauseDuration), total paused: \(totalPausedDuration)")
+                
+                // Now restart the engine if it was paused due to background
+                do {
+                    // Reinstall tap with hardware format to ensure we have good input
+                    _ = installTapWithHardwareFormat()
+                    // Restart the engine
+                    try audioEngine.start()
+                    Logger.debug("AudioStreamManager", "Successfully restarted audio engine after returning from background")
+                } catch {
+                    Logger.debug("AudioStreamManager", "Failed to restart audio engine after returning from background: \(error)")
+                    // If we can't restart, officially pause the recording
+                    if !isPaused {
+                        isPaused = true
+                        // Notify delegate
+                        delegate?.audioStreamManager(self, didPauseRecording: Date())
+                    }
+                }
             }
             
             notificationManager?.stopUpdates()
@@ -768,9 +791,21 @@ class AudioStreamManager: NSObject, AudioDeviceManagerDelegate {
             // Append necessary options for background recording if keepAwake is enabled
             if settings.keepAwake {
                 Logger.debug("AudioStreamManager", "keepAwake enabled - configuring for background recording")
-                // Add background audio option
+                // Set the category to PlayAndRecord with proper background options
                 options.insert(.mixWithOthers)
-                try session.setActive(true, options: .notifyOthersOnDeactivation)
+                // Add duckOthers to reduce volume of other apps instead of stopping them
+                options.insert(.duckOthers)
+                
+                // Configure audio session for background audio
+                do {
+                    try session.setCategory(.playAndRecord, mode: .default, options: options)
+                    try session.setActive(true, options: .notifyOthersOnDeactivation)
+                    // Ensure the app has appropriate Info.plist settings for background audio
+                    Logger.debug("AudioStreamManager", "Audio session configured for background recording with options: \(options)")
+                } catch {
+                    Logger.debug("AudioStreamManager", "Failed to configure audio session for background: \(error)")
+                    try session.setActive(true, options: .notifyOthersOnDeactivation)
+                }
             } else {
                 Logger.debug("AudioStreamManager", "keepAwake disabled - using standard session configuration")
                 // If keepAwake is false, don't add background audio options

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@siteed/expo-audio-studio",
-  "version": "2.6.3",
+  "version": "2.7.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",
@@ -44,7 +44,7 @@
     "ios",
     "cpp",
     "plugin",
-    "app.plugin.js",
+    "app.plugin.cjs",
     "LICENSE",
     "CHANGELOG.md",
     "generated",
@@ -66,7 +66,7 @@
   ],
   "scripts": {
     "build": "tsc",
-    "build:plugin": "tsc --build plugin/tsconfig.json",
+    "build:plugin": "tsc --build plugin/tsconfig.json && node scripts/convert-to-cjs.js",
     "build:plugin:dev": "expo-module build plugin",
     "build:dev": "expo-module build",
     "clean": "expo-module clean && rimraf plugin/build",
@@ -74,7 +74,7 @@
     "test": "expo-module test",
     "typecheck": "tsc --noEmit",
     "docgen": "typedoc src/index.ts --plugin typedoc-plugin-markdown --readme none --out ../../documentation_site/docs/api-reference/API",
-    "prepare": "yarn build && yarn build:plugin",
+    "prepare": "yarn build && yarn build:plugin && node -e \"require('fs').renameSync('./plugin/build/index.d.ts', './plugin/build/index.d.cts')\"",
     "prepublishOnly": "expo-module prepublishOnly",
     "expo-module": "expo-module",
     "open:ios": "open -a \"Xcode\" ../../apps/playground/ios",
@@ -99,7 +99,7 @@
     "eslint-plugin-prettier": "^5.1.3",
     "eslint-plugin-promise": "^6.1.1",
     "eslint-plugin-react": "^7.34.1",
-    "expo": "^52.0.27",
+    "expo": "^53.0.6",
     "expo-module-scripts": "^4.0.2",
     "jest": "^29.7.0",
     "prettier": "^3.2.5",
@@ -121,6 +121,6 @@
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
-    "expo-modules-core": "~2.1.4"
+    "expo-modules-core": "~2.3.12"
   }
 }

package/plugin/build/index.cjs

@@ -0,0 +1,192 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const config_plugins_1 = require("@expo/config-plugins");
+const MICROPHONE_USAGE = 'Allow $(PRODUCT_NAME) to access your microphone';
+const NOTIFICATION_USAGE = 'Show recording notifications and controls';
+const LOG_PREFIX = '[@siteed/expo-audio-studio]';
+function debugLog(message, ...args) {
+    if (process.env.EXPO_DEBUG) {
+        console.log(`${LOG_PREFIX} ${message}`, ...args);
+    }
+}
+const withRecordingPermission = (config, props) => {
+    const options = {
+        enablePhoneStateHandling: true, // Default to true for backward compatibility
+        enableNotifications: true,
+        enableBackgroundAudio: true,
+        iosBackgroundModes: {
+            useVoIP: false,
+            useAudio: false,
+            useProcessing: false,
+            useLocation: false,
+            useExternalAccessory: false,
+        },
+        iosConfig: {
+            microphoneUsageDescription: MICROPHONE_USAGE,
+            notificationUsageDescription: NOTIFICATION_USAGE,
+        },
+        ...(props || {}),
+    };
+    const { enablePhoneStateHandling, enableNotifications, enableBackgroundAudio, } = options;
+    debugLog('📱 Configuring Recording Permissions Plugin...', options);
+    // iOS Configuration
+    config = (0, config_plugins_1.withInfoPlist)(config, (config) => {
+        // Always set the microphone usage description from options first
+        config.modResults['NSMicrophoneUsageDescription'] =
+            options.iosConfig?.microphoneUsageDescription ||
+                config.modResults['NSMicrophoneUsageDescription'] ||
+                MICROPHONE_USAGE;
+        if (enableNotifications) {
+            config.modResults['NSUserNotificationsUsageDescription'] =
+                options.iosConfig?.notificationUsageDescription ||
+                    config.modResults['NSUserNotificationsUsageDescription'] ||
+                    NOTIFICATION_USAGE;
+            config.modResults['NSUserNotificationAlertStyle'] = 'alert';
+        }
+        const existingBackgroundModes = config.modResults.UIBackgroundModes || [];
+        // If background audio is enabled with useAudio, add the audio background mode
+        if (options.iosBackgroundModes?.useAudio === true &&
+            enableBackgroundAudio === true &&
+            !existingBackgroundModes.includes('audio')) {
+            // Add 'audio' background mode - REQUIRED for background recording
+            existingBackgroundModes.push('audio');
+            debugLog('✅ Added audio background mode for iOS background recording');
+            // Also ensure processing mode is recommended
+            if (options.iosBackgroundModes?.useProcessing !== true) {
+                console.warn(`${LOG_PREFIX} Warning: Background audio recording works best with both 'audio' and 'processing' background modes. Consider enabling 'useProcessing' in iosBackgroundModes.`);
+            }
+        }
+        if (options.iosBackgroundModes?.useVoIP === true &&
+            enablePhoneStateHandling === true) {
+            if (!existingBackgroundModes.includes('voip')) {
+                existingBackgroundModes.push('voip');
+            }
+            const existingCapabilities = (config.modResults
+                .UIRequiredDeviceCapabilities || []);
+            if (!existingCapabilities.includes('telephony')) {
+                existingCapabilities.push('telephony');
+            }
+            config.modResults.UIRequiredDeviceCapabilities =
+                existingCapabilities;
+        }
+        // Add additional background modes only if explicitly set to true
+        if (options.iosBackgroundModes?.useProcessing === true) {
+            if (!existingBackgroundModes.includes('processing')) {
+                existingBackgroundModes.push('processing');
+            }
+            // Add processing info if enabled
+            // Note: We keep the 'audiostream' namespace for native modules to maintain compatibility
+            config.modResults.BGTaskSchedulerPermittedIdentifiers = [
+                'com.siteed.audiostream.processing',
+            ];
+        }
+        if (options.iosBackgroundModes?.useLocation === true) {
+            if (!existingBackgroundModes.includes('location')) {
+                existingBackgroundModes.push('location');
+            }
+        }
+        if (options.iosBackgroundModes?.useExternalAccessory === true) {
+            if (!existingBackgroundModes.includes('external-accessory')) {
+                existingBackgroundModes.push('external-accessory');
+            }
+        }
+        // Configure background processing info if enabled
+        if (options.iosConfig?.backgroundProcessingTitle) {
+            config.modResults.BGProcessingTaskTitle =
+                options.iosConfig.backgroundProcessingTitle;
+        }
+        // Configure audio session behavior
+        if (options.iosConfig?.allowBackgroundAudioControls) {
+            config.modResults.UIBackgroundModes = [
+                ...existingBackgroundModes,
+                'remote-notification',
+            ];
+            config.modResults.MPNowPlayingInfoPropertyPlaybackRate = true;
+        }
+        config.modResults.UIBackgroundModes = existingBackgroundModes;
+        return config;
+    });
+    // Android Configuration
+    config = (0, config_plugins_1.withAndroidManifest)(config, (config) => {
+        const basePermissions = [
+            'android.permission.RECORD_AUDIO',
+            'android.permission.WAKE_LOCK',
+        ];
+        const optionalPermissions = [
+            enableNotifications && 'android.permission.POST_NOTIFICATIONS',
+            enablePhoneStateHandling && 'android.permission.READ_PHONE_STATE', // Only add if enabled
+            enableBackgroundAudio && 'android.permission.FOREGROUND_SERVICE',
+            enableBackgroundAudio && 'android.permission.FOREGROUND_SERVICE_MICROPHONE',
+        ].filter(Boolean);
+        const permissionsToAdd = [...basePermissions, ...optionalPermissions];
+        debugLog('📋 Existing Android permissions:', config.modResults.manifest['uses-permission']?.map((p) => p.$?.['android:name']) || []);
+        debugLog('➕ Adding Android permissions:', permissionsToAdd);
+        const { addPermission } = config_plugins_1.AndroidConfig.Permissions;
+        // Add each permission only if it doesn't exist
+        permissionsToAdd.forEach((permission) => {
+            const existingPermission = config.modResults.manifest['uses-permission']?.find((p) => p.$?.['android:name'] === permission);
+            if (!existingPermission) {
+                addPermission(config.modResults, permission);
+            }
+        });
+        // Get the main application node
+        const mainApplication = config.modResults.manifest.application?.[0];
+        if (mainApplication) {
+            debugLog('📱 Configuring Android application components...');
+            // Add RecordingActionReceiver
+            if (!mainApplication.receiver) {
+                mainApplication.receiver = [];
+            }
+            const receiverConfig = {
+                $: {
+                    'android:name': '.RecordingActionReceiver',
+                    'android:exported': 'false',
+                },
+                'intent-filter': [
+                    {
+                        action: [
+                            { $: { 'android:name': 'PAUSE_RECORDING' } },
+                            { $: { 'android:name': 'RESUME_RECORDING' } },
+                            { $: { 'android:name': 'STOP_RECORDING' } },
+                        ],
+                    },
+                ],
+            };
+            const receiverIndex = mainApplication.receiver.findIndex((receiver) => receiver.$?.['android:name'] === '.RecordingActionReceiver');
+            if (receiverIndex >= 0) {
+                mainApplication.receiver[receiverIndex] = receiverConfig;
+            }
+            else {
+                mainApplication.receiver.push(receiverConfig);
+            }
+            debugLog('✅ RecordingActionReceiver configured');
+            // Add AudioRecordingService
+            if (!mainApplication.service) {
+                mainApplication.service = [];
+            }
+            const serviceConfig = {
+                $: {
+                    'android:name': '.AudioRecordingService',
+                    'android:enabled': 'true',
+                    'android:exported': 'false',
+                    'android:foregroundServiceType': 'microphone',
+                },
+            };
+            const serviceIndex = mainApplication.service.findIndex((service) => service.$?.['android:name'] === '.AudioRecordingService');
+            if (serviceIndex >= 0) {
+                mainApplication.service[serviceIndex] = serviceConfig;
+            }
+            else {
+                mainApplication.service.push(serviceConfig);
+            }
+            debugLog('✅ AudioRecordingService configured');
+        }
+        else {
+            console.error(`${LOG_PREFIX} ❌ Main application node not found in Android Manifest`);
+        }
+        return config;
+    });
+    debugLog('✨ Recording Permissions Plugin configuration completed');
+    return config;
+};
+exports.default = withRecordingPermission;

package/plugin/build/index.js

@@ -44,15 +44,16 @@ const withRecordingPermission = (config, props) => {
             config.modResults['NSUserNotificationAlertStyle'] = 'alert';
         }
         const existingBackgroundModes = config.modResults.UIBackgroundModes || [];
-        // Only add background modes if explicitly enabled and set to true
+        // If background audio is enabled with useAudio, add the audio background mode
         if (options.iosBackgroundModes?.useAudio === true &&
             enableBackgroundAudio === true &&
             !existingBackgroundModes.includes('audio')) {
-            // Don't automatically add 'audio' background mode as it's only for playback
-            // existingBackgroundModes.push('audio')
-            // Instead, ensure processing mode is used for background recording
+            // Add 'audio' background mode - REQUIRED for background recording
+            existingBackgroundModes.push('audio');
+            debugLog('✅ Added audio background mode for iOS background recording');
+            // Also ensure processing mode is recommended
             if (options.iosBackgroundModes?.useProcessing !== true) {
-                console.warn(`${LOG_PREFIX} Warning: Background audio recording requires 'processing' background mode. Please enable 'useProcessing' in iosBackgroundModes.`);
+                console.warn(`${LOG_PREFIX} Warning: Background audio recording works best with both 'audio' and 'processing' background modes. Consider enabling 'useProcessing' in iosBackgroundModes.`);
             }
         }
         if (options.iosBackgroundModes?.useVoIP === true &&

package/plugin/src/index.ts

@@ -84,19 +84,22 @@ const withRecordingPermission: ConfigPlugin<AudioStreamPluginOptions> = (
         const existingBackgroundModes =
             config.modResults.UIBackgroundModes || []
 
-        // Only add background modes if explicitly enabled and set to true
+        // If background audio is enabled with useAudio, add the audio background mode
         if (
             options.iosBackgroundModes?.useAudio === true &&
             enableBackgroundAudio === true &&
             !existingBackgroundModes.includes('audio')
         ) {
-            // Don't automatically add 'audio' background mode as it's only for playback
-            // existingBackgroundModes.push('audio')
+            // Add 'audio' background mode - REQUIRED for background recording
+            existingBackgroundModes.push('audio')
+            debugLog(
+                '✅ Added audio background mode for iOS background recording'
+            )
 
-            // Instead, ensure processing mode is used for background recording
+            // Also ensure processing mode is recommended
             if (options.iosBackgroundModes?.useProcessing !== true) {
                 console.warn(
-                    `${LOG_PREFIX} Warning: Background audio recording requires 'processing' background mode. Please enable 'useProcessing' in iosBackgroundModes.`
+                    `${LOG_PREFIX} Warning: Background audio recording works best with both 'audio' and 'processing' background modes. Consider enabling 'useProcessing' in iosBackgroundModes.`
                 )
             }
         }

package/app.plugin.js

@@ -1 +0,0 @@
-module.exports = require('./plugin/build')