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

package/ios/Model/TrackPlayerError.swift

@@ -1,6 +1,6 @@
 import Foundation
 #if canImport(NitroModules)
-import NitroModules
+  import NitroModules
 #endif
 
 public enum TrackPlayerError: Error {
@@ -8,8 +8,13 @@ public enum TrackPlayerError: Error {
     case failedToLoadKeyValue
     case invalidSourceUrl(String)
     case notConnectedToInternet
+    /// DNS, connect, timeout or a dropped connection — we never reached the host.
+    case hostUnreachable
+    /// The server answered with a non-2xx status.
+    case httpStatus(Int)
     case playbackFailed
     case trackWasUnplayable
+    case playbackStalled
   }
 
   public enum QueueError: Error {
@@ -28,10 +33,16 @@ extension TrackPlayerError.PlaybackError: LocalizedError {
       "Invalid audio source URL: \(url)"
     case .notConnectedToInternet:
       "No internet connection"
+    case .hostUnreachable:
+      "Could not reach the stream host"
+    case let .httpStatus(status):
+      "Server responded with HTTP \(status)"
     case .playbackFailed:
       "Playback failed"
     case .trackWasUnplayable:
       "Track is not playable"
+    case .playbackStalled:
+      "Playback stalled"
     }
   }
 }
@@ -49,25 +60,78 @@ extension TrackPlayerError.QueueError: LocalizedError {
   }
 }
 
