react-native-queue-player 1.0.0

package/ios/PlaybackModeStateMachine.swift

@@ -0,0 +1,159 @@
+import Foundation
+import NitroModules
+
+/// Pure-data transition table for `PlaybackMode` switches.
+///
+/// Owns nothing — `TrackPlayer.setPlaybackMode` calls into the
+/// machine to compute (next state, transition effect) given the
+/// current `active` state. The caller applies the effect:
+///
+/// - `noOp`          → already in the requested mode.
+/// - `immediateSwap` → swap engines synchronously, regardless of
+///                     play state. A brief audible interruption
+///                     while the new engine constructs is the
+///                     expected feedback to the user.
+///
+/// Always-immediate is the right UX: the user sees + hears the
+/// engine change as soon as they confirm it. The same pattern
+/// extends naturally to cast-engine swaps (Chromecast / AirPlay)
+/// where waiting for a track boundary would be wrong.
+///
+/// Mirrored on Android in `PlaybackModeStateMachine.kt` with the
+/// same transition matrix. Cross-platform parity is enforced by
+/// the per-platform unit suites against the same matrix.
+final class PlaybackModeStateMachine {
+
+  /// `Equatable` synthesis would require `PlaybackMode: Equatable`,
+  /// but the Nitrogen-bridged `PlaybackMode` is a C++ struct typealias
+  /// and Swift interop does NOT bridge C++ `operator==` into Swift's
+  /// `Equatable` conformance. The hand-rolled `==` therefore delegates
+  /// to [modesEqual], which applies the same custom equality
+  /// `setRequested` uses (gapless ignores duration).
+  struct State: Equatable {
+    let active: PlaybackMode
+
+    init(active: PlaybackMode) {
+      self.active = active
+    }
+
+    static func == (lhs: State, rhs: State) -> Bool {
+      return PlaybackModeStateMachine.modesEqual(lhs.active, rhs.active)
+    }
+  }
+
+  enum TransitionEffect: Equatable {
+    case noOp
+    case immediateSwap
+  }
+
+  /// Default seed state for first-configure callers — gapless
+  /// mode, no pending. Avoids hand-construction at every entry
+  /// point.
+  static let initial: State = State(
+    active: PlaybackMode(kind: .gapless, crossfadeDurationMs: nil)
+  )
+
+  /// Compute the result of a `setPlaybackMode(requested)` call.
+  ///
+  /// Equality is structural — same kind + same `crossfadeDurationMs`
+  /// (or both nil for gapless) is a no-op. Swapping
+  /// `crossfade(2000) → crossfade(5000)` is NOT equal — the engine
+  /// must rebuild for the new duration.
+  ///
+  /// Throws `InvalidPlaybackModeError` when [requested] fails the
+  /// `requireValid` checks (out-of-range / non-quantised crossfade
+  /// duration); the caller's `throws` chain propagates it through
+  /// the Nitro Promise<Void> bridge as a JS-thrown error.
+  ///
+  /// The caller is responsible for managing the brief audio
+  /// interruption (resume position carryover, queue re-attach,
+  /// etc.) — that's the engine-handoff contract.
+  func setRequested(
+    state: State,
+    requested: PlaybackMode
+  ) throws -> (State, TransitionEffect) {
+    try Self.requireValid(requested)
+    if Self.modesEqual(state.active, requested) {
+      return (state, .noOp)
+    }
+    return (State(active: requested), .immediateSwap)
+  }
+
+  // The static helpers below are file-internal so the test suite
+  // can drive them directly: `PlaybackMode` is a C++ struct
+  // typealias on the Swift side and does not auto-conform to
+  // `Equatable`, so callers can't use `XCTAssertEqual` on it.
+  // Tests assert via `modesEqual` to mirror the production-code
+  // equality semantics.
+
+  /// Modes match when kind matches AND, for crossfade, when the
+  /// `crossfadeDurationMs` matches. Gapless never carries a
+  /// duration and is equal across construction.
+  static func modesEqual(_ a: PlaybackMode, _ b: PlaybackMode) -> Bool {
+    if a.kind != b.kind { return false }
+    switch a.kind {
+    case .gapless:
+      return true
+    case .crossfade:
+      return a.crossfadeDurationMs == b.crossfadeDurationMs
+    }
+  }
+
+  /// Reject malformed `PlaybackMode` at the state-machine entry
+  /// so the downstream `CrossfadeEngine` constructor sees only
+  /// valid inputs. Crossfade duration must be:
+  ///   - non-nil
+  ///   - within `[CrossfadeDurationBounds.minMs, CrossfadeDurationBounds.maxMs]`
+  ///   - quantised to `CrossfadeDurationBounds.stepMs` increments
+  ///
+  /// Throws Nitro's `RuntimeError` rather than aborting the
+  /// process — `precondition` / `preconditionFailure` would
+  /// terminate the app via `__assert_rtn`, not surface as a
+  /// catchable JS error. The Nitro bridge converts the throw to
+  /// a rejected JS Promise; `RuntimeError` (vs a custom `Error`
+  /// type) is the right choice because Nitro's
+  /// `RuntimeError.toCpp()` uses `String(describing:)`, which
+  /// `RuntimeError` exposes as the bare message string —
+  /// matches Android's `IllegalArgumentException` shape on the JS
+  /// side (consumer sees `e.message === "crossfadeDurationMs..."`,
+  /// not a wrapped type description).
+  ///
+  /// The runtime safety clamp inside `CrossfadeEngine`
+  /// (`effectiveCrossfadeSeconds`) reduces the configured value
+  /// further when the leading or standby track is shorter than
+  /// twice the configured duration — that clamp is silent + audio-
+  /// only + applies on top of this surface validation.
+  static func requireValid(_ mode: PlaybackMode) throws {
+    guard mode.kind == .crossfade else { return }
+    guard let ms = mode.crossfadeDurationMs else {
+      throw RuntimeError("PlaybackMode(crossfade) requires crossfadeDurationMs; got nil")
+    }
+    guard ms.isFinite else {
+      throw RuntimeError("crossfadeDurationMs must be finite; got \(ms)")
+    }
+    guard ms >= CrossfadeDurationBounds.minMs && ms <= CrossfadeDurationBounds.maxMs else {
+      throw RuntimeError("crossfadeDurationMs must be in [\(CrossfadeDurationBounds.minMs), \(CrossfadeDurationBounds.maxMs)]; got \(ms)")
+    }
+    guard CrossfadeDurationBounds.isQuantised(ms) else {
+      throw RuntimeError("crossfadeDurationMs must be quantised to \(CrossfadeDurationBounds.stepMs)ms steps; got \(ms)")
+    }
+  }
+}
+
+/// Surface-validation bounds for `crossfadeDurationMs`. Centralised
+/// so both the state machine + any consumer wanting to render a
+/// stepper UI can read the same numbers.
+enum CrossfadeDurationBounds {
+  static let minMs: Double = 1_000
+  static let maxMs: Double = 12_000
+  static let stepMs: Double = 500
+
+  /// True when `ms` lands exactly on a `stepMs` boundary. Uses
+  /// integer rounding so floating-point noise within ±0.5 of an
+  /// integer ms doesn't reject otherwise-valid inputs.
+  static func isQuantised(_ ms: Double) -> Bool {
+    let rounded = ms.rounded()
+    guard rounded == ms else { return false }
+    return Int(rounded).isMultiple(of: Int(stepMs))
+  }
+}

