react-native-queue-player 1.1.1 → 1.2.0

package/android/build.gradle

@@ -129,6 +129,13 @@ dependencies {
   implementation "com.facebook.react:react-android"
   implementation project(":react-native-nitro-modules")
 
+  // @Keep drives R8 retention of the Nitrogen-generated bridge classes, and
+  // this artifact carries the consumer rule that honours it. Resolved
+  // transitively via Media3 / androidx.core today; declared explicitly at the
+  // version that already resolves so the dependency surface is honest rather
+  // than relying on another artifact keeping it in the graph.
+  implementation "androidx.annotation:annotation:1.8.1"
+
   // Media3 ExoPlayer — Android audio engine. Pinned to 1.10.0 (current
   // stable, Mar 2026). 1.10 keeps cache + audio/wake-lock APIs stable
   // and only deprecates MetadataRetriever (we don't use it).

package/android/consumer-rules.pro

@@ -1,10 +1,79 @@
 # React Native Queue Player — consumer R8 / ProGuard rules.
 #
-# Packaged into the published AAR via `consumerProguardFiles` and applied
+# Packaged into the AAR via `consumerProguardFiles` and applied
 # automatically to a consuming app's R8 run, so consumers need no manual rules
-# for this library's transitive dependencies.
+# for this library's native bindings or its transitive dependencies.
+#
+# The keeps below are deliberately whole-class rather than member-scoped. The
+# saving from narrowing them is a few kilobytes; the cost of getting one wrong
+# is a silent runtime failure in someone else's shipped app.
+
+# libraop's JNI_OnLoad binds this class by literal descriptor: src/main/cpp/
+# airplay_jni.cpp calls FindClass on the string
+# "com/margelo/nitro/queueplayer/cast/airplay/AirplayJNI", then resolves all 28
+# entries of its JNINativeMethod table by name and signature. React Native's own
+# rules pin the native method names but let the class be renamed, and the rule
+# that pins the class name ships only in AGP's optional default ProGuard file.
+# When the class is renamed, FindClass returns null, RegisterNatives never runs,
+# and AirPlay 1 reports itself unavailable rather than failing loudly.
+-keep class com.margelo.nitro.queueplayer.cast.airplay.AirplayJNI { *; }
+
+# libairplay2 binds this class the same way (src/main/cpp/airplay2_jni.cpp) and
+# additionally calls back into Kotlin: the audio drain thread invokes
+# onNativeSessionDied(long, int), resolved through GetStaticMethodID on that
+# literal name. Nothing in Kotlin calls that method, so without this rule R8
+# deletes it as unreachable — the native side then logs that upcalls are
+# disabled and carries on. Connect and streaming still work; only the receiver's
+# feedback timeout stops arriving, so a dead receiver never tears its session
+# down and never reverts routing to local. Playback stops with the UI still
+# showing the remote device.
+-keep class com.margelo.nitro.queueplayer.cast.airplay.AirPlay2JNI { *; }
+
+# libsignalsmith_stretch has no JNI_OnLoad; src/main/cpp/stretch_jni.cpp relies
+# on implicit JNI name mangling, so its exported symbols spell out both the
+# package path and the method name (Java_com_margelo_nitro_queueplayer_
+# SignalsmithStretchNative_nativeCreate). Renaming either half breaks the lookup
+# and the `music` pitch-correction mode throws UnsatisfiedLinkError on first use.
+# The native methods live on this class, not on its Companion.
+-keep class com.margelo.nitro.queueplayer.SignalsmithStretchNative { *; }
+
+# Named as a string in this library's own AndroidManifest.xml, through the cast
+# OPTIONS_PROVIDER_CLASS_NAME meta-data. aapt2 generates keep rules for manifest
+# components but does not descend into meta-data values, so nothing automatic
+# protects this one. The Play Services Cast AAR happens to keep it today via
+# `-keep public class * implements OptionsProvider`; this rule means correctness
+# does not depend on another artifact's rule surviving.
+-keep class com.margelo.nitro.queueplayer.cast.chromecast.ChromecastOptionsProvider { *; }
+
+# Named as a string in this library's own AndroidManifest.xml, as the
+# androidx.startup meta-data entry that registers it with
+# InitializationProvider. Same shape as the cast options provider above and
+# equally invisible to aapt2, which generates keep rules for manifest
+# components but not for meta-data values. androidx.startup keeps it today via
+# `-keepnames class * extends androidx.startup.Initializer`; this rule means
+# correctness does not depend on that.
+-keep class com.margelo.nitro.queueplayer.cast.airplay.AirPlayBackendInitializer { *; }
+
+# The Nitrogen-generated enums are read from C++ by constant name — e.g.
+# getStaticField<JCastProtocol>("AIRPLAY") — so losing a constant's name breaks
+# every conversion across the bridge. They survive today only because
+# androidx.annotation ships a keep rule for @Keep-annotated classes and Nitrogen
+# annotates what it generates, which makes correctness depend on that artifact
+# staying in the resolution graph. `**` also matches the enums internal to this
+# library that native code never touches; keeping them is accepted collateral.
+-keep enum com.margelo.nitro.queueplayer.** { *; }
+
+# Constructed from C++ during Nitro's onLoad via getConstructor<javaobject()>().
+# R8's compatibility FAQ states that full mode does not implicitly keep a kept
+# class's no-arg constructor; AGP's keep-rule documentation states that it does.
+# Current R8 keeps it. These rules make the library correct under either.
+-keep class com.margelo.nitro.queueplayer.TrackPlayer { <init>(); }
+-keep class com.margelo.nitro.queueplayer.Equalizer { <init>(); }
+-keep class com.margelo.nitro.queueplayer.Visualizer { <init>(); }
+-keep class com.margelo.nitro.queueplayer.CastManager { <init>(); }
 
-# The embedded Ktor CIO HTTP server (the Android AirPlay 2 receiver) ships
+# The embedded Ktor CIO HTTP server (the Chromecast local media server, which
+# serves local files to a receiver) ships
 # io.ktor.util.debug.IntellijIdeaDebugDetector, which references
 # java.lang.management.ManagementFactory and RuntimeMXBean to detect an attached
 # IntelliJ debugger. Those JMX classes are JVM-only and absent on Android, so a

package/android/src/main/cpp/airplay2_jni.cpp

@@ -546,19 +546,39 @@ jint ap2_register_natives(JavaVM *vm) {
 
     jclass clazz = env->FindClass(sClassName);
     if (!clazz) {
-        __android_log_print(ANDROID_LOG_WARN, TAG,
-            "AirPlay2JNI class not found — RegisterNatives deferred");
-        return JNI_VERSION_1_6;
+        /* Leaves a pending NoClassDefFoundError. Clear it and fail the load
+         * outright: nothing retries registration, so reporting success here
+         * would leave the Kotlin object reporting AirPlay 2 as available with
+         * no natives bound, and the first call would throw
+         * UnsatisfiedLinkError. Failing makes System.loadLibrary throw, and
+         * AirPlay2JNI's initialiser catches that and sets isAvailable false. */
+        env->ExceptionClear();
+        __android_log_print(ANDROID_LOG_ERROR, TAG,
+            "AirPlay2JNI class not found — AirPlay 2 unavailable");
+        return JNI_ERR;
     }
 
     if (env->RegisterNatives(clazz, sMethods,
             sizeof(sMethods) / sizeof(sMethods[0])) < 0) {
+        /* An unresolved table entry leaves a pending NoSuchMethodError. */
+        env->ExceptionClear();
         __android_log_print(ANDROID_LOG_ERROR, TAG, "RegisterNatives failed");
         return JNI_ERR;
     }
 
     /* Cache the session-death upcall target (global ref + static method id). */
     sAp2JniClass = (jclass)env->NewGlobalRef(clazz);
+    if (!sAp2JniClass) {
+        /* Null only when the global reference table is exhausted, which can
+         * leave a pending OutOfMemoryError; clear it so the load reports
+         * success with upcalls disabled, matching the missing-method path
+         * below. The check has to precede GetStaticMethodID, which aborts
+         * under CheckJNI when handed a null class. */
+        env->ExceptionClear();
+        __android_log_print(ANDROID_LOG_WARN, TAG,
+            "could not retain AirPlay2JNI — upcalls disabled");
+        return JNI_VERSION_1_6;
+    }
     sOnNativeSessionDied = env->GetStaticMethodID(
         sAp2JniClass, "onNativeSessionDied", "(JI)V");
     if (!sOnNativeSessionDied) {

package/android/src/main/cpp/airplay_jni.cpp

@@ -576,13 +576,22 @@ jint JNI_OnLoad(JavaVM *vm, void * /* reserved */) {
 
     jclass clazz = env->FindClass(sClassName);
     if (clazz == nullptr) {
-        __android_log_print(ANDROID_LOG_WARN, TAG,
-            "AirplayJNI class not loaded yet — RegisterNatives deferred");
-        return JNI_VERSION_1_6;
+        /* Leaves a pending NoClassDefFoundError. Clear it and fail the load
+         * outright: nothing retries registration, so reporting success here
+         * would leave the Kotlin object reporting AirPlay 1 as available with
+         * no natives bound, and the first call would throw
+         * UnsatisfiedLinkError. Failing makes System.loadLibrary throw, and
+         * AirplayJNI's initialiser catches that and sets isAvailable false. */
+        env->ExceptionClear();
+        __android_log_print(ANDROID_LOG_ERROR, TAG,
+            "AirplayJNI class not found — AirPlay 1 unavailable");
+        return JNI_ERR;
     }
 
     if (env->RegisterNatives(clazz, sMethods,
             sizeof(sMethods) / sizeof(sMethods[0])) < 0) {
+        /* An unresolved table entry leaves a pending NoSuchMethodError. */
+        env->ExceptionClear();
         __android_log_print(ANDROID_LOG_ERROR, TAG, "RegisterNatives failed");
         return JNI_ERR;
     }

package/android/src/main/java/com/margelo/nitro/queueplayer/TrackPlayer.kt

@@ -974,12 +974,19 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
       }
 
       override fun onSkipToNextCommand(): Boolean {
+        // Cast routing before the local body, same early-return contract as
+        // the public transport methods. The `true` return suppresses the
+        // forwarding player's default seek either way, so the receiver gets
+        // exactly one skip. The reason stamp sits on the local path because
+        // that is the only path whose listener consumes it.
+        if (com.margelo.nitro.queueplayer.cast.CastTransportRouter.routeSkipToNext()) return true
         pendingStateChangeReason = StateChangeReason.SYSTEM
         skipToNextInternal()
         return true
       }
 
       override fun onSkipToPreviousCommand(): Boolean {
+        if (com.margelo.nitro.queueplayer.cast.CastTransportRouter.routeSkipToPrevious()) return true
         pendingStateChangeReason = StateChangeReason.SYSTEM
         skipToPreviousInternal()
         return true
@@ -990,7 +997,6 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
         // no-ops it (Media3 passes C.INDEX_UNSET when the seek implies
         // no move).
         if (mediaItemIndex < 0 || mediaItemIndex >= tracks.size) return false
-        pendingStateChangeReason = StateChangeReason.SYSTEM
         // Same path as the public skipToIndex: jump the receiver while
         // casting, else the local engine. Both write currentTrackIndex +
         // the USER_SKIP_TO_INDEX reason that a raw controller seek skips.
@@ -1000,21 +1006,25 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
         if (com.margelo.nitro.queueplayer.cast.CastTransportRouter.routeSkipToIndex(mediaItemIndex)) {
           return true
         }
+        pendingStateChangeReason = StateChangeReason.SYSTEM
         skipToIndexInternal(mediaItemIndex)
         return true
       }
 
       override fun onMediaPlay() {
+        if (com.margelo.nitro.queueplayer.cast.CastTransportRouter.routePlay()) return
         pendingStateChangeReason = StateChangeReason.SYSTEM
         serviceBinder?.engine?.play()
       }
 
       override fun onMediaPause() {
+        if (com.margelo.nitro.queueplayer.cast.CastTransportRouter.routePause()) return
         pendingStateChangeReason = StateChangeReason.SYSTEM
         serviceBinder?.engine?.pause()
       }
 
       override fun onMediaTogglePlayPause() {
+        if (com.margelo.nitro.queueplayer.cast.CastTransportRouter.routeTogglePlayPause()) return
         pendingStateChangeReason = StateChangeReason.SYSTEM
         val engine = serviceBinder?.engine ?: return
         // `playWhenReady` (intent to play) is read off the underlying
@@ -1026,11 +1036,13 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
       }
 
       override fun onMediaSkipNext() {
+        if (com.margelo.nitro.queueplayer.cast.CastTransportRouter.routeSkipToNext()) return
         pendingStateChangeReason = StateChangeReason.SYSTEM
         skipToNextInternal()
       }
 
       override fun onMediaSkipPrevious() {
+        if (com.margelo.nitro.queueplayer.cast.CastTransportRouter.routeSkipToPrevious()) return
         pendingStateChangeReason = StateChangeReason.SYSTEM
         skipToPreviousInternal()
       }
@@ -2875,13 +2887,25 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
   // goes away.
 
   /**
-   * Snapshot of the ExoPlayer's current state mapped onto the
-   * public [PlayerState] enum. Safe to call from any thread —
-   * hops to main via [syncMain] so Media3's thread-assertion does
-   * not fire.
+   * Snapshot of the active playback source's state mapped onto the public
+   * [PlayerState] enum — the cast receiver while a session owns playback,
+   * otherwise the local ExoPlayer. Safe to call from any thread: the receiver
+   * read is lock-free, and the local read hops to main via [syncMain] so
+   * Media3's thread-assertion does not fire.
    */
-  override fun getState(): PlayerState =
-    syncMain { getStateInternal() }
+  override fun getState(): PlayerState {
+    // The receiver owns playback during a cast session — the local player is
+    // parked and paused for its duration, so its derived state describes
+    // nothing the user can hear. Until the receiver has reported (session
+    // still activating, holding its initial IDLE) the local read is the
+    // better answer; after that the receiver is authoritative, including a
+    // later IDLE, which means it genuinely has nothing loaded.
+    val remote = com.margelo.nitro.queueplayer.cast.PlaybackStateRouter.activeRemote()
+    if (remote != null && remote.hasReportedState) {
+      return com.margelo.nitro.queueplayer.cast.mapRemotePlaybackState(remote.state.value)
+    }
+    return syncMain { getStateInternal() }
+  }
 
   @VisibleForTesting
   internal fun getStateInternal(): PlayerState {

package/android/src/main/java/com/margelo/nitro/queueplayer/cast/CastEventBridge.kt

@@ -70,7 +70,7 @@ internal class CastEventBridge(private val owner: TrackPlayer) {
         sessionJob = scope.launch {
           launch {
             session.state.collectLatest { remoteState ->
-              owner.emitRemoteState(mapState(remoteState), StateChangeReason.SYSTEM)
+              owner.emitRemoteState(mapRemotePlaybackState(remoteState), StateChangeReason.SYSTEM)
             }
           }
           launch {
@@ -110,13 +110,4 @@ internal class CastEventBridge(private val owner: TrackPlayer) {
     lastPositionMs = positionMs
   }
 
-  private fun mapState(state: RemotePlaybackState): PlayerState = when (state) {
-    RemotePlaybackState.PLAYING -> PlayerState.PLAYING
-    RemotePlaybackState.PAUSED -> PlayerState.PAUSED
-    RemotePlaybackState.LOADING -> PlayerState.BUFFERING
-    RemotePlaybackState.BUFFERING -> PlayerState.BUFFERING
-    RemotePlaybackState.IDLE -> PlayerState.NONE
-    RemotePlaybackState.ENDED -> PlayerState.ENDED
-    RemotePlaybackState.ERROR -> PlayerState.ERROR
-  }
 }

package/android/src/main/java/com/margelo/nitro/queueplayer/cast/CastSession.kt

@@ -124,6 +124,19 @@ sealed class CastSession {
     /** Receiver-driven playback state for `PlaybackStateRouter`. */
     abstract val state: StateFlow<RemotePlaybackState>
 
+    /**
+     * `true` once the receiver has reported any state other than
+     * [RemotePlaybackState.IDLE]. Latches on the first such report and stays
+     * set for the session's lifetime.
+     *
+     * State reads use this to decide whether the receiver can answer yet: a
+     * session that has just activated still holds its initial IDLE, and the
+     * local engine is the better answer until the receiver speaks. Once it
+     * has, the receiver is authoritative — including a later IDLE, which
+     * means it genuinely has nothing loaded.
+     */
+    abstract val hasReportedState: Boolean
+
     /** Receiver-driven position in ms. */
     abstract val positionMs: StateFlow<Long>
 

package/android/src/main/java/com/margelo/nitro/queueplayer/cast/CastTransportRouter.kt

@@ -30,6 +30,25 @@ internal object CastTransportRouter {
     return true
   }
 
+  /**
+   * Flip the receiver's play state. The receiver's own state picks the
+   * direction — the local engine is parked and paused while casting, so its
+   * `playWhenReady` would resume the receiver on every press. Anything that
+   * represents "trying to play" toggles to pause, so a press during buffering
+   * stops rather than restarts.
+   */
+  fun routeTogglePlayPause(): Boolean {
+    val remote = PlaybackStateRouter.activeRemote() ?: return false
+    val active = when (remote.state.value) {
+      RemotePlaybackState.PLAYING,
+      RemotePlaybackState.BUFFERING,
+      RemotePlaybackState.LOADING -> true
+      else -> false
+    }
+    if (active) remote.pause() else remote.play()
+    return true
+  }
+
   fun routeStop(): Boolean {
     val remote = PlaybackStateRouter.activeRemote() ?: return false
     remote.stop()

package/android/src/main/java/com/margelo/nitro/queueplayer/cast/RemotePlaybackStateMapping.kt

@@ -0,0 +1,18 @@
+package com.margelo.nitro.queueplayer.cast
+
+import com.margelo.nitro.queueplayer.PlayerState
+
+/**
+ * Map the protocol-neutral receiver state to the JS-facing [PlayerState].
+ * Shared by the cast event fan-out and `TrackPlayer.getState`, so a state read
+ * and the event stream can't disagree about the same receiver.
+ */
+internal fun mapRemotePlaybackState(state: RemotePlaybackState): PlayerState = when (state) {
+  RemotePlaybackState.PLAYING -> PlayerState.PLAYING
+  RemotePlaybackState.PAUSED -> PlayerState.PAUSED
+  RemotePlaybackState.LOADING -> PlayerState.BUFFERING
+  RemotePlaybackState.BUFFERING -> PlayerState.BUFFERING
+  RemotePlaybackState.IDLE -> PlayerState.NONE
+  RemotePlaybackState.ENDED -> PlayerState.ENDED
+  RemotePlaybackState.ERROR -> PlayerState.ERROR
+}

package/android/src/main/java/com/margelo/nitro/queueplayer/cast/airplay/AirPlay2Session.kt

@@ -9,6 +9,7 @@ import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.SupervisorJob
 import kotlinx.coroutines.launch
+import java.util.concurrent.atomic.AtomicReference
 
 /**
  * A live AirPlay 2 streaming session backed by libairplay2 via [AirPlay2JNI].
@@ -28,7 +29,7 @@ class AirPlay2Session(
     private val handle: Long,
     private val host: String,
     private val port: Int,
-) : CastSession.PcmStream(), MetadataAwareSession {
+) : CastSession.PcmStream(), MetadataAwareSession, MetadataSyncTarget {
 
     companion object {
         private const val TAG = "AirPlay2Session"
@@ -36,7 +37,10 @@ class AirPlay2Session(
 
     private val sink = AirPlay2Sink(handle)
     @Volatile private var closed = false
-    private var metadataSync: AirPlay2MetadataSync? = null
+    // Swapped on the player's looper by onActivated, read and cleared on the
+    // disconnecting thread — the exchange has to be atomic or a teardown can
+    // read a stale null and leave the previous sync running.
+    private val metadataSync = AtomicReference<AirPlayMetadataSync?>()
 
     /** Internal scope for fire-and-forget native teardown. */
     private val teardownScope = CoroutineScope(SupervisorJob() + Dispatchers.IO)
@@ -53,16 +57,21 @@ class AirPlay2Session(
     }
 
     override fun onActivated(player: Player, scope: CoroutineScope) {
-        // Re-entrant safe: stop any prior sync before rebinding so a repeat
+        if (closed) return
+        // Stop any prior sync before starting the replacement, so a repeat
         // activation (the player swaps under a still-connected session) never
         // leaves an orphaned sync running against the previous player.
-        metadataSync?.stop()
-        metadataSync = AirPlay2MetadataSync(context, this, player, scope).also { it.start() }
+        val next = AirPlayMetadataSync(context, this, player, scope)
+        metadataSync.getAndSet(next)?.stop()
+        next.start()
+        // A close() that ran while this was publishing exchanged out a null
+        // and tore down without seeing `next`, so re-check: otherwise a live
+        // sync stays bound to a closed session for the process lifetime.
+        if (closed) metadataSync.getAndSet(null)?.stop()
     }
 
     override fun onDeactivated() {
-        metadataSync?.stop()
-        metadataSync = null
+        metadataSync.getAndSet(null)?.stop()
     }
 
     /**
@@ -103,17 +112,17 @@ class AirPlay2Session(
         }
     }
 
-    fun setMetadata(title: String?, artist: String?, album: String?) {
+    override fun setMetadata(title: String?, artist: String?, album: String?) {
         if (closed) return
         AirPlay2JNI.nativeAp2SetMetadata(handle, title, artist, album)
     }
 
-    fun setArtwork(imageData: ByteArray, contentType: String = "image/jpeg") {
+    override fun setArtwork(imageData: ByteArray, contentType: String) {
         if (closed) return
         AirPlay2JNI.nativeAp2SetArtwork(handle, imageData, imageData.size)
     }
 
-    fun setProgress(elapsedMs: Int, durationMs: Int) {
+    override fun setProgress(elapsedMs: Int, durationMs: Int) {
         if (closed) return
         AirPlay2JNI.nativeAp2SetProgressMs(handle, elapsedMs.toLong(), durationMs.toLong())
     }

package/android/src/main/java/com/margelo/nitro/queueplayer/cast/airplay/AirPlayMetadataSync.kt

@@ -14,19 +14,23 @@ import java.io.ByteArrayOutputStream
 import java.net.URL
 
 /**
- * Syncs ExoPlayer track metadata and playback progress to an [AirPlaySession].
+ * Syncs ExoPlayer track metadata and playback progress to an AirPlay
+ * receiver through [MetadataSyncTarget].
  *
- * - On activation and on every track transition: sends DAAP metadata
+ * - On activation and on every track transition: sends metadata
  *   (title/artist/album) and kicks off an async artwork fetch.
  * - Every 5 seconds while playing: sends progress (elapsed/duration).
  * - On seek: sends progress immediately.
  * - On stop: cancels all coroutines and removes the player listener.
+ *
+ * One instance covers one activation — [start] then [stop]. Starting again
+ * after a stop is a no-op; a new activation builds a new instance.
  */
 internal class AirPlayMetadataSync(
     private val context: Context,
-    private val session: AirPlaySession,
+    private val target: MetadataSyncTarget,
     private val player: Player,
-    private val scope: CoroutineScope,
+    scope: CoroutineScope,
 ) {
     companion object {
         private const val TAG = "AirPlayMetadataSync"
@@ -35,11 +39,32 @@ internal class AirPlayMetadataSync(
         private const val JPEG_QUALITY = 80
     }
 
+    /**
+     * Owns every coroutine this sync launches, so [stop] can cancel them as
+     * one atomic operation from any thread. Cancelling the scope needs no
+     * field read, so a teardown racing the player looper cannot miss a job,
+     * and a launch that loses the race starts already-cancelled rather than
+     * outliving the session it pushes into.
+     */
+    private val syncScope =
+        CoroutineScope(scope.coroutineContext + SupervisorJob(scope.coroutineContext[Job]))
+
+    // Touched only on the player's application looper.
     private var progressJob: Job? = null
     private var artworkJob: Job? = null
     private var lastArtworkUri: String? = null
+
+    // Written by start/stop on whichever thread activated or tore the
+    // session down; read on the looper and by the progress loop.
+    @Volatile
     private var started = false
 
+    // Latches on stop so a restart cannot half-revive a spent instance: the
+    // scope is already cancelled, so the listener would still push metadata
+    // while the progress loop and artwork fetch stay dead.
+    @Volatile
+    private var stopped = false
+
     // ExoPlayer rejects add/removeListener + state reads off its application
     // looper. start()/stop() are driven by session activation/close, and
     // close() runs on whichever thread disconnected (the JS thread for a
@@ -48,6 +73,10 @@ internal class AirPlayMetadataSync(
     // already on it.
     private val playerHandler = Handler(player.applicationLooper)
 
+    // Both protocols log under one tag, so every line says which sender it
+    // came from.
+    private val targetName = target.javaClass.simpleName
+
     private fun onPlayerLooper(block: () -> Unit) {
         if (Looper.myLooper() == player.applicationLooper) block()
         else playerHandler.post(block)
@@ -69,6 +98,7 @@ internal class AirPlayMetadataSync(
         }
 
         override fun onPlayWhenReadyChanged(playWhenReady: Boolean, reason: Int) {
+            if (!started) return
             if (playWhenReady) {
                 startProgressTimer()
             } else {
@@ -79,37 +109,43 @@ internal class AirPlayMetadataSync(
     }
 
     fun start() {
-        if (started) return
+        if (started || stopped) return
         started = true
         onPlayerLooper {
+            // A stop() between this post and its execution has already run its
+            // own removeListener, so attaching now would leave the listener on
+            // the player for its lifetime.
+            if (stopped) return@onPlayerLooper
             player.addListener(listener)
             sendCurrentMetadata()
-            if (player.playWhenReady) {
+            if (started && player.playWhenReady) {
                 startProgressTimer()
             }
         }
-        Log.i(TAG, "Started metadata sync")
+        Log.i(TAG, "Started metadata sync for $targetName")
     }
 
     fun stop() {
-        if (!started) return
+        if (stopped) return
+        stopped = true
         started = false
-        progressJob?.cancel()
-        progressJob = null
-        artworkJob?.cancel()
-        artworkJob = null
+        syncScope.cancel()
+        // Listener removal has to hop to the looper, so a callback queued
+        // ahead of it can still run; the `started` gate in the senders is
+        // what stops those from reaching a session that is being closed.
         onPlayerLooper { player.removeListener(listener) }
-        Log.i(TAG, "Stopped metadata sync")
+        Log.i(TAG, "Stopped metadata sync for $targetName")
     }
 
     private fun sendCurrentMetadata() {
+        if (!started) return
         val meta = player.currentMediaItem?.mediaMetadata ?: return
         val title = meta.title?.toString()
         val artist = meta.artist?.toString()
         val album = meta.albumTitle?.toString()
 
-        Log.i(TAG, "Sending metadata: title=$title, artist=$artist, album=$album")
-        session.setMetadata(title, artist, album)
+        Log.i(TAG, "$targetName sending metadata: title=$title, artist=$artist, album=$album")
+        target.setMetadata(title, artist, album)
 
         // Send initial progress for the new track
         sendProgress()
@@ -123,16 +159,17 @@ internal class AirPlayMetadataSync(
     }
 
     private fun sendProgress() {
+        if (!started) return
         val position = player.currentPosition.toInt()
         val duration = player.duration.let { if (it > 0) it.toInt() else 0 }
         if (duration > 0) {
-            session.setProgress(position, duration)
+            target.setProgress(position, duration)
         }
     }
 
     private fun startProgressTimer() {
         progressJob?.cancel()
-        progressJob = scope.launch {
+        progressJob = syncScope.launch {
             while (isActive) {
                 delay(PROGRESS_INTERVAL_MS)
                 if (player.isPlaying) {
@@ -144,7 +181,7 @@ internal class AirPlayMetadataSync(
 
     private fun fetchAndSendArtwork(uriString: String) {
         artworkJob?.cancel()
-        artworkJob = scope.launch(Dispatchers.IO) {
+        artworkJob = syncScope.launch(Dispatchers.IO) {
             try {
                 val uri = Uri.parse(uriString)
                 val scheme = uri.scheme ?: return@launch
@@ -185,9 +222,9 @@ internal class AirPlayMetadataSync(
                 bitmap.recycle()
 
                 val bytes = baos.toByteArray()
-                if (isActive) {
-                    session.setArtwork(bytes, "image/jpeg")
-                    Log.i(TAG, "Sent artwork: ${bytes.size} bytes from $uriString")
+                if (isActive && started) {
+                    target.setArtwork(bytes, "image/jpeg")
+                    Log.i(TAG, "$targetName sent artwork: ${bytes.size} bytes from $uriString")
                 }
             } catch (e: Exception) {
                 if (e !is CancellationException) {