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

package/ios/NowPlayingInfo/NowPlayingInfoController.swift

@@ -0,0 +1,191 @@
+import AVFoundation
+import Foundation
+@preconcurrency import MediaPlayer
+import os.log
+
+// MPRemoteCommandCenter is not Sendable, but we only use it on the main thread
+extension MPRemoteCommandCenter: @retroactive @unchecked Sendable {}
+
+/// Controller for managing Now Playing info.
+///
+/// On iOS 16+, uses `MPNowPlayingSession` with `automaticallyPublishNowPlayingInfo` to let the system
+/// automatically update elapsed time, playback rate, and duration. We still manually set metadata
+/// (title, artist, artwork) which the automatic publishing doesn't handle.
+///
+/// On iOS 15.x, falls back to manual `MPNowPlayingInfoCenter` updates for all properties.
+@MainActor
+class NowPlayingInfoController {
+  private let logger = Logger(subsystem: "com.audiobrowser", category: "NowPlayingInfoController")
+
+  private(set) var infoCenter: NowPlayingInfoCenter
+  private var _info: [String: Any] = [:]
+
+  /// Wrapper for MPNowPlayingSession (iOS 16+) to avoid @available on stored property
+  private var _nowPlayingSession: Any?
+
+  /// The linked AVPlayer (iOS 16+)
+  private weak var _linkedPlayer: AVPlayer?
+
+  /// Whether automatic publishing is currently active (iOS 16+ with linked player)
+  private var isAutomaticPublishingEnabled: Bool = false
+
+  /// The current remote command center - either the session's (iOS 16+) or shared
+  private(set) var remoteCommandCenter: MPRemoteCommandCenter = .shared()
+
+  /// The current Now Playing info dictionary
+  var info: [String: Any] { _info }
+
+  required init() {
+    infoCenter = MPNowPlayingInfoCenter.default()
+  }
+
+  required init(infoCenter: NowPlayingInfoCenter) {
+    self.infoCenter = infoCenter
+  }
+
+  /// Callback invoked when the remote command center changes (iOS 16+ session created/destroyed)
+  var onRemoteCommandCenterChanged: ((MPRemoteCommandCenter) -> Void)?
+
+  /// Links an AVPlayer to enable automatic Now Playing publishing on iOS 16+.
+  /// On older iOS versions, this is a no-op.
+  ///
+  /// When linked:
+  /// - System automatically updates elapsed time, playback rate, and duration
+  /// - Metadata (title, artist, artwork) is set via `AVPlayerItem.nowPlayingInfo`
+  /// - The session's `remoteCommandCenter` must be used for remote commands
+  ///
+  /// - Important: On iOS 16+, this creates an `MPNowPlayingSession` with its own `remoteCommandCenter`.
+  ///   The `onRemoteCommandCenterChanged` callback will be invoked with the new command center.
+  func linkPlayer(_ player: AVPlayer) {
+    if #available(iOS 16.0, *) {
+      logger.info("Linking AVPlayer to MPNowPlayingSession for automatic publishing")
+
+      _linkedPlayer = player
+
+      let session = MPNowPlayingSession(players: [player])
+      _nowPlayingSession = session
+
+      remoteCommandCenter = session.remoteCommandCenter
+
+      session.automaticallyPublishesNowPlayingInfo = true
+
+      session.becomeActiveIfPossible { success in
+        self.logger.info("MPNowPlayingSession becomeActiveIfPossible: \(success)")
+      }
+
+      isAutomaticPublishingEnabled = true
+      onRemoteCommandCenterChanged?(remoteCommandCenter)
+    } else {
+      logger.debug("linkPlayer: iOS 16+ required for automatic publishing, using manual updates")
+    }
+  }
+
+  /// Unlinks the AVPlayer, disabling automatic publishing.
+  func unlinkPlayer() {
+    if #available(iOS 16.0, *) {
+      logger.info("Unlinking AVPlayer from MPNowPlayingSession")
+
+      _linkedPlayer = nil
+
+      if let session = _nowPlayingSession as? MPNowPlayingSession {
+        session.automaticallyPublishesNowPlayingInfo = false
+      }
+      _nowPlayingSession = nil
+      isAutomaticPublishingEnabled = false
+
+      remoteCommandCenter = MPRemoteCommandCenter.shared()
+      onRemoteCommandCenterChanged?(remoteCommandCenter)
+    }
+  }
+
+  /// Keys that are automatically published by MPNowPlayingSession on iOS 16+.
+  /// When automatic publishing is enabled, we skip setting these manually.
+  private static let autoPublishedKeys: Set<String> = [
+    MPNowPlayingInfoPropertyElapsedPlaybackTime,
+    MPMediaItemPropertyPlaybackDuration,
+    MPNowPlayingInfoPropertyPlaybackRate,
+  ]
+
+  /// Returns true if the key is auto-published and automatic publishing is enabled
+  private func shouldSkipKey(_ key: String) -> Bool {
+    isAutomaticPublishingEnabled && Self.autoPublishedKeys.contains(key)
+  }
+
+  /// Sets key-values and immediately updates the Now Playing Info Center.
+  /// When automatic publishing is enabled (iOS 16+), playback-related keys are skipped.
+  func set(keyValues: [NowPlayingInfoKeyValue]) {
+    for kv in keyValues {
+      if !shouldSkipKey(kv.key) {
+        _info[kv.key] = kv.value
+      }
+    }
+    performUpdate()
+  }
+
+  /// Sets key-values without updating the Now Playing Info Center.
+  /// Useful for batching multiple updates - call update() when ready to commit.
+  /// When automatic publishing is enabled (iOS 16+), playback-related keys are skipped.
+  func setWithoutUpdate(keyValues: [NowPlayingInfoKeyValue]) {
+    for kv in keyValues {
+      if !shouldSkipKey(kv.key) {
+        _info[kv.key] = kv.value
+      }
+    }
+  }
+
+  /// Sets a single key-value and immediately updates the Now Playing Info Center.
+  /// When automatic publishing is enabled (iOS 16+), playback-related keys are skipped.
+  func set(keyValue: NowPlayingInfoKeyValue) {
+    if !shouldSkipKey(keyValue.key) {
+      _info[keyValue.key] = keyValue.value
+      performUpdate()
+    }
+  }
+
+  /// Explicitly updates the Now Playing Info Center with the current info.
+  /// Use after calling setWithoutUpdate() to commit batched changes.
+  func update() {
+    performUpdate()
+  }
+
+  /// Pushes the current info to the appropriate Now Playing target.
+  ///
+  /// On iOS 16+ with automatic publishing:
+  /// - Sets metadata on `AVPlayerItem.nowPlayingInfo`
+  /// - Skips elapsed time and duration (system handles these)
+  ///
+  /// On iOS 15.x or without automatic publishing:
+  /// - Sets all info on `MPNowPlayingInfoCenter.default().nowPlayingInfo`
+  private func performUpdate() {
+    if #available(iOS 16.0, *), isAutomaticPublishingEnabled {
+      _linkedPlayer?.currentItem?.nowPlayingInfo = _info
+    } else {
+      infoCenter.nowPlayingInfo = _info
+    }
+  }
+
+  /// Prepares an AVPlayerItem with stored metadata before it becomes current.
+  /// Call this before `replaceCurrentItem(with:)` so the item has metadata from the start.
+  func prepareItem(_ item: AVPlayerItem) {
+    if #available(iOS 16.0, *), isAutomaticPublishingEnabled {
+      item.nowPlayingInfo = _info
+    }
+  }
+
+  /// Clears all Now Playing info
+  func clear() {
+    _info = [:]
+
+    // With automatic publishing, the session handles clearing when the player stops
+    // Without automatic publishing, we need to clear MPNowPlayingInfoCenter manually
+    if !isAutomaticPublishingEnabled {
+      infoCenter.nowPlayingInfo = nil
+    }
+  }
+
+  /// Sets the playback state (required for CarPlay Now Playing to show correct play/pause state)
+  func setPlaybackState(_ state: MPNowPlayingPlaybackState) {
+    logger.debug("setPlaybackState: \(state.rawValue)")
+    infoCenter.playbackState = state
+  }
+}

