react-native-queue-player 1.2.0 → 2.0.1

package/ios/TrackPlayer+SleepTimer.swift

@@ -0,0 +1,175 @@
+import Foundation
+import NitroModules
+
+extension TrackPlayer {
+  func setSleepTimer(seconds: Double) throws -> Promise<Void> {
+    return enqueue { self.setSleepTimerInternal(seconds: seconds) }
+  }
+  func setSleepTimerToTrackEnd() throws -> Promise<Void> {
+    return enqueue { self.armSleepTimerToTrackEndInternal() }
+  }
+  func clearSleepTimer() throws -> Promise<Void> {
+    return enqueue { self.clearSleepTimerInternal() }
+  }
+  func getSleepTimer() throws -> SleepTimerState {
+    return onPlayerQueueSync { self.sleepTimerSnapshot() }
+  }
+  func onSleepTimerChange(
+    callback: @escaping (_ state: SleepTimerState) -> Void
+  ) throws -> () -> Void {
+    let id = sleepTimerListeners.add(callback)
+    playerQueue.async { [weak self] in
+      guard let self else { return }
+      guard self.sleepTimerListeners.contains(id: id) else { return }
+      callback(self.sleepTimerSnapshot())
+    }
+    return { [weak self] in _ = self?.sleepTimerListeners.remove(id: id) }
+  }
+
+  // MARK: - Sleep timer — internal
+
+  /// Arm a wall-clock duration timer; a non-positive value clears any timer.
+  private func setSleepTimerInternal(seconds: Double) {
+    guard seconds.isFinite, seconds > 0 else {
+      clearSleepTimerInternal()
+      return
+    }
+    restoreSleepTimerVolume()
+    sleepTimerCore.armDuration(seconds: seconds, nowMs: Self.nowEpochMs())
+    startSleepTimerTick()
+    emitSleepTimerChanged()
+  }
+
+  private func armSleepTimerToTrackEndInternal() {
+    restoreSleepTimerVolume()
+    sleepTimerCore.armEndOfTrack()
+    startSleepTimerTick()
+    emitSleepTimerChanged()
+  }
+
+  private func clearSleepTimerInternal() {
+    let wasActive = sleepTimerCore.isActive
+    restoreSleepTimerVolume()
+    sleepTimerCore.clear()
+    stopSleepTimerTick()
+    if wasActive { emitSleepTimerChanged() }
+  }
+
+  private func sleepTimerSnapshot() -> SleepTimerState {
+    let now = Self.nowEpochMs()
+    return SleepTimerState(
+      active: sleepTimerCore.isActive,
+      endsAtEpochMs: sleepTimerCore.deadlineEpochMs.map { Double($0) },
+      remainingSeconds: sleepTimerCore.remainingSeconds(nowMs: now).map { Double($0) },
+      endOfTrack: sleepTimerCore.isEndOfTrack)
+  }
+
+  private func emitSleepTimerChanged() {
+    let snapshot = sleepTimerSnapshot()
+    sleepTimerListeners.forEach { $0(snapshot) }
+  }
+
+  private func startSleepTimerTick() {
+    guard sleepTimerTimer == nil else { return }
+    let timer = DispatchSource.makeTimerSource(queue: playerQueue)
+    timer.schedule(
+      deadline: .now() + Self.sleepTimerTickInterval,
+      repeating: Self.sleepTimerTickInterval)
+    timer.setEventHandler { [weak self] in
+      self?.onSleepTimerTick()
+    }
+    sleepTimerTimer = timer
+    // The source is resumed exactly once and never suspended — a suspended
+    // source traps libdispatch on release.
+    timer.resume()
+  }
+
+  /// Caller must be on `playerQueue` — cancelling from the source's own
+  /// queue is what guarantees no further tick.
+  internal func stopSleepTimerTick() {
+    sleepTimerTimer?.cancel()
+    sleepTimerTimer = nil
+  }
+
+  private func onSleepTimerTick() {
+    // While casting, the local engine is intentionally frozen (its position
+    // never advances), so feed the state machine the receiver's position /
+    // duration instead — otherwise the end-of-track tail rule never trips and
+    // `.endOfTrack` stays idle forever.
+    let durationSec: Double
+    let positionSec: Double
+    if let remote = PlaybackStateRouter.shared.activeRemote() {
+      let d = Double(remote.lastDurationMs) / 1000.0
+      let p = Double(remote.lastPositionMs) / 1000.0
+      durationSec = (d.isFinite && d > 0) ? d : 0
+      positionSec = (p.isFinite && p > 0) ? p : 0
+    } else {
+      let duration = self.engine?.currentDurationSeconds ?? 0
+      let position = self.engine?.currentPositionSeconds ?? 0
+      durationSec = (duration.isFinite && duration > 0) ? duration : 0
+      positionSec = (position.isFinite && position > 0) ? position : 0
+    }
+    let result = sleepTimerCore.tick(
+      nowMs: Self.nowEpochMs(),
+      trackDurationSec: durationSec,
+      trackPositionSec: positionSec)
+    applySleepTimerResult(result)
+  }
+
+  /// Apply a `SleepTimerCore.Tick` decision to the engine — fade, state emit,
+  /// and the boundary pause. Shared by the polling tick and the real track-end
+  /// signal (`handlePlayerItemDidPlayToEndTime`).
+  internal func applySleepTimerResult(_ result: SleepTimerCore.Tick) {
+    applySleepTimerFade(result.fadeFraction)
+    if result.stateChanged { emitSleepTimerChanged() }
+    if result.pauseNow {
+      // Route the boundary pause to the receiver when casting (the receiver
+      // emits its own paused state); only the local-engine pause needs the
+      // sleep-timer reason tag.
+      if !CastTransportRouter.routePause() {
+        self.pendingStateChangeReason = .sleepTimer
+        // The timer's pause is a transport intent like the user's: without
+        // clearing these, a drain that follows (the timer firing at a track
+        // end on the last installed item) or a buffer refill would restart
+        // playback the timer just stopped.
+        self.wantsToPlay = false
+        self.isRecoveringFromStall = false
+        self.engine?.pause()
+      }
+    }
+    if !sleepTimerCore.isActive { stopSleepTimerTick() }
+  }
+
+  /// Fade multiplies off `volumeState` without mutating it, so `getVolume`
+  /// stays truthful and the pre-fade level is restored on clear/fire.
+  private func applySleepTimerFade(_ fraction: Double) {
+    // Fade is local-only: the receiver's volume is user/system-owned and
+    // `volumeState` tracks the local level, so ramping it on the receiver would
+    // clobber the cast volume. When casting the boundary pause still routes to
+    // the receiver; the pre-pause fade is skipped. Undo any in-progress local
+    // fade first so a cast session appearing mid-fade can't strand the local
+    // engine at a ramped-down volume for a later cast→local return.
+    if PlaybackStateRouter.shared.activeRemote() != nil {
+      restoreSleepTimerVolume()
+      return
+    }
+    if fraction < 1.0 {
+      self.engine?.setVolume(Float(Double(self.volumeState) * fraction))
+      sleepTimerFading = true
+    } else if sleepTimerFading {
+      self.engine?.setVolume(self.volumeState)
+      sleepTimerFading = false
+    }
+  }
+
+  private func restoreSleepTimerVolume() {
+    if sleepTimerFading {
+      self.engine?.setVolume(self.volumeState)
+      sleepTimerFading = false
+    }
+  }
+
+  private static func nowEpochMs() -> Int64 {
+    Int64(Date().timeIntervalSince1970 * 1000)
+  }
+}

