react-native-audio-browser 0.2.0-next.3 → 0.2.0-next.31

package/ios/Model/NitroTypeStubs.swift

@@ -5,6 +5,12 @@
   /// These stubs declare `Equatable` for test ergonomics — the generated
   /// Nitro types do NOT. Shared `ios/` sources must not rely on conformances
   /// that exist only here: `swift test` compiles, the app build breaks.
+  ///
+  /// Property names and types ARE checked against `nitrogen/generated/ios/swift`
+  /// by `src/nitro-stub-drift.test.ts`, which runs in the JS CI job — neither
+  /// native job can see both files at once. Declaring fewer properties than the
+  /// real type is fine and deliberate; spelling one differently is what that
+  /// test catches. Conformances and default values are still on you.
 
   struct ArtworkVariants: Equatable {
     var light: String
@@ -23,19 +29,20 @@
   }
 
   struct Track: Equatable {
-    var id: String
-    var url: String?
+    var id: String?
+    var path: String?
     var src: String?
+    var artwork: Variant_String_ArtworkVariants?
+    var artworkSource: ImageSource?
     var request: TrackRequest?
     var title: String = ""
     var artist: String?
-    var albumUrl: String?
+    var albumPath: String?
     var album: String?
+    var style: TrackStyle?
+    var disabled: Bool?
     var live: Bool?
-    var artwork: Variant_String_ArtworkVariants?
-    var artworkSource: ImageSource?
-    var groupTitle: String?
-    var imageRow: [ImageRowItem]?
+    var icyCharset: String?
   }
 
   struct TrackLoadEvent {
@@ -48,6 +55,23 @@
     case off
     case track
     case queue
+
+    init?(fromString string: String) {
+      switch string {
+      case "off": self = .off
+      case "track": self = .track
+      case "queue": self = .queue
+      default: return nil
+      }
+    }
+
+    var stringValue: String {
+      switch self {
+      case .off: "off"
+      case .track: "track"
+      case .queue: "queue"
+      }
+    }
   }
 
   enum CarPlaySiriListButtonPosition {
@@ -63,14 +87,24 @@
     }
   }
 
+  enum HttpMethod {
+    case get
+    case post
+    case put
+    case patch
+    case delete
+    case head
+    case options
+  }
+
   struct ImageSource: Equatable {
     var uri: String
-    var method: String?
+    var method: HttpMethod?
     var headers: [String: String]?
     var body: String?
   }
 
-  enum TrackStyle {
+  enum StyleDisplay: Equatable {
     case list
     case grid
 
@@ -83,17 +117,108 @@
     }
   }
 
