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

package/ios/TrackPlayer.swift

@@ -0,0 +1,1590 @@
+@preconcurrency import AVFoundation
+import Foundation
+import Kingfisher
+import MediaPlayer
+import NitroModules
+import os.log
+
+/// Result of media URL resolution
+struct MediaResolvedUrl {
+  let url: String
+  let headers: [String: String]?
+  let userAgent: String?
+}
+
+@MainActor
+class TrackPlayer {
+  private let logger = Logger(subsystem: "com.audiobrowser", category: "TrackPlayer")
+
+  let nowPlayingInfoController: NowPlayingInfoController
+  let remoteCommandController: RemoteCommandController
+  let sleepTimerManager = SleepTimerManager()
+  private let retryManager = RetryManager()
+  private var pendingRetryTask: Task<Void, Never>?
+  private weak var callbacks: TrackPlayerCallbacks?
+  private var lastIndex: Int = -1
+  private var lastTrack: Track?
+
+  /// Retry configuration for load errors (network failures, timeouts, etc.)
+  var retryConfig: Variant_Bool_RetryConfig? {
+    didSet {
+      retryManager.updatePolicy(from: retryConfig)
+    }
+  }
+
+  /// Network monitor for accelerating retries when connectivity is restored.
+  /// When set, retries will trigger immediately when network comes back online
+  /// instead of waiting for the full exponential backoff delay.
+  weak var networkMonitor: NetworkMonitor? {
+    didSet {
+      retryManager.networkMonitor = networkMonitor
+    }
+  }
+
+  /// Callback to resolve media URLs with optional transform
+  var mediaUrlResolver: ((String) async -> MediaResolvedUrl)?
+
+  /// Callback to resolve artwork URLs with size context for Now Playing.
+  /// Returns an ImageSource with potentially size-optimized URL.
+  var artworkUrlResolver: ((Track, ImageContext?) async -> ImageSource?)?
+
+  /// The repeat mode for the queue player.
+  var repeatMode: RepeatMode = .off {
+    didSet {
+      guard oldValue != repeatMode else { return }
+
+      // Sync state with MPRemoteCommandCenter for CarPlay/lock screen button display
+      remoteCommandController.updateRepeatMode(repeatMode)
+
+      callbacks?.playerDidChangeRepeatMode(
+        RepeatModeChangedEvent(repeatMode: repeatMode),
+      )
+    }
+  }
+
+  /// Whether shuffle mode is enabled.
+  /// When enabled, next/previous traverse the shuffle order instead of sequential order.
+  /// Like Media3, the shuffle order is pre-generated when tracks are added to the queue,
+  /// so toggling shuffle just changes how navigation works without reshuffling.
+  var shuffleEnabled: Bool = false {
+    didSet {
+      guard oldValue != shuffleEnabled else { return }
+
+      // Sync state with MPRemoteCommandCenter for CarPlay/lock screen button display
+      remoteCommandController.updateShuffleMode(shuffleEnabled)
+
+      logger.debug("Shuffle \(self.shuffleEnabled ? "enabled" : "disabled"), order: \(self.shuffleOrder.shuffled)")
+      callbacks?.playerDidChangeShuffleEnabled(shuffleEnabled)
+    }
+  }
+
+  /// The shuffle order for randomized playback
+  private var shuffleOrder = ShuffleOrder()
+
+  // MARK: - Queue 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).
+   Used to avoid re-expanding the queue when selecting tracks from the same source.
+   */
+  private(set) var queueSourcePath: String?
+
+  /**
+   All tracks held by the queue.
+   */
+  private(set) var tracks: [Track] = [] {
+    didSet {
+      callbacks?.playerDidChangeQueue(tracks)
+    }
+  }
+
+  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 {
+      // Return tracks in shuffled order after current position
+      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 {
+      // Return tracks in shuffled order before current position
+      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.
+   When shuffle is enabled, this checks the shuffle order; otherwise, queue order.
+   */
+  private var isLastInPlaybackOrder: Bool {
+    if shuffleEnabled {
+      return shuffleOrder.isLast(currentIndex)
+    }
+    return currentIndex == tracks.count - 1
+  }
+
+  // MARK: - AVPlayer Properties (from AVPlayerWrapper)
+
+  /// Represents a seek operation that's pending while a track loads
+  private struct PendingSeek: Sendable {
+    let time: TimeInterval
+    let completion: (@Sendable (Bool) -> Void)?
+
+    func execute(on player: AVPlayer, delegate: TrackPlayer?) {
+      let cmTime = CMTime(seconds: time, preferredTimescale: 1000)
+      let seekTime = time
+      player
+        .seek(to: cmTime, toleranceBefore: CMTime.zero, toleranceAfter: CMTime.zero) { finished in
+          Task { @MainActor in
+            delegate?.handleSeekCompleted(to: Double(seekTime), didFinish: finished)
+          }
+          completion?(finished)
+        }
+    }
+
+    func cancel() {
+      completion?(false)
+    }
+  }
+
+  private var avPlayer = AVPlayer()
+
+  private lazy var playerObserver: PlayerStateObserver = .init(
+    onStatusChange: { [weak self] status in
+      Task { @MainActor in self?.avPlayerStatusDidChange(status) }
+    },
+    onTimeControlStatusChange: { [weak self] status in
+      Task { @MainActor in self?.avPlayerDidChangeTimeControlStatus(status) }
+    },
+  )
+
+  private lazy var playerTimeObserver: PlayerTimeObserver = .init(
+    periodicObserverTimeInterval: CMTime(seconds: 1, preferredTimescale: 1000),
+    onAudioDidStart: { [weak self] in
+      Task { @MainActor in self?.audioDidStart() }
+    },
+    onSecondElapsed: { [weak self] seconds in
+      Task { @MainActor in self?.setNowPlayingCurrentTime(seconds: seconds) }
+    },
+  )
+
+  private lazy var playerItemNotificationObserver: PlayerItemNotificationObserver = .init(
+    onDidPlayToEndTime: { [weak self] in
+      Task { @MainActor in self?.handleTrackDidPlayToEndTime() }
+    },
+    onFailedToPlayToEndTime: { [weak self] error in
+      Task { @MainActor in self?.handleItemFailedToPlayToEndTime(error: error) }
+    },
+  )
+
+  private lazy var playerItemObserver: PlayerItemPropertyObserver = .init(
+    onDurationUpdate: { [weak self] duration in
+      Task { @MainActor in self?.callbacks?.playerDidUpdateDuration(duration) }
+    },
+    onPlaybackLikelyToKeepUpUpdate: { [weak self] isLikely in
+      Task { @MainActor in self?.avItemDidUpdatePlaybackLikelyToKeepUp(isLikely) }
+    },
+    onStatusChange: { [weak self] status, error in
+      Task { @MainActor in self?.avItemStatusDidChange(status, error: error) }
+    },
+    onTimedMetadataReceived: { [weak self] groups in
+      self?.callbacks?.playerDidReceiveTimedMetadata(groups)
+    },
+  )
+
+  private lazy var progressUpdateManager: PlaybackProgressUpdateManager =
+    PlaybackProgressUpdateManager { [weak self] in
+      guard let self, currentIndex >= 0 else { return }
+      let progressEvent = PlaybackProgressUpdatedEvent(
+        track: Double(currentIndex),
+        position: currentTime,
+        duration: duration,
+        buffered: bufferedPosition,
+      )
+      callbacks?.playerDidUpdateProgress(progressEvent)
+    }
+
+  lazy var playingStateManager: PlayingStateManager = PlayingStateManager { [weak self] state in
+    self?.callbacks?.playerDidChangePlayingState(state)
+  }
+
+  private var pendingSeek: PendingSeek?
+  private var metadataLoadTask: Task<Void, Never>?
+  private var playableLoadTask: Task<Void, Never>?
+  private var asset: AVAsset?
+  private var url: URL?
+  private var urlOptions: [String: Any]?
+  private(set) var playbackError: TrackPlayerError.PlaybackError? {
+    didSet {
+      guard oldValue != playbackError else { return }
+
+      // Setting an error should set state to .error
+      if let _ = playbackError, state != .error {
+        state = .error
+      }
+
+      callbacks?.playerDidError(PlaybackErrorEvent(error: playbackError?.toNitroError()))
+    }
+  }
+
+  private(set) var lastPlayerTimeControlStatus: AVPlayer.TimeControlStatus = .paused
+
+  func getPlayback() -> Playback {
+    Playback(state: state, error: playbackError?.toNitroError())
+  }
+
+  func getRepeatMode() -> RepeatMode {
+    repeatMode
+  }
+
+  func setRepeatMode(_ mode: RepeatMode) {
+    repeatMode = mode
+  }
+
+  /**
+   Controls the time pitch algorithm applied to each track loaded into the player.
+   If the loaded `AudioItem` conforms to `TimePitcher`-protocol this will be overriden.
+   */
+  var audioTimePitchAlgorithm: AVAudioTimePitchAlgorithm = .timeDomain
+
+  /**
+   Default remote commands to use for each playing track
+   */
+  var remoteCommands: [RemoteCommand] = [] {
+    didSet {
+      enableRemoteCommands(remoteCommands)
+    }
+  }
+
+  /**
+    Handles the `playWhenReady` setting while executing a given action.
+
+    This method takes an optional `Bool` value and a closure representing an action to execute.
+    If the `Bool` value is not `nil`, `self.playWhenReady` is set accordingly either before or
+    after executing the action.
+
+    - Parameters:
+      - playWhenReady: Optional `Bool` to set `self.playWhenReady`.
+                       - If `true`, `self.playWhenReady` will be set after executing the action.
+                       - If `false`, `self.playWhenReady` will be set before executing the action.
+                       - If `nil`, `self.playWhenReady` will not be changed.
+      - action: A closure representing the action to execute. This closure can throw an error.
+
+    - Throws: This function will propagate any errors thrown by the `action` closure.
+   */
+  func handlePlayWhenReady(_ playWhenReady: Bool?, action: () throws -> Void) rethrows {
+    if playWhenReady == false {
+      self.playWhenReady = false
+    }
+
+    try action()
+
+    if playWhenReady == true {
+      self.playWhenReady = true
+    }
+  }
+
+  // MARK: - AVPlayer State and Computed Properties
+
+  private(set) var state: PlaybackState = .none {
+    didSet {
+      guard oldValue != state else { return }
+
+      // Clear error when transitioning away from error state
+      if oldValue == .error, state != .error {
+        playbackError = nil
+      }
+
+      switch state {
+      case .ready:
+        setTimePitchingAlgorithmForCurrentItem()
+        // When item becomes ready and playWhenReady is true, start playback
+        if playWhenReady {
+          startPlayback()
+        }
+      case .loading:
+        setTimePitchingAlgorithmForCurrentItem()
+      default: break
+      }
+
+      switch state {
+      case .ready, .loading, .playing, .paused:
+        updateNowPlayingPlaybackValues()
+        // Update playback state for CarPlay Now Playing
+        updateNowPlayingPlaybackState()
+      default: break
+      }
+
+      let playback = Playback(state: state, error: playbackError?.toNitroError())
+      callbacks?.playerDidChangePlayback(playback)
+
+      // Emit queue ended event when playback ends on the last track
+      // This matches Android's behavior (TrackPlayer.kt:642-646)
+      if state == .ended, isLastInPlaybackOrder {
+        let event = PlaybackQueueEndedEvent(
+          track: Double(currentIndex),
+          position: currentTime,
+        )
+        callbacks?.playerDidEndQueue(event)
+      }
+
+      progressUpdateManager.onPlaybackStateChanged(state)
+      playingStateManager.update(playWhenReady: playWhenReady, state: state)
+    }
+  }
+
+  var playbackActive: Bool {
+    switch state {
+    case .none, .stopped, .ended, .error:
+      false
+    default: true
+    }
+  }
+
+  var reasonForWaitingToPlay: AVPlayer.WaitingReason? {
+    avPlayer.reasonForWaitingToPlay
+  }
+
+  // MARK: - Getters from AVPlayerWrapper
+
+  /**
+   The elapsed playback time of the current track.
+   */
+  var currentTime: Double {
+    let seconds = avPlayer.currentTime().seconds
+    return seconds.isNaN ? 0 : seconds
+  }
+
+  /**
+   The duration of the current track.
+   */
+  var duration: Double {
+    guard let item = avPlayer.currentItem else { return 0.0 }
+
+    if !item.asset.duration.seconds.isNaN {
+      return item.asset.duration.seconds
+    }
+    if !item.duration.seconds.isNaN {
+      return item.duration.seconds
+    }
+    if let seekable = item.seekableTimeRanges.last?.timeRangeValue.duration.seconds,
+       !seekable.isNaN
+    {
+      return seekable
+    }
+    return 0.0
+  }
+
+  /**
+   The bufferedPosition of the active track
+   */
+  var bufferedPosition: Double {
+    avPlayer.currentItem?.loadedTimeRanges.last?.timeRangeValue.end.seconds ?? 0
+  }
+
+  /**
+   The current state of the underlying `TrackPlayer`.
+   */
+  var playerState: PlaybackState {
+    state
+  }
+
+  // MARK: - Setters for AVPlayerWrapper
+
+  /**
+   Whether the player should start playing automatically when the track is ready.
+   */
+  var playWhenReady: Bool = false {
+    didSet {
+      if playWhenReady == true, state == .error || state == .stopped {
+        reload(startFromCurrentTime: state == .error)
+      }
+      if playWhenReady {
+        startPlayback()
+      } else {
+        pausePlayback()
+      }
+
+      if oldValue != playWhenReady {
+        callbacks?.playerDidChangePlayWhenReady(playWhenReady)
+        playingStateManager.update(playWhenReady: playWhenReady, state: state)
+      }
+    }
+  }
+
+  /**
+   The amount of milliseconds to be buffered by the player. Default value is 0, this means the AVPlayer will choose an appropriate level of buffering. Setting `bufferDuration` to larger than zero automatically disables `automaticallyWaitsToMinimizeStalling`. Setting it back to zero automatically enables `automaticallyWaitsToMinimizeStalling`.
+
+   [Read more from Apple Documentation](https://developer.apple.com/documentation/avfoundation/avplayeritem/1643630-preferredforwardbufferduration)
+   */
+  var bufferDuration: Double = 0 {
+    didSet {
+      avPlayer.automaticallyWaitsToMinimizeStalling = bufferDuration == 0
+    }
+  }
+
+  /**
+   Indicates whether the player should automatically delay playback in order to minimize stalling. Setting this to true will also set `bufferDuration` back to `0`.
+
+   [Read more from Apple Documentation](https://developer.apple.com/documentation/avfoundation/avplayer/1643482-automaticallywaitstominimizestal)
+   */
+  var automaticallyWaitsToMinimizeStalling: Bool {
+    get { avPlayer.automaticallyWaitsToMinimizeStalling }
+    set {
+      if newValue {
+        bufferDuration = 0
+      }
+      avPlayer.automaticallyWaitsToMinimizeStalling = newValue
+    }
+  }
+
+  var volume: Float {
+    get { avPlayer.volume }
+    set { avPlayer.volume = newValue }
+  }
+
+  var isMuted: Bool {
+    get { avPlayer.isMuted }
+    set { avPlayer.isMuted = newValue }
+  }
+
+  var rate: Float = 1.0 {
+    didSet {
+      avPlayer.rate = rate
+      updateNowPlayingPlaybackValues()
+    }
+  }
+
+  // MARK: - Init
+
+  init(
+    nowPlayingInfoController: NowPlayingInfoController = NowPlayingInfoController(),
+    callbacks: TrackPlayerCallbacks? = nil,
+  ) {
+    self.nowPlayingInfoController = nowPlayingInfoController
+    remoteCommandController = RemoteCommandController(callbacks: callbacks)
+    self.callbacks = callbacks
+
+    // Configure sleep timer
+    sleepTimerManager.onComplete = { [weak self] in
+      self?.pause()
+    }
+
+    // Configure retry manager
+    retryManager.shouldRetry = { [weak self] in
+      self?.playWhenReady ?? false
+    }
+    retryManager.onRetry = { [weak self] startFromCurrentTime in
+      self?.reload(startFromCurrentTime: startFromCurrentTime)
+    }
+
+    // Handle command center changes when MPNowPlayingSession is created/destroyed (iOS 16+)
+    // This callback is guaranteed to be called on the main thread by NowPlayingInfoController
+    nowPlayingInfoController.onRemoteCommandCenterChanged = { [weak self] newCommandCenter in
+      MainActor.assumeIsolated {
+        self?.remoteCommandController.switchCommandCenter(newCommandCenter)
+      }
+    }
+
+    setupAVPlayer()
+  }
+
+  // MARK: - Player Actions
+
+  /**
+   Will replace the current track with a new one and load it into the player.
+
+   - parameter track: The Track to replace the current track.
+   - parameter playWhenReady: Optional, whether to start playback when the track is ready.
+   */
+  func load(_ track: Track, playWhenReady: Bool? = nil) {
+    handlePlayWhenReady(playWhenReady) {
+      if currentIndex == -1 {
+        tracks.append(track)
+        currentIndex = 0
+      } else {
+        setTrack(at: currentIndex, track)
+      }
+      handleCurrentTrackChanged()
+    }
+  }
+
+  /**
+   Toggle playback status.
+   */
+  func togglePlaying() {
+    switch avPlayer.timeControlStatus {
+    case .playing, .waitingToPlayAtSpecifiedRate:
+      pause()
+    case .paused:
+      play()
+    @unknown default:
+      fatalError("Unknown AVPlayer.timeControlStatus")
+    }
+  }
+
+  /**
+   Start playback
+   */
+  func play() {
+    playWhenReady = true
+  }
+
+  /**
+   Pause playback
+   */
+  func pause() {
+    playWhenReady = false
+  }
+
+  /**
+   Toggle playback between play and pause
+   */
+  func togglePlayback() {
+    playWhenReady = !playWhenReady
+  }
+
+  /**
+   Stop playback
+   */
+  func stop() {
+    state = .stopped
+    if currentTrack?.live != true {
+      seekTo(0)
+    }
+    playWhenReady = false
+  }
+
+  /**
+   Reload the current track.
+   */
+  func reload(startFromCurrentTime: Bool) {
+    var time: Double? = nil
+    if startFromCurrentTime {
+      if let currentItem = avPlayer.currentItem {
+        if !currentItem.duration.isIndefinite {
+          time = currentItem.currentTime().seconds
+        }
+      }
+    }
+    loadAVPlayer()
+    if let time {
+      seekTo(time)
+    }
+  }
+
+  /**
+   Seek to a specific time in the track.
+   */
+  func seekTo(_ seconds: TimeInterval) {
+    seekTo(seconds, completion: { _ in })
+  }
+
+  /**
+   Seek to a specific time in the track with a completion handler.
+
+   - parameter seconds: The time to seek to.
+   - parameter completion: Called when the seek operation completes. The Bool parameter indicates whether the seek finished successfully (true) or was interrupted/deferred (false).
+   */
+  func seekTo(_ seconds: TimeInterval, completion: @escaping @Sendable (Bool) -> Void) {
+    // If an track is currently being loaded asynchronously, defer the seek until it's ready.
+    if state == .loading {
+      // Cancel any previous pending seek before creating a new one
+      pendingSeek?.cancel()
+      pendingSeek = PendingSeek(time: seconds, completion: completion)
+    } else if avPlayer.currentItem != nil {
+      let time = CMTime(seconds: seconds, preferredTimescale: 1000)
+      let seekSeconds = seconds
+      avPlayer
+        .seek(to: time, toleranceBefore: CMTime.zero, toleranceAfter: CMTime.zero) { [weak self] finished in
+          Task { @MainActor in
+            self?.handleSeekCompleted(to: Double(seekSeconds), didFinish: finished)
+          }
+          completion(finished)
+        }
+    } else {
+      // No track loaded and not loading - seek fails immediately
+      completion(false)
+    }
+  }
+
+  /**
+   Seek by relative a time offset in the track.
+   */
+  func seekBy(_ offset: TimeInterval) {
+    // Calculate the target time based on current state
+    let targetTime: TimeInterval
+    if state == .loading {
+      // If loading, offset from pending seek (or 0 if no pending seek)
+      targetTime = (pendingSeek?.time ?? 0) + offset
+    } else if let currentItem = avPlayer.currentItem {
+      // If playing, offset from current position
+      targetTime = currentItem.currentTime().seconds + offset
+    } else {
+      // No track and not loading - nothing to seek in
+      return
+    }
+
+    // Delegate to absolute seek
+    seekTo(targetTime)
+  }
+
+  // MARK: - Remote Command Center
+
+  func enableRemoteCommands(_ commands: [RemoteCommand]) {
+    remoteCommandController.enable(commands: commands)
+  }
+
+  // MARK: - NowPlayingInfo
+
+  /**
+   Loads NowPlayingInfo-meta values with the values found in the current track. Use this if a change to the track is made and you want to update the `NowPlayingInfoController`s values.
+
+   Reloads:
+   - Artist
+   - Title
+   - Album title
+   - Album artwork
+   */
+  func loadNowPlayingMetaValues() {
+    guard let track = currentTrack else { return }
+
+    nowPlayingInfoController.set(keyValues: [
+      MediaItemProperty.artist(track.artist),
+      MediaItemProperty.title(track.title),
+      MediaItemProperty.albumTitle(track.album),
+      NowPlayingInfoProperty.playbackRate(Double(rate)),
+      NowPlayingInfoProperty.isLiveStream(track.live),
+    ])
+    loadArtworkForTrack(track)
+  }
+
+  /**
+   Resyncs the playbackvalues of the currently playing track.
+
+   Will resync:
+   - Current time
+   - Duration
+   - Playback rate
+   */
+  func updateNowPlayingPlaybackValues() {
+    logger.debug("updateNowPlayingPlaybackValues: duration=\(self.duration), rate=\(self.rate), currentTime=\(self.currentTime), playWhenReady=\(self.playWhenReady)")
+    nowPlayingInfoController.set(keyValues: [
+      MediaItemProperty.duration(duration),
+      NowPlayingInfoProperty.playbackRate(Double(rate)),
+      NowPlayingInfoProperty.elapsedPlaybackTime(currentTime),
+    ])
+  }
+
+  /// Updates the Now Playing playback state for CarPlay.
+  /// This is separate from playbackRate and required for CarPlay to show correct play/pause button.
+  private func updateNowPlayingPlaybackState() {
+    let state: MPNowPlayingPlaybackState = playWhenReady ? .playing : .paused
+    logger.debug("updateNowPlayingPlaybackState: \(state.rawValue) (playWhenReady=\(self.playWhenReady))")
+    nowPlayingInfoController.setPlaybackState(state)
+  }
+
+  func clear() {
+    clearTracks()
+    unloadAVPlayer()
+    nowPlayingInfoController.unlinkPlayer()
+    nowPlayingInfoController.clear()
+  }
+
+  // MARK: - Private
+
+  private func setNowPlayingCurrentTime(seconds: Double) {
+    nowPlayingInfoController.set(
+      keyValue: NowPlayingInfoProperty.elapsedPlaybackTime(seconds),
+    )
+  }
+
+  private func loadArtworkForTrack(_ track: Track) {
+    let artworkUrl = track.artworkSource?.uri ?? track.artwork
+    logger.debug("loadArtworkForTrack: \(track.title), artworkUrl: \(artworkUrl ?? "nil")")
+
+    // Now Playing artwork: use screen width in pixels, capped at 1200px
+    let screenScale = UIScreen.main.scale
+    let screenWidth = UIScreen.main.bounds.width * screenScale
+    let artworkSize = min(screenWidth, 1200)
+    let nowPlayingSize = ImageContext(width: artworkSize, height: artworkSize)
+
+    Task {
+      let image: UIImage?
+
+      // Try to resolve artwork URL with size context for CDN optimization
+      if let resolver = artworkUrlResolver,
+         let imageSource = await resolver(track, nowPlayingSize)
+      {
+        logger.debug("loadArtworkForTrack: using resolved URL: \(imageSource.uri)")
+        image = await loadImage(from: imageSource)
+      } else {
+        // Fall back to loading from track's existing artwork URL
+        image = await track.loadArtwork()
+      }
+
+      // Verify we're still on the same track after async load
+      guard currentTrack?.src == track.src else { return }
+
+      if let image {
+        logger.debug("loadArtworkForTrack: loaded image \(image.size.width)x\(image.size.height)")
+        // Note: The requestHandler closure is called from MediaPlayer's background queue,
+        // so we must mark it @Sendable to break @MainActor isolation inheritance.
+        let artwork = MPMediaItemArtwork(boundsSize: image.size) { @Sendable requestedSize in
+          return image
+        }
+        nowPlayingInfoController.set(keyValue: MediaItemProperty.artwork(artwork))
+      } else {
+        logger.debug("loadArtworkForTrack: no image loaded")
+        nowPlayingInfoController.set(keyValue: MediaItemProperty.artwork(nil))
+      }
+    }
+  }
+
+  /// Loads an image from an ImageSource using Kingfisher.
+  private func loadImage(from imageSource: ImageSource) async -> UIImage? {
+    guard let url = URL(string: imageSource.uri) else { return nil }
+
+    if url.isFileURL {
+      return UIImage(contentsOfFile: url.path)
+    }
+
+    // Build Kingfisher options with headers if provided
+    var options: KingfisherOptionsInfo = []
+    if let headers = imageSource.headers, !headers.isEmpty {
+      let modifier = AnyModifier { request in
+        var mutableRequest = request
+        for (key, value) in headers {
+          mutableRequest.setValue(value, forHTTPHeaderField: key)
+        }
+        return mutableRequest
+      }
+      options.append(.requestModifier(modifier))
+    }
+
+    do {
+      let result = try await KingfisherManager.shared.retrieveImage(with: url, options: options)
+      return result.image
+    } catch {
+      logger.error("Failed to load artwork from \(imageSource.uri): \(error.localizedDescription)")
+      return nil
+    }
+  }
+
+  private func setTimePitchingAlgorithmForCurrentItem() {
+    // Use player's default pitch algorithm (per-track pitch control not in Nitro API)
+    avPlayer.currentItem?.audioTimePitchAlgorithm = audioTimePitchAlgorithm
+  }
+
+  // MARK: - AVPlayer Management Methods (from AVPlayerWrapper)
+
+  /// Starts playback at the configured rate
+  private func startPlayback() {
+    avPlayer.play()
+  }
+
+  /// Pauses playback
+  private func pausePlayback() {
+    avPlayer.pause()
+  }
+
+  private func clearCurrentAVItem() {
+    guard let currentAsset = asset else {
+      avPlayer.replaceCurrentItem(with: nil)
+      return
+    }
+
+    stopObservingAVPlayerItem()
+
+    // Don't call currentAsset.cancelLoading() - it blocks the main thread for 500ms+
+    // Instead, cancel on a background queue
+    DispatchQueue.global(qos: .utility).async {
+      currentAsset.cancelLoading()
+    }
+
+    asset = nil
+    pendingSeek?.cancel()
+    pendingSeek = nil
+
+    avPlayer.replaceCurrentItem(with: nil)
+  }
+
+  private func startObservingAVPlayerItem(_ avItem: AVPlayerItem) {
+    playerItemObserver.startObserving(item: avItem)
+    playerItemNotificationObserver.startObserving(item: avItem)
+  }
+
+  private func stopObservingAVPlayerItem() {
+    playerItemObserver.stopObservingCurrentItem()
+    playerItemNotificationObserver.stopObservingCurrentItem()
+  }
+
+  private func recreateAVPlayer() {
+    playbackError = nil
+    playerTimeObserver.unregisterForBoundaryTimeEvents()
+    playerTimeObserver.unregisterForPeriodicEvents()
+    playerObserver.stopObserving()
+    stopObservingAVPlayerItem()
+    clearCurrentAVItem()
+
+    // Unlink old player before creating new one
+    nowPlayingInfoController.unlinkPlayer()
+
+    avPlayer = AVPlayer()
+    setupAVPlayer()
+  }
+
+  private func setupAVPlayer() {
+    // disabled since we're not making use of video playback
+    avPlayer.allowsExternalPlayback = false
+
+    playerObserver.avPlayer = avPlayer
+    playerObserver.startObserving()
+
+    playerTimeObserver.avPlayer = avPlayer
+    playerTimeObserver.registerForBoundaryTimeEvents()
+    playerTimeObserver.registerForPeriodicTimeEvents()
+
+    // Link AVPlayer to NowPlayingInfoController for automatic publishing on iOS 16+
+    nowPlayingInfoController.linkPlayer(avPlayer)
+
+    // Apply initial playback state
+    if playWhenReady {
+      startPlayback()
+    } else {
+      // Ensure defaultRate is set for when playback starts later
+      if #available(iOS 16.0, *) {
+        avPlayer.defaultRate = rate
+      }
+    }
+  }
+
+  func loadAVPlayer() {
+    if state == .error {
+      recreateAVPlayer()
+    } else if let oldAsset = asset {
+      // Prepare for new item: cancel in-flight tasks, stop observing, cancel asset loading
+      metadataLoadTask?.cancel()
+      playableLoadTask?.cancel()
+      stopObservingAVPlayerItem()
+      pausePlayback()
+      DispatchQueue.global(qos: .utility).async {
+        oldAsset.cancelLoading()
+      }
+      asset = nil
+      pendingSeek?.cancel()
+      pendingSeek = nil
+    }
+    if let url {
+      let pendingAsset = AVURLAsset(url: url, options: urlOptions)
+      asset = pendingAsset
+      state = .loading
+
+      // Load metadata asynchronously, separate from playable to allow playback to start faster
+      metadataLoadTask = Task { [weak self] in
+        guard let self else { return }
+
+        guard let (commonMetadata, chapterLocales, metadataFormats) = try? await pendingAsset.load(
+          .commonMetadata,
+          .availableChapterLocales,
+          .availableMetadataFormats,
+        ) else { return }
+
+        guard !Task.isCancelled, pendingAsset == asset else { return }
+
+        if !commonMetadata.isEmpty {
+          callbacks?.playerDidReceiveCommonMetadata(commonMetadata)
+        }
+
+        if !chapterLocales.isEmpty {
+          for locale in chapterLocales {
+            guard !Task.isCancelled else { return }
+            if let chapters = try? await pendingAsset.loadChapterMetadataGroups(
+              withTitleLocale: locale,
+              containingItemsWithCommonKeys: [],
+            ) {
+              callbacks?.playerDidReceiveChapterMetadata(chapters)
+            }
+          }
+        } else {
+          let duration = await (try? pendingAsset.load(.duration)) ?? .zero
+          for format in metadataFormats {
+            guard !Task.isCancelled else { return }
+            if let metadata = try? await pendingAsset.loadMetadata(for: format) {
+              let timeRange = CMTimeRange(
+                start: CMTime(seconds: 0, preferredTimescale: 1000),
+                end: duration,
+              )
+              let group = AVTimedMetadataGroup(items: metadata, timeRange: timeRange)
+              callbacks?.playerDidReceiveTimedMetadata([group])
+            }
+          }
+        }
+      }
+
+      // Load playable and start playback when ready
+      playableLoadTask = Task { [weak self] in
+        guard let self else { return }
+
+        do {
+          let isPlayable = try await pendingAsset.load(.isPlayable)
+
+          guard !Task.isCancelled else { return }
+
+          await MainActor.run {
+            guard pendingAsset == self.asset else { return }
+
+            if !isPlayable {
+              self.playbackError = TrackPlayerError.PlaybackError.trackWasUnplayable
+              return
+            }
+
+            let avItem = AVPlayerItem(asset: pendingAsset)
+            avItem.preferredForwardBufferDuration = self.bufferDuration / 1000.0
+            // Set metadata on item before it becomes current, so there's no gap
+            self.nowPlayingInfoController.prepareItem(avItem)
+            self.logger.debug("AVPlayerItem created, calling replaceCurrentItem")
+            self.avPlayer.replaceCurrentItem(with: avItem)
+            self.startObservingAVPlayerItem(avItem)
+            self.logger.debug("AVPlayerItem loaded, currentItem: \(String(describing: self.avPlayer.currentItem)), playWhenReady: \(self.playWhenReady), avPlayer.status=\(self.avPlayer.status.rawValue)")
+            if self.playWhenReady {
+              self.startPlayback()
+            }
+
+            // Execute any pending seek operation
+            if let pending = self.pendingSeek {
+              self.pendingSeek = nil
+              pending.execute(on: self.avPlayer, delegate: self)
+            }
+          }
+        } catch {
+          guard !Task.isCancelled else { return }
+
+          // Try retry before setting error
+          if self.retryManager.isRetryable(error) {
+            let retried = await self.retryManager.attemptRetry(startFromCurrentTime: false)
+            if retried {
+              return // Retry was triggered, don't set error
+            }
+          }
+
+          await MainActor.run {
+            guard pendingAsset == self.asset else { return }
+            self.playbackError = TrackPlayerError.PlaybackError.failedToLoadKeyValue
+          }
+        }
+      }
+    }
+  }
+
+  func unloadAVPlayer() {
+    clearCurrentAVItem()
+    state = .none
+  }
+
+  // MARK: - Internal Event Handlers
+
+  /**
+   Sets the progress update interval.
+   - Parameter interval: The interval in seconds, or nil to disable progress updates
+   */
+  func setProgressUpdateInterval(_ interval: TimeInterval?) {
+    progressUpdateManager.setUpdateInterval(interval)
+  }
+
+  private func handleSeekCompleted(to seconds: Double, didFinish: Bool) {
+    setNowPlayingCurrentTime(seconds: seconds)
+    callbacks?.playerDidCompleteSeek(position: seconds, didFinish: didFinish)
+  }
+
+  func handleTrackDidPlayToEndTime() {
+    // Check if sleep timer should trigger on track end
+    sleepTimerManager.onTrackPlayedToEnd()
+
+    if repeatMode == .track {
+      replay()
+    } else if repeatMode == .queue || !isLastInPlaybackOrder {
+      next()
+    } else {
+      state = .ended
+    }
+  }
+
+  // MARK: - Observer Callbacks
+
+  func avPlayerDidChangeTimeControlStatus(_ status: AVPlayer.TimeControlStatus) {
+    switch status {
+    case .paused:
+      let currentState = state
+      let currentTime = currentTime
+      let duration = duration
+      // Ignore pauses when near track end - let handleTrackDidPlayToEndTime handle track
+      // completion
+      let nearTrackEnd = currentTime >= duration - 0.5 && duration > 0
+
+      // Completely ignore pause events when near track end to avoid race with
+      // handleTrackDidPlayToEndTime
+      if nearTrackEnd {
+        // Ignore - track completion will be handled by handleTrackDidPlayToEndTime
+      } else if asset == nil, currentState != .stopped {
+        state = .none
+      } else if currentState != .error, currentState != .stopped {
+        // Only update state, never modify playWhenReady
+        // playWhenReady represents user intent and should only change via explicit user actions
+        if !playWhenReady {
+          state = .paused
+        }
+        // If playWhenReady is true, this is likely buffering/seeking - don't change state
+      }
+    case .waitingToPlayAtSpecifiedRate:
+      if asset != nil {
+        state = .buffering
+      }
+    case .playing:
+      state = .playing
+    @unknown default:
+      break
+    }
+  }
+
+  func avPlayerStatusDidChange(_ status: AVPlayer.Status) {
+    if status == .failed {
+      handlePlaybackFailure(error: avPlayer.currentItem?.error)
+    }
+  }
+
+  /// Handles AVPlayerItem status changes - this catches errors that don't show up in AVPlayer.status
+  func avItemStatusDidChange(_ status: AVPlayerItem.Status, error: Error?) {
+    if status == .failed {
+      let effectiveError = error ?? avPlayer.currentItem?.error
+      handlePlaybackFailure(error: effectiveError)
+    }
+  }
+
+  /// Common handler for playback failures from either AVPlayer or AVPlayerItem
+  private func handlePlaybackFailure(error: Error?) {
+    if let error {
+      let nsError = error as NSError
+      logger.error("Playback failure: domain=\(nsError.domain), code=\(nsError.code), localizedDescription=\(error.localizedDescription)")
+    } else {
+      logger.error("Playback failure with nil error")
+    }
+
+    // Try retry before setting error state
+    if retryManager.isRetryable(error) {
+      pendingRetryTask?.cancel()
+      pendingRetryTask = Task {
+        let retried = await retryManager.attemptRetry(startFromCurrentTime: true)
+        if !retried {
+          // Max retries exceeded or retry cancelled, surface error
+          self.setPlaybackError(from: error)
+        }
+      }
+      return
+    }
+
+    logger.warning("Error not retryable, surfacing playback_failed")
+    setPlaybackError(from: error)
+  }
+
+  /// Sets the playback error from an Error, with appropriate classification
+  private func setPlaybackError(from error: Error?) {
+    let nsError = error as NSError?
+    playbackError = nsError?.code == URLError.notConnectedToInternet.rawValue
+      ? TrackPlayerError.PlaybackError.notConnectedToInternet
+      : TrackPlayerError.PlaybackError.playbackFailed
+  }
+
+  /// Handles AVPlayerItemFailedToPlayToEndTime notification with retry logic
+  private func handleItemFailedToPlayToEndTime(error: Error?) {
+    let effectiveError = error ?? avPlayer.currentItem?.error
+    handlePlaybackFailure(error: effectiveError)
+  }
+
+  func audioDidStart() {
+    state = .playing
+  }
+
+  func avItemDidUpdatePlaybackLikelyToKeepUp(_ playbackLikelyToKeepUp: Bool) {
+    logger.debug("avItemDidUpdatePlaybackLikelyToKeepUp: \(playbackLikelyToKeepUp), state=\(self.state.rawValue)")
+    if playbackLikelyToKeepUp, state != .playing {
+      logger.debug("setting state = .ready")
+      state = .ready
+    }
+  }
+
+  // MARK: - Queue 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: - Queue Methods
+
+  /**
+   Set the track at a specific index.
+
+   - parameter index: The index of the track to set.
+   - parameter track: The track to set.
+   */
+  func setTrack(at index: Int, _ track: Track) {
+    guard index >= 0, index < tracks.count else { return }
+    tracks[index] = track
+  }
+
+  /**
+   Replace the entire queue with new tracks.
+
+   - parameter tracks: The tracks to set as the new queue.
+   - parameter initialIndex: The index to start at. Defaults to 0.
+   - parameter playWhenReady: Optional, whether to start playback when the track is ready.
+   - parameter sourcePath: Optional path from which this queue was expanded (for contextual URL optimization).
+   */
+  func setQueue(_ newTracks: [Track], initialIndex: Int = 0, playWhenReady: Bool? = nil, sourcePath: String? = nil) {
+    guard !newTracks.isEmpty else {
+      clear()
+      return
+    }
+
+    // Replace tracks and index atomically to avoid intermediate nil state
+    let clampedIndex = max(0, min(initialIndex, newTracks.count - 1))
+    tracks = newTracks
+    currentIndex = clampedIndex
+    queueSourcePath = sourcePath
+
+    // Generate new shuffle order for the new queue
+    // Like Media3, this is a fresh randomized order - not reshuffled based on current track
+    shuffleOrder = ShuffleOrder(length: newTracks.count)
+
+    // Handle playWhenReady and load the new track
+    handlePlayWhenReady(playWhenReady) {
+      handleCurrentTrackChanged()
+    }
+  }
+
+  /**
+   Add tracks to the queue.
+
+   - parameter tracks: The tracks to add to the queue.
+   - parameter initialIndex: Optional, the index to start at when queue was empty. Defaults to 0.
+   - parameter playWhenReady: Optional, whether to start playback when the track is ready.
+   */
+  func add(_ tracks: [Track], initialIndex: Int? = nil, playWhenReady: Bool? = nil) {
+    handlePlayWhenReady(playWhenReady) {
+      add(tracks, initialIndex: initialIndex ?? 0)
+    }
+  }
+
+  private func add(_ newTracks: [Track], initialIndex: Int) {
+    guard !newTracks.isEmpty else { return }
+    let wasEmpty = tracks.isEmpty
+    let insertIndex = tracks.count
+    tracks.append(contentsOf: newTracks)
+
+    // Update shuffle order - inserts new items at random positions (like Media3)
+    shuffleOrder.insert(at: insertIndex, count: newTracks.count)
+
+    if wasEmpty {
+      // Use initialIndex, clamped to valid range
+      currentIndex = max(0, min(initialIndex, tracks.count - 1))
+      handleCurrentTrackChanged()
+    }
+  }
+
+  func add(_ tracks: [Track], at index: Int) throws {
+    guard !tracks.isEmpty else { return }
+    guard index >= 0, self.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: (\(self.tracks.count))",
+      )
+    }
+    let wasEmpty = self.tracks.isEmpty
+    // Correct index when tracks were inserted in front of it:
+    if self.tracks.count > 1, currentIndex >= index {
+      currentIndex += tracks.count
+    }
+    self.tracks.insert(contentsOf: tracks, at: index)
+
+    // Update shuffle order - inserts new items at random positions (like Media3)
+    shuffleOrder.insert(at: index, count: tracks.count)
+
+    if wasEmpty {
+      currentIndex = 0
+      handleCurrentTrackChanged()
+    }
+  }
+
+  /**
+   Step to the next track in the queue.
+   */
+  func next() {
+    guard currentTrack != nil, !tracks.isEmpty else { return }
+
+    let wrap = repeatMode == .queue
+
+    if tracks.count == 1 {
+      if wrap, playWhenReady {
+        replay()
+      }
+      return
+    }
+
+    var newIndex: Int?
+    if shuffleEnabled {
+      // Use shuffle order for navigation
+      newIndex = shuffleOrder.getNextIndex(after: currentIndex)
+      if newIndex == nil {
+        // Wrap to start of shuffle order (same order, like Media3)
+        newIndex = shuffleOrder.firstIndex
+      }
+    } else {
+      // Sequential navigation
+      let nextIndex = currentIndex + 1
+      if nextIndex < tracks.count {
+        newIndex = nextIndex
+      } else if wrap {
+        newIndex = 0
+      }
+    }
+
+    if let newIndex, newIndex != currentIndex {
+      currentIndex = newIndex
+      handleCurrentTrackChanged()
+    }
+  }
+
+  /**
+   Step to the previous track in the queue.
+   */
+  func previous() {
+    guard currentTrack != nil, !tracks.isEmpty else { return }
+
+    let wrap = repeatMode == .queue
+
+    if tracks.count == 1 {
+      if wrap, playWhenReady {
+        replay()
+      }
+      return
+    }
+
+    var newIndex: Int?
+    if shuffleEnabled {
+      // Use shuffle order for navigation
+      newIndex = shuffleOrder.getPreviousIndex(before: currentIndex)
+      if newIndex == nil {
+        // Wrap to end of shuffle order (same order, like Media3)
+        newIndex = shuffleOrder.lastIndex
+      }
+    } else {
+      // Sequential navigation
+      let prevIndex = currentIndex - 1
+      if prevIndex >= 0 {
+        newIndex = prevIndex
+      } else if wrap {
+        newIndex = tracks.count - 1
+      }
+    }
+
+    if let newIndex, newIndex != currentIndex {
+      currentIndex = newIndex
+      handleCurrentTrackChanged()
+    }
+  }
+
+  /**
+   Remove a track from the queue.
+
+   - parameter index: The index of the track to remove.
+   - throws: `TrackPlayerError.QueueError`
+   */
+  func remove(_ index: Int) throws {
+    try throwIfQueueEmpty()
+    try throwIfIndexInvalid(index: index)
+    tracks.remove(at: index)
+
+    // Update shuffle order
+    shuffleOrder.remove(from: index, to: index + 1)
+
+    if index == currentIndex {
+      currentIndex = tracks.count > 0 ? currentIndex % tracks.count : -1
+      handleCurrentTrackChanged()
+    } else if index < currentIndex {
+      currentIndex -= 1
+    }
+  }
+
+  /**
+   Skip to a certain track in the queue.
+
+   - parameter index: The index of the track to skip to.
+   - parameter playWhenReady: Optional, whether to start playback when the track is ready.
+   - throws: `TrackPlayerError`
+   */
+  func skipTo(_ index: Int, playWhenReady: Bool? = nil) throws {
+    try handlePlayWhenReady(playWhenReady) {
+      if index == currentIndex {
+        seekTo(0)
+      } else {
+        try skipTo(index)
+      }
+    }
+  }
+
+  private func skipTo(_ index: Int) throws {
+    try throwIfQueueEmpty()
+    try throwIfIndexInvalid(index: index)
+
+    if index == currentIndex {
+      if playWhenReady {
+        replay()
+      }
+    } else {
+      currentIndex = index
+      handleCurrentTrackChanged()
+    }
+  }
+
+  /**
+   Move a track in the queue from one position to another.
+
+   - parameter fromIndex: The index of the track to move.
+   - parameter toIndex: The index to move the track to.
+   - throws: `TrackPlayerError.QueueError`
+   */
+  func move(fromIndex: Int, toIndex: Int) throws {
+    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
+      handleCurrentTrackChanged()
+    }
+  }
+
+  /**
+   Remove all upcoming tracks, those returned by `next()`
+   */
+  func removeUpcomingTracks() {
+    guard !tracks.isEmpty else { return }
+    let nextIndex = currentIndex + 1
+    guard nextIndex < tracks.count else { return }
+    tracks.removeSubrange(nextIndex ..< tracks.count)
+  }
+
+  /**
+   Removes all tracks from queue
+   */
+  private func clearTracks() {
+    guard currentIndex != -1 else { return }
+    currentIndex = -1
+    tracks.removeAll()
+    queueSourcePath = nil
+    handleCurrentTrackChanged()
+  }
+
+  func replay() {
+    seekTo(0) { [weak self] succeeded in
+      if succeeded {
+        Task { @MainActor in
+          self?.play()
+        }
+      }
+    }
+  }
+
+  func handleCurrentTrackChanged() {
+    // Reset end-of-track sleep timer when track changes
+    sleepTimerManager.onTrackChanged()
+
+    // Cancel any pending retry and reset count when track changes
+    pendingRetryTask?.cancel()
+    pendingRetryTask = nil
+    retryManager.reset()
+
+    // Clear any previous playback error when switching tracks
+    if playbackError != nil {
+      playbackError = nil
+    }
+
+    let lastPosition = currentTime
+    let shouldContinuePlayback = playWhenReady
+    if let currentTrack {
+      // Ensure playWhenReady is set before loading to preserve playback state
+      playWhenReady = shouldContinuePlayback
+
+      // Reset playback values without updating, because that will happen in
+      // the loadNowPlayingMetaValues call straight after:
+      nowPlayingInfoController.setWithoutUpdate(keyValues: [
+        MediaItemProperty.duration(nil),
+        NowPlayingInfoProperty.playbackRate(nil),
+        NowPlayingInfoProperty.elapsedPlaybackTime(nil),
+      ])
+      loadNowPlayingMetaValues()
+
+      // Load the track - resolve media URL first if resolver is configured
+      guard let src = currentTrack.src else {
+        logger.error("Failed to load track - no src")
+        logger.error("  track.title: \(currentTrack.title)")
+        logger.error("  track.url: \(currentTrack.url ?? "nil")")
+        clearCurrentAVItem()
+        playbackError = TrackPlayerError.PlaybackError.invalidSourceUrl("nil")
+        return
+      }
+
+      logger.debug("Loading track: \(currentTrack.title)")
+      logger.debug("  track.url: \(currentTrack.url ?? "nil")")
+      logger.debug("  track.src: \(src)")
+
+      // Check if it's already a full URL (http/https) or local file
+      if src.hasPrefix("http://") || src.hasPrefix("https://") || src.hasPrefix("file://") {
+        // Already a full URL, use directly (may still need transform for headers)
+        resolveAndLoadMedia(src: src, track: currentTrack)
+      } else {
+        // Relative path - needs media URL resolution
+        resolveAndLoadMedia(src: src, track: currentTrack)
+      }
+    } else {
+      unloadAVPlayer()
+      nowPlayingInfoController.clear()
+    }
+
+    let eventData = PlaybackActiveTrackChangedEvent(
+      lastIndex: lastIndex == -1 ? nil : Double(lastIndex),
+      lastTrack: lastTrack,
+      lastPosition: lastPosition,
+      index: currentIndex == -1 ? nil : Double(currentIndex),
+      track: currentTrack,
+    )
+    callbacks?.playerDidChangeActiveTrack(eventData)
+    lastTrack = currentTrack
+    lastIndex = currentIndex
+  }
+
+  /// Resolves the media URL (applying transform if configured) and loads the player
+  private func resolveAndLoadMedia(src: String, track: Track) {
+    // If we have a resolver, use it asynchronously
+    if let resolver = mediaUrlResolver {
+      // Don't use @MainActor for the entire Task - this can cause deadlocks
+      // when the JS callback needs to schedule work back on the main thread.
+      // Instead, only hop to main thread when we need to access/modify state.
+      Task {
+        self.logger.debug("resolveAndLoadMedia: starting resolution for \(src)")
+
+        // Check on main thread that this track is still the current one
+        let isCurrentTrack = await MainActor.run { self.currentTrack?.src == track.src }
+        guard isCurrentTrack else {
+          self.logger.debug("Track changed during media resolution, skipping load")
+          return
+        }
+
+        self.logger.debug("resolveAndLoadMedia: calling resolver...")
+        let resolved = await resolver(src)
+        self.logger.debug("resolveAndLoadMedia: resolver returned, resolved URL: \(resolved.url)")
+        if let headers = resolved.headers {
+          self.logger.debug("  headers: \(headers)")
+        }
+        if let userAgent = resolved.userAgent {
+          self.logger.debug("  userAgent: \(userAgent)")
+        }
+
+        // Load on main thread
+        await MainActor.run {
+          self.loadMediaWithResolvedUrl(resolved, track: track)
+        }
+      }
+    } else {
+      // No resolver, use src directly
+      let resolved = MediaResolvedUrl(url: src, headers: nil, userAgent: nil)
+      loadMediaWithResolvedUrl(resolved, track: track)
+    }
+  }
+
+  /// Loads the AVPlayer with a resolved media URL
+  private func loadMediaWithResolvedUrl(_ resolved: MediaResolvedUrl, track _: Track) {
+    guard let mediaUrl = URL(string: resolved.url) else {
+      logger.error("Invalid media URL: \(resolved.url)")
+      playbackError = TrackPlayerError.PlaybackError.invalidSourceUrl(resolved.url)
+      return
+    }
+
+    // Build URL options with headers if provided
+    var options: [String: Any] = [:]
+    if let headers = resolved.headers, !headers.isEmpty {
+      options["AVURLAssetHTTPHeaderFieldsKey"] = headers
+    }
+
+    let isLocalFile = mediaUrl.isFileURL
+    url = isLocalFile ? URL(fileURLWithPath: mediaUrl.path) : mediaUrl
+    urlOptions = options.isEmpty ? nil : options
+
+    logger.debug("  final playbackUrl: \(mediaUrl.absoluteString)")
+    logger.debug("  isLocalFile: \(isLocalFile)")
+
+    loadAVPlayer()
+  }
+}