package/ios/TrackPlayer+State.swift

@@ -0,0 +1,108 @@
+import Foundation
+
+extension TrackPlayer {
+  // MARK: - State snapshots
+  //
+  // Nitro calls these getters on a JS worker thread. Player state lives
+  // on `playerQueue`, so every read hops there with `onPlayerQueueSync`,
+  // which runs the body inline when the caller is already on that queue
+  // (a `sync` from the queue onto itself would deadlock). The cached
+  // `canSkip*` Bools are written on `playerQueue` by
+  // `recomputeCapabilities()`, so the same hop reads them consistently.
+  func getState() throws -> PlayerState {
+    // The receiver owns playback during a cast session — the local engine is
+    // parked and paused for its duration, so its derived state describes
+    // nothing the user can hear. Until the receiver has reported (session
+    // still activating, holding its initial `.idle`) the local read is the
+    // better answer; after that the receiver is authoritative, including a
+    // later `.idle`, which means it genuinely has nothing loaded.
+    if let remote = PlaybackStateRouter.shared.activeRemote(), remote.hasReportedState {
+      return remote.lastState.asPlayerState
+    }
+    return onPlayerQueueSync {
+      // Both engines derive PlayerState from the same inputs via
+      // `engine.timeControlStatus` (gapless returns its AVQueuePlayer's, which
+      // is what `self.player` also points at; crossfade returns the active
+      // leg's), so gapless + crossfade report identical states. `.none` when no
+      // engine is configured.
+      guard let engine = self.engine else { return .none }
+      return PlayerStateDerivation.translate(
+        status: engine.timeControlStatus,
+        currentIndex: self.currentTrackIndex,
+        hasCurrentItem: engine.currentMediaItem != nil,
+        reachedQueueEnd: self.reachedQueueEnd
+      )
+    }
+  }
+  func getCurrentTrackIndex() throws -> Double {
+    // Nitrogen spec types this return as Double; bridge the internal Int.
+    return onPlayerQueueSync { Double(self.currentTrackIndex) }
+  }
+  func getCurrentTrackSource() throws -> TrackSource? {
+    return onPlayerQueueSync { self.currentTrackSource }
+  }
+  func getCanSkipNext() throws -> Bool {
+    return onPlayerQueueSync { self.cachedSkipCapability.canSkipNext }
+  }
+  func getSkipCapability() throws -> SkipCapability {
+    return onPlayerQueueSync { self.cachedSkipCapability }
+  }
+  func getCanSkipPrevious() throws -> Bool {
+    return onPlayerQueueSync { self.cachedSkipCapability.canSkipPrevious }
+  }
+  func getPlaybackSpeed() throws -> Double {
+    return onPlayerQueueSync { Double(self.playbackSpeedState) }
+  }
+  func getVolume() throws -> Double {
+    return onPlayerQueueSync { Double(self.volumeState) }
+  }
+  func getRemoteControls() throws -> RemoteControlOptions {
+    return onPlayerQueueSync {
+      let options: RemoteControlOptions = .init(
+        skipMode: self.remoteSkipMode,
+        forwardJumpInterval: self.remoteForwardInterval,
+        backwardJumpInterval: self.remoteBackwardInterval)
+      return options
+    }
+  }
+
+  func getBufferState() throws -> BufferState {
+    return onPlayerQueueSync { self.currentBufferState }
+  }
+
+  func getIsSeekable() throws -> Bool {
+    return onPlayerQueueSync {
+      guard let item = self.engine?.currentMediaItem else { return true }
+      return !item.seekableTimeRanges.isEmpty
+    }
+  }
+
+  func isFullyBuffered() throws -> Bool {
+    return onPlayerQueueSync { self.currentFullyBuffered }
+  }
+
+  func onBufferStateChange(
+    callback: @escaping (_ state: BufferState) -> Void
+  ) throws -> () -> Void {
+    let id = bufferStateListeners.add(callback)
+    // Fire once on subscribe with the current state so a UI renders immediately.
+    playerQueue.async { [weak self] in
+      guard let self else { return }
+      guard self.bufferStateListeners.contains(id: id) else { return }
+      callback(self.currentBufferState)
+    }
+    return { [weak self] in self?.bufferStateListeners.remove(id: id) }
+  }
+
+  func onFullyBufferedChange(
+    callback: @escaping (_ fullyBuffered: Bool) -> Void
+  ) throws -> () -> Void {
+    let id = fullyBufferedListeners.add(callback)
+    playerQueue.async { [weak self] in
+      guard let self else { return }
+      guard self.fullyBufferedListeners.contains(id: id) else { return }
+      callback(self.currentFullyBuffered)
+    }
+    return { [weak self] in self?.fullyBufferedListeners.remove(id: id) }
+  }
+}

