react-native-audio-browser 0.2.0-next.33 → 0.2.0-next.35

package/ios/Model/RemoteCommand.swift

@@ -1,89 +1,17 @@
 import Foundation
 
-// Internal on purpose: nothing outside the module uses this, and a public
-// declaration gets printed into the generated -Swift.h C++ interop section,
-// where the [NSNumber] associated values don't compile for plain-C++
-// consumers of the header (Xcode 26.2 / Swift 6.2).
-enum RemoteCommand: CustomStringConvertible, Equatable {
+/// A system remote command (lock screen, Control Center, CarPlay, headset). The skip intervals
+/// and the playback rates the commands offer go to `RemoteCommandController.enable` beside them.
+enum RemoteCommand: CaseIterable, Hashable {
   case play
-
   case pause
-
   case stop
-
-  case togglePlayPause
-
   case next
-
   case previous
-
   case changePlaybackPosition
-
-  case skipForward(preferredIntervals: [NSNumber])
-
-  case skipBackward(preferredIntervals: [NSNumber])
-
+  case skipForward
+  case skipBackward
   case changeRepeatMode
-
   case changeShuffleMode
-
-  case changePlaybackRate(supportedPlaybackRates: [NSNumber])
-
-  var description: String {
-    switch self {
-    case .play: "play"
-    case .pause: "pause"
-    case .stop: "stop"
-    case .togglePlayPause: "togglePlayPause"
-    case .next: "nextTrack"
-    case .previous: "previousTrack"
-    case .changePlaybackPosition: "changePlaybackPosition"
-    case .skipForward: "skipForward"
-    case .skipBackward: "skipBackward"
-    case .changeRepeatMode: "changeRepeatMode"
-    case .changeShuffleMode: "changeShuffleMode"
-    case .changePlaybackRate: "changePlaybackRate"
-    }
-  }
-
-  var key: String { description }
-
-  /**
-   Commands in `self` that are absent from `next` and so should be disabled.
-
-   Compared by `key`, not by `==`. `RemoteCommand` is `Equatable` including its
-   associated values, but every case with associated values maps onto a single
-   `MPRemoteCommand` addressed by `key`: `.skipForward([15])` and
-   `.skipForward([30])` are two different values of one command. Diffing by `==`
-   would report the old interval as removed and disable the command that the new
-   interval had just re-enabled.
-   */
-  static func commandsToDisable(
-    enabled: [RemoteCommand],
-    replacedBy next: [RemoteCommand],
-  ) -> [RemoteCommand] {
-    let nextKeys = Set(next.map(\.key))
-    return enabled.filter { !nextKeys.contains($0.key) }
-  }
-
-  /**
-   All values in an array for convenience.
-   Don't use for associated values.
-   */
-  static func all() -> [RemoteCommand] {
-    [
-      .play,
-      .pause,
-      .stop,
-      .togglePlayPause,
-      .next,
-      .previous,
-      .changePlaybackPosition,
-      .skipForward(preferredIntervals: []),
-      .skipBackward(preferredIntervals: []),
-      .changeRepeatMode,
-      .changeShuffleMode,
-      .changePlaybackRate(supportedPlaybackRates: []),
-    ]
-  }
+  case changePlaybackRate
 }

package/ios/Player/NowPlayingUpdater.swift

@@ -18,13 +18,11 @@ final class NowPlayingUpdater {
   var onChanged: ((NowPlayingMetadata) -> Void)?
 
   /// When false the surface shows the track's own fields: the override and formatter are ignored.
-  var enabled = true
+  private let enabled: Bool
   var formatter: ((_ params: FormatNowPlayingParams) -> Promise<NowPlayingUpdate?>)?
 
-  /// Whether the device is online, which tells a stall apart: offline or buffering.
-  var isOnline = true {
-    didSet { if isOnline != oldValue { render() } }
-  }
+  /// Tells a stall apart: offline or buffering.
+  private weak var networkStatus: (any NetworkStatusProviding)?
 
   private var override: NowPlayingUpdate?
   private var timedMetadata: TimedMetadata?
@@ -103,8 +101,16 @@ final class NowPlayingUpdater {
   /// formatter result (a flash overwrites it, `clearNowPlaying` empties it).
   private var formattedTrackId: String?
 
-  init(nowPlayingInfoController: NowPlayingInfoController) {
+  init(
+    nowPlayingInfoController: NowPlayingInfoController,
+    networkStatus: (any NetworkStatusProviding)?,
+    enabled: Bool,
+    formatter: ((_ params: FormatNowPlayingParams) -> Promise<NowPlayingUpdate?>)?,
+  ) {
     self.nowPlayingInfoController = nowPlayingInfoController
+    self.networkStatus = networkStatus
+    self.enabled = enabled
+    self.formatter = formatter
   }
 
   /// Pixel width to request now-playing artwork at: the active scene's screen
@@ -169,7 +175,7 @@ final class NowPlayingUpdater {
       track: track,
       timedMetadata: timedMetadata,
       playWhenReady: source.playWhenReady,
-      stalled: source.isStalled ? (isOnline ? .buffering : .offline) : nil,
+      stalled: source.isStalled ? ((networkStatus?.isOnline ?? true) ? .buffering : .offline) : nil,
       error: source.nitroPlaybackError,
     )
     // `@Sendable` breaks the @MainActor isolation inheritance: Nitro resolves the promise on the JS

package/ios/Player/Player.swift

@@ -216,12 +216,14 @@ final class Player {
   ///   - persistenceSaveInterval: How often the snapshot is saved while the play intent is active.
   init(
     engine: any PlayerEngine,
+    callbacks: PlayerCallbacks? = nil,
     retry: RetryLoop = RetryLoop(),
     sleepTimerScheduler: any SleepTimerScheduling = MainQueueSleepTimerScheduler(),
     persistenceDefaults: UserDefaults = PlaybackPersistence.standardDefaults,
     persistenceSaveInterval: Duration = .seconds(5),
   ) {
     self.engine = engine
+    self.callbacks = callbacks
     self.retry = retry
     sleepTimerManager = SleepTimerManager(
       fader: VolumeFader(
@@ -290,7 +292,8 @@ final class Player {
 
   /// Emits what changed since the last publish, in order: the play intent, the playing state,
   /// the playback (state and error), the terminal error, the active play intent. The one place
-  /// these leave the Player, so each goes out once per change.
+  /// these leave the Player, so each goes out once per change, with the audio-session and
+  /// now-playing effects it drives.
   private func publish() {
     let playing = playingState
     let now = Published(
@@ -302,13 +305,19 @@ final class Player {
     guard now != old else { return }
     published = now
     if now.playWhenReady != old.playWhenReady {
+      if now.playWhenReady { engine.cancelAudioSessionRelease() }
       callbacks?.playerDidChangePlayWhenReady(now.playWhenReady)
     }
     if now.playing != old.playing || now.buffering != old.buffering {
       callbacks?.playerDidChangePlayingState(playing)
+      // Activated on output, not at setup: activating at launch interrupts other apps' audio.
+      if playing.playing || playing.buffering { engine.activateAudioSession() }
+      // A stall starting or recovering may leave the state as it was.
+      engine.renderNowPlaying()
     }
     if now.state != old.state || now.errorStatus != old.errorStatus {
       callbacks?.playerDidChangePlayback(Playback(state: now.state, error: now.errorStatus.nitroError))
+      engine.renderNowPlaying()
     }
     let erred = now.state == .error, wasErred = old.state == .error
     if erred != wasErred || (erred && now.errorStatus != old.errorStatus) {
@@ -399,13 +408,14 @@ final class Player {
   }
 
   /// Requests a session release once playback is deliberately stopped: no intent, no
-  /// interruption to resume from, no retry pending. The host debounces it.
+  /// interruption to resume from, and no retry pending, whose reconnect needs the session. The
+  /// engine debounces it.
   private func evaluateSessionRelease() {
     guard !playWhenReady,
           !shouldResumeAfterInterruption,
           retry.pendingTask == nil
     else { return }
-    callbacks?.playerShouldReleaseSession()
+    engine.scheduleAudioSessionRelease()
   }
 
   func getPlayback() -> Playback {
@@ -599,6 +609,7 @@ final class Player {
       track: currentTrack,
     )
     callbacks?.playerDidChangeActiveTrack(eventData)
+    engine.nowPlayingTrackChanged()
     lastTrack = currentTrack
     lastIndex = queue.currentIndex
   }
@@ -755,6 +766,9 @@ final class Player {
     case .stalled:
       // Nudge, don't reconnect: a genuine drop is recovered by the retry and network paths.
       recoverFromStall(reconnectIfLive: false)
+    case let .timedMetadata(metadata):
+      callbacks?.playerDidReceiveTimedMetadata(metadata)
+      engine.applyTimedMetadata(metadata)
     }
   }
 
@@ -839,13 +853,15 @@ final class Player {
 
   // MARK: - Connectivity
 
-  /// Re-establishes a stalled stream when connectivity returns. AVPlayer doesn't reliably report
-  /// a live stream's mid-stream drop as a failure: it waits with no error, so the retry loop
-  /// never engages. Only while stalled (.buffering) with play intent, so a pause or a retry that
-  /// gave up isn't resumed; and not while the retry loop is itself waiting for the network,
-  /// which owns that reload.
-  func networkDidReturn() {
-    guard playWhenReady, state == .buffering, !retry.isWaitingForNetwork else { return }
+  /// Re-renders the now-playing lines, whose stall line tells offline from buffering, and when
+  /// connectivity returns re-establishes a stalled stream. AVPlayer doesn't reliably report a
+  /// live stream's mid-stream drop as a failure: it waits with no error, so the retry loop never
+  /// engages. Only while stalled (.buffering) with play intent, so a pause or a retry that gave up
+  /// isn't resumed; and not while the retry loop is itself waiting for the network, which owns
+  /// that reload.
+  func networkStatusDidChange(isOnline: Bool) {
+    engine.renderNowPlaying()
+    guard isOnline, playWhenReady, state == .buffering, !retry.isWaitingForNetwork else { return }
     logger.info("Connectivity restored while stalled — re-resolving to reconnect")
     reloadResolving(startFromCurrentTime: true)
   }
@@ -911,6 +927,25 @@ final class Player {
     }
   }
 
+  // MARK: - Now Playing Preview
+
+  /// Shows `track` on the now-playing surface before it is current, so a tapped track shows at
+  /// once while its queue and media resolve.
+  func previewNowPlaying(_ track: Track) {
+    engine.loadNowPlayingMetadata(for: track)
+  }
+
+  /// Puts the current track back over a preview that will not play, or clears the surface when
+  /// nothing is current.
+  func endNowPlayingPreview() {
+    guard let currentTrack else {
+      engine.clearNowPlaying()
+      return
+    }
+    engine.loadNowPlayingMetadata(for: currentTrack)
+    engine.renderNowPlaying()
+  }
+
   // MARK: - Progress Updates
 
   func setProgressUpdateInterval(_ interval: TimeInterval?) {

package/ios/Player/PlayerCallbacks.swift

@@ -15,9 +15,6 @@
   func playerDidChangeRepeatMode(_ event: RepeatModeChangedEvent)
   func playerDidChangeShuffleEnabled(_ enabled: Bool)
   func playerDidError(_ event: PlaybackErrorEvent)
-  /// Playback is deliberately stopped — play intent is off, it isn't an interruption-driven pause
-  /// (those resume), and no retry is pending (a live-stream reconnect must keep the session). The
-  /// host may release the audio session (debounced) so other apps' audio can resume.
-  func playerShouldReleaseSession()
+  func playerDidReceiveTimedMetadata(_ metadata: TimedMetadata)
   func playerDidChangeSleepTimer(_ state: SleepTimerState?)
 }

package/ios/Player/PlayerEngine.swift

@@ -24,6 +24,9 @@ enum EngineEvent {
   case playedToEnd
   /// The buffer emptied mid-playback.
   case stalled
+  /// A timed-metadata group (a live stream's song line), decoded with the loaded track's ICY
+  /// charset.
+  case timedMetadata(TimedMetadata)
 }
 
 /// The media stack under the Player: the AVPlayer and its items, media loading, now playing and
@@ -80,8 +83,22 @@ enum EngineEvent {
   func primeNowPlaying()
   func loadNowPlayingMetadata(for track: Track)
   func clearNowPlaying()
+  /// Re-renders the now-playing lines from the Player's state.
+  func renderNowPlaying()
+  /// Drops the previous track's override, flash and timed metadata, and re-renders.
+  func nowPlayingTrackChanged()
+  func applyTimedMetadata(_ metadata: TimedMetadata)
   func updateRemoteRepeatMode(_ mode: RepeatMode)
   func updateRemoteShuffleMode(_ enabled: Bool)
   /// Greys out next/previous on the remote surfaces when the queue has nowhere to skip.
   func updateSkipAvailability(canNext: Bool, canPrevious: Bool)
+
+  // MARK: Audio session
+
+  /// Activates the audio session off the main thread, then re-requests the now-playing session,
+  /// which the system may have declined while the audio session was inactive.
+  func activateAudioSession()
+  func cancelAudioSessionRelease()
+  /// Releases the audio session after a debounce, unless playback resumes first.
+  func scheduleAudioSessionRelease()
 }

package/ios/Player/RetryLoop.swift

@@ -101,7 +101,11 @@ final class RetryLoop {
   private let sleep: @Sendable (TimeInterval) async throws -> Void
 
   /// - Parameter sleep: Waits out a backoff or a connectivity poll; tests make it instant.
-  init(sleep: @escaping @Sendable (TimeInterval) async throws -> Void = { try await Task.sleep(for: .seconds($0)) }) {
+  init(
+    networkMonitor: (any NetworkStatusProviding)? = nil,
+    sleep: @escaping @Sendable (TimeInterval) async throws -> Void = { try await Task.sleep(for: .seconds($0)) },
+  ) {
+    self.networkMonitor = networkMonitor
     self.sleep = sleep
   }
 

package/ios/RemoteCommand/RemoteCommandCallbacks.swift

@@ -17,9 +17,6 @@
   /// Called when stop is triggered remotely.
   func remoteStop()
 
-  /// Called when toggle play/pause is triggered remotely.
-  func remotePlayPause()
-
   /// Called when next is triggered remotely.
   func remoteNext()
 

package/ios/RemoteCommand/RemoteCommandController.swift

@@ -39,7 +39,10 @@ final class RemoteCommandController {
 
   weak var callbacks: RemoteCommandCallbacks?
 
-  private var enabledCommands: [RemoteCommand] = []
+  private var enabledCommands: Set<RemoteCommand> = []
+  private var forwardJumpInterval: Double = 15
+  private var backwardJumpInterval: Double = 15
+  private var playbackRates: [Double] = []
 
   /// Whether the queue has a next / previous track; read whenever those commands are enabled.
   var skipAvailability: @MainActor () -> (canNext: Bool, canPrevious: Bool) = { (true, true) }
@@ -62,18 +65,27 @@ final class RemoteCommandController {
   func switchCommandCenter(_ newCenter: MPRemoteCommandCenter) {
     guard newCenter !== center else { return }
     let commands = enabledCommands
-    disableAll()
+    commands.forEach(disable)
     center = newCenter
-    enable(commands: commands)
+    commands.forEach(enable)
     center.changeShuffleModeCommand.currentShuffleType = shuffleEnabled.mpShuffleType
     center.changeRepeatModeCommand.currentRepeatType = repeatMode.mpRepeatType
     logger.info("Switched command center, re-enabled \(commands.count) commands")
   }
 
-  /// Enables exactly `commands`, disabling any enabled command they no longer include.
-  func enable(commands: [RemoteCommand]) {
-    RemoteCommand.commandsToDisable(enabled: enabledCommands, replacedBy: commands).forEach(disable)
+  /// Enables exactly `commands`, disabling any enabled command they no longer include. The skip
+  /// commands offer their interval, the rate command `playbackRates`.
+  func enable(
+    commands: Set<RemoteCommand>,
+    forwardJumpInterval: Double = 15,
+    backwardJumpInterval: Double = 15,
+    playbackRates: [Double] = [],
+  ) {
+    enabledCommands.subtracting(commands).forEach(disable)
     enabledCommands = commands
+    self.forwardJumpInterval = forwardJumpInterval
+    self.backwardJumpInterval = backwardJumpInterval
+    self.playbackRates = playbackRates
     commands.forEach(enable)
   }
 
@@ -106,7 +118,6 @@ final class RemoteCommandController {
     case .play: center.playCommand
     case .pause: center.pauseCommand
     case .stop: center.stopCommand
-    case .togglePlayPause: center.togglePlayPauseCommand
     case .next: center.nextTrackCommand
     case .previous: center.previousTrackCommand
     case .changePlaybackPosition: center.changePlaybackPositionCommand
@@ -120,9 +131,10 @@ final class RemoteCommandController {
 
   private func enable(_ command: RemoteCommand) {
     switch command {
-    case let .skipForward(intervals): center.skipForwardCommand.preferredIntervals = intervals
-    case let .skipBackward(intervals): center.skipBackwardCommand.preferredIntervals = intervals
-    case let .changePlaybackRate(rates): center.changePlaybackRateCommand.supportedPlaybackRates = rates
+    case .skipForward: center.skipForwardCommand.preferredIntervals = [NSNumber(value: forwardJumpInterval)]
+    case .skipBackward: center.skipBackwardCommand.preferredIntervals = [NSNumber(value: backwardJumpInterval)]
+    case .changePlaybackRate:
+      center.changePlaybackRateCommand.supportedPlaybackRates = playbackRates.map { NSNumber(value: $0) }
     default: break
     }
     let mpCommand = mpCommand(for: command)
@@ -148,14 +160,13 @@ final class RemoteCommandController {
     case .play: callbacks?.remotePlay()
     case .pause: callbacks?.remotePause()
     case .stop: callbacks?.remoteStop()
-    case .togglePlayPause: callbacks?.remotePlayPause()
     case .next: callbacks?.remoteNext()
     case .previous: callbacks?.remotePrevious()
     case .skipForward, .skipBackward:
       guard let interval = (event.command as? MPSkipIntervalCommand)?.preferredIntervals.first else {
         return .commandFailed
       }
-      if case .skipForward = command {
+      if command == .skipForward {
         callbacks?.remoteJumpForward(interval: interval.doubleValue)
       } else {
         callbacks?.remoteJumpBackward(interval: interval.doubleValue)

package/ios/Tests/CapabilityRemoteCommandTests.swift

@@ -0,0 +1,35 @@
+import Testing
+
+@testable import AudioBrowserTestable
+
+@Suite("PlayerCapabilities.remoteCommands")
+struct CapabilityRemoteCommandTests {
+  @Test func everyCommandIsEnabledUnlessSetToFalse() {
+    #expect(PlayerCapabilities().remoteCommands == Set(RemoteCommand.allCases))
+  }
+
+  @Test func eachCapabilitySetToFalseDropsExactlyItsCommand() {
+    let pairs: [(WritableKeyPath<PlayerCapabilities, Bool?>, RemoteCommand)] = [
+      (\.play, .play),
+      (\.pause, .pause),
+      (\.stop, .stop),
+      (\.skipToNext, .next),
+      (\.skipToPrevious, .previous),
+      (\.seekTo, .changePlaybackPosition),
+      (\.jumpForward, .skipForward),
+      (\.jumpBackward, .skipBackward),
+      (\.shuffleMode, .changeShuffleMode),
+      (\.repeatMode, .changeRepeatMode),
+      (\.playbackRate, .changePlaybackRate),
+    ]
+    for (capability, command) in pairs {
+      var capabilities = PlayerCapabilities()
+      capabilities[keyPath: capability] = false
+      #expect(capabilities.remoteCommands == Set(RemoteCommand.allCases).subtracting([command]), "\(command)")
+    }
+  }
+
+  @Test func favoriteEnablesNoCommand() {
+    #expect(PlayerCapabilities(favorite: false).remoteCommands == Set(RemoteCommand.allCases))
+  }
+}

package/ios/Tests/ConcurrentMapTests.swift

@@ -0,0 +1,42 @@
+@testable import AudioBrowserTestable
+import Testing
+
+@Suite("concurrentMap")
+struct ConcurrentMapTests {
+  @Test @MainActor
+  func keepsElementOrder_whenLaterElementsFinishFirst() async {
+    let results = await [30, 20, 10].concurrentMap { delayMs in
+      try? await Task.sleep(for: .milliseconds(delayMs))
+      return delayMs * 2
+    }
+    #expect(results == [60, 40, 20])
+  }
+
+  @Test @MainActor
+  func keepsNilResults_inPlace() async {
+    let results = await ["a", "", "c"].concurrentMap { $0.isEmpty ? nil : $0 }
+    #expect(results == ["a", nil, "c"])
+  }
+
+  @Test @MainActor
+  func empty_returnsEmpty() async {
+    let results = await [Int]().concurrentMap { $0 }
+    #expect(results.isEmpty)
+  }
+
+  @Test @MainActor
+  func cancellingTheCaller_cancelsEveryTransform() async {
+    let task = Task { @MainActor in
+      await [1, 2].concurrentMap { _ in
+        do {
+          try await Task.sleep(for: .seconds(10))
+          return false
+        } catch {
+          return Task.isCancelled
+        }
+      }
+    }
+    task.cancel()
+    #expect(await task.value == [true, true])
+  }
+}

package/ios/Tests/EmitterTests.swift

@@ -69,55 +69,12 @@ struct RemoveListenerTests {
 
   @Test func doubleRemoveSameTokenIsSafe() {
     let emitter = Emitter<Int>()
-    let token = emitter.addListener { _ in }
+    var received = [Int]()
+    let token = emitter.addListener { received.append($0) }
     emitter.removeListener(token)
     emitter.removeListener(token)
-    #expect(emitter.listenerCount == 0)
-  }
-}
-
-// MARK: - removeAllListeners
-
-@Suite("removeAllListeners")
-struct RemoveAllListenersTests {
-  @Test func clearsAllAndCountGoesToZero() {
-    let emitter = Emitter<Int>()
-    emitter.addListener { _ in }
-    emitter.addListener { _ in }
-    emitter.addListener { _ in }
-    emitter.removeAllListeners()
-    #expect(emitter.listenerCount == 0)
-  }
-
-  @Test func previouslyAddedListenersStopReceiving() {
-    let emitter = Emitter<Int>()
-    var called = false
-    emitter.addListener { _ in called = true }
-    emitter.removeAllListeners()
     emitter.emit(1)
-    #expect(called == false)
-  }
-}
-
-// MARK: - listenerCount
-
-@Suite("listenerCount")
-struct ListenerCountTests {
-  @Test func reflectsAddsAndRemoves() {
-    let emitter = Emitter<Int>()
-    #expect(emitter.listenerCount == 0)
-
-    let t1 = emitter.addListener { _ in }
-    #expect(emitter.listenerCount == 1)
-
-    let t2 = emitter.addListener { _ in }
-    #expect(emitter.listenerCount == 2)
-
-    emitter.removeListener(t1)
-    #expect(emitter.listenerCount == 1)
-
-    emitter.removeListener(t2)
-    #expect(emitter.listenerCount == 0)
+    #expect(received.isEmpty)
   }
 }
 
@@ -133,7 +90,6 @@ struct SubscribeTests {
     subscription.cancel()
     emitter.emit(2)
     #expect(received == [1])
-    #expect(emitter.listenerCount == 0)
   }
 
   @Test func releasingTheSubscriptionRemovesTheListener() {
@@ -146,6 +102,5 @@ struct SubscribeTests {
     }
     emitter.emit(2)
     #expect(received == [1])
-    #expect(emitter.listenerCount == 0)
   }
 }