expo-audio 55.0.4 → 55.0.6

package/CHANGELOG.md

@@ -10,6 +10,31 @@
 
 ### 💡 Others
 
+## 55.0.6 — 2026-02-16
+
+### 🎉 New features
+
+- [iOS] Add support for `shouldRouteThroughEarpiece`. ([#43089](https://github.com/expo/expo/pull/43089) by [@alanjhughes](https://github.com/alanjhughes))
+- [Android] Make it possible to add/remove the foreground service and foreground service permissions with a config plugin. ([#43014](https://github.com/expo/expo/pull/43014) by [@behenate](https://github.com/behenate))
+- [Web] Add support for audio sampling. ([#43149](https://github.com/expo/expo/pull/43149) by [@alanjhughes](https://github.com/alanjhughes))
+- [Web] Add support for media controls. ([#43150](https://github.com/expo/expo/pull/43150) by [@alanjhughes](https://github.com/alanjhughes))
+- [Web] Add support for selecting recording inputs. ([#43151](https://github.com/expo/expo/pull/43151) by [@alanjhughes](https://github.com/alanjhughes))
+- [Web] Add support for recording metering. ([#43152](https://github.com/expo/expo/pull/43152) by [@alanjhughes](https://github.com/alanjhughes))
+
+### 🐛 Bug fixes
+
+- [Android] Fix memory leaks when refreshing the app. ([#42785](https://github.com/expo/expo/pull/42785) by [@behenate](https://github.com/behenate))
+- [iOS] Fixes `mediaServicesDidReset` not being correctly implemented. ([#42898](https://github.com/expo/expo/pull/42898) by [@alanjhughes](https://github.com/alanjhughes))
+
+### 💡 Others
+
+- [Android] Improve event handling. ([#43121](https://github.com/expo/expo/pull/43121) by [@alanjhughes](https://github.com/alanjhughes))
+- [Android] Rework native audio service handling. ([#43015](https://github.com/expo/expo/pull/43015) by [@behenate](https://github.com/behenate))
+
+## 55.0.5 — 2026-02-08
+
+_This version does not introduce any user-facing changes._
+
 ## 55.0.4 — 2026-02-03
 
 _This version does not introduce any user-facing changes._

package/android/build.gradle

@@ -4,13 +4,13 @@ plugins {
 }
 
 group = 'expo.modules.audio'
-version = '55.0.4'
+version = '55.0.6'
 
 android {
   namespace "expo.modules.audio"
   defaultConfig {
     versionCode 1
-    versionName "55.0.4"
+    versionName "55.0.6"
   }
 
   compileOptions {

package/android/src/main/AndroidManifest.xml

@@ -1,21 +1,4 @@
 <manifest xmlns:android="http://schemas.android.com/apk/res/android">
   <uses-permission android:name="android.permission.RECORD_AUDIO" />
   <uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
-  <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
-  <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />
-
-  <application>
-    <service
-      android:name=".service.AudioControlsService"
-      android:exported="false"
-      android:foregroundServiceType="mediaPlayback">
-      <intent-filter>
-        <action android:name="androidx.media3.session.MediaSessionService" />
-      </intent-filter>
-    </service>
-    <service
-      android:name=".service.AudioRecordingService"
-      android:exported="false"
-      android:foregroundServiceType="microphone" />
-  </application>
 </manifest>

package/android/src/main/java/expo/modules/audio/AudioExceptions.kt

@@ -2,9 +2,24 @@ package expo.modules.audio
 
 import expo.modules.kotlin.exception.CodedException
 
+private const val defaultPlaybackServiceTip =
+  "Make sure that the expo-audio config plugin is properly configured with " +
+    "'enableBackgroundPlayback: true' to avoid issues with lock screen controls " +
+    "and background audio playback."
+
+private const val defaultRecordingServiceTip =
+  "Make sure that the expo-audio config plugin is properly configured with " +
+    "'enableBackgroundRecording: true' to avoid issues with background recording."
+
 internal class AudioPermissionsException :
   CodedException("RECORD_AUDIO permission has not been granted")
 
+internal class NotificationPermissionsException :
+  CodedException(
+    "POST_NOTIFICATIONS permission has not been granted. This permission is required when using background recording (allowsBackgroundRecording: true). " +
+      "Request notification permissions using AudioModule.requestNotificationPermissionsAsync() before calling prepareRecording()."
+  )
+
 internal class GetAudioInputNotSupportedException :
   CodedException("Getting current audio input is not supported on devices running Android version lower than Android 9.0")
 
@@ -22,3 +37,23 @@ internal class AudioRecorderPrepareException(cause: Throwable) :
 
 internal class AudioRecorderAlreadyPreparedException :
   CodedException("AudioRecorder has already been prepared. Stop or release the current session before preparing again.")
+
+internal fun getPlaybackServiceErrorMessage(
+  message: String?,
+  tip: String = defaultPlaybackServiceTip
+): String {
+  return (message ?: "expo-audio playback service error") + ". $tip"
+}
+
+internal fun getRecordingServiceErrorMessage(
+  message: String?,
+  tip: String = defaultRecordingServiceTip
+): String {
+  return (message ?: "expo-audio recording service error") + ". $tip"
+}
+
+internal class AudioRecordingServiceException(message: String?, cause: Throwable? = null) :
+  CodedException(getRecordingServiceErrorMessage(message), cause)
+
+internal class AudioPlaybackServiceException(message: String?, cause: Throwable? = null) :
+  CodedException(getPlaybackServiceErrorMessage(message), cause)

package/android/src/main/java/expo/modules/audio/AudioModule.kt

@@ -28,10 +28,10 @@ import androidx.media3.exoplayer.hls.HlsMediaSource
 import androidx.media3.exoplayer.smoothstreaming.SsMediaSource
 import androidx.media3.exoplayer.source.MediaSource
 import androidx.media3.exoplayer.source.ProgressiveMediaSource
-import expo.modules.audio.service.AudioControlsService
 import expo.modules.interfaces.permissions.Permissions
 import expo.modules.kotlin.Promise
 import expo.modules.kotlin.exception.Exceptions
+import expo.modules.kotlin.functions.Coroutine
 import expo.modules.kotlin.functions.Queues
 import expo.modules.kotlin.modules.Module
 import expo.modules.kotlin.modules.ModuleDefinition
@@ -210,6 +210,10 @@ class AudioModule : Module() {
       Permissions.askForPermissionsWithPermissionsManager(appContext.permissions, promise, Manifest.permission.RECORD_AUDIO)
     }
 
+    AsyncFunction("requestNotificationPermissionsAsync") { promise: Promise ->
+      Permissions.askForPermissionsWithPermissionsManager(appContext.permissions, promise, Manifest.permission.POST_NOTIFICATIONS)
+    }
+
     AsyncFunction("getRecordingPermissionsAsync") { promise: Promise ->
       Permissions.getPermissionsWithPermissionsManager(appContext.permissions, promise, Manifest.permission.RECORD_AUDIO)
     }
@@ -269,8 +273,6 @@ class AudioModule : Module() {
         recorders.values.forEach {
           it.stopRecording()
         }
-
-        AudioControlsService.clearSession()
       }
     }
 
@@ -494,7 +496,7 @@ class AudioModule : Module() {
         recorder.getCurrentTimeSeconds()
       }
 
-      AsyncFunction("prepareToRecordAsync") { recorder: AudioRecorder, options: RecordingOptions? ->
+      AsyncFunction("prepareToRecordAsync") Coroutine { recorder: AudioRecorder, options: RecordingOptions? ->
         checkRecordingPermission()
         recorder.prepareRecording(options)
       }

package/android/src/main/java/expo/modules/audio/AudioPlayer.kt

@@ -13,12 +13,16 @@ import androidx.media3.common.Player
 import androidx.media3.common.util.UnstableApi
 import androidx.media3.exoplayer.ExoPlayer
 import androidx.media3.exoplayer.source.MediaSource
-import expo.modules.audio.service.AudioControlsService
+import androidx.media3.session.MediaSession
+import expo.modules.audio.service.AudioPlaybackServiceConnection
+import expo.modules.audio.service.ServiceBindingState
 import expo.modules.kotlin.AppContext
 import expo.modules.kotlin.exception.Exceptions
 import expo.modules.kotlin.sharedobjects.SharedRef
 import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.DelicateCoroutinesApi
 import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.GlobalScope
 import kotlinx.coroutines.Job
 import kotlinx.coroutines.cancel
 import kotlinx.coroutines.delay
@@ -27,7 +31,7 @@ import kotlinx.coroutines.flow.launchIn
 import kotlinx.coroutines.flow.onEach
 import kotlinx.coroutines.flow.onStart
 import kotlinx.coroutines.launch
-import kotlinx.coroutines.withContext
+import java.lang.ref.WeakReference
 import java.util.UUID
 
 private const val PLAYBACK_STATUS_UPDATE = "playbackStatusUpdate"
@@ -58,9 +62,12 @@ class AudioPlayer(
 
   // Lock screen controls
   var isActiveForLockScreen = false
-  private var metadata: Metadata? = null
+  internal var metadata: Metadata? = null
+  internal var lockScreenOptions: AudioLockScreenOptions? = null
+  internal var mediaSession: MediaSession = buildBasicMediaSession(context, ref)
+  val serviceConnection = AudioPlaybackServiceConnection(WeakReference(this), appContext)
 
-  private var playerScope = CoroutineScope(Dispatchers.Default)
+  private var playerScope = CoroutineScope(Dispatchers.Main)
   private var samplingEnabled = false
   private var visualizer: Visualizer? = null
   private var playing = false
@@ -106,22 +113,47 @@ class AudioPlayer(
   fun setActiveForLockScreen(active: Boolean, metadata: Metadata? = null, options: AudioLockScreenOptions? = null) {
     if (active) {
       this.metadata = metadata
-      AudioControlsService.setActivePlayer(context, this, metadata, options)
+      this.lockScreenOptions = options
+      this.isActiveForLockScreen = true
+
+      if (serviceConnection.bindingState == ServiceBindingState.UNBOUND) {
+        serviceConnection.bindWithService()
+      }
+
+      val serviceBinder = serviceConnection.playbackServiceBinder
+      if (serviceBinder != null && serviceConnection.bindingState == ServiceBindingState.BOUND) {
+        serviceBinder.service.setPlayerOptions(this, metadata, options)
+      } else if (serviceConnection.bindingState == ServiceBindingState.BINDING) {
+        // The settings will be applied when the service connects
+      } else {
+        appContext?.jsLogger?.error(
+          getPlaybackServiceErrorMessage("Failed to activate lock screen controls - service binding failed")
+        )
+      }
     } else if (isActiveForLockScreen) {
-      AudioControlsService.setActivePlayer(context, null)
+      this.isActiveForLockScreen = false
+      serviceConnection.playbackServiceBinder?.service?.unregisterPlayer()
     }
   }
 
   fun updateLockScreenMetadata(metadata: Metadata) {
     if (isActiveForLockScreen) {
       this.metadata = metadata
-      AudioControlsService.updateMetadata(this, metadata)
+
+      val serviceBinder = serviceConnection.playbackServiceBinder
+      if (serviceBinder != null && serviceConnection.bindingState == ServiceBindingState.BOUND) {
+        serviceBinder.service.setPlayerMetadata(this, metadata)
+      } else {
+        appContext?.jsLogger?.warn(
+          getPlaybackServiceErrorMessage("Cannot update lock screen metadata - service not connected")
+        )
+      }
     }
   }
 
   fun clearLockScreenControls() {
     if (isActiveForLockScreen) {
-      AudioControlsService.setActivePlayer(context, null)
+      serviceConnection.playbackServiceBinder?.service?.unregisterPlayer()
     }
   }
 
@@ -158,15 +190,11 @@ class AudioPlayer(
       if (isTransient) {
         return
       }
-      playerScope.launch {
-        sendPlayerUpdate(mapOf("playing" to isPlaying))
-      }
+      sendPlayerUpdate(mapOf("playing" to isPlaying))
     }
 
     override fun onIsLoadingChanged(isLoading: Boolean) {
-      playerScope.launch {
-        sendPlayerUpdate(mapOf("isLoaded" to !isLoading))
-      }
+      sendPlayerUpdate()
     }
 
     override fun onPlaybackStateChanged(playbackState: Int) {
@@ -178,22 +206,18 @@ class AudioPlayer(
         intendedPlayingState = false
       }
 
-      playerScope.launch {
-        val updateMap = mutableMapOf<String, Any?>(
-          "playbackState" to playbackStateToString(playbackState)
-        )
-        if (justFinished) {
-          updateMap["didJustFinish"] = true
-          updateMap["playing"] = false
-        }
-        sendPlayerUpdate(updateMap)
+      val updateMap = mutableMapOf<String, Any?>(
+        "playbackState" to playbackStateToString(playbackState)
+      )
+      if (justFinished) {
+        updateMap["didJustFinish"] = true
+        updateMap["playing"] = false
       }
+      sendPlayerUpdate(updateMap)
     }
 
     override fun onMediaItemTransition(mediaItem: MediaItem?, reason: Int) {
-      playerScope.launch {
-        sendPlayerUpdate()
-      }
+      sendPlayerUpdate()
     }
 
     override fun onPositionDiscontinuity(
@@ -202,9 +226,7 @@ class AudioPlayer(
       reason: Int
     ) {
       if (reason == Player.DISCONTINUITY_REASON_SEEK) {
-        playerScope.launch {
-          sendPlayerUpdate(mapOf("currentTime" to (newPosition.positionMs / 1000f)))
-        }
+        sendPlayerUpdate(mapOf("currentTime" to (newPosition.positionMs / 1000f)))
       }
     }
   })
@@ -260,12 +282,16 @@ class AudioPlayer(
     )
   }
 
-  private suspend fun sendPlayerUpdate(map: Map<String, Any?>? = null) =
-    withContext(Dispatchers.Main) {
-      val data = currentStatus()
-      val body = map?.let { data + it } ?: data
-      emit(PLAYBACK_STATUS_UPDATE, body)
-    }
+  internal fun assignBasicMediaSession() {
+    mediaSession.release()
+    mediaSession = buildBasicMediaSession(context, ref)
+  }
+
+  private fun sendPlayerUpdate(map: Map<String, Any?>? = null) {
+    val data = currentStatus()
+    val body = map?.let { data + it } ?: data
+    emit(PLAYBACK_STATUS_UPDATE, body)
+  }
 
   private fun sendAudioSampleUpdate(sample: List<Float>) {
     val body = mapOf(
@@ -314,12 +340,20 @@ class AudioPlayer(
     }
   }
 
+  @OptIn(DelicateCoroutinesApi::class)
   override fun sharedObjectDidRelease() {
     super.sharedObjectDidRelease()
-    appContext?.mainQueue?.launch {
+
+    serviceConnection.release()
+
+    // Run on global scope (not appContext.mainQueue) so that reloading doesn't cancel the release process
+    // https://github.com/expo/expo/blob/cdf592a7fea56fc01b0149e9b2e5dbd294bcdc4c/packages/expo-modules-core/android/src/main/java/expo/modules/kotlin/AppContext.kt#L277-L279
+    GlobalScope.launch(Dispatchers.Main) {
+      mediaSession.release()
       if (isActiveForLockScreen) {
-        AudioControlsService.clearSession()
+        serviceConnection.playbackServiceBinder?.service?.unregisterPlayer()
       }
+      serviceConnection.unbind()
       playerScope.cancel()
       visualizer?.release()
       ref.release()

package/android/src/main/java/expo/modules/audio/AudioRecorder.kt

@@ -13,15 +13,19 @@ import android.os.Build
 import android.os.Bundle
 import androidx.core.content.ContextCompat
 import androidx.core.net.toUri
-import expo.modules.audio.service.AudioRecordingService
+import expo.modules.audio.service.AudioRecordingServiceConnection
 import expo.modules.kotlin.AppContext
+import expo.modules.kotlin.exception.CodedException
+import expo.modules.kotlin.exception.Exceptions
 import expo.modules.kotlin.sharedobjects.SharedObject
 import kotlinx.coroutines.Job
 import kotlinx.coroutines.delay
 import kotlinx.coroutines.launch
 import java.io.File
 import java.io.IOException
+import java.lang.ref.WeakReference
 import java.util.UUID
+import kotlin.coroutines.Continuation
 import kotlin.math.log10
 
 private const val RECORDING_STATUS_UPDATE = "recordingStatusUpdate"
@@ -45,7 +49,14 @@ class AudioRecorder(
   var isPaused = false
   private var recordingTimerJob: Job? = null
   var useForegroundService = false
-  private var isRegisteredWithService = false
+  private var bindingContinuation: Continuation<Boolean>? = null
+
+  val serviceConnection = AudioRecordingServiceConnection(WeakReference(this), appContext)
+
+  private val _appContext: AppContext
+    get() {
+      return appContext ?: throw Exceptions.AppContextLost()
+    }
 
   private fun currentFileUrl(): String? =
     filePath?.let(::File)?.toUri()?.toString()
@@ -71,25 +82,41 @@ class AudioRecorder(
     }
   }
 
-  fun prepareRecording(options: RecordingOptions?) {
+  suspend fun prepareRecording(options: RecordingOptions?) {
     if (recorder != null || isPrepared || isRecording || isPaused) {
       throw AudioRecorderAlreadyPreparedException()
     }
+
+    if (useForegroundService && !hasNotificationPermissions()) {
+      throw NotificationPermissionsException()
+    }
+
     val recordingOptions = options ?: this.options
     val mediaRecorder = createRecorder(recordingOptions)
     recorder = mediaRecorder
+
     try {
+      if (useForegroundService) {
+        serviceConnection.bindWithService()
+      }
       mediaRecorder.prepare()
       isPrepared = true
-    } catch (cause: Exception) {
+    } catch (e: Exception) {
       mediaRecorder.release()
       recorder = null
       isPrepared = false
-      throw AudioRecorderPrepareException(cause)
+
+      throw e as? CodedException ?: AudioRecorderPrepareException(e)
     }
   }
 
   fun record() {
+    if (useForegroundService) {
+      serviceConnection.recordingServiceBinder?.service?.registerRecorder(this) ?: run {
+        throw AudioRecordingServiceException("The service connection is not bound, but `allowsBackgroundRecording` is set to `true`")
+      }
+    }
+
     if (isPaused) {
       recorder?.resume()
     } else {
@@ -98,11 +125,6 @@ class AudioRecorder(
     startTime = System.currentTimeMillis()
     isRecording = true
     isPaused = false
-
-    if (useForegroundService && !isRegisteredWithService) {
-      AudioRecordingService.startService(context, this)
-      isRegisteredWithService = true
-    }
   }
 
   fun recordWithOptions(atTimeSeconds: Double? = null, forDurationSeconds: Double? = null) {
@@ -147,9 +169,8 @@ class AudioRecorder(
     var stopFailed = false
     var stopError: String? = null
 
-    if (useForegroundService && isRegisteredWithService) {
-      AudioRecordingService.getInstance()?.unregisterRecorder(this)
-      isRegisteredWithService = false
+    if (useForegroundService) {
+      serviceConnection.recordingServiceBinder?.service?.unregisterRecorder(this)
     }
 
     try {
@@ -259,9 +280,16 @@ class AudioRecorder(
 
   override fun sharedObjectDidRelease() {
     super.sharedObjectDidRelease()
-    if (useForegroundService && isRegisteredWithService) {
-      AudioRecordingService.getInstance()?.unregisterRecorder(this)
-      isRegisteredWithService = false
+
+    // Mark recorder as released
+    serviceConnection.release()
+
+    if (useForegroundService) {
+      serviceConnection.recordingServiceBinder?.service?.unregisterRecorder(this)
+      // Unbind service connection
+      serviceConnection.unbind()
+      // Clean up service connection resources
+      serviceConnection.cleanup()
     }
     reset()
   }
@@ -319,9 +347,10 @@ class AudioRecorder(
       MEDIA_RECORDER_INFO_MAX_FILESIZE_REACHED -> {
         val url = currentFileUrl()
 
-        if (useForegroundService && isRegisteredWithService) {
-          AudioRecordingService.getInstance()?.unregisterRecorder(this)
-          isRegisteredWithService = false
+        if (useForegroundService) {
+          serviceConnection.recordingServiceBinder?.service?.unregisterRecorder(this)
+          // Unbind the service connection
+          serviceConnection.unbind()
         }
 
         try {
@@ -390,6 +419,14 @@ class AudioRecorder(
   private fun hasRecordingPermissions() =
     ContextCompat.checkSelfPermission(context, Manifest.permission.RECORD_AUDIO) == PackageManager.PERMISSION_GRANTED
 
+  private fun hasNotificationPermissions(): Boolean {
+    // POST_NOTIFICATIONS permission is only required on Android 13+ (API 33+)
+    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU) {
+      return true
+    }
+    return ContextCompat.checkSelfPermission(context, Manifest.permission.POST_NOTIFICATIONS) == PackageManager.PERMISSION_GRANTED
+  }
+
   fun getAvailableInputs(audioManager: AudioManager) =
     audioManager.getDevices(AudioManager.GET_DEVICES_INPUTS).mapNotNull { deviceInfo ->
       val type = deviceInfo.type

package/android/src/main/java/expo/modules/audio/AudioUtils.kt

@@ -1,7 +1,10 @@
 package expo.modules.audio
 
+import android.content.Context
 import android.media.AudioDeviceInfo
 import android.os.Bundle
+import androidx.media3.exoplayer.ExoPlayer
+import androidx.media3.session.MediaSession
 import java.io.File
 import java.io.IOException
 
@@ -27,3 +30,9 @@ fun getMapFromDeviceInfo(deviceInfo: AudioDeviceInfo): Bundle {
   map.putString("uid", deviceInfo.id.toString())
   return map
 }
+
+fun buildBasicMediaSession(context: Context, player: ExoPlayer): MediaSession {
+  return MediaSession.Builder(context, player)
+    .setId("ExpoAudioBasicMediaSession_${player.hashCode()}")
+    .build()
+}