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? panType position source? spatialSmoothingTau
    _spatialSmoothingActive currentTime duration filters isFading isPaused isPlaying occlusion outputNode pitchShift playbackRate sourceLoop state stereoPan supportsClipLoop threeDOptions volume
    _addFilterEffect _addSourceEffect _snapSpatialMotion _validateLoopCount _validateSpatialOptions 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 prepareSeek rampEffectParam rampFilterParam removeFilter scheduleStop seek setEffectChainEndpoints setFilterBypassed setFilterOrder setGainNode setLoopRegion setOcclusion 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

    _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
    panType: PanType
    position: Position

    Requested position target; initial poses are immediate, subsequent writes use spatialSmoothingTau.

    source?: SourceNode
    spatialSmoothingTau: number

    Spatial exponential time constant in seconds (default 0). Setting 0 snaps pending targets.

    _spatialSmoothingActive

    • get _spatialSmoothingActive(): boolean
      Internal

      Smooth only while a voice can be heard or resumed. Unplayed and stopped voices take poses immediately, so a replayed voice starts at its requested pose.

      Returns boolean

    • get currentTime(): number

      Current source position in seconds. Playing HTML media reports its observed cursor, including buffering stalls and native loop wraps. Buffer playback follows the render clock; idle and paused voices retain their committed offset.

      Returns number

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

      The last requested normalized occlusion amount, initially 0 (clear direct path).

      Returns number

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

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

      Gets the current lifecycle state without changing playback.

      Returns PlaybackState

    • get stereoPan(): number | null

      Requested stereo pan target, including during smoothing.

      Returns number | null

    • set stereoPan(value: number): void

      Parameters

      • value: number

      Returns void

    • get supportsClipLoop(): boolean

      Whether this live voice can enforce native buffer clip boundaries. HTML media cannot.

      Returns boolean

    _addFilterEffect

    _addSourceEffect

    _snapSpatialMotion

    • _snapSpatialMotion(): void
      Internal

      Snap pending spatial transitions to their requested targets.

      Returns void

    _validateLoopCount

    • _validateLoopCount(loopCount: LoopCount): void
      Internal

      Preflight Sound broadcasts and play options before any mutation.

      Parameters

      Returns void

    _validateSpatialOptions

    • _validateSpatialOptions(options: SpatialOptions): void
      Internal

      Validate a spatial write without changing the voice.

      Parameters

      • options: SpatialOptions

      Returns void

    • 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

    • Silently prepares an idle or paused voice at a finite offset in seconds. Buffers resolve immediately. Media elements wait for metadata, a seekable range containing the target, and completed seeking with current audio data. No play(), context resume, or autoplay primer is performed. State is retained. A later preparation, play, seek, stop, or cleanup rejects pending work with AbortError. Cancellation does not roll back a browser seek already requested. Live/unknown-duration media rejects with NotSupportedError; readiness timeout rejects with TimeoutError. Browser media seeking is not sample accurate.

      Parameters

      Returns Promise<void>

    • Parameters

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

      Returns void

    • Parameters

      Returns void

    • End this started buffer activation at an absolute AudioContext time. A deadline before a future onset prevents all onset audio. Past deadlines stop now. Rate changes do not move this render-clock deadline. A later call replaces it; pause, seek, source recreation, stop and cleanup revoke it. Downstream effect tails remain. Legacy numeric repeats and ended-time fade-outs cannot share this per-source deadline.

      Parameters

      • atAudioSeconds: number

      Returns void

    • Configure a hard clip end and native loop points, in Sound-relative seconds. Configure while idle or paused. loop(0) ends at R; loop("infinite") wraps R to L. Numeric repeats and per-loop fades are unsupported with explicit bounds.

      Parameters

      • startSeconds: number
      • endSeconds: number

      Returns void

    • Renders obstruction for this voice independently of volume, fades, and positioning. The caller owns geometry, materials, and policy; Cacophony only renders the amount. Finite amounts clamp to [0, 1]; non-finite amounts throw RangeError. A dedicated pre-panner low-pass opens to Nyquist at 0 and closes logarithmically to 800 Hz at 1, with attenuation from 0 to -18 dB. Resetting to 0 is transparent. Nodes are allocated on the first nonzero amount and reused, including after reset.

      Parameters

      • amount: number

        0 for a clear path, 1 for maximum obstruction.

      • duration: number = 50

        Linear transition duration in milliseconds, default 50; 0 applies immediately.

      Returns void

      For a non-finite amount or a negative/non-finite duration.

      If this playback has been cleaned up.

    • 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