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

package/ios/Observer/PlayerItemPropertyObserver.swift

@@ -0,0 +1,110 @@
+@preconcurrency import AVFoundation
+import Foundation
+
+// AVTimedMetadataGroup is not Sendable, but we only use it on the main thread
+// via AVPlayerItemMetadataOutputPushDelegate (queue: .main)
+extension AVTimedMetadataGroup: @retroactive @unchecked Sendable {}
+
+/**
+ Observes player item property changes and invokes callbacks passed at initialization.
+ Uses modern block-based KVO for type-safe observation with automatic cleanup.
+ */
+final class PlayerItemPropertyObserver: NSObject, @unchecked Sendable {
+  private var observations: [NSKeyValueObservation] = []
+  private var currentMetadataOutput: AVPlayerItemMetadataOutput?
+
+  private(set) weak var observingAVItem: AVPlayerItem?
+
+  private let onDurationUpdate: @Sendable (Double) -> Void
+  private let onPlaybackLikelyToKeepUpUpdate: @Sendable (Bool) -> Void
+  private let onStatusChange: @Sendable (AVPlayerItem.Status, Error?) -> Void
+  // Note: AVTimedMetadataGroup is not Sendable, but this callback is always invoked
+  // on the main thread via AVPlayerItemMetadataOutputPushDelegate (queue: .main)
+  private let onTimedMetadataReceived: @MainActor ([AVTimedMetadataGroup]) -> Void
+
+  init(
+    onDurationUpdate: @escaping @Sendable (Double) -> Void,
+    onPlaybackLikelyToKeepUpUpdate: @escaping @Sendable (Bool) -> Void,
+    onStatusChange: @escaping @Sendable (AVPlayerItem.Status, Error?) -> Void,
+    onTimedMetadataReceived: @escaping @MainActor ([AVTimedMetadataGroup]) -> Void,
+  ) {
+    self.onDurationUpdate = onDurationUpdate
+    self.onPlaybackLikelyToKeepUpUpdate = onPlaybackLikelyToKeepUpUpdate
+    self.onStatusChange = onStatusChange
+    self.onTimedMetadataReceived = onTimedMetadataReceived
+  }
+
+  deinit {
+    stopObservingCurrentItem()
+  }
+
+  /**
+   Start observing an AVPlayerItem. Will remove self as observer from old item, if any.
+
+   - parameter avItem: The AVPlayerItem to observe.
+   */
+  func startObserving(item avItem: AVPlayerItem) {
+    stopObservingCurrentItem()
+
+    observingAVItem = avItem
+
+    observations = [
+      avItem.observe(\.duration, options: [.new]) { [weak self] item, _ in
+        self?.onDurationUpdate(item.duration.seconds)
+      },
+      avItem.observe(\.loadedTimeRanges, options: [.new]) { [weak self] item, _ in
+        if let duration = item.loadedTimeRanges.first?.timeRangeValue.duration {
+          self?.onDurationUpdate(duration.seconds)
+        }
+      },
+      avItem.observe(\.isPlaybackLikelyToKeepUp, options: [.new]) { [weak self] item, _ in
+        self?.onPlaybackLikelyToKeepUpUpdate(item.isPlaybackLikelyToKeepUp)
+      },
+      avItem.observe(\.status, options: [.new]) { [weak self] item, _ in
+        self?.onStatusChange(item.status, item.error)
+      },
+    ]
+
+    // Create and add a new metadata output to the AVPlayerItem
+    let metadataOutput = AVPlayerItemMetadataOutput()
+    metadataOutput.setDelegate(self, queue: .main)
+    avItem.add(metadataOutput)
+    currentMetadataOutput = metadataOutput
+  }
+
+  func stopObservingCurrentItem() {
+    observations.removeAll()
+
+    if let observingAVItem {
+      // removeAllMetadataOutputs is MainActor-isolated; this observer is used from main thread
+      MainActor.assumeIsolated {
+        observingAVItem.removeAllMetadataOutputs()
+      }
+    }
+
+    observingAVItem = nil
+    currentMetadataOutput = nil
+  }
+}
+
+extension PlayerItemPropertyObserver: AVPlayerItemMetadataOutputPushDelegate {
+  func metadataOutput(
+    _ output: AVPlayerItemMetadataOutput,
+    didOutputTimedMetadataGroups groups: [AVTimedMetadataGroup],
+    from _: AVPlayerItemTrack?,
+  ) {
+    if output == currentMetadataOutput {
+      // Delegate is called on main thread (queue: .main), so we can assume isolation
+      MainActor.assumeIsolated { onTimedMetadataReceived(groups) }
+    }
+  }
+}
+
+extension AVPlayerItem {
+  @MainActor
+  func removeAllMetadataOutputs() {
+    for output in outputs.filter({ $0 is AVPlayerItemMetadataOutput }) {
+      remove(output)
+    }
+  }
+}

package/ios/Observer/PlayerStateObserver.swift

