WaaPlayer

WaaPlayer provides a unified, class-based interface that wraps all waa-play modules. It manages its own AudioContext internally.

import { WaaPlayer } from "waa-play";

Constructor

new WaaPlayer();
new WaaPlayer(ctx: AudioContext);
new WaaPlayer(options: WaaPlayerOptions);

Create a new WaaPlayer instance. You can optionally pass an existing AudioContext or an options object.

// Use default AudioContext
const player = new WaaPlayer();

// Provide your own AudioContext
const ctx = new AudioContext({ sampleRate: 48000 });
const player = new WaaPlayer(ctx);

// Pass options for AudioContext creation
const player = new WaaPlayer({ sampleRate: 48000 });

Properties

ctx

readonly ctx: AudioContext;

The underlying AudioContext instance.

Context Methods

resume()

resume(): Promise<void>;

Resume the suspended AudioContext. Equivalent to resumeContext(ctx).

ensureRunning()

ensureRunning(): Promise<void>;

Ensure the AudioContext is in the running state.

now()

now(): number;

Returns the current time of the AudioContext (ctx.currentTime).

Buffer Methods

load()

load(url: string, options?: LoadBufferOptions): Promise<AudioBuffer>;

Fetch and decode an audio file from a URL.

const buffer = await player.load("/audio/track.mp3", {
  onProgress: (p) => console.log(`${Math.round(p * 100)}%`),
});

loadFromBlob()

loadFromBlob(blob: Blob): Promise<AudioBuffer>;

Decode an AudioBuffer from a Blob or File.

loadAll()

loadAll(map: Record<string, string>): Promise<Map<string, AudioBuffer>>;

Load multiple audio files in parallel.

const buffers = await player.loadAll({
  kick: "/audio/kick.wav",
  snare: "/audio/snare.wav",
});

getBufferInfo()

getBufferInfo(buffer: AudioBuffer): BufferInfo;

Get metadata about an AudioBuffer (duration, channels, sampleRate, length).

Playback

play()

play(buffer: AudioBuffer, options?: PlayOptions): Playback;

Play an AudioBuffer. Returns a controllable Playback handle.

const playback = player.play(buffer, {
  offset: 10,
  loop: true,
  playbackRate: 1.5,
});

See play module for PlayOptions and Playback details.

Node Factories

createGain()

createGain(initialValue?: number): GainNode;

createAnalyser()

createAnalyser(options?: { fftSize?: number; smoothingTimeConstant?: number }): AnalyserNode;

createFilter()

createFilter(options?: { type?: BiquadFilterType; frequency?: number; Q?: number; gain?: number }): BiquadFilterNode;

createPanner()

createPanner(pan?: number): StereoPannerNode;

createCompressor()

createCompressor(options?: { threshold?: number; knee?: number; ratio?: number; attack?: number; release?: number }): DynamicsCompressorNode;

rampGain()

rampGain(gain: GainNode, target: number, duration: number): void;

Smooth linear ramp of a GainNode’s value.

getFrequencyData()

getFrequencyData(analyser: AnalyserNode): Float32Array;

getFrequencyDataByte()

getFrequencyDataByte(analyser: AnalyserNode): Uint8Array;

chain()

chain(...nodes: AudioNode[]): void;

Connect audio nodes in series.

disconnectChain()

disconnectChain(...nodes: AudioNode[]): void;

Disconnect previously chained nodes.

Waveform

extractPeaks()

extractPeaks(buffer: AudioBuffer, options?: ExtractPeaksOptions): number[];

Extract normalized peak amplitudes [0, 1] from an AudioBuffer.

extractPeakPairs()

extractPeakPairs(buffer: AudioBuffer, options?: ExtractPeaksOptions): PeakPair[];

Extract min/max peak pairs for waveform rendering.

extractRMS()

extractRMS(buffer: AudioBuffer, options?: ExtractPeaksOptions): number[];

Extract RMS loudness values [0, 1].

Fade

fadeIn()

fadeIn(gain: GainNode, target: number, options?: FadeOptions): void;

fadeOut()

fadeOut(gain: GainNode, options?: FadeOptions): void;

crossfade()

crossfade(gainA: GainNode, gainB: GainNode, options?: CrossfadeOptions): void;

autoFade()

autoFade(playback: Playback, gain: GainNode, options?: AutoFadeOptions): () => void;

Automatically apply fade-in on play and fade-out before end. Returns a cleanup function.

Scheduler

createScheduler()

createScheduler(options?: SchedulerOptions): Scheduler;

createClock()

createClock(options?: ClockOptions): Clock;

Synth

createSineBuffer()

createSineBuffer(frequency: number, duration: number): AudioBuffer;

createNoiseBuffer()

createNoiseBuffer(duration: number): AudioBuffer;

createClickBuffer()

createClickBuffer(frequency: number, duration: number): AudioBuffer;

Adapters

getSnapshot()

getSnapshot(playback: Playback): PlaybackSnapshot;

subscribeSnapshot()

subscribeSnapshot(playback: Playback, callback: (snap: PlaybackSnapshot) => void): () => void;

onFrame()

onFrame(playback: Playback, callback: (snap: PlaybackSnapshot) => void): () => void;

whenEnded()

whenEnded(playback: Playback): Promise<void>;

whenPosition()

whenPosition(playback: Playback, position: number): Promise<void>;

Lifecycle

dispose()

dispose(): void;

Close the AudioContext and release all resources. The instance should not be used after calling dispose().