react-native-audio-browser 0.1.1 → 0.2.0-next.2

package/ios/Observer/PlayerTimeObserver.swift

@@ -2,48 +2,28 @@ import AVFoundation
 import Foundation
 
 /**
- Observes time-based player events and invokes callbacks passed at initialization.
+ Observes the player's audio-start boundary and invokes the callback passed at initialization.
  */
 @MainActor class PlayerTimeObserver {
   /// The time to use as start boundary time. Cannot be zero.
   private static let startBoundaryTime: CMTime = .init(value: 1, timescale: 1000)
 
   var boundaryTimeStartObserverToken: Any?
-  var periodicTimeObserverToken: Any?
 
   weak var avPlayer: AVPlayer? {
     willSet {
       unregisterForBoundaryTimeEvents()
-      unregisterForPeriodicEvents()
-    }
-  }
-
-  /// The frequency to receive periodic time events.
-  /// Setting this to a new value will trigger a re-registering to the periodic events of the
-  /// player.
-  var periodicObserverTimeInterval: CMTime {
-    didSet {
-      if oldValue != periodicObserverTimeInterval {
-        registerForPeriodicTimeEvents()
-      }
     }
   }
 
   private let onAudioDidStart: @MainActor () -> Void
-  private let onSecondElapsed: @MainActor (Double) -> Void
 
-  init(
-    periodicObserverTimeInterval: CMTime,
-    onAudioDidStart: @escaping @MainActor () -> Void,
-    onSecondElapsed: @escaping @MainActor (Double) -> Void,
-  ) {
-    self.periodicObserverTimeInterval = periodicObserverTimeInterval
+  init(onAudioDidStart: @escaping @MainActor () -> Void) {
     self.onAudioDidStart = onAudioDidStart
-    self.onSecondElapsed = onSecondElapsed
   }
 
   /**
-   Will register for the AVPlayer BoundaryTimeEvents, to trigger start and complete events.
+   Will register for the AVPlayer BoundaryTimeEvents, to trigger the audio-start event.
    */
   func registerForBoundaryTimeEvents() {
     guard let avPlayer else {
@@ -72,34 +52,4 @@ import Foundation
     avPlayer.removeTimeObserver(boundaryTimeStartObserverToken)
     self.boundaryTimeStartObserverToken = nil
   }
-
-  /**
-   Start observing periodic time events.
-   Will trigger unregisterForPeriodicEvents() first to avoid multiple subscriptions.
-   */
-  func registerForPeriodicTimeEvents() {
-    guard let avPlayer else {
-      return
-    }
-    unregisterForPeriodicEvents()
-    periodicTimeObserverToken = avPlayer.addPeriodicTimeObserver(
-      forInterval: periodicObserverTimeInterval,
-      queue: nil,
-      using: { [weak self] time in
-        let seconds = time.seconds
-        Task { @MainActor in self?.onSecondElapsed(seconds) }
-      },
-    )
-  }
-
-  /**
-   Unregister for periodic events.
-   */
-  func unregisterForPeriodicEvents() {
-    guard let avPlayer, let periodicTimeObserverToken else {
-      return
-    }
-    avPlayer.removeTimeObserver(periodicTimeObserverToken)
-    self.periodicTimeObserverToken = nil
-  }
 }

package/ios/Option/SessionCategories.swift

@@ -31,11 +31,7 @@ enum SessionCategoryPolicy: String {
     case .longFormAudio:
       .longFormAudio
     case .longFormVideo:
-      if #available(iOS 13.0, *) {
-        .longFormVideo
-      } else {
-        .longFormAudio
-      }
+      .longFormVideo
     }
   }
 }
@@ -63,12 +59,7 @@ enum SessionCategoryMode: String {
     case .voiceChat:
       .voiceChat
     case .voicePrompt:
-      if #available(iOS 12.0, *) {
-        .voicePrompt
-      } else {
-        // Do Nothing
-        .default
-      }
+      .voicePrompt
     }
   }
 }
@@ -98,3 +89,34 @@ enum SessionCategoryOptions: String {
     }
   }
 }
