sezo-audio-engine 0.0.12 → 0.0.13

package/README.md

@@ -38,7 +38,7 @@ allprojects {
 Optionally pin the engine version in `android/gradle.properties`:
 
 ```properties
-sezoAudioEngineVersion=android-engine-v0.1.5
+sezoAudioEngineVersion=android-engine-v0.1.6
 ```
 
 If you want to build from source instead, include the local engine module in

package/android/build.gradle

@@ -38,13 +38,15 @@ android {
 dependencies {
   implementation "org.jetbrains.kotlin:kotlin-stdlib:1.9.0"
   implementation project(":expo-modules-core")
+  implementation "androidx.core:core-ktx:1.13.1"
+  implementation "androidx.media:media:1.7.0"
 
   // Link to the android-engine package when available, otherwise fall back to JitPack.
   def androidEngineProject = rootProject.findProject(":android-engine")
   if (androidEngineProject != null) {
     implementation androidEngineProject
   } else {
-    def sezoAudioEngineVersion = project.findProperty("sezoAudioEngineVersion") ?: "android-engine-v0.1.5"
+    def sezoAudioEngineVersion = project.findProperty("sezoAudioEngineVersion") ?: "android-engine-v0.1.6"
     implementation "com.github.Sepzie:SezoAudioEngine:${sezoAudioEngineVersion}"
   }
 }

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,11 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+  <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
+  <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />
+
+  <application>
+    <service
+      android:name=".MediaPlaybackService"
+      android:exported="false"
+      android:foregroundServiceType="mediaPlayback" />
+  </application>
+</manifest>

package/android/src/main/java/expo/modules/audioengine/AudioFocusManager.kt

@@ -0,0 +1,69 @@
+package expo.modules.audioengine
+
+import android.content.Context
+import android.media.AudioAttributes
+import android.media.AudioFocusRequest
+import android.media.AudioManager
+import android.os.Build
+
+internal class AudioFocusManager(
+  context: Context,
+  private val onAudioFocusChanged: (Int) -> Unit
+) {
+  private val audioManager = context.getSystemService(Context.AUDIO_SERVICE) as AudioManager
+  private val focusListener = AudioManager.OnAudioFocusChangeListener { change ->
+    onAudioFocusChanged(change)
+  }
+
+  private var focusRequest: AudioFocusRequest? = null
+  @Volatile
+  private var hasFocus = false
+
+  fun requestFocus(): Boolean {
+    if (hasFocus) {
+      return true
+    }
+
+    val result = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+      if (focusRequest == null) {
+        val attributes = AudioAttributes.Builder()
+          .setUsage(AudioAttributes.USAGE_MEDIA)
+          .setContentType(AudioAttributes.CONTENT_TYPE_MUSIC)
+          .build()
+        focusRequest = AudioFocusRequest.Builder(AudioManager.AUDIOFOCUS_GAIN)
+          .setAudioAttributes(attributes)
+          .setAcceptsDelayedFocusGain(false)
+          .setWillPauseWhenDucked(false)
+          .setOnAudioFocusChangeListener(focusListener)
+          .build()
+      }
+      audioManager.requestAudioFocus(focusRequest!!)
+    } else {
+      @Suppress("DEPRECATION")
+      audioManager.requestAudioFocus(
+        focusListener,
+        AudioManager.STREAM_MUSIC,
+        AudioManager.AUDIOFOCUS_GAIN
+      )
+    }
+
+    hasFocus = result == AudioManager.AUDIOFOCUS_REQUEST_GRANTED
+    return hasFocus
+  }
+
+  fun abandonFocus() {
+    if (!hasFocus) {
+      return
+    }
+
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+      focusRequest?.let { audioManager.abandonAudioFocusRequest(it) }
+    } else {
+      @Suppress("DEPRECATION")
+      audioManager.abandonAudioFocus(focusListener)
+    }
+    hasFocus = false
+  }
+
+  fun hasAudioFocus(): Boolean = hasFocus
+}

package/android/src/main/java/expo/modules/audioengine/BackgroundPlaybackBridge.kt

@@ -0,0 +1,40 @@
+package expo.modules.audioengine
+
+internal object BackgroundPlaybackBridge {
+  interface Controller {
+    fun play(): Boolean
+    fun pause()
+    fun stop()
+    fun seekTo(positionMs: Double)
+    fun isPlaying(): Boolean
+    fun getCurrentPositionMs(): Double
+    fun getDurationMs(): Double
+  }
+
+  @Volatile
+  private var controller: Controller? = null
+
+  fun setController(nextController: Controller?) {
+    controller = nextController
+  }
+
+  fun play(): Boolean = controller?.play() ?: false
+
+  fun pause() {
+    controller?.pause()
+  }
+
+  fun stop() {
+    controller?.stop()
+  }
+
+  fun seekTo(positionMs: Double) {
+    controller?.seekTo(positionMs)
+  }
+
+  fun isPlaying(): Boolean = controller?.isPlaying() ?: false
+
+  fun getCurrentPositionMs(): Double = controller?.getCurrentPositionMs() ?: 0.0
+
+  fun getDurationMs(): Double = controller?.getDurationMs() ?: 0.0
+}

package/android/src/main/java/expo/modules/audioengine/ExpoAudioEngineModule.kt

@@ -1,5 +1,7 @@
 package expo.modules.audioengine
 
+import android.media.AudioManager
+import android.os.Bundle
 import android.util.Log
 import com.sezo.audioengine.AudioEngine
 import expo.modules.kotlin.Promise
