@siteed/audio-studio 3.0.0

package/package.json

@@ -0,0 +1,146 @@
+{
+    "name": "@siteed/audio-studio",
+    "version": "3.0.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",
+    "type": "commonjs",
+    "main": "./build/cjs/index.js",
+    "module": "./build/esm/index.js",
+    "types": "./build/types/index.d.ts",
+    "expo": {
+        "plugin": "./app.plugin.js"
+    },
+    "author": "Arthur Breton <abreton@siteed.net> (https://github.com/deeeed)",
+    "homepage": "https://github.com/deeeed/audiolab/blob/main/packages/audio-studio/README.md",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/deeeed/audiolab.git",
+        "directory": "packages/audio-studio"
+    },
+    "bugs": {
+        "url": "https://github.com/deeeed/audiolab/issues"
+    },
+    "keywords": [
+        "react-native",
+        "expo",
+        "audio",
+        "recording",
+        "audio-analysis",
+        "audio-processing",
+        "audio-visualization",
+        "waveform",
+        "spectrogram",
+        "mel-spectrogram",
+        "mfcc",
+        "audio-features",
+        "audio-compression",
+        "opus",
+        "aac",
+        "pcm",
+        "wav",
+        "cross-platform",
+        "background-recording",
+        "audio-trimming",
+        "dual-stream"
+    ],
+    "files": [
+        "src",
+        "android",
+        "ios",
+        "cpp",
+        "plugin",
+        "app.plugin.js",
+        "LICENSE",
+        "CHANGELOG.md",
+        "generated",
+        "expo-module.config.json",
+        "README.md",
+        "package.json",
+        "*.podspec",
+        "prebuilt",
+        "build",
+        "!ios/build",
+        "!android/build",
+        "!android/gradle",
+        "!android/gradlew",
+        "!android/gradlew.bat",
+        "!android/local.properties",
+        "!**/__tests__",
+        "!**/__fixtures__",
+        "!**/__mocks__",
+        "!**/.*"
+    ],
+    "scripts": {
+        "build:wasm": "bash scripts/build-wasm.sh",
+        "build": "rimraf build && yarn build:types && yarn build:cjs && yarn build:esm && yarn build:plugin",
+        "build:cjs": "tsc -p tsconfig.cjs.json",
+        "build:esm": "tsc -p tsconfig.esm.json",
+        "build:types": "tsc -p tsconfig.types.json",
+        "build:plugin": "tsc --project plugin/tsconfig.json && cp plugin/build/index.js plugin/build/index.cjs",
+        "build:plugin:dev": "expo-module build plugin",
+        "build:dev": "expo-module build",
+        "clean": "expo-module clean && rimraf build plugin/build",
+        "lint": "expo-module lint",
+        "lint:fix": "expo-module lint --fix",
+        "test": "expo-module test",
+        "test:android": "yarn test:android:unit && yarn test:android:instrumented",
+        "test:android:unit": "cd ../../apps/playground/android && ./gradlew :siteed-expo-audio-studio:test",
+        "test:android:instrumented": "cd ../../apps/playground/android && ./gradlew :siteed-expo-audio-studio:connectedAndroidTest",
+        "test:android:unit:watch": "cd ../../apps/playground/android && ./gradlew :siteed-expo-audio-studio:test --continuous",
+        "test:ios": "cd ../../apps/playground/ios && xcodebuild -workspace AudioDevPlayground.xcworkspace -scheme AudioDevPlayground -destination 'platform=iOS Simulator,name=iPhone 15' build",
+        "test:coverage": "cd ../../apps/playground/android && ./gradlew :siteed-expo-audio-studio:jacocoTestReport",
+        "typecheck": "tsc --noEmit",
+        "docgen": "typedoc src/index.ts --plugin typedoc-plugin-markdown --readme none --out ../../documentation_site/docs/api-reference/API && node ../../scripts/escape-mdx-generics.js ../../documentation_site/docs/api-reference",
+        "prepare": "yarn build && node -e \"require('fs').renameSync('./plugin/build/index.d.ts', './plugin/build/index.d.cts')\"",
+        "prepublishOnly.disabled": "expo-module prepublishOnly",
+        "expo-module": "expo-module",
+        "open:ios": "open -a \"Xcode\" ../../apps/playground/ios",
+        "open:android": "open -a \"Android Studio\" ../../apps/playground/android",
+        "size": "bundle-size && size-limit",
+        "release": "./publish.sh",
+        "agent:test:unit": "yarn test:android:unit",
+        "agent:test:integration": "yarn test:android:instrumented",
+        "agent:compilation:check": "yarn typecheck && yarn build"
+    },
+    "devDependencies": {
+        "@expo/config-plugins": "~54.0.0",
+        "@expo/npm-proofread": "^1.0.1",
+        "@siteed/publisher": "^0.4.18",
+        "@size-limit/preset-big-lib": "^11.1.4",
+        "@types/jest": "^29.5.12",
+        "@types/node": "^20.12.7",
+        "@types/react": "~19.0.10",
+        "@typescript-eslint/eslint-plugin": "^7.7.0",
+        "@typescript-eslint/parser": "^7.7.0",
+        "bundle-size": "^1.1.5",
+        "eslint": "^8.56.0",
+        "eslint-config-prettier": "^9.1.0",
+        "eslint-config-universe": "^12.0.0",
+        "eslint-plugin-import": "^2.29.1",
+        "eslint-plugin-prettier": "^5.1.3",
+        "eslint-plugin-promise": "^6.1.1",
+        "eslint-plugin-react": "^7.34.1",
+        "expo": "^54.0.0",
+        "expo-module-scripts": "^4.1.7",
+        "expo-modules-core": "~3.0.0",
+        "jest": "^29.7.0",
+        "prettier": "^3.2.5",
+        "react": "19.1.0",
+        "react-native": "0.81.5",
+        "rimraf": "^6.0.1",
+        "size-limit": "^11.1.4",
+        "ts-node": "^10.9.2",
+        "typedoc": "^0.27.4",
+        "typedoc-plugin-markdown": "~4.4.2",
+        "typescript": "~5.8.3"
+    },
+    "peerDependencies": {
+        "expo": ">=52.0.0",
+        "react": "*",
+        "react-native": "*"
+    },
+    "publishConfig": {
+        "access": "public",
+        "registry": "https://registry.npmjs.org"
+    }
+}

