cacophony
    Preparing search index...

    Class Playback

    The base interface for any sound-producing entity, including individual sounds, groups, and playbacks. BaseSound

    Hierarchy

    • BasePlayback
      • Playback

    Implements

    Index
    constructor
    _effectChain? _fadeInConfig? _fadeOutConfig? _filters _isFading _loopEndCallback? _panType _sendGains _state currentLoop eventEmitter gainNode? loopCount origin panner? source?
    currentTime duration filters isFading isPaused isPlaying outputNode panType pitchShift playbackRate position sourceLoop stereoPan threeDOptions volume
    _addFilterEffect _addSourceEffect addEffect addFilter addFilters cancelFade cleanup clone configureFadeOut connect disconnect emit emitAsync emitPaused emitPlayStarted emitStopped fadeIn fadeOut fadeTo isFilterBypassed loop loopEnded markPaused markPlaying markStopped off on pause play rampEffectParam rampFilterParam removeFilter seek setEffectChainEndpoints setFilterBypassed setFilterOrder setGainNode setPannerNode setPanType setPitchShift stop stopWithFade

    Protected Optional_effectChain

    _effectChain?: EffectChain

    Optional_fadeInConfig

    _fadeInConfig?: {
        duration: number;
        perLoop: boolean;
        targetVolume: number;
        type: FadeType;
    }

    Optional_fadeOutConfig

    _fadeOutConfig?: { duration: number; type: FadeType }

    _filters

    _filters: BiquadFilterNode[] = []

    _isFading

    _isFading: boolean

    Optional_loopEndCallback

    _loopEndCallback?: () => void

    _panType

    _panType: PanType = "stereo"

    _sendGains

    _sendGains: Map<Bus, GainNode> = ...

    Per-playback send-gain allocations owned by the shared routing state machine. Cleanup disconnects every allocation deterministically.

    Protected_state

    _state: PlaybackState = "unplayed"
    currentLoop: number = 0
    eventEmitter: TypedEventEmitter<PlaybackEvents> = ...
    gainNode?: GainNode
    loopCount: LoopCount = 0
    origin: Sound
    panner?: PannerNode | StereoPannerNode
    source?: SourceNode
    • get duration(): number

      Gets the duration of the audio in seconds.

      Returns number

      The duration of the audio or NaN if the duration is unknown.

      Throws an error if the sound has been cleaned up.

    • get isFading(): boolean

      Returns boolean

    • get outputNode(): GainNode

      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.

      Returns GainNode

      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);
    • get playbackRate(): number

      Gets the current playback rate of the audio.

      Returns number

    • set playbackRate(rate: number): void

      Sets the playback rate of the audio.

      Parameters

      • rate: number

      Returns void

      Throws an error if the sound has been cleaned up or if the source type is unsupported.

    • get position(): Position

      Gets the position of the audio source in 3D space (HRTF panning only).

      Returns Position

      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.

    • set position(position: Position): void

      Sets the position of the audio source in 3D space (HRTF panning only).

      Parameters

      • position: Position

        The [x, y, z] coordinates of the audio source.

      Returns void

      Throws an error if the sound has been cleaned up or if HRTF panning is not used.

    • set sourceLoop(loop: boolean): void

      Sets whether the audio source should loop.

      Parameters

      • loop: boolean

      Returns void

      Throws an error if the sound has been cleaned up.

    • get stereoPan(): number | null

      Gets the stereo panning value.

      Returns number | null

      The current stereo pan value, or null if stereo panning is not applicable.

    • set stereoPan(value: number): void

      Sets the stereo panning value.

      Parameters

      • value: number

        The stereo pan value to set, between -1 (left) and 1 (right).

      Returns void

      Throws an error if stereo panning is not available, if the sound has been cleaned up, or if the value is out of bounds.

    _addFilterEffect

    _addSourceEffect

    • Cancels any in-progress fade, emitting fadeCancel if a fade was active.

      Returns void

    • Cleans up resources used by the Playback instance. This method should be called when the audio is no longer needed to free up resources.

      Returns void

    • Creates 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. The clone is connected to the origin Sound's primary route and registered with the Sound.

      Parameters

      • overrides: Partial<PlaybackCloneOverrides> = {}

      Returns Playback

      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).

      Parameters

      • duration: number

        The fade-out duration in milliseconds.

      • Optionaltype: FadeType

        The fade curve type. Defaults to "linear".

      Returns void

    • Connects this playback's output to an AudioNode or AudioParam. Follows the Web Audio API connection pattern.

      Parameters

      Returns AudioNode

      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.

      Parameters

      • Optionaldestination: AudioParam | AudioNode

        Optional specific destination to disconnect from. If omitted, disconnects from all destinations.

      Returns void

      Throws an error if the playback has been cleaned up.

      // Disconnect from all
      playback.disconnect();

      // Disconnect from specific node
      playback.disconnect(reverbNode);

    • Type Parameters

      • K extends "seek" | (keyof BaseAudioEvents)

      Parameters

      Returns void

    • Type Parameters

      • K extends "seek" | (keyof BaseAudioEvents)

      Parameters

      Returns Promise<void>

    • Parameters

      • isResume: boolean

      Returns void

    • Fades in from silence to the current volume. Optionally stores config to re-trigger the fade on each loop iteration.

      Parameters

      • duration: number

        The fade duration in milliseconds.

      • Optionaltype: FadeType

        The fade curve type. Defaults to "linear".

      • Optionaloptions: { perLoop?: boolean; startTime?: number }

        Optional. Set perLoop: true to re-trigger fadeIn on each loop.

      Returns Promise<void>

      Resolves when the fade completes.

    • Fades the volume to a target value, emitting fadeStart and fadeEnd events.

      Parameters

      • value: number
      • duration: number
      • type: FadeType = "linear"
      • Optionaloptions: { startTime?: number; startValue?: number }

      Returns Promise<void>

    • Sets or gets the loop count for the audio.

      Parameters

      • OptionalloopCount: LoopCount

        The number of times the audio should loop. 'infinite' for endless looping.

      Returns LoopCount

      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.

    • Handles the loop event when the audio ends. This method is bound to the 'onended' event of the audio source. It manages looping logic and restarts playback if necessary.

      Returns void

    • Remove event listener.

      Type Parameters

      • K extends "seek" | (keyof BaseAudioEvents)

      Parameters

      Returns void

    • Register event listener.

      Type Parameters

      • K extends "seek" | (keyof BaseAudioEvents)

      Parameters

      Returns () => void

      Cleanup function

    • Parameters

      • handle: AudioNode
      • paramName: string
      • value: number
      • Optionaloptions: { duration?: number; type?: FadeType }

      Returns void

    • Parameters

      Returns void

    • Sets 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 and added as an ordinary entry at the tail of the pre-panner effect chain: source → [filters] → phase vocoder → panner → gainNode. The factor is forwarded to the node's pitchFactor AudioParam (1 = no shift, 2 = +1 octave, 0.5 = -1 octave).

      Parameters

      • factor: number

        Pitch multiplier (> 0).

      Returns Promise<void>

      if the playback has been cleaned up or factor <= 0.

    • Fades out then stops the playback.

      Parameters

      • duration: number

        The fade-out duration in milliseconds.

      • Optionaltype: FadeType

        The fade curve type. Defaults to "linear".

      Returns Promise<void>

      Resolves when the fade completes and playback is stopped.

    Settings
    Member Visibility

    On This Page
    Constructors
    Properties
    Accessors
    Methods