package/ios/PlayerStateDerivation.swift

@@ -0,0 +1,45 @@
+import AVFoundation
+
+/// Pure derivation of `PlayerState` from the active player's time-control
+/// status. Shared by BOTH engines (gapless + crossfade) via
+/// `PlaybackEngine.timeControlStatus`, so the two report identical states for
+/// identical situations — no per-engine special-casing for consumers. Mirrors
+/// Android's `TransportStateTranslator`; pure + deterministic, so it unit-tests
+/// directly.
+///
+/// iOS has no native "ended" player state (unlike Android's `STATE_ENDED`), so
+/// `reachedQueueEnd` is a latch that `TrackPlayer` sets when the queue drains
+/// with repeat off and clears when playback resumes / a new track loads.
+enum PlayerStateDerivation {
+  /// - Parameters:
+  ///   - status: the active player's `timeControlStatus`.
+  ///   - currentIndex: the lib's canonical current track index (`-1` = empty).
+  ///   - hasCurrentItem: whether the active player has a current item.
+  ///   - reachedQueueEnd: the end-of-queue latch (see type doc).
+  static func translate(
+    status: AVPlayer.TimeControlStatus,
+    currentIndex: Int,
+    hasCurrentItem: Bool,
+    reachedQueueEnd: Bool
+  ) -> PlayerState {
+    // A drained queue (repeat off) that isn't actively playing is terminal.
+    // `.playing` takes precedence so a resume reads correctly even before the
+    // latch clears.
+    if reachedQueueEnd, currentIndex >= 0, status != .playing {
+      return .ended
+    }
+    switch status {
+    case .paused:
+      return currentIndex < 0 ? .none : .paused
+    case .waitingToPlayAtSpecifiedRate:
+      // Waiting WITH a current item = initial load / rebuffer → `.buffering`.
+      // Waiting with NO item = the AVQueuePlayer advanced past the last item
+      // (end of queue) before the latch flipped → terminal `.ended`.
+      return hasCurrentItem ? .buffering : (currentIndex < 0 ? .none : .ended)
+    case .playing:
+      return .playing
+    @unknown default:
+      return .none
+    }
+  }
+}