package/ios/NowPlayingInfo/NowPlayingInfoKeyValue.swift

@@ -0,0 +1,6 @@
+import Foundation
+
+protocol NowPlayingInfoKeyValue {
+  var key: String { get }
+  var value: Any? { get }
+}

package/ios/NowPlayingInfo/NowPlayingInfoProperty.swift

@@ -0,0 +1,220 @@
+import Foundation
+@preconcurrency import MediaPlayer
+
+/**
+ Enum representing MPNowPlayingInfoProperties.
+ Docs for each property is taken from [Apple docs](https://developer.apple.com/documentation/mediaplayer/mpnowplayinginfocenter/additional_metadata_properties).
+ */
+enum NowPlayingInfoProperty: NowPlayingInfoKeyValue {
+  /**
+   The identifier of the collection the now playing item belongs to.
+   The identifier can be an album, artist, playlist, etc.
+   */
+  case collectionIdentifier(String?)
+
+  /**
+   The available language option groups for the now playing item.
+   Value is an array of MPNowPlayingInfoLanguageOptionGroup items. Only one language option in a given group can be played at a time.
+   */
+  case availableLanguageOptions([MPNowPlayingInfoLanguageOptionGroup]?)
+
+  /**
+   The URL pointing to the now playing item's underlying asset.
+   This constant is used by the system UI when video thumbnails or audio waveform visualizations are applicable.
+   */
+  case assetUrl(URL?)
+
+  /**
+   The total number of chapters in the now-playing item.
+   Value is an NSNumber object configured as an NSUInteger.
+   */
+  case chapterCount(UInt64?)
+
+  /**
+   The number corresponding to the chapter currently being played.
+   Value is an NSNumber object configured as an NSUInteger. Chapter numbering uses zero-based indexing. If you want the first chapter in the now-playing item to be displayed as “Chapter 1,” for example, set the chapter number to 0.
+   */
+  case chapterNumber(UInt64?)
+
+  /**
+   The currently active language options for the now playing item.
+   Value is an array of MPNowPlayingInfoLanguageOption items.
+   */
+  case currentLanguageOptions([MPNowPlayingInfoLanguageOption]?)
+
+  /**
+   The default playback rate for the now playing item.
+   Value is an NSNumber object configured as a double. Set this property if your app is playing a media item at a playback rate other than 1.0 as its default rate.
+   */
+  case defaultPlaybackRate(Double?)
+
+  /**
+   The elapsed time of the now playing item, in seconds.
+   Value is an NSNumber object configured as a double. Elapsed time is automatically calculated, by the system, from the previously provided elapsed time and the playback rate. Do not update this property frequently—it is not necessary
+   */
+  case elapsedPlaybackTime(Double?)
+
+  /**
+   The opaque identifier that uniquely identifies the now playing item, even through app relaunches.
+   This is only used to reference the item to the now playing app and can be in any format.
+   */
+  case externalContentIdentifier(Any?)
+
+  /**
+   The opaque identifier that uniquely identifies the profile the now playing item is played from, even through app relaunches.
+   This is only used to reference the profile to the now playing app and can be in any format.
+   */
+  case externalUserProfileIdentifier(Any?)
+
+  /**
+   Denotes whether the now playing item is a live stream.
+   Value is an NSNumber object configured as a boolean. A value of 1.0 indicates the now playing item is a live stream.
+   */
+  case isLiveStream(Bool?)
+
+  /**
+   The media type of the now playing item.
+   Value is an NSNumber object configured as a MPNowPlayingInfoMediaType.
+   */
+  case mediaType(MPNowPlayingInfoMediaType?)
+
+  /**
+   The current progress of the now playing item.
+   Value is an NSNumber object configured as a float. A value of 0.0 indicates the item has not been watched while a value of 1.0 indicates the item has been fully watched. This is a high-level indicator. Use MPNowPlayingInfoPropertyElapsedPlaybackTime for fine-detailed information on how much of the item has been watched.
+   */
+  case playbackProgress(Float?)
+
+  /**
+   The total number of items in the app’s playback queue.
+   Value is an NSNumber object configured as an NSUInteger.
+   */
+  case playbackQueueCount(UInt64?)
+
+  /**
+   The index of the now-playing item in the app’s playback queue.
+   Value is an NSNumber object configured as an NSUInteger. The playback queue uses zero-based indexing. If you want the first item in the queue to be displayed as “item 1 of 10,” for example, set the item’s index to 0.
+   */
+  case playbackQueueIndex(UInt64?)
+
+  /**
+   The playback rate of the now-playing item, with a value of 1.0 indicating the normal playback rate.
+   Value is an NSNumber object configured as a double. The default value is 1.0. A playback rate value of 2.0 means twice the normal playback rate; a piece of media played at this rate would take half as long to play to completion. A value of 0.5 means half the normal playback rate; a piece of media played at this rate would take twice as long to play to completion.
+   */
+  case playbackRate(Double?)
+
+  /**
+   The service provider associated with the now-playing item.
+   Value is a unique NSString that identifies the service provider for the now-playing item. If the now-playing item belongs to a channel or subscription service, this key can be used to coordinate various types of now-playing content from the service provider.
+   */
+  case serviceIdentifier(String?)
+
+  var key: String {
+    switch self {
+    case .collectionIdentifier:
+      MPNowPlayingInfoCollectionIdentifier
+
+    case .availableLanguageOptions:
+      MPNowPlayingInfoPropertyAvailableLanguageOptions
+
+    case .assetUrl:
+      MPNowPlayingInfoPropertyAssetURL
+
+    case .chapterCount:
+      MPNowPlayingInfoPropertyChapterCount
+
+    case .chapterNumber:
+      MPNowPlayingInfoPropertyChapterNumber
+
+    case .currentLanguageOptions:
+      MPNowPlayingInfoPropertyCurrentLanguageOptions
+
+    case .defaultPlaybackRate:
+      MPNowPlayingInfoPropertyDefaultPlaybackRate
+
+    case .elapsedPlaybackTime:
+      MPNowPlayingInfoPropertyElapsedPlaybackTime
+
+    case .externalContentIdentifier:
+      MPNowPlayingInfoPropertyExternalContentIdentifier
+
+    case .externalUserProfileIdentifier:
+      MPNowPlayingInfoPropertyExternalUserProfileIdentifier
+
+    case .isLiveStream:
+      MPNowPlayingInfoPropertyIsLiveStream
+
+    case .mediaType:
+      MPNowPlayingInfoPropertyMediaType
+
+    case .playbackProgress:
+      MPNowPlayingInfoPropertyPlaybackProgress
+
+    case .playbackQueueCount:
+      MPNowPlayingInfoPropertyPlaybackQueueCount
+
+    case .playbackQueueIndex:
+      MPNowPlayingInfoPropertyPlaybackQueueIndex
+
+    case .playbackRate:
+      MPNowPlayingInfoPropertyPlaybackRate
+
+    case .serviceIdentifier:
+      MPNowPlayingInfoPropertyServiceIdentifier
+    }
+  }
+
+  var value: Any? {
+    switch self {
+    case let .collectionIdentifier(identifier):
+      identifier
+
+    case let .availableLanguageOptions(options):
+      options
+
+    case let .assetUrl(url):
+      url
+
+    case let .chapterCount(count):
+      count != nil ? NSNumber(value: count!) : nil
+
+    case let .chapterNumber(number):
+      number != nil ? NSNumber(value: number!) : nil
+
+    case let .currentLanguageOptions(options):
+      options
+
+    case let .defaultPlaybackRate(rate):
+      rate != nil ? NSNumber(floatLiteral: rate!) : nil
+
+    case let .elapsedPlaybackTime(time):
+      time != nil ? NSNumber(floatLiteral: time!) : nil
+
+    case let .externalContentIdentifier(id):
+      id
+
+    case let .externalUserProfileIdentifier(id):
+      id
+
+    case let .isLiveStream(status):
+      status
+
+    case let .mediaType(type):
+      type != nil ? NSNumber(value: type!.rawValue) : nil
+
+    case let .playbackProgress(progress):
+      progress != nil ? NSNumber(value: progress!) : nil
+
+    case let .playbackQueueCount(count):
+      count != nil ? NSNumber(value: count!) : nil
+
+    case let .playbackQueueIndex(index):
+      index != nil ? NSNumber(value: index!) : nil
+
+    case let .playbackRate(rate):
+      rate != nil ? NSNumber(floatLiteral: rate!) : nil
+
+    case let .serviceIdentifier(id):
+      id != nil ? NSString(string: id!) : nil
+    }
+  }
+}

