react-native-audio-browser 0.0.1 → 0.1.0-next.1

package/ios/Player/PlaybackProgressUpdateManager.swift

@@ -0,0 +1,68 @@
+import Foundation
+#if canImport(NitroModules)
+import NitroModules
+#endif
+
+/**
+ Manages periodic progress updates during playback.
+ Emits progress events at configurable intervals based on playback state.
+ */
+@MainActor
+class PlaybackProgressUpdateManager {
+  // nonisolated(unsafe) for deinit cleanup — Timer must be invalidated to
+  // break RunLoop retain, and deinit is always nonisolated in Swift 6.
+  nonisolated(unsafe) private var timer: Timer?
+  private var updateInterval: TimeInterval?
+  private let onProgressUpdate: () -> Void
+
+  init(onProgressUpdate: @escaping () -> Void) {
+    self.onProgressUpdate = onProgressUpdate
+  }
+
+  deinit {
+    timer?.invalidate()
+  }
+
+  func setUpdateInterval(_ interval: TimeInterval?) {
+    if interval == updateInterval { return }
+    let wasRunning = timer != nil
+    updateInterval = (interval != nil && interval! > 0) ? interval : nil
+    stop()
+    if updateInterval != nil, wasRunning {
+      start()
+    }
+  }
+
+  func start() {
+    guard timer == nil, let interval = updateInterval else { return }
+    timer = Timer.scheduledTimer(
+      withTimeInterval: interval,
+      repeats: true,
+    ) { [weak self] _ in
+      MainActor.assumeIsolated {
+        self?.onProgressUpdate()
+      }
+    }
+  }
+
+  func stop() {
+    timer?.invalidate()
+    timer = nil
+  }
+
+  func onPlaybackStateChanged(_ state: PlaybackState) {
+    switch state {
+    // Start when playback is set to resume (loading, buffering) or playing
+    case .loading, .buffering, .playing:
+      start()
+
+    // Stop when playback pauses, stops, or errors
+    case .paused, .stopped, .ended, .error:
+      stop()
+
+    // No action for ready, none
+    default:
+      break
+    }
+  }
+}

package/ios/Player/PlaybackStateMachine.swift

@@ -0,0 +1,31 @@
+/// Determines the next playback state for a given event, or `nil` to suppress the transition.
+///
+/// Guards here are **state-related** (e.g., "only from .loading"). Context-related
+/// guards (e.g., `asset != nil`, `nearTrackEnd`, `!playWhenReady`) live at the call
+/// 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 .trackEndedNaturally: return .ended
+  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):
+    guard current != .stopped else { return nil }
+    if !hasAsset { return PlaybackState.none }
+    guard current != .error else { return nil }
+    return .paused
+
+  case .bufferingSufficient:
+    guard current != .playing else { return nil }
+    return .ready
+  }
+}

package/ios/Player/PlayerStatusTypes.swift

@@ -0,0 +1,9 @@
+/// Decouples PlaybackCoordinator from AVFoundation enum types.
+/// TrackPlayer maps from AVPlayer.TimeControlStatus → PlayerTimeControlStatus at the call boundary.
+enum PlayerTimeControlStatus {
+  case paused, waitingToPlayAtSpecifiedRate, playing
+}
+
+enum PlayerItemStatus {
+  case unknown, readyToPlay, failed
+}

package/ios/Player/PlayingStateManager.swift

@@ -0,0 +1,32 @@
+import Foundation
+#if canImport(NitroModules)
+import NitroModules
+#endif
+
+/// Manages the playing state (playing and buffering flags) and notifies when they change.
+@MainActor
+class PlayingStateManager {
+  private(set) var playing: Bool = false
+  private(set) var buffering: Bool = false
+
+  private let onChange: (PlayingState) -> Void
+
+  init(onChange: @escaping (PlayingState) -> Void) {
+    self.onChange = onChange
+  }
+
+  func update(playWhenReady: Bool, state: PlaybackState) {
+    let newPlaying = playWhenReady && !(state == .error || state == .ended || state == .none)
+    let newBuffering = playWhenReady && (state == .loading || state == .buffering)
+
+    if newPlaying != playing || newBuffering != buffering {
+      playing = newPlaying
+      buffering = newBuffering
+      onChange(PlayingState(playing: playing, buffering: buffering))
+    }
+  }
+
+  func toPlayingState() -> PlayingState {
+    PlayingState(playing: playing, buffering: buffering)
+  }
+}