package/ios/ProgressEmissionGate.swift

@@ -0,0 +1,54 @@
+/// Throttles the JS `onProgress` fan-out to a configurable cadence, with an
+/// optional reduced rate while the app is backgrounded. Pure + deterministic
+/// (the caller supplies a monotonic timestamp), so it unit-tests directly.
+///
+/// This gates ONLY the JS emission — the native 2 Hz sampler keeps running, so
+/// milestone detection and buffer-state recomputation stay full-rate. A tick
+/// emits when at least `interval` has elapsed since the last emit, where
+/// `interval` is the foreground or background cadence per the current app
+/// state. `lastEmittedMs` starts at `-.infinity` so the first tick after a
+/// subscribe always emits, and a background→foreground transition resets it so
+/// the now-visible UI resumes at the live position on the next tick.
+///
+/// Main-thread-confined (the progress tick, the cast push, and the
+/// background/foreground notifications all run on main), so no synchronisation.
+struct ProgressEmissionGate {
+  private var foregroundIntervalMs: Double = 500
+  private var backgroundIntervalMs: Double = 500
+  private var isBackgrounded = false
+  private var lastEmittedMs: Double = -.infinity
+  /// Half the native sampler period. The sampler fires at a fixed cadence, so a
+  /// configured interval equal to that cadence would drop ~half the ticks to
+  /// timing jitter — a tick landing a hair early reads as "too soon". Allowing
+  /// emission up to half a sampler period early snaps each emit to the nearest
+  /// tick: interval == sampler period emits every tick, 2× the period emits
+  /// every other tick, and so on.
+  private var toleranceMs: Double = 0
+
+  /// Set the foreground + background cadences (already clamped by the caller)
+  /// and the native sampler period that drives `shouldEmit`. Runtime state
+  /// (`lastEmittedMs`, `isBackgrounded`) is preserved so a re-`configure()`
+  /// updates the rate without dropping the throttle position.
+  mutating func setIntervals(foregroundMs: Double, backgroundMs: Double, samplerPeriodMs: Double) {
+    foregroundIntervalMs = foregroundMs
+    backgroundIntervalMs = backgroundMs
+    toleranceMs = samplerPeriodMs / 2
+  }
+
+  /// Whether a tick at `nowMs` may emit; records the emit time when it does.
+  mutating func shouldEmit(nowMs: Double) -> Bool {
+    let interval = isBackgrounded ? backgroundIntervalMs : foregroundIntervalMs
+    guard nowMs - lastEmittedMs >= interval - toleranceMs else { return false }
+    lastEmittedMs = nowMs
+    return true
+  }
+
+  /// Update the foreground/background state. On a background→foreground
+  /// transition, force the next tick to emit immediately (foreground-flush).
+  mutating func setBackgrounded(_ backgrounded: Bool) {
+    if isBackgrounded && !backgrounded {
+      lastEmittedMs = -.infinity
+    }
+    isBackgrounded = backgrounded
+  }
+}

package/ios/QueueMutationArithmetic.swift

