gapless.js

pnpm add gapless

import Queue from 'gapless';

const player = new Queue({
  tracks: [
    'https://example.com/set1-01.mp3',
    'https://example.com/set1-02.mp3',
    'https://example.com/set1-03.mp3',
  ],
  trackMetadata: [
    { title: 'Help on the Way' },
    { title: 'Slipknot!' },
    { title: 'Franklin\'s Tower' },
  ],
  onProgress: (track) => renderProgress(track.currentTime, track.duration),
  onStartNewTrack: (track) => renderNowPlaying(track.metadata?.title),
  onEnded: () => console.log('Show over'),
});

playButton.addEventListener('click', () => player.togglePlayPause());
nextButton.addEventListener('click', () => player.next());

use-player.ts

import { useEffect, useState, useSyncExternalStore } from 'react';
import Queue, { type TrackInfo } from 'gapless';

interface Snapshot {
  current?: TrackInfo;
  isPlaying: boolean;
}

class PlayerStore {
  queue: Queue | null = null;
  private snapshot: Snapshot = { isPlaying: false };
  private listeners = new Set<() => void>();

  constructor(private urls: string[]) {}

  subscribe = (fn: () => void) => {
    this.listeners.add(fn);
    return () => void this.listeners.delete(fn);
  };
  getSnapshot = () => this.snapshot;

  private sync = () => {
    const q = this.queue;
    if (!q) return;
    this.snapshot = { current: q.currentTrack, isPlaying: q.isPlaying };
    for (const fn of this.listeners) fn();
  };

  connect() {
    const queue = new Queue({
      tracks: this.urls,
      onProgress: this.sync,
      onStartNewTrack: this.sync,
      onEnded: this.sync,
    });
    this.queue = queue;
    return () => queue.destroy();
  }
}

export function usePlayer(urls: string[]) {
  const [store] = useState(() => new PlayerStore(urls));
  useEffect(() => store.connect(), [store]);
  const state = useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot);
  return { ...state, queue: store.queue };
}

AddTrackOptions

player.addTrack('https://example.com/encore.mp3', {
  // Skip the HEAD request used to resolve redirects, if the URL is already final.
  skipHEAD: true,
  metadata: { title: 'Ripple', artist: 'Grateful Dead' },
});

interface TrackInfo {
  index: number;            // Position in the queue
  currentTime: number;      // Seconds
  duration: number;         // Seconds, NaN until loaded
  isPlaying: boolean;
  isPaused: boolean;
  volume: number;
  playbackRate: number;
  trackUrl: string;         // Resolved URL, after redirects
  playbackType: 'HTML5' | 'WEBAUDIO';   // Which backend is making sound right now
  webAudioLoadingState: 'NONE' | 'LOADING' | 'LOADED' | 'ERROR';
  metadata?: TrackMetadata;
  machineState: string;     // Internal state, handy for debugging
}

interface TrackMetadata {
  title?: string;
  artist?: string;
  album?: string;
  artwork?: MediaImage[];   // [{ src, sizes, type }]
  [key: string]: unknown;   // Anything else you want to carry along
}

const player = new Queue({ tracks, preloadNumTracks: 1 });

player.preloadNumTracks = 0; // Disable preloading
player.preloadNumTracks = 3; // Preload 3 ahead

const player = new Queue({ tracks, playbackRate: 1.5 });

player.setPlaybackRate(2);
player.playbackRate; // 2

const player = new Queue({
  tracks,
  onPlayBlocked: () => showPlayButton(),
});