+
+extension NativeIOSSetupOptions {
+  /// The resolved `AVAudioSession` category configuration from the iOS setup options. Each field
+  /// falls back to a playback default when it's absent or unrecognised, so a consumer's
+  /// `categoryOptions` (e.g. `allowBluetooth` / `allowAirPlay`), `mode`, and route `policy` are
+  /// actually honoured at setup instead of being dropped.
+  func resolveAudioSessionConfig() -> (
+    category: AVAudioSession.Category,
+    mode: AVAudioSession.Mode,
+    policy: AVAudioSession.RouteSharingPolicy,
+    options: AVAudioSession.CategoryOptions
+  ) {
+    let category = self.category
+      .flatMap { SessionCategory(rawValue: $0.stringValue) }?
+      .mapConfigToAVAudioSessionCategory() ?? .playback
+    let mode = self.categoryMode
+      .flatMap { SessionCategoryMode(rawValue: $0.stringValue) }?
+      .mapConfigToAVAudioSessionCategoryMode() ?? .default
+    let policy = self.categoryPolicy
+      .flatMap { SessionCategoryPolicy(rawValue: $0.stringValue) }?
+      .toRouteSharingPolicy() ?? .default
+    let options = (self.categoryOptions ?? [])
+      .reduce(into: AVAudioSession.CategoryOptions()) { acc, option in
+        if let mapped = SessionCategoryOptions(rawValue: option.stringValue)?
+          .mapConfigToAVAudioSessionCategoryOptions() {
+          acc.insert(mapped)
+        }
+      }
+    return (category, mode, policy, options)
+  }
+}

package/ios/Player/AirPlayStallJudgement.swift

@@ -0,0 +1,25 @@
+/// Pure decision for the AirPlay "silently stuck" recovery, kept free of
+/// AVFoundation so it can be unit-tested off-device.
+///
+/// Over AirPlay, AVPlayer can drop `.waitingToPlayAtSpecifiedRate` (reason
+/// `.noItemToPlay`) → `.paused` while the app still intends to play, leaving
+/// playback stuck/silent with no error. Re-issuing `play()` on exactly that
+/// transition recovers it. Scoped narrowly to AirPlay so it never nudges a
+/// legitimate pause on the local route.
+struct AirPlayStallJudgement {
+  let previous: PlayerTimeControlStatus?
+  let current: PlayerTimeControlStatus
+  /// Whether the previous waiting state's reason was specifically
+  /// `.noItemToPlay` (the AirPlay-stall signature, not a normal rebuffer).
+  let previousWaitingReasonWasNoItemToPlay: Bool
+  let isAirPlay: Bool
+  let playWhenReady: Bool
+
+  var shouldNudge: Bool {
+    isAirPlay
+      && playWhenReady
+      && current == .paused
+      && previous == .waitingToPlayAtSpecifiedRate
+      && previousWaitingReasonWasNoItemToPlay
+  }
+}

package/ios/Player/EndOfTrackJudgement.swift

@@ -0,0 +1,32 @@
+import Foundation
+
+/// Whether an `AVPlayerItemDidPlayToEndTime` notification represents a genuine
+/// end of the track, or a stall masquerading as one.
+enum EndOfTrackOutcome: Equatable {
+  /// Genuine end — advance the queue / complete.
+  case ended
+  /// Not a real end (a dropped live stream, or a mid-stream buffer exhaustion
+  /// reported as EOF) — recover instead of advancing.
+  case stalled
+}
+
+/// Pure decision for how to treat an end-of-item notification, kept free of
+/// AVFoundation so it can be unit-tested off-device. iOS surfaces a dropped
+/// connection on a live stream — and sometimes a mid-stream buffer underrun —
+/// as a "played to end", which would otherwise stop the station or skip the
+/// track.
+struct EndOfTrackJudgement {
+  let isLive: Bool
+  let currentTime: Double
+  let duration: Double
+
+  var outcome: EndOfTrackOutcome {
+    // Live streams are infinite; an end-of-item here is a dropped connection.
+    if isLive { return .stalled }
+    // Indefinite/unknown duration — can't validate the position, trust iOS.
+    guard duration.isFinite, duration > 0 else { return .ended }
+    // More than 5% short of the end → a stall reported as EOF, not a real finish.
+    if currentTime + duration * 0.05 < duration { return .stalled }
+    return .ended
+  }
+}

package/ios/Player/LoadSeekCoordinator.swift