-  struct ImageRowItem: Equatable {
-    var id: String?
-    var url: String?
-    var src: String?
-    var artwork: String?
-    var artworkSource: ImageSource?
-    var title: String
+  enum ArtworkRendering: Equatable {
+    case original
+    case stencil
+
+    init?(fromString string: String) {
+      switch string {
+      case "original": self = .original
+      case "stencil": self = .stencil
+      default: return nil
+      }
+    }
+  }
+
+  enum ImageShape: Equatable {
+    case circular
+    case roundedRectangle
+
+    init?(fromString string: String) {
+      switch string {
+      case "circular": self = .circular
+      case "rounded-rectangle": self = .roundedRectangle
+      default: return nil
+      }
+    }
+  }
+
+  enum GridTile: Equatable {
+    case plain
+    case image
+    case card
+    case condensed
+
+    init?(fromString string: String) {
+      switch string {
+      case "plain": self = .plain
+      case "image": self = .image
+      case "card": self = .card
+      case "condensed": self = .condensed
+      default: return nil
+      }
+    }
+
+    // Mirrors the generated extension (nitrogen emits `stringValue` beside
+    // `init?(fromString:)` for every string-backed enum).
+    var stringValue: String {
+      switch self {
+      case .plain: "plain"
+      case .image: "image"
+      case .card: "card"
+      case .condensed: "condensed"
+      }
+    }
+  }
+
+  enum CardImage: Equatable {
+    case normal
+    case background
+
+    init?(fromString string: String) {
+      switch string {
+      case "normal": self = .normal
+      case "background": self = .background
+      default: return nil
+      }
+    }
+  }
+
+  struct TrackStyle: Equatable {
+    var display: StyleDisplay?
+    var artworkRendering: ArtworkRendering?
+    var imageShape: ImageShape?
+    var accessorySymbol: String?
+    var cardTint: String?
+    var cardImage: CardImage?
+  }
+
+  // Member order matches the generated init (own properties before inherited
+  // ones — Nitro flattens `extends` own-props-first): the memberwise init this
+  // produces must accept the same argument order as the real type, or
+  // `swift test` passes while the app build breaks on argument order.
+  struct SectionStyle: Equatable {
+    var gridWrap: Bool?
+    var gridTile: GridTile?
+    var display: StyleDisplay?
+    var artworkRendering: ArtworkRendering?
+    var imageShape: ImageShape?
+    var accessorySymbol: String?
+    var cardTint: String?
+    var cardImage: CardImage?
+  }
+
+  struct Section: Equatable {
+    var title: String?
+    var style: SectionStyle?
+    var path: String?
+    var children: [Track]
   }
 
   struct ResolvedTrack: Equatable {
-    var url: String
+    var path: String
+    var style: SectionStyle?
+    var sections: [Section]?
     var children: [Track]?
     var carPlaySiriListButton: CarPlaySiriListButtonPosition?
     var id: String?
@@ -101,21 +226,18 @@
     var artwork: Variant_String_ArtworkVariants?
     var artworkSource: ImageSource?
     var request: TrackRequest?
-    var artworkCarPlayTinted: Bool?
     var title: String
     var subtitle: String?
     var artist: String?
-    var albumUrl: String?
+    var albumPath: String?
     var album: String?
     var description: String?
     var genre: String?
     var duration: Double?
-    var style: TrackStyle?
-    var childrenStyle: TrackStyle?
+    var disabled: Bool?
     var favorited: Bool?
-    var groupTitle: String?
     var live: Bool?
-    var imageRow: [ImageRowItem]?
+    var icyCharset: String?
   }
 
   enum PlaybackState: Equatable {
@@ -208,7 +330,7 @@
     }
   }
 
-  // MARK: - Playback Event Types (used by PlaybackCoordinator)
+  // MARK: - Playback Event Types (used by Player)
 
   /// Public to match the generated Nitro enum, which `TrackPlayerError`
   /// exposes from a public property.

package/ios/Model/PlayerUpdateOptions.swift

@@ -2,7 +2,7 @@ import Foundation
 import NitroModules
 
 /**
- * Update options for the TrackPlayer that can be changed at runtime.
+ * Update options for the player that can be changed at runtime.
  * These options control player behavior and capabilities that can be modified during playback.
  */
 class PlayerUpdateOptions {
@@ -32,6 +32,9 @@ class PlayerUpdateOptions {
   /// Custom buttons for the CarPlay Now Playing screen
   var carPlayNowPlayingButtons: [CarPlayNowPlayingButton] = []
 
+  /// Where the now-playing indicator draws on CarPlay list rows
+  var carPlayPlayingIndicatorLocation: CarPlayPlayingIndicatorLocation = .leading
+
   // MARK: - Initialization
 
   init() {}
@@ -74,6 +77,9 @@ class PlayerUpdateOptions {
       if let buttons = ios.carPlayNowPlayingButtons {
         carPlayNowPlayingButtons = buttons
       }
+      if let location = ios.carPlayPlayingIndicatorLocation {
+        carPlayPlayingIndicatorLocation = location
+      }
     }
   }
 
@@ -92,6 +98,7 @@ class PlayerUpdateOptions {
         playbackRates: playbackRates,
         carPlayUpNextButton: carPlayUpNextButton,
         carPlayNowPlayingButtons: carPlayNowPlayingButtons,
+        carPlayPlayingIndicatorLocation: carPlayPlayingIndicatorLocation,
       ),
     )
   }

package/ios/Model/RemoteCommand.swift

