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

package/ios/Player/PlaybackErrorHandler.swift

@@ -1,9 +1,14 @@
+import AVFoundation
 import Foundation
 import os.log
 
 /// Abstracts RetryManager for testability.
 @MainActor public protocol RetryHandling: AnyObject {
-  func isRetryable(_ error: Error?) -> Bool
+  /// False when the configured policy is `disabled` — every error is then terminal.
+  var isEnabled: Bool { get }
+  /// Whether the current load has produced audio — selects the retry budget.
+  var hasPlayed: Bool { get set }
+  func isRetryable(_ error: Error?, httpStatusCode: Int?) -> Bool
   func attemptRetry(startFromCurrentTime: Bool) async -> Bool
   func reset()
 }
@@ -18,15 +23,15 @@ public enum PlaybackErrorContext {
 
   var startFromCurrentTime: Bool {
     switch self {
-    case .playback:   true
-    case .mediaLoad:  false
+    case .playback: true
+    case .mediaLoad: false
     }
   }
 
   var fallbackError: TrackPlayerError.PlaybackError {
     switch self {
-    case .playback:   .playbackFailed
-    case .mediaLoad:  .failedToLoadKeyValue
+    case .playback: .playbackFailed
+    case .mediaLoad: .failedToLoadKeyValue
     }
   }
 }