@@ -0,0 +1,129 @@
+import Foundation
+
+/// Pure-Swift index-shift arithmetic for queue mutations. Extracted
+/// from `TrackPlayer.swift` so the shift semantics are unit-testable
+/// without an AVQueuePlayer. Mirrors
+/// `android/.../QueueMutationArithmetic.kt` 1:1 — same function
+/// shapes, same input/output semantics, same test matrix.
+///
+/// The helper only computes the new `currentTrackIndex` and (for
+/// `removeFromQueue`) which original indices apply after dedup /
+/// range-filter. Actual mutation of the track list + forwarding to
+/// AVQueuePlayer happens in `TrackPlayer.swift`.
+///
+/// Gated behind `@_spi(QueuePlayerTests)` so the helpers stay off
+/// the library's consumer-facing public surface — same SPI scope
+/// used by `AVQueueBuilder.makeItemRaw`. The `@_spi` annotation
+/// goes on each function (not the enum) to match the project-
+/// established pattern + ensure cross-module visibility from the
+/// test bundle.
+public enum QueueMutationArithmetic {
+
+  /// Clamp an `insertBefore` argument to a valid insertion point in
+  /// a track list of size `trackCount`. `nil` → append (return
+  /// `trackCount`). Out-of-range values clamp into `0...trackCount`.
+  @_spi(QueuePlayerTests)
+  public static func clampInsertBefore(insertBefore: Int?, trackCount: Int) -> Int {
+    guard let insertBefore else { return trackCount }
+    if insertBefore < 0 { return 0 }
+    if insertBefore > trackCount { return trackCount }
+    return insertBefore
+  }
+
+  /// New `currentTrackIndex` after inserting `count` items at
+  /// `insertAt`.
+  ///
+  /// Rules:
+  /// - empty queue (`currentIndex < 0`) — stays at -1; inserting
+  ///   into an empty queue does NOT auto-start playback (consumers
+  ///   call `skipToIndex(0)` explicitly).
+  /// - `insertAt <= currentIndex` — cur shifts forward by `count`
+  ///   (items slid under it).
+  /// - `insertAt > currentIndex` — cur unchanged.
+  /// - `count <= 0` — no-op (should not be called with empty inputs
+  ///   in practice; defensive).
+  @_spi(QueuePlayerTests)
+  public static func currentIndexAfterAdd(
+    currentIndex: Int, insertAt: Int, count: Int
+  ) -> Int {
+    if count <= 0 { return currentIndex }
+    if currentIndex < 0 { return currentIndex }
+    return insertAt <= currentIndex ? currentIndex + count : currentIndex
+  }
+
+  /// Filter + dedup a removal-index input, dropping out-of-range
+  /// and negative entries. Returned array is ASCENDING — callers
+  /// iterate it descending when applying removals to the
+  /// underlying list, but ascending shape is easier to reason
+  /// about for the shift math downstream.
+  ///
+  /// `Set<Int>` has no defined iteration order in Swift, so the
+  /// explicit `.sorted()` is load-bearing — do not omit it.
+  @_spi(QueuePlayerTests)
+  public static func sanitiseRemoveIndices(
+    rawIndices: [Int], trackCount: Int
+  ) -> [Int] {
+    let inRange = rawIndices.filter { $0 >= 0 && $0 < trackCount }
+    return Array(Set(inRange)).sorted()
+  }
+
+  /// New `currentTrackIndex` after removing the given (sanitised,
+  /// ascending) indices from the track list.
+  ///
+  /// Rules (matches Kotlin sibling):
+  /// - `currentIndex < 0` (empty / not-started) — stays -1.
+  /// - Every `i < currentIndex` that was removed shifts cur down
+  ///   by 1.
+  /// - If cur itself was removed AND the list becomes empty,
+  ///   cur → -1.
+  /// - If cur itself was removed but other tracks remain, cur
+  ///   stays at the SAME index value (now points at the track
+  ///   previously at `cur+1` — auto-advance semantic). Clamp to
+  ///   `newTrackCount - 1` if that lands past the new tail.
+  @_spi(QueuePlayerTests)
+  public static func currentIndexAfterRemove(
+    currentIndex: Int, sanitisedIndices: [Int], trackCountBefore: Int
+  ) -> Int {
+    if currentIndex < 0 { return -1 }
+    let indexSet = Set(sanitisedIndices)
+    let removedBelowCur = sanitisedIndices.filter { $0 < currentIndex }.count
+    let newTrackCount = trackCountBefore - sanitisedIndices.count
+    if newTrackCount <= 0 { return -1 }
+
+    var newCur = currentIndex - removedBelowCur
+    if indexSet.contains(currentIndex) {
+      // cur was removed; player auto-advances to what was at cur+1,
+      // which now occupies the same index value after the earlier-
+      // below shift has been applied. Clamp in case cur was at the
+      // tail. Narrower-than-iOS-original guard for fidelity to the
+      // Kotlin matrix (functionally equivalent — `removedBelow`
+      // can never push `newCur` above the new tail).
+      if newCur >= newTrackCount { newCur = newTrackCount - 1 }
+    }
+    return newCur
+  }
+
+  /// New `currentTrackIndex` after moving the track at `fromIndex`
+  /// to `toIndex`. Inputs are assumed validated (in range,
+  /// `from != to`).
+  ///
+  /// Rules (matches Kotlin sibling):
+  /// - `currentIndex < 0` → -1.
+  /// - `currentIndex == fromIndex` → `newCur = toIndex` (cur moved
+  ///   with the track).
+  /// - `from < cur && to >= cur` → `newCur -= 1` (track slid past
+  ///   cur from below; cur is now one slot earlier).
+  /// - `from > cur && to <= cur` → `newCur += 1` (track slid past
+  ///   cur from above; cur is now one slot later).
+  /// - otherwise cur unchanged.
+  @_spi(QueuePlayerTests)
+  public static func currentIndexAfterMove(
+    currentIndex: Int, fromIndex: Int, toIndex: Int
+  ) -> Int {
+    if currentIndex < 0 { return currentIndex }
+    if currentIndex == fromIndex { return toIndex }
+    if fromIndex < currentIndex && toIndex >= currentIndex { return currentIndex - 1 }
+    if fromIndex > currentIndex && toIndex <= currentIndex { return currentIndex + 1 }
+    return currentIndex
+  }
+}