@@ -48,6 +48,24 @@ enum RemoteCommand: CustomStringConvertible, Equatable {
 
   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.

package/ios/Model/TrackPlayerError.swift

@@ -103,10 +103,10 @@ public extension TrackPlayerError.PlaybackError {
   static func kind(forHttpStatus status: Int) -> PlaybackErrorKind {
     switch status {
     case 404, 410: .notFound
-    case 500...599: .serverError
+    case 500 ... 599: .serverError
     // Every other 4xx is the server refusing us — auth, geo-blocking, a
     // rate limit. All of them mean "you can't have this stream", not "retry".
-    case 400...499: .rejected
+    case 400 ... 499: .rejected
     default: .unknown
     }
   }

package/ios/NowPlayingInfo/NowPlayingInfoController.swift

@@ -3,62 +3,45 @@ import Foundation
 @preconcurrency import MediaPlayer
 import os.log
 
-// MPRemoteCommandCenter is not Sendable, but we only use it on the main thread
-extension MPRemoteCommandCenter: @retroactive @unchecked Sendable {}
-
 /// Controller for managing Now Playing info.
 ///
 /// A `MPNowPlayingSession` bound to the linked AVPlayer publishes now-playing info
 /// automatically: the system derives elapsed time, playback rate, and duration from
 /// the player, so the per-second clock stays out of our code (it extrapolates the
-/// scrubber). We supply the two things automatic publishing does NOT provide:
-/// metadata (title/artist/artwork), attached to `AVPlayerItem.nowPlayingInfo` (the
-/// supported channel under automatic publishing); and the explicit `playbackState`
-/// that CarPlay / Control Center read for their play/pause button (see `setPlaybackState`).
+/// scrubber). We supply what automatic publishing does not: metadata (title/artist/
+/// artwork), attached to `AVPlayerItem.nowPlayingInfo` (the supported channel under
+/// automatic publishing). An explicit `playbackState` would be dropped: iOS ignores it
+/// without a private entitlement (ADR 0005).
 @MainActor
 class NowPlayingInfoController {
   private let logger = Logger(subsystem: "com.audiobrowser", category: "NowPlayingInfoController")
 
   private var _info: [String: Any] = [:]
 
-  /// Last play/pause state pushed to the session's center, to skip redundant writes.
-  private var _playbackState: MPNowPlayingPlaybackState?
-
   /// The session bound to the linked AVPlayer; held so it stays alive while publishing.
   private var nowPlayingSession: MPNowPlayingSession?
 
   /// The linked AVPlayer — metadata is attached to its current item.
   private weak var linkedPlayer: AVPlayer?
 
-  /// The current remote command center - the session's while linked, else the shared one.
-  private(set) var remoteCommandCenter: MPRemoteCommandCenter = .shared()
-
   required init() {}
 
-  /// Callback invoked when the remote command center changes (session created/destroyed).
-  var onRemoteCommandCenterChanged: ((MPRemoteCommandCenter) -> Void)?
-
-  /// Binds an AVPlayer to a new auto-publishing `MPNowPlayingSession`.
-  ///
-  /// - Important: This creates an `MPNowPlayingSession` with its own `remoteCommandCenter`;
-  ///   the `onRemoteCommandCenterChanged` callback is invoked with the new command center.
-  func linkPlayer(_ player: AVPlayer) {
+  /// Binds an AVPlayer to a new auto-publishing `MPNowPlayingSession`, and returns the session's
+  /// own remote command center, which remote commands must now be enabled on.
+  func linkPlayer(_ player: AVPlayer) -> MPRemoteCommandCenter {
     logger.notice("Linking AVPlayer to MPNowPlayingSession for automatic publishing")
 
     linkedPlayer = player
 
     let session = MPNowPlayingSession(players: [player])
     nowPlayingSession = session
-    _playbackState = nil // new center starts at .unknown; force the next write
-    remoteCommandCenter = session.remoteCommandCenter
 
     session.automaticallyPublishesNowPlayingInfo = true
 
     session.becomeActiveIfPossible { success in
       self.logger.notice("MPNowPlayingSession becomeActiveIfPossible: \(success)")
     }
-
-    onRemoteCommandCenterChanged?(remoteCommandCenter)
+    return session.remoteCommandCenter
   }
 
   /// Re-requests now-playing activation for the linked session.
@@ -77,17 +60,14 @@ class NowPlayingInfoController {
     }
   }
 
-  /// Unlinks the AVPlayer, tearing down the session and restoring the shared command center.
+  /// Unlinks the AVPlayer and tears down the session with its command center. Remote commands
+  /// never fall back to the shared center, whose targets belong to the host app.
   func unlinkPlayer() {
     logger.info("Unlinking AVPlayer from MPNowPlayingSession")
 
     linkedPlayer = nil
     nowPlayingSession?.automaticallyPublishesNowPlayingInfo = false
     nowPlayingSession = nil
-    _playbackState = nil
-
-    remoteCommandCenter = MPRemoteCommandCenter.shared()
-    onRemoteCommandCenterChanged?(remoteCommandCenter)
   }
 
   /// Keys the session derives from the player itself — we never set these manually,
@@ -112,22 +92,18 @@ class NowPlayingInfoController {
     }
   }
 
-  /// Sets key-values and immediately updates Now Playing.
-  /// Playback-dynamics keys (elapsed/duration/rate) are owned by the session and skipped.
-  func set(keyValues: [NowPlayingInfoKeyValue]) {
+  /// Sets now-playing fields, keyed by their `MPMediaItemProperty*` / `MPNowPlayingInfoProperty*`
+  /// names (nil removes one), and publishes when any changed. Elapsed time, duration and rate
+  /// are the session's to publish and are ignored. Returns whether anything changed.
+  @discardableResult
+  func set(_ fields: [String: Any?]) -> Bool {
     var changed = false
-    for kv in keyValues where !Self.autoPublishedKeys.contains(kv.key) && !valueUnchanged(kv.key, kv.value) {
-      _info[kv.key] = kv.value
+    for (key, value) in fields where !Self.autoPublishedKeys.contains(key) && !valueUnchanged(key, value) {
+      _info[key] = value
       changed = true
     }
     if changed { performUpdate() }
-  }
-
-  /// Sets a single key-value and immediately updates Now Playing.
-  func set(keyValue: NowPlayingInfoKeyValue) {
-    guard !Self.autoPublishedKeys.contains(keyValue.key), !valueUnchanged(keyValue.key, keyValue.value) else { return }
-    _info[keyValue.key] = keyValue.value
-    performUpdate()
+    return changed
   }
 
   /// Attaches metadata to the current item — the supported channel under automatic publishing.
@@ -155,15 +131,4 @@ class NowPlayingInfoController {
     linkedPlayer?.currentItem?.nowPlayingInfo = nil
     nowPlayingSession?.nowPlayingInfoCenter.nowPlayingInfo = nil
   }
-
-  /// Sets the play/pause state CarPlay / Control Center show for their transport
-  /// button. Automatic publishing fills the info dict (metadata/elapsed/rate) but
-  /// not the explicit `playbackState`, so the coordinator pushes the user's
-  /// play/pause intent here on intent/state changes.
-  func setPlaybackState(playing: Bool) {
-    let state: MPNowPlayingPlaybackState = playing ? .playing : .paused
-    guard state != _playbackState else { return }
-    _playbackState = state
-    nowPlayingSession?.nowPlayingInfoCenter.playbackState = state
-  }
 }

package/ios/Observer/ItemObserver.swift

@@ -0,0 +1,90 @@
+@preconcurrency import AVFoundation
+
+// Delivered on the main queue through AVPlayerItemMetadataOutputPushDelegate.
+extension AVTimedMetadataGroup: @retroactive @unchecked Sendable {}
+
+/// Observes one AVPlayerItem from creation to `invalidate()`: its status and buffer, the
+/// end-of-item and stall notifications, and its timed metadata. KVO and notifications arrive off
+/// the main thread; anything that lands after `invalidate()` is dropped, so an old item's late
+/// failure never reaches the next item's handlers.
+@MainActor
+final class ItemObserver: NSObject {
+  enum Event {
+    case likelyToKeepUp(Bool)
+    case failed(Error?)
+    case playedToEnd
+    case failedToPlayToEnd(Error?)
+    /// The buffer emptied mid-playback.
+    case stalled
+    case timedMetadata([AVTimedMetadataGroup])
+  }
+
+  private let item: AVPlayerItem
+  private let onEvent: @MainActor (Event) -> Void
+  private var observations: [NSKeyValueObservation] = []
+  private var notificationTokens: [any NSObjectProtocol] = []
+  private let metadataOutput = AVPlayerItemMetadataOutput()
+  private(set) var isActive = true
+
+  init(item: AVPlayerItem, onEvent: @escaping @MainActor (Event) -> Void) {
+    self.item = item
+    self.onEvent = onEvent
+    super.init()
+    observations = [
+      item.observe(\.isPlaybackLikelyToKeepUp, options: [.new]) { [weak self] item, _ in
+        let isLikely = item.isPlaybackLikelyToKeepUp
+        Task { @MainActor in self?.emit(.likelyToKeepUp(isLikely)) }
+      },
+      item.observe(\.status, options: [.new]) { [weak self] item, _ in
+        guard item.status == .failed else { return }
+        let error = item.error
+        Task { @MainActor in self?.emit(.failed(error)) }
+      },
+    ]
+    notificationTokens = [
+      observe(.AVPlayerItemDidPlayToEndTime) { _ in .playedToEnd },
+      observe(.AVPlayerItemFailedToPlayToEndTime) {
+        .failedToPlayToEnd($0.userInfo?[AVPlayerItemFailedToPlayToEndTimeErrorKey] as? Error)
+      },
+      observe(.AVPlayerItemPlaybackStalled) { _ in .stalled },
+    ]
+    metadataOutput.setDelegate(self, queue: .main)
+    item.add(metadataOutput)
+  }
+
+  func invalidate() {
+    guard isActive else { return }
+    isActive = false
+    observations.removeAll()
+    for token in notificationTokens {
+      NotificationCenter.default.removeObserver(token)
+    }
+    notificationTokens = []
+    item.remove(metadataOutput)
+  }
+
+  private func observe(
+    _ name: Notification.Name,
+    _ event: @escaping @Sendable (Notification) -> Event,
+  ) -> any NSObjectProtocol {
+    NotificationCenter.default.addObserver(forName: name, object: item, queue: nil) { [weak self] notification in
+      let event = event(notification)
+      Task { @MainActor in self?.emit(event) }
+    }
+  }
+
+  private func emit(_ event: Event) {
+    guard isActive else { return }
+    onEvent(event)
+  }
+}
+
+extension ItemObserver: AVPlayerItemMetadataOutputPushDelegate {
+  nonisolated func metadataOutput(
+    _: AVPlayerItemMetadataOutput,
+    didOutputTimedMetadataGroups groups: [AVTimedMetadataGroup],
+    from _: AVPlayerItemTrack?,
+  ) {
+    MainActor.assumeIsolated { emit(.timedMetadata(groups)) }
+  }
+}

package/ios/Observer/PlayerObserver.swift

@@ -0,0 +1,59 @@
+import AVFoundation
+
+/// Observes one AVPlayer from creation to `invalidate()`: its status, its time-control status,
+/// and the moment audio starts. A recreated player gets a new observer, so nothing a released
+/// player reports reaches its successor.
+@MainActor
+final class PlayerObserver {
+  enum Event {
+    case status(AVPlayer.Status)
+    case timeControlStatus(AVPlayer.TimeControlStatus)
+    /// Playback crossed the first millisecond.
+    case audioDidStart
+  }
+
+  /// A boundary time cannot be zero.
+  private static let startBoundaryTime = CMTime(value: 1, timescale: 1000)
+
+  private let player: AVPlayer
+  private let onEvent: @MainActor (Event) -> Void
+  private var observations: [NSKeyValueObservation] = []
+  private(set) var boundaryObserverToken: Any?
+  private var isActive = true
+
+  init(player: AVPlayer, onEvent: @escaping @MainActor (Event) -> Void) {
+    self.player = player
+    self.onEvent = onEvent
+    observations = [
+      player.observe(\.status, options: [.new, .initial]) { [weak self] player, _ in
+        let status = player.status
+        Task { @MainActor in self?.emit(.status(status)) }
+      },
+      player.observe(\.timeControlStatus, options: [.new]) { [weak self] player, _ in
+        let status = player.timeControlStatus
+        Task { @MainActor in self?.emit(.timeControlStatus(status)) }
+      },
+    ]
+    boundaryObserverToken = player.addBoundaryTimeObserver(
+      forTimes: [NSValue(time: Self.startBoundaryTime)], queue: nil,
+    ) { [weak self] in
+      Task { @MainActor in self?.emit(.audioDidStart) }
+    }
+  }
+
+  /// Stops all delivery, including events already hopping to the main actor. An AVPlayer
+  /// retains its time observers, so one left registered outlives the observer (#96).
+  func invalidate() {
+    isActive = false
+    observations.removeAll()
+    if let boundaryObserverToken {
+      player.removeTimeObserver(boundaryObserverToken)
+      self.boundaryObserverToken = nil
+    }
+  }
+
+  private func emit(_ event: Event) {
+    guard isActive else { return }
+    onEvent(event)
+  }
+}