@@ -37,6 +42,11 @@ public enum PlaybackErrorContext {
   private let logger = Logger(subsystem: "com.audiobrowser", category: "PlaybackErrorHandler")
 
   var onError: ((TrackPlayerError.PlaybackError) -> Void)?
+  /// A failure the retry loop is still working on. Fired when a retry is
+  /// scheduled, before its backoff elapses, so UIs can show the cause while
+  /// the playback state stays non-terminal. `onError` still fires if the
+  /// retries give up.
+  var onRetryingError: ((TrackPlayerError.PlaybackError) -> Void)?
   private(set) var pendingRetryTask: Task<Void, Never>?
   private let retryHandler: any RetryHandling
 
@@ -44,7 +54,7 @@ public enum PlaybackErrorContext {
     self.retryHandler = retryHandler
   }
 
-  func handleError(_ error: Error?, context: PlaybackErrorContext) {
+  func handleError(_ error: Error?, context: PlaybackErrorContext, httpStatusCode: Int? = nil) {
     if let error {
       let nsError = error as NSError
       logger.error("[\(String(describing: context))] failure: domain=\(nsError.domain), code=\(nsError.code), localizedDescription=\(error.localizedDescription)")
@@ -52,21 +62,30 @@ public enum PlaybackErrorContext {
       logger.error("[\(String(describing: context))] failure with nil error")
     }
 
-    if retryHandler.isRetryable(error) {
+    if retryHandler.isEnabled, retryHandler.isRetryable(error, httpStatusCode: httpStatusCode) {
+      onRetryingError?(PlaybackErrorHandler.classify(
+        error: error, fallback: context.fallbackError, httpStatusCode: httpStatusCode,
+      ))
       pendingRetryTask?.cancel()
       pendingRetryTask = Task { [weak self] in
         guard let self else { return }
         let retried = await retryHandler.attemptRetry(startFromCurrentTime: context.startFromCurrentTime)
+        // Cancelled (track change / stop): stay silent — attemptRetry returns
+        // false on a cancelled wait, and surfacing that would flip the new
+        // track or a deliberate stop to .error. The canceller owns the handle.
+        if Task.isCancelled { return }
         if !retried {
-          let classified = PlaybackErrorHandler.classify(error: error, fallback: context.fallbackError)
+          let classified = PlaybackErrorHandler.classify(error: error, fallback: context.fallbackError, httpStatusCode: httpStatusCode)
           self.onError?(classified)
         }
+        // Clear the handle: session release is gated on no pending retry.
+        pendingRetryTask = nil
       }
       return
     }
 
     logger.warning("Error not retryable, surfacing \(String(describing: context.fallbackError))")
-    let classified = PlaybackErrorHandler.classify(error: error, fallback: context.fallbackError)
+    let classified = PlaybackErrorHandler.classify(error: error, fallback: context.fallbackError, httpStatusCode: httpStatusCode)
     onError?(classified)
   }
 
@@ -80,12 +99,77 @@ public enum PlaybackErrorContext {
     retryHandler.reset()
   }
 
-  /// Classifies an error, checking for internet connectivity issues before falling back.
-  public static func classify(error: Error?, fallback: TrackPlayerError.PlaybackError) -> TrackPlayerError.PlaybackError {
-    let nsError = error as NSError?
-    if nsError?.code == URLError.notConnectedToInternet.rawValue {
-      return .notConnectedToInternet
+  /// A restart from a terminal error begins a new load of the same track:
+  /// fresh budgets and unproven playback, so the user's tap yields a visible
+  /// first-connect retry window instead of a single silent attempt — the same
+  /// behavior as re-selecting the track (ADR 0004).
+  func resetForNewLoad() {
+    resetRetry()
+    retryHandler.hasPlayed = false
+  }
+
+  /// Classifies an error into the narrowest case the evidence supports, so JS
+  /// receives a real `kind` rather than a context fallback.
+  ///
+  /// Order matters: a transport failure means we never got a response, so it
+  /// outranks any status left in the item's error log. AVFoundation reports
+  /// HTTP failures as opaque CoreMedia errors, which is why `httpStatusCode`
+  /// is passed in separately by the caller rather than read off `error`.
+  public static func classify(
+    error: Error?,
+    fallback: TrackPlayerError.PlaybackError,
+    httpStatusCode: Int? = nil,
+  ) -> TrackPlayerError.PlaybackError {
+    // `as?` bridges plain `NSError`s in `NSURLErrorDomain` too, which is the
+    // form AVFoundation usually hands back.
+    if let urlError = error as? URLError {
+      switch urlError.code {
+      case .notConnectedToInternet:
+        return .notConnectedToInternet
+      case .timedOut,
+           .cannotFindHost,
+           .cannotConnectToHost,
+           .networkConnectionLost,
+           .dnsLookupFailed,
+           .secureConnectionFailed:
+        return .hostUnreachable
+      default:
+        break
+      }
+    }
+
+    if let httpStatusCode, !(200 ... 299).contains(httpStatusCode) {
+      return .httpStatus(httpStatusCode)
+    }
+
+    if isUnplayableMedia(error) {
+      return .trackWasUnplayable
     }
+
     return fallback
   }
+
+  /// Picks the HTTP status out of an `AVPlayerItem` error log's status codes.
+  ///
+  /// `errorStatusCode` is a mixed space — negative OSStatus values share it
+  /// with HTTP statuses — so only in-range values count, and the newest wins:
+  /// a live stream reconnects, and older entries describe earlier attempts.
+  public static func httpStatusCode(fromErrorStatusCodes codes: [Int]) -> Int? {
+    codes.last { (100 ... 599).contains($0) }
+  }
+
+  /// The stream was fetched but cannot be decoded — unknown container,
+  /// unsupported codec, or a decoder that refused it.
+  private static func isUnplayableMedia(_ error: Error?) -> Bool {
+    guard let nsError = error as NSError? else { return false }
+    guard nsError.domain == AVFoundationErrorDomain else { return false }
+    return [
+      AVError.fileFormatNotRecognized,
+      AVError.failedToParse,
+      AVError.decoderNotFound,
+      AVError.decoderTemporarilyUnavailable,
+      AVError.formatUnsupported,
+      AVError.contentIsUnavailable,
+    ].contains { $0.rawValue == nsError.code }
+  }
 }

package/ios/Player/PlaybackStateMachine.swift

@@ -5,27 +5,32 @@
 /// site and decide whether to fire the event at all.
 func nextPlaybackState(from current: PlaybackState, on event: PlaybackEvent) -> PlaybackState? {
   switch event {
-  case .stopped:             return .stopped
-  case .trackLoading:        return .loading
-  case .trackUnloaded:       return PlaybackState.none
+  case .stopped: return .stopped
+  case .trackLoading: return .loading
+  case .trackUnloaded: return PlaybackState.none
   case .trackEndedNaturally: return .ended
-  case .avPlayerWaiting:     return .buffering
-  case .avPlayerPlaying:     return .playing
-  case .audioFrameDecoded:   return .playing
-  case .errorOccurred:       return .error
-
+  case .avPlayerWaiting: return .buffering
+  case .avPlayerPlaying: return .playing
+  case .audioFrameDecoded: return .playing
+  case .errorOccurred: return .error
   case .loadSeekCompleted:
     guard current == .loading else { return nil }
     return .ready
-
-  case .avPlayerPaused(let hasAsset):
+  case let .avPlayerPaused(hasAsset):
     guard current != .stopped else { return nil }
     if !hasAsset { return PlaybackState.none }
-    guard current != .error else { return nil }
+    // .error and .ended own their state against stray pause observations —
+    // reachable from .ended since the natural-end intent clear opens the
+    // call site's `!playWhenReady` gate.
+    guard current != .error, current != .ended else { return nil }
     return .paused
-
   case .bufferingSufficient:
-    guard current != .playing, current != .ended else { return nil }
+    // Terminal states must not drift back to .ready on a buffer refill: .ended
+    // would restart the completed track (playWhenReady is still true), and
+    // .stopped/.error would skip the reload-on-play path, which only triggers
+    // from those states. Leaving them requires an explicit load or reload.
+    guard current != .playing, current != .ended, current != .stopped, current != .error
+    else { return nil }
     return .ready
   }
 }

package/ios/Player/PlaybackStateStore.swift

@@ -0,0 +1,27 @@
+import Foundation
+
+/// Persists the player's resumable state to UserDefaults so a cold-start
+/// "resume" intent can restore the last session without the JS runtime.
+/// Swift counterpart of Android's `PlaybackStateStore.kt`.
+final class PlaybackStateStore {
+  private let defaults: UserDefaults
+  private let key = "playbackState.v1"
+
+  init(defaults: UserDefaults = UserDefaults(suiteName: "com.audiobrowser.playback") ?? .standard) {
+    self.defaults = defaults
+  }
+
+  func save(_ state: PersistedPlaybackState) {
+    guard 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)
+  }
+
+  func clear() {
+    defaults.removeObject(forKey: key)
+  }
+}

package/ios/Player/PlaybackTimer.swift

@@ -0,0 +1,61 @@
+import Foundation
+#if canImport(NitroModules)
+  import NitroModules
+#endif
+
+/// A playback-gated repeating timer. Runs `onTick` every `interval` seconds while
+/// the current playback state satisfies `isActive`. `interval == nil` (or <= 0)
+/// means stopped — that is the single off-switch.
+@MainActor
+final class PlaybackTimer {
+  // nonisolated(unsafe) for deinit cleanup — Timer must be invalidated to break
+  // the RunLoop retain, and deinit is always nonisolated in Swift 6.
+  private nonisolated(unsafe) var timer: Timer?
+  private var interval: TimeInterval?
+  private var active = false
+  private let isActive: (PlaybackState) -> Bool
+  private let onTick: () -> Void
+
+  init(isActive: @escaping (PlaybackState) -> Bool, onTick: @escaping () -> Void) {
+    self.isActive = isActive
+    self.onTick = onTick
+  }
+
+  deinit {
+    timer?.invalidate()
+  }
+
+  func setInterval(_ interval: TimeInterval?) {
+    let normalized = (interval ?? 0) > 0 ? interval : nil
+    if normalized == self.interval { return }
+    self.interval = normalized
+    stop() // restart with the new interval on the next reconcile
+    reconcile()
+  }
+
+  func onPlaybackStateChanged(_ state: PlaybackState) {
+    active = isActive(state)
+    reconcile()
+  }
+
+  private func reconcile() {
+    if let interval, active {
+      start(interval)
+    } else {
+      stop()
+    }
+  }
+
+  private func start(_ interval: TimeInterval) {
+    guard timer == nil else { return }
+    timer = Timer.scheduledTimer(withTimeInterval: interval, repeats: true) {
+      [weak self] _ in
+      MainActor.assumeIsolated { self?.onTick() }
+    }
+  }
+
+  private func stop() {
+    timer?.invalidate()
+    timer = nil
+  }
+}

package/ios/Player/PlayingStateManager.swift

@@ -1,6 +1,6 @@
 import Foundation
 #if canImport(NitroModules)
-import NitroModules
+  import NitroModules
 #endif
 
 /// Manages the playing state (playing and buffering flags) and notifies when they change.
@@ -16,7 +16,8 @@ class PlayingStateManager {
   }
 
   func update(playWhenReady: Bool, state: PlaybackState) {
-    let newPlaying = playWhenReady && !(state == .error || state == .ended || state == .none)
+    let newPlaying =
+      playWhenReady && !(state == .error || state == .ended || state == .none || state == .stopped)
     let newBuffering = playWhenReady && (state == .loading || state == .buffering)
 
     if newPlaying != playing || newBuffering != buffering {

package/ios/Player/QueueManager.swift

@@ -1,6 +1,6 @@
 import Foundation
 #if canImport(NitroModules)
-import NitroModules
+  import NitroModules
 #endif
 
 /// Notifies the owner when the track list changes.
@@ -40,13 +40,20 @@ class QueueManager {
   }
 
   /// The shuffle order for randomized playback.
-  private var shuffleOrder = ShuffleOrder()
+  private(set) var shuffleOrder = ShuffleOrder()
 
   /// The repeat mode for the queue. Plain property — no side effects.
   var repeatMode: RepeatMode = .off
 
-  /// Whether shuffle mode is enabled. Plain property — no side effects.
-  var shuffleEnabled: Bool = false
+  /// Whether shuffle mode is enabled.
+  var shuffleEnabled: Bool = false {
+    didSet {
+      // Re-pin on enable: the existing order has the current track wherever it happened to land,
+      // so without this, turning shuffle on near the end of the queue ends it right away.
+      guard shuffleEnabled, shuffleEnabled != oldValue else { return }
+      shuffleOrder.reshuffle(keepingFirst: currentIndex)
+    }
+  }
 
   // MARK: - Computed Properties
 
@@ -101,6 +108,14 @@ class QueueManager {
     return currentIndex == tracks.count - 1
   }
 
+  /// Whether `next()` would move to a distinct track — drives remote/CarPlay
+  /// next-button enablement. Shares `nextIndex` with `next()` so the button
+  /// state and the actual navigation can't diverge (shuffle/repeat-wrap aware).
+  var canNext: Bool { nextIndex != nil }
+
+  /// Whether `previous()` would move to a distinct track. Symmetric to `canNext`.
+  var canPrevious: Bool { previousIndex != nil }
+
   // MARK: - Validation
 
   private func throwIfQueueEmpty() throws {
@@ -113,82 +128,69 @@ class QueueManager {
     index: Int,
     name: String = "index",
     min: Int? = nil,
-    max: Int? = nil
+    max: Int? = nil,
   ) throws {
     guard index >= (min ?? 0), (max ?? tracks.count) > index else {
       throw TrackPlayerError.QueueError.invalidIndex(
         index: index,
-        message: "\(name) must be non-negative and less than \(tracks.count)"
+        message: "\(name) must be non-negative and less than \(tracks.count)",
       )
     }
   }
 
   // MARK: - Navigation (returns QueueNavigationResult)
 
-  /// Step to the next track in the queue.
-  func next() -> QueueNavigationResult {
-    guard currentTrack != nil, !tracks.isEmpty else { return .noChange }
-
-    if tracks.count == 1 {
-      return repeatMode == .queue ? .sameTrackReplay : .noChange
+  /// The index `next()` will move to — a distinct track in playback order, or
+  /// nil when there's nowhere to go (empty/single-track queue, or a real end
+  /// with no wrap). Single source of truth shared by `next()` and `canNext`, so
+  /// the button state and the actual navigation can't disagree. Shuffle wraps
+  /// the order unconditionally (like Media3); sequential wraps only on repeat-all.
+  private var nextIndex: Int? {
+    guard currentTrack != nil, tracks.count > 1 else { return nil }
+    let candidate: Int? = if shuffleEnabled {
+      shuffleOrder.getNextIndex(after: currentIndex) ?? shuffleOrder.firstIndex
+    } else if currentIndex + 1 < tracks.count {
+      currentIndex + 1
+    } else {
+      repeatMode == .queue ? 0 : nil
     }
+    guard let candidate, candidate != currentIndex else { return nil }
+    return candidate
+  }
 
-    var newIndex: Int?
-    if shuffleEnabled {
-      // Use shuffle order for navigation
-      newIndex = shuffleOrder.getNextIndex(after: currentIndex)
-      if newIndex == nil {
-        // Wrap to start of shuffle order unconditionally (same order, like Media3)
-        newIndex = shuffleOrder.firstIndex
-      }
+  /// The index `previous()` will move to. Symmetric to `nextIndex`.
+  private var previousIndex: Int? {
+    guard currentTrack != nil, tracks.count > 1 else { return nil }
+    let candidate: Int? = if shuffleEnabled {
+      shuffleOrder.getPreviousIndex(before: currentIndex) ?? shuffleOrder.lastIndex
+    } else if currentIndex - 1 >= 0 {
+      currentIndex - 1
     } else {
-      // Sequential navigation
-      let nextIdx = currentIndex + 1
-      if nextIdx < tracks.count {
-        newIndex = nextIdx
-      } else if repeatMode == .queue {
-        newIndex = 0
-      }
+      repeatMode == .queue ? tracks.count - 1 : nil
     }
+    guard let candidate, candidate != currentIndex else { return nil }
+    return candidate
+  }
 
-    if let newIndex, newIndex != currentIndex {
-      currentIndex = newIndex
+  /// Step to the next track in the queue.
+  func next() -> QueueNavigationResult {
+    guard currentTrack != nil, !tracks.isEmpty else { return .noChange }
+    if let nextIndex {
+      currentIndex = nextIndex
       return .trackChanged
     }
-    return .noChange
+    // No distinct next: single-track + repeat-all replays; otherwise a real end.
+    return tracks.count == 1 && repeatMode == .queue ? .sameTrackReplay : .noChange
   }
 
   /// Step to the previous track in the queue.
   func previous() -> QueueNavigationResult {
     guard currentTrack != nil, !tracks.isEmpty else { return .noChange }
-
-    if tracks.count == 1 {
-      return repeatMode == .queue ? .sameTrackReplay : .noChange
-    }
-
-    var newIndex: Int?
-    if shuffleEnabled {
-      // Use shuffle order for navigation
-      newIndex = shuffleOrder.getPreviousIndex(before: currentIndex)
-      if newIndex == nil {
-        // Wrap to end of shuffle order unconditionally (same order, like Media3)
-        newIndex = shuffleOrder.lastIndex
-      }
-    } else {
-      // Sequential navigation
-      let prevIdx = currentIndex - 1
-      if prevIdx >= 0 {
-        newIndex = prevIdx
-      } else if repeatMode == .queue {
-        newIndex = tracks.count - 1
-      }
-    }
-
-    if let newIndex, newIndex != currentIndex {
-      currentIndex = newIndex
+    if let previousIndex {
+      currentIndex = previousIndex
       return .trackChanged
     }
-    return .noChange
+    return tracks.count == 1 && repeatMode == .queue ? .sameTrackReplay : .noChange
   }
 
   /// Skip to a specific track in the queue.
@@ -211,7 +213,7 @@ class QueueManager {
     currentIndex = clampedIndex
     queueSourcePath = sourcePath
     tracks = newTracks
-    shuffleOrder = ShuffleOrder(length: newTracks.count)
+    shuffleOrder = ShuffleOrder(length: newTracks.count, firstIndex: clampedIndex)
     return true
   }
 
@@ -239,12 +241,12 @@ class QueueManager {
     guard index >= 0, tracks.count >= index else {
       throw TrackPlayerError.QueueError.invalidIndex(
         index: index,
-        message: "Index to insert at has to be non-negative and equal to or smaller than the number of tracks: (\(tracks.count))"
+        message: "Index to insert at has to be non-negative and equal to or smaller than the number of tracks: (\(tracks.count))",
       )
     }
     let wasEmpty = tracks.isEmpty
     // Correct index when tracks were inserted in front of it:
-    if tracks.count > 1, currentIndex >= index {
+    if currentIndex >= 0, currentIndex >= index {
       currentIndex += newTracks.count
     }
     tracks.insert(contentsOf: newTracks, at: index)
@@ -283,11 +285,19 @@ class QueueManager {
     // Mutate a copy and assign once to trigger didSet only once
     var newTracks = tracks
     let track = newTracks.remove(at: fromIndex)
-    newTracks.insert(track, at: min(newTracks.count, toIndex))
+    let insertion = min(newTracks.count, toIndex)
+    newTracks.insert(track, at: insertion)
     tracks = newTracks
-    if fromIndex == currentIndex {
-      currentIndex = toIndex
-      return true
+    shuffleOrder.remove(from: fromIndex, to: fromIndex + 1)
+    shuffleOrder.insert(at: insertion, count: 1)
+    // The pointer follows the playing track; its identity never changes on a
+    // move, so no caller needs to reload (returning true reloads).
+    if currentIndex == fromIndex {
+      currentIndex = insertion
+    } else if fromIndex < currentIndex, insertion >= currentIndex {
+      currentIndex -= 1
+    } else if fromIndex > currentIndex, insertion <= currentIndex {
+      currentIndex += 1
     }
     return false
   }
@@ -299,6 +309,7 @@ class QueueManager {
     guard currentIndex != -1 else { return false }
     currentIndex = -1
     tracks.removeAll()
+    shuffleOrder.clear()
     queueSourcePath = nil
     return true
   }
@@ -315,6 +326,8 @@ class QueueManager {
     guard !tracks.isEmpty else { return }
     let nextIndex = currentIndex + 1
     guard nextIndex < tracks.count else { return }
-    tracks.removeSubrange(nextIndex ..< tracks.count)
+    let end = tracks.count
+    tracks.removeSubrange(nextIndex ..< end)
+    shuffleOrder.remove(from: nextIndex, to: end)
   }
 }