package/ios/Observer/PlayerItemNotificationObserver.swift

@@ -0,0 +1,79 @@
+import AVFoundation
+import Foundation
+
+/**
+ Observes player item notifications and invokes callbacks passed at initialization.
+ */
+@MainActor class PlayerItemNotificationObserver {
+  private let notificationCenter: NotificationCenter = .default
+
+  private(set) weak var observingAVItem: AVPlayerItem?
+  private(set) var isObserving: Bool = false
+
+  private let onDidPlayToEndTime: @MainActor () -> Void
+  private let onFailedToPlayToEndTime: @MainActor (Error?) -> Void
+
+  init(
+    onDidPlayToEndTime: @escaping @MainActor () -> Void,
+    onFailedToPlayToEndTime: @escaping @MainActor (Error?) -> Void,
+  ) {
+    self.onDidPlayToEndTime = onDidPlayToEndTime
+    self.onFailedToPlayToEndTime = onFailedToPlayToEndTime
+  }
+
+  /**
+   Will start observing notifications from an AVPlayerItem.
+
+   - parameter avItem: The AVPlayerItem to observe.
+   - important: Cannot observe more than one item at a time.
+   */
+  func startObserving(item avItem: AVPlayerItem) {
+    stopObservingCurrentItem()
+    observingAVItem = avItem
+    isObserving = true
+    notificationCenter.addObserver(
+      self,
+      selector: #selector(avItemDidPlayToEndTime),
+      name: NSNotification.Name.AVPlayerItemDidPlayToEndTime,
+      object: avItem,
+    )
+    notificationCenter.addObserver(
+      self,
+      selector: #selector(avItemFailedToPlayToEndTime(_:)),
+      name: NSNotification.Name.AVPlayerItemFailedToPlayToEndTime,
+      object: avItem,
+    )
+  }
+
+  /**
+   Stop receiving notifications for the current AVPlayerItem.
+   */
+  func stopObservingCurrentItem() {
+    guard let observingAVItem, isObserving else {
+      return
+    }
+    notificationCenter.removeObserver(
+      self,
+      name: NSNotification.Name.AVPlayerItemDidPlayToEndTime,
+      object: observingAVItem,
+    )
+    notificationCenter.removeObserver(
+      self,
+      name: NSNotification.Name.AVPlayerItemFailedToPlayToEndTime,
+      object: observingAVItem,
+    )
+    self.observingAVItem = nil
+    isObserving = false
+  }
+
+  @objc nonisolated private func avItemDidPlayToEndTime() {
+    Task { @MainActor in self.onDidPlayToEndTime() }
+  }
+
+  @objc nonisolated private func avItemFailedToPlayToEndTime(_ notification: Notification) {
+    // Extract the error from the notification's userInfo
+    // AVPlayerItemFailedToPlayToEndTimeErrorKey contains the actual error
+    let error = notification.userInfo?[AVPlayerItemFailedToPlayToEndTimeErrorKey] as? Error
+    Task { @MainActor in self.onFailedToPlayToEndTime(error) }
+  }
+}

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.
+ */
+@MainActor final class PlayerItemPropertyObserver: NSObject {
+  private var observations: [NSKeyValueObservation] = []
+  private var currentMetadataOutput: AVPlayerItemMetadataOutput?
+
+  private(set) weak var observingAVItem: AVPlayerItem?
+
+  private let onDurationUpdate: @MainActor (Double) -> Void
+  private let onPlaybackLikelyToKeepUpUpdate: @MainActor (Bool) -> Void
+  private let onStatusChange: @MainActor (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 @MainActor (Double) -> Void,
+    onPlaybackLikelyToKeepUpUpdate: @escaping @MainActor (Bool) -> Void,
+    onStatusChange: @escaping @MainActor (AVPlayerItem.Status, Error?) -> Void,
+    onTimedMetadataReceived: @escaping @MainActor ([AVTimedMetadataGroup]) -> Void,
+  ) {
+    self.onDurationUpdate = onDurationUpdate
+    self.onPlaybackLikelyToKeepUpUpdate = onPlaybackLikelyToKeepUpUpdate
+    self.onStatusChange = onStatusChange
+    self.onTimedMetadataReceived = onTimedMetadataReceived
+  }
+
+  /**
+   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
+        let seconds = item.duration.seconds
+        Task { @MainActor in self?.onDurationUpdate(seconds) }
+      },
+      avItem.observe(\.loadedTimeRanges, options: [.new]) { [weak self] item, _ in
+        if let duration = item.loadedTimeRanges.first?.timeRangeValue.duration {
+          let seconds = duration.seconds
+          Task { @MainActor in self?.onDurationUpdate(seconds) }
+        }
+      },
+      avItem.observe(\.isPlaybackLikelyToKeepUp, options: [.new]) { [weak self] item, _ in
+        let isLikely = item.isPlaybackLikelyToKeepUp
+        Task { @MainActor in self?.onPlaybackLikelyToKeepUpUpdate(isLikely) }
+      },
+      avItem.observe(\.status, options: [.new]) { [weak self] item, _ in
+        let status = item.status
+        let error = item.error
+        Task { @MainActor in self?.onStatusChange(status, 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 {
+      observingAVItem.removeAllMetadataOutputs()
+    }
+
+    observingAVItem = nil
+    currentMetadataOutput = nil
+  }
+}
+
+extension PlayerItemPropertyObserver: AVPlayerItemMetadataOutputPushDelegate {
+  nonisolated func metadataOutput(
+    _ output: AVPlayerItemMetadataOutput,
+    didOutputTimedMetadataGroups groups: [AVTimedMetadataGroup],
+    from _: AVPlayerItemTrack?,
+  ) {
+    // Delegate is called on main thread (queue: .main), so we can assume isolation
+    MainActor.assumeIsolated {
+      if output == currentMetadataOutput {
+        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,50 @@
+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.
+ */
+@MainActor final class PlayerStateObserver {
+  private var observations: [NSKeyValueObservation] = []
+
+  weak var avPlayer: AVPlayer? {
+    willSet {
+      stopObserving()
+    }
+  }
+
+  private let onStatusChange: @MainActor (AVPlayer.Status) -> Void
+  private let onTimeControlStatusChange: @MainActor (AVPlayer.TimeControlStatus) -> Void
+
+  init(
+    onStatusChange: @escaping @MainActor (AVPlayer.Status) -> Void,
+    onTimeControlStatusChange: @escaping @MainActor (AVPlayer.TimeControlStatus) -> Void,
+  ) {
+    self.onStatusChange = onStatusChange
+    self.onTimeControlStatusChange = onTimeControlStatusChange
+  }
+
+  /**
+   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
+        let status = player.status
+        Task { @MainActor in self?.onStatusChange(status) }
+      },
+      avPlayer.observe(\.timeControlStatus, options: [.new]) { [weak self] player, _ in
+        let status = player.timeControlStatus
+        Task { @MainActor in self?.onTimeControlStatusChange(status) }
+      },
+    ]
+  }
+
+  func stopObserving() {
+    observations.removeAll()
+  }
+}