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

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'