package/ios/QueueSkipArithmetic.swift

@@ -0,0 +1,109 @@
+/// Pure-Swift skip-index arithmetic. Extracted from `TrackPlayer.swift`
+/// so the logic can be unit-tested without crossing the Swift ↔ C++
+/// interop boundary — Nitrogen-generated types (`TrackItem`, `RepeatMode`)
+/// don't export their members to importing modules under Swift's current
+/// `-cxx-interoperability-mode=default` settings, which makes `@testable
+/// import QueuePlayer` useless for touching anything that reads Nitro
+/// types. By taking primitive arguments, these helpers stay reachable
+/// from the XCTest bundle via plain `import QueuePlayer`.
+///
+/// `TrackPlayer.computeNextIndex` / `.computePreviousIndex` instance
+/// methods are thin adapters that map the Nitrogen `RepeatMode` enum
+/// onto `QueueSkipRepeatMode` and call through here.
+
+/// Repeat-mode enum expressed in plain Swift. Value order (0/1/2)
+/// matches `RepeatModeKind` in the nitro.ts spec, so a test that
+/// asserts the raw integer is robust against accidental reordering
+/// in the Nitrogen spec.
+///
+/// Gated behind `@_spi(QueuePlayerTests)` so the XCTest-only helper
+/// surface stays off the library's consumer-facing API.
+@_spi(QueuePlayerTests)
+public enum QueueSkipRepeatMode: Int {
+  case off = 0
+  case track = 1
+  case queue = 2
+}
+
+@_spi(QueuePlayerTests)
+public enum QueueSkipArithmetic {
+
+  /// Returns the next-track index, or nil when nothing should play
+  /// next (empty queue, no next track under `.off`/`.track` at the
+  /// end, or nothing currently playing). `.track` navigates
+  /// identically to `.off`: advance with no wrap. Repeat-one persists
+  /// so the newly-current track loops on natural end (handled in
+  /// `TrackPlayer`, not here).
+  public static func computeNext(
+    trackCount: Int,
+    currentIndex: Int,
+    repeatMode: QueueSkipRepeatMode
+  ) -> Int? {
+    guard trackCount > 0, currentIndex >= 0 else { return nil }
+    switch repeatMode {
+    case .off, .track:
+      let next = currentIndex + 1
+      return next < trackCount ? next : nil
+    case .queue:
+      let next = currentIndex + 1
+      return next < trackCount ? next : 0
+    }
+  }
+
+  /// Previous-track index. Same early-bail rules as `computeNext`.
+  ///
+  /// `.off` and `.track` both return nil at index 0 (no previous
+  /// track, no wrap). Apps that want the "tap Previous at track 0
+  /// restarts current" UX implement that in their button handler.
+  public static func computePrevious(
+    trackCount: Int,
+    currentIndex: Int,
+    repeatMode: QueueSkipRepeatMode
+  ) -> Int? {
+    guard trackCount > 0, currentIndex >= 0 else { return nil }
+    switch repeatMode {
+    case .off, .track:
+      let prev = currentIndex - 1
+      return prev >= 0 ? prev : nil
+    case .queue:
+      return currentIndex == 0 ? trackCount - 1 : currentIndex - 1
+    }
+  }
+
+  /// Whether the user-facing Next button should be enabled. Defined as
+  /// `computeNext(...) != nil` so all three repeat modes are handled
+  /// in one place: `.off` and `.track` are false at the last track
+  /// (no wrap); `.queue` is always true with an active track (wraps).
+  public static func canSkipNext(
+    trackCount: Int,
+    currentIndex: Int,
+    repeatMode: QueueSkipRepeatMode
+  ) -> Bool {
+    return computeNext(
+      trackCount: trackCount,
+      currentIndex: currentIndex,
+      repeatMode: repeatMode) != nil
+  }
+
+  /// Whether the user-facing Previous button should be enabled.
+  /// Symmetric with `canSkipNext` — defined as `computePrevious(...)
+  /// != nil`, so all three repeat modes are handled in one place:
+  /// `.off` and `.track` are false at index 0 (no wrap); `.queue` is
+  /// always true with an active track (wraps).
+  ///
+  /// **Apps that want the Apple-Music-style "tap Previous restarts
+  /// when position > 3s" UX** should implement that in their button
+  /// handler: read playback position, branch to `seekTo(0)` vs
+  /// `skipToPrevious()` themselves. Lib intentionally ships the
+  /// primitive (skip if there's a track to skip to), not the policy.
+  public static func canSkipPrevious(
+    trackCount: Int,
+    currentIndex: Int,
+    repeatMode: QueueSkipRepeatMode
+  ) -> Bool {
+    return computePrevious(
+      trackCount: trackCount,
+      currentIndex: currentIndex,
+      repeatMode: repeatMode) != nil
+  }
+}

