@5stones/react-native-audio-browser 0.1.0

package/ios/Player/RetryManager.swift

@@ -0,0 +1,281 @@
+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")
+
+  /// Retry policy configuration
+  enum Policy {
+    case disabled
+    case infinite
+    case limited(maxRetries: Int)
+  }
+
+  /// Default maximum duration to keep retrying before giving up (in milliseconds).
+  private static let defaultMaxRetryDurationMs: Double = 120_000 // 2 minutes
+
+  /// Maximum duration to keep retrying before giving up (in seconds).
+  /// This 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?
+
+  /// Network monitor for accelerating retries when connectivity is restored
+  weak var networkMonitor: NetworkMonitor?
+
+  /// Flag to track if we're waiting for network (for cleanup on reset)
+  private var isWaitingForNetwork = false
+
+  /// Callback to check if we should retry (typically checks playWhenReady)
+  var shouldRetry: () -> Bool = { true }
+
+  /// Callback to trigger reload
+  var onRetry: ((Bool) -> Void)?
+
+  // MARK: - Configuration
+
+  /// Updates the retry policy from the Nitro config type
+  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)
+      // Use configured duration or default
+      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
+
+  /// Calculates delay for current attempt using exponential backoff.
+  /// Delays: 1s -> 1.5s -> 2.3s -> 3.4s -> 5s (capped)
+  /// Returns delay in seconds.
+  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
+
+  /// Classifies whether an error is retryable or permanent.
+  /// Only clearly transient network errors are retried.
+  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
+
+  /// Resets retry count. Call when track changes.
+  func reset() {
+    attemptCount = 0
+    firstRetryTime = nil
+    isWaitingForNetwork = false
+    logger.debug("Retry count reset")
+  }
+
+  /// Attempts a retry if policy allows.
+  /// Returns true if retry was scheduled, false if max retries exceeded or disabled.
+  ///
+  /// If a network monitor is configured and the device is offline, the retry will
+  /// trigger immediately when connectivity is restored instead of waiting for the
+  /// full backoff delay.
+  func attemptRetry(startFromCurrentTime: Bool) async -> Bool {
+    // Check if retry is disabled
+    if case .disabled = policy {
+      logger.debug("Retry disabled, not retrying")
+      return false
+    }
+
+    // Check if we should retry (e.g., playWhenReady is true)
+    guard shouldRetry() else {
+      logger.debug("shouldRetry returned false, not retrying")
+      return false
+    }
+
+    // Check max retries for limited policy
+    if case let .limited(maxRetries) = policy {
+      if attemptCount >= maxRetries {
+        logger.info("Max retries (\(maxRetries)) exceeded, giving up")
+        return false
+      }
+    }
+
+    // Track when we started retrying
+    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
+      }
+    }
+
+    // Schedule retry with exponential backoff
+    let delaySeconds = calculateDelaySeconds()
+    attemptCount += 1
+    logger.info("Scheduling retry #\(self.attemptCount) 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
+    }
+
+    // Double-check we should still retry after the delay
+    guard shouldRetry() else {
+      logger.debug("shouldRetry returned false after delay, cancelling retry")
+      return false
+    }
+
+    // Check duration again after waiting (in case we waited a long time for network)
+    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
+      }
+    }
+
+    // Trigger the retry
+    logger.info("Executing retry #\(self.attemptCount)")
+    onRetry?(startFromCurrentTime)
+    return true
+  }
+
+  // MARK: - Network-Aware Waiting
+
+  /// Waits for either the backoff delay to elapse OR network to be restored (if offline).
+  /// Returns true if cancelled, false if ready to retry.
+  private func waitForDelayOrNetworkRestored(delaySeconds: Double) async -> Bool {
+    let isOffline = !(networkMonitor?.isOnline ?? true)
+
+    // If online or no monitor, just do a simple sleep
+    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")
+
+    // Race between sleep and network restoration
+    return await withTaskGroup(of: Bool.self, returning: Bool.self) { group in
+      // Task 1: Sleep for backoff delay
+      group.addTask {
+        do {
+          let nanoseconds = UInt64(delaySeconds * 1_000_000_000)
+          try await Task.sleep(nanoseconds: nanoseconds)
+          return false // Sleep completed, ready to retry
+        } catch {
+          return true // Sleep cancelled
+        }
+      }
+
+      // Task 2: Wait for network restoration
+      group.addTask { [weak self] in
+        await self?.waitForNetworkRestored(monitor: monitor) ?? true
+      }
+
+      // Return when either completes
+      let result = await group.next() ?? true
+      group.cancelAll()
+      return result
+    }
+  }
+
+  /// Waits until network connectivity is restored.
+  /// Returns false when network is restored, true if cancelled.
+  @MainActor
+  private func waitForNetworkRestored(monitor: NetworkMonitor) async -> Bool {
+    // If already online, return immediately
+    if monitor.isOnline {
+      return false
+    }
+
+    isWaitingForNetwork = true
+
+    // Set up listener for network restoration
+    let previousHandler = monitor.onChanged
+
+    // Use withCheckedContinuation to wait for network
+    let result: Bool = await withCheckedContinuation { continuation in
+      var hasResumed = false
+
+      monitor.onChanged = { [weak self] isOnline in
+        // Always call previous handler to maintain JS callback
+        previousHandler?(isOnline)
+
+        guard !hasResumed else { return }
+
+        if isOnline {
+          hasResumed = true
+          self?.logger.info("Network restored, accelerating retry")
+          // Restore original handler
+          monitor.onChanged = previousHandler
+          continuation.resume(returning: false) // Network restored, ready to retry
+        }
+      }
+    }
+
+    isWaitingForNetwork = false
+    return result
+  }
+}

