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

package/ios/Player/NowPlayingUpdater.swift

@@ -3,51 +3,155 @@ import MediaPlayer
 import NitroModules
 import os.log
 
+/// What the now-playing surface renders from: the player's track and state.
+@MainActor
+protocol NowPlayingSource: AnyObject {
+  var currentTrack: Track? { get }
+  var currentTime: Double { get }
+  var playWhenReady: Bool { get }
+  var isStalled: Bool { get }
+  var nitroPlaybackError: PlaybackError? { get }
+}
+
 /// Owns the now-playing surface: publishes a track's static fields + artwork, and renders the
-/// title/artist line — the formatter's result, or the track/override default. The single writer of
-/// the title/artist fields, with a publish-dedupe so the frequent re-renders stay cheap.
-///
-/// Does not exclusively own NowPlayingInfoController -- other callers (e.g. HybridAudioBrowser for
-/// overrides) can still access it directly.
+/// title/artist line — a flash, else the formatter's result, else the override or the track's own
+/// fields. Holds that state (override, flash, latest timed metadata, formatter) and reports each
+/// change of the rendered lines through `onChanged`.
 @MainActor
 final class NowPlayingUpdater {
   private let logger = Logger(subsystem: "com.audiobrowser", category: "NowPlayingUpdater")
   private let nowPlayingInfoController: NowPlayingInfoController
 
+  weak var source: NowPlayingSource?
   var artworkUrlResolver: ((Track, ImageContext?) async -> ImageSource?)?
-  /// Invoked when the published title/artist actually change, so the owner can emit the JS
-  /// `onNowPlayingChanged` event (which it shapes with elapsed time / artwork / etc.).
-  var onChanged: (@MainActor (_ track: Track, _ title: String, _ artist: String?, _ album: String?) -> Void)?
+  /// Called with the JS-facing metadata whenever the rendered lines or the track change.
+  var onChanged: ((NowPlayingMetadata) -> Void)?
+
+  /// When false the surface shows the track's own fields: the override and formatter are ignored.
+  var enabled = true
+  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() } }
+  }
+
+  private var override: NowPlayingUpdate?
+  private var timedMetadata: TimedMetadata?
+  /// A transient line (e.g. feedback for a refused remote command) that outranks the formatter
+  /// and the override, reverted by a native timer: JS timers pause in the background.
+  private var flash: NowPlayingUpdate?
+  private var flashRevert: DispatchWorkItem?
 
   private var artworkLoadTask: Task<Void, Never>?
-  private var artworkGeneration: UInt = 0
 