package/ios/QueueState.swift

@@ -0,0 +1,49 @@
+import Foundation
+
+/// Two parallel arrays bound 1:1 — `tracks[i]` is the consumer-supplied
+/// `TrackItem` at queue position `i`, `queueItemIds[i]` is the
+/// lib-generated UUID stamped onto the corresponding AVPlayerItem.
+/// `matchTrackIndex` looks up `player.currentItem` by walking
+/// `queueItemIds`; mismatched lengths break that lookup.
+///
+/// All mutations go through the methods below so the two fields
+/// always change together. Fields are `private(set)` so external
+/// code can read but never assign.
+internal struct QueueState {
+  private(set) var tracks: [TrackItem] = []
+  private(set) var queueItemIds: [String] = []
+
+  /// Returns the freshly-generated IDs.
+  mutating func replaceAll(_ newTracks: [TrackItem]) -> [String] {
+    tracks = newTracks
+    queueItemIds = newTracks.map { _ in UUID().uuidString }
+    return queueItemIds
+  }
+
+  /// Returns the freshly-generated IDs for the inserted slice.
+  mutating func insert(_ newTracks: [TrackItem], at index: Int) -> [String] {
+    let newIds = newTracks.map { _ in UUID().uuidString }
+    tracks.insert(contentsOf: newTracks, at: index)
+    queueItemIds.insert(contentsOf: newIds, at: index)
+    return newIds
+  }
+
+  /// Returns the removed `queueItemId`.
+  mutating func remove(at index: Int) -> String {
+    let removedId = queueItemIds.remove(at: index)
+    tracks.remove(at: index)
+    return removedId
+  }
+
+  mutating func move(from: Int, to: Int) {
+    let movedTrack = tracks.remove(at: from)
+    tracks.insert(movedTrack, at: to)
+    let movedId = queueItemIds.remove(at: from)
+    queueItemIds.insert(movedId, at: to)
+  }
+
+  mutating func clear() {
+    tracks.removeAll()
+    queueItemIds.removeAll()
+  }
+}