package/ios/Player/ShuffleOrder.swift

@@ -0,0 +1,191 @@
+import Foundation
+
+/// Manages a shuffled ordering of indices, similar to Media3's ShuffleOrder.
+///
+/// The shuffle order maintains a mapping between logical shuffle positions and actual
+/// track indices. This allows shuffle to be toggled on/off without reordering the queue.
+///
+/// Example with 5 tracks and shuffle order [3, 1, 4, 0, 2]:
+/// - Shuffle position 0 → track index 3
+/// - Shuffle position 1 → track index 1
+/// - Shuffle position 2 → track index 4
+/// - etc.
+struct ShuffleOrder {
+  /// Maps shuffle position → track index
+  private(set) var shuffled: [Int]
+
+  /// Maps track index → shuffle position (inverse of shuffled)
+  private(set) var indexInShuffled: [Int]
+
+  /// The number of items in the shuffle order
+  var count: Int { shuffled.count }
+
+  var isEmpty: Bool { shuffled.isEmpty }
+
+  // MARK: - Initialization
+
+  /// Creates an empty shuffle order
+  init() {
+    shuffled = []
+    indexInShuffled = []
+  }
+
+  /// Creates a shuffle order for the given length using Fisher-Yates algorithm
+  init(length: Int) {
+    // Generate shuffled indices using Fisher-Yates
+    shuffled = Self.createShuffledIndices(length: length)
+
+    // Build reverse mapping
+    indexInShuffled = Self.buildIndexInShuffled(from: shuffled)
+  }
+
+  /// Creates a shuffle order with pre-defined indices
+  init(shuffledIndices: [Int]) {
+    shuffled = shuffledIndices
+    indexInShuffled = Self.buildIndexInShuffled(from: shuffledIndices)
+  }
+
+  // MARK: - Navigation
+
+  /// Returns the first index in the shuffle order, or nil if empty
+  var firstIndex: Int? {
+    shuffled.first
+  }
+
+  /// Returns the last index in the shuffle order, or nil if empty
+  var lastIndex: Int? {
+    shuffled.last
+  }
+
+  /// Returns the next index after the given index in the shuffle order
+  /// - Parameter index: The current track index
+  /// - Returns: The next track index, or nil if at the end
+  func getNextIndex(after index: Int) -> Int? {
+    guard index >= 0, index < indexInShuffled.count else { return nil }
+    let shufflePosition = indexInShuffled[index]
+    let nextPosition = shufflePosition + 1
+    guard nextPosition < shuffled.count else { return nil }
+    return shuffled[nextPosition]
+  }
+
+  /// Returns the previous index before the given index in the shuffle order
+  /// - Parameter index: The current track index
+  /// - Returns: The previous track index, or nil if at the beginning
+  func getPreviousIndex(before index: Int) -> Int? {
+    guard index >= 0, index < indexInShuffled.count else { return nil }
+    let shufflePosition = indexInShuffled[index]
+    let prevPosition = shufflePosition - 1
+    guard prevPosition >= 0 else { return nil }
+    return shuffled[prevPosition]
+  }
+
+  /// Checks if the given index is the last in the shuffle order
+  func isLast(_ index: Int) -> Bool {
+    guard index >= 0, index < indexInShuffled.count else { return false }
+    return indexInShuffled[index] == shuffled.count - 1
+  }
+
+  /// Checks if the given index is the first in the shuffle order
+  func isFirst(_ index: Int) -> Bool {
+    guard index >= 0, index < indexInShuffled.count else { return false }
+    return indexInShuffled[index] == 0
+  }
+
+  // MARK: - Mutation
+
+  /// Inserts items at random positions in the shuffle order
+  mutating func insert(at insertionIndex: Int, count insertionCount: Int) {
+    guard insertionCount > 0 else { return }
+
+    // Adjust existing indices that are >= insertionIndex
+    for i in 0 ..< shuffled.count {
+      if shuffled[i] >= insertionIndex {
+        shuffled[i] += insertionCount
+      }
+    }
+
+    // Insert new indices at random positions
+    for i in 0 ..< insertionCount {
+      let newIndex = insertionIndex + i
+      let insertPosition = Int.random(in: 0 ... shuffled.count)
+      shuffled.insert(newIndex, at: insertPosition)
+    }
+
+    // Rebuild reverse mapping
+    indexInShuffled = Self.buildIndexInShuffled(from: shuffled)
+  }
+
+  /// Removes items in the specified range from the shuffle order
+  mutating func remove(from indexFrom: Int, to indexToExclusive: Int) {
+    let removeCount = indexToExclusive - indexFrom
+    guard removeCount > 0 else { return }
+
+    // Remove indices in the range and adjust remaining indices
+    shuffled = shuffled.compactMap { index -> Int? in
+      if index >= indexFrom, index < indexToExclusive {
+        return nil // Remove this index
+      } else if index >= indexToExclusive {
+        return index - removeCount // Adjust index
+      }
+      return index
+    }
+
+    // Rebuild reverse mapping
+    indexInShuffled = Self.buildIndexInShuffled(from: shuffled)
+  }
+
+  /// Clears the shuffle order
+  mutating func clear() {
+    shuffled = []
+    indexInShuffled = []
+  }
+
+  /// Reshuffles the order, optionally keeping a specific index first or last
+  mutating func reshuffle(keepingFirst: Int? = nil, keepingLast: Int? = nil) {
+    let length = shuffled.count
+    guard length > 0 else { return }
+
+    shuffled = Self.createShuffledIndices(length: length)
+
+    // If we have a keepingFirst index, move it to the front
+    if let first = keepingFirst, first >= 0, first < length {
+      if let pos = shuffled.firstIndex(of: first), pos > 0 {
+        shuffled.remove(at: pos)
+        shuffled.insert(first, at: 0)
+      }
+    }
+
+    // If we have a keepingLast index, move it to the end
+    if let last = keepingLast, last >= 0, last < length {
+      if let pos = shuffled.firstIndex(of: last), pos < shuffled.count - 1 {
+        shuffled.remove(at: pos)
+        shuffled.append(last)
+      }
+    }
+
+    indexInShuffled = Self.buildIndexInShuffled(from: shuffled)
+  }
+
+  // MARK: - Private Helpers
+
+  /// Creates shuffled indices using Fisher-Yates algorithm
+  private static func createShuffledIndices(length: Int) -> [Int] {
+    var indices = Array(0 ..< length)
+    for i in stride(from: length - 1, through: 1, by: -1) {
+      let j = Int.random(in: 0 ... i)
+      indices.swapAt(i, j)
+    }
+    return indices
+  }
+
+  /// Builds the reverse mapping from track index to shuffle position
+  private static func buildIndexInShuffled(from shuffled: [Int]) -> [Int] {
+    var result = [Int](repeating: -1, count: shuffled.count)
+    for (position, index) in shuffled.enumerated() {
+      if index >= 0, index < result.count {
+        result[index] = position
+      }
+    }
+    return result
+  }
+}