@@ -0,0 +1,52 @@
+import AVFoundation
+import Foundation
+
+/**
+ Observes player state changes and invokes callbacks passed at initialization.
+ Uses modern block-based KVO for type-safe observation with automatic cleanup.
+ */
+final class PlayerStateObserver: @unchecked Sendable {
+  private var observations: [NSKeyValueObservation] = []
+
+  weak var avPlayer: AVPlayer? {
+    willSet {
+      stopObserving()
+    }
+  }
+
+  private let onStatusChange: @Sendable (AVPlayer.Status) -> Void
+  private let onTimeControlStatusChange: @Sendable (AVPlayer.TimeControlStatus) -> Void
+
+  init(
+    onStatusChange: @escaping @Sendable (AVPlayer.Status) -> Void,
+    onTimeControlStatusChange: @escaping @Sendable (AVPlayer.TimeControlStatus) -> Void,
+  ) {
+    self.onStatusChange = onStatusChange
+    self.onTimeControlStatusChange = onTimeControlStatusChange
+  }
+
+  deinit {
+    stopObserving()
+  }
+
+  /**
+   Start receiving events from this observer.
+   */
+  func startObserving() {
+    guard let avPlayer else { return }
+    stopObserving()
+
+    observations = [
+      avPlayer.observe(\.status, options: [.new, .initial]) { [weak self] player, _ in
+        self?.onStatusChange(player.status)
+      },
+      avPlayer.observe(\.timeControlStatus, options: [.new]) { [weak self] player, _ in
+        self?.onTimeControlStatusChange(player.timeControlStatus)
+      },
+    ]
+  }
+
+  func stopObserving() {
+    observations.removeAll()
+  }
+}

package/ios/Observer/PlayerTimeObserver.swift

@@ -0,0 +1,109 @@
+import AVFoundation
+import Foundation
+
+/**
+ Observes time-based player events and invokes callbacks passed at initialization.
+ */
+class PlayerTimeObserver: @unchecked Sendable {
+  /// The time to use as start boundary time. Cannot be zero.
+  private static let startBoundaryTime: CMTime = .init(value: 1, timescale: 1000)
+
+  var boundaryTimeStartObserverToken: Any?
+  var periodicTimeObserverToken: Any?
+
+  weak var avPlayer: AVPlayer? {
+    willSet {
+      unregisterForBoundaryTimeEvents()
+      unregisterForPeriodicEvents()
+    }
+  }
+
+  /// The frequency to receive periodic time events.
+  /// Setting this to a new value will trigger a re-registering to the periodic events of the
+  /// player.
+  var periodicObserverTimeInterval: CMTime {
+    didSet {
+      if oldValue != periodicObserverTimeInterval {
+        registerForPeriodicTimeEvents()
+      }
+    }
+  }
+
+  private let onAudioDidStart: @Sendable () -> Void
+  private let onSecondElapsed: @Sendable (Double) -> Void
+
+  init(
+    periodicObserverTimeInterval: CMTime,
+    onAudioDidStart: @escaping @Sendable () -> Void,
+    onSecondElapsed: @escaping @Sendable (Double) -> Void,
+  ) {
+    self.periodicObserverTimeInterval = periodicObserverTimeInterval
+    self.onAudioDidStart = onAudioDidStart
+    self.onSecondElapsed = onSecondElapsed
+  }
+
+  deinit {
+    unregisterForPeriodicEvents()
+    unregisterForBoundaryTimeEvents()
+  }
+
+  /**
+   Will register for the AVPlayer BoundaryTimeEvents, to trigger start and complete events.
+   */
+  func registerForBoundaryTimeEvents() {
+    guard let avPlayer else {
+      return
+    }
+    unregisterForBoundaryTimeEvents()
+    boundaryTimeStartObserverToken = avPlayer.addBoundaryTimeObserver(
+      forTimes: [PlayerTimeObserver.startBoundaryTime].map {
+        NSValue(time: $0)
+      },
+      queue: nil,
+      using: { [weak self] in
+        self?.onAudioDidStart()
+      },
+    )
+  }
+
+  /**
+   Unregister from the boundary events of the player.
+   */
+  func unregisterForBoundaryTimeEvents() {
+    guard
+      let avPlayer,
+      let boundaryTimeStartObserverToken
+    else { return }
+    avPlayer.removeTimeObserver(boundaryTimeStartObserverToken)
+    self.boundaryTimeStartObserverToken = nil
+  }
+
+  /**
+   Start observing periodic time events.
+   Will trigger unregisterForPeriodicEvents() first to avoid multiple subscriptions.
+   */
+  func registerForPeriodicTimeEvents() {
+    guard let avPlayer else {
+      return
+    }
+    unregisterForPeriodicEvents()
+    periodicTimeObserverToken = avPlayer.addPeriodicTimeObserver(
+      forInterval: periodicObserverTimeInterval,
+      queue: nil,
+      using: { [weak self] time in
+        self?.onSecondElapsed(time.seconds)
+      },
+    )
+  }
+
+  /**
+   Unregister for periodic events.
+   */
+  func unregisterForPeriodicEvents() {
+    guard let avPlayer, let periodicTimeObserverToken else {
+      return
+    }
+    avPlayer.removeTimeObserver(periodicTimeObserverToken)
+    self.periodicTimeObserverToken = nil
+  }
+}

