AudioEngine: Web Audio Playback and Stem Synchronization

// src/lib/audio/AudioEngine.ts

export const STEM_ORDER = ['vocals', 'guitar', 'strings', 'drums', 'bass', 'fx', 'other'] as const;

export class AudioEngine {
  constructor(options: EngineOptions = {})
}

interface EngineOptions {
  audioContext?: AudioContext;
  fetchArrayBuffer?: (url: string) => Promise<ArrayBuffer>;
  createPitchShiftNode?: (audioContext: AudioContext) => Promise<PitchShiftNodeLike>;
  driftCorrectionIntervalMs?: number;
  wait?: (milliseconds: number) => Promise<void>;
  decodeProfile?: DecodeProfile | null;
  createOfflineAudioContext?: (channels: number, length: number, sampleRate: number) => OfflineRenderContextLike;
  pitchTempoMode?: PitchTempoMode;
  createRenderedBuffer?: RenderedBufferFactory;
}

async loadSong(song: LoadableSong): Promise<void>

interface LoadableSong {
  id: string;
  title: string;
  stems: Array<{
    name: string;   // e.g. 'bass', 'drums', 'vocals'
    label: string;  // Display label, e.g. 'Bass'
    url: string;    // Absolute URL to the MP3 file
  }>;
}

async play(): Promise<void>

pause(): void

stop(): void

seek(time: number): void

setVolume(name: string, volume: number): void

setMuted(name: string, muted: boolean): void

setSolo(name: string, solo: boolean): void

async setTempoRatio(value: number): Promise<void>

async setGlobalTransposeSemitones(value: number): Promise<void>

async adjustGlobalTransposeSemitones(delta: number): Promise<void>

subscribe(listener: (snapshot: AudioEngineSnapshot) => void): () => void

getSnapshot(): AudioEngineSnapshot

destroy(): void

AudioBufferSourceNode (per stem)
  └── [PitchShiftNode (SoundTouch worklet, realtime mode only)]
      └── GainNode (per stem)
          └── AnalyserNode (per stem, for VU meter)
              └── masterGainNode (GainNode)
                  └── masterLimiterNode (DynamicsCompressorNode)
                      └── AudioContext.destination

export interface AudioEngineSnapshot {
  songId: string | null;
  title: string | null;
  globalTransposeSemitones: number;
  duration: number;
  position: number;
  tempoRatio: number;
  playing: boolean;
  loading: boolean;
  /** True while stems are being re-rendered offline after a transpose/tempo change. */
  rendering: boolean;
  /** Progress of the in-flight offline render (done of total stems). */
  renderProgress: { done: number; total: number };
  errors: string[];
  stems: Record<string, StemPlaybackState>;
}

export interface StemPlaybackState {
  name: string;
  label: string;
  url: string;
  loading: boolean;
  loaded: boolean;
  error: string | null;
  muted: boolean;
  solo: boolean;
  volume: number;
  effectiveGain: number;
  meterLevel: number;
  pitchAdjustable: boolean;
  effectivePitchSemitones: number;
  pitchShiftError: string | null;
}

const engine = new AudioEngine({
  audioContext: new FakeAudioContext() as unknown as AudioContext,
  fetchArrayBuffer: async (url) => fakeBuffers[url],
});