react-native-queue-player 1.0.0

package/ios/Tests/QueueMutationArithmeticTests.swift

@@ -0,0 +1,245 @@
+import XCTest
+@testable import QueuePlayer
+@_spi(QueuePlayerTests) import QueuePlayer
+
+/// Pure-Swift tests for the queue-mutation index-shift arithmetic.
+/// 1:1 mirror of `android/.../QueueMutationArithmeticTest.kt` —
+/// every Kotlin test name has a Swift twin so the cross-platform
+/// matrix stays in lock-step.
+final class QueueMutationArithmeticTests: XCTestCase {
+
+  // MARK: - clampInsertBefore
+
+  func testClampInsertBeforeNilAppendsToEnd() {
+    XCTAssertEqual(QueueMutationArithmetic.clampInsertBefore(insertBefore: nil, trackCount: 5), 5)
+  }
+
+  func testClampInsertBeforeNegativeClampsToZero() {
+    XCTAssertEqual(QueueMutationArithmetic.clampInsertBefore(insertBefore: -1, trackCount: 5), 0)
+    XCTAssertEqual(QueueMutationArithmetic.clampInsertBefore(insertBefore: -100, trackCount: 5), 0)
+  }
+
+  func testClampInsertBeforePastTrackCountClampsToTrackCount() {
+    XCTAssertEqual(QueueMutationArithmetic.clampInsertBefore(insertBefore: 100, trackCount: 5), 5)
+  }
+
+  func testClampInsertBeforeInRangePassesThrough() {
+    XCTAssertEqual(QueueMutationArithmetic.clampInsertBefore(insertBefore: 3, trackCount: 5), 3)
+    XCTAssertEqual(QueueMutationArithmetic.clampInsertBefore(insertBefore: 0, trackCount: 5), 0)
+    XCTAssertEqual(QueueMutationArithmetic.clampInsertBefore(insertBefore: 5, trackCount: 5), 5)
+  }
+
+  // MARK: - currentIndexAfterAdd
+
+  func testAfterAddEmptyQueueCurStaysMinusOne() {
+    XCTAssertEqual(
+      QueueMutationArithmetic.currentIndexAfterAdd(currentIndex: -1, insertAt: 0, count: 3),
+      -1
+    )
+  }
+
+  func testAfterAddInsertCountZeroIsNoOp() {
+    XCTAssertEqual(
+      QueueMutationArithmetic.currentIndexAfterAdd(currentIndex: 2, insertAt: 0, count: 0),
+      2
+    )
+  }
+
+  func testAfterAddInsertAtExactlyCurShiftsCurForward() {
+    // Insert of 3 items at position 2 when cur == 2 moves cur to 5.
+    XCTAssertEqual(
+      QueueMutationArithmetic.currentIndexAfterAdd(currentIndex: 2, insertAt: 2, count: 3),
+      5
+    )
+  }
+
+  func testAfterAddInsertBeforeCurShiftsCurForward() {
+    XCTAssertEqual(
+      QueueMutationArithmetic.currentIndexAfterAdd(currentIndex: 2, insertAt: 1, count: 2),
+      4
+    )
+  }
+
+  func testAfterAddInsertAfterCurLeavesCurUnchanged() {
+    XCTAssertEqual(
+      QueueMutationArithmetic.currentIndexAfterAdd(currentIndex: 2, insertAt: 4, count: 3),
+      2
+    )
+  }
+
+  func testAfterAddInsertAtQueueTailLeavesCurUnchanged() {
+    XCTAssertEqual(
+      QueueMutationArithmetic.currentIndexAfterAdd(currentIndex: 2, insertAt: 5, count: 3),
+      2
+    )
+  }
+
+  // MARK: - sanitiseRemoveIndices
+
+  func testSanitiseDropsNegativeAndOutOfRange() {
+    XCTAssertEqual(
+      QueueMutationArithmetic.sanitiseRemoveIndices(
+        rawIndices: [-1, 0, 2, 5, 100], trackCount: 5
+      ),
+      [0, 2]
+    )
+  }
+
+  func testSanitiseDedupsAndSortsAscending() {
+    XCTAssertEqual(
+      QueueMutationArithmetic.sanitiseRemoveIndices(
+        rawIndices: [3, 1, 3, 2, 1], trackCount: 5
+      ),
+      [1, 2, 3]
+    )
+  }
+
+  func testSanitiseEmptyInputReturnsEmpty() {
+    XCTAssertEqual(
+      QueueMutationArithmetic.sanitiseRemoveIndices(rawIndices: [], trackCount: 5),
+      []
+    )
+  }
+
+  func testSanitiseTrackCountZeroReturnsEmpty() {
+    XCTAssertEqual(
+      QueueMutationArithmetic.sanitiseRemoveIndices(rawIndices: [0, 1], trackCount: 0),
+      []
+    )
+  }
+
+  // MARK: - currentIndexAfterRemove
+
+  func testAfterRemoveCurNegativeStaysMinusOne() {
+    XCTAssertEqual(
+      QueueMutationArithmetic.currentIndexAfterRemove(
+        currentIndex: -1, sanitisedIndices: [0, 1], trackCountBefore: 5
+      ),
+      -1
+    )
+  }
+
+  func testAfterRemoveBelowCurShiftsCurDown() {
+    // cur=3, remove [0,1] → cur shifts to 1.
+    XCTAssertEqual(
+      QueueMutationArithmetic.currentIndexAfterRemove(
+        currentIndex: 3, sanitisedIndices: [0, 1], trackCountBefore: 5
+      ),
+      1
+    )
+  }
+
+  func testAfterRemoveAboveCurLeavesCurUnchanged() {
+    XCTAssertEqual(
+      QueueMutationArithmetic.currentIndexAfterRemove(
+        currentIndex: 1, sanitisedIndices: [3, 4], trackCountBefore: 5
+      ),
+      1
+    )
+  }
+
+  func testAfterRemoveCurItselfKeepsCurAutoAdvanceSemantics() {
+    // cur=2, remove [2] → newCur stays 2 (now points to what was at 3).
+    XCTAssertEqual(
+      QueueMutationArithmetic.currentIndexAfterRemove(
+        currentIndex: 2, sanitisedIndices: [2], trackCountBefore: 5
+      ),
+      2
+    )
+  }
+
+  func testAfterRemoveCurAtTailClampsToNewTail() {
+    // cur=4 (last), remove [4] → newTrackCount=4, cur clamps to 3.
+    XCTAssertEqual(
+      QueueMutationArithmetic.currentIndexAfterRemove(
+        currentIndex: 4, sanitisedIndices: [4], trackCountBefore: 5
+      ),
+      3
+    )
+  }
+
+  func testAfterRemoveEverythingReturnsMinusOne() {
+    XCTAssertEqual(
+      QueueMutationArithmetic.currentIndexAfterRemove(
+        currentIndex: 2, sanitisedIndices: [0, 1, 2, 3, 4], trackCountBefore: 5
+      ),
+      -1
+    )
+  }
+
+  func testAfterRemoveMixedBelowAndCurCombinesShiftAndClamp() {
+    // cur=3, remove [0, 3] → removedBelow=1, newCur=2; cur was
+    // removed but 2 < newTrackCount(3) so no clamp.
+    XCTAssertEqual(
+      QueueMutationArithmetic.currentIndexAfterRemove(
+        currentIndex: 3, sanitisedIndices: [0, 3], trackCountBefore: 5
+      ),
+      2
+    )
+  }
+
+  // MARK: - currentIndexAfterMove
+
+  func testAfterMoveCurNegativeStaysNegative() {
+    XCTAssertEqual(
+      QueueMutationArithmetic.currentIndexAfterMove(currentIndex: -1, fromIndex: 0, toIndex: 2),
+      -1
+    )
+  }
+
+  func testAfterMoveMovingCurTracksIt() {
+    // cur=2, move [2 → 4]. newCur = 4.
+    XCTAssertEqual(
+      QueueMutationArithmetic.currentIndexAfterMove(currentIndex: 2, fromIndex: 2, toIndex: 4),
+      4
+    )
+  }
+
+  func testAfterMoveSlidePastCurFromBelowShiftsCurDown() {
+    // cur=3, move [1 → 4]. newCur = 2.
+    XCTAssertEqual(
+      QueueMutationArithmetic.currentIndexAfterMove(currentIndex: 3, fromIndex: 1, toIndex: 4),
+      2
+    )
+  }
+
+  func testAfterMoveSlidePastCurFromAboveShiftsCurUp() {
+    // cur=1, move [3 → 0]. newCur = 2.
+    XCTAssertEqual(
+      QueueMutationArithmetic.currentIndexAfterMove(currentIndex: 1, fromIndex: 3, toIndex: 0),
+      2
+    )
+  }
+
+  func testAfterMoveEntirelyBelowCurLeavesCurAlone() {
+    // cur=4, move [0 → 2].
+    XCTAssertEqual(
+      QueueMutationArithmetic.currentIndexAfterMove(currentIndex: 4, fromIndex: 0, toIndex: 2),
+      4
+    )
+  }
+
+  func testAfterMoveEntirelyAboveCurLeavesCurAlone() {
+    // cur=1, move [3 → 4].
+    XCTAssertEqual(
+      QueueMutationArithmetic.currentIndexAfterMove(currentIndex: 1, fromIndex: 3, toIndex: 4),
+      1
+    )
+  }
+
+  func testAfterMoveToExactlyCurFromBelowShiftsCurDownByOne() {
+    // cur=2, from=0, to=2. newCur = 1.
+    XCTAssertEqual(
+      QueueMutationArithmetic.currentIndexAfterMove(currentIndex: 2, fromIndex: 0, toIndex: 2),
+      1
+    )
+  }
+
+  func testAfterMoveToExactlyCurFromAboveShiftsCurUpByOne() {
+    // cur=2, from=4, to=2. newCur = 3.
+    XCTAssertEqual(
+      QueueMutationArithmetic.currentIndexAfterMove(currentIndex: 2, fromIndex: 4, toIndex: 2),
+      3
+    )
+  }
+}