package/ios/Player/QueueManager.swift

@@ -0,0 +1,320 @@
+import Foundation
+#if canImport(NitroModules)
+import NitroModules
+#endif
+
+/// Notifies the owner when the track list changes.
+@MainActor protocol QueueManagerDelegate: AnyObject {
+  func queueDidChangeTracks(_ tracks: [Track])
+}
+
+/// Result of a navigation action (next/previous/skipTo).
+enum QueueNavigationResult {
+  /// A different track was selected as current.
+  case trackChanged
+  /// Single-track queue with repeat-queue — caller decides whether to replay based on playWhenReady.
+  case sameTrackReplay
+  /// Nothing happened (boundary without wrap, or guards failed).
+  case noChange
+}
+
+/// Pure queue logic: tracks, indices, shuffle, repeat.
+/// Has no knowledge of AVPlayer or playback — TrackPlayer owns that.
+@MainActor
+class QueueManager {
+  weak var delegate: QueueManagerDelegate?
+
+  // MARK: - Stored Properties
+
+  /// The index of the current track. `-1` when there is no current track.
+  private(set) var currentIndex: Int = -1
+
+  /// The source path from which the current queue was expanded (e.g., from a contextual URL).
+  private(set) var queueSourcePath: String?
+
+  /// All tracks held by the queue.
+  private(set) var tracks: [Track] = [] {
+    didSet {
+      delegate?.queueDidChangeTracks(tracks)
+    }
+  }
+
+  /// The shuffle order for randomized playback.
+  private 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
+
+  // MARK: - Computed Properties
+
+  var currentTrack: Track? {
+    guard currentIndex >= 0, currentIndex < tracks.count else { return nil }
+    return tracks[currentIndex]
+  }
+
+  /// The upcoming tracks in playback order.
+  /// When shuffle is enabled, returns tracks in shuffled order.
+  var nextTracks: [Track] {
+    guard currentIndex >= 0, currentIndex < tracks.count else { return [] }
+
+    if shuffleEnabled {
+      var result: [Track] = []
+      var index = currentIndex
+      while let nextIndex = shuffleOrder.getNextIndex(after: index) {
+        result.append(tracks[nextIndex])
+        index = nextIndex
+      }
+      return result
+    }
+
+    guard currentIndex < tracks.count - 1 else { return [] }
+    return Array(tracks[currentIndex + 1 ..< tracks.count])
+  }
+
+  /// The previous tracks in playback order.
+  /// When shuffle is enabled, returns tracks in shuffled order.
+  var previousTracks: [Track] {
+    guard currentIndex >= 0, currentIndex < tracks.count else { return [] }
+
+    if shuffleEnabled {
+      var result: [Track] = []
+      var index = currentIndex
+      while let prevIndex = shuffleOrder.getPreviousIndex(before: index) {
+        result.insert(tracks[prevIndex], at: 0)
+        index = prevIndex
+      }
+      return result
+    }
+
+    guard currentIndex > 0 else { return [] }
+    return Array(tracks[0 ..< currentIndex])
+  }
+
+  /// Whether the current track is the last track in playback order.
+  var isLastInPlaybackOrder: Bool {
+    if shuffleEnabled {
+      return shuffleOrder.isLast(currentIndex)
+    }
+    return currentIndex == tracks.count - 1
+  }
+
+  // MARK: - Validation
+
+  private func throwIfQueueEmpty() throws {
+    if tracks.isEmpty {
+      throw TrackPlayerError.QueueError.empty
+    }
+  }
+
+  private func throwIfIndexInvalid(
+    index: Int,
+    name: String = "index",
+    min: 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)"
+      )
+    }
+  }
+
+  // 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
+    }
+
+    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
+      }
+    } else {
+      // Sequential navigation
+      let nextIdx = currentIndex + 1
+      if nextIdx < tracks.count {
+        newIndex = nextIdx
+      } else if repeatMode == .queue {
+        newIndex = 0
+      }
+    }
+
+    if let newIndex, newIndex != currentIndex {
+      currentIndex = newIndex
+      return .trackChanged
+    }
+    return .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
+      return .trackChanged
+    }
+    return .noChange
+  }
+
+  /// Skip to a specific track in the queue.
+  @discardableResult
+  func skipTo(_ index: Int) throws -> QueueNavigationResult {
+    try throwIfQueueEmpty()
+    try throwIfIndexInvalid(index: index)
+    guard index != currentIndex else { return .noChange }
+    currentIndex = index
+    return .trackChanged
+  }
+
+  // MARK: - Mutations (returns Bool: whether current track changed)
+
+  /// Replace the entire queue with new tracks.
+  /// Returns `true` (current track always changes).
+  @discardableResult
+  func setQueue(_ newTracks: [Track], initialIndex: Int = 0, sourcePath: String? = nil) -> Bool {
+    let clampedIndex = max(0, min(initialIndex, newTracks.count - 1))
+    currentIndex = clampedIndex
+    queueSourcePath = sourcePath
+    tracks = newTracks
+    shuffleOrder = ShuffleOrder(length: newTracks.count)
+    return true
+  }
+
+  /// Add tracks to the end of the queue.
+  /// Returns `true` if the queue was empty (a new current track was set).
+  @discardableResult
+  func add(_ newTracks: [Track], initialIndex: Int = 0) -> Bool {
+    guard !newTracks.isEmpty else { return false }
+    let wasEmpty = tracks.isEmpty
+    let insertIndex = tracks.count
+    tracks.append(contentsOf: newTracks)
+    shuffleOrder.insert(at: insertIndex, count: newTracks.count)
+    if wasEmpty {
+      currentIndex = max(0, min(initialIndex, tracks.count - 1))
+      return true
+    }
+    return false
+  }
+
+  /// Add tracks at a specific index in the queue.
+  /// Returns `true` if the queue was empty (a new current track was set).
+  @discardableResult
+  func addAt(_ newTracks: [Track], at index: Int) throws -> Bool {
+    guard !newTracks.isEmpty else { return false }
+    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))"
+      )
+    }
+    let wasEmpty = tracks.isEmpty
+    // Correct index when tracks were inserted in front of it:
+    if tracks.count > 1, currentIndex >= index {
+      currentIndex += newTracks.count
+    }
+    tracks.insert(contentsOf: newTracks, at: index)
+    shuffleOrder.insert(at: index, count: newTracks.count)
+    if wasEmpty {
+      currentIndex = 0
+      return true
+    }
+    return false
+  }
+
+  /// Remove a track from the queue.
+  /// Returns `true` if the current track changed.
+  @discardableResult
+  func remove(_ index: Int) throws -> Bool {
+    try throwIfQueueEmpty()
+    try throwIfIndexInvalid(index: index)
+    tracks.remove(at: index)
+    shuffleOrder.remove(from: index, to: index + 1)
+    if index == currentIndex {
+      currentIndex = tracks.count > 0 ? currentIndex % tracks.count : -1
+      return true
+    } else if index < currentIndex {
+      currentIndex -= 1
+    }
+    return false
+  }
+
+  /// Move a track in the queue from one position to another.
+  /// Returns `true` if the current track changed (fromIndex was currentIndex).
+  @discardableResult
+  func move(fromIndex: Int, toIndex: Int) throws -> Bool {
+    try throwIfQueueEmpty()
+    try throwIfIndexInvalid(index: fromIndex, name: "fromIndex")
+    try throwIfIndexInvalid(index: toIndex, name: "toIndex", max: Int.max)
+    // 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))
+    tracks = newTracks
+    if fromIndex == currentIndex {
+      currentIndex = toIndex
+      return true
+    }
+    return false
+  }
+
+  /// Remove all tracks and reset state.
+  /// Returns `true` if there was a current track to clear.
+  @discardableResult
+  func clear() -> Bool {
+    guard currentIndex != -1 else { return false }
+    currentIndex = -1
+    tracks.removeAll()
+    queueSourcePath = nil
+    return true
+  }
+
+  // MARK: - Other Mutations
+
+  /// Replace the track at a specific index.
+  func replace(_ index: Int, _ track: Track) {
+    tracks[index] = track
+  }
+
+  /// Remove all upcoming tracks (those after currentIndex).
+  func removeUpcomingTracks() {
+    guard !tracks.isEmpty else { return }
+    let nextIndex = currentIndex + 1
+    guard nextIndex < tracks.count else { return }
+    tracks.removeSubrange(nextIndex ..< tracks.count)
+  }
+}

