react-native-audio-browser 0.1.1 → 0.2.0-next.2

package/src/web/TrackPlayer/QueueManager.ts

@@ -0,0 +1,302 @@
+import type { RepeatMode as RepeatModeType } from '../../features'
+import type { Track } from '../../types'
+import { assertedNotNullish } from '../../utils/validation'
+import { fisherYatesShuffle } from '../util/shuffle'
+import { RepeatMode } from './RepeatMode'
+
+/**
+ * What removing tracks means for the currently-playing item — the caller (the
+ * player) acts on it (reload / stop), keeping engine concerns out of the queue.
+ */
+export type RemoveOutcome =
+  | { kind: 'no-current' } // nothing was playing; the queue was filtered, nothing else to do
+  | { kind: 'kept' } // the current track survived; its index was adjusted in place
+  | { kind: 'reload'; index: number } // the current track was removed; reload this index
+  | { kind: 'emptied' } // the current track was removed and the queue is now empty
+
+/**
+ * Owns the play queue: the track list, the current/last index, repeat mode and
+ * shuffle order, plus all the pure index math (next/previous, wrap-around,
+ * shuffle ordering, index adjustment on mutation). It has no knowledge of the
+ * playback engine — the web analog of iOS's `QueueManager` + `ShuffleOrder`.
+ * Orchestration (loading a track when the index changes) stays with the caller.
+ */
+export class QueueManager {
+  private _tracks: Track[] = []
+  private _currentIndex: number | undefined
+  private _lastIndex: number | undefined
+  private _repeatMode: RepeatModeType = RepeatMode.Off
+  private _shuffleEnabled = false
+  private shuffleOrder: number[] = []
+
+  // MARK: tracks
+
+  get tracks(): Track[] {
+    return this._tracks
+  }
+
+  get length(): number {
+    return this._tracks.length
+  }
+
+  getTrack(index: number): Track | undefined {
+    return this._tracks[index]
+  }
+
+  /** Replaces the whole queue and resets the current/last index. */
+  setTracks(tracks: Track[]): void {
+    this._tracks = tracks
+    this._currentIndex = undefined
+    this._lastIndex = undefined
+    if (this._shuffleEnabled) this.regenerateShuffleOrder()
+  }
+
+  /** Replaces a single track in place (e.g. a favorite toggle). */
+  replaceTrack(index: number, track: Track): void {
+    this._tracks[index] = track
+  }
+
+  // MARK: current index
+
+  get currentIndex(): number | undefined {
+    return this._currentIndex
+  }
+
+  set currentIndex(index: number | undefined) {
+    this._lastIndex = this._currentIndex
+    this._currentIndex = index
+  }
+
+  get lastIndex(): number | undefined {
+    return this._lastIndex
+  }
+
+  // MARK: repeat / shuffle
+
+  get repeatMode(): RepeatModeType {
+    return this._repeatMode
+  }
+
+  set repeatMode(mode: RepeatModeType) {
+    this._repeatMode = mode
+  }
+
+  get shuffleEnabled(): boolean {
+    return this._shuffleEnabled
+  }
+
+  setShuffleEnabled(enabled: boolean): void {
+    this._shuffleEnabled = enabled
+    if (enabled) this.regenerateShuffleOrder()
+  }
+
+  regenerateShuffleOrder(): void {
+    this.shuffleOrder = Array.from({ length: this._tracks.length }, (_, i) => i)
+    fisherYatesShuffle(this.shuffleOrder)
+
+    // Keep the current track at the front so navigation continues from it.
+    if (this._currentIndex === undefined) return
+    const currentPos = this.shuffleOrder.indexOf(this._currentIndex)
+    if (currentPos > 0) {
+      const first = assertedNotNullish(this.shuffleOrder[0])
+      this.shuffleOrder[0] = assertedNotNullish(this.shuffleOrder[currentPos])
+      this.shuffleOrder[currentPos] = first
+    }
+  }
+
+  // The shuffle order is maintained incrementally across mutations (matching
+  // iOS's ShuffleOrder and ExoPlayer's DefaultShuffleOrder) rather than
+  // regenerated: a regeneration re-randomizes the upcoming order and erases
+  // the played history, leaving previous() dead after any add/remove/move.
+
+  /** Shifts indices for an insertion and slots the new ones in at random positions. */
+  private shuffleOrderInsert(at: number, count: number): void {
+    if (!this._shuffleEnabled || count <= 0) return
+    this.shuffleOrder = this.shuffleOrder.map((idx) =>
+      idx >= at ? idx + count : idx
+    )
+    for (let i = 0; i < count; i++) {
+      const pos = Math.floor(Math.random() * (this.shuffleOrder.length + 1))
+      this.shuffleOrder.splice(pos, 0, at + i)
+    }
+  }
+
+  /** Drops removed indices and shifts the survivors down past them. */
+  private shuffleOrderRemove(removed: Set<number>): void {
+    if (!this._shuffleEnabled || removed.size === 0) return
+    const sorted = [...removed].sort((a, b) => a - b)
+    this.shuffleOrder = this.shuffleOrder
+      .filter((idx) => !removed.has(idx))
+      .map((idx) => idx - sorted.filter((r) => r < idx).length)
+  }
+
+  /** Remaps indices for a move, keeping every track's shuffle position. */
+  private shuffleOrderMove(fromIndex: number, toIndex: number): void {
+    if (!this._shuffleEnabled) return
+    this.shuffleOrder = this.shuffleOrder.map((idx) => {
+      if (idx === fromIndex) return toIndex
+      let adjusted = idx > fromIndex ? idx - 1 : idx
+      if (adjusted >= toIndex) adjusted += 1
+      return adjusted
+    })
+  }
+
+  // MARK: navigation
+
+  nextIndex(): number | undefined {
+    if (this._currentIndex === undefined) return undefined
+
+    if (!this._shuffleEnabled) {
+      const next = this._currentIndex + 1
+      return next >= this._tracks.length ? undefined : next
+    }
+
+    const pos = this.shuffleOrder.indexOf(this._currentIndex)
+    if (pos === -1) return undefined
+    const nextPos = pos + 1
+    return nextPos >= this.shuffleOrder.length
+      ? undefined
+      : this.shuffleOrder[nextPos]
+  }
+
+  previousIndex(): number | undefined {
+    if (this._currentIndex === undefined) return undefined
+
+    if (!this._shuffleEnabled) {
+      const prev = this._currentIndex - 1
+      return prev < 0 ? undefined : prev
+    }
+
+    const pos = this.shuffleOrder.indexOf(this._currentIndex)
+    if (pos === -1) return undefined
+    const prevPos = pos - 1
+    return prevPos < 0 ? undefined : this.shuffleOrder[prevPos]
+  }
+
+  wrapAroundFirstIndex(): number | undefined {
+    if (this._repeatMode !== RepeatMode.Queue) return undefined
+    return this._shuffleEnabled ? this.shuffleOrder[0] : 0
+  }
+
+  wrapAroundLastIndex(): number | undefined {
+    if (this._repeatMode !== RepeatMode.Queue) return undefined
+    return this._shuffleEnabled
+      ? this.shuffleOrder[this.shuffleOrder.length - 1]
+      : this._tracks.length - 1
+  }
+
+  // MARK: mutations
+
+  /** Inserts tracks at `insertBeforeIndex`, or appends when omitted/-1. */
+  insert(tracks: Track[], insertBeforeIndex?: number): void {
+    if (insertBeforeIndex !== -1 && insertBeforeIndex !== undefined) {
+      // Match Android/iOS, which throw here: a negative index other than the
+      // -1 sentinel would splice from the end and mis-shift the current
+      // pointer; past-the-end would silently append under a lying index.
+      if (insertBeforeIndex < 0 || insertBeforeIndex > this._tracks.length) {
+        throw new Error(
+          `insertBeforeIndex out of bounds: ${insertBeforeIndex} (use -1 to append)`
+        )
+      }
+      this._tracks.splice(insertBeforeIndex, 0, ...tracks)
+      // Keep the pointer on the same track (remove()/move() already do).
+      if (
+        this._currentIndex !== undefined &&
+        insertBeforeIndex <= this._currentIndex
+      ) {
+        this._currentIndex += tracks.length
+      }
+      this.shuffleOrderInsert(insertBeforeIndex, tracks.length)
+    } else {
+      this._tracks.push(...tracks)
+      this.shuffleOrderInsert(
+        this._tracks.length - tracks.length,
+        tracks.length
+      )
+    }
+  }
+
+  /**
+   * Removes the tracks at `indexes`, adjusting the current index. Returns what
+   * the caller must do for the current track (the queue itself never reloads).
+   */
+  remove(indexes: number[]): RemoveOutcome {
+    const idxSet = new Set(indexes)
+    const current = this._currentIndex
+    let removedBeforeCurrent = 0
+    let removedCurrent = false
+
+    this._tracks = this._tracks.filter((_track, idx) => {
+      if (!idxSet.has(idx)) return true
+      if (idx === current) removedCurrent = true
+      else if (current !== undefined && idx < current) removedBeforeCurrent++
+      return false
+    })
+    this.shuffleOrderRemove(idxSet)
+
+    if (current === undefined) return { kind: 'no-current' }
+
+    if (!removedCurrent) {
+      this._currentIndex = current - removedBeforeCurrent
+      return { kind: 'kept' }
+    }
+
+    if (this._tracks.length === 0) {
+      this._currentIndex = undefined
+      return { kind: 'emptied' }
+    }
+
+    // Reset so the caller's reload always loads the track at this position.
+    this._currentIndex = undefined
+    const adjusted = current - removedBeforeCurrent
+    // Wrap: removing the last-and-current track activates the first (the
+    // documented contract, matching iOS's modulo).
+    return { kind: 'reload', index: adjusted % this._tracks.length }
+  }
+
+  move(fromIndex: number, toIndex: number): void {
+    // Both ends are checked: an out-of-range destination would write a
+    // permanent out-of-range entry into the incrementally-maintained order.
+    const item = this._tracks[fromIndex]
+    if (item === undefined || toIndex < 0 || toIndex >= this._tracks.length) {
+      throw new Error('index out of bounds')
+    }
+
+    this._tracks.splice(fromIndex, 1)
+    this._tracks.splice(toIndex, 0, item)
+
+    // Track the current item's new position (matches Android's moveMediaItem).
+    const current = this._currentIndex
+    if (current !== undefined) {
+      if (fromIndex === current) this._currentIndex = toIndex
+      else if (fromIndex < current && toIndex >= current) {
+        this._currentIndex = current - 1
+      } else if (fromIndex > current && toIndex <= current) {
+        this._currentIndex = current + 1
+      }
+    }
+
+    this.shuffleOrderMove(fromIndex, toIndex)
+  }
+
+  /** Drops every track after the current one. */
+  removeUpcoming(): void {
+    if (this._currentIndex === undefined) return
+    const dropped = new Set<number>()
+    for (let i = this._currentIndex + 1; i < this._tracks.length; i++) {
+      dropped.add(i)
+    }
+    this._tracks = this._tracks.slice(0, this._currentIndex + 1)
+    this.shuffleOrderRemove(dropped)
+  }
+
+  /** Empties the queue and resets the index. */
+  clear(): void {
+    this._tracks = []
+    this._currentIndex = undefined
+    this._lastIndex = undefined
+    // Mutations maintain the order incrementally, so a stale order would
+    // survive the clear and corrupt the first post-clear insert.
+    this.shuffleOrder = []
+  }
+}