-#if canImport(NitroModules)
-// MARK: - Nitro PlaybackError Conversion
+// MARK: - Cross-platform Classification
 
 public extension TrackPlayerError.PlaybackError {
-  /// Converts to Nitro PlaybackError for JS callbacks
-  func toNitroError() -> PlaybackError {
-    let code = switch self {
-    case .failedToLoadKeyValue:
-      "failed_to_load"
-    case .invalidSourceUrl:
-      "invalid_source_url"
-    case .notConnectedToInternet:
-      "not_connected_to_internet"
-    case .playbackFailed:
-      "playback_failed"
-    case .trackWasUnplayable:
-      "track_unplayable"
+  /// The platform-specific identifier, for diagnostics only. Consumers branch
+  /// on `kind`; this is what they log.
+  var code: String {
+    switch self {
+    case .failedToLoadKeyValue: "failed-to-load"
+    case .invalidSourceUrl: "invalid-source-url"
+    case .notConnectedToInternet: "not-connected-to-internet"
+    case .hostUnreachable: "host-unreachable"
+    case .httpStatus: "http-status"
+    case .playbackFailed: "playback-failed"
+    case .trackWasUnplayable: "track-unplayable"
+    case .playbackStalled: "playback-stalled"
+    }
+  }
+
+  /// The normalized classification handed to JS. Android derives the same set
+  /// from its ExoPlayer codes, so app-side copy can switch on this alone.
+  var kind: PlaybackErrorKind {
+    switch self {
+    case .notConnectedToInternet: .offline
+    case .hostUnreachable: .unreachable
+    case let .httpStatus(status): TrackPlayerError.PlaybackError.kind(forHttpStatus: status)
+    // A missing or malformed source URL is a broken stream from the listener's
+    // side — same outcome as an undecodable one.
+    case .invalidSourceUrl, .trackWasUnplayable: .unplayable
+    case .playbackStalled: .stalled
+    // Context fallbacks: the underlying error carried nothing we could classify.
+    case .failedToLoadKeyValue, .playbackFailed: .unknown
+    }
+  }
+
+  /// The HTTP status behind this error, when it came from a server response.
+  var statusCode: Int? {
+    if case let .httpStatus(status) = self { return status }
+    return nil
+  }
+
+  static func kind(forHttpStatus status: Int) -> PlaybackErrorKind {
+    switch status {
+    case 404, 410: .notFound
+    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
+    default: .unknown
     }
-    return PlaybackError(code: code, message: errorDescription ?? "Unknown error")
   }
 }
-#endif
+
+// MARK: - Nitro PlaybackError Conversion
+
+// Internal, not public: the stub `PlaybackError` struct is internal, and every
+// caller of this lives in the module.
+extension TrackPlayerError.PlaybackError {
+  /// Converts to Nitro PlaybackError for JS callbacks.
+  ///
+  /// Deliberately not behind `#if canImport(NitroModules)`: the stub struct in
+  /// `NitroTypeStubs` mirrors the generated one field for field, so this single
+  /// definition compiles in both worlds and the tests exercise the shipped
+  /// converter rather than a copy of it.
+  /// `retrying` marks an advisory error the retry loop is still working on
+  /// (surfaced with a non-terminal playback state); terminal errors leave it nil.
+  func toNitroError(retrying: Bool = false) -> PlaybackError {
+    PlaybackError(
+      kind: kind,
+      code: code,
+      message: errorDescription ?? "Unknown error",
+      statusCode: statusCode.map(Double.init),
+      retrying: retrying ? true : nil,
+    )
+  }
+}

package/ios/NowPlayingInfo/NowPlayingInfoController.swift

@@ -8,184 +8,162 @@ extension MPRemoteCommandCenter: @retroactive @unchecked Sendable {}
 
 /// Controller for managing Now Playing info.
 ///
-/// On iOS 16+, uses `MPNowPlayingSession` with `automaticallyPublishNowPlayingInfo` to let the system
-/// automatically update elapsed time, playback rate, and duration. We still manually set metadata
-/// (title, artist, artwork) which the automatic publishing doesn't handle.
-///
-/// On iOS 15.x, falls back to manual `MPNowPlayingInfoCenter` updates for all properties.
+/// 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`).
 @MainActor
 class NowPlayingInfoController {
   private let logger = Logger(subsystem: "com.audiobrowser", category: "NowPlayingInfoController")
 
-  private(set) var infoCenter: NowPlayingInfoCenter
   private var _info: [String: Any] = [:]
 
-  /// Wrapper for MPNowPlayingSession (iOS 16+) to avoid @available on stored property
-  private var _nowPlayingSession: Any?
+  /// Last play/pause state pushed to the session's center, to skip redundant writes.
+  private var _playbackState: MPNowPlayingPlaybackState?
 
-  /// The linked AVPlayer (iOS 16+)
-  private weak var _linkedPlayer: AVPlayer?
+  /// The session bound to the linked AVPlayer; held so it stays alive while publishing.
+  private var nowPlayingSession: MPNowPlayingSession?
 
-  /// Whether automatic publishing is currently active (iOS 16+ with linked player)
-  private var isAutomaticPublishingEnabled: Bool = false
+  /// The linked AVPlayer — metadata is attached to its current item.
+  private weak var linkedPlayer: AVPlayer?
 
-  /// The current remote command center - either the session's (iOS 16+) or shared
+  /// The current remote command center - the session's while linked, else the shared one.
   private(set) var remoteCommandCenter: MPRemoteCommandCenter = .shared()
 
-  /// The current Now Playing info dictionary
-  var info: [String: Any] { _info }
-
-  required init() {
-    infoCenter = MPNowPlayingInfoCenter.default()
-  }
+  required init() {}
 
-  required init(infoCenter: NowPlayingInfoCenter) {
-    self.infoCenter = infoCenter
-  }
-
-  /// Callback invoked when the remote command center changes (iOS 16+ session created/destroyed)
+  /// Callback invoked when the remote command center changes (session created/destroyed).
   var onRemoteCommandCenterChanged: ((MPRemoteCommandCenter) -> Void)?
 
-  /// Links an AVPlayer to enable automatic Now Playing publishing on iOS 16+.
-  /// On older iOS versions, this is a no-op.
-  ///
-  /// When linked:
-  /// - System automatically updates elapsed time, playback rate, and duration
-  /// - Metadata (title, artist, artwork) is set via `AVPlayerItem.nowPlayingInfo`
-  /// - The session's `remoteCommandCenter` must be used for remote commands
+  /// Binds an AVPlayer to a new auto-publishing `MPNowPlayingSession`.
   ///
-  /// - Important: On iOS 16+, this creates an `MPNowPlayingSession` with its own `remoteCommandCenter`.
-  ///   The `onRemoteCommandCenterChanged` callback will be invoked with the new command center.
+  /// - Important: This creates an `MPNowPlayingSession` with its own `remoteCommandCenter`;
+  ///   the `onRemoteCommandCenterChanged` callback is invoked with the new command center.
   func linkPlayer(_ player: AVPlayer) {
-    if #available(iOS 16.0, *) {
-      logger.info("Linking AVPlayer to MPNowPlayingSession for automatic publishing")
+    logger.notice("Linking AVPlayer to MPNowPlayingSession for automatic publishing")
 
-      _linkedPlayer = player
+    linkedPlayer = player
 
-      let session = MPNowPlayingSession(players: [player])
-      _nowPlayingSession = session
+    let session = MPNowPlayingSession(players: [player])
+    nowPlayingSession = session
+    _playbackState = nil // new center starts at .unknown; force the next write
+    remoteCommandCenter = session.remoteCommandCenter
 
-      remoteCommandCenter = session.remoteCommandCenter
+    session.automaticallyPublishesNowPlayingInfo = true
 
-      session.automaticallyPublishesNowPlayingInfo = true
+    session.becomeActiveIfPossible { success in
+      self.logger.notice("MPNowPlayingSession becomeActiveIfPossible: \(success)")
+    }
 
-      session.becomeActiveIfPossible { success in
-        self.logger.info("MPNowPlayingSession becomeActiveIfPossible: \(success)")
-      }
+    onRemoteCommandCenterChanged?(remoteCommandCenter)
+  }
 
-      isAutomaticPublishingEnabled = true
-      onRemoteCommandCenterChanged?(remoteCommandCenter)
-    } else {
-      logger.debug("linkPlayer: iOS 16+ required for automatic publishing, using manual updates")
+  /// Re-requests now-playing activation for the linked session.
+  ///
+  /// `linkPlayer` runs at player setup, before the audio session is active, and the
+  /// system can decline the election at that point. Without a later re-request the
+  /// session stays unfeatured until actual audio output elects the app through the
+  /// system's own path — which never happens when the first-ever load fails (a cold
+  /// start onto a dead stream showed no now-playing surface at all). Call whenever
+  /// the audio session (re)activates; no-op while already active.
+  func reactivateSessionIfNeeded() {
+    guard let session = nowPlayingSession, !session.isActive else { return }
+    logger.notice("MPNowPlayingSession inactive (canBecomeActive: \(session.canBecomeActive)) — re-requesting activation")
+    session.becomeActiveIfPossible { success in
+      self.logger.notice("MPNowPlayingSession re-activation: \(success)")
     }
   }
 
-  /// Unlinks the AVPlayer, disabling automatic publishing.
+  /// Unlinks the AVPlayer, tearing down the session and restoring the shared command center.
   func unlinkPlayer() {
-    if #available(iOS 16.0, *) {
-      logger.info("Unlinking AVPlayer from MPNowPlayingSession")
-
-      _linkedPlayer = nil
+    logger.info("Unlinking AVPlayer from MPNowPlayingSession")
 
-      if let session = _nowPlayingSession as? MPNowPlayingSession {
-        session.automaticallyPublishesNowPlayingInfo = false
-      }
-      _nowPlayingSession = nil
-      isAutomaticPublishingEnabled = false
+    linkedPlayer = nil
+    nowPlayingSession?.automaticallyPublishesNowPlayingInfo = false
+    nowPlayingSession = nil
+    _playbackState = nil
 
-      remoteCommandCenter = MPRemoteCommandCenter.shared()
-      onRemoteCommandCenterChanged?(remoteCommandCenter)
-    }
+    remoteCommandCenter = MPRemoteCommandCenter.shared()
+    onRemoteCommandCenterChanged?(remoteCommandCenter)
   }
 
-  /// Keys that are automatically published by MPNowPlayingSession on iOS 16+.
-  /// When automatic publishing is enabled, we skip setting these manually.
+  /// Keys the session derives from the player itself — we never set these manually,
+  /// the system owns elapsed/duration/rate.
   private static let autoPublishedKeys: Set<String> = [
     MPNowPlayingInfoPropertyElapsedPlaybackTime,
     MPMediaItemPropertyPlaybackDuration,
     MPNowPlayingInfoPropertyPlaybackRate,
   ]
 
-  /// Returns true if the key is auto-published and automatic publishing is enabled
-  private func shouldSkipKey(_ key: String) -> Bool {
-    isAutomaticPublishingEnabled && Self.autoPublishedKeys.contains(key)
-  }
-
-  /// Sets key-values and immediately updates the Now Playing Info Center.
-  /// When automatic publishing is enabled (iOS 16+), playback-related keys are skipped.
-  func set(keyValues: [NowPlayingInfoKeyValue]) {
-    for kv in keyValues {
-      if !shouldSkipKey(kv.key) {
-        _info[kv.key] = kv.value
-      }
+  /// Whether a new value matches what's already in `_info` — used to avoid
+  /// re-publishing unchanged metadata. Compares the comparable scalar types we
+  /// store (title/artist/album strings, isLiveStream); non-comparable values
+  /// (e.g. artwork) are treated as changed.
+  private func valueUnchanged(_ key: String, _ newValue: Any?) -> Bool {
+    switch (_info[key], newValue) {
+    case (nil, nil): true
+    case let (a as String, b as String): a == b
+    case let (a as Bool, b as Bool): a == b
+    case let (a as NSNumber, b as NSNumber): a == b
+    default: false
     }
-    performUpdate()
   }
 
-  /// Sets key-values without updating the Now Playing Info Center.
-  /// Useful for batching multiple updates - call update() when ready to commit.
-  /// When automatic publishing is enabled (iOS 16+), playback-related keys are skipped.
-  func setWithoutUpdate(keyValues: [NowPlayingInfoKeyValue]) {
-    for kv in keyValues {
-      if !shouldSkipKey(kv.key) {
-        _info[kv.key] = kv.value
-      }
+  /// 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]) {
+    var changed = false
+    for kv in keyValues where !Self.autoPublishedKeys.contains(kv.key) && !valueUnchanged(kv.key, kv.value) {
+      _info[kv.key] = kv.value
+      changed = true
     }
+    if changed { performUpdate() }
   }
 
-  /// Sets a single key-value and immediately updates the Now Playing Info Center.
-  /// When automatic publishing is enabled (iOS 16+), playback-related keys are skipped.
+  /// Sets a single key-value and immediately updates Now Playing.
   func set(keyValue: NowPlayingInfoKeyValue) {
-    if !shouldSkipKey(keyValue.key) {
-      _info[keyValue.key] = keyValue.value
-      performUpdate()
-    }
-  }
-
-  /// Explicitly updates the Now Playing Info Center with the current info.
-  /// Use after calling setWithoutUpdate() to commit batched changes.
-  func update() {
+    guard !Self.autoPublishedKeys.contains(keyValue.key), !valueUnchanged(keyValue.key, keyValue.value) else { return }
+    _info[keyValue.key] = keyValue.value
     performUpdate()
   }
 
-  /// Pushes the current info to the appropriate Now Playing target.
-  ///
-  /// On iOS 16+ with automatic publishing:
-  /// - Sets metadata on `AVPlayerItem.nowPlayingInfo`
-  /// - Skips elapsed time and duration (system handles these)
-  ///
-  /// On iOS 15.x or without automatic publishing:
-  /// - Sets all info on `MPNowPlayingInfoCenter.default().nowPlayingInfo`
+  /// Attaches metadata to the current item — the supported channel under automatic publishing.
+  /// While no item exists (the media URL resolve is still in flight), publishes to the
+  /// session's center directly so the Now Playing surface isn't blank between load
+  /// intent and item creation; the item channel takes over via `prepareItem`.
   private func performUpdate() {
-    if #available(iOS 16.0, *), isAutomaticPublishingEnabled {
-      _linkedPlayer?.currentItem?.nowPlayingInfo = _info
+    if let item = linkedPlayer?.currentItem {
+      item.nowPlayingInfo = _info
     } else {
-      infoCenter.nowPlayingInfo = _info
+      nowPlayingSession?.nowPlayingInfoCenter.nowPlayingInfo = _info
     }
   }
 
-  /// Prepares an AVPlayerItem with stored metadata before it becomes current.
-  /// Call this before `replaceCurrentItem(with:)` so the item has metadata from the start.
+  /// Prepares an AVPlayerItem with stored metadata before it becomes current, so the
+  /// session has metadata from the moment the item starts playing.
+  /// Call this before `replaceCurrentItem(with:)`.
   func prepareItem(_ item: AVPlayerItem) {
-    if #available(iOS 16.0, *), isAutomaticPublishingEnabled {
-      item.nowPlayingInfo = _info
-    }
+    item.nowPlayingInfo = _info
   }
 
-  /// Clears all Now Playing info
+  /// Clears all Now Playing info.
   func clear() {
     _info = [:]
-
-    // With automatic publishing, the session handles clearing when the player stops
-    // Without automatic publishing, we need to clear MPNowPlayingInfoCenter manually
-    if !isAutomaticPublishingEnabled {
-      infoCenter.nowPlayingInfo = nil
-    }
+    linkedPlayer?.currentItem?.nowPlayingInfo = nil
+    nowPlayingSession?.nowPlayingInfoCenter.nowPlayingInfo = nil
   }
 
-  /// Sets the playback state (required for CarPlay Now Playing to show correct play/pause state)
-  func setPlaybackState(_ state: MPNowPlayingPlaybackState) {
-    logger.debug("setPlaybackState: \(state.rawValue)")
-    infoCenter.playbackState = state
+  /// 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/NowPlayingInfo/SilentAudioPrimer.swift

@@ -0,0 +1,73 @@
+import AVFoundation
+import Foundation
+import os.log
+
+/// Renders a fraction of a second of generated silence through the app's audio session.
+///
+/// iOS elects an app onto the system now-playing surfaces (lock screen, Control
+/// Center, the CarPlay now-playing template) only once its audio session actually
+/// renders output. Published metadata alone never surfaces — and the explicit
+/// `MPNowPlayingInfoCenter.playbackState` write is dropped on iOS without a private
+/// entitlement (`com.apple.mediaremote.set-playback-state`), so there is no
+/// declarative way in. When the very first load of a session fails, no audio ever
+/// renders and the failure line + transport controls have nowhere to appear.
+/// Rendering one burst of silence satisfies the election rule; the session's
+/// already-published info (station + failure line) then displays.
+///
+/// The samples are zeros: inaudible by construction, no volume tricks involved.
+@MainActor
+final class SilentAudioPrimer {
+  private let logger = Logger(subsystem: "com.audiobrowser", category: "SilentAudioPrimer")
+
+  private static let duration: TimeInterval = 0.3
+
+  /// Held while playing so the player isn't deallocated mid-render.
+  private var player: AVAudioPlayer?
+
+  func prime() {
+    guard player == nil else { return }
+    guard let wav = Self.silentWav else { return }
+    do {
+      let player = try AVAudioPlayer(data: wav)
+      self.player = player
+      logger.notice("Priming now-playing election with \(Self.duration)s of silence")
+      player.play()
+      DispatchQueue.main.asyncAfter(deadline: .now() + Self.duration + 0.2) { [weak self] in
+        self?.player = nil
+      }
+    } catch {
+      logger.error("Failed to create silent primer player: \(error.localizedDescription)")
+    }
+  }
+
+  /// A minimal mono 16-bit PCM WAV of silence. 8 kHz keeps it a few KB — the
+  /// content is zeros, so fidelity is irrelevant.
+  private static let silentWav: Data? = makeSilentWav()
+
+  private static func makeSilentWav() -> Data? {
+    let sampleRate = 8000
+    let sampleCount = Int(Double(sampleRate) * duration)
+    let dataSize = sampleCount * 2 // 16-bit mono
+    var data = Data(capacity: 44 + dataSize)
+
+    func append(_ string: String) { data.append(contentsOf: Array(string.utf8)) }
+    func append32(_ value: Int) { withUnsafeBytes(of: UInt32(value).littleEndian) { data.append(contentsOf: $0) } }
+    func append16(_ value: Int) { withUnsafeBytes(of: UInt16(value).littleEndian) { data.append(contentsOf: $0) } }
+
+    append("RIFF")
+    append32(36 + dataSize)
+    append("WAVE")
+    append("fmt ")
+    append32(16) // PCM fmt chunk size
+    append16(1) // linear PCM
+    append16(1) // mono
+    append32(sampleRate)
+    append32(sampleRate * 2) // byte rate
+    append16(2) // block align
+    append16(16) // bits per sample
+    append("data")
+    append32(dataSize)
+    data.append(contentsOf: [UInt8](repeating: 0, count: dataSize))
+    return data
+  }
+}

package/ios/Observer/PlayerItemNotificationObserver.swift

@@ -12,13 +12,16 @@ import Foundation
 
   private let onDidPlayToEndTime: @MainActor () -> Void
   private let onFailedToPlayToEndTime: @MainActor (Error?) -> Void
+  private let onPlaybackStalled: @MainActor () -> Void
 
   init(
     onDidPlayToEndTime: @escaping @MainActor () -> Void,
     onFailedToPlayToEndTime: @escaping @MainActor (Error?) -> Void,
+    onPlaybackStalled: @escaping @MainActor () -> Void,
   ) {
     self.onDidPlayToEndTime = onDidPlayToEndTime
     self.onFailedToPlayToEndTime = onFailedToPlayToEndTime
+    self.onPlaybackStalled = onPlaybackStalled
   }
 
   /**
@@ -33,7 +36,7 @@ import Foundation
     isObserving = true
     notificationCenter.addObserver(
       self,
-      selector: #selector(avItemDidPlayToEndTime),
+      selector: #selector(avItemDidPlayToEndTime(_:)),
       name: NSNotification.Name.AVPlayerItemDidPlayToEndTime,
       object: avItem,
     )
@@ -43,6 +46,12 @@ import Foundation
       name: NSNotification.Name.AVPlayerItemFailedToPlayToEndTime,
       object: avItem,
     )
+    notificationCenter.addObserver(
+      self,
+      selector: #selector(avItemPlaybackStalled(_:)),
+      name: NSNotification.Name.AVPlayerItemPlaybackStalled,
+      object: avItem,
+    )
   }
 
   /**
@@ -62,18 +71,49 @@ import Foundation
       name: NSNotification.Name.AVPlayerItemFailedToPlayToEndTime,
       object: observingAVItem,
     )
+    notificationCenter.removeObserver(
+      self,
+      name: NSNotification.Name.AVPlayerItemPlaybackStalled,
+      object: observingAVItem,
+    )
     self.observingAVItem = nil
     isObserving = false
   }
 
-  @objc nonisolated private func avItemDidPlayToEndTime() {
-    Task { @MainActor in self.onDidPlayToEndTime() }
+  @objc private nonisolated func avItemDidPlayToEndTime(_ notification: Notification) {
+    let identity = (notification.object as? AVPlayerItem).map(ObjectIdentifier.init)
+    Task { @MainActor in
+      guard self.isObserving(identity) else { return }
+      self.onDidPlayToEndTime()
+    }
   }
 
-  @objc nonisolated private func avItemFailedToPlayToEndTime(_ notification: Notification) {
+  @objc private nonisolated func avItemFailedToPlayToEndTime(_ notification: Notification) {
     // Extract the error from the notification's userInfo
     // AVPlayerItemFailedToPlayToEndTimeErrorKey contains the actual error
     let error = notification.userInfo?[AVPlayerItemFailedToPlayToEndTimeErrorKey] as? Error
-    Task { @MainActor in self.onFailedToPlayToEndTime(error) }
+    let identity = (notification.object as? AVPlayerItem).map(ObjectIdentifier.init)
+    Task { @MainActor in
+      guard self.isObserving(identity) else { return }
+      self.onFailedToPlayToEndTime(error)
+    }
+  }
+
+  // Fired when the item's buffer empties mid-playback. iOS exposes no
+  // rebuffer-vs-initial signal otherwise, and AVPlayer can stay parked in
+  // `.waitingToPlayAtSpecifiedRate` after data returns — the listener nudges it.
+  @objc private nonisolated func avItemPlaybackStalled(_ notification: Notification) {
+    let identity = (notification.object as? AVPlayerItem).map(ObjectIdentifier.init)
+    Task { @MainActor in
+      guard self.isObserving(identity) else { return }
+      self.onPlaybackStalled()
+    }
+  }
+
+  /// True when `identity` still names the observed item. Notifications are posted off the main
+  /// thread, so the main-actor hop can land after the observer switched items — without this
+  /// check the old item's late delivery (e.g. a stale failure) reaches the new item's handlers.
+  private func isObserving(_ identity: ObjectIdentifier?) -> Bool {
+    identity != nil && observingAVItem.map(ObjectIdentifier.init) == identity
   }
 }

package/ios/Observer/PlayerItemPropertyObserver.swift

@@ -47,22 +47,38 @@ extension AVTimedMetadataGroup: @retroactive @unchecked Sendable {}
     observations = [
       avItem.observe(\.duration, options: [.new]) { [weak self] item, _ in
         let seconds = item.duration.seconds
-        Task { @MainActor in self?.onDurationUpdate(seconds) }
+        let identity = ObjectIdentifier(item)
+        Task { @MainActor in
+          guard let self, self.isObserving(identity) else { return }
+          self.onDurationUpdate(seconds)
+        }
       },
       avItem.observe(\.loadedTimeRanges, options: [.new]) { [weak self] item, _ in
         if let duration = item.loadedTimeRanges.first?.timeRangeValue.duration {
           let seconds = duration.seconds
-          Task { @MainActor in self?.onDurationUpdate(seconds) }
+          let identity = ObjectIdentifier(item)
+          Task { @MainActor in
+            guard let self, self.isObserving(identity) else { return }
+            self.onDurationUpdate(seconds)
+          }
         }
       },
       avItem.observe(\.isPlaybackLikelyToKeepUp, options: [.new]) { [weak self] item, _ in
         let isLikely = item.isPlaybackLikelyToKeepUp
-        Task { @MainActor in self?.onPlaybackLikelyToKeepUpUpdate(isLikely) }
+        let identity = ObjectIdentifier(item)
+        Task { @MainActor in
+          guard let self, self.isObserving(identity) else { return }
+          self.onPlaybackLikelyToKeepUpUpdate(isLikely)
+        }
       },
       avItem.observe(\.status, options: [.new]) { [weak self] item, _ in
         let status = item.status
         let error = item.error
-        Task { @MainActor in self?.onStatusChange(status, error) }
+        let identity = ObjectIdentifier(item)
+        Task { @MainActor in
+          guard let self, self.isObserving(identity) else { return }
+          self.onStatusChange(status, error)
+        }
       },
     ]
 
@@ -83,6 +99,13 @@ extension AVTimedMetadataGroup: @retroactive @unchecked Sendable {}
     observingAVItem = nil
     currentMetadataOutput = nil
   }
+
+  /// True when `identity` still names the observed item. KVO fires off the main thread, so
+  /// the main-actor hop can land after the observer switched items — without this check a
+  /// stale delivery (e.g. the old item's `.failed`) is attributed to the freshly loaded one.
+  private func isObserving(_ identity: ObjectIdentifier) -> Bool {
+    observingAVItem.map(ObjectIdentifier.init) == identity
+  }
 }
 
 extension PlayerItemPropertyObserver: AVPlayerItemMetadataOutputPushDelegate {