package/ios/Tests/RemoteCommandsTests.swift

@@ -0,0 +1,147 @@
+import MediaPlayer
+import XCTest
+@testable import QueuePlayer
+
+/// `RemoteCommands` owns the `MPRemoteCommandCenter.shared()` handler
+/// registrations + the per-command `isEnabled` state. Tests pin the
+/// install / uninstall lifecycle and the `setSkipCapability` ->
+/// `nextTrackCommand.isEnabled` / `previousTrackCommand.isEnabled`
+/// mapping. Dispatch into the owner's `onCommand` closure is verified
+/// at the integration layer (Maestro suite + JS-visible reason
+/// classification); attempting to fire `MPRemoteCommandCenter`
+/// handlers from XCTest would require lib-side SPI we deliberately
+/// do not ship.
+///
+/// The shared command center is process-global. `setUp` resets all
+/// seven commands the lib touches, `tearDown` calls `uninstall()` to
+/// release any handlers leaked from a crashing test.
+final class RemoteCommandsTests: XCTestCase {
+
+  private var commands: RemoteCommands!
+
+  override func setUp() {
+    super.setUp()
+    resetSharedCenter()
+    commands = RemoteCommands()
+  }
+
+  override func tearDown() {
+    commands.uninstall()
+    commands = nil
+    resetSharedCenter()
+    super.tearDown()
+  }
+
+  // MARK: - install / uninstall
+
+  func testInstallEnablesAllOwnedCommands() {
+    let center = MPRemoteCommandCenter.shared()
+    commands.install()
+    XCTAssertTrue(center.playCommand.isEnabled)
+    XCTAssertTrue(center.pauseCommand.isEnabled)
+    XCTAssertTrue(center.togglePlayPauseCommand.isEnabled)
+    XCTAssertTrue(center.stopCommand.isEnabled)
+    XCTAssertTrue(center.nextTrackCommand.isEnabled)
+    XCTAssertTrue(center.previousTrackCommand.isEnabled)
+    XCTAssertTrue(center.changePlaybackPositionCommand.isEnabled)
+  }
+
+  func testUninstallDisablesAllOwnedCommands() {
+    let center = MPRemoteCommandCenter.shared()
+    commands.install()
+    commands.uninstall()
+    XCTAssertFalse(center.playCommand.isEnabled)
+    XCTAssertFalse(center.pauseCommand.isEnabled)
+    XCTAssertFalse(center.togglePlayPauseCommand.isEnabled)
+    XCTAssertFalse(center.stopCommand.isEnabled)
+    XCTAssertFalse(center.nextTrackCommand.isEnabled)
+    XCTAssertFalse(center.previousTrackCommand.isEnabled)
+    XCTAssertFalse(center.changePlaybackPositionCommand.isEnabled)
+  }
+
+  func testInstallTwiceLeavesEnabledStatesIntact() {
+    let center = MPRemoteCommandCenter.shared()
+    commands.install()
+    commands.install()
+    XCTAssertTrue(center.playCommand.isEnabled)
+    XCTAssertTrue(center.nextTrackCommand.isEnabled)
+    commands.uninstall()
+    XCTAssertFalse(center.playCommand.isEnabled)
+  }
+
+  func testUninstallWithoutInstallIsNoOp() {
+    let center = MPRemoteCommandCenter.shared()
+    let priorPlay = center.playCommand.isEnabled
+    commands.uninstall()
+    commands.uninstall()
+    XCTAssertEqual(center.playCommand.isEnabled, priorPlay)
+  }
+
+  func testUninstallDoesNotTouchUnownedCommands() {
+    let center = MPRemoteCommandCenter.shared()
+    center.seekForwardCommand.isEnabled = true
+    center.skipBackwardCommand.isEnabled = true
+    commands.install()
+    commands.uninstall()
+    XCTAssertTrue(center.seekForwardCommand.isEnabled,
+                  "seekForward is not lib-owned; uninstall must leave it alone")
+    XCTAssertTrue(center.skipBackwardCommand.isEnabled,
+                  "skipBackward is not lib-owned; uninstall must leave it alone")
+  }
+
+  // MARK: - setSkipCapability
+
+  func testSetSkipCapabilityNoOpWhenNotInstalled() {
+    let center = MPRemoteCommandCenter.shared()
+    let priorNext = center.nextTrackCommand.isEnabled
+    let priorPrev = center.previousTrackCommand.isEnabled
+    commands.setSkipCapability(canSkipNext: !priorNext, canSkipPrevious: !priorPrev)
+    XCTAssertEqual(center.nextTrackCommand.isEnabled, priorNext)
+    XCTAssertEqual(center.previousTrackCommand.isEnabled, priorPrev)
+  }
+
+  func testSetSkipCapabilityFlipsIsEnabledWhenInstalled() {
+    let center = MPRemoteCommandCenter.shared()
+    commands.install()
+    commands.setSkipCapability(canSkipNext: false, canSkipPrevious: false)
+    XCTAssertFalse(center.nextTrackCommand.isEnabled)
+    XCTAssertFalse(center.previousTrackCommand.isEnabled)
+    commands.setSkipCapability(canSkipNext: true, canSkipPrevious: true)
+    XCTAssertTrue(center.nextTrackCommand.isEnabled)
+    XCTAssertTrue(center.previousTrackCommand.isEnabled)
+  }
+
+  func testSetSkipCapabilityNoOpAfterUninstall() {
+    let center = MPRemoteCommandCenter.shared()
+    commands.install()
+    commands.uninstall()
+    let priorNext = center.nextTrackCommand.isEnabled
+    let priorPrev = center.previousTrackCommand.isEnabled
+    commands.setSkipCapability(canSkipNext: true, canSkipPrevious: true)
+    XCTAssertEqual(center.nextTrackCommand.isEnabled, priorNext)
+    XCTAssertEqual(center.previousTrackCommand.isEnabled, priorPrev)
+  }
+
+  // MARK: - Helpers
+
+  /// Reset the seven lib-owned commands on the process-global
+  /// `MPRemoteCommandCenter.shared()`. Targets registered by other
+  /// tests / debug code are best-effort cleared via `removeTarget(nil)`
+  /// (Apple-documented as "remove all targets").
+  private func resetSharedCenter() {
+    let center = MPRemoteCommandCenter.shared()
+    let owned: [MPRemoteCommand] = [
+      center.playCommand,
+      center.pauseCommand,
+      center.togglePlayPauseCommand,
+      center.stopCommand,
+      center.nextTrackCommand,
+      center.previousTrackCommand,
+      center.changePlaybackPositionCommand,
+    ]
+    for cmd in owned {
+      cmd.removeTarget(nil)
+      cmd.isEnabled = false
+    }
+  }
+}