package/src/web/TrackPlayer/QueuePlayer.ts

@@ -0,0 +1,188 @@
+import type {
+  PlaybackState,
+  RepeatMode as RepeatModeType
+} from '../../features'
+import type { Track } from '../../types'
+import { Player } from './Player'
+import { QueueManager } from './QueueManager'
+import { RepeatMode } from './RepeatMode'
+import { State } from './State'
+
+/**
+ * A {@link Player} with a play queue. Owns the *orchestration* — advancing the
+ * queue on track end, loading the track when the index changes — while the
+ * queue data and index math live in {@link QueueManager}.
+ */
+export class QueuePlayer extends Player {
+  protected queue = new QueueManager()
+
+  protected applyState(state: PlaybackState) {
+    // A natural queue end exhausts the play intent — nothing is left to play.
+    // Keeping it set inverted togglePlayback (the first press after completion
+    // was a silent pause) and armed load()'s auto-play with phantom intent.
+    // Cleared before the state lands so consumers observe the native order
+    // (intent → state → queueEnded), independent of onQueueEnded overrides.
+    // Per-track ends that advance the queue keep the intent.
+    if (state === State.Ended && this.endsQueue()) {
+      this.playWhenReady = false
+    }
+
+    super.applyState(state)
+
+    // dispatch() already gates on _isStopped before reaching applyState, so a
+    // natural end while stopped never advances the queue.
+    if (state === State.Ended) {
+      this.onTrackEnded()
+    }
+  }
+
+  /** True when a natural end has nowhere to go: not repeating, no next track. */
+  private endsQueue(): boolean {
+    return (
+      this.queue.repeatMode !== RepeatMode.Track &&
+      this.queue.repeatMode !== RepeatMode.Queue &&
+      this.queue.nextIndex() === undefined
+    )
+  }
+
+  protected onTrackEnded() {
+    if (this.queue.repeatMode === RepeatMode.Track) {
+      if (this.queue.currentIndex !== undefined) {
+        this.goToIndex(this.queue.currentIndex)
+      }
+      return
+    }
+    if (this.endsQueue()) {
+      this.onQueueEnded()
+      return
+    }
+    this.skipToNext()
+  }
+
+  /**
+   * Notification hook for a natural queue end. The play intent is already
+   * cleared in {@link applyState} — this is purely for subclasses to react
+   * (e.g. emitting the queue-ended event).
+   */
+  protected onQueueEnded() {}
+
+  protected goToIndex(index: number, initialPosition?: number) {
+    const track = this.queue.getTrack(index)
+
+    if (!track) return
+
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const onLoaded = (_track: Track) => {
+      if (initialPosition !== undefined) {
+        this.seekTo(initialPosition)
+      }
+    }
+
+    if (this.queue.currentIndex !== index) {
+      this.queue.currentIndex = index
+      this.load(track, onLoaded)
+    } else if (this._isStopped) {
+      // The element is unloaded while stopped — a bare seek does nothing.
+      this.load(track, onLoaded)
+    } else {
+      // Replay the same track - seek to start (or initialPosition if specified)
+      this.seekTo(initialPosition ?? 0)
+      if (this.playWhenReady) {
+        this.play()
+      }
+    }
+  }
+
+  public add(tracks: Track[], insertBeforeIndex?: number): void {
+    this.queue.insert(tracks, insertBeforeIndex)
+
+    if (this.queue.currentIndex === undefined) {
+      this.goToIndex(0)
+    }
+  }
+
+  public skip(index: number, initialPosition?: number): void {
+    if (this.queue.getTrack(index) === undefined) {
+      throw new Error('index out of bounds')
+    }
+
+    this.goToIndex(index, initialPosition)
+  }
+
+  public skipToNext(initialPosition?: number): void {
+    if (this.queue.currentIndex === undefined) return
+
+    const nextIndex =
+      this.queue.nextIndex() ?? this.queue.wrapAroundFirstIndex()
+    if (nextIndex === undefined) return
+
+    this.goToIndex(nextIndex, initialPosition)
+  }
+
+  public skipToPrevious(initialPosition?: number): void {
+    if (this.queue.currentIndex === undefined) return
+
+    const previousIndex =
+      this.queue.previousIndex() ?? this.queue.wrapAroundLastIndex()
+    if (previousIndex === undefined) return
+
+    this.goToIndex(previousIndex, initialPosition)
+  }
+
+  public setShuffleEnabled(enabled: boolean): void {
+    this.queue.setShuffleEnabled(enabled)
+  }
+
+  public getShuffleEnabled(): boolean {
+    return this.queue.shuffleEnabled
+  }
+
+  public getTrack(index: number): Track | undefined {
+    return this.queue.getTrack(index)
+  }
+
+  public setRepeatMode(mode: RepeatModeType): void {
+    this.queue.repeatMode = mode
+  }
+
+  public getRepeatMode(): RepeatModeType {
+    return this.queue.repeatMode
+  }
+
+  public remove(indexes: number[]): void {
+    const outcome = this.queue.remove(indexes)
+    switch (outcome.kind) {
+      case 'no-current':
+      case 'kept':
+        break
+      case 'reload':
+        this.goToIndex(outcome.index)
+        break
+      case 'emptied':
+        this.current = undefined
+        this.stop()
+        break
+    }
+  }
+
+  public stop(onComplete?: () => void): void {
+    super.stop(onComplete)
+  }
+
+  public reset(): void {
+    // Clear queue state synchronously so subsequent add()/load() calls
+    // see a clean slate. The async player.unload() in stop() can finish
+    // in the background — it only releases the Shaka source.
+    this.queue.clear()
+    this.current = undefined
+    this.stop()
+  }
+
+  public removeUpcomingTracks(): void {
+    this.queue.removeUpcoming()
+  }
+
+  public move(fromIndex: number, toIndex: number): void {
+    this.queue.move(fromIndex, toIndex)
+  }
+}