@@ -14,6 +16,40 @@ class ExpoAudioEngineModule : Module() {
   private val progressLogState = Collections.synchronizedMap(mutableMapOf<Long, Float>())
   private var lastExtractionJobId: Long? = null
   private var activeRecordingFormat: String = "aac"
+  private var wasPlayingBeforePause: Boolean = false
+  private var backgroundPlaybackEnabled: Boolean = false
+  private var shouldResumeAfterTransientFocusLoss: Boolean = false
+  private var volumeBeforeDuck: Float? = null
+  private var audioFocusManager: AudioFocusManager? = null
+  private val nowPlayingMetadata = mutableMapOf<String, Any?>()
+
+  private val backgroundController = object : BackgroundPlaybackBridge.Controller {
+    override fun play(): Boolean {
+      val engine = audioEngine ?: return false
+      return startPlaybackInternal(engine, fromSystem = true)
+    }
+
+    override fun pause() {
+      audioEngine?.let { pausePlaybackInternal(it, fromSystem = true) }
+    }
+
+    override fun stop() {
+      audioEngine?.let { stopPlaybackInternal(it, fromSystem = true, stopService = false) }
+    }
+
+    override fun seekTo(positionMs: Double) {
+      audioEngine?.seek(positionMs)
+      if (backgroundPlaybackEnabled) {
+        syncBackgroundService(isPlaying = audioEngine?.isPlaying() ?: false)
+      }
+    }
+
+    override fun isPlaying(): Boolean = audioEngine?.isPlaying() ?: false
+
+    override fun getCurrentPositionMs(): Double = audioEngine?.getCurrentPosition() ?: 0.0
+
+    override fun getDurationMs(): Double = audioEngine?.getDuration() ?: 0.0
+  }
 
   private data class PendingExtraction(
     val promise: Promise,
@@ -27,6 +63,84 @@ class ExpoAudioEngineModule : Module() {
   override fun definition() = ModuleDefinition {
     Name("ExpoAudioEngineModule")
 
+    OnActivityEntersBackground {
+      Log.d(TAG, "Activity entering background")
+      val engine = audioEngine ?: return@OnActivityEntersBackground
+
+      if (backgroundPlaybackEnabled) {
+        Log.d(TAG, "Background playback enabled, keeping engine running")
+        return@OnActivityEntersBackground
+      }
+
+      wasPlayingBeforePause = engine.isPlaying()
+      if (wasPlayingBeforePause) {
+        Log.d(TAG, "Pausing engine before background (was playing)")
+        pausePlaybackInternal(engine, fromSystem = true, keepAudioFocus = false)
+        sendEvent("engineStateChanged", mapOf(
+          "reason" to "backgrounded",
+          "wasPlaying" to true
+        ))
+      }
+    }
+
+    OnActivityEntersForeground {
+      Log.d(TAG, "Activity entering foreground")
+      val engine = audioEngine ?: return@OnActivityEntersForeground
+
+      // Check stream health on resume
+      if (!engine.isStreamHealthy()) {
+        Log.w(TAG, "Stream unhealthy on resume, attempting restart")
+        val restarted = engine.restartStream()
+        sendEvent("engineStateChanged", mapOf(
+          "reason" to "streamRestarted",
+          "success" to restarted
+        ))
+        if (!restarted) {
+          Log.e(TAG, "Failed to restart stream on resume")
+          sendEvent("error", mapOf(
+            "code" to "STREAM_DISCONNECTED",
+            "message" to "Audio stream could not be recovered after returning to foreground"
+          ))
+          return@OnActivityEntersForeground
+        }
+      }
+
+      // Resume playback if it was playing before backgrounding
+      if (wasPlayingBeforePause && !backgroundPlaybackEnabled) {
+        Log.d(TAG, "Resuming playback after returning to foreground")
+        val resumed = startPlaybackInternal(engine, fromSystem = true)
+        wasPlayingBeforePause = false
+        sendEvent(
+          "engineStateChanged",
+          mapOf(
+            "reason" to "resumed",
+            "wasPlaying" to true,
+            "success" to resumed
+          )
+        )
+      }
+    }
+
+    OnDestroy {
+      Log.d(TAG, "Module being destroyed, releasing engine")
+      teardownBackgroundPlayback(clearMetadata = true, stopService = true)
+      audioEngine?.let { engine ->
+        synchronized(pendingExtractions) {
+          pendingExtractions.keys.forEach { engine.cancelExtraction(it) }
+          pendingExtractions.clear()
+        }
+        progressLogState.clear()
+        engine.setExtractionProgressListener(null)
+        engine.setExtractionCompletionListener(null)
+        engine.setPlaybackStateListener(null)
+        engine.release()
+        engine.destroy()
+      }
+      BackgroundPlaybackBridge.setController(null)
+      audioEngine = null
+      loadedTrackIds.clear()
+    }
+
     AsyncFunction("initialize") { config: Map<String, Any?> ->
       Log.d(TAG, "Initialize called with config: $config")
 
@@ -40,6 +154,9 @@ class ExpoAudioEngineModule : Module() {
         throw Exception("Failed to initialize audio engine")
       }
 
+      ensureAudioFocusManager()
+      BackgroundPlaybackBridge.setController(backgroundController)
+
       audioEngine?.setPlaybackStateListener { state, positionMs, durationMs ->
         sendEvent(
           "playbackStateChange",
@@ -49,6 +166,7 @@ class ExpoAudioEngineModule : Module() {
             "durationMs" to durationMs
           )
         )
+        handlePlaybackStateChange(state)
       }
 
       Log.d(TAG, "Audio engine initialized successfully")
@@ -56,6 +174,7 @@ class ExpoAudioEngineModule : Module() {
 
     AsyncFunction("release") {
       Log.d(TAG, "Release called")
+      teardownBackgroundPlayback(clearMetadata = false, stopService = true)
       audioEngine?.let { engine ->
         synchronized(pendingExtractions) {
           pendingExtractions.keys.forEach { engine.cancelExtraction(it) }
@@ -68,6 +187,7 @@ class ExpoAudioEngineModule : Module() {
         engine.release()
         engine.destroy()
       }
+      BackgroundPlaybackBridge.setController(null)
       audioEngine = null
       loadedTrackIds.clear()
       Log.d(TAG, "Audio engine released")
@@ -115,21 +235,23 @@ class ExpoAudioEngineModule : Module() {
       loadedTrackIds.map { mapOf("id" to it) }
     }
 
-    Function("play") {
+    AsyncFunction("play") {
       val engine = audioEngine ?: throw Exception("Engine not initialized")
-      engine.play()
+      if (!startPlaybackInternal(engine, fromSystem = false)) {
+        throw Exception("Failed to start playback")
+      }
       Log.d(TAG, "Playback started")
     }
 
     Function("pause") {
       val engine = audioEngine ?: throw Exception("Engine not initialized")
-      engine.pause()
+      pausePlaybackInternal(engine, fromSystem = false)
       Log.d(TAG, "Playback paused")
     }
 
     Function("stop") {
       val engine = audioEngine ?: throw Exception("Engine not initialized")
-      engine.stop()
+      stopPlaybackInternal(engine, fromSystem = false)
       Log.d(TAG, "Playback stopped")
     }
 
@@ -404,9 +526,35 @@ class ExpoAudioEngineModule : Module() {
     Function("getOutputLevel") { 0.0 }
     Function("getTrackLevel") { _trackId: String -> 0.0 }
 
-    AsyncFunction("enableBackgroundPlayback") { _metadata: Map<String, Any?> -> }
-    Function("updateNowPlayingInfo") { _metadata: Map<String, Any?> -> }
-    AsyncFunction("disableBackgroundPlayback") { }
+    AsyncFunction("enableBackgroundPlayback") { metadata: Map<String, Any?> ->
+      val engine = audioEngine ?: throw Exception("Engine not initialized")
+      backgroundPlaybackEnabled = true
+      mergeNowPlayingMetadata(metadata)
+      ensureAudioFocusManager()
+      BackgroundPlaybackBridge.setController(backgroundController)
+      if (engine.isPlaying()) {
+        requestAudioFocus()
+      }
+      syncBackgroundService(engine.isPlaying())
+      sendEvent("engineStateChanged", mapOf("reason" to "backgroundPlaybackEnabled"))
+    }
+    Function("updateNowPlayingInfo") { metadata: Map<String, Any?> ->
+      mergeNowPlayingMetadata(metadata)
+      if (backgroundPlaybackEnabled) {
+        syncBackgroundService(audioEngine?.isPlaying() ?: false)
+      }
+    }
+    AsyncFunction("disableBackgroundPlayback") {
+      backgroundPlaybackEnabled = false
+      shouldResumeAfterTransientFocusLoss = false
+      volumeBeforeDuck = null
+      stopBackgroundService()
+      if (!(audioEngine?.isPlaying() ?: false)) {
+        abandonAudioFocus()
+      }
+      nowPlayingMetadata.clear()
+      sendEvent("engineStateChanged", mapOf("reason" to "backgroundPlaybackDisabled"))
+    }
 
     Events(
       "playbackStateChange",
@@ -418,6 +566,7 @@ class ExpoAudioEngineModule : Module() {
       "recordingStopped",
       "extractionProgress",
       "extractionComplete",
+      "engineStateChanged",
       "error"
     )
   }
@@ -527,6 +676,253 @@ class ExpoAudioEngineModule : Module() {
     }
   }
 
+  private fun startPlaybackInternal(engine: AudioEngine, fromSystem: Boolean): Boolean {
+    if (!engine.isStreamHealthy()) {
+      Log.w(TAG, "Stream unhealthy before play, attempting restart")
+      if (!engine.restartStream()) {
+        if (!fromSystem) {
+          sendEvent(
+            "error",
+            mapOf(
+              "code" to "STREAM_DISCONNECTED",
+              "message" to "Audio stream is disconnected and could not be recovered"
+            )
+          )
+        }
+        return false
+      }
+    }
+
+    if (!requestAudioFocus()) {
+      Log.w(TAG, "Audio focus request denied")
+      if (!fromSystem) {
+        sendEvent(
+          "error",
+          mapOf(
+            "code" to "AUDIO_FOCUS_DENIED",
+            "message" to "Could not gain audio focus for playback"
+          )
+        )
+      }
+      return false
+    }
+
+    shouldResumeAfterTransientFocusLoss = false
+    restoreDuckedVolumeIfNeeded(engine)
+    engine.play()
+
+    if (backgroundPlaybackEnabled) {
+      syncBackgroundService(true)
+    }
+    return true
+  }
+
+  private fun pausePlaybackInternal(
+    engine: AudioEngine,
+    fromSystem: Boolean,
+    keepAudioFocus: Boolean = false
+  ) {
+    engine.pause()
+    shouldResumeAfterTransientFocusLoss = false
+    restoreDuckedVolumeIfNeeded(engine)
+
+    if (!keepAudioFocus) {
+      abandonAudioFocus()
+    }
+
+    if (backgroundPlaybackEnabled) {
+      syncBackgroundService(false)
+    }
+
+    if (fromSystem) {
+      sendEvent("engineStateChanged", mapOf("reason" to "pausedFromSystem"))
+    }
+  }
+
+  private fun stopPlaybackInternal(
+    engine: AudioEngine,
+    fromSystem: Boolean,
+    stopService: Boolean = true
+  ) {
+    engine.stop()
+    shouldResumeAfterTransientFocusLoss = false
+    restoreDuckedVolumeIfNeeded(engine)
+    abandonAudioFocus()
+
+    if (backgroundPlaybackEnabled && stopService) {
+      stopBackgroundService()
+    }
+
+    if (fromSystem) {
+      sendEvent("engineStateChanged", mapOf("reason" to "stoppedFromSystem"))
+    }
+  }
+
+  private fun handlePlaybackStateChange(state: String) {
+    if (!backgroundPlaybackEnabled) {
+      return
+    }
+
+    when (state) {
+      "playing" -> {
+        requestAudioFocus()
+        syncBackgroundService(true)
+      }
+      "paused" -> syncBackgroundService(false)
+      "stopped" -> stopBackgroundService()
+    }
+  }
+
+  private fun ensureAudioFocusManager(): AudioFocusManager? {
+    if (audioFocusManager != null) {
+      return audioFocusManager
+    }
+
+    val context = appContext.reactContext?.applicationContext ?: run {
+      Log.w(TAG, "React context unavailable; audio focus manager not initialized")
+      return null
+    }
+
+    audioFocusManager = AudioFocusManager(context) { focusChange ->
+      handleAudioFocusChange(focusChange)
+    }
+    return audioFocusManager
+  }
+
+  private fun requestAudioFocus(): Boolean {
+    return ensureAudioFocusManager()?.requestFocus() ?: false
+  }
+
+  private fun abandonAudioFocus() {
+    audioFocusManager?.abandonFocus()
+  }
+
+  private fun handleAudioFocusChange(focusChange: Int) {
+    val engine = audioEngine ?: return
+    when (focusChange) {
+      AudioManager.AUDIOFOCUS_GAIN -> {
+        restoreDuckedVolumeIfNeeded(engine)
+        if (shouldResumeAfterTransientFocusLoss) {
+          shouldResumeAfterTransientFocusLoss = false
+          startPlaybackInternal(engine, fromSystem = true)
+        }
+      }
+      AudioManager.AUDIOFOCUS_LOSS_TRANSIENT -> {
+        if (engine.isPlaying()) {
+          shouldResumeAfterTransientFocusLoss = true
+          pausePlaybackInternal(engine, fromSystem = true, keepAudioFocus = true)
+          sendEvent("engineStateChanged", mapOf("reason" to "audioFocusLossTransient"))
+        }
+      }
+      AudioManager.AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK -> {
+        if (volumeBeforeDuck == null) {
+          volumeBeforeDuck = engine.getMasterVolume()
+          val duckedVolume = (volumeBeforeDuck!! * 0.3f).coerceAtLeast(0.05f)
+          engine.setMasterVolume(duckedVolume)
+          sendEvent(
+            "engineStateChanged",
+            mapOf(
+              "reason" to "audioFocusDuck",
+              "volume" to duckedVolume.toDouble()
+            )
+          )
+        }
+      }
+      AudioManager.AUDIOFOCUS_LOSS -> {
+        shouldResumeAfterTransientFocusLoss = false
+        if (engine.isPlaying()) {
+          pausePlaybackInternal(engine, fromSystem = true)
+          sendEvent("engineStateChanged", mapOf("reason" to "audioFocusLoss"))
+        } else {
+          abandonAudioFocus()
+        }
+        restoreDuckedVolumeIfNeeded(engine)
+      }
+    }
+  }
+
+  private fun restoreDuckedVolumeIfNeeded(engine: AudioEngine) {
+    val previousVolume = volumeBeforeDuck ?: return
+    engine.setMasterVolume(previousVolume)
+    volumeBeforeDuck = null
+  }
+
+  private fun mergeNowPlayingMetadata(metadata: Map<String, Any?>) {
+    metadata.forEach { (key, value) ->
+      if (value == null) {
+        nowPlayingMetadata.remove(key)
+      } else {
+        nowPlayingMetadata[key] = value
+      }
+    }
+  }
+
+  private fun syncBackgroundService(isPlaying: Boolean) {
+    if (!backgroundPlaybackEnabled) {
+      return
+    }
+
+    val context = appContext.reactContext?.applicationContext ?: return
+    val metadataBundle = mapToBundle(nowPlayingMetadata)
+    MediaPlaybackService.sync(context, metadataBundle, isPlaying)
+  }
+
+  private fun stopBackgroundService() {
+    val context = appContext.reactContext?.applicationContext ?: return
+    MediaPlaybackService.stop(context)
+  }
+
+  private fun teardownBackgroundPlayback(clearMetadata: Boolean, stopService: Boolean) {
+    backgroundPlaybackEnabled = false
+    shouldResumeAfterTransientFocusLoss = false
+    volumeBeforeDuck = null
+    if (stopService) {
+      stopBackgroundService()
+    }
+    if (clearMetadata) {
+      nowPlayingMetadata.clear()
+    }
+    abandonAudioFocus()
+  }
+
+  private fun mapToBundle(map: Map<String, Any?>): Bundle {
+    val bundle = Bundle()
+    map.forEach { (key, value) ->
+      when (value) {
+        null -> Unit
+        is String -> bundle.putString(key, value)
+        is Boolean -> bundle.putBoolean(key, value)
+        is Int -> bundle.putInt(key, value)
+        is Long -> bundle.putLong(key, value)
+        is Float -> bundle.putFloat(key, value)
+        is Double -> bundle.putDouble(key, value)
+        is Number -> {
+          val numberAsDouble = value.toDouble()
+          val isIntegral = numberAsDouble % 1.0 == 0.0
+          if (isIntegral &&
+            numberAsDouble >= Long.MIN_VALUE.toDouble() &&
+            numberAsDouble <= Long.MAX_VALUE.toDouble()
+          ) {
+            bundle.putLong(key, numberAsDouble.toLong())
+          } else {
+            bundle.putDouble(key, numberAsDouble)
+          }
+        }
+        is Map<*, *> -> {
+          val child = mutableMapOf<String, Any?>()
+          value.forEach { (nestedKey, nestedValue) ->
+            if (nestedKey is String) {
+              child[nestedKey] = nestedValue
+            }
+          }
+          bundle.putBundle(key, mapToBundle(child))
+        }
+        else -> bundle.putString(key, value.toString())
+      }
+    }
+    return bundle
+  }
+
   private fun getCacheDir(): String {
     return appContext.reactContext?.cacheDir?.absolutePath ?: "/tmp"
   }

package/android/src/main/java/expo/modules/audioengine/MediaPlaybackService.kt

@@ -0,0 +1,556 @@
+package expo.modules.audioengine
+
+import android.app.Notification
+import android.app.NotificationChannel
+import android.app.NotificationManager
+import android.app.PendingIntent
+import android.app.Service
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import android.content.IntentFilter
+import android.graphics.Bitmap
+import android.graphics.BitmapFactory
+import android.graphics.Color
+import android.media.AudioManager
+import android.net.Uri
+import android.os.Build
+import android.os.Bundle
+import android.os.IBinder
+import android.util.Log
+import androidx.core.app.NotificationCompat
+import androidx.core.app.NotificationManagerCompat
+import androidx.core.content.ContextCompat
+import androidx.media.app.NotificationCompat as MediaStyleNotificationCompat
+import android.support.v4.media.MediaMetadataCompat
+import android.support.v4.media.session.MediaSessionCompat
+import android.support.v4.media.session.PlaybackStateCompat
+
+internal class MediaPlaybackService : Service() {
+  private lateinit var mediaSession: MediaSessionCompat
+  private val notificationManager by lazy { NotificationManagerCompat.from(this) }
+
+  private var metadata = NowPlayingMetadata()
+  private var cardOptions = PlaybackCardOptions()
+  private var isPlaying = false
+  private var isForeground = false
+  private var noisyReceiverRegistered = false
+
+  private val noisyReceiver = object : BroadcastReceiver() {
+    override fun onReceive(context: Context?, intent: Intent?) {
+      if (intent?.action == AudioManager.ACTION_AUDIO_BECOMING_NOISY) {
+        handlePause()
+        publishState()
+      }
+    }
+  }
+
+  override fun onCreate() {
+    super.onCreate()
+    createNotificationChannel()
+    mediaSession = MediaSessionCompat(this, TAG).apply {
+      setFlags(
+        MediaSessionCompat.FLAG_HANDLES_MEDIA_BUTTONS or
+          MediaSessionCompat.FLAG_HANDLES_TRANSPORT_CONTROLS
+      )
+      setCallback(object : MediaSessionCompat.Callback() {
+        override fun onPlay() {
+          handlePlay()
+          publishState()
+        }
+
+        override fun onPause() {
+          handlePause()
+          publishState()
+        }
+
+        override fun onStop() {
+          handleStop()
+          publishState()
+        }
+
+        override fun onSeekTo(pos: Long) {
+          BackgroundPlaybackBridge.seekTo(pos.toDouble())
+          publishState()
+        }
+
+        override fun onSkipToPrevious() {
+          handleSeekBy(-cardOptions.seekStepMs)
+          publishState()
+        }
+
+        override fun onSkipToNext() {
+          handleSeekBy(cardOptions.seekStepMs)
+          publishState()
+        }
+      })
+      isActive = true
+    }
+    updatePlaybackState()
+  }
+
+  override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
+    when (intent?.action) {
+      ACTION_PLAY -> handlePlay()
+      ACTION_PAUSE -> handlePause()
+      ACTION_TOGGLE -> if (isPlaying) handlePause() else handlePlay()
+      ACTION_STOP -> handleStop()
+      ACTION_PREVIOUS -> handleSeekBy(-cardOptions.seekStepMs)
+      ACTION_NEXT -> handleSeekBy(cardOptions.seekStepMs)
+      ACTION_STOP_SERVICE -> {
+        stopSelf()
+        return START_NOT_STICKY
+      }
+      ACTION_UPDATE, null -> {
+        applyMetadataBundle(intent?.getBundleExtra(EXTRA_METADATA))
+        if (intent?.hasExtra(EXTRA_IS_PLAYING) == true) {
+          isPlaying = intent.getBooleanExtra(EXTRA_IS_PLAYING, isPlaying)
+        }
+      }
+      else -> Log.w(TAG, "Unknown service action: ${intent.action}")
+    }
+
+    publishState()
+    return START_STICKY
+  }
+
+  override fun onDestroy() {
+    super.onDestroy()
+    unregisterNoisyReceiver()
+    if (isForeground) {
+      stopForegroundCompat(removeNotification = true)
+      isForeground = false
+    } else {
+      notificationManager.cancel(NOTIFICATION_ID)
+    }
+    mediaSession.release()
+  }
+
+  override fun onBind(intent: Intent?): IBinder? = null
+
+  private fun handlePlay() {
+    isPlaying = BackgroundPlaybackBridge.play()
+  }
+
+  private fun handlePause() {
+    BackgroundPlaybackBridge.pause()
+    isPlaying = false
+  }
+
+  private fun handleStop() {
+    BackgroundPlaybackBridge.stop()
+    isPlaying = false
+  }
+
+  private fun handleSeekBy(deltaMs: Long) {
+    val duration = BackgroundPlaybackBridge.getDurationMs().coerceAtLeast(0.0)
+    val current = BackgroundPlaybackBridge.getCurrentPositionMs().coerceAtLeast(0.0)
+    val unclampedTarget = current + deltaMs.toDouble()
+    val maxPosition = if (duration > 0.0) duration else Double.MAX_VALUE
+    val target = unclampedTarget.coerceIn(0.0, maxPosition)
+    BackgroundPlaybackBridge.seekTo(target)
+  }
+
+  private fun publishState() {
+    isPlaying = BackgroundPlaybackBridge.isPlaying()
+    updatePlaybackState()
+    mediaSession.setMetadata(buildMediaMetadata())
+
+    val notification = buildNotification()
+    if (isPlaying) {
+      registerNoisyReceiver()
+      if (!isForeground) {
+        startForeground(NOTIFICATION_ID, notification)
+        isForeground = true
+      } else {
+        notificationManager.notify(NOTIFICATION_ID, notification)
+      }
+    } else {
+      unregisterNoisyReceiver()
+      if (isForeground) {
+        stopForegroundCompat(removeNotification = false)
+        isForeground = false
+      }
+      notificationManager.notify(NOTIFICATION_ID, notification)
+    }
+  }
+
+  private fun stopForegroundCompat(removeNotification: Boolean) {
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.N) {
+      stopForeground(
+        if (removeNotification) {
+          Service.STOP_FOREGROUND_REMOVE
+        } else {
+          Service.STOP_FOREGROUND_DETACH
+        }
+      )
+    } else {
+      @Suppress("DEPRECATION")
+      stopForeground(removeNotification)
+    }
+  }
+
+  private fun updatePlaybackState() {
+    val actions = PlaybackStateCompat.ACTION_PLAY or
+      PlaybackStateCompat.ACTION_PAUSE or
+      PlaybackStateCompat.ACTION_PLAY_PAUSE or
+      PlaybackStateCompat.ACTION_STOP or
+      PlaybackStateCompat.ACTION_SEEK_TO
+
+    val state = if (isPlaying) {
+      PlaybackStateCompat.STATE_PLAYING
+    } else {
+      PlaybackStateCompat.STATE_PAUSED
+    }
+
+    mediaSession.setPlaybackState(
+      PlaybackStateCompat.Builder()
+        .setActions(actions)
+        .setState(
+          state,
+          BackgroundPlaybackBridge.getCurrentPositionMs().toLong(),
+          if (isPlaying) 1.0f else 0.0f
+        )
+        .build()
+    )
+  }
+
+  private fun buildMediaMetadata(): MediaMetadataCompat {
+    val builder = MediaMetadataCompat.Builder()
+      .putString(MediaMetadataCompat.METADATA_KEY_TITLE, metadata.title)
+      .putString(MediaMetadataCompat.METADATA_KEY_ARTIST, metadata.artist ?: "")
+      .putString(MediaMetadataCompat.METADATA_KEY_ALBUM, metadata.album ?: "")
+      .putLong(
+        MediaMetadataCompat.METADATA_KEY_DURATION,
+        BackgroundPlaybackBridge.getDurationMs().toLong()
+      )
+
+    resolveArtworkBitmap()?.let { bitmap ->
+      builder.putBitmap(MediaMetadataCompat.METADATA_KEY_ART, bitmap)
+      builder.putBitmap(MediaMetadataCompat.METADATA_KEY_ALBUM_ART, bitmap)
+      builder.putBitmap(MediaMetadataCompat.METADATA_KEY_DISPLAY_ICON, bitmap)
+    }
+    return builder.build()
+  }
+
+  private fun buildNotification(): Notification {
+    val style = MediaStyleNotificationCompat.MediaStyle()
+      .setMediaSession(mediaSession.sessionToken)
+
+    val builder = NotificationCompat.Builder(this, CHANNEL_ID)
+      .setSmallIcon(resolveSmallIconResId())
+      .setContentTitle(metadata.title.ifBlank { "Audio" })
+      .setContentText(metadata.artist ?: "")
+      .setSubText(metadata.album)
+      .setVisibility(NotificationCompat.VISIBILITY_PUBLIC)
+      .setOnlyAlertOnce(true)
+      .setOngoing(isPlaying)
+      .setShowWhen(false)
+      .setStyle(style)
+
+    buildContentIntent()?.let { builder.setContentIntent(it) }
+    builder.setDeleteIntent(buildServicePendingIntent(ACTION_STOP))
+
+    resolveArtworkBitmap()?.let { builder.setLargeIcon(it) }
+    cardOptions.accentColor?.let { color ->
+      builder.setColorized(true)
+      builder.setColor(color)
+    }
+
+    val compactActions = mutableListOf<Int>()
+    var actionIndex = 0
+
+    if (cardOptions.showPrevious) {
+      builder.addAction(
+        android.R.drawable.ic_media_previous,
+        "Back",
+        buildServicePendingIntent(ACTION_PREVIOUS)
+      )
+      compactActions.add(actionIndex)
+      actionIndex++
+    }
+
+    val playPauseAction = if (isPlaying) ACTION_PAUSE else ACTION_PLAY
+    val playPauseIcon = if (isPlaying) android.R.drawable.ic_media_pause else android.R.drawable.ic_media_play
+    val playPauseLabel = if (isPlaying) "Pause" else "Play"
+    builder.addAction(playPauseIcon, playPauseLabel, buildServicePendingIntent(playPauseAction))
+    compactActions.add(actionIndex)
+    actionIndex++
+
+    if (cardOptions.showNext) {
+      builder.addAction(
+        android.R.drawable.ic_media_next,
+        "Forward",
+        buildServicePendingIntent(ACTION_NEXT)
+      )
+      compactActions.add(actionIndex)
+      actionIndex++
+    }
+
+    if (cardOptions.showStop) {
+      builder.addAction(
+        android.R.drawable.ic_menu_close_clear_cancel,
+        "Stop",
+        buildServicePendingIntent(ACTION_STOP)
+      )
+    }
+
+    style.setShowActionsInCompactView(*compactActions.take(3).toIntArray())
+    return builder.build()
+  }
+
+  private fun buildServicePendingIntent(action: String): PendingIntent {
+    val intent = Intent(this, MediaPlaybackService::class.java).apply { this.action = action }
+    val flags = PendingIntent.FLAG_UPDATE_CURRENT or
+      (if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) PendingIntent.FLAG_IMMUTABLE else 0)
+    return PendingIntent.getService(this, action.hashCode(), intent, flags)
+  }
+
+  private fun buildContentIntent(): PendingIntent? {
+    val launchIntent = packageManager.getLaunchIntentForPackage(packageName) ?: return null
+    launchIntent.flags = Intent.FLAG_ACTIVITY_SINGLE_TOP or Intent.FLAG_ACTIVITY_CLEAR_TOP
+    val flags = PendingIntent.FLAG_UPDATE_CURRENT or
+      (if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) PendingIntent.FLAG_IMMUTABLE else 0)
+    return PendingIntent.getActivity(this, 1001, launchIntent, flags)
+  }
+
+  private fun applyMetadataBundle(bundle: Bundle?) {
+    if (bundle == null) {
+      return
+    }
+
+    bundle.getString(KEY_TITLE)?.let { metadata.title = it }
+    if (bundle.containsKey(KEY_ARTIST)) {
+      metadata.artist = bundle.getString(KEY_ARTIST)
+    }
+    if (bundle.containsKey(KEY_ALBUM)) {
+      metadata.album = bundle.getString(KEY_ALBUM)
+    }
+    if (bundle.containsKey(KEY_ARTWORK)) {
+      metadata.artwork = bundle.getString(KEY_ARTWORK)
+    }
+    if (bundle.containsKey(KEY_LOGO)) {
+      metadata.logo = bundle.getString(KEY_LOGO)
+    }
+
+    val playbackCardBundle = bundle.getBundle(KEY_PLAYBACK_CARD)
+    if (playbackCardBundle != null) {
+      applyPlaybackCardBundle(playbackCardBundle)
+    }
+  }
+
+  private fun applyPlaybackCardBundle(bundle: Bundle) {
+    if (bundle.containsKey(KEY_CARD_SMALL_ICON)) {
+      cardOptions.smallIcon = bundle.getString(KEY_CARD_SMALL_ICON)
+    }
+    if (bundle.containsKey(KEY_CARD_SHOW_PREVIOUS)) {
+      cardOptions.showPrevious = bundle.getBoolean(KEY_CARD_SHOW_PREVIOUS)
+    }
+    if (bundle.containsKey(KEY_CARD_SHOW_NEXT)) {
+      cardOptions.showNext = bundle.getBoolean(KEY_CARD_SHOW_NEXT)
+    }
+    if (bundle.containsKey(KEY_CARD_SHOW_STOP)) {
+      cardOptions.showStop = bundle.getBoolean(KEY_CARD_SHOW_STOP)
+    }
+    if (bundle.containsKey(KEY_CARD_SEEK_STEP_MS)) {
+      val seekValue = bundle.get(KEY_CARD_SEEK_STEP_MS)
+      val seekStepMs = when (seekValue) {
+        is Long -> seekValue
+        is Int -> seekValue.toLong()
+        is Double -> seekValue.toLong()
+        is Float -> seekValue.toLong()
+        is String -> seekValue.toLongOrNull()
+        is Number -> seekValue.toLong()
+        else -> null
+      }
+      if (seekStepMs != null) {
+        cardOptions.seekStepMs = seekStepMs.coerceAtLeast(1000L)
+      }
+    }
+    if (bundle.containsKey(KEY_CARD_ACCENT_COLOR)) {
+      cardOptions.accentColor = parseColor(bundle.get(KEY_CARD_ACCENT_COLOR))
+    }
+  }
+
+  private fun parseColor(value: Any?): Int? {
+    return when (value) {
+      is Int -> value
+      is Long -> value.toInt()
+      is Double -> value.toInt()
+      is Float -> value.toInt()
+      is String -> try {
+        Color.parseColor(value)
+      } catch (_: IllegalArgumentException) {
+        null
+      }
+      else -> null
+    }
+  }
+
+  private fun resolveArtworkBitmap(): Bitmap? {
+    val artworkValue = metadata.artwork ?: metadata.logo ?: return null
+    return decodeBitmapFromString(artworkValue)
+  }
+
+  private fun decodeBitmapFromString(value: String): Bitmap? {
+    val path = when {
+      value.startsWith("file://") -> Uri.parse(value).path
+      value.startsWith("/") -> value
+      else -> null
+    }
+
+    if (!path.isNullOrBlank()) {
+      return BitmapFactory.decodeFile(path)
+    }
+
+    val resId = resolveResourceId(value)
+    if (resId != 0) {
+      return BitmapFactory.decodeResource(resources, resId)
+    }
+    return null
+  }
+
+  private fun resolveSmallIconResId(): Int {
+    val customIconName = cardOptions.smallIcon ?: metadata.logo
+    if (!customIconName.isNullOrBlank()) {
+      val customResId = resolveResourceId(customIconName)
+      if (customResId != 0) {
+        return customResId
+      }
+    }
+
+    val appIcon = applicationInfo.icon
+    if (appIcon != 0) {
+      return appIcon
+    }
+    return android.R.drawable.ic_media_play
+  }
+
+  private fun resolveResourceId(name: String): Int {
+    val cleaned = name.substringAfterLast("/").substringBeforeLast(".")
+    val drawable = resources.getIdentifier(cleaned, "drawable", packageName)
+    if (drawable != 0) {
+      return drawable
+    }
+    return resources.getIdentifier(cleaned, "mipmap", packageName)
+  }
+
+  private fun createNotificationChannel() {
+    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) {
+      return
+    }
+    val manager = getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
+    if (manager.getNotificationChannel(CHANNEL_ID) != null) {
+      return
+    }
+
+    val channel = NotificationChannel(
+      CHANNEL_ID,
+      CHANNEL_NAME,
+      NotificationManager.IMPORTANCE_LOW
+    ).apply {
+      description = CHANNEL_DESCRIPTION
+      lockscreenVisibility = Notification.VISIBILITY_PUBLIC
+    }
+    manager.createNotificationChannel(channel)
+  }
+
+  private fun registerNoisyReceiver() {
+    if (noisyReceiverRegistered) {
+      return
+    }
+    registerReceiver(noisyReceiver, IntentFilter(AudioManager.ACTION_AUDIO_BECOMING_NOISY))
+    noisyReceiverRegistered = true
+  }
+
+  private fun unregisterNoisyReceiver() {
+    if (!noisyReceiverRegistered) {
+      return
+    }
+    try {
+      unregisterReceiver(noisyReceiver)
+    } catch (_: IllegalArgumentException) {
+      // Receiver was already unregistered.
+    }
+    noisyReceiverRegistered = false
+  }
+
+  private data class NowPlayingMetadata(
+    var title: String = "Audio",
+    var artist: String? = null,
+    var album: String? = null,
+    var artwork: String? = null,
+    var logo: String? = null
+  )
+
+  private data class PlaybackCardOptions(
+    var smallIcon: String? = null,
+    var accentColor: Int? = null,
+    var showPrevious: Boolean = false,
+    var showNext: Boolean = false,
+    var showStop: Boolean = true,
+    var seekStepMs: Long = 15000L
+  )
+
+  companion object {
+    private const val TAG = "MediaPlaybackService"
+    private const val CHANNEL_ID = "sezo_audio_playback"
+    private const val CHANNEL_NAME = "Audio playback"
+    private const val CHANNEL_DESCRIPTION = "Playback controls"
+    private const val NOTIFICATION_ID = 7342
+
+    const val ACTION_UPDATE = "expo.modules.audioengine.action.UPDATE"
+    const val ACTION_PLAY = "expo.modules.audioengine.action.PLAY"
+    const val ACTION_PAUSE = "expo.modules.audioengine.action.PAUSE"
+    const val ACTION_TOGGLE = "expo.modules.audioengine.action.TOGGLE"
+    const val ACTION_STOP = "expo.modules.audioengine.action.STOP"
+    const val ACTION_PREVIOUS = "expo.modules.audioengine.action.PREVIOUS"
+    const val ACTION_NEXT = "expo.modules.audioengine.action.NEXT"
+    const val ACTION_STOP_SERVICE = "expo.modules.audioengine.action.STOP_SERVICE"
+
+    private const val EXTRA_METADATA = "extra_metadata"
+    private const val EXTRA_IS_PLAYING = "extra_is_playing"
+
+    private const val KEY_TITLE = "title"
+    private const val KEY_ARTIST = "artist"
+    private const val KEY_ALBUM = "album"
+    private const val KEY_ARTWORK = "artwork"
+    private const val KEY_LOGO = "logo"
+    private const val KEY_PLAYBACK_CARD = "playbackCard"
+    private const val KEY_CARD_SMALL_ICON = "smallIcon"
+    private const val KEY_CARD_ACCENT_COLOR = "accentColor"
+    private const val KEY_CARD_SHOW_PREVIOUS = "showPrevious"
+    private const val KEY_CARD_SHOW_NEXT = "showNext"
+    private const val KEY_CARD_SHOW_STOP = "showStop"
+    private const val KEY_CARD_SEEK_STEP_MS = "seekStepMs"
+
+    fun sync(context: Context, metadata: Bundle, isPlaying: Boolean) {
+      val intent = Intent(context, MediaPlaybackService::class.java).apply {
+        action = ACTION_UPDATE
+        putExtra(EXTRA_METADATA, metadata)
+        putExtra(EXTRA_IS_PLAYING, isPlaying)
+      }
+
+      try {
+        if (isPlaying) {
+          ContextCompat.startForegroundService(context, intent)
+        } else {
+          context.startService(intent)
+        }
+      } catch (e: Exception) {
+        Log.e(TAG, "Failed to start/update playback service", e)
+      }
+    }
+
+    fun stop(context: Context) {
+      val stopIntent = Intent(context, MediaPlaybackService::class.java).apply {
+        action = ACTION_STOP_SERVICE
+      }
+      try {
+        context.startService(stopIntent)
+      } catch (e: Exception) {
+        Log.w(TAG, "Failed to request service stop", e)
+      }
+    }
+  }
+}

package/dist/AudioEngineModule.types.d.ts

@@ -53,6 +53,16 @@ export interface MediaMetadata {
     artist?: string;
     album?: string;
     artwork?: string;
+    logo?: string;
+    playbackCard?: PlaybackCardOptions;
+}
+export interface PlaybackCardOptions {
+    smallIcon?: string;
+    accentColor?: string | number;
+    showPrevious?: boolean;
+    showNext?: boolean;
+    showStop?: boolean;
+    seekStepMs?: number;
 }
 export type AudioEngineEvent = 'playbackStateChange' | 'positionUpdate' | 'playbackComplete' | 'trackLoaded' | 'trackUnloaded' | 'recordingStarted' | 'recordingStopped' | 'extractionProgress' | 'extractionComplete' | 'error';
 export interface AudioEngineError {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sezo-audio-engine",
-  "version": "0.0.12",
+  "version": "0.0.13",
   "description": "Cross-platform Expo module for the Sezo Audio Engine with iOS implementation and background playback.",
   "license": "MIT",
   "author": "Sezo",