package/ios/Tests/ReplayGainExtractorTests.swift

@@ -0,0 +1,197 @@
+import XCTest
+@testable import QueuePlayer
+
+/// Unit tests for `ReplayGainExtractor`'s pure string parsers
+/// (`parseGainDb`, `parsePeak`) and the `selectGain(mode:)` matrix
+/// on `ReplayGainData`.
+///
+/// Container-level extraction (ID3v2 TXXX, FLAC Vorbis, MP4
+/// freeform) is covered by `MetadataReaderTests`. End-to-end
+/// extraction-on-load is covered by the auto-suite `replaygain.ts`
+/// step.
+final class ReplayGainExtractorTests: XCTestCase {
+
+  // Helper: `XCTAssertEqual` with the `accuracy:` overload requires
+  // non-optional matching types. Lift the parser's `Double?` to
+  // `Double` (failing the assertion early on `nil`) so test bodies
+  // stay readable.
+  private func assertGain(
+    _ raw: String,
+    expected: Double,
+    accuracy: Double = 0.001,
+    file: StaticString = #file, line: UInt = #line
+  ) {
+    guard let actual = ReplayGainExtractor.parseGainDb(raw) else {
+      XCTFail("expected parseGainDb(\"\(raw)\") to succeed", file: file, line: line)
+      return
+    }
+    XCTAssertEqual(actual, expected, accuracy: accuracy, file: file, line: line)
+  }
+
+  private func assertPeak(
+    _ raw: String,
+    expected: Double,
+    accuracy: Double = 0.0001,
+    file: StaticString = #file, line: UInt = #line
+  ) {
+    guard let actual = ReplayGainExtractor.parsePeak(raw) else {
+      XCTFail("expected parsePeak(\"\(raw)\") to succeed", file: file, line: line)
+      return
+    }
+    XCTAssertEqual(actual, expected, accuracy: accuracy, file: file, line: line)
+  }
+
+  // MARK: - parseGainDb tolerance
+
+  func testParseGainDbStandardFormat() {
+    assertGain("-6.54 dB", expected: -6.54)
+    assertGain("+3.21 dB", expected: 3.21)
+    assertGain("0.00 dB", expected: 0.0)
+  }
+
+  func testParseGainDbAcceptsBareNumberWithoutSuffix() {
+    assertGain("-6.54", expected: -6.54)
+    assertGain("+3.21", expected: 3.21)
+  }
+
+  func testParseGainDbAcceptsMissingSpaceBeforeDb() {
+    assertGain("-6.54dB", expected: -6.54)
+  }
+
+  func testParseGainDbToleratesWhitespace() {
+    assertGain("  -1.0 dB  ", expected: -1.0)
+    assertGain("\t-6.54 dB\n", expected: -6.54)
+  }
+
+  func testParseGainDbToleratesInternalWhitespace() {
+    // Per NOTES.md §25 — extra-internal whitespace is tolerated.
+    // Some taggers emit the sign separated from the digits.
+    assertGain("- 6.54 dB", expected: -6.54)
+    assertGain("+ 3.21 dB", expected: 3.21)
+    assertGain("-6 .54 dB", expected: -6.54)
+  }
+
+  func testParseGainDbCaseInsensitiveSuffix() {
+    assertGain("-6.54 DB", expected: -6.54)
+    assertGain("-6.54 Db", expected: -6.54)
+  }
+
+  func testParseGainDbNormalisesUnicodeMinusSign() {
+    // U+2212 MINUS SIGN — emitted by some mac-based taggers.
+    assertGain("\u{2212}6.54 dB", expected: -6.54)
+  }
+
+  func testParseGainDbRejectsCommaDecimal() {
+    // RG2 spec is period-decimal only.
+    XCTAssertNil(ReplayGainExtractor.parseGainDb("-6,54 dB"))
+  }
+
+  func testParseGainDbRejectsNonNumeric() {
+    XCTAssertNil(ReplayGainExtractor.parseGainDb("abc"))
+    XCTAssertNil(ReplayGainExtractor.parseGainDb(""))
+    XCTAssertNil(ReplayGainExtractor.parseGainDb("dB"))
+    XCTAssertNil(ReplayGainExtractor.parseGainDb(" "))
+  }
+
+  func testParseGainDbRejectsNaNAndInf() {
+    XCTAssertNil(ReplayGainExtractor.parseGainDb("nan dB"))
+    XCTAssertNil(ReplayGainExtractor.parseGainDb("inf dB"))
+    XCTAssertNil(ReplayGainExtractor.parseGainDb("-inf"))
+  }
+
+  // MARK: - parsePeak tolerance + encoder-default detection
+
+  func testParsePeakStandardLinear() {
+    assertPeak("0.987654", expected: 0.987654)
+    assertPeak("0.5", expected: 0.5)
+    assertPeak("1.234567", expected: 1.234567)
+  }
+
+  func testParsePeakRejectsEncoderDefaultsOneAndZero() {
+    XCTAssertNil(ReplayGainExtractor.parsePeak("1.000000"),
+                 "peak == exactly 1.0 means the analyser didn't run")
+    XCTAssertNil(ReplayGainExtractor.parsePeak("1"),
+                 "peak == exactly 1.0 means the analyser didn't run")
+    XCTAssertNil(ReplayGainExtractor.parsePeak("0.0001"),
+                 "peak < 0.001 means encoder zero / no analysis")
+    XCTAssertNil(ReplayGainExtractor.parsePeak("0"),
+                 "peak == 0 means encoder zero")
+  }
+
+  func testParsePeakRejectsOutOfRange() {
+    XCTAssertNil(ReplayGainExtractor.parsePeak("-0.5"))
+    XCTAssertNil(ReplayGainExtractor.parsePeak("3.0"))
+  }
+
+  func testParsePeakRejectsUnparseable() {
+    XCTAssertNil(ReplayGainExtractor.parsePeak("abc"))
+    XCTAssertNil(ReplayGainExtractor.parsePeak(""))
+    XCTAssertNil(ReplayGainExtractor.parsePeak("nan"))
+    XCTAssertNil(ReplayGainExtractor.parsePeak("inf"))
+  }
+
+  // MARK: - selectGain matrix on ReplayGainData
+
+  func testSelectGainOff() {
+    let data = ReplayGainData(trackGainDb: -12, trackPeak: 0.95,
+                              albumGainDb: -8, albumPeak: 0.90)
+    let (g, p) = data.selectGain(mode: .off)
+    XCTAssertNil(g)
+    XCTAssertNil(p)
+  }
+
+  func testSelectGainTrack() throws {
+    let data = ReplayGainData(trackGainDb: -12, trackPeak: 0.95,
+                              albumGainDb: -8, albumPeak: 0.90)
+    let (g, p) = data.selectGain(mode: .track)
+    XCTAssertEqual(try XCTUnwrap(g), -12, accuracy: 0.001)
+    XCTAssertEqual(try XCTUnwrap(p), 0.95, accuracy: 0.001)
+  }
+
+  func testSelectGainAlbum() throws {
+    let data = ReplayGainData(trackGainDb: -12, trackPeak: 0.95,
+                              albumGainDb: -8, albumPeak: 0.90)
+    let (g, p) = data.selectGain(mode: .album)
+    XCTAssertEqual(try XCTUnwrap(g), -8, accuracy: 0.001)
+    XCTAssertEqual(try XCTUnwrap(p), 0.90, accuracy: 0.001)
+  }
+
+  func testSelectGainAlbumStrictNoFallback() throws {
+    // album-only-missing scenario: track tag present, album not.
+    // strict mode → album returns nil pair (no fallback to track).
+    let data = ReplayGainData(trackGainDb: -6, trackPeak: 0.92,
+                              albumGainDb: nil, albumPeak: nil)
+    let (g, p) = data.selectGain(mode: .album)
+    XCTAssertNil(g, "strict album mode does NOT fall back to track gain")
+    XCTAssertNil(p)
+
+    // ... but track mode on the same data returns the track values.
+    let (gT, pT) = data.selectGain(mode: .track)
+    XCTAssertEqual(try XCTUnwrap(gT), -6, accuracy: 0.001)
+    XCTAssertEqual(try XCTUnwrap(pT), 0.92, accuracy: 0.001)
+  }
+
+  func testSelectGainTrackOnlyAlbumPresent() throws {
+    // Inverse: only album tag present (rare but possible).
+    // track mode returns nil pair; album mode returns the values.
+    let data = ReplayGainData(trackGainDb: nil, trackPeak: nil,
+                              albumGainDb: -9, albumPeak: 0.88)
+    let (gT, pT) = data.selectGain(mode: .track)
+    XCTAssertNil(gT)
+    XCTAssertNil(pT)
+    let (gA, pA) = data.selectGain(mode: .album)
+    XCTAssertEqual(try XCTUnwrap(gA), -9, accuracy: 0.001)
+    XCTAssertEqual(try XCTUnwrap(pA), 0.88, accuracy: 0.001)
+  }
+
+  func testSelectGainAllNil() {
+    let data = ReplayGainData(trackGainDb: nil, trackPeak: nil,
+                              albumGainDb: nil, albumPeak: nil)
+    for mode in [ReplayGainSelectorMode.off, .track, .album] {
+      let (g, p) = data.selectGain(mode: mode)
+      XCTAssertNil(g, "mode \(mode) should return nil gain")
+      XCTAssertNil(p, "mode \(mode) should return nil peak")
+    }
+  }
+
+}