package/ios/TrackPlayer+Threading.swift

@@ -0,0 +1,135 @@
+import Foundation
+import NitroModules
+
+extension TrackPlayer {
+  /// True when the caller is already executing on `playerQueue`.
+  ///
+  /// `DispatchQueue.sync` runs its body on the calling thread, so a thread
+  /// identity test answers the wrong question — it reports "main" for work
+  /// serialised on the queue and would let a nested `sync` deadlock. The
+  /// queue's own specific travels with the execution context instead.
+  internal var isOnPlayerQueue: Bool {
+    DispatchQueue.getSpecific(key: playerQueueKey) == ObjectIdentifier(self)
+  }
+
+  /// Claim the audio session, then start the engine.
+  ///
+  /// Every path that starts playback goes through here so activation cannot be
+  /// forgotten at a new one. `activateIfNeeded` is idempotent, so the cost
+  /// after the first play is a bool check.
+  ///
+  /// Activation is deliberately not done at `configure()`: that would stop
+  /// whatever else the user is listening to the moment a consumer app
+  /// launches, before they have pressed anything.
+  internal func beginPlayback() {
+    audioSession.activateIfNeeded()
+    engine?.play()
+  }
+
+  /// Enqueue `body` on `playerQueue` **at call time**, on the calling thread,
+  /// and resolve the returned promise when it completes.
+  ///
+  /// This is what makes the queue's FIFO order equal the JS call order.
+  /// `Promise.async` starts an unstructured `Task`, and two Tasks created back
+  /// to back have no ordering relationship with each other — so a body that
+  /// hops onto the queue *inside* the Task reaches the player at an arbitrary
+  /// later point. Two calls issued in order from JS could then arrive
+  /// reversed: `play()` then `pause()` landing as pause-then-play, leaving
+  /// audio running after the user paused it.
+  ///
+  /// A serial queue gives mutual exclusion, not ordering. Ordering comes from
+  /// when the work is enqueued, which is why this runs before returning.
+  internal func enqueue(_ body: @escaping () -> Void) -> Promise<Void> {
+    let promise = Promise<Void>()
+    playerQueue.async {
+      body()
+      promise.resolve()
+    }
+    return promise
+  }
+
+  /// Enqueue a mutation at call time and hand its result to a receiver mirror
+  /// that runs off the queue.
+  ///
+  /// The enqueue is what fixes ordering against other player work — a later
+  /// call cannot overtake this one. Doing it with `async` rather than `sync`
+  /// matters just as much: the mutation can rebuild the whole player queue,
+  /// and `sync` would run that on the JS thread.
+  ///
+  /// `mirror` awaits the receiver afterwards, holding neither the queue nor
+  /// the calling thread, and is chained behind the previous mutation's mirror
+  /// so the receiver sees mutations in the order they were made. The promise
+  /// resolves once the mirror returns, so a consumer awaiting the call knows
+  /// local and remote are both settled.
+  internal func enqueueThenMirror<T>(
+    _ body: @escaping () -> T,
+    mirror: @escaping (T, _ generation: UInt64) async -> Void
+  ) -> Promise<Void> {
+    let promise = Promise<Void>()
+    playerQueue.async {
+      self.queueMutationGeneration &+= 1
+      let generation = self.queueMutationGeneration
+      let value = body()
+      let previous = self.castMirrorChain
+      self.castMirrorChain = Task {
+        // Deltas are only correct against a receiver that has applied
+        // everything before them, so this waits rather than racing. A failed
+        // mirror still completes its Task, so one bad round-trip cannot wedge
+        // the chain.
+        await previous?.value
+        await mirror(value, generation)
+        promise.resolve()
+      }
+    }
+    return promise
+  }
+
+  /// Value-returning variant of `enqueue`.
+  internal func enqueueValue<T>(_ body: @escaping () -> T) -> Promise<T> {
+    let promise = Promise<T>()
+    playerQueue.async {
+      promise.resolve(withResult: body())
+    }
+    return promise
+  }
+
+  /// Throwing variant of `enqueue` — a thrown error rejects the JS promise
+  /// with its message, as `Promise.async` does for a throwing body.
+  internal func enqueueThrowing(_ body: @escaping () throws -> Void) -> Promise<Void> {
+    let promise = Promise<Void>()
+    playerQueue.async {
+      do {
+        try body()
+        promise.resolve()
+      } catch {
+        promise.reject(withError: error)
+      }
+    }
+    return promise
+  }
+
+  /// Serialise a mutation body on `playerQueue` and return a
+  /// Promise-compatible awaitable. Centralising here keeps every access to
+  /// player state on one queue, which is what makes the state safe to read
+  /// without locks inside these bodies.
+  internal func onPlayerQueue(_ body: @escaping () -> Void) async {
+    await withCheckedContinuation { (cont: CheckedContinuation<Void, Never>) in
+      playerQueue.async {
+        body()
+        cont.resume()
+      }
+    }
+  }
+
+  /// Run `body` on `playerQueue` synchronously and return its value. Used by
+  /// the Nitro getters and the listener register / dispose paths, which are
+  /// not Promise-wrapped and run on whatever thread the JS bridge uses.
+  ///
+  /// Running inline when already on the queue is what makes re-entrant calls
+  /// safe: `playerQueue.sync` from a block already on `playerQueue` is an
+  /// immediate deadlock.
+  internal func onPlayerQueueSync<T>(_ body: () -> T) -> T {
+    if isOnPlayerQueue { return body() }
+    return playerQueue.sync(execute: body)
+  }
+}