package/ios/Player/RetryManager.swift

@@ -0,0 +1,246 @@
+import Foundation
+import NitroModules
+import os.log
+
+/// Manages retry logic for media load errors with exponential backoff.
+/// Similar to Android's RetryLoadErrorHandlingPolicy.
+///
+/// When a network monitor is provided and the device is offline, the retry will
+/// trigger immediately when connectivity is restored instead of waiting for the
+/// full backoff delay.
+@MainActor
+class RetryManager {
+  private let logger = Logger(subsystem: "com.audiobrowser", category: "RetryManager")
+
+  enum Policy {
+    case disabled
+    case infinite
+    case limited(maxRetries: Int)
+  }
+
+  private static let defaultMaxRetryDurationMs: Double = 120_000 // 2 minutes
+
+  /// Prevents surprising playback resumption after long periods offline.
+  private var maxRetryDuration: TimeInterval = defaultMaxRetryDurationMs / 1000
+
+  private var policy: Policy = .disabled
+  private var attemptCount = 0
+  private var firstRetryTime: Date?
+
+  weak var networkMonitor: NetworkMonitor?
+  private var isWaitingForNetwork = false
+  /// Invalidates in-flight retries when reset() is called (e.g. track change)
+  private var generation: Int = 0
+
+  var shouldRetry: () -> Bool = { true }
+  var onRetry: ((Bool) -> Void)?
+
+  // MARK: - Configuration
+
+  func updatePolicy(from config: Variant_Bool_RetryConfig?) {
+    guard let config else {
+      policy = .disabled
+      maxRetryDuration = Self.defaultMaxRetryDurationMs / 1000
+      logger.debug("Retry policy: disabled")
+      return
+    }
+
+    switch config {
+    case let .first(enabled):
+      policy = enabled ? .infinite : .disabled
+      maxRetryDuration = Self.defaultMaxRetryDurationMs / 1000
+      logger.debug("Retry policy: \(enabled ? "infinite" : "disabled")")
+    case let .second(retryConfig):
+      let maxRetries = Int(retryConfig.maxRetries)
+      policy = .limited(maxRetries: maxRetries)
+      let durationMs = retryConfig.maxRetryDurationMs ?? Self.defaultMaxRetryDurationMs
+      maxRetryDuration = durationMs / 1000
+      logger.debug("Retry policy: limited to \(maxRetries) retries, max duration \(self.maxRetryDuration)s")
+    }
+  }
+
+  // MARK: - Exponential Backoff
+
+  /// Delays: 1s -> 1.5s -> 2.3s -> 3.4s -> 5s (capped)
+  private func calculateDelaySeconds() -> Double {
+    let baseDelay = 1.0
+    let multiplier = 1.5
+    let maxDelay = 5.0
+
+    return min(baseDelay * pow(multiplier, Double(attemptCount)), maxDelay)
+  }
+
+  // MARK: - Error Classification
+
+  func isRetryable(_ error: Error?) -> Bool {
+    guard let error else { return false }
+
+    if let urlError = error as? URLError {
+      switch urlError.code {
+      // Transient network errors - safe to retry
+      case .timedOut,
+           .networkConnectionLost,
+           .notConnectedToInternet,
+           .cannotConnectToHost,
+           .cannotFindHost,
+           .dnsLookupFailed:
+        logger.debug("URLError is retryable: code=\(urlError.code.rawValue)")
+        return true
+      default:
+        logger.debug("URLError not retryable: code=\(urlError.code.rawValue)")
+        return false
+      }
+    }
+
+    // Unknown errors - don't retry
+    let nsError = error as NSError
+    logger.debug("Error not retryable: domain=\(nsError.domain), code=\(nsError.code)")
+    return false
+  }
+
+  // MARK: - Retry Management
+
+  func reset() {
+    attemptCount = 0
+    firstRetryTime = nil
+    isWaitingForNetwork = false
+    generation += 1
+    logger.debug("Retry count reset (generation \(self.generation))")
+  }
+
+  func attemptRetry(startFromCurrentTime: Bool) async -> Bool {
+    if case .disabled = policy {
+      logger.debug("Retry disabled, not retrying")
+      return false
+    }
+
+    guard shouldRetry() else {
+      logger.debug("shouldRetry returned false, not retrying")
+      return false
+    }
+
+    if case let .limited(maxRetries) = policy {
+      if attemptCount >= maxRetries {
+        logger.info("Max retries (\(maxRetries)) exceeded, giving up")
+        return false
+      }
+    }
+
+    if firstRetryTime == nil {
+      firstRetryTime = Date()
+    }
+
+    // Check if we've been retrying too long (prevents surprising resumption after long offline periods)
+    if let startTime = firstRetryTime {
+      let elapsed = Date().timeIntervalSince(startTime)
+      if elapsed >= maxRetryDuration {
+        logger.info("Max retry duration (\(self.maxRetryDuration)s) exceeded after \(elapsed)s, giving up")
+        return false
+      }
+    }
+
+    let delaySeconds = calculateDelaySeconds()
+    let currentGeneration = generation
+    logger.info("Scheduling retry after \(delaySeconds)s")
+
+    // Race between: backoff delay OR network restored (if offline)
+    let waitCancelled = await waitForDelayOrNetworkRestored(delaySeconds: delaySeconds)
+
+    if waitCancelled {
+      logger.debug("Retry wait cancelled")
+      return false
+    }
+
+    // Check if reset() was called while we were waiting
+    guard generation == currentGeneration else {
+      logger.debug("Retry invalidated by reset (generation changed)")
+      return false
+    }
+
+    guard shouldRetry() else {
+      logger.debug("shouldRetry returned false after delay, cancelling retry")
+      return false
+    }
+
+    // Re-check duration — we may have waited a long time for network restoration
+    if let startTime = firstRetryTime {
+      let elapsed = Date().timeIntervalSince(startTime)
+      if elapsed >= maxRetryDuration {
+        logger.info("Max retry duration (\(self.maxRetryDuration)s) exceeded after waiting (\(elapsed)s), giving up")
+        return false
+      }
+    }
+
+    attemptCount += 1
+    logger.info("Executing retry #\(self.attemptCount)")
+    onRetry?(startFromCurrentTime)
+    return true
+  }
+
+  // MARK: - Network-Aware Waiting
+
+  /// Returns true if cancelled, false if ready to retry.
+  private func waitForDelayOrNetworkRestored(delaySeconds: Double) async -> Bool {
+    let isOffline = !(networkMonitor?.isOnline ?? true)
+
+    guard isOffline, let monitor = networkMonitor else {
+      do {
+        let nanoseconds = UInt64(delaySeconds * 1_000_000_000)
+        try await Task.sleep(nanoseconds: nanoseconds)
+        return false
+      } catch {
+        return true // Cancelled
+      }
+    }
+
+    logger.debug("Device is offline, will retry immediately when connectivity is restored")
+
+    return await withTaskGroup(of: Bool.self, returning: Bool.self) { group in
+      group.addTask {
+        do {
+          let nanoseconds = UInt64(delaySeconds * 1_000_000_000)
+          try await Task.sleep(nanoseconds: nanoseconds)
+          return false
+        } catch {
+          return true
+        }
+      }
+
+      group.addTask { [weak self] in
+        await self?.waitForNetworkRestored(monitor: monitor) ?? true
+      }
+
+      let result = await group.next() ?? true
+      group.cancelAll()
+      return result
+    }
+  }
+
+  /// Returns false when network is restored, true if cancelled.
+  @MainActor
+  private func waitForNetworkRestored(monitor: NetworkMonitor) async -> Bool {
+    if monitor.isOnline {
+      return false
+    }
+
+    isWaitingForNetwork = true
+    defer { isWaitingForNetwork = false }
+
+    logger.debug("Device is offline, polling for network restoration")
+
+    while !monitor.isOnline {
+      do {
+        try await Task.sleep(nanoseconds: 500_000_000) // 0.5s poll
+      } catch {
+        return true // Task cancelled
+      }
+    }
+
+    logger.info("Network restored, accelerating retry")
+    return false
+  }
+}
+
+// MARK: - RetryHandling
+
+extension RetryManager: RetryHandling {}