Creates an instance of the Playback class.
Throws an error if an invalid pan type is provided.
Optional _fadeOptional _fadeOptional _fadeOptional _loopPrivate Optional _mediaPromise that tracks an in-flight media-element .play() settlement.
Set when the media element's play() returns a pending promise; cleared
once that promise settles. Used by loopEnded to avoid racing source-state
mutations (seek/play) against the deferred state transition driven by
this promise.
Private _offsetPrivate _pitchDesired pitch-shift factor (1 = no shift, 2 = +1 octave, 0.5 = -1 octave). Stored even before the worklet node exists so a value set on a cleaned-up / not-yet-built playback is honoured once setPitchShift builds the node.
Private Optional _pitchThe phase-vocoder AudioWorkletNode (Laroche & Dolson 1999 peak-based
pitch-shift with Identity Phase-Locking) spliced into this playback's chain
between the filter tail and gainNode. undefined until
setPitchShift is first called with a factor != 1; lazily built via
cacophony.createPhaseVocoderNode. refreshFilters re-inserts it on
every chain rebuild so it is never bypassed.
Private _playbackPer-playback send-gain allocations: bus → allocated GainNode. Sounds
record send intent in Sound._sends (value-only), and the actual
GainNode lifecycle is owned here — allocated at preplay or
Sound.routeTo(bus, gain), torn down in cleanup.
Iterable Map (not WeakMap) so cleanup can walk every send and call
disconnect() on it; relying on GC for disconnect would leave the bus
graph holding the allocation indirectly.
Private _startPrivate _statePrivate Optional bufferPrivate contextOptional gainOptional pannerOptional sourceGets the duration of the audio in seconds.
The duration of the audio or NaN if the duration is unknown.
Throws an error if the sound has been cleaned up.
Whether a fade is currently in progress.
Gets the output node of this playback's audio graph. This is the final node in the internal chain before connection to destination. Use this to manually wire the playback into custom audio graphs.
The gain node that serves as the output of this playback.
Throws an error if the playback has been cleaned up.
// Manual routing through custom effects
const playback = sound.play()[0];
playback.disconnect(); // Disconnect from default destination
playback.connect(reverbNode).connect(context.destination);
The current pitch-shift factor (1 = no shift). See setPitchShift.
Gets the current playback rate of the audio.
Sets the playback rate of the audio.
Throws an error if the sound has been cleaned up or if the source type is unsupported.
Gets the position of the audio source in 3D space (HRTF panning only).
The [x, y, z] coordinates of the audio source.
Throws an error if the sound has been cleaned up or if HRTF panning is not used.
Sets the position of the audio source in 3D space (HRTF panning only).
The [x, y, z] coordinates of the audio source.
Throws an error if the sound has been cleaned up or if HRTF panning is not used.
Sets whether the audio source should loop.
Throws an error if the sound has been cleaned up.
Gets the stereo panning value.
The current stereo pan value, or null if stereo panning is not applicable.
Sets the stereo panning value.
The stereo pan value to set, between -1 (left) and 1 (right).
Throws an error if stereo panning is not available, if the sound has been cleaned up, or if the value is out of bounds.
Gets the 3D audio options if HRTF panning is used.
The current 3D audio options (HRTF variant).
Throws an error if the sound has been cleaned up or if HRTF panning is not used.
Sets the 3D audio options for HRTF panning. Accepts either a full ThreeDOptions value or a partial HRTF override. Any field omitted from the input is left at its current value on the underlying PannerNode.
Throws an error if the sound has been cleaned up or if HRTF panning is not used.
Private _runPrivate assertCreates a clone of the current Playback instance with optional overrides for certain properties. This method allows for the creation of a new Playback instance that shares the same audio context and source node but can have different settings such as loop count or pan type.
Throws an error if the sound has been cleaned up.
Configures a fade-out to be applied when the playback ends naturally (last loop iteration).
The fade-out duration in milliseconds.
Optional type: FadeTypeThe fade curve type. Defaults to "linear".
Connects this playback's output to an AudioNode or AudioParam. Follows the Web Audio API connection pattern.
The destination node (for chaining).
Throws an error if the playback has been cleaned up.
// Chain multiple effects
playback.connect(delay).connect(reverb).connect(context.destination);
Disconnects this playback's output from a specific destination or from all destinations.
Optional destination: AudioParam | AudioNodeOptional specific destination to disconnect from. If omitted, disconnects from all destinations.
Throws an error if the playback has been cleaned up.
// Disconnect from all
playback.disconnect();
// Disconnect from specific node
playback.disconnect(reverbNode);
Fades in from silence to the current volume. Optionally stores config to re-trigger the fade on each loop iteration.
The fade duration in milliseconds.
Optional type: FadeTypeThe fade curve type. Defaults to "linear".
Optional options: { Optional. Set perLoop: true to re-trigger fadeIn on each loop.
Optional perResolves when the fade completes.
Fades out from the current volume to silence.
The fade duration in milliseconds.
Optional type: FadeTypeThe fade curve type. Defaults to "linear".
Resolves when the fade completes.
Fades the volume to a target value, emitting fadeStart and fadeEnd events.
Sets or gets the loop count for the audio.
Optional loopCount: LoopCountThe number of times the audio should loop. 'infinite' for endless looping.
The loop count if no parameter is provided.
Throws an error if the sound has been cleaned up or if the source type is unsupported.
Remove event listener.
Register event listener.
Cleanup function
Private recreatePrivate refreshPrivate removeSets the pitch-shift factor for this playback, resurrecting the dormant phase-vocoder worklet (Jean Laroche & Mark Dolson, "New Phase-Vocoder Techniques for Pitch-Shifting, Harmonizing and Other Exotic Effects", 1999 IEEE WASPAA — peak-based pitch shift with Identity Phase-Locking).
On first use (factor !== 1) the phase-vocoder AudioWorkletNode is built via
cacophony.createPhaseVocoderNode and spliced into this playback's graph at
the refreshFilters seam (panner → [filters] → pitchShiftNode →
gainNode). The factor is forwarded to the node's pitchFactor AudioParam
(1 = no shift, 2 = +1 octave, 0.5 = -1 octave).
Pitch multiplier (> 0).
if the playback has been cleaned up or factor <= 0.
Private setupFades out then stops the playback.
The fade-out duration in milliseconds.
Optional type: FadeTypeThe fade curve type. Defaults to "linear".
Resolves when the fade completes and playback is stopped.
The base interface for any sound-producing entity, including individual sounds, groups, and playbacks. BaseSound