@siteed/expo-audio-studio 2.9.0 → 2.10.1

package/package.json

@@ -1,134 +1,141 @@
 {
-  "name": "@siteed/expo-audio-studio",
-  "version": "2.9.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/expo-audio-stream/blob/main/packages/expo-audio-studio/README.md",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/deeeed/expo-audio-stream.git",
-    "directory": "packages/expo-audio-studio"
-  },
-  "bugs": {
-    "url": "https://github.com/deeeed/expo-audio-stream/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",
-    "build",
-    "!ios/build",
-    "!android/build",
-    "!android/gradle",
-    "!android/gradlew",
-    "!android/gradlew.bat",
-    "!android/local.properties",
-    "!**/__tests__",
-    "!**/__fixtures__",
-    "!**/__mocks__",
-    "!**/.*"
-  ],
-  "scripts": {
-    "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 --build plugin/tsconfig.json",
-    "build:plugin:dev": "expo-module build plugin",
-    "build:dev": "expo-module build",
-    "clean": "expo-module clean && rimraf build plugin/build",
-    "lint": "expo-module lint",
-    "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 && 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",
-    "open:android": "open -a \"Android Studio\" ../../apps/playground/android",
-    "size": "bundle-size && size-limit",
-    "release": "./publish.sh"
-  },
-  "devDependencies": {
-    "@expo/config-plugins": "~10.0.0",
-    "@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": "^53.0.9",
-    "expo-module-scripts": "^4.0.2",
-    "jest": "^29.7.0",
-    "prettier": "^3.2.5",
-    "react-native": "0.79.2",
-    "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": "*",
-    "react": "*",
-    "react-native": "*"
-  },
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org"
-  },
-  "dependencies": {
-    "expo-modules-core": "~2.3.13"
-  }
-}
+    "name": "@siteed/expo-audio-studio",
+    "version": "2.10.1",
+    "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/expo-audio-stream/blob/main/packages/expo-audio-studio/README.md",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/deeeed/expo-audio-stream.git",
+        "directory": "packages/expo-audio-studio"
+    },
+    "bugs": {
+        "url": "https://github.com/deeeed/expo-audio-stream/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",
+        "build",
+        "!ios/build",
+        "!android/build",
+        "!android/gradle",
+        "!android/gradlew",
+        "!android/gradlew.bat",
+        "!android/local.properties",
+        "!**/__tests__",
+        "!**/__fixtures__",
+        "!**/__mocks__",
+        "!**/.*"
+    ],
+    "scripts": {
+        "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 --build plugin/tsconfig.json",
+        "build:plugin:dev": "expo-module build plugin",
+        "build:dev": "expo-module build",
+        "clean": "expo-module clean && rimraf build plugin/build",
+        "lint": "expo-module lint",
+        "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 ios && xcodebuild test -workspace ExpoAudioStudio.xcworkspace -scheme ExpoAudioStudio -destination 'platform=iOS Simulator,name=iPhone 14'",
+        "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",
+        "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"
+    },
+    "devDependencies": {
+        "@expo/config-plugins": "~10.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": "^53.0.9",
+        "expo-module-scripts": "^4.1.7",
+        "jest": "^29.7.0",
+        "prettier": "^3.2.5",
+        "react-native": "0.79.2",
+        "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": "*",
+        "react": "*",
+        "react-native": "*"
+    },
+    "publishConfig": {
+        "access": "public",
+        "registry": "https://registry.npmjs.org"
+    },
+    "dependencies": {
+        "expo-modules-core": "~2.3.13"
+    }
+}

package/src/ExpoAudioStream.types.ts