package/plugin/build/index.cjs

@@ -0,0 +1,194 @@
+"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,
+        enableDeviceDetection: true, // Default to true for backward compatibility
+        iosBackgroundModes: {
+            useVoIP: false,
+            useAudio: false,
+            useProcessing: false,
+            useLocation: false,
+            useExternalAccessory: false,
+        },
+        iosConfig: {
+            microphoneUsageDescription: MICROPHONE_USAGE,
+            notificationUsageDescription: NOTIFICATION_USAGE,
+        },
+        ...(props || {}),
+    };
+    const { enablePhoneStateHandling, enableNotifications, enableBackgroundAudio, enableDeviceDetection, } = 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'];
+        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',
+            enableBackgroundAudio && 'android.permission.WAKE_LOCK', // Keep device awake during background recording
+            // Device detection permissions (only if enabled)
+            enableDeviceDetection && 'android.permission.BLUETOOTH',
+            enableDeviceDetection && 'android.permission.BLUETOOTH_ADMIN',
+            enableDeviceDetection && 'android.permission.BLUETOOTH_CONNECT',
+            enableDeviceDetection && 'android.permission.USB_PERMISSION',
+        ].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);
+        // Add each permission only if it doesn't exist
+        permissionsToAdd.forEach((permission) => {
+            config_plugins_1.AndroidConfig.Permissions.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;
+};
+// Export as default
+exports.default = withRecordingPermission;

package/plugin/build/index.d.cts

@@ -0,0 +1,22 @@
+import { ConfigPlugin } from '@expo/config-plugins';
+interface AudioStreamPluginOptions {
+    enablePhoneStateHandling?: boolean;
+    enableNotifications?: boolean;
+    enableBackgroundAudio?: boolean;
+    enableDeviceDetection?: boolean;
+    iosBackgroundModes?: {
+        useVoIP?: boolean;
+        useAudio?: boolean;
+        useProcessing?: boolean;
+        useLocation?: boolean;
+        useExternalAccessory?: boolean;
+    };
+    iosConfig?: {
+        allowBackgroundAudioControls?: boolean;
+        backgroundProcessingTitle?: string;
+        microphoneUsageDescription?: string;
+        notificationUsageDescription?: string;
+    };
+}
+declare const withRecordingPermission: ConfigPlugin<AudioStreamPluginOptions>;
+export default withRecordingPermission;

package/plugin/build/index.js

@@ -0,0 +1,194 @@
+"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,
+        enableDeviceDetection: true, // Default to true for backward compatibility
+        iosBackgroundModes: {
+            useVoIP: false,
+            useAudio: false,
+            useProcessing: false,
+            useLocation: false,
+            useExternalAccessory: false,
+        },
+        iosConfig: {
+            microphoneUsageDescription: MICROPHONE_USAGE,
+            notificationUsageDescription: NOTIFICATION_USAGE,
+        },
+        ...(props || {}),
+    };
+    const { enablePhoneStateHandling, enableNotifications, enableBackgroundAudio, enableDeviceDetection, } = 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'];
+        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',
+            enableBackgroundAudio && 'android.permission.WAKE_LOCK', // Keep device awake during background recording
+            // Device detection permissions (only if enabled)
+            enableDeviceDetection && 'android.permission.BLUETOOTH',
+            enableDeviceDetection && 'android.permission.BLUETOOTH_ADMIN',
+            enableDeviceDetection && 'android.permission.BLUETOOTH_CONNECT',
+            enableDeviceDetection && 'android.permission.USB_PERMISSION',
+        ].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);
+        // Add each permission only if it doesn't exist
+        permissionsToAdd.forEach((permission) => {
+            config_plugins_1.AndroidConfig.Permissions.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;
+};
+// Export as default
+exports.default = withRecordingPermission;