package/ios/Option/PitchAlgorithms.swift

@@ -0,0 +1,17 @@
+import AVFoundation
+import Foundation
+
+public enum PitchAlgorithm: String {
+  case linear
+  case music
+  case voice
+
+  /// The corresponding AVAudioTimePitchAlgorithm for use with AVPlayer
+  public var avAlgorithm: AVAudioTimePitchAlgorithm {
+    switch self {
+    case .linear: .varispeed
+    case .music: .spectral
+    case .voice: .timeDomain
+    }
+  }
+}

package/ios/Option/SessionCategories.swift

@@ -0,0 +1,100 @@
+import AVFoundation
+import Foundation
+import MediaPlayer
+
+enum SessionCategory: String {
+  case playAndRecord, multiRoute, playback, ambient, soloAmbient
+
+  func mapConfigToAVAudioSessionCategory() -> AVAudioSession.Category {
+    switch self {
+    case .playAndRecord:
+      .playAndRecord
+    case .multiRoute:
+      .multiRoute
+    case .playback:
+      .playback
+    case .ambient:
+      .ambient
+    case .soloAmbient:
+      .soloAmbient
+    }
+  }
+}
+
+enum SessionCategoryPolicy: String {
+  case `default`, longFormAudio, longFormVideo
+
+  func toRouteSharingPolicy() -> AVAudioSession.RouteSharingPolicy {
+    switch self {
+    case .default:
+      .default
+    case .longFormAudio:
+      .longFormAudio
+    case .longFormVideo:
+      if #available(iOS 13.0, *) {
+        .longFormVideo
+      } else {
+        .longFormAudio
+      }
+    }
+  }
+}
+
+enum SessionCategoryMode: String {
+  case `default`, gameChat, measurement, moviePlayback, spokenAudio, videoChat, videoRecording,
+       voiceChat, voicePrompt
+
+  func mapConfigToAVAudioSessionCategoryMode() -> AVAudioSession.Mode {
+    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:
+      if #available(iOS 12.0, *) {
+        .voicePrompt
+      } else {
+        // Do Nothing
+        .default
+      }
+    }
+  }
+}
+
+enum SessionCategoryOptions: String {
+  case mixWithOthers, duckOthers, interruptSpokenAudioAndMixWithOthers, allowBluetooth,
+       allowBluetoothA2DP,
+       allowAirPlay,
+       defaultToSpeaker
+
+  func mapConfigToAVAudioSessionCategoryOptions() -> 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
+    }
+  }
+}

package/ios/Option/TimeEventFrequency.swift

@@ -0,0 +1,18 @@
+import AVFoundation
+import Foundation
+
+enum TimeEventFrequency {
+  case everySecond
+  case everyHalfSecond
+  case everyQuarterSecond
+  case custom(time: CMTime)
+
+  func getTime() -> CMTime {
+    switch self {
+    case .everySecond: CMTime(value: 1, timescale: 1)
+    case .everyHalfSecond: CMTime(value: 1, timescale: 2)
+    case .everyQuarterSecond: CMTime(value: 1, timescale: 4)
+    case let .custom(time): time
+    }
+  }
+}

package/ios/Player/PlaybackProgressUpdateManager.swift

@@ -0,0 +1,60 @@
+import Foundation
+import NitroModules
+
+/**
+ Manages periodic progress updates during playback.
+ Emits progress events at configurable intervals based on playback state.
+ */
+class PlaybackProgressUpdateManager: @unchecked Sendable {
+  private var timer: Timer?
+  private var updateInterval: TimeInterval?
+  private let onProgressUpdate: () -> Void
+
+  init(onProgressUpdate: @escaping () -> Void) {
+    self.onProgressUpdate = onProgressUpdate
+  }
+
+  deinit {
+    stop()
+  }
+
+  func setUpdateInterval(_ interval: TimeInterval?) {
+    if interval == updateInterval { return }
+    updateInterval = (interval != nil && interval! > 0) ? interval : nil
+    stop()
+    if updateInterval != nil {
+      start()
+    }
+  }
+
+  func start() {
+    guard timer == nil, let interval = updateInterval else { return }
+    timer = Timer.scheduledTimer(
+      withTimeInterval: interval,
+      repeats: true,
+    ) { [weak self] _ in
+      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/PlayingStateManager.swift

@@ -0,0 +1,29 @@
+import Foundation
+import NitroModules
+
+/// Manages the playing state (playing and buffering flags) and notifies when they change.
+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)
+  }
+}