Audio

Sound is opt-in: pass sound: true to use the built-in audio. Enable it from a user gesture such as a click, because browsers block an AudioContext that starts without one. Each remove and restore phase owns an independent sound definition, so matching visuals do not have to share or reverse one audio track.

Enable and disable sound

const audible = new Disintegrator({ sound: true });
const silent = new Disintegrator();

effects.remove(element, { sound: true });

An operation-level value overrides the instance for that one call.

Supported sources

type SoundSource = string | URL | ArrayBuffer | AudioBuffer;

Strings and URL values are fetched and decoded lazily. ArrayBuffer is useful when the application already controls loading. AudioBuffer is the most direct reusable form when the application owns an AudioContext-based asset pipeline.

The library does not force bundled audio into source code as AudioBuffer: browser decoding is runtime work, and encoded files remain smaller and cacheable. Internally decoded results can still be reused.

Playback options

const sound = {
  src: new URL('/sounds/snap.ogg', location.href),
  gain: 0.35,
  delay: 40,
  duration: 700,
  fadeDuration: 120,
  playbackRate: 1.05,
};

effects.remove(element, { sound });

Custom player

Use a factory to integrate an existing audio engine.

const sound = ({ operation, element, signal }) => {
  const playback = audioEngine.play(operation === 'remove' ? 'card-out' : 'card-in');

  const stop = () => playback.stop();
  signal.addEventListener('abort', stop, { once: true });

  return {
    finished: playback.finished,
    stop,
    dispose() {
      signal.removeEventListener('abort', stop);
      playback.dispose();
    },
  };
};

The factory receives the operation, target element, and abort signal. Return stop() for cancellation and dispose() for unconditional cleanup.

Failure isolation

Autoplay restrictions, fetch failures, decode errors, and custom player exceptions never reject the visual operation solely because of audio. They are forwarded to onError; animation and the selected DOM action continue.