@siteed/audio-studio 3.0.5 → 3.1.0

package/CHANGELOG.md

@@ -8,6 +8,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 
+## [3.1.0] - 2026-05-01
+### Changed
+- fix(audio-studio): preserve pause intent across interruptions (#375) ([2f0f731](https://github.com/deeeed/audiolab/commit/2f0f731e412f45fc81c4fe46bec2abd3f15b4824))
+- fix(android): avoid recorder crashes from stale system callbacks (#374) ([34a9bc0](https://github.com/deeeed/audiolab/commit/34a9bc0c2f7c4e3e569862e8db43710abbde9043))
+- Document when to avoid retaining live analysis history (#373) ([aa617b0](https://github.com/deeeed/audiolab/commit/aa617b048dd790218dda43ec2ed21e0abaf38daf))
+- Let long-running analysis skip full history retention (#372) ([13c230c](https://github.com/deeeed/audiolab/commit/13c230cde655131a3a7c9472d294b2d432f79d50))
+- Keep low-rate iOS AAC recordings from losing compressed output (#371) ([a689eb0](https://github.com/deeeed/audiolab/commit/a689eb03c7436429bd3bf997430f7f7c842b2e57))
+- chore(audio-studio): release @siteed/audio-studio@3.0.5 ([9dff021](https://github.com/deeeed/audiolab/commit/9dff0219993803d29a03946cf81fe2bedb541cab))
 ## [3.0.5] - 2026-04-25
 ### Changed
 - fix(audio-studio): don't start notification on prepareRecording (Android) (#364) ([5d40d7e](https://github.com/deeeed/audiolab/commit/5d40d7e730f2b74459d319979fd9c112891b10f2))
@@ -349,7 +357,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Audio features extraction during recording
 - Consistent WAV PCM recording format across all platforms
 
-[unreleased]: https://github.com/deeeed/audiolab/compare/@siteed/audio-studio@3.0.5...HEAD
+[unreleased]: https://github.com/deeeed/audiolab/compare/@siteed/audio-studio@3.1.0...HEAD
+[3.1.0]: https://github.com/deeeed/audiolab/compare/@siteed/audio-studio@3.0.5...@siteed/audio-studio@3.1.0
 [3.0.5]: https://github.com/deeeed/audiolab/compare/@siteed/audio-studio@3.0.4...@siteed/audio-studio@3.0.5
 [3.0.4]: https://github.com/deeeed/audiolab/compare/@siteed/audio-studio@3.0.3...@siteed/audio-studio@3.0.4
 [3.0.3]: https://github.com/deeeed/audiolab/compare/@siteed/audio-studio@3.0.2...@siteed/audio-studio@3.0.3

package/README.md

@@ -113,6 +113,26 @@ await startRecording({
 
 ## Audio Analysis
 
+For live analysis during recording, `useAudioRecorder` keeps a recent analysis
+window in `analysisData` for visualization and, by default, also retains the
+full analysis history so `stopRecording().analysisData` can describe the whole
+recording. This option only matters when `enableProcessing: true`. For
+long-running sessions that only need live callbacks, disable the full-history
+retention to avoid unbounded JS memory growth:
+
+```typescript
+await startRecording({
+  sampleRate: 16000,
+  channels: 1,
+  enableProcessing: true,
+  keepFullAnalysis: false,
+  onAudioAnalysis: async (analysis) => {
+    // Consume each analysis chunk without retaining the full recording history.
+    updateVoiceActivity(analysis.dataPoints);
+  },
+});
+```
+
 ```typescript
 import { extractAudioAnalysis, extractPreview, extractMelSpectrogram, trimAudio } from '@siteed/audio-studio';
 

package/android/src/main/java/net/siteed/audiostudio/AudioRecorderManager.kt

@@ -118,6 +118,7 @@ class AudioRecorderManager(
     private var audioFocusRequest: Any? = null  // Type Any to handle both old and new APIs
     private var phoneStateListener: PhoneStateListener? = null
     private var telephonyCallback: Any? = null  // TelephonyCallback for API 31+, typed as Any to avoid class verification issues on older APIs
+    private val pausedBySystemInterruption = AtomicBoolean(false)
     private var telephonyManager: TelephonyManager? = null
         get() {
             if (field == null) {
@@ -408,7 +409,7 @@ class AudioRecorderManager(
                 if (_isRecording.get() && !isPaused.get()) {
                     LogUtils.d(CLASS_NAME, "Pausing recording due to incoming/ongoing call")
                     mainHandler.post {
-                        pauseRecording(object : Promise {
+                        pauseRecordingForSystemInterruption(object : Promise {
                             override fun resolve(value: Any?) {
                                 LogUtils.d(CLASS_NAME, "Successfully paused recording due to call")
                                 eventSender.sendExpoEvent(Constants.RECORDING_INTERRUPTED_EVENT_NAME, bundleOf(
@@ -426,8 +427,14 @@ class AudioRecorderManager(
             TelephonyManager.CALL_STATE_IDLE -> {
                 if (_isRecording.get() && isPaused.get()) {
                     val autoResume = if (::recordingConfig.isInitialized) recordingConfig.autoResumeAfterInterruption else false
-                    LogUtils.d(CLASS_NAME, "Call ended, handling auto-resume (enabled: $autoResume)")
-                    if (autoResume) {
+                    val shouldAutoResume = InterruptionAutoResumePolicy.shouldAutoResume(
+                        autoResumeAfterInterruption = autoResume,
+                        isRecording = _isRecording.get(),
+                        isPaused = isPaused.get(),
+                        pausedBySystemInterruption = pausedBySystemInterruption.get()
+                    )
+                    LogUtils.d(CLASS_NAME, "Call ended, handling auto-resume (enabled: $autoResume, pausedBySystemInterruption: ${pausedBySystemInterruption.get()})")
+                    if (shouldAutoResume) {
                         mainHandler.post {
                             resumeRecording(object : Promise {
                                 override fun resolve(value: Any?) {
@@ -443,7 +450,7 @@ class AudioRecorderManager(
                             })
                         }
                     } else {
-                        LogUtils.d(CLASS_NAME, "Auto-resume disabled, staying paused")
+                        LogUtils.d(CLASS_NAME, "Auto-resume not permitted, staying paused")
                         eventSender.sendExpoEvent(Constants.RECORDING_INTERRUPTED_EVENT_NAME, bundleOf(
                             "reason" to "phoneCallEnded",
                             "isPaused" to true
@@ -954,6 +961,7 @@ class AudioRecorderManager(
 
             audioRecord?.startRecording()
             isPaused.set(false)
+            pausedBySystemInterruption.set(false)
             isFirstChunk = true
             recordingStartTime = System.currentTimeMillis()
 
@@ -1174,6 +1182,7 @@ class AudioRecorderManager(
                 // Reset the timing variables
                 _isRecording.set(false)
                 isPaused.set(false)
+                pausedBySystemInterruption.set(false)
                 totalRecordedTime = 0
                 pausedDuration = 0
             } catch (e: Exception) {
@@ -1258,6 +1267,7 @@ class AudioRecorderManager(
             }
             
             LogUtils.d(CLASS_NAME, "⏺️ Recording resumed successfully")
+            pausedBySystemInterruption.set(false)
             promise.resolve("Recording resumed")
         } catch (e: Exception) {
             LogUtils.e(CLASS_NAME, "⏺️ Failed to resume recording: ${e.message}", e)
@@ -1267,12 +1277,21 @@ class AudioRecorderManager(
     }
 
     fun pauseRecording(promise: Promise) {
+        pauseRecording(promise, isSystemInterruption = false)
+    }
+
+    private fun pauseRecordingForSystemInterruption(promise: Promise) {
+        pauseRecording(promise, isSystemInterruption = true)
+    }
+
+    private fun pauseRecording(promise: Promise, isSystemInterruption: Boolean) {
         if (_isRecording.get() && !isPaused.get()) {
             audioRecord?.stop()
             compressedRecorder?.pause()
             
             lastPauseTime = System.currentTimeMillis()
             isPaused.set(true)
+            pausedBySystemInterruption.set(isSystemInterruption)
 
             if (recordingConfig.showNotification) {
                 notificationManager.pauseUpdates()
@@ -1417,17 +1436,7 @@ class AudioRecorderManager(
                        "audioManager.mode=${audioManager.mode}, " +
                        "audioManager.isBluetoothScoOn=${audioManager.isBluetoothScoOn}")
             
-            // Trust phone state more than audio manager state
-            if (callState == TelephonyManager.CALL_STATE_RINGING || 
-                callState == TelephonyManager.CALL_STATE_OFFHOOK) {
-                return true
-            }
-            
-            // Only check audio manager mode as secondary indicator
-            return audioManager.mode == AudioManager.MODE_IN_CALL || 
-                   audioManager.mode == AudioManager.MODE_IN_COMMUNICATION
-            
-            // Remove audioManager.isBluetoothScoOn check as it can be erroneously true after disconnection
+            return AndroidCallState.isOngoingCall(callState, audioManager.mode)
         } catch (e: Exception) {
             LogUtils.e(CLASS_NAME, "Error checking call state: ${e.message}")
             return false
@@ -1757,6 +1766,7 @@ class AudioRecorderManager(
                 
                 _isRecording.set(false)
                 isPaused.set(false)
+                pausedBySystemInterruption.set(false)
                 isPrepared = false  // Reset prepared state
                 
                 if (::recordingConfig.isInitialized && recordingConfig.showNotification) {
@@ -1919,9 +1929,8 @@ class AudioRecorderManager(
                 AudioManager.AUDIOFOCUS_LOSS_TRANSIENT -> {
                     if (_isRecording.get() && !isPaused.get()) {
                         mainHandler.post {
-                            pauseRecording(object : Promise {
+                            pauseRecordingForSystemInterruption(object : Promise {
                                 override fun resolve(value: Any?) {
-                                    isPaused.set(true)
                                     eventSender.sendExpoEvent(Constants.RECORDING_INTERRUPTED_EVENT_NAME, bundleOf(
                                         "reason" to "audioFocusLoss",
                                         "isPaused" to true
@@ -1936,7 +1945,12 @@ class AudioRecorderManager(
                 }
                 AudioManager.AUDIOFOCUS_GAIN -> {
                     val autoResume = if (::recordingConfig.isInitialized) recordingConfig.autoResumeAfterInterruption else false
-                    if (_isRecording.get() && isPaused.get() && autoResume) {
+                    if (InterruptionAutoResumePolicy.shouldAutoResume(
+                            autoResumeAfterInterruption = autoResume,
+                            isRecording = _isRecording.get(),
+                            isPaused = isPaused.get(),
+                            pausedBySystemInterruption = pausedBySystemInterruption.get()
+                        )) {
                         mainHandler.post {
                             resumeRecording(object : Promise {
                                 override fun resolve(value: Any?) {
@@ -1985,9 +1999,8 @@ class AudioRecorderManager(
                     // Only pause for permanent focus loss (like phone calls)
                     if (_isRecording.get() && !isPaused.get()) {
                         mainHandler.post {
-                            pauseRecording(object : Promise {
+                            pauseRecordingForSystemInterruption(object : Promise {
                                 override fun resolve(value: Any?) {
-                                    isPaused.set(true)
                                     eventSender.sendExpoEvent(Constants.RECORDING_INTERRUPTED_EVENT_NAME, bundleOf(
                                         "reason" to "audioFocusLoss",
                                         "isPaused" to true
@@ -2006,7 +2019,12 @@ class AudioRecorderManager(
                 }
                 AudioManager.AUDIOFOCUS_GAIN -> {
                     val autoResume = if (::recordingConfig.isInitialized) recordingConfig.autoResumeAfterInterruption else false
-                    if (_isRecording.get() && isPaused.get() && autoResume) {
+                    if (InterruptionAutoResumePolicy.shouldAutoResume(
+                            autoResumeAfterInterruption = autoResume,
+                            isRecording = _isRecording.get(),
+                            isPaused = isPaused.get(),
+                            pausedBySystemInterruption = pausedBySystemInterruption.get()
+                        )) {
                         mainHandler.post {
                             resumeRecording(object : Promise {
                                 override fun resolve(value: Any?) {
@@ -2168,4 +2186,38 @@ class AudioRecorderManager(
             return false
         }
     }
-}
+}
+
+internal object AndroidCallState {
+    /**
+     * Telephony call state wins when known. AudioManager mode is only a fallback
+     * for unknown state because some Android devices leave it stale after calls.
+     */
+    fun isOngoingCall(callState: Int?, audioMode: Int): Boolean {
+        return when (callState) {
+            TelephonyManager.CALL_STATE_RINGING,
+            TelephonyManager.CALL_STATE_OFFHOOK -> true
+            TelephonyManager.CALL_STATE_IDLE -> false
+            else -> audioMode == AudioManager.MODE_IN_CALL ||
+                audioMode == AudioManager.MODE_IN_COMMUNICATION
+        }
+    }
+}
+
+internal object InterruptionAutoResumePolicy {
+    /**
+     * Auto-resume is only allowed when the pause was caused by a system interruption.
+     * User-initiated pauses must stay paused even after phone/audio focus interruptions end.
+     */
+    fun shouldAutoResume(
+        autoResumeAfterInterruption: Boolean,
+        isRecording: Boolean,
+        isPaused: Boolean,
+        pausedBySystemInterruption: Boolean
+    ): Boolean {
+        return autoResumeAfterInterruption &&
+            isRecording &&
+            isPaused &&
+            pausedBySystemInterruption
+    }
+}

package/android/src/main/java/net/siteed/audiostudio/AudioStudioModule.kt

@@ -413,7 +413,7 @@ class AudioStudioModule : Module(), EventSender {
 
                     val progressListener = object : AudioTrimmer.ProgressListener {
                         override fun onProgress(progress: Float, bytesProcessed: Long, totalBytes: Long) {
-                            sendEvent(Constants.TRIM_PROGRESS_EVENT, mapOf(
+                            safeSendEvent(Constants.TRIM_PROGRESS_EVENT, mapOf(
                                 "progress" to progress,
                                 "bytesProcessed" to bytesProcessed,
                                 "totalBytes" to totalBytes
@@ -989,7 +989,7 @@ class AudioStudioModule : Module(), EventSender {
                         }
                         
                         // Notify JS about the disconnection
-                        sendEvent(Constants.DEVICE_CHANGED_EVENT, bundleOf(
+                        safeSendEvent(Constants.DEVICE_CHANGED_EVENT, bundleOf(
                             "type" to "deviceDisconnected",
                             "deviceId" to deviceId
                         ))
@@ -1004,7 +1004,7 @@ class AudioStudioModule : Module(), EventSender {
         audioDeviceManager.onDeviceConnected = { deviceId ->
             LogUtils.d(CLASS_NAME, "📱 Device connected: $deviceId")
             // Notify JS about the connection
-            sendEvent(Constants.DEVICE_CHANGED_EVENT, bundleOf(
+            safeSendEvent(Constants.DEVICE_CHANGED_EVENT, bundleOf(
                 "type" to "deviceConnected",
                 "deviceId" to deviceId
             ))
@@ -1014,7 +1014,7 @@ class AudioStudioModule : Module(), EventSender {
         audioDeviceManager.onDeviceDisconnected = { deviceId ->
             LogUtils.d(CLASS_NAME, "📱 Device disconnected: $deviceId")
             // Notify JS about the disconnection
-            sendEvent(Constants.DEVICE_CHANGED_EVENT, bundleOf(
+            safeSendEvent(Constants.DEVICE_CHANGED_EVENT, bundleOf(
                 "type" to "deviceDisconnected",
                 "deviceId" to deviceId
             ))
@@ -1023,6 +1023,18 @@ class AudioStudioModule : Module(), EventSender {
         audioProcessor = AudioProcessor(filesDir)
     }
     
+    private fun safeSendEvent(eventName: String, params: Bundle) {
+        AndroidEventEmitter.safeSend(CLASS_NAME, eventName) {
+            sendEvent(eventName, params)
+        }
+    }
+
+    private fun safeSendEvent(eventName: String, params: Map<String, Any?>) {
+        AndroidEventEmitter.safeSend(CLASS_NAME, eventName) {
+            sendEvent(eventName, params)
+        }
+    }
+
     /**
      * Handles audio device disconnection based on the recording configuration
      */
@@ -1055,7 +1067,7 @@ class AudioStudioModule : Module(), EventSender {
                         
                         // Notify JS about fallback
                         LogUtils.d(CLASS_NAME, "📱 Sending deviceFallback event to JS")
-                        sendEvent(Constants.RECORDING_INTERRUPTED_EVENT_NAME, bundleOf(
+                        safeSendEvent(Constants.RECORDING_INTERRUPTED_EVENT_NAME, bundleOf(
                             "reason" to "deviceFallback",
                             "isPaused" to false,
                             "deviceId" to deviceId
@@ -1070,7 +1082,7 @@ class AudioStudioModule : Module(), EventSender {
                                 // Notify AudioRecorderManager to handle device change while paused
                                 audioRecorderManager.handleDeviceChange()
                                 
-                                sendEvent(Constants.RECORDING_INTERRUPTED_EVENT_NAME, bundleOf(
+                                safeSendEvent(Constants.RECORDING_INTERRUPTED_EVENT_NAME, bundleOf(
                                     "reason" to "deviceSwitchFailed",
                                     "isPaused" to true
                                 ))
@@ -1090,7 +1102,7 @@ class AudioStudioModule : Module(), EventSender {
                             // Notify AudioRecorderManager to handle device change while paused
                             audioRecorderManager.handleDeviceChange()
                             
-                            sendEvent(Constants.RECORDING_INTERRUPTED_EVENT_NAME, bundleOf(
+                            safeSendEvent(Constants.RECORDING_INTERRUPTED_EVENT_NAME, bundleOf(
                                 "reason" to "deviceDisconnected",
                                 "isPaused" to true
                             ))
@@ -1112,7 +1124,7 @@ class AudioStudioModule : Module(), EventSender {
                         // Notify AudioRecorderManager to handle device change while paused
                         audioRecorderManager.handleDeviceChange()
                         
-                        sendEvent(Constants.RECORDING_INTERRUPTED_EVENT_NAME, bundleOf(
+                        safeSendEvent(Constants.RECORDING_INTERRUPTED_EVENT_NAME, bundleOf(
                             "reason" to "deviceDisconnected",
                             "isPaused" to true
                         ))
@@ -1128,6 +1140,18 @@ class AudioStudioModule : Module(), EventSender {
 
     override fun sendExpoEvent(eventName: String, params: Bundle) {
         LogUtils.d(CLASS_NAME, "Sending event: $eventName")
-        this@AudioStudioModule.sendEvent(eventName, params)
+        safeSendEvent(eventName, params)
+    }
+}
+
+internal object AndroidEventEmitter {
+    fun safeSend(className: String, eventName: String, send: () -> Unit): Boolean {
+        return try {
+            send()
+            true
+        } catch (e: Exception) {
+            LogUtils.e(className, "Failed to send event $eventName: ${e.message}", e)
+            false
+        }
     }
 }

package/android/src/main/java/net/siteed/audiostudio/EventSender.kt

@@ -3,5 +3,11 @@ package net.siteed.audiostudio
 import android.os.Bundle
 
 interface EventSender {
+    /**
+     * Best-effort event delivery to JavaScript.
+     *
+     * Native recording/device callbacks must not crash if Expo rejects an event
+     * while the module is not ready to emit.
+     */
     fun sendExpoEvent(eventName: String, params: Bundle)
 }

package/android/src/test/java/net/siteed/audiostudio/AndroidCallStateTest.kt

@@ -0,0 +1,37 @@
+package net.siteed.audiostudio
+
+import android.media.AudioManager
+import android.telephony.TelephonyManager
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+class AndroidCallStateTest {
+    @Test
+    fun idleCallStateWinsOverStaleInCallAudioMode() {
+        val result = AndroidCallState.isOngoingCall(
+            TelephonyManager.CALL_STATE_IDLE,
+            AudioManager.MODE_IN_CALL
+        )
+
+        assertFalse(result)
+    }
+
+    @Test
+    fun ringingAndOffhookAreOngoingCalls() {
+        assertTrue(AndroidCallState.isOngoingCall(
+            TelephonyManager.CALL_STATE_RINGING,
+            AudioManager.MODE_NORMAL
+        ))
+        assertTrue(AndroidCallState.isOngoingCall(
+            TelephonyManager.CALL_STATE_OFFHOOK,
+            AudioManager.MODE_NORMAL
+        ))
+    }
+
+    @Test
+    fun unknownCallStateFallsBackToAudioMode() {
+        assertTrue(AndroidCallState.isOngoingCall(null, AudioManager.MODE_IN_COMMUNICATION))
+        assertFalse(AndroidCallState.isOngoingCall(null, AudioManager.MODE_NORMAL))
+    }
+}

package/android/src/test/java/net/siteed/audiostudio/AndroidEventEmitterTest.kt

@@ -0,0 +1,28 @@
+package net.siteed.audiostudio
+
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+class AndroidEventEmitterTest {
+    @Test
+    fun safeSendReturnsTrueWhenEventIsSent() {
+        var sent = false
+
+        val result = AndroidEventEmitter.safeSend("Test", "event") {
+            sent = true
+        }
+
+        assertTrue(result)
+        assertTrue(sent)
+    }
+
+    @Test
+    fun safeSendCatchesEmitterExceptions() {
+        val result = AndroidEventEmitter.safeSend("Test", "event") {
+            throw IllegalArgumentException("module not ready")
+        }
+
+        assertFalse(result)
+    }
+}

package/android/src/test/java/net/siteed/audiostudio/InterruptionAutoResumePolicyTest.kt

@@ -0,0 +1,49 @@
+package net.siteed.audiostudio
+
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+class InterruptionAutoResumePolicyTest {
+    @Test
+    fun autoResumesOnlyWhenSystemInterruptionPausedRecording() {
+        assertTrue(InterruptionAutoResumePolicy.shouldAutoResume(
+            autoResumeAfterInterruption = true,
+            isRecording = true,
+            isPaused = true,
+            pausedBySystemInterruption = true
+        ))
+    }
+
+    @Test
+    fun doesNotAutoResumeUserPausedRecording() {
+        assertFalse(InterruptionAutoResumePolicy.shouldAutoResume(
+            autoResumeAfterInterruption = true,
+            isRecording = true,
+            isPaused = true,
+            pausedBySystemInterruption = false
+        ))
+    }
+
+    @Test
+    fun requiresAutoResumeAndActivePausedRecording() {
+        assertFalse(InterruptionAutoResumePolicy.shouldAutoResume(
+            autoResumeAfterInterruption = false,
+            isRecording = true,
+            isPaused = true,
+            pausedBySystemInterruption = true
+        ))
+        assertFalse(InterruptionAutoResumePolicy.shouldAutoResume(
+            autoResumeAfterInterruption = true,
+            isRecording = false,
+            isPaused = true,
+            pausedBySystemInterruption = true
+        ))
+        assertFalse(InterruptionAutoResumePolicy.shouldAutoResume(
+            autoResumeAfterInterruption = true,
+            isRecording = true,
+            isPaused = false,
+            pausedBySystemInterruption = true
+        ))
+    }
+}