Class Playback

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

Hierarchy

  • BasePlayback
    • Playback

Implements

Constructors

constructor

Properties

_fadeInConfig? _fadeOutConfig? _fadeTimeout? _filters _isFading _offset _panType _playbackRate _playing _startTime _state buffer? context currentLoop eventEmitter gainNode? loopCount origin panner? source?

Accessors

currentTime duration filters isFading isPlaying outputNode panType playbackRate position sourceLoop stereoPan threeDOptions volume

Methods

addFilter addFilters applyFilters assertNotCleanedUp cancelFade cleanup clone configureFadeOut connect disconnect emit emitAsync fadeIn fadeOut fadeTo loop loopEnded off on pause play recreateSource refreshFilters removeFilter removeFilters seek setGainNode setPanType setPannerNode setupSourceNode stop stopWithFade

Constructors

constructor

  • new Playback(origin, source, gainNode): Playback

  • Creates an instance of the Playback class.

    Parameters

    • origin: Sound

      The Sound instance that the Playback is associated with.

    • source: SourceNode

      The audio source node.

    • gainNode: GainNode

      The gain node for controlling volume.

    Returns Playback

    Throws

    Throws an error if an invalid pan type is provided.

Properties

Optional _fadeInConfig

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

Type declaration

  • duration: number
  • perLoop: boolean
  • targetVolume: number
  • type: FadeType

Optional _fadeOutConfig

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

Type declaration

Optional _fadeTimeout

_fadeTimeout?: Timeout

_filters

_filters: BiquadFilterNode[] = []

_isFading

_isFading: boolean = false

Private _offset

_offset: number = 0

_panType

_panType: PanType = 'stereo'

Private _playbackRate

_playbackRate: number = 1

_playing

_playing: boolean = false

Private _startTime

_startTime: number = 0

Private _state

_state: PlaybackState = PlaybackState.Unplayed

Private Optional buffer

buffer?: IAudioBuffer

Private context

context: IAudioContext

currentLoop

currentLoop: number = 0

eventEmitter

eventEmitter: TypedEventEmitter<PlaybackEvents> = ...

Optional gainNode

gainNode?: GainNode

loopCount

loopCount: LoopCount = 0

origin

origin: Sound

The Sound instance that the Playback is associated with.

Optional panner

panner?: PannerNode | StereoPannerNode

Optional source

source?: SourceNode

Accessors

currentTime

duration

  • 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

    Throws an error if the sound has been cleaned up.

filters

  • get filters(): BiquadFilterNode[]

  • Returns BiquadFilterNode[]

isFading

  • get isFading(): boolean

  • Whether a fade is currently in progress.

    Returns boolean

isPlaying

outputNode

  • 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

    Throws an error if the playback has been cleaned up.

    Example

    // Manual routing through custom effects
    const playback = sound.play()[0];
    playback.disconnect(); // Disconnect from default destination
    playback.connect(reverbNode).connect(context.destination);

panType

playbackRate

  • get playbackRate(): number

  • Gets the current playback rate of the audio.

    Returns number

    The current playback rate.

  • set playbackRate(rate): void

  • Sets the playback rate of the audio.

    Parameters

    • rate: number

      The playback rate to set.

    Returns void

    Throws

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

position

  • 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

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

  • set 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

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

sourceLoop

  • set sourceLoop(loop): void

  • Sets whether the audio source should loop.

    Parameters

    • loop: boolean

      Whether the audio should loop.

    Returns void

    Throws

    Throws an error if the sound has been cleaned up.

stereoPan

  • get stereoPan(): null | number

  • Gets the stereo panning value.

    Returns null | number

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

    Throws

    Throws an error if stereo panning is not available or if the sound has been cleaned up.

  • set stereoPan(value): void

  • Sets the stereo panning value.

    Parameters

    • value: number

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

    Returns void

    Throws

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

threeDOptions

  • get threeDOptions(): PannerOptions

  • Gets the 3D audio options if HRTF panning is used.

    Returns PannerOptions

    The current 3D audio options.

    Throws

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

  • set threeDOptions(options): void

  • Sets the 3D audio options for HRTF panning.

    Parameters

    • options: Partial<PannerOptions>

      The 3D audio options to set.

    Returns void

    Throws

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

volume

  • get volume(): number

  • Gets the current volume of the audio.

    Returns number

    The current volume.

    Throws

    Throws an error if the sound has been cleaned up.

  • set volume(v): void

  • Sets the volume of the audio.

    Parameters

    • v: number

      The volume to set.

    Returns void

    Throws

    Throws an error if the sound has been cleaned up.

Methods

addFilter

addFilters

  • addFilters(filters): void

  • Parameters

    • filters: BiquadFilterNode[]

    Returns void

applyFilters

  • applyFilters(connection): any

  • Parameters

    • connection: any

    Returns any

Private assertNotCleanedUp

cancelFade

  • cancelFade(): void

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

    Returns void

cleanup

  • cleanup(): 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

