react-native-queue-player 1.2.0 → 2.0.0

package/android/src/test/java/com/margelo/nitro/queueplayer/ReplayGainMergeTest.kt

@@ -0,0 +1,258 @@
+package com.margelo.nitro.queueplayer
+
+import org.junit.Assert.assertEquals
+import org.junit.Test
+
+/**
+ * Coverage for [ReplayGainData.merge] — the all-or-nothing, per-item
+ * choice between consumer-supplied ReplayGain and values detected from
+ * the file. Mirrors the iOS `ReplayGainMergeTests` matrix row for row,
+ * with the same fixtures, so both platforms hold the same rule.
+ *
+ * The rule is one predicate on the item, not two pair decisions and not
+ * four field decisions: a claimed track's ReplayGain comes solely from
+ * the consumer and detection is discarded in full — including for the
+ * mode the consumer said nothing about. `merge` takes the claim and the
+ * surviving values as two separate inputs; which fields make a claim and
+ * which values survive is [SuppliedReplayGain]'s job, covered in
+ * `SuppliedReplayGainTest`.
+ *
+ * Supplied and detected fixtures carry different values in every field,
+ * so a row that returned the wrong source cannot pass.
+ */
+class ReplayGainMergeTest {
+
+  // region Fixtures
+
+  private val detectedAll = ReplayGainData(
+    trackGainDb = -20.0f, trackPeak = 0.5f,
+    albumGainDb = -6.0f, albumPeak = 0.6f,
+  )
+  private val detectedTrackOnly = ReplayGainData(
+    trackGainDb = -20.0f, trackPeak = 0.5f,
+    albumGainDb = null, albumPeak = null,
+  )
+  private val detectedAlbumOnly = ReplayGainData(
+    trackGainDb = null, trackPeak = null,
+    albumGainDb = -6.0f, albumPeak = 0.6f,
+  )
+
+  private val suppliedAll = ReplayGainData(
+    trackGainDb = -3.0f, trackPeak = 0.25f,
+    albumGainDb = -9.0f, albumPeak = 0.3f,
+  )
+  private val suppliedTrackGain = ReplayGainData(
+    trackGainDb = -3.0f, trackPeak = null,
+    albumGainDb = null, albumPeak = null,
+  )
+  private val suppliedAlbumGain = ReplayGainData(
+    trackGainDb = null, trackPeak = null,
+    albumGainDb = -9.0f, albumPeak = null,
+  )
+  private val suppliedTrackPeak = ReplayGainData(
+    trackGainDb = null, trackPeak = 0.25f,
+    albumGainDb = null, albumPeak = null,
+  )
+  private val suppliedAlbumPeak = ReplayGainData(
+    trackGainDb = null, trackPeak = null,
+    albumGainDb = null, albumPeak = 0.3f,
+  )
+  private val suppliedTrackPair = ReplayGainData(
+    trackGainDb = -3.0f, trackPeak = 0.25f,
+    albumGainDb = null, albumPeak = null,
+  )
+  private val suppliedAlbumPair = ReplayGainData(
+    trackGainDb = null, trackPeak = null,
+    albumGainDb = -9.0f, albumPeak = 0.3f,
+  )
+
+  // endregion
+
+  // region No claim — detection is used verbatim
+
+  @Test
+  fun `an unclaimed track uses every detected field`() {
+    assertMerge(
+      claimed = false, supplied = null, detected = detectedAll,
+      expected = detectedAll,
+      message = "no supplied field means detection is used, all four",
+    )
+  }
+
+  @Test
+  fun `an unclaimed track with no detection has no ReplayGain`() {
+    assertMerge(
+      claimed = false, supplied = null, detected = null,
+      expected = null,
+      message = "nothing supplied and nothing detected is no ReplayGain",
+    )
+  }
+
+  @Test
+  fun `an unclaimed track keeps a track-only detection`() {
+    assertMerge(
+      claimed = false, supplied = null, detected = detectedTrackOnly,
+      expected = detectedTrackOnly,
+      message = "a partial detection is used as-is, not padded",
+    )
+  }
+
+  @Test
+  fun `an unclaimed track keeps an album-only detection`() {
+    assertMerge(
+      claimed = false, supplied = null, detected = detectedAlbumOnly,
+      expected = detectedAlbumOnly,
+      message = "the mirrored partial-detection case",
+    )
+  }
+
+  // endregion
+
+  // region Claimed — one supplied field discards all detection
+
+  @Test
+  fun `a supplied track gain discards every detected field`() {
+    assertMerge(
+      claimed = true, supplied = suppliedTrackGain, detected = detectedAll,
+      expected = suppliedTrackGain,
+      message = "supplied trackGain applies; detected peak and album pair are dropped",
+    )
+  }
+
+  @Test
+  fun `a supplied album gain discards every detected field`() {
+    assertMerge(
+      claimed = true, supplied = suppliedAlbumGain, detected = detectedAll,
+      expected = suppliedAlbumGain,
+      message = "supplied albumGain applies; detected track pair and album peak are dropped",
+    )
+  }
+
+  @Test
+  fun `a supplied track peak alone leaves no gain anywhere`() {
+    assertMerge(
+      claimed = true, supplied = suppliedTrackPeak, detected = detectedAll,
+      expected = suppliedTrackPeak,
+      message = "a peak with no gain is ownership with nothing to apply",
+    )
+  }
+
+  @Test
+  fun `a supplied album peak alone leaves no gain anywhere`() {
+    assertMerge(
+      claimed = true, supplied = suppliedAlbumPeak, detected = detectedAll,
+      expected = suppliedAlbumPeak,
+      message = "the mirrored peak-only case",
+    )
+  }
+
+  @Test
+  fun `a supplied track pair discards the detected album pair`() {
+    assertMerge(
+      claimed = true, supplied = suppliedTrackPair, detected = detectedAll,
+      expected = suppliedTrackPair,
+      message = "album mode plays at unity even though the file carries album tags",
+    )
+  }
+
+  @Test
+  fun `a supplied album pair discards the detected track pair`() {
+    assertMerge(
+      claimed = true, supplied = suppliedAlbumPair, detected = detectedAll,
+      expected = suppliedAlbumPair,
+      message = "track mode plays at unity even though the file carries track tags",
+    )
+  }
+
+  @Test
+  fun `a fully supplied set replaces a fully detected set`() {
+    assertMerge(
+      claimed = true, supplied = suppliedAll, detected = detectedAll,
+      expected = suppliedAll,
+      message = "all four supplied values win over all four detected values",
+    )
+  }
+
+  @Test
+  fun `a supplied track gain discards an album-only detection`() {
+    assertMerge(
+      claimed = true, supplied = suppliedTrackGain, detected = detectedAlbumOnly,
+      expected = suppliedTrackGain,
+      message = "detection is discarded even where supplied and detected do not overlap",
+    )
+  }
+
+  // endregion
+
+  // region Claimed with no detection to discard
+
+  @Test
+  fun `a fully supplied set applies to an untagged file`() {
+    assertMerge(
+      claimed = true, supplied = suppliedAll, detected = null,
+      expected = suppliedAll,
+      message = "a supplied set is applied where the file carries no tags",
+    )
+  }
+
+  @Test
+  fun `a supplied track gain applies to an untagged file`() {
+    assertMerge(
+      claimed = true, supplied = suppliedTrackGain, detected = null,
+      expected = suppliedTrackGain,
+      message = "a single supplied field on an untagged file applies alone",
+    )
+  }
+
+  // endregion
+
+  // region Claimed but nothing usable — ownership without a value
+
+  @Test
+  fun `a claim with no usable value discards a full detection`() {
+    assertMerge(
+      claimed = true, supplied = null, detected = detectedAll,
+      expected = null,
+      message = "a claim discards detection even when it carries no value",
+    )
+  }
+
+  @Test
+  fun `a claim with no usable value discards a partial detection`() {
+    assertMerge(
+      claimed = true, supplied = null, detected = detectedTrackOnly,
+      expected = null,
+      message = "a partial detection is discarded by a claim just as a full one is",
+    )
+  }
+
+  @Test
+  fun `a claim with no usable value and no detection has no ReplayGain`() {
+    assertMerge(
+      claimed = true, supplied = null, detected = null,
+      expected = null,
+      message = "ownership claimed, nothing supplied, nothing detected",
+    )
+  }
+
+  // endregion
+
+  // region Helper
+
+  private fun assertMerge(
+    claimed: Boolean,
+    supplied: ReplayGainData?,
+    detected: ReplayGainData?,
+    expected: ReplayGainData?,
+    message: String,
+  ) {
+    val actual = ReplayGainData.merge(
+      suppliedClaimed = claimed,
+      supplied = supplied,
+      detected = detected,
+    )
+    assertEquals(message, expected, actual)
+  }
+
+  // endregion
+}