@@ -209,15 +209,7 @@ export interface IOSConfig {
 
 /** Web platform specific configuration options */
 export interface WebConfig {
-    /**
-     * Whether to store uncompressed audio data for WAV generation
-     *
-     * When true, all PCM chunks are stored in memory to create a WAV file when compression is disabled
-     * When false, uncompressed audio won't be available, but memory usage will be lower
-     *
-     * Default: true (for backward compatibility)
-     */
-    storeUncompressedAudio?: boolean
+    // Reserved for future web-specific options
 }
 
 // Add new type for interruption reasons
@@ -291,6 +283,45 @@ export const DeviceDisconnectionBehavior = {
 export type DeviceDisconnectionBehaviorType =
     (typeof DeviceDisconnectionBehavior)[keyof typeof DeviceDisconnectionBehavior]
 
+/**
+ * Configuration for audio output files during recording
+ */
+export interface OutputConfig {
+    /**
+     * Configuration for the primary (uncompressed) output file
+     */
+    primary?: {
+        /** Whether to create the primary output file (default: true) */
+        enabled?: boolean
+        /** Format for the primary output (currently only 'wav' is supported) */
+        format?: 'wav'
+    }
+
+    /**
+     * Configuration for the compressed output file
+     */
+    compressed?: {
+        /** Whether to create a compressed output file (default: false) */
+        enabled?: boolean
+        /**
+         * Format for compression
+         * - 'aac': Advanced Audio Coding - supported on all platforms
+         * - 'opus': Opus encoding - supported on Android and Web; on iOS will automatically fall back to AAC
+         */
+        format?: 'aac' | 'opus'
+        /** Bitrate for compression in bits per second (default: 128000) */
+        bitrate?: number
+    }
+
+    // Future enhancement: Post-processing pipeline
+    // postProcessing?: {
+    //     normalize?: boolean
+    //     trimSilence?: boolean
+    //     noiseReduction?: boolean
+    //     customProcessors?: AudioProcessor[]
+    // }
+}
+
 export interface RecordingConfig {
     /** Sample rate for recording in Hz (16000, 44100, or 48000) */
     sampleRate?: SampleRate
@@ -340,19 +371,16 @@ export interface RecordingConfig {
     /** Callback function to handle audio features extraction results */
     onAudioAnalysis?: (_: AudioAnalysisEvent) => Promise<void>
 
-    /** Configuration for audio compression */
-    compression?: {
-        /** Enable audio compression */
-        enabled: boolean
-        /**
-         * Format for compression
-         * - 'aac': Advanced Audio Coding - supported on all platforms
-         * - 'opus': Opus encoding - supported on Android and Web; on iOS will automatically fall back to AAC
-         */
-        format: 'aac' | 'opus'
-        /** Bitrate for compression in bits per second */
-        bitrate?: number
-    }
+    /**
+     * Configuration for audio output files
+     *
+     * Examples:
+     * - Primary only (default): `{ primary: { enabled: true } }`
+     * - Compressed only: `{ primary: { enabled: false }, compressed: { enabled: true, format: 'aac' } }`
+     * - Both outputs: `{ compressed: { enabled: true } }`
+     * - Streaming only: `{ primary: { enabled: false } }`
+     */
+    output?: OutputConfig
 
     /** Whether to automatically resume recording after an interruption (default is false) */
     autoResumeAfterInterruption?: boolean
@@ -370,6 +398,22 @@ export interface RecordingConfig {
 
     /** How to handle device disconnection during recording */
     deviceDisconnectionBehavior?: DeviceDisconnectionBehaviorType
+
+    /**
+     * Buffer duration in seconds. Controls the size of audio buffers
+     * used during recording. Smaller values reduce latency but increase
+     * CPU usage. Larger values improve efficiency but increase latency.
+     *
+     * Platform Notes:
+     * - iOS/macOS: Minimum effective 0.1s, uses accumulation below
+     * - Android: Respects all sizes within hardware limits
+     * - Web: Fully configurable
+     *
+     * Default: undefined (uses platform default ~23ms at 44.1kHz)
+     * Recommended: 0.01 - 0.5 seconds
+     * Optimal iOS: >= 0.1 seconds
+     */
+    bufferDurationSeconds?: number
 }
 
 export interface NotificationConfig {

package/src/ExpoAudioStream.web.ts

@@ -285,13 +285,15 @@ export class ExpoAudioStreamWeb extends LegacyEventEmitter {
             bitDepth: this.bitDepth,
             channels: recordingConfig.channels ?? 1,
             sampleRate: recordingConfig.sampleRate ?? 44100,
-            compression: recordingConfig.compression
+            compression: recordingConfig.output?.compressed?.enabled
                 ? {
-                      ...recordingConfig.compression,
-                      bitrate: recordingConfig.compression?.bitrate ?? 128000,
+                      ...recordingConfig.output.compressed,
+                      bitrate:
+                          recordingConfig.output.compressed.bitrate ?? 128000,
                       size: 0,
                       mimeType: 'audio/webm',
-                      format: recordingConfig.compression?.format ?? 'opus',
+                      format:
+                          recordingConfig.output.compressed.format ?? 'opus',
                       compressedFileUri: '',
                   }
                 : undefined,
@@ -459,56 +461,56 @@ export class ExpoAudioStreamWeb extends LegacyEventEmitter {
             let fileUri = `${this.streamUuid}.${this.extension}`
             let mimeType = `audio/${this.extension}`
 
-            // Handle both compressed and uncompressed blobs according to configuration
-            const compressionEnabled =
-                this.recordingConfig?.compression?.enabled ?? false
+            // Handle both compressed and uncompressed blobs according to new output configuration
+            const primaryEnabled =
+                this.recordingConfig?.output?.primary?.enabled ?? true
+            const compressedEnabled =
+                this.recordingConfig?.output?.compressed?.enabled ?? false
 
-            // Process compressed blob if available
-            if (compressedBlob) {
+            // Process compressed blob if available and enabled
+            if (compressedBlob && compressedEnabled) {
                 const compressedUri = URL.createObjectURL(compressedBlob)
                 const compressedInfo = {
                     compressedFileUri: compressedUri,
                     size: compressedBlob.size,
                     mimeType: 'audio/webm',
-                    format: 'opus',
+                    format:
+                        this.recordingConfig?.output?.compressed?.format ??
+                        'opus',
                     bitrate:
-                        this.recordingConfig?.compression?.bitrate ?? 128000,
+                        this.recordingConfig?.output?.compressed?.bitrate ??
+                        128000,
                 }
 
-                // If compression is enabled, use compressed blob as primary format
-                if (compressionEnabled) {
+                // Store compression info
+                compression = compressedInfo
+
+                // If primary is disabled, use compressed as main file
+                if (!primaryEnabled) {
                     this.logger?.debug(
-                        'Using compressed audio as primary output'
+                        'Using compressed audio as primary output (primary disabled)'
                     )
                     fileUri = compressedUri
                     mimeType = 'audio/webm'
-
-                    // Store compression info
-                    compression = compressedInfo
-                } else {
-                    // Compression was enabled during recording but not set as primary
-                    // Store as alternate format
-                    compression = compressedInfo
                 }
             }
 
-            // Process uncompressed WAV if available
-            if (uncompressedBlob) {
+            // Process uncompressed WAV if available and primary is enabled
+            if (uncompressedBlob && primaryEnabled) {
                 const wavUri = URL.createObjectURL(uncompressedBlob)
-
-                // If compression is disabled or no compressed blob is available,
-                // use WAV as primary format
-                if (!compressionEnabled || !compressedBlob) {
-                    this.logger?.debug(
-                        'Using uncompressed WAV as primary output'
-                    )
-                    fileUri = wavUri
-                    mimeType = 'audio/wav'
-                }
+                fileUri = wavUri
+                mimeType = 'audio/wav'
+            } else if (!primaryEnabled && !compressedEnabled) {
+                // No outputs enabled - streaming only mode
+                this.logger?.debug('No outputs enabled - streaming only mode')
+                fileUri = ''
+                mimeType = 'audio/wav'
             }
 
             // Use the stored streamUuid for the final filename
-            const filename = `${this.streamUuid}.${this.extension}`
+            const filename = fileUri
+                ? `${this.streamUuid}.${this.extension}`
+                : 'stream-only'
             const result: AudioRecording = {
                 fileUri,
                 filename,
@@ -517,7 +519,7 @@ export class ExpoAudioStreamWeb extends LegacyEventEmitter {
                 channels: this.recordingConfig?.channels ?? 1,
                 sampleRate: this.recordingConfig?.sampleRate ?? 44100,
                 durationMs: this.currentDurationMs,
-                size: this.currentSize,
+                size: primaryEnabled ? this.currentSize : 0,
                 mimeType,
                 compression,
             }
@@ -630,13 +632,16 @@ export class ExpoAudioStreamWeb extends LegacyEventEmitter {
             interval: this.currentInterval,
             intervalAnalysis: this.currentIntervalAnalysis,
             mimeType: `audio/${this.extension}`,
-            compression: this.recordingConfig?.compression?.enabled
+            compression: this.recordingConfig?.output?.compressed?.enabled
                 ? {
                       size: this.totalCompressedSize,
                       mimeType: 'audio/webm',
-                      format: this.recordingConfig.compression.format ?? 'opus',
+                      format:
+                          this.recordingConfig.output.compressed.format ??
+                          'opus',
                       bitrate:
-                          this.recordingConfig.compression.bitrate ?? 128000,
+                          this.recordingConfig.output.compressed.bitrate ??
+                          128000,
                       compressedFileUri: `${this.streamUuid}.webm`,
                   }
                 : undefined,

package/src/WebRecorder.web.ts

@@ -154,7 +154,7 @@ export class WebRecorder {
         }
 
         // Initialize compressed recording if enabled
-        if (recordingConfig.compression?.enabled) {
+        if (recordingConfig.output?.compressed?.enabled) {
             this.initializeCompressedRecorder()
         }
 
@@ -234,9 +234,9 @@ export class WebRecorder {
                     )
                     const samples = chunk.length // Number of samples in this chunk
 
-                    // Only store PCM data if web.storeUncompressedAudio is not explicitly false
+                    // Only store PCM data if primary output is enabled
                     const shouldStoreUncompressed =
-                        this.config.web?.storeUncompressedAudio !== false
+                        this.config.output?.primary?.enabled ?? true
 
                     // Store PCM chunks when needed - this is for the final WAV file
                     if (shouldStoreUncompressed) {
@@ -275,9 +275,12 @@ export class WebRecorder {
                               size: this.pendingCompressedChunk.size,
                               totalSize: this.compressedSize,
                               mimeType: 'audio/webm',
-                              format: 'opus',
+                              format:
+                                  this.config.output?.compressed?.format ??
+                                  'opus',
                               bitrate:
-                                  this.config.compression?.bitrate ?? 128000,
+                                  this.config.output?.compressed?.bitrate ??
+                                  128000,
                           }
                         : undefined
 
@@ -312,11 +315,11 @@ export class WebRecorder {
                 interval,
                 position: this.position,
                 deviceId: this.config.deviceId ?? 'default',
-                compression: this.config.compression
+                compression: this.config.output?.compressed
                     ? {
-                          enabled: this.config.compression.enabled,
-                          format: this.config.compression.format,
-                          bitrate: this.config.compression.bitrate,
+                          enabled: this.config.output.compressed.enabled,
+                          format: this.config.output.compressed.format,
+                          bitrate: this.config.output.compressed.bitrate,
                       }
                     : 'disabled',
             })
@@ -843,7 +846,7 @@ export class WebRecorder {
                 {
                     mimeType,
                     audioBitsPerSecond:
-                        this.config.compression?.bitrate ?? 128000,
+                        this.config.output?.compressed?.bitrate ?? 128000,
                 }
             )
 

package/src/useAudioRecorder.tsx

@@ -566,7 +566,7 @@ export function useAudioRecorder({
     }, [dispatch])
 
     useEffect(() => {
-        let intervalId: NodeJS.Timeout | undefined
+        let intervalId: ReturnType<typeof setInterval> | undefined
 
         if (state.isRecording || state.isPaused) {
             // Immediately check status when starting