@@ -17,6 +17,17 @@ final class LoadSeekCoordinator {
   private let logger = Logger(subsystem: "com.audiobrowser", category: "LoadSeekCoordinator")
   private(set) var state: State = .idle
 
+  /// Identifies the item epoch a seek was issued against. `reset()` (called on
+  /// track/queue changes) bumps it, so the completion of a seek issued against
+  /// the previous item can recognize itself as stale and be dropped — a
+  /// cancelled cross-item completion arriving after the new track's start
+  /// position was captured would otherwise consume or prematurely resolve it.
+  private(set) var generation = 0
+
+  func isCurrentGeneration(_ generation: Int) -> Bool {
+    generation == self.generation
+  }
+
   /// Used by `seekBy()` to offset from the deferred position.
   var pendingTime: TimeInterval? {
     switch state {
@@ -49,9 +60,12 @@ final class LoadSeekCoordinator {
     state = .seekInFlight(time: time)
 
     let cmTime = CMTime(seconds: time, preferredTimescale: 1000)
+    let generation = generation
     player
-      .seek(to: cmTime, toleranceBefore: CMTime.zero, toleranceAfter: CMTime.zero) { finished in
+      .seek(to: cmTime, toleranceBefore: CMTime.zero, toleranceAfter: CMTime.zero) {
+        [weak self] finished in
         Task { @MainActor in
+          guard let self, self.isCurrentGeneration(generation) else { return }
           delegate?.handleSeekCompleted(to: time, didFinish: finished)
         }
       }
@@ -80,5 +94,6 @@ final class LoadSeekCoordinator {
 
   func reset() {
     state = .idle
+    generation += 1
   }
 }

package/ios/Player/MediaIntentCriteria.swift

@@ -0,0 +1,139 @@
+import Foundation
+
+/// Normalized "what did the user ask to play", derived from a media intent.
+/// Deliberately free of `Intents` types so the core (`HybridAudioBrowser`)
+/// never imports the Intents framework — the mapping lives in the
+/// `Intents`-aware `RNABMediaIntentHandler`.
+public struct MediaIntentCriteria: Sendable {
+  /// Media-reference axis (mirrors `INMediaReference`). `currentlyPlaying`
+  /// routes to native resume and never reaches the consumer; `my` routes to
+  /// the search source; `unknown` is the default.
+  public enum Reference: Sendable { case my, currentlyPlaying, unknown }
+
+  let query: String
+  let reference: Reference
+  let hasGenres: Bool
+  let hasMediaType: Bool
+  /// True when `query` is effectively the host app's own name. Siri turns
+  /// "Play «app»" into a search for a word in the app name — e.g. "Play Radio
+  /// Garden" arrives as mediaName "Garden" (+ radio mediaType). That's an
+  /// app-open/resume, not a station search.
+  let matchesAppName: Bool
+
+  // Structured search payload, mirroring the shared `SearchParams`. Plain
+  // Sendable strings so this type stays in the unit-testable target; the Nitro
+  // `SearchParams` is assembled in the funnel.
+  /// The container-vertical `SearchMode` name, or nil. Comes ONLY from the
+  /// intent's media type — never derived from which filter field is set.
+  let searchMode: String?
+  let genre: String?
+  let artist: String?
+  let album: String?
+  let title: String?
+  let playlist: String?
+
+  init(
+    query: String,
+    reference: Reference,
+    hasGenres: Bool,
+    hasMediaType: Bool,
+    matchesAppName: Bool,
+    searchMode: String? = nil,
+    genre: String? = nil,
+    artist: String? = nil,
+    album: String? = nil,
+    title: String? = nil,
+    playlist: String? = nil
+  ) {
+    self.query = query
+    self.reference = reference
+    self.hasGenres = hasGenres
+    self.hasMediaType = hasMediaType
+    self.matchesAppName = matchesAppName
+    self.searchMode = searchMode
+    self.genre = genre
+    self.artist = artist
+    self.album = album
+    self.title = title
+    self.playlist = playlist
+  }
+
+  /// Resume vs search, by reference:
+  /// - `currentlyPlaying` → always resume ("play this" plays the active track)
+  /// - `my` → always search ("play my favorites" goes to the consumer)
+  /// - `unknown` → the no-criteria / app-name heuristic
+  var isResume: Bool {
+    switch reference {
+    case .currentlyPlaying: return true
+    case .my: return false
+    case .unknown:
+      let q = query.trimmingCharacters(in: .whitespacesAndNewlines)
+      // "Play «app»": no search term and no other filter → resume.
+      if q.isEmpty { return !hasGenres && !hasMediaType }
+      // "Play «app-name»": resume — unless a real filter signals a search.
+      return matchesAppName && !hasGenres
+    }
+  }
+
+  /// Builds criteria from the raw fields of a media-search intent. Pure (no
+  /// `Intents`/`Bundle` dependency) so the whole Siri-phrase → search decision
+  /// is unit-testable.
+  ///
+  /// `mediaTypeMode` is the already-collapsed `SearchMode` string for the
+  /// intent's container vertical (e.g. "station"/"podcast"/"song"), or nil for
+  /// a filter-only / unclassified type. `reference` is the mapped axis.
+  static func from(
+    mediaName: String?,
+    genreNames: [String],
+    artistName: String?,
+    albumName: String?,
+    mediaTypeMode: String?,
+    reference: Reference,
+    hasMediaType: Bool,
+    appName: String?
+  ) -> MediaIntentCriteria {
+    let name = (mediaName ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
+    let trimmedNonEmpty: (String?) -> String? = {
+      let t = ($0 ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
+      return t.isEmpty ? nil : t
+    }
+
+    let genre = genreNames.isEmpty ? nil : genreNames.joined(separator: " ")
+    let artist = trimmedNonEmpty(artistName)
+    let album = trimmedNonEmpty(albumName)
+    // song/playlist carry their spoken name into a dedicated field.
+    let title = mediaTypeMode == "song" ? (name.isEmpty ? nil : name) : nil
+    let playlist = mediaTypeMode == "playlist" ? (name.isEmpty ? nil : name) : nil
+
+    // `query` is always populated so search works even before the API honours
+    // `mode`: prefer the spoken name, else fall back to a structured value.
+    let query = name.isEmpty ? (genre ?? artist ?? album ?? title ?? playlist ?? "") : name
+
+    return MediaIntentCriteria(
+      query: query,
+      reference: reference,
+      hasGenres: !genreNames.isEmpty,
+      hasMediaType: hasMediaType,
+      matchesAppName: queryMatchesAppName(query, appName: appName),
+      searchMode: mediaTypeMode,   // mode is the vertical, verbatim — no derivation
+      genre: genre,
+      artist: artist,
+      album: album,
+      title: title,
+      playlist: playlist
+    )
+  }
+
+  /// Whether `query` is effectively the host app's own name. Case- and
+  /// diacritic-insensitive.
+  private static func queryMatchesAppName(_ query: String, appName: String?) -> Bool {
+    guard let appName else { return false }
+    let normalize: (String) -> String = {
+      $0.folding(options: [.diacriticInsensitive, .caseInsensitive], locale: nil)
+        .trimmingCharacters(in: .whitespacesAndNewlines)
+    }
+    let q = normalize(query), a = normalize(appName)
+    guard !q.isEmpty, !a.isEmpty else { return false }
+    return a.contains(q) || q.contains(a)
+  }
+}

package/ios/Player/MediaLoader.swift

@@ -12,7 +12,10 @@ struct MediaResolvedUrl {
 final class MediaLoader {
   private let logger = Logger(subsystem: "com.audiobrowser", category: "MediaLoader")
 
-  var mediaUrlResolver: ((String) async -> MediaResolvedUrl)?
+  /// Resolves a playback src into a concrete URL + headers/user-agent.
+  /// The `Track` is threaded through so the resolver can invoke the
+  /// consumer-supplied `media.resolve(track)` as the final media layer.
+  var mediaUrlResolver: ((String, Track?) async -> MediaResolvedUrl)?
 
   /// Internal access so TrackPlayer can read it for observer guards.
   private(set) var asset: AVURLAsset?
@@ -22,7 +25,9 @@ final class MediaLoader {
 
   weak var delegate: MediaLoaderDelegate?
 
-  private var mediaResolverTask: Task<Void, Never>?
+  /// The in-flight resolve. Readable so tests can await the resolve-then-load
+  /// chain instead of sleeping past it; only this type starts and cancels it.
+  private(set) var mediaResolverTask: Task<Void, Never>?
   private var metadataLoadTask: Task<Void, Never>?
   private var playableLoadTask: Task<Void, Never>?
   private var url: URL?
@@ -30,7 +35,7 @@ final class MediaLoader {
 
   // MARK: - Public API
 
-  func resolveAndLoad(src: String) {
+  func resolveAndLoad(src: String, track: Track? = nil) {
     if let resolver = mediaUrlResolver {
       mediaResolverTask?.cancel()
       mediaResolverTask = Task {
@@ -42,7 +47,7 @@ final class MediaLoader {
         }
 
         self.logger.debug("resolveAndLoad: calling resolver...")
-        let resolved = await resolver(src)
+        let resolved = await resolver(src, track)
 
         guard !Task.isCancelled else {
           self.logger.debug("resolveAndLoad: cancelled after resolver returned")
@@ -72,7 +77,12 @@ final class MediaLoader {
   }
 
   func loadAsset() {
-    guard let url else { return }
+    guard let url else {
+      // Callers (reload-from-terminal) have already transitioned to .loading;
+      // a silent return would strand that state with no load in flight.
+      delegate?.mediaLoaderDidFailWithError(.invalidSourceUrl("nil"))
+      return
+    }
     let pendingAsset = AVURLAsset(url: url, options: urlOptions)
     asset = pendingAsset
 
@@ -171,6 +181,21 @@ final class MediaLoader {
     asset = nil
   }
 
+  /// Builds AVURLAsset options, merging any explicit headers with a resolved
+  /// User-Agent. An explicit `User-Agent` in `headers` wins (mirrors the artwork
+  /// path in BrowserManager+URLResolution). A nil/empty userAgent contributes
+  /// nothing, so "no UA configured" still falls through to AVPlayer's default.
+  nonisolated static func buildAssetOptions(
+    headers: [String: String]?,
+    userAgent: String?,
+  ) -> [String: Any]? {
+    var merged = headers ?? [:]
+    if let userAgent, !userAgent.isEmpty, merged["User-Agent"] == nil {
+      merged["User-Agent"] = userAgent
+    }
+    return merged.isEmpty ? nil : ["AVURLAssetHTTPHeaderFieldsKey": merged]
+  }
+
   // MARK: - Private
 
   private func loadWithResolvedUrl(_ resolved: MediaResolvedUrl) {
@@ -180,14 +205,9 @@ final class MediaLoader {
       return
     }
 
-    var options: [String: Any] = [:]
-    if let headers = resolved.headers, !headers.isEmpty {
-      options["AVURLAssetHTTPHeaderFieldsKey"] = headers
-    }
-
     let isLocalFile = mediaUrl.isFileURL
     url = isLocalFile ? URL(fileURLWithPath: mediaUrl.path) : mediaUrl
-    urlOptions = options.isEmpty ? nil : options
+    urlOptions = Self.buildAssetOptions(headers: resolved.headers, userAgent: resolved.userAgent)
 
     logger.debug("  final playbackUrl: \(mediaUrl.absoluteString)")
     logger.debug("  isLocalFile: \(isLocalFile)")

package/ios/Player/NowPlayingUpdater.swift

@@ -3,59 +3,153 @@ import MediaPlayer
 import NitroModules
 import os.log
 
-/// Does not exclusively own NowPlayingInfoController -- other callers
-/// (e.g. HybridAudioBrowser for overrides) can still access it directly.
+/// 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.
 @MainActor
 final class NowPlayingUpdater {
   private let logger = Logger(subsystem: "com.audiobrowser", category: "NowPlayingUpdater")
   private let nowPlayingInfoController: NowPlayingInfoController
 
   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)?
 
   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?
+  }
+
+  private var lastPublished: Published?
+
+  /// 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
+
   init(nowPlayingInfoController: NowPlayingInfoController) {
     self.nowPlayingInfoController = nowPlayingInfoController
   }
 
-  func loadMetaValues(for track: Track, rate: Float) {
+  /// 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: [
-      MediaItemProperty.artist(track.artist),
-      MediaItemProperty.title(track.title),
-      MediaItemProperty.albumTitle(track.album),
-      NowPlayingInfoProperty.playbackRate(Double(rate)),
       NowPlayingInfoProperty.isLiveStream(track.live),
     ])
+    applyFields(track: track, title: track.title, artist: track.artist, album: track.album)
     loadArtwork(for: track)
   }
 
-  func updatePlaybackValues(duration: Double, rate: Float, currentTime: Double) {
-    logger.debug("updatePlaybackValues: duration=\(duration), rate=\(rate), currentTime=\(currentTime)")
-    nowPlayingInfoController.set(keyValues: [
-      MediaItemProperty.duration(duration),
-      NowPlayingInfoProperty.playbackRate(Double(rate)),
-      NowPlayingInfoProperty.elapsedPlaybackTime(currentTime),
-    ])
-  }
+  /// Renders the now-playing text lines (title, artist, album): the default (`override ?? track`)
+  /// immediately, then — when a formatter is configured — its async result overlaid (each field
+  /// falling back to the default). A `flash` (transient line, e.g. feedback for a refused remote
+  /// 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(
+    track: Track,
+    timedMetadata: TimedMetadata?,
+    playWhenReady: Bool,
+    stalled: StallReason?,
+    error: PlaybackError?,
+    flash: NowPlayingUpdate? = nil,
+    override: NowPlayingUpdate?,
+    formatter: ((_ params: FormatNowPlayingParams) -> Promise<NowPlayingUpdate?>)?,
+  ) {
+    renderGeneration &+= 1
+    let generation = renderGeneration
+
+    let defaultTitle = override?.title ?? track.title
+    let defaultSecondary = override?.artist ?? track.artist
+    let defaultAlbum = override?.album ?? track.album
+
+    if let flash {
+      applyFields(
+        track: track,
+        title: flash.title ?? defaultTitle,
+        artist: flash.artist ?? defaultSecondary,
+        album: flash.album ?? defaultAlbum,
+      )
+      return
+    }
 
-  /// Separate from playbackRate — required for CarPlay to show correct play/pause button.
-  func updatePlaybackState(playWhenReady: Bool) {
-    let state: MPNowPlayingPlaybackState = playWhenReady ? .playing : .paused
-    logger.debug("updatePlaybackState: \(state.rawValue) (playWhenReady=\(playWhenReady))")
-    nowPlayingInfoController.setPlaybackState(state)
-  }
+    applyFields(track: track, title: defaultTitle, artist: defaultSecondary, album: defaultAlbum)
 
-  func setCurrentTime(seconds: Double) {
-    nowPlayingInfoController.set(
-      keyValue: NowPlayingInfoProperty.elapsedPlaybackTime(seconds),
+    guard let formatter else { return }
+    let params = FormatNowPlayingParams(
+      track: track,
+      timedMetadata: timedMetadata,
+      playWhenReady: playWhenReady,
+      stalled: stalled,
+      error: error,
     )
+    // `@Sendable` breaks the @MainActor isolation inheritance: Nitro resolves the promise on the JS
+    // thread, so the resolver must NOT be main-isolated (a main-isolated closure run off-main traps
+    // in `_swift_task_checkIsolated`). Hop back to the main actor to apply (same pattern as the
+    // artwork callback below).
+    formatter(params)
+      .then { @Sendable [weak self] formatted in
+        guard let self, let formatted else { return }
+        Task { @MainActor in
+          // Apply only if no newer render has superseded this one (fast skip / state moved on).
+          guard self.renderGeneration == generation else { return }
+          self.applyFields(
+            track: track,
+            title: formatted.title ?? defaultTitle,
+            artist: formatted.artist ?? defaultSecondary,
+            album: formatted.album ?? defaultAlbum,
+          )
+        }
+      }
+      .catch { @Sendable [weak self] error in
+        let message = error.localizedDescription
+        Task { @MainActor in
+          self?.logger.error("nowPlayingMetadataFormatter failed: \(message)")
+        }
+      }
   }
 
   // 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`.
+  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,
+    )
+    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 loadArtwork(for track: Track) {
-    let artworkUrl = track.artworkSource?.uri ?? track.artwork
+    // Now-playing is a single image with no appearance to key off, so a pair
+    // collapses to its dark URL (see `Variant_String_ArtworkVariants.url`).
+    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
@@ -102,5 +196,4 @@ final class NowPlayingUpdater {
       }
     }
   }
-
 }

package/ios/Player/PersistedPlaybackState.swift

@@ -0,0 +1,11 @@
+import Foundation
+
+/// A serialisable snapshot of the player's resumable state. Mirrors Android's
+/// `PlaybackStateStore.PersistedState`. `positionMs` is `nil` for live streams.
+struct PersistedPlaybackState: Codable {
+  let track: JsonTrack
+  let positionMs: Double?
+  let repeatMode: String
+  let shuffleEnabled: Bool
+  let playbackSpeed: Float
+}