package/src/web/TrackPlayer/RepeatMode.ts

@@ -3,5 +3,5 @@ import type { RepeatMode as RepeatModeType } from '../../features'
 export const RepeatMode = {
   Off: 'off' as const,
   Track: 'track' as const,
-  Playlist: 'queue' as const
+  Queue: 'queue' as const
 } satisfies Record<string, RepeatModeType>

package/src/web/TrackPlayer/SleepTimer.ts

@@ -2,12 +2,14 @@
  * Manages a sleep timer that calls a completion callback after a specified duration.
  *
  * The timer stores the expiration time as a timestamp and uses setTimeout to schedule the completion
- * callback. Supports both time-based and end-of-track modes.
+ * callback. Supports both time-based and end-of-track modes, plus an optional fade-out that starts
+ * `fadeDuration` seconds before the deadline so silence lands exactly when the timer completes.
  */
 export class SleepTimerManager {
   public time: number | null = null
   public sleepWhenPlayedToEnd: boolean = false
   private timeoutId: NodeJS.Timeout | null = null
+  private fadeTimeoutId: NodeJS.Timeout | null = null
 
   get isRunning(): boolean {
     return this.time !== null || this.sleepWhenPlayedToEnd
@@ -17,15 +19,28 @@ export class SleepTimerManager {
    * Sets a timer to complete after the specified number of seconds.
    *
    * @param seconds Number of seconds until the timer completes
+   * @param fadeDuration Seconds over which to fade out before completion; clamped to `seconds`
    */
-  sleepAfter(seconds: number): void {
+  sleepAfter(seconds: number, fadeDuration?: number): void {
     this.stopTimer()
+    this.onFadeCancel()
     this.sleepWhenPlayedToEnd = false
 
     this.timeoutId = setTimeout(() => {
       this.complete()
     }, seconds * 1000)
     this.time = Date.now() + seconds * 1000
+
+    if (fadeDuration !== undefined && fadeDuration > 0) {
+      const fade = Math.min(fadeDuration, seconds)
+      this.fadeTimeoutId = setTimeout(
+        () => {
+          this.fadeTimeoutId = null
+          this.onFadeStart(fade)
+        },
+        (seconds - fade) * 1000
+      )
+    }
   }
 
   /**
@@ -34,6 +49,7 @@ export class SleepTimerManager {
    */
   setToEndOfTrack(): void {
     this.stopTimer()
+    this.onFadeCancel()
     this.time = null
     this.sleepWhenPlayedToEnd = true
   }
@@ -46,6 +62,7 @@ export class SleepTimerManager {
   clear(): boolean {
     const wasRunning = this.isRunning
     this.stopTimer()
+    this.onFadeCancel()
     this.time = null
     this.sleepWhenPlayedToEnd = false
     return wasRunning
@@ -56,9 +73,23 @@ export class SleepTimerManager {
     // Default implementation does nothing - override in subclass
   }
 
+  /** Override to begin fading the volume; the timer still completes at its deadline. */
+  protected onFadeStart(_durationSeconds: number): void {
+    // Default implementation does nothing - override in subclass
+  }
+
+  /** Override to handle a fade cancelled before completion — restore the volume. */
+  protected onFadeCancel(): void {
+    // Default implementation does nothing - override in subclass
+  }
+
   private complete(): void {
     if (!this.isRunning) return
-    this.clear()
+    // Tear down without onFadeCancel: completion pauses first, then the
+    // completion handler restores the volume.
+    this.stopTimer()
+    this.time = null
+    this.sleepWhenPlayedToEnd = false
     this.onComplete()
   }
 
@@ -67,5 +98,9 @@ export class SleepTimerManager {
       clearTimeout(this.timeoutId)
       this.timeoutId = null
     }
+    if (this.fadeTimeoutId !== null) {
+      clearTimeout(this.fadeTimeoutId)
+      this.fadeTimeoutId = null
+    }
   }
 }

package/src/web/TrackPlayer/VolumeFader.ts

@@ -0,0 +1,74 @@
+/**
+ * Ramps the player volume down over a duration (sleep-timer fade). The gain
+ * follows a squared curve: loudness perception is logarithmic, so a linear
+ * gain ramp sounds like a late cutoff rather than a fade.
+ */
+export class VolumeFader {
+  private interval: NodeJS.Timeout | null = null
+
+  /**
+   * Volume captured when the fade started; restored after the fade resolves.
+   * Non-null from fade start until cancel/completion, even once the ramp has
+   * reached silence.
+   */
+  private preFadeVolume: number | null = null
+
+  constructor(
+    private getVolume: () => number,
+    private setVolume: (volume: number) => void
+  ) {}
+
+  get isActive(): boolean {
+    return this.preFadeVolume !== null
+  }
+
+  start(durationSeconds: number): void {
+    // If a fade is already running, keep its captured volume as the baseline —
+    // the current (partially faded) volume is not the value to restore.
+    const baseVolume = this.preFadeVolume ?? this.getVolume()
+    this.cancel(false)
+    this.preFadeVolume = baseVolume
+    if (durationSeconds <= 0) return
+
+    const startTime = Date.now()
+    this.interval = setInterval(() => {
+      const progress = Math.min(
+        1,
+        (Date.now() - startTime) / (durationSeconds * 1000)
+      )
+      this.setVolume(baseVolume * (1 - progress) ** 2)
+      if (progress >= 1 && this.interval !== null) {
+        clearInterval(this.interval)
+        this.interval = null
+      }
+    }, 50)
+  }
+
+  /**
+   * Stops the ramp. With `restoreVolume` the pre-fade volume is put back
+   * immediately (cancellation); without it the caller restores after pausing
+   * (completion path — restoring first would let full-volume audio slip out).
+   */
+  cancel(restoreVolume: boolean): void {
+    if (this.interval !== null) {
+      clearInterval(this.interval)
+      this.interval = null
+    }
+    const preFadeVolume = this.preFadeVolume
+    this.preFadeVolume = null
+    if (restoreVolume && preFadeVolume !== null) this.setVolume(preFadeVolume)
+  }
+
+  /**
+   * Resolves the fade around a halting action: stops the ramp, runs `halt`,
+   * then restores the pre-fade volume — in that order, because restoring
+   * before halting would let full-volume audio slip out. The restore is
+   * skipped when no fade was running.
+   */
+  resolve(halt: () => void): void {
+    const preFadeVolume = this.preFadeVolume
+    this.cancel(false)
+    halt()
+    if (preFadeVolume !== null) this.setVolume(preFadeVolume)
+  }
+}

package/src/web/TrackPlayer/index.ts

@@ -1,4 +1,5 @@
 export * from './Player'
-export * from './PlaylistPlayer'
+export * from './QueuePlayer'
 export * from './RepeatMode'
 export { SleepTimerManager } from './SleepTimer'
+export { VolumeFader } from './VolumeFader'