package/android/src/test/java/com/margelo/nitro/queueplayer/RobolectricServiceBindHelper.kt

@@ -41,8 +41,8 @@ import org.robolectric.android.controller.ServiceController
  * enforces a unique session ID per JVM and a leaked session
  * blocks the next [PlaybackService.onCreate] in the same run.
  *
- * Standard Robolectric service-lifecycle plumbing — no test
- * injection seam on the lib side.
+ * Standard Robolectric service-lifecycle driving — no test
+ * injection point on the lib side.
  */
 @UnstableApi
 internal class PlaybackServiceTestHandle(

package/android/src/test/java/com/margelo/nitro/queueplayer/SessionCommandForwardingPlayerTest.kt

@@ -27,7 +27,7 @@ import org.robolectric.annotation.Config
  *
  * The wrapper's `handle*` overrides are `protected` on a `final`
  * Kotlin class, so the suite drives them through [HandleDriver] — a
- * thin reflection seam onto the exact overridden methods — to assert
+ * thin reflection helper into the exact overridden methods — to assert
  * the routing directly without standing up a live `MediaController`.
  *
  * Controller-vs-internal gating turns on whether
@@ -422,7 +422,7 @@ class SessionCommandForwardingPlayerTest {
   }
 
   /**
-   * Reflection seam onto a [SessionCommandForwardingPlayer]'s
+   * Reflection helper into a [SessionCommandForwardingPlayer]'s
    * `protected` `handle*` overrides. The wrapper is a `final` Kotlin
    * class so it cannot be subclassed; reflecting straight onto the
    * declared overrides invokes the exact production methods without

package/android/src/test/java/com/margelo/nitro/queueplayer/ShadowDynamicsProcessingRejectingEnable.kt

@@ -0,0 +1,19 @@
+package com.margelo.nitro.queueplayer
+
+import android.media.audiofx.DynamicsProcessing
+import org.robolectric.annotation.Implements
+import org.robolectric.shadows.ShadowDynamicsProcessing
+
+/**
+ * A [DynamicsProcessing] whose construction and band writes succeed and
+ * whose `setEnabled` throws. The framework constructor never calls
+ * `setEnabled`; the engine does, after applying the bands and before
+ * recording the attach — so this is the one call that fails an attach
+ * inside its configure step rather than at construction.
+ */
+@Implements(DynamicsProcessing::class)
+class ShadowDynamicsProcessingRejectingEnable : ShadowDynamicsProcessing() {
+
+  override fun native_setEnabled(enabled: Boolean): Int =
+    throw IllegalStateException("setEnabled() called on uninitialized AudioEffect")
+}

package/android/src/test/java/com/margelo/nitro/queueplayer/ShadowEqualizer.kt

@@ -20,7 +20,7 @@ import java.util.Optional
  * [Equalizer] API.
  */
 @Implements(Equalizer::class)
-class ShadowEqualizer : ShadowAudioEffect() {
+open class ShadowEqualizer : ShadowAudioEffect() {
 
   override fun getDefaultParameter(parameter: ByteBuffer): Optional<ByteBuffer> {
     val key = parameter.duplicate().order(ByteOrder.nativeOrder())

package/android/src/test/java/com/margelo/nitro/queueplayer/ShadowEqualizerRejectingBandWrites.kt

@@ -0,0 +1,27 @@
+package com.margelo.nitro.queueplayer
+
+import android.media.audiofx.AudioEffect
+import android.media.audiofx.Equalizer
+import org.robolectric.annotation.Implements
+import java.nio.ByteBuffer
+import java.nio.ByteOrder
+
+/**
+ * A five-band equalizer whose construction and parameter reads succeed and
+ * whose first band-level write fails, so an attach reaches its configure
+ * step and throws there. `Equalizer.setBandLevel` routes the returned error
+ * through `checkStatus`, which raises `RuntimeException`.
+ */
+@Implements(Equalizer::class)
+class ShadowEqualizerRejectingBandWrites : ShadowEqualizer() {
+
+  override fun native_setParameter(psize: Int, param: ByteArray, vsize: Int, value: ByteArray): Int {
+    val id = ByteBuffer.wrap(param).order(ByteOrder.nativeOrder()).int
+    if (id == PARAM_BAND_LEVEL) return AudioEffect.ERROR_INVALID_OPERATION
+    return super.native_setParameter(psize, param, vsize, value)
+  }
+
+  private companion object {
+    const val PARAM_BAND_LEVEL = 2
+  }
+}

package/android/src/test/java/com/margelo/nitro/queueplayer/SuppliedReplayGainTest.kt

@@ -0,0 +1,61 @@
+package com.margelo.nitro.queueplayer
+
+import androidx.media3.common.util.UnstableApi
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNotNull
+import org.junit.Assert.assertNull
+import org.junit.Test
+
+/**
+ * [SuppliedReplayGain.from] separates the consumer's claim over a track
+ * from the values that survive validation: any present field claims the
+ * track, and only accepted values are carried.
+ */
+@UnstableApi
+class SuppliedReplayGainTest {
+
+  @Test
+  fun `a track with no ReplayGain field makes no claim`() {
+    assertNull(SuppliedReplayGain.from(track()))
+  }
+
+  @Test
+  fun `one valid field claims the track and is carried`() {
+    val claim = SuppliedReplayGain.from(track(trackGain = -3.0))
+
+    assertNotNull(claim)
+    assertEquals(
+      ReplayGainData(trackGainDb = -3.0f, trackPeak = null, albumGainDb = null, albumPeak = null),
+      claim?.data)
+  }
+
+  @Test
+  fun `only invalid fields still claim the track but carry nothing`() {
+    val claim = SuppliedReplayGain.from(
+      track(trackGain = Double.NaN, trackPeak = 5.0, albumGain = Double.POSITIVE_INFINITY, albumPeak = 0.0))
+
+    assertNotNull("presence claims the track, whatever the values", claim)
+    assertNull("no value passed acceptance, so there is nothing to apply", claim?.data)
+  }
+
+  @Test
+  fun `a mix carries the accepted fields and drops the rest`() {
+    val claim = SuppliedReplayGain.from(
+      track(trackGain = -3.0, trackPeak = 5.0, albumGain = -9.0, albumPeak = 0.3))
+
+    assertEquals(
+      ReplayGainData(trackGainDb = -3.0f, trackPeak = null, albumGainDb = -9.0f, albumPeak = 0.3f),
+      claim?.data)
+  }
+
+  private fun track(
+    trackGain: Double? = null,
+    trackPeak: Double? = null,
+    albumGain: Double? = null,
+    albumPeak: Double? = null,
+  ) = TrackItem(
+    id = null, url = "https://example.com/a.mp3", title = null, artist = null, album = null,
+    duration = null, artworkUrl = null, extras = null,
+    replayGainTrackGain = trackGain, replayGainTrackPeak = trackPeak,
+    replayGainAlbumGain = albumGain, replayGainAlbumPeak = albumPeak)
+}

package/android/src/test/java/com/margelo/nitro/queueplayer/TrackPlayerAirPlayMetadataWiringTest.kt

@@ -38,7 +38,7 @@ import java.nio.ByteBuffer
  * stopped when the AirPlay engine is released or the session closes
  * (`MetadataAwareSession.onDeactivated`).
  *
- * The route flip is driven through the production seam — `CastSinkRouter`'s
+ * The route flip is driven through the production path — `CastSinkRouter`'s
  * activate/deactivate transitions, which `TrackPlayer`'s route listener turns
  * into a posted `applyEngineSwapForMode`. The sync itself is observed through a
  * fake [CastSession.PcmStream] that also implements [MetadataAwareSession] and
@@ -64,7 +64,7 @@ class TrackPlayerAirPlayMetadataWiringTest {
       PlayerConfig(
         httpHeaders = null, userAgent = null, autoRetries = null,
         retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null,
-        audioCategoryOptions = null, visualizationEnabled = null,
+        audioCategoryOptions = null, voiceVocabularyDonationEnabled = null, visualizationEnabled = null,
         clampSeekToBuffered = null,
       lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null,
       ),
@@ -74,8 +74,8 @@ class TrackPlayerAirPlayMetadataWiringTest {
     // matching the production path where `onActivated` is fired after the queue
     // install reads a populated player.
     player.tracks = listOf(
-      TrackItem("t1", "https://example.com/1.m4a", null, null, null, null, null, null),
-      TrackItem("t2", "https://example.com/2.m4a", null, null, null, null, null, null),
+      TrackItem("t1", "https://example.com/1.m4a", null, null, null, null, null, null, null, null, null, null),
+      TrackItem("t2", "https://example.com/2.m4a", null, null, null, null, null, null, null, null, null, null),
     )
     player.currentTrackIndex = 0
   }

package/android/src/test/java/com/margelo/nitro/queueplayer/TrackPlayerAudioFocusTest.kt

@@ -44,7 +44,7 @@ class TrackPlayerAudioFocusTest {
     player = TrackPlayer()
     serviceHandle = bindPlaybackServiceForTest(player, context())
     player.configureInternal(
-      PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null), context()
+      PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, voiceVocabularyDonationEnabled = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null), context()
     )
   }
 

package/android/src/test/java/com/margelo/nitro/queueplayer/TrackPlayerCastCommandRoutingTest.kt

@@ -41,7 +41,8 @@ class TrackPlayerCastCommandRoutingTest {
       PlayerConfig(
         httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null,
         networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null,
-        visualizationEnabled = null, clampSeekToBuffered = null,
+        voiceVocabularyDonationEnabled = null,
+      visualizationEnabled = null, clampSeekToBuffered = null,
         lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null,
         progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null,
         placeholderArtworkUri = null, skipToPreviousBehavior = null

package/android/src/test/java/com/margelo/nitro/queueplayer/TrackPlayerCastStateTest.kt

@@ -40,7 +40,8 @@ class TrackPlayerCastStateTest {
       PlayerConfig(
         httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null,
         networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null,
-        visualizationEnabled = null, clampSeekToBuffered = null,
+        voiceVocabularyDonationEnabled = null,
+      visualizationEnabled = null, clampSeekToBuffered = null,
         lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null,
         progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null,
         placeholderArtworkUri = null, skipToPreviousBehavior = null