clone

  • clone(overrides?): Playback

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

    Parameters

    • overrides: Partial<PlaybackCloneOverrides> = {}

      An object containing properties to override in the cloned instance.

    Returns Playback

    A new Playback instance cloned from the current one with the specified overrides applied.

    Throws

    Throws an error if the sound has been cleaned up.

configureFadeOut

  • configureFadeOut(duration, type?): void

  • Configures a fade-out to be applied when the playback ends naturally (last loop iteration).

    Parameters

    • duration: number

      The fade-out duration in milliseconds.

    • Optional type: FadeType

      The fade curve type. Defaults to "linear".

    Returns void

connect

  • connect(destination): AudioNode

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

    Parameters

    • destination: AudioNode | AudioParam

      The node or param to connect to.

    Returns AudioNode

    The destination node (for chaining).

    Throws

    Throws an error if the playback has been cleaned up.

    Example

    // Chain multiple effects
    playback.connect(delay).connect(reverb).connect(context.destination);

disconnect

  • disconnect(destination?): void

  • Disconnects this playback's output from a specific destination or from all destinations.

    Parameters

    • Optional destination: AudioNode | AudioParam

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

    Returns void

    Throws

    Throws an error if the playback has been cleaned up.

    Example

    // Disconnect from all
    playback.disconnect();

    Example

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

emit

emitAsync

fadeIn

  • fadeIn(duration, type?, options?): Promise<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.

    • Optional type: FadeType

      The fade curve type. Defaults to "linear".

    • Optional options: {
          perLoop?: boolean;
      }

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

      • Optional perLoop?: boolean

    Returns Promise<void>

    Resolves when the fade completes.

fadeOut

  • fadeOut(duration, type?): Promise<void>

  • Fades out from the current volume to silence.

    Parameters

    • duration: number

      The fade duration in milliseconds.

    • Optional type: FadeType

      The fade curve type. Defaults to "linear".

    Returns Promise<void>

    Resolves when the fade completes.

fadeTo

  • fadeTo(value, duration, type?): Promise<void>

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

    Parameters

    • value: number
    • duration: number
    • type: FadeType = "linear"

    Returns Promise<void>

loop

  • loop(loopCount?): LoopCount

  • Sets or gets the loop count for the audio.

    Parameters

    • Optional loopCount: LoopCount

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

    Returns LoopCount

    The loop count if no parameter is provided.

    Throws

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

loopEnded

  • loopEnded(): void

  • 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

off

  • off<K>(event, listener): void

  • Remove event listener.

    Type Parameters

    Parameters

    • event: K
    • listener: ((data) => void)

    Returns void

on

  • on<K>(event, listener): void

  • Register event listener.

    Type Parameters

    Parameters

    • event: K
    • listener: ((data) => void)

    Returns void

    Cleanup function

pause

play

  • play(): [Playback]

  • Starts playing the audio.

    Returns [Playback]

    Returns the instance of the Playback class for chaining.

    Throws

    Throws an error if the sound has been cleaned up.

Private recreateSource

Private refreshFilters

  • refreshFilters(): void

  • Refreshes the audio filters by re-applying them to the audio signal chain. This method is called internally whenever filters are added or removed.

    Returns void

    Throws

    Throws an error if the sound has been cleaned up.

removeFilter

removeFilters

  • removeFilters(filters): void

  • Parameters

    • filters: BiquadFilterNode[]

    Returns void

seek

setGainNode

  • setGainNode(gainNode): void

  • Parameters

    • gainNode: GainNode

    Returns void

setPanType

  • setPanType(panType, audioContext): void

  • Parameters

    • panType: PanType
    • audioContext: IAudioContext

    Returns void

setPannerNode

  • setPannerNode(pannerNode): void

  • Parameters

    • pannerNode: PannerNode

    Returns void

Private setupSourceNode

  • setupSourceNode(source): void

  • Parameters

    • source: SourceNode

    Returns void

stop

stopWithFade

  • stopWithFade(duration, type?): Promise<void>

  • Fades out then stops the playback.

    Parameters

    • duration: number

      The fade-out duration in milliseconds.

    • Optional type: FadeType

      The fade curve type. Defaults to "linear".

    Returns Promise<void>

    Resolves when the fade completes and playback is stopped.

Settings

Member Visibility

Theme

On This Page

constructor_fadeInConfig_fadeOutConfig_fadeTimeout_filters_isFading_offset_panType_playbackRate_playing_startTime_statebuffercontextcurrentLoopeventEmittergainNodeloopCountoriginpannersourcecurrentTimedurationfiltersisFadingisPlayingoutputNodepanTypeplaybackRatepositionsourceLoopstereoPanthreeDOptionsvolumeaddFilteraddFiltersapplyFiltersassertNotCleanedUpcancelFadecleanupcloneconfigureFadeOutconnectdisconnectemitemitAsyncfadeInfadeOutfadeTolooploopEndedoffonpauseplayrecreateSourcerefreshFiltersremoveFilterremoveFiltersseeksetGainNodesetPanTypesetPannerNodesetupSourceNodestopstopWithFade