package/ios/Player/SleepTimerManager.swift

@@ -0,0 +1,137 @@
+import Foundation
+import NitroModules
+
+/// Type alias for the Nitro SleepTimer variant type
+typealias SleepTimerState = SleepTimer
+
+/// Manages sleep timer functionality for the audio player.
+/// Supports both time-based timers and end-of-track timers.
+class SleepTimerManager {
+  // MARK: - Properties
+
+  private var sleepTimerJob: DispatchWorkItem?
+
+  private func assertMainThread() {
+    assert(Thread.isMainThread, "SleepTimerManager must be accessed from the main thread")
+  }
+
+  /// The time when playback should stop (seconds since epoch), or -1 if inactive
+  private(set) var sleepTimerTime: TimeInterval = -1 {
+    didSet {
+      if sleepTimerTime > -1 {
+        willSleepWhenCurrentItemReachesEnd = false
+      } else {
+        cancelSleepTimerJob()
+      }
+    }
+  }
+
+  /// Whether to stop playback when the current track ends
+  private(set) var willSleepWhenCurrentItemReachesEnd: Bool = false {
+    didSet {
+      if willSleepWhenCurrentItemReachesEnd {
+        sleepTimerTime = -1
+      }
+    }
+  }
+
+  /// Callback invoked when the sleep timer fires
+  var onComplete: (() -> Void)?
+
+  /// Callback invoked when the sleep timer state changes
+  var onChanged: ((SleepTimerState?) -> Void)?
+
+  // MARK: - Public Methods
+
+  /// Clears any active sleep timer.
+  /// - Returns: true if a timer was cleared, false if no timer was active
+  @discardableResult
+  func clear() -> Bool {
+    assertMainThread()
+    let hasSleepTimer = sleepTimerTime > -1 || willSleepWhenCurrentItemReachesEnd
+    if !hasSleepTimer { return false }
+    sleepTimerTime = -1
+    willSleepWhenCurrentItemReachesEnd = false
+    onChanged?(nil)
+    return true
+  }
+
+  /// Gets the current sleep timer state.
+  /// - Returns: The current timer state, or nil if no timer is active
+  func get() -> SleepTimerState? {
+    assertMainThread()
+    let sleepOnEnd = willSleepWhenCurrentItemReachesEnd
+    let hasSleepTimerTime = sleepTimerTime > -1
+
+    if !hasSleepTimerTime, !sleepOnEnd { return nil }
+
+    if hasSleepTimerTime {
+      // Return time in milliseconds since epoch
+      return .second(SleepTimerTime(time: sleepTimerTime * 1000))
+    }
+
+    if sleepOnEnd {
+      return .third(SleepTimerEndOfTrack(sleepWhenPlayedToEnd: true))
+    }
+
+    return nil
+  }
+
+  /// Sets a time-based sleep timer.
+  /// - Parameter seconds: Number of seconds until playback stops
+  func set(seconds: TimeInterval) {
+    assertMainThread()
+    cancelSleepTimerJob()
+    let job = DispatchWorkItem { [weak self] in
+      self?.complete()
+    }
+    sleepTimerJob = job
+    sleepTimerTime = Date().timeIntervalSince1970 + seconds
+    DispatchQueue.main.asyncAfter(deadline: .now() + seconds, execute: job)
+    onChanged?(get())
+  }
+
+  /// Sets the timer to stop playback when the current track ends.
+  func setToEndOfTrack() {
+    assertMainThread()
+    let changed = !willSleepWhenCurrentItemReachesEnd
+    willSleepWhenCurrentItemReachesEnd = true
+    if changed {
+      onChanged?(get())
+    }
+  }
+
+  /// Called when the current track changes. Resets end-of-track timer.
+  func onTrackChanged() {
+    if willSleepWhenCurrentItemReachesEnd {
+      willSleepWhenCurrentItemReachesEnd = false
+      onChanged?(nil)
+    }
+  }
+
+  /// Called when the current track plays to end.
+  /// Triggers completion if end-of-track timer is active.
+  func onTrackPlayedToEnd() {
+    if willSleepWhenCurrentItemReachesEnd {
+      complete()
+    }
+  }
+
+  // MARK: - Private Methods
+
+  private func cancelSleepTimerJob() {
+    sleepTimerJob?.cancel()
+    sleepTimerJob = nil
+  }
+
+  private func complete() {
+    sleepTimerTime = -1
+    willSleepWhenCurrentItemReachesEnd = false
+    onChanged?(nil)
+    onComplete?()
+  }
+
+  deinit {
+    cancelSleepTimerJob()
+  }
+}