expo-audio 55.0.5 → 55.0.7

package/CHANGELOG.md

@@ -10,6 +10,39 @@
 
 ### 💡 Others
 
+## 55.0.7 — 2026-02-20
+
+### 🐛 Bug fixes
+
+- [Web] Fix potential `nan` duration. ([#43268](https://github.com/expo/expo/pull/43268) by [@alanjhughes](https://github.com/alanjhughes))
+
+### 💡 Others
+
+- [android] Make in-memory preload cache. ([#43293](https://github.com/expo/expo/pull/43293) by [@alanjhughes](https://github.com/alanjhughes))
+
+## 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))
+- [Web] Enable `setIsAudioActiveAsync`. ([#43142](https://github.com/expo/expo/pull/43142) by [@alanjhughes](https://github.com/alanjhughes))
+- Add support for preloading audio sources. ([#43063](https://github.com/expo/expo/pull/43063) 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._

package/android/build.gradle

@@ -4,13 +4,13 @@ plugins {
 }
 
 group = 'expo.modules.audio'
-version = '55.0.5'
+version = '55.0.7'
 
 android {
   namespace "expo.modules.audio"
   defaultConfig {
     versionCode 1
-    versionName "55.0.5"
+    versionName "55.0.7"
   }
 
   compileOptions {
@@ -24,12 +24,14 @@ repositories {
 
 dependencies {
   implementation 'androidx.appcompat:appcompat:1.7.1'
+  implementation 'androidx.core:core-ktx:1.15.0'
 
   def androidxMedia3Version = "1.8.0"
   implementation "androidx.media3:media3-session:$androidxMedia3Version"
   implementation "androidx.media3:media3-ui:$androidxMedia3Version"
   implementation "androidx.media3:media3-exoplayer:$androidxMedia3Version"
   implementation "androidx.media3:media3-exoplayer-dash:$androidxMedia3Version"
+  implementation "androidx.media3:media3-datasource:$androidxMedia3Version"
   implementation "androidx.media3:media3-datasource-okhttp:$androidxMedia3Version"
   implementation "androidx.media3:media3-exoplayer-hls:$androidxMedia3Version"
   implementation "androidx.media3:media3-exoplayer-smoothstreaming:$androidxMedia3Version"

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

@@ -17,7 +17,6 @@ import androidx.media3.common.C.CONTENT_TYPE_HLS
 import androidx.media3.common.C.CONTENT_TYPE_OTHER
 import androidx.media3.common.C.CONTENT_TYPE_SS
 import androidx.media3.common.MediaItem
-import androidx.media3.common.PlaybackParameters
 import androidx.media3.common.Player
 import androidx.media3.common.util.Util
 import androidx.media3.datasource.DataSource
@@ -28,20 +27,23 @@ 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
+import kotlinx.coroutines.DelicateCoroutinesApi
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.GlobalScope
 import kotlinx.coroutines.launch
 import kotlinx.coroutines.runBlocking
 import okhttp3.OkHttpClient
 import java.io.File
 import java.util.concurrent.ConcurrentHashMap
-import kotlin.math.min
 
+@DelicateCoroutinesApi
 @androidx.annotation.OptIn(androidx.media3.common.util.UnstableApi::class)
 class AudioModule : Module() {
   private lateinit var audioManager: AudioManager
@@ -51,6 +53,7 @@ class AudioModule : Module() {
 
   private val players = ConcurrentHashMap<String, AudioPlayer>()
   private val recorders = ConcurrentHashMap<String, AudioRecorder>()
+  private val playlists = ConcurrentHashMap<String, AudioPlaylist>()
   private var shouldPlayInBackground = false
   private var audioEnabled = true
   private var shouldRouteThroughEarpiece = false
@@ -58,40 +61,41 @@ class AudioModule : Module() {
   private var interruptionMode: InterruptionMode? = null
   private var allowsBackgroundRecording = false
 
+  private val allPlayables: Sequence<Playable>
+    get() = players.values.asSequence() + playlists.values.asSequence()
+
   private var audioFocusRequest: AudioFocusRequest? = null
   private val audioFocusChangeListener = AudioManager.OnAudioFocusChangeListener { focusChange ->
     appContext.mainQueue.launch {
       when (focusChange) {
         AudioManager.AUDIOFOCUS_LOSS -> {
           focusAcquired = false
-          players.values.forEach { player ->
-            player.ref.pause()
-          }
+          allPlayables.forEach { it.pause() }
         }
 
         AudioManager.AUDIOFOCUS_LOSS_TRANSIENT -> {
           focusAcquired = false
-          players.values.forEach { player ->
-            if (player.ref.isPlaying) {
-              player.isPaused = true
-              player.ref.pause()
+          allPlayables.forEach { playable ->
+            if (playable.isPlaying) {
+              playable.isPaused = true
+              playable.pause()
             }
           }
         }
 
         AudioManager.AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK -> {
           if (interruptionMode == InterruptionMode.DUCK_OTHERS) {
-            players.values.forEach { player ->
-              if (player.previousVolume != player.ref.volume) {
-                player.previousVolume = player.ref.volume
+            allPlayables.forEach { playable ->
+              if (playable.previousVolume != playable.volume) {
+                playable.previousVolume = playable.volume
               }
-              player.ref.volume = player.previousVolume * 0.5f
+              playable.setVolume(playable.previousVolume * 0.5f)
             }
           } else {
-            players.values.forEach { player ->
-              if (player.ref.isPlaying) {
-                player.isPaused = true
-                player.ref.pause()
+            allPlayables.forEach { playable ->
+              if (playable.isPlaying) {
+                playable.isPaused = true
+                playable.pause()
               }
             }
           }
@@ -99,11 +103,11 @@ class AudioModule : Module() {
 
         AudioManager.AUDIOFOCUS_GAIN -> {
           focusAcquired = true
-          players.values.forEach { player ->
-            player.setVolume(player.previousVolume)
-            if (player.isPaused) {
-              player.isPaused = false
-              player.ref.play()
+          allPlayables.forEach { playable ->
+            playable.setVolume(playable.previousVolume)
+            if (playable.isPaused) {
+              playable.isPaused = false
+              playable.play()
             }
           }
         }
@@ -112,7 +116,7 @@ class AudioModule : Module() {
   }
 
   private fun shouldReleaseFocus(): Boolean {
-    return players.values.none { it.ref.isPlaying }
+    return allPlayables.none { it.isPlaying }
   }
 
   private fun requestAudioFocus() {
@@ -197,9 +201,9 @@ class AudioModule : Module() {
       if (!enabled) {
         releaseAudioFocus()
         runOnMain {
-          players.values.forEach {
-            if (it.ref.isPlaying) {
-              it.ref.pause()
+          allPlayables.forEach {
+            if (it.isPlaying) {
+              it.pause()
             }
           }
         }
@@ -210,17 +214,43 @@ 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)
     }
 
+    AsyncFunction("preload") Coroutine { source: AudioSource, _: Double ->
+      val uri = source.uri ?: return@Coroutine
+      val factory = when (uri.toUri().scheme) {
+        "http", "https" -> httpDataSourceFactory(source.headers)
+        else -> DefaultDataSource.Factory(context)
+      }
+      AudioPreloadManager.preload(uri, factory)
+    }
+
+    AsyncFunction("clearPreloadedSource") Coroutine { source: AudioSource ->
+      val uri = source.uri ?: return@Coroutine
+      AudioPreloadManager.clearSource(uri)
+    }
+
+    AsyncFunction("clearAllPreloadedSources") Coroutine { ->
+      AudioPreloadManager.clearAll()
+    }
+
+    AsyncFunction("getPreloadedSources") {
+      AudioPreloadManager.getPreloadedSources()
+    }
+
     OnActivityEntersBackground {
       if (!shouldPlayInBackground) {
         releaseAudioFocus()
-        players.values.forEach { player ->
-          if (player.ref.isPlaying) {
-            player.isPaused = true
-            player.ref.pause()
+        allPlayables.forEach { playable ->
+          if (playable.isPlaying) {
+            playable.isPaused = true
+            playable.pause()
           }
         }
       }
@@ -235,15 +265,14 @@ class AudioModule : Module() {
 
     OnActivityEntersForeground {
       if (!shouldPlayInBackground) {
-        val hasPlayersToResume = players.values.any { it.isPaused }
-        if (hasPlayersToResume) {
+        if (allPlayables.any { it.isPaused }) {
           requestAudioFocus()
         }
 
-        players.values.forEach { player ->
-          if (player.isPaused) {
-            player.isPaused = false
-            player.ref.play()
+        allPlayables.forEach { playable ->
+          if (playable.isPaused) {
+            playable.isPaused = false
+            playable.play()
           }
         }
       }
@@ -260,29 +289,34 @@ class AudioModule : Module() {
     }
 
     OnDestroy {
-      appContext.mainQueue.launch {
+      GlobalScope.launch(Dispatchers.Main) {
         releaseAudioFocus()
         players.values.forEach {
           it.ref.stop()
         }
 
+        playlists.values.forEach {
+          it.ref.stop()
+        }
+
         recorders.values.forEach {
           it.stopRecording()
         }
-
-        AudioControlsService.clearSession()
+        AudioPreloadManager.clearAll()
       }
     }
 
     Class(AudioPlayer::class) {
-      Constructor { source: AudioSource?, updateInterval: Double, keepAudioSessionActive: Boolean ->
+      Constructor { source: AudioSource?, updateInterval: Double, keepAudioSessionActive: Boolean, preferredForwardBufferDuration: Double ->
         val mediaSource = createMediaItem(source)
+        val bufferDurationMs = (preferredForwardBufferDuration * 1000).toLong()
         runOnMain {
           val player = AudioPlayer(
             context,
             appContext,
             mediaSource,
-            updateInterval
+            updateInterval,
+            bufferDurationMs
           )
           player.onPlaybackStateChange = { isPlaying ->
             if (!isPlaying && shouldReleaseFocus()) {
@@ -453,9 +487,7 @@ class AudioModule : Module() {
 
       Function("setPlaybackRate") { player: AudioPlayer, rate: Float ->
         appContext.mainQueue.launch {
-          val playbackRate = if (rate <= 0) 0.1f else min(rate, 2.0f)
-          val pitch = if (player.preservesPitch) 1f else playbackRate
-          player.ref.playbackParameters = PlaybackParameters(playbackRate, pitch)
+          player.setPlaybackRate(rate)
         }
       }
 
@@ -494,7 +526,7 @@ class AudioModule : Module() {
         recorder.getCurrentTimeSeconds()
       }
 
-      AsyncFunction("prepareToRecordAsync") { recorder: AudioRecorder, options: RecordingOptions? ->
+      AsyncFunction("prepareToRecordAsync") Coroutine { recorder: AudioRecorder, options: RecordingOptions? ->
         checkRecordingPermission()
         recorder.prepareRecording(options)
       }
@@ -550,6 +582,200 @@ class AudioModule : Module() {
         }
       }
     }
+
+    Class(AudioPlaylist::class) {
+      Constructor { sources: List<AudioSource>, updateInterval: Double, loop: LoopMode ->
+        runOnMain {
+          val playlist = AudioPlaylist(
+            context,
+            appContext,
+            sources,
+            updateInterval,
+            DefaultDataSource.Factory(context)
+          )
+          playlist.loopMode = loop
+          playlist.setMediaItemCreator { source ->
+            source.uri?.let { uriString ->
+              val uri = uriString.toUri()
+              when {
+                isRawResource(uri) -> {
+                  val file = getResourceName(uri, uriString)
+                  MediaItem.fromUri(getRawResourceURI(file))
+                }
+                else -> MediaItem.fromUri(uri)
+              }
+            }
+          }
+          playlist.loadInitialPlaylist()
+          playlist.onPlaybackStateChange = { isPlaying ->
+            if (!isPlaying && shouldReleaseFocus()) {
+              releaseAudioFocus()
+            }
+          }
+          playlists[playlist.id] = playlist
+          playlist
+        }
+      }
+
+      Property("id") { playlist ->
+        playlist.id
+      }
+
+      Property("currentIndex") { playlist ->
+        runOnMain {
+          playlist.currentTrackIndex
+        }
+      }
+
+      Property("trackCount") { playlist ->
+        runOnMain {
+          playlist.trackCount
+        }
+      }
+
+      Property("sources") { playlist ->
+        playlist.getSources()
+      }
+
+      Property("playing") { playlist ->
+        runOnMain {
+          playlist.ref.isPlaying
+        }
+      }
+
+      Property("muted") { playlist ->
+        playlist.isMuted
+      }.set { playlist, muted: Boolean? ->
+        val newMuted = muted ?: false
+        playlist.isMuted = newMuted
+        playlist.setVolume(if (newMuted) 0f else playlist.previousVolume)
+      }
+
+      Property("isLoaded") { playlist ->
+        runOnMain {
+          playlist.ref.playbackState == Player.STATE_READY
+        }
+      }
+
+      Property("isBuffering") { playlist ->
+        runOnMain {
+          playlist.ref.playbackState == Player.STATE_BUFFERING
+        }
+      }
+
+      Property("currentTime") { playlist ->
+        runOnMain {
+          playlist.currentTime
+        }
+      }
+
+      Property("duration") { playlist ->
+        runOnMain {
+          playlist.duration
+        }
+      }
+
+      Property("volume") { playlist ->
+        runOnMain {
+          playlist.ref.volume
+        }
+      }.set { playlist, volume: Float? ->
+        playlist.setVolume(volume)
+      }
+
+      Property("playbackRate") { playlist ->
+        runOnMain {
+          playlist.ref.playbackParameters.speed
+        }
+      }.set { playlist, rate: Float ->
+        appContext.mainQueue.launch {
+          playlist.setPlaybackRate(rate)
+        }
+      }
+
+      Property("loop") { playlist ->
+        playlist.loopMode.value
+      }.set { playlist, mode: LoopMode ->
+        runOnMain {
+          playlist.loopMode = mode
+        }
+      }
+
+      Property("currentStatus") { playlist ->
+        runOnMain {
+          playlist.currentStatus()
+        }
+      }
+
+      Function("play") { playlist: AudioPlaylist ->
+        if (!audioEnabled) {
+          Log.e(TAG, "Audio has been disabled. Re-enable to start playing")
+          return@Function
+        }
+        runOnMain {
+          if (!focusAcquired) {
+            requestAudioFocus()
+          }
+          playlist.ref.play()
+        }
+      }
+
+      Function("pause") { playlist: AudioPlaylist ->
+        runOnMain {
+          playlist.ref.pause()
+        }
+      }
+
+      Function("next") { playlist: AudioPlaylist ->
+        runOnMain {
+          playlist.next()
+        }
+      }
+
+      Function("previous") { playlist: AudioPlaylist ->
+        runOnMain {
+          playlist.previous()
+        }
+      }
+
+      Function("skipTo") { playlist: AudioPlaylist, index: Int ->
+        runOnMain {
+          playlist.skipTo(index)
+        }
+      }
+
+      AsyncFunction("seekTo") { playlist: AudioPlaylist, seconds: Double ->
+        playlist.seekTo(seconds)
+      }.runOnQueue(Queues.MAIN)
+
+      Function("add") { playlist: AudioPlaylist, source: AudioSource ->
+        runOnMain {
+          playlist.add(source)
+        }
+      }
+
+      Function("insert") { playlist: AudioPlaylist, source: AudioSource, index: Int ->
+        runOnMain {
+          playlist.insert(source, index)
+        }
+      }
+
+      Function("remove") { playlist: AudioPlaylist, index: Int ->
+        runOnMain {
+          playlist.remove(index)
+        }
+      }
+
+      Function("clear") { playlist: AudioPlaylist ->
+        runOnMain {
+          playlist.clear()
+        }
+      }
+
+      Function("destroy") { playlist: AudioPlaylist ->
+        playlists.remove(playlist.id)
+      }
+    }
   }
 
   private fun createMediaItem(source: AudioSource?): MediaSource? = source?.uri?.let { uriString ->
@@ -562,9 +788,14 @@ class AudioModule : Module() {
       else -> MediaItem.fromUri(uri)
     }
 
-    val factory = when (uri.scheme) {
-      "http", "https" -> httpDataSourceFactory(source.headers)
-      else -> DefaultDataSource.Factory(context)
+    val preloadedBytes = AudioPreloadManager.get(uriString)
+    val factory: DataSource.Factory = if (preloadedBytes != null) {
+      InMemoryDataSourceFactory(preloadedBytes)
+    } else {
+      when (uri.scheme) {
+        "http", "https" -> httpDataSourceFactory(source.headers)
+        else -> DefaultDataSource.Factory(context)
+      }
     }
     return buildMediaSourceFactory(factory, mediaItem)
   }