package/ios/Tests/ReplayGainProcessorTests.swift

@@ -0,0 +1,90 @@
+import XCTest
+@testable import QueuePlayer
+
+/// Unit tests for `ReplayGainProcessor` — the standalone Float32
+/// gain stage. Covers identity-at-unity, scaling shapes, dB→linear
+/// math, and contention on `setLinearGain` while `process` runs.
+final class ReplayGainProcessorTests: XCTestCase {
+
+  // MARK: - Gain shapes
+
+  func testProcessIsIdentityAtUnityGain() {
+    let processor = ReplayGainProcessor()
+    var samples: [Float] = [-1.0, -0.5, 0.0, 0.25, 1.0]
+    let original = samples
+    samples.withUnsafeMutableBufferPointer { ptr in
+      processor.process(buffer: ptr.baseAddress!, frames: ptr.count)
+    }
+    XCTAssertEqual(samples, original, "unity gain should not mutate the buffer")
+  }
+
+  func testProcessHalvesAtHalfGain() {
+    let processor = ReplayGainProcessor()
+    processor.setLinearGain(0.5)
+    var samples: [Float] = [1.0, 0.5, -0.5, -1.0, 0.0]
+    let expected: [Float] = [0.5, 0.25, -0.25, -0.5, 0.0]
+    samples.withUnsafeMutableBufferPointer { ptr in
+      processor.process(buffer: ptr.baseAddress!, frames: ptr.count)
+    }
+    for (s, e) in zip(samples, expected) {
+      XCTAssertEqual(s, e, accuracy: 0.0001)
+    }
+  }
+
+  func testProcessZeroesAtZeroGain() {
+    let processor = ReplayGainProcessor()
+    processor.setLinearGain(0.0)
+    var samples: [Float] = [1.0, 0.5, -0.5, -1.0, 0.25]
+    samples.withUnsafeMutableBufferPointer { ptr in
+      processor.process(buffer: ptr.baseAddress!, frames: ptr.count)
+    }
+    XCTAssertEqual(samples, [0, 0, 0, 0, 0])
+  }
+
+  // MARK: - Gain attenuation matches dB→linear conversion
+
+  func testProcessAttenuatesByDbValue() {
+    // -6 dB ≈ 0.5012 linear. Confirms the math at the call-site
+    // (`linearGain = pow(10, dB/20)`) lines up with the processor.
+    let processor = ReplayGainProcessor()
+    let linear = Float(pow(10.0, -6.0 / 20.0))
+    processor.setLinearGain(linear)
+
+    var samples = Array<Float>(repeating: 1.0, count: 64)
+    samples.withUnsafeMutableBufferPointer { ptr in
+      processor.process(buffer: ptr.baseAddress!, frames: ptr.count)
+    }
+    for s in samples {
+      XCTAssertEqual(s, linear, accuracy: 0.0001)
+    }
+  }
+
+  // MARK: - Threading
+
+  func testSetLinearGainAndProcessRunConcurrentlyWithoutCrash() {
+    let processor = ReplayGainProcessor()
+    let writerExp = expectation(description: "writer finished")
+    let readerExp = expectation(description: "reader finished")
+
+    let writerQueue = DispatchQueue(label: "rg.writer")
+    let readerQueue = DispatchQueue(label: "rg.reader")
+
+    writerQueue.async {
+      for i in 0..<2_000 {
+        processor.setLinearGain(Float(i % 100) / 100.0)
+      }
+      writerExp.fulfill()
+    }
+    readerQueue.async {
+      var samples = Array<Float>(repeating: 0.5, count: 256)
+      for _ in 0..<2_000 {
+        samples.withUnsafeMutableBufferPointer { ptr in
+          processor.process(buffer: ptr.baseAddress!, frames: ptr.count)
+        }
+      }
+      readerExp.fulfill()
+    }
+
+    wait(for: [writerExp, readerExp], timeout: 10)
+  }
+}