-  /// Last published text lines, to dedupe redundant writes (render runs on every transition).
-  private struct Published: Equatable {
-    let trackId: String?
-    let title: String?
-    let artist: String?
-    let album: String?
+  /// The track `onChanged` last reported, so a new track with the same text still reports.
+  private var publishedTrackId: String?
+
+  func setOverride(_ update: NowPlayingUpdate?) {
+    override = update
+    render()
+  }
+
+  func flash(_ update: NowPlayingUpdate, durationMs: Double) {
+    flashRevert?.cancel()
+    flash = update
+    let revert = DispatchWorkItem { [weak self] in
+      self?.flash = nil
+      self?.flashRevert = nil
+      self?.render()
+    }
+    flashRevert = revert
+    DispatchQueue.main.asyncAfter(deadline: .now() + durationMs / 1000, execute: revert)
+    render()
   }
 
-  private var lastPublished: Published?
+  func clearFlash() {
+    guard flash != nil else { return }
+    cancelFlash()
+    render()
+  }
+
+  func receivedTimedMetadata(_ metadata: TimedMetadata) {
+    timedMetadata = metadata
+    render()
+  }
+
+  /// A new track drops the override, flash and timed metadata of the last one.
+  func trackChanged() {
+    override = nil
+    cancelFlash()
+    timedMetadata = nil
+    render()
+  }
+
+  /// The metadata JS sees for the current track, before any formatter result.
+  var nowPlaying: NowPlayingMetadata? {
+    guard let track = source?.currentTrack else { return nil }
+    let lines = defaultLines(for: track)
+    return metadata(track: track, title: lines.title, artist: lines.artist, album: lines.album)
+  }
+
+  /// Re-renders the text lines for the current track and state. Called on every playback
+  /// transition; unchanged lines are not re-published.
+  func render() {
+    guard let source, let track = source.currentTrack else { return }
+    render(
+      track: track,
+      timedMetadata: timedMetadata,
+      playWhenReady: source.playWhenReady,
+      stalled: source.isStalled ? (isOnline ? .buffering : .offline) : nil,
+      error: source.nitroPlaybackError,
+      flash: flash,
+      override: enabled ? override : nil,
+      formatter: enabled ? formatter : nil,
+    )
+  }
+
+  /// Empties the now-playing surface and drops any artwork fetch or formatter result in flight.
+  func clearNowPlaying() {
+    renderGeneration &+= 1
+    artworkLoadTask?.cancel()
+    artworkLoadTask = nil
+    nowPlayingInfoController.clear()
+    publishedTrackId = nil
+    formattedTrackId = nil
+  }
 
   /// Bumped on every `render`; an async formatter result applies only if its render is still the
   /// latest (latest-render-wins — drops a result whose track skipped or whose state moved on while
   /// the formatter was in flight).
   private var renderGeneration: UInt = 0
 
+  /// The track whose *formatted* line is currently on the surface. While this
+  /// matches the rendering track, `render` skips its interim default write — see
+  /// the comment at that site. Cleared whenever the surface stops showing a
+  /// formatter result (a flash overwrites it, `clearNowPlaying` empties it).
+  private var formattedTrackId: String?
+
   init(nowPlayingInfoController: NowPlayingInfoController) {
     self.nowPlayingInfoController = nowPlayingInfoController
   }
 
+  /// Pixel width to request now-playing artwork at: the active scene's screen
+  /// width in pixels, capped at `maxArtworkPixelWidth`. With no foreground
+  /// scene (headless CarPlay) the cap stands in — every current device exceeds
+  /// it anyway, and this only sizes a CDN request.
+  private static var artworkPixelWidth: CGFloat {
+    guard let screen = UIApplication.shared.activeWindowScene?.screen else {
+      return maxArtworkPixelWidth
+    }
+    return min(screen.bounds.width * screen.scale, maxArtworkPixelWidth)
+  }
+
+  /// Mirrored by the Kotlin twin's `artworkSizePx`.
+  private static let maxArtworkPixelWidth: CGFloat = 1200
+
   /// Publishes the static, per-track fields + artwork on a track change. The title/artist/album
   /// lines are owned by `render` (routed through `applyFields` here so it dedupes against later
   /// renders).
   func loadMetaValues(for track: Track) {
-    nowPlayingInfoController.set(keyValues: [
-      NowPlayingInfoProperty.isLiveStream(track.live),
-    ])
+    nowPlayingInfoController.set([MPNowPlayingInfoPropertyIsLiveStream: track.live])
     applyFields(track: track, title: track.title, artist: track.artist, album: track.album)
     loadArtwork(for: track)
   }
@@ -58,13 +162,13 @@ final class NowPlayingUpdater {
   /// command) outranks both: while one is active the formatter pass is skipped entirely, so its
   /// async result can't land on top. Safe to call on every playback transition; redundant writes
   /// are deduped.
-  func render(
+  private func render(
     track: Track,
     timedMetadata: TimedMetadata?,
     playWhenReady: Bool,
     stalled: StallReason?,
     error: PlaybackError?,
-    flash: NowPlayingUpdate? = nil,
+    flash: NowPlayingUpdate?,
     override: NowPlayingUpdate?,
     formatter: ((_ params: FormatNowPlayingParams) -> Promise<NowPlayingUpdate?>)?,
   ) {
@@ -75,6 +179,8 @@ final class NowPlayingUpdater {
     let defaultSecondary = override?.artist ?? track.artist
     let defaultAlbum = override?.album ?? track.album
 
+    let trackId = track.identity ?? track.path
+
     if let flash {
       applyFields(
         track: track,
@@ -82,10 +188,22 @@ final class NowPlayingUpdater {
         artist: flash.artist ?? defaultSecondary,
         album: flash.album ?? defaultAlbum,
       )
+      // The flash replaced the formatter's line, so the surface no longer shows
+      // one: the render that follows the flash reverting must publish the default
+      // immediately rather than sit on stale flash text awaiting the formatter.
+      formattedTrackId = nil
       return
     }
 
-    applyFields(track: track, title: defaultTitle, artist: defaultSecondary, album: defaultAlbum)
+    // Publish the raw default only while no formatter result is on screen for this
+    // track. `render` runs on EVERY playback transition (state change, playing/
+    // buffering flip, timed-metadata tick, connectivity change); writing the
+    // default each time would flash the track title over the formatter's line
+    // until the async result lands, since the two differ by construction on a live
+    // stream (station name vs. song line).
+    if formatter == nil || formattedTrackId != trackId {
+      applyFields(track: track, title: defaultTitle, artist: defaultSecondary, album: defaultAlbum)
+    }
 
     guard let formatter else { return }
     let params = FormatNowPlayingParams(
@@ -111,6 +229,9 @@ final class NowPlayingUpdater {
             artist: formatted.artist ?? defaultSecondary,
             album: formatted.album ?? defaultAlbum,
           )
+          // A formatter result now owns the surface for this track, so later
+          // renders skip the interim default write.
+          self.formattedTrackId = trackId
         }
       }
       .catch { @Sendable [weak self] error in
@@ -123,27 +244,58 @@ final class NowPlayingUpdater {
 
   // MARK: - Private
 
-  /// Stamps the title/artist/album (each falling back to the track's own) onto
-  /// NowPlayingInfoCenter, deduped against the last publish, and notifies `onChanged`.
+  /// Stamps the title/artist/album (each falling back to the track's own) onto the now-playing
+  /// surface, and notifies `onChanged` when the text or the track changed.
   private func applyFields(track: Track, title: String?, artist: String?, album: String?) {
     let resolvedTitle = title ?? track.title
     let resolvedArtist = artist ?? track.artist
     let resolvedAlbum = album ?? track.album
-    let published = Published(
-      trackId: track.src ?? track.url,
-      title: resolvedTitle,
-      artist: resolvedArtist,
-      album: resolvedAlbum,
+    let textChanged = nowPlayingInfoController.set([
+      MPMediaItemPropertyTitle: resolvedTitle,
+      MPMediaItemPropertyArtist: resolvedArtist,
+      MPMediaItemPropertyAlbumTitle: resolvedAlbum,
+    ])
+    let trackId = track.identity ?? track.path
+    guard textChanged || trackId != publishedTrackId else { return }
+    publishedTrackId = trackId
+    onChanged?(metadata(track: track, title: resolvedTitle, artist: resolvedArtist, album: resolvedAlbum))
+  }
+
+  private func cancelFlash() {
+    flashRevert?.cancel()
+    flashRevert = nil
+    flash = nil
+  }
+
+  /// Flash over override over the track's own fields.
+  private func defaultLines(for track: Track) -> (title: String, artist: String?, album: String?) {
+    (
+      flash?.title ?? override?.title ?? track.title,
+      flash?.artist ?? override?.artist ?? track.artist,
+      flash?.album ?? override?.album ?? track.album,
     )
-    guard published != lastPublished else { return }
-    lastPublished = published
+  }
 
-    nowPlayingInfoController.set(keyValues: [
-      MediaItemProperty.title(resolvedTitle),
-      MediaItemProperty.artist(resolvedArtist),
-      MediaItemProperty.albumTitle(resolvedAlbum),
-    ])
-    onChanged?(track, resolvedTitle, resolvedArtist, resolvedAlbum)
+  private func metadata(track: Track, title: String, artist: String?, album: String?) -> NowPlayingMetadata {
+    NowPlayingMetadata(
+      elapsedTime: source?.currentTime,
+      title: title,
+      album: album,
+      artist: artist,
+      duration: track.duration,
+      artwork: Self.jsArtwork(for: track),
+      description: track.description,
+      mediaId: track.src ?? track.path,
+      genre: track.genre,
+    )
+  }
+
+  /// The artwork URI JS can load: the resolved `artworkSource` (a rendered SF Symbol's `file://`
+  /// included), else the raw artwork unless it is an SF Symbol.
+  private static func jsArtwork(for track: Track) -> String? {
+    if let uri = track.artworkSource?.uri { return uri }
+    guard let artwork = track.artwork?.url else { return nil }
+    return SFSymbolRenderer.isSFSymbol(artwork) ? nil : artwork
   }
 
   private func loadArtwork(for track: Track) {
@@ -152,15 +304,10 @@ final class NowPlayingUpdater {
     let artworkUrl = track.artworkSource?.uri ?? track.artwork?.url
     logger.debug("loadArtwork: \(track.title), artworkUrl: \(artworkUrl ?? "nil")")
 
-    // Now Playing artwork: use screen width in pixels, capped at 1200px
-    let screenScale = UIScreen.main.scale
-    let screenWidth = UIScreen.main.bounds.width * screenScale
-    let artworkSize = min(screenWidth, 1200)
+    let artworkSize = Self.artworkPixelWidth
     let nowPlayingSize = ImageContext(width: artworkSize, height: artworkSize)
 
     artworkLoadTask?.cancel()
-    artworkGeneration &+= 1
-    let expectedGeneration = artworkGeneration
     artworkLoadTask = Task {
       let image: UIImage?
 
@@ -168,19 +315,19 @@ final class NowPlayingUpdater {
       if let resolver = artworkUrlResolver,
          let imageSource = await resolver(track, nowPlayingSize)
       {
-        guard !Task.isCancelled, artworkGeneration == expectedGeneration else { return }
+        guard !Task.isCancelled else { return }
         logger.debug("loadArtwork: using resolved URL: \(imageSource.uri)")
-        image = await ArtworkImageFetcher.fetchImage(from: imageSource)
+        image = await ArtworkImageFetcher.fetchImage(from: imageSource, waitsForConnectivity: true)
       } else {
-        guard !Task.isCancelled, artworkGeneration == expectedGeneration else { return }
+        guard !Task.isCancelled else { return }
         if let source = track.artworkImageSource {
-          image = await ArtworkImageFetcher.fetchImage(from: source)
+          image = await ArtworkImageFetcher.fetchImage(from: source, waitsForConnectivity: true)
         } else {
           image = nil
         }
       }
 
-      guard !Task.isCancelled, artworkGeneration == expectedGeneration else { return }
+      guard !Task.isCancelled else { return }
 
       if let image {
         logger.debug("loadArtwork: loaded image \(image.size.width)x\(image.size.height)")
@@ -189,10 +336,10 @@ final class NowPlayingUpdater {
         let artwork = MPMediaItemArtwork(boundsSize: image.size) { @Sendable requestedSize in
           return image
         }
-        nowPlayingInfoController.set(keyValue: MediaItemProperty.artwork(artwork))
+        nowPlayingInfoController.set([MPMediaItemPropertyArtwork: artwork])
       } else {
         logger.debug("loadArtwork: no image loaded")
-        nowPlayingInfoController.set(keyValue: MediaItemProperty.artwork(nil))
+        nowPlayingInfoController.set([MPMediaItemPropertyArtwork: nil])
       }
     }
   }

package/ios/Player/PlaybackFailure.swift

@@ -0,0 +1,125 @@
+import AVFoundation
+import Foundation
+
+/// What a playback failure is reported as, and whether another attempt could fix it: one table,
+/// so the error JS receives and the retry decision are read off the same evidence.
+enum PlaybackFailure {
+  struct Classification: Equatable {
+    /// The narrowest error the evidence supports, falling back to the context's error.
+    let error: TrackPlayerError.PlaybackError
+    let retryable: Bool
+  }
+
+  /// Classifies a failure. AVFoundation reports HTTP failures as opaque CoreMedia errors, so
+  /// `httpStatusCode` comes from the item's error log, passed in by the caller.
+  ///
+  /// Both read the error and the errors it wraps, but rank the evidence differently, on purpose:
+  /// - The error: a transport failure first (no response arrived, so a status left in the log
+  ///   describes an earlier attempt), then a non-2xx status, then media that cannot be decoded.
+  /// - Retrying: a status first (a retry cannot conjure content the server refused), then the
+  ///   error and the errors it wraps. An unrecognized failure is transient, bounded by the retry
+  ///   budgets, as on Android: AVFoundation reports most stream failures opaquely.
+  static func classify(
+    _ error: Error?,
+    httpStatusCode: Int?,
+    fallback: TrackPlayerError.PlaybackError,
+  ) -> Classification {
+    Classification(
+      error: reportedError(error, httpStatusCode: httpStatusCode, fallback: fallback),
+      retryable: isRetryable(error, httpStatusCode: httpStatusCode),
+    )
+  }
+
+  /// Picks the HTTP status out of an `AVPlayerItem` error log's status codes. The codes share
+  /// their space with negative OSStatus values, so only in-range values count, and the newest
+  /// wins: a live stream reconnects, and older entries describe earlier attempts.
+  static func httpStatusCode(fromErrorStatusCodes codes: [Int]) -> Int? {
+    codes.last { (100 ... 599).contains($0) }
+  }
+
+  // MARK: - The error
+
+  private static func reportedError(
+    _ error: Error?,
+    httpStatusCode: Int?,
+    fallback: TrackPlayerError.PlaybackError,
+  ) -> TrackPlayerError.PlaybackError {
+    let chain = error.map(errorChain) ?? []
+    // `as?` bridges a plain NSError in NSURLErrorDomain too, AVFoundation's usual form.
+    for case let urlError as URLError in chain {
+      switch urlError.code {
+      case .notConnectedToInternet:
+        return .notConnectedToInternet
+      case .timedOut, .cannotFindHost, .cannotConnectToHost, .networkConnectionLost, .dnsLookupFailed,
+           .secureConnectionFailed:
+        return .hostUnreachable
+      default:
+        continue
+      }
+    }
+    if let httpStatusCode, !(200 ... 299).contains(httpStatusCode) {
+      return .httpStatus(httpStatusCode)
+    }
+    let unplayable = chain.contains {
+      let nsError = $0 as NSError
+      return nsError.domain == AVFoundationErrorDomain && unplayableAVErrorCodes.contains(nsError.code)
+    }
+    return unplayable ? .trackWasUnplayable : fallback
+  }
+
+  /// The stream arrived but cannot be decoded: unknown container, unsupported codec, or no
+  /// decoder.
+  private static let unplayableAVErrorCodes: Set<Int> = [
+    AVError.fileFormatNotRecognized.rawValue,
+    AVError.failedToParse.rawValue,
+    AVError.decoderNotFound.rawValue,
+    AVError.decoderTemporarilyUnavailable.rawValue,
+    AVError.formatUnsupported.rawValue,
+    AVError.contentIsUnavailable.rawValue,
+  ]
+
+  // MARK: - Retrying
+
+  /// Beyond the 500–599 range. Android shares 408/429 but lists only 500/502/503/504 of 5xx.
+  private static let retryableHTTPStatusCodes: Set<Int> = [408, 429]
+
+  /// AVFoundation failures a retry cannot fix: the media is unusable, not the transport
+  /// unreliable. Every unplayable code but the temporary decoder shortage is here, so a failure
+  /// reported as unplayable is never also retried. `AVError.unknown` is absent on purpose: it
+  /// is the wrapper around opaque CoreMedia transport failures.
+  private static let fatalAVErrorCodes: Set<Int> = unplayableAVErrorCodes
+    .subtracting([AVError.decoderTemporarilyUnavailable.rawValue])
+    .union([
+      AVError.decodeFailed.rawValue,
+      AVError.contentIsProtected.rawValue,
+      AVError.contentIsNotAuthorized.rawValue,
+    ])
+
+  private static func isRetryable(_ error: Error?, httpStatusCode: Int?) -> Bool {
+    if let status = httpStatusCode {
+      return retryableHTTPStatusCodes.contains(status) || (500 ... 599).contains(status)
+    }
+    guard let error else { return false }
+    // AVFoundation routinely wraps the real cause (a URLError, a CoreMedia code) in an AVError.
+    for candidate in errorChain(error) {
+      if let urlError = candidate as? URLError { return urlError.isConnectivity }
+      let nsError = candidate as NSError
+      if nsError.domain == AVFoundationErrorDomain, fatalAVErrorCodes.contains(nsError.code) {
+        return false
+      }
+    }
+    return true
+  }
+
+  /// The error and its `NSUnderlyingError` ancestors, outermost first, bounded so a malformed
+  /// cycle cannot spin.
+  private static func errorChain(_ error: Error) -> [Error] {
+    var chain: [Error] = []
+    var current: Error? = error
+    while let error = current, chain.count < 8 {
+      chain.append(error)
+      current = (error as NSError).userInfo[NSUnderlyingErrorKey] as? Error
+    }
+    return chain
+  }
+}

package/ios/Player/PlaybackPersistence.swift

@@ -0,0 +1,73 @@
+import Foundation
+
+/// Keeps the player's resumable state in UserDefaults so a cold-start resume can restore the
+/// last session without the JS runtime. Saves on demand and, while the play intent is active,
+/// every `saveInterval`. Swift counterpart of Android's `PlaybackStateStore.kt`.
+@MainActor
+final class PlaybackPersistence {
+  static let standardDefaults = UserDefaults(suiteName: "com.audiobrowser.playback") ?? .standard
+
+  private let defaults: UserDefaults
+  private let key = "playbackState.v1"
+  private let saveInterval: Duration
+  private let snapshot: @MainActor () -> PersistedPlaybackState?
+  private var periodicSave: Task<Void, Never>?
+
+  /// - Parameter snapshot: The state to save; nil when there is nothing to resume.
+  init(
+    defaults: UserDefaults = standardDefaults,
+    saveInterval: Duration = .seconds(5),
+    snapshot: @escaping @MainActor () -> PersistedPlaybackState?,
+  ) {
+    self.defaults = defaults
+    self.saveInterval = saveInterval
+    self.snapshot = snapshot
+  }
+
+  func save() {
+    guard let state = snapshot(), let data = try? JSONEncoder().encode(state) else { return }
+    defaults.set(data, forKey: key)
+  }
+
+  func load() -> PersistedPlaybackState? {
+    guard let data = defaults.data(forKey: key) else { return nil }
+    return try? JSONDecoder().decode(PersistedPlaybackState.self, from: data)
+  }
+
+  /// Saves periodically while `active`, and once when it turns false.
+  func playIntentDidChange(active: Bool) {
+    periodicSave?.cancel()
+    periodicSave = nil
+    guard active else {
+      save()
+      return
+    }
+    periodicSave = Task { [weak self, saveInterval] in
+      while !Task.isCancelled {
+        try? await Task.sleep(for: saveInterval)
+        guard !Task.isCancelled else { return }
+        self?.save()
+      }
+    }
+  }
+
+  /// The state a resume restores. A live stream keeps no position, and an ended track resumes
+  /// from 0: at .ended the position is the duration, which would re-end at once (Android twin:
+  /// savePositionZero).
+  static func snapshot(
+    of track: Track,
+    state: PlaybackState,
+    position: TimeInterval,
+    repeatMode: RepeatMode,
+    shuffleEnabled: Bool,
+    rate: Float,
+  ) -> PersistedPlaybackState {
+    PersistedPlaybackState(
+      track: JsonTrack(from: track),
+      positionMs: track.live == true ? nil : (state == .ended ? 0 : position * 1000),
+      repeatMode: repeatMode.stringValue,
+      shuffleEnabled: shuffleEnabled,
+      playbackSpeed: rate,
+    )
+  }
+}

package/ios/Player/PlaybackTimer.swift

@@ -48,10 +48,16 @@ final class PlaybackTimer {
 
   private func start(_ interval: TimeInterval) {
     guard timer == nil else { return }
-    timer = Timer.scheduledTimer(withTimeInterval: interval, repeats: true) {
-      [weak self] _ in
+    // `.common`, not the `.default` mode `Timer.scheduledTimer` installs: UIKit
+    // runs the main run loop in tracking mode while a list is being dragged, and
+    // a default-mode timer does not fire there. Missed repeats are dropped rather
+    // than replayed, so progress events would freeze and interval ticks would be
+    // lost for as long as the user scrolls. (VolumeFader already does this.)
+    let timer = Timer(timeInterval: interval, repeats: true) { [weak self] _ in
       MainActor.assumeIsolated { self?.onTick() }
     }
+    self.timer = timer
+    RunLoop.main.add(timer, forMode: .common)
   }
 
   private func stop() {