react-native-audio-browser 0.2.0-next.3 → 0.2.0-next.30

package/ios/Option/SessionCategories.swift

@@ -1,122 +1,72 @@
 import AVFoundation
-import Foundation
-import MediaPlayer
 
-enum SessionCategory: String {
-  case playAndRecord, multiRoute, playback, ambient, soloAmbient
-
-  func mapConfigToAVAudioSessionCategory() -> AVAudioSession.Category {
+extension IOSCategory {
+  var avCategory: AVAudioSession.Category {
     switch self {
-    case .playAndRecord:
-      .playAndRecord
-    case .multiRoute:
-      .multiRoute
-    case .playback:
-      .playback
-    case .ambient:
-      .ambient
-    case .soloAmbient:
-      .soloAmbient
+    case .playback: .playback
+    case .playandrecord: .playAndRecord
+    case .multiroute: .multiRoute
+    case .ambient: .ambient
+    case .soloambient: .soloAmbient
+    case .record: .record
     }
   }
 }
 
-enum SessionCategoryPolicy: String {
-  case `default`, longFormAudio, longFormVideo
-
-  func toRouteSharingPolicy() -> AVAudioSession.RouteSharingPolicy {
+extension IOSCategoryMode {
+  var avMode: AVAudioSession.Mode {
     switch self {
-    case .default:
-      .default
-    case .longFormAudio:
-      .longFormAudio
-    case .longFormVideo:
-      .longFormVideo
+    case .default: .default
+    case .gamechat: .gameChat
+    case .measurement: .measurement
+    case .movieplayback: .moviePlayback
+    case .spokenaudio: .spokenAudio
+    case .videochat: .videoChat
+    case .videorecording: .videoRecording
+    case .voicechat: .voiceChat
+    case .voiceprompt: .voicePrompt
     }
   }
 }
 
-enum SessionCategoryMode: String {
-  case `default`, gameChat, measurement, moviePlayback, spokenAudio, videoChat, videoRecording,
-       voiceChat, voicePrompt
-
-  func mapConfigToAVAudioSessionCategoryMode() -> AVAudioSession.Mode {
+extension IOSCategoryPolicy {
+  var avPolicy: AVAudioSession.RouteSharingPolicy {
     switch self {
-    case .default:
-      .default
-    case .gameChat:
-      .gameChat
-    case .measurement:
-      .measurement
-    case .moviePlayback:
-      .moviePlayback
-    case .spokenAudio:
-      .spokenAudio
-    case .videoChat:
-      .videoChat
-    case .videoRecording:
-      .videoRecording
-    case .voiceChat:
-      .voiceChat
-    case .voicePrompt:
-      .voicePrompt
+    case .default: .default
+    case .longformaudio: .longFormAudio
+    case .longformvideo: .longFormVideo
     }
   }
 }
 
-enum SessionCategoryOptions: String {
-  case mixWithOthers, duckOthers, interruptSpokenAudioAndMixWithOthers, allowBluetooth,
-       allowBluetoothA2DP,
-       allowAirPlay,
-       defaultToSpeaker
-
-  func mapConfigToAVAudioSessionCategoryOptions() -> AVAudioSession.CategoryOptions? {
+extension IOSCategoryOptions {
+  var avOptions: AVAudioSession.CategoryOptions {
     switch self {
-    case .mixWithOthers:
-      .mixWithOthers
-    case .duckOthers:
-      .duckOthers
-    case .interruptSpokenAudioAndMixWithOthers:
-      .interruptSpokenAudioAndMixWithOthers
-    case .allowBluetooth:
-      .allowBluetoothHFP
-    case .allowBluetoothA2DP:
-      .allowBluetoothA2DP
-    case .allowAirPlay:
-      .allowAirPlay
-    case .defaultToSpeaker:
-      .defaultToSpeaker
+    case .mixwithothers: .mixWithOthers
+    case .duckothers: .duckOthers
+    case .interruptspokenaudioandmixwithothers: .interruptSpokenAudioAndMixWithOthers
+    case .allowbluetooth: .allowBluetoothHFP
+    case .allowbluetootha2dp: .allowBluetoothA2DP
+    case .allowairplay: .allowAirPlay
+    case .defaulttospeaker: .defaultToSpeaker
     }
   }
 }
 
 extension NativeIOSSetupOptions {
-  /// The resolved `AVAudioSession` category configuration from the iOS setup options. Each field
-  /// falls back to a playback default when it's absent or unrecognised, so a consumer's
-  /// `categoryOptions` (e.g. `allowBluetooth` / `allowAirPlay`), `mode`, and route `policy` are
-  /// actually honoured at setup instead of being dropped.
+  /// The `AVAudioSession` configuration these options ask for; an absent field takes the
+  /// playback default.
   func resolveAudioSessionConfig() -> (
     category: AVAudioSession.Category,
     mode: AVAudioSession.Mode,
     policy: AVAudioSession.RouteSharingPolicy,
-    options: AVAudioSession.CategoryOptions
+    options: AVAudioSession.CategoryOptions,
   ) {
-    let category = self.category
-      .flatMap { SessionCategory(rawValue: $0.stringValue) }?
-      .mapConfigToAVAudioSessionCategory() ?? .playback
-    let mode = self.categoryMode
-      .flatMap { SessionCategoryMode(rawValue: $0.stringValue) }?
-      .mapConfigToAVAudioSessionCategoryMode() ?? .default
-    let policy = self.categoryPolicy
-      .flatMap { SessionCategoryPolicy(rawValue: $0.stringValue) }?
-      .toRouteSharingPolicy() ?? .default
-    let options = (self.categoryOptions ?? [])
-      .reduce(into: AVAudioSession.CategoryOptions()) { acc, option in
-        if let mapped = SessionCategoryOptions(rawValue: option.stringValue)?
-          .mapConfigToAVAudioSessionCategoryOptions() {
-          acc.insert(mapped)
-        }
-      }
-    return (category, mode, policy, options)
+    (
+      category?.avCategory ?? .playback,
+      categoryMode?.avMode ?? .default,
+      categoryPolicy?.avPolicy ?? .default,
+      AVAudioSession.CategoryOptions((categoryOptions ?? []).map(\.avOptions)),
+    )
   }
 }

package/ios/Player/AudioSessionController.swift

@@ -0,0 +1,177 @@
+import AVFoundation
+import NitroModules
+
+/// What `AudioSessionController` tells the player about the audio session.
+@MainActor
+protocol AudioSessionPlayer: AnyObject {
+  var playWhenReady: Bool { get }
+  var willResumeAfterInterruption: Bool { get }
+  func handleInterruptionBegan()
+  func handleInterruptionEnded(shouldResume: Bool)
+  func handleRouteDisconnected()
+  func mediaServicesWereReset()
+}
+
+/// Owns the app's `AVAudioSession`: its category, activation and release, and the interruption,
+/// route-change, media-services-reset and volume observers, installed once at init.
+///
+/// The session is configured at setup but activated only when playback produces output:
+/// activating a non-mixable session interrupts other apps' audio, which must not happen at
+/// launch.
+@MainActor
+final class AudioSessionController {
+  weak var player: AudioSessionPlayer?
+
+  let outputChanged = Emitter<Output>()
+  let volumeChanged = Emitter<Double>()
+
+  /// Nil until `configure`: before setup the category is the host app's, not ours to restore.
+  private var configuration: (
+    category: AVAudioSession.Category,
+    mode: AVAudioSession.Mode,
+    policy: AVAudioSession.RouteSharingPolicy,
+    options: AVAudioSession.CategoryOptions,
+  )?
+
+  private var releaseWork: DispatchWorkItem?
+
+  /// Touched only by `init` and `deinit`.
+  private nonisolated(unsafe) var observers: [NSObjectProtocol] = []
+  private var volumeObservation: NSKeyValueObservation?
+
+  private var session: AVAudioSession {
+    .sharedInstance()
+  }
+
+  init() {
+    let center = NotificationCenter.default
+    observers = [
+      center.addObserver(forName: AVAudioSession.interruptionNotification, object: nil, queue: .main) {
+        [weak self] notification in
+        let info = notification.userInfo
+        let type = info?[AVAudioSessionInterruptionTypeKey] as? UInt
+        let reason = info?[AVAudioSessionInterruptionReasonKey] as? UInt
+        let options = info?[AVAudioSessionInterruptionOptionKey] as? UInt
+        MainActor.assumeIsolated { self?.handleInterruption(type: type, reason: reason, options: options) }
+      },
+      center.addObserver(forName: AVAudioSession.routeChangeNotification, object: nil, queue: .main) {
+        [weak self] notification in
+        let reason = notification.userInfo?[AVAudioSessionRouteChangeReasonKey] as? UInt
+        MainActor.assumeIsolated { self?.handleRouteChange(reason: reason) }
+      },
+      center.addObserver(forName: AVAudioSession.mediaServicesWereResetNotification, object: nil, queue: .main) {
+        [weak self] _ in
+        MainActor.assumeIsolated {
+          // The reset cleared the category and invalidated every player and session handle.
+          self?.applyCategory()
+          self?.player?.mediaServicesWereReset()
+        }
+      },
+    ]
+    volumeObservation = session.observe(\.outputVolume, options: [.new]) { [weak self] _, change in
+      guard let volume = change.newValue else { return }
+      Task { @MainActor in self?.volumeChanged.emit(Double(volume)) }
+    }
+  }
+
+  deinit {
+    for observer in observers {
+      NotificationCenter.default.removeObserver(observer)
+    }
+  }
+
+  /// Sets the session category from the iOS setup options, without activating it.
+  func configure(_ options: NativeIOSSetupOptions?) {
+    configuration = options?.resolveAudioSessionConfig() ?? (.playback, .default, .default, [])
+    applyCategory()
+  }
+
+  /// Activates the session for output and cancels a pending release.
+  func activate() {
+    try? session.setActive(true)
+    cancelRelease()
+  }
+
+  /// Releases the session after 3 s unless playback resumes, so other apps' audio can come back.
+  /// Debounced: iOS dislikes deactivating while audio trails off, and a quick pause → resume
+  /// should not thrash it.
+  func scheduleRelease() {
+    releaseWork?.cancel()
+    let release = DispatchWorkItem { [weak self] in
+      guard let self, player?.playWhenReady == false else { return }
+      releaseWork = nil
+      try? session.setActive(false, options: .notifyOthersOnDeactivation)
+    }
+    releaseWork = release
+    DispatchQueue.main.asyncAfter(deadline: .now() + 3, execute: release)
+  }
+
+  func cancelRelease() {
+    releaseWork?.cancel()
+    releaseWork = nil
+  }
+
+  nonisolated static var volume: Double {
+    Double(AVAudioSession.sharedInstance().outputVolume)
+  }
+
+  nonisolated static var currentOutput: Output? {
+    guard let output = AVAudioSession.sharedInstance().currentRoute.outputs.first else { return nil }
+    let (type, external): (OutputType, Bool) = switch output.portType {
+    case .builtInSpeaker: (.speaker, false)
+    case .builtInReceiver: (.receiver, false)
+    case .airPlay: (.airplay, true)
+    case .bluetoothA2DP, .bluetoothHFP, .bluetoothLE: (.bluetooth, true)
+    case .headphones: (.headphones, true)
+    case .carAudio: (.car, true)
+    case .HDMI: (.hdmi, true)
+    case .usbAudio: (.usb, true)
+    default: (.other, true)
+    }
+    return Output(type: type, name: output.portName, external: external)
+  }
+
+  // MARK: - Private
+
+  private func applyCategory() {
+    guard let configuration else { return }
+    try? session.setCategory(
+      configuration.category, mode: configuration.mode, policy: configuration.policy, options: configuration.options,
+    )
+  }
+
+  private func handleInterruption(type: UInt?, reason: UInt?, options: UInt?) {
+    guard let type = type.flatMap(AVAudioSession.InterruptionType.init(rawValue:)) else { return }
+    switch type {
+    case .began:
+      // iOS 17+ also begins one, never ended, when an output route disappears; the route
+      // change handles that.
+      if #available(iOS 17.0, *),
+         let reason,
+         AVAudioSession.InterruptionReason(rawValue: reason) == .routeDisconnected
+      {
+        return
+      }
+      player?.handleInterruptionBegan()
+    case .ended:
+      let shouldResume = options.map { AVAudioSession.InterruptionOptions(rawValue: $0).contains(.shouldResume) } ?? false
+      // Reactivate only when a resume follows: activating while staying paused would hold a
+      // non-mixable session with nothing to release it.
+      if shouldResume, player?.willResumeAfterInterruption == true {
+        try? session.setActive(true)
+      }
+      player?.handleInterruptionEnded(shouldResume: shouldResume)
+    @unknown default:
+      break
+    }
+  }
+
+  private func handleRouteChange(reason: UInt?) {
+    // The output disappeared (headphones unplugged, a speaker off): pause, as every media app
+    // does, rather than carry on from the built-in speaker.
+    if let reason, AVAudioSession.RouteChangeReason(rawValue: reason) == .oldDeviceUnavailable {
+      player?.handleRouteDisconnected()
+    }
+    if let output = Self.currentOutput { outputChanged.emit(output) }
+  }
+}

package/ios/Player/DeferredSeek.swift

@@ -0,0 +1,70 @@
+import Foundation
+
+/// A seek that arrives while an item loads. AVPlayer ignores `seek(to:)` without a loaded item,
+/// so the target is held until the item is ready, and the ready transition waits until it lands.
+/// Pure state: the caller issues the seek this hands out and reports when it lands.
+struct DeferredSeek {
+  enum State: Equatable {
+    case idle
+    case pending(TimeInterval)
+    case inFlight(TimeInterval)
+  }
+
+  /// What to do once an issued seek lands.
+  enum Landing: Equatable {
+    /// The target is reached: the load may become ready.
+    case done
+    /// A newer target arrived meanwhile: issue it.
+    case reseek(TimeInterval)
+    /// No deferred seek was in flight.
+    case none
+  }
+
+  private(set) var state: State = .idle
+
+  /// Identifies the item a seek was issued against. `reset()` bumps it, so the completion of a
+  /// seek against the previous item can tell it is stale.
+  private(set) var generation = 0
+
+  /// The target, pending or in flight; `seekBy` offsets from it.
+  var target: TimeInterval? {
+    switch state {
+    case let .pending(time), let .inFlight(time): time
+    case .idle: nil
+    }
+  }
+
+  var defersReady: Bool {
+    state != .idle
+  }
+
+  /// Holds `position` as the target, replacing a pending one or one in flight.
+  mutating func capture(_ position: TimeInterval) {
+    state = .pending(position)
+  }
+
+  /// Hands out the pending target to issue, marking it in flight; nil when none is pending.
+  mutating func begin() -> TimeInterval? {
+    guard case let .pending(time) = state else { return nil }
+    state = .inFlight(time)
+    return time
+  }
+
+  mutating func land() -> Landing {
+    switch state {
+    case .inFlight:
+      state = .idle
+      return .done
+    case .pending:
+      guard let time = begin() else { return .none }
+      return .reseek(time)
+    case .idle:
+      return .none
+    }
+  }
+
+  mutating func reset() {
+    state = .idle
+    generation += 1
+  }
+}

package/ios/Player/ErrorStatus.swift

@@ -0,0 +1,27 @@
+#if canImport(NitroModules)
+  import NitroModules
+#endif
+
+/// The player's error: none, one the retry loop is still working on (shown over a non-terminal
+/// state, an Advisory error), or terminal (the `.error` state).
+enum ErrorStatus: Equatable {
+  case none
+  case retrying(TrackPlayerError.PlaybackError)
+  case terminal(TrackPlayerError.PlaybackError)
+
+  var error: TrackPlayerError.PlaybackError? {
+    switch self {
+    case .none: nil
+    case let .retrying(error), let .terminal(error): error
+    }
+  }
+
+  var isRetrying: Bool {
+    if case .retrying = self { true } else { false }
+  }
+
+  /// The JS-facing error, carrying the retrying flag.
+  var nitroError: PlaybackError? {
+    error?.toNitroError(retrying: isRetrying)
+  }
+}

package/ios/Player/MediaLoader.swift

@@ -17,40 +17,60 @@ final class MediaLoader {
   /// consumer-supplied `media.resolve(track)` as the final media layer.
   var mediaUrlResolver: ((String, Track?) async -> MediaResolvedUrl)?
 
-  /// Internal access so TrackPlayer can read it for observer guards.
+  /// Internal access so AVPlayerEngine can read it.
   private(set) var asset: AVURLAsset?
 
   /// Milliseconds; applied to AVPlayerItem's preferredForwardBufferDuration.
   var bufferDuration: Double = 0
 
-  weak var delegate: MediaLoaderDelegate?
+  enum Event {
+    case prepared(AVPlayerItem)
+    /// Loading failed; the retry loop decides whether another attempt could help.
+    case failed(Error)
+    /// The asset loaded but cannot play.
+    case unplayable
+    /// The source is not a URL, so no asset exists.
+    case invalidSource(String)
+    case commonMetadata([AVMetadataItem])
+    case chapterMetadata([AVTimedMetadataGroup])
+    case timedMetadata([AVTimedMetadataGroup])
+  }
+
+  var onEvent: (@MainActor (Event) -> Void)?
 
   /// The in-flight resolve. Readable so tests can await the resolve-then-load
   /// chain instead of sleeping past it; only this type starts and cancels it.
   private(set) var mediaResolverTask: Task<Void, Never>?
   private var metadataLoadTask: Task<Void, Never>?
   private var playableLoadTask: Task<Void, Never>?
-  private var url: URL?
-  private var urlOptions: [String: Any]?
 
   // MARK: - Public API
 
   func resolveAndLoad(src: String, track: Track? = nil) {
     if let resolver = mediaUrlResolver {
       mediaResolverTask?.cancel()
-      mediaResolverTask = Task {
-        self.logger.debug("resolveAndLoad: starting resolution for \(src)")
+      // `[weak self]` like the sibling load tasks below: the resolver is
+      // consumer-supplied and `cancelAll()` cannot force an in-flight `await`
+      // to return, so a strong capture let a resolver that never settles pin
+      // this loader (which also retains the task) indefinitely.
+      // `Logger` is a value type, so capturing it directly keeps the logging
+      // off `self` — and `self` weak, so a consumer resolver that never settles
+      // can't pin the loader (`cancelAll()` can't force an in-flight `await` to
+      // return).
+      let logger = logger
+      mediaResolverTask = Task { [weak self] in
+        logger.debug("resolveAndLoad: starting resolution for \(src)")
 
         guard !Task.isCancelled else {
-          self.logger.debug("resolveAndLoad: cancelled before start")
+          logger.debug("resolveAndLoad: cancelled before start")
           return
         }
 
-        self.logger.debug("resolveAndLoad: calling resolver...")
+        logger.debug("resolveAndLoad: calling resolver...")
         let resolved = await resolver(src, track)
 
-        guard !Task.isCancelled else {
-          self.logger.debug("resolveAndLoad: cancelled after resolver returned")
+        guard !Task.isCancelled, let self else {
+          logger.debug("resolveAndLoad: cancelled after resolver returned")
           return
         }
 
@@ -76,14 +96,8 @@ final class MediaLoader {
     }
   }
 
-  func loadAsset() {
-    guard let url else {
-      // Callers (reload-from-terminal) have already transitioned to .loading;
-      // a silent return would strand that state with no load in flight.
-      delegate?.mediaLoaderDidFailWithError(.invalidSourceUrl("nil"))
-      return
-    }
-    let pendingAsset = AVURLAsset(url: url, options: urlOptions)
+  private func loadAsset(url: URL, options: [String: Any]?) {
+    let pendingAsset = AVURLAsset(url: url, options: options)
     asset = pendingAsset
 
     // Separate from playable loading to allow playback to start faster
@@ -96,33 +110,35 @@ final class MediaLoader {
         .availableMetadataFormats,
       ) else { return }
 
-      guard !Task.isCancelled, pendingAsset == asset else { return }
+      guard isCurrent(pendingAsset) else { return }
 
       if !commonMetadata.isEmpty {
-        delegate?.mediaLoaderDidReceiveCommonMetadata(commonMetadata)
+        onEvent?(.commonMetadata(commonMetadata))
       }
 
       if !chapterLocales.isEmpty {
         for locale in chapterLocales {
-          guard !Task.isCancelled else { return }
+          guard isCurrent(pendingAsset) else { return }
           if let chapters = try? await pendingAsset.loadChapterMetadataGroups(
             withTitleLocale: locale,
             containingItemsWithCommonKeys: [],
           ) {
-            delegate?.mediaLoaderDidReceiveChapterMetadata(chapters)
+            guard isCurrent(pendingAsset) else { return }
+            onEvent?(.chapterMetadata(chapters))
           }
         }
       } else {
         let duration = await (try? pendingAsset.load(.duration)) ?? .zero
         for format in metadataFormats {
-          guard !Task.isCancelled else { return }
+          guard isCurrent(pendingAsset) else { return }
           if let metadata = try? await pendingAsset.loadMetadata(for: format) {
+            guard isCurrent(pendingAsset) else { return }
             let timeRange = CMTimeRange(
               start: CMTime(seconds: 0, preferredTimescale: 1000),
               end: duration,
             )
             let group = AVTimedMetadataGroup(items: metadata, timeRange: timeRange)
-            delegate?.mediaLoaderDidReceiveTimedMetadata([group])
+            onEvent?(.timedMetadata([group]))
           }
         }
       }
@@ -140,25 +156,38 @@ final class MediaLoader {
           guard pendingAsset == self.asset else { return }
 
           if !isPlayable {
-            self.delegate?.mediaLoaderDidFailWithUnplayableTrack()
+            self.onEvent?(.unplayable)
             return
           }
 
           let avItem = AVPlayerItem(asset: pendingAsset)
           avItem.preferredForwardBufferDuration = self.bufferDuration / 1000.0
-          self.delegate?.mediaLoaderDidPrepareItem(avItem)
+          self.onEvent?(.prepared(avItem))
         }
       } catch {
         guard !Task.isCancelled else { return }
 
         await MainActor.run {
           guard pendingAsset == self.asset else { return }
-          self.delegate?.mediaLoaderDidFailWithRetryableError(error)
+          self.onEvent?(.failed(error))
         }
       }
     }
   }
 
+  /// Whether `candidate` is still the load this loader cares about — checked
+  /// after EVERY await, not just once before a loop.
+  ///
+  /// Cancellation alone is not enough: it only sets a flag, and can't abort a
+  /// load already in flight inside AVFoundation (only `cancelLoading()` does,
+  /// and the track-change path deliberately doesn't call it — the old asset
+  /// still backs the playing item at that point). So a load that lands after
+  /// the track changed would otherwise attribute the old asset's metadata to
+  /// the newly loaded track.
+  private func isCurrent(_ candidate: AVURLAsset) -> Bool {
+    !Task.isCancelled && candidate == asset
+  }
+
   func cancelAll() {
     mediaResolverTask?.cancel()
     mediaResolverTask = nil
@@ -168,8 +197,6 @@ final class MediaLoader {
     playableLoadTask = nil
   }
 
-  /// Preserves `url` and `urlOptions` so that `loadAsset()` can recreate the asset
-  /// (used by `reload()` → `loadAVPlayer()` without a preceding `resolveAndLoad`).
   func clearAsset() {
     guard let currentAsset = asset else { return }
 
@@ -183,7 +210,7 @@ final class MediaLoader {
 
   /// Builds AVURLAsset options, merging any explicit headers with a resolved
   /// User-Agent. An explicit `User-Agent` in `headers` wins (mirrors the artwork
-  /// path in BrowserManager+URLResolution). A nil/empty userAgent contributes
+  /// path in RequestPipeline). A nil/empty userAgent contributes
   /// nothing, so "no UA configured" still falls through to AVPlayer's default.
   nonisolated static func buildAssetOptions(
     headers: [String: String]?,
@@ -201,17 +228,17 @@ final class MediaLoader {
   private func loadWithResolvedUrl(_ resolved: MediaResolvedUrl) {
     guard let mediaUrl = URL(string: resolved.url) else {
       logger.error("Invalid media URL: \(resolved.url)")
-      delegate?.mediaLoaderDidFailWithError(.invalidSourceUrl(resolved.url))
+      onEvent?(.invalidSource(resolved.url))
       return
     }
 
     let isLocalFile = mediaUrl.isFileURL
-    url = isLocalFile ? URL(fileURLWithPath: mediaUrl.path) : mediaUrl
-    urlOptions = Self.buildAssetOptions(headers: resolved.headers, userAgent: resolved.userAgent)
-
     logger.debug("  final playbackUrl: \(mediaUrl.absoluteString)")
     logger.debug("  isLocalFile: \(isLocalFile)")
 
-    loadAsset()
+    loadAsset(
+      url: isLocalFile ? URL(fileURLWithPath: mediaUrl.path) : mediaUrl,
+      options: Self.buildAssetOptions(headers: resolved.headers, userAgent: resolved.userAgent),
+    )
   }
 }