cacophony 0.32.1 → 0.34.0

package/README.md

@@ -19,36 +19,36 @@ Cacophony is a powerful and intuitive audio library designed for modern web appl
 ## Installation
 
 ```bash
-npm install cacophony
-```
-
-## Bundling and lazy loading
-
-Use named ESM imports so your bundler can discard unused modules:
-
-```typescript
-import { AudioCache } from 'cacophony';
-```
-
-The package preserves its module boundaries and declares import side effects.
-Importing `AudioCache` or an individual effect does not pull in the full
-`Cacophony` class or the offline FFT implementation. The `Cacophony` class keeps
-its complete factory API, so importing that class still includes the code its
-methods reference.
-
-`createStream()` loads MediaBunny on demand when using the WebCodecs transport.
-HLS streams and browsers without `AudioDecoder` take their existing fallback
-paths without loading it. Each AudioWorklet payload loads when its processor is
-first needed. Call `await audio.loadWorklets()` to preload all processors.
-
-Consumer bundlers must support code splitting to keep these imports in separate
-downloadable chunks. Deploy all generated chunks with the application. MediaBunny
-remains an installed dependency; lazy loading defers its runtime load.
-
-Run `npm run build` followed by `npm run check:bundles -- --report` to inspect
-initial bundle sizes for cache-only, full-factory, and single-effect consumers.
-
-## Quick Start
+npm install cacophony
+```
+
+## Bundling and lazy loading
+
+Use named ESM imports so your bundler can discard unused modules:
+
+```typescript
+import { AudioCache } from 'cacophony';
+```
+
+The package preserves its module boundaries and declares import side effects.
+Importing `AudioCache` or an individual effect does not pull in the full
+`Cacophony` class or the offline FFT implementation. The `Cacophony` class keeps
+its complete factory API, so importing that class still includes the code its
+methods reference.
+
+`createStream()` loads MediaBunny on demand when using the WebCodecs transport.
+HLS streams and browsers without `AudioDecoder` take their existing fallback
+paths without loading it. Each AudioWorklet payload loads when its processor is
+first needed. Call `await audio.loadWorklets()` to preload all processors.
+
+Consumer bundlers must support code splitting to keep these imports in separate
+downloadable chunks. Deploy all generated chunks with the application. MediaBunny
+remains an installed dependency; lazy loading defers its runtime load.
+
+Run `npm run build` followed by `npm run check:bundles -- --report` to inspect
+initial bundle sizes for cache-only, full-factory, and single-effect consumers.
+
+## Quick Start
 
 ```typescript
 import { Cacophony } from 'cacophony';
@@ -81,6 +81,37 @@ async function audioDemo() {
 audioDemo();
 ```
 
+## Per-playback occlusion
+
+Apply obstruction to an individual `Playback` using a normalized amount:
+
+```typescript
+const [voice] = sound.play({ panType: 'HRTF', position: [5, 0, 0] });
+voice.setOcclusion(0.7);      // Smooth transition over 50 ms by default.
+voice.setOcclusion(0, 100);   // Restore the clear path over 100 ms.
+console.log(voice.occlusion); // Last requested amount, independent of transition progress.
+```
+
+The caller computes the amount and owns geometry, materials, and policy.
+Cacophony renders it with a dedicated low-pass and attenuation stage after user
+effects and before the panner. Finite amounts clamp to `[0, 1]`; non-finite
+amounts throw `RangeError`. The optional transition duration is in milliseconds:
+`0` applies immediately; negative or non-finite durations throw `RangeError`.
+
+At `0`, the low-pass opens to the context's Nyquist frequency and attenuation
+returns to unity, restoring the unobstructed response. At `1`, the low-pass
+cutoff is 800 Hz (limited to Nyquist on lower-rate contexts) and attenuation is
+-18 dB. Intermediate amounts map logarithmically to cutoff and linearly in
+decibels to attenuation. The filter has a Butterworth response without a resonant
+peak. Changes use linear AudioParam ramps, cancelling and re-anchoring any prior
+occlusion transition at its current value.
+
+Occlusion leaves ordinary volume and fades independent. Each voice starts clear;
+updates affect only that voice. Pause/resume and panner changes retain its
+occlusion, and `Playback.clone()` copies the requested amount into independent
+nodes. One lazily allocated filter/gain pair is reused even after resetting to
+`0`, then disconnected on cleanup. Updating a cleaned-up playback throws.
+
 ## Mobile Autoplay Handling
 
 Modern browsers — especially iOS Safari and Chrome on Android — refuse to
@@ -118,6 +149,92 @@ const cacophony = new Cacophony(undefined, undefined, { autoUnlock: false });
 The auto-unlock has no effect on offline contexts or in non-browser
 environments (`typeof document === 'undefined'`).
 
+## Mobile Robustness and Audio Sessions
+
+By default, browser instances observe context `statechange` and emit `suspend`,
+`resume`, or `interrupted` once per transition, including changes initiated by
+the platform or by code using the context directly. Construction does not emit
+an initial state event. A gesture unlock therefore emits `resume` along with
+`unlock`. Once the context has run, `autoRecover` attempts silent resume after
+suspension or interruption only while the document is visible, and retries on
+`visibilitychange`, `pageshow`, and window `focus`. A context that has never run
+(blocked by autoplay policy) is left to the gesture unlock, so `unlock` still fires
+on the first interaction. It does not suspend audio merely because the page
+is hidden. Failed recovery is logged through the instance logger; the existing
+gesture unlock remains available when the browser requires interaction.
+
+`await cacophony.pause()` records user intent before suspending. Neither automatic
+recovery nor subsequent gestures undo that pause; call `await cacophony.resume()`
+to continue. This also protects pauses made while a recovery attempt is pending.
+Set `{ autoRecover: false }` to disable browser session and device-list listeners.
+`autoUnlock` controls gesture handling separately; disable both to manage all
+recovery yourself. Offline and non-browser contexts install no session listeners.
+
+```typescript
+const cacophony = new Cacophony();
+cacophony.on('interrupted', () => showAudioStatus('Audio interrupted'));
+cacophony.on('resume', () => showAudioStatus('Audio running'));
+cacophony.on('devicechange', ({ devices }) => updateOutputPicker(devices));
+cacophony.on('sinkChange', ({ sinkId }) => showSelectedOutput(sinkId));
+
+// When the instance is no longer needed:
+cacophony.dispose(); // Removes platform and gesture listeners and event subscriptions.
+await cacophony.context.close?.(); // The caller owns context and sound cleanup.
+```
+
+`devicechange` carries `{ devices: MediaDeviceInfo[], timestamp: number }`, with
+only `audiooutput` devices. Enumeration does not request permission; labels and
+the device list may be restricted. Failed enumeration is logged and emits no
+partial result. Closing the context also removes browser session, sink, and gesture
+listeners when `autoRecover` is enabled; your event subscriptions stay attached
+until `dispose()`. `sinkChange` reports the active sink independently of
+the available device list; neither event selects a replacement automatically.
+
+Automated tests cover native context transitions and synthetic device-list
+notifications. Real hardware and OS interruptions require this manual matrix:
+
+| Platform | Action | Expected result |
+| --- | --- | --- |
+| iOS Safari | Interrupt playback with a call or Siri, then return | `interrupted`/`suspend` when reported by the OS; visible-page recovery or gesture unlock restores audio |
+| Android Chrome | Unplug headphones during playback | Device-list notification when delivered; context transitions are observable and recovery is attempted |
+| Both | Background and foreground the page | No forced background suspension; retry on foreground if the context needs recovery |
+| Both | Pause explicitly, then repeat these actions and tap | Audio remains paused until the app calls `resume()` |
+
+## Output Device Selection
+
+`setOutputDevice(sinkId)` delegates to the supplied context's runtime `setSinkId`
+capability. `outputDevice` reads its current sink: `''` means the system default,
+a device id selects that output, and `{ type: 'none' }` selects silent processing.
+The same API works with the Node backend; its constructor `sinkId` option remains
+available. Switching does not recreate the context or audio graph.
+
+```typescript
+// Run from a user action. selectAudioOutput is optional and browser-dependent.
+const mediaDevices = navigator.mediaDevices as MediaDevices & {
+  selectAudioOutput?: () => Promise<MediaDeviceInfo>;
+};
+if (mediaDevices.selectAudioOutput) {
+  const output = await mediaDevices.selectAudioOutput();
+  await cacophony.setOutputDevice(output.deviceId);
+}
+await cacophony.setOutputDevice(''); // Return to the system default.
+```
+
+Concrete device selection requires a secure context and any permissions required
+by the platform; obtaining authorized ids (through `selectAudioOutput` or permitted
+`enumerateDevices`/`getUserMedia`) belongs to the app. Platform errors such as
+`NotAllowedError` and `NotFoundError` propagate unchanged. Unsupported real-time
+contexts reject with `Error("Output device selection is not supported by this context")`
+until the shared typed-error API in #169 lands. Offline selection is a no-op and
+`outputDevice` is `undefined`.
+
+Support is detected on the actual context, never inferred from a browser name.
+Native Chromium supports selection; Safari and Firefox versions lacking
+`AudioContext.setSinkId` reject it. Standardized-audio-context wrappers that do
+not expose `setSinkId` are unsupported even when the native browser supports it.
+See [Chrome's output-selection guide](https://developer.chrome.com/blog/audiocontext-setsinkid/)
+for platform permissions and silent-sink behavior.
+
 ## Core Concepts
 
 ### Sound vs Playback Architecture
@@ -127,30 +244,30 @@ Cacophony uses a two-tier architecture that separates audio assets from their pl
 - **Sound**: Represents an audio asset (file or buffer). Acts as a container managing multiple playback instances.
 - **Playback**: Represents a single playback instance of a Sound. Each call to `play()` creates a new Playback.
 
-This design allows the same sound to be played multiple times simultaneously with different settings (volume, position, playback rate, etc.).
-
-Pass invocation settings to `play(options)` to configure each voice before audio
-starts. Omitted values inherit source defaults; `0` is valid for volume, stereo
-pan, and loop count. Sound defaults and overlapping voices stay independent.
-
-```typescript
-const [voice] = sound.play({ volume: 0.5, playbackRate: 1.2, loopCount: 0,
-  panType: 'stereo', stereoPan: 0 });
-const step = group.playOrdered(true, { volume: 0.7, panType: 'HRTF',
-  position: [10, 0, 5], threeDOptions: { distanceModel: 'linear', rolloffFactor: 0.1 } });
-```
-
-`stereoPan` requires the effective stereo mode; `position` and `threeDOptions`
-require HRTF. Partial HRTF options preserve unspecified settings. Group all,
-random, and ordered playback and sprite children accept these same options.
-Invalid options throw before voice preparation, and group playback preflights
-every member. Direct `Playback.play(options)` also supports these settings,
-scheduling, and fades. Calling play on an already playing voice remains a no-op
-after validation.
-
-Synths and live streams support volume, spatial settings, and fade-in. They
-reject playback rate, loop count, scheduled starts, end fades, and per-loop fade
-settings because these sources do not support those controls.
+This design allows the same sound to be played multiple times simultaneously with different settings (volume, position, playback rate, etc.).
+
+Pass invocation settings to `play(options)` to configure each voice before audio
+starts. Omitted values inherit source defaults; `0` is valid for volume, stereo
+pan, and loop count. Sound defaults and overlapping voices stay independent.
+
+```typescript
+const [voice] = sound.play({ volume: 0.5, playbackRate: 1.2, loopCount: 0,
+  panType: 'stereo', stereoPan: 0 });
+const step = group.playOrdered(true, { volume: 0.7, panType: 'HRTF',
+  position: [10, 0, 5], threeDOptions: { distanceModel: 'linear', rolloffFactor: 0.1 } });
+```
+
+`stereoPan` requires the effective stereo mode; `position` and `threeDOptions`
+require HRTF. Partial HRTF options preserve unspecified settings. Group all,
+random, and ordered playback and sprite children accept these same options.
+Invalid options throw before voice preparation, and group playback preflights
+every member. Direct `Playback.play(options)` also supports these settings,
+scheduling, and fades. Calling play on an already playing voice remains a no-op
+after validation.
+
+Synths and live streams support volume, spatial settings, and fade-in. They
+reject playback rate, loop count, scheduled starts, end fades, and per-loop fade
+settings because these sources do not support those controls.
 
 ```typescript
 const sound = await cacophony.createSound('laser.mp3');
@@ -173,111 +290,111 @@ setTimeout(() => playback1.pause(), 1000);
 setTimeout(() => playback2.stop(), 2000);
 
 // Or control all playbacks through the Sound
-sound.stop();  // Stops all three playbacks
-```
-
-Each playback exposes a read-only `state`: `"unplayed"`, `"playing"`, `"paused"`,
-or `"stopped"`. When `sound.preplay()` or `sound.play()` prepares a new voice,
-it removes stopped entries from `sound.playbacks`. Repeated play/stop calls
-therefore retain at most the most recently stopped voice in that collection.
-Unplayed, paused, and playing voices remain registered.
-
-An individual `playback.stop()` preserves the ability to call `playback.play()`
-again. A successfully restarted playback rejoins `sound.playbacks` and receives
-Sound controls again, even if it was previously reaped. Reaping disconnects its
-output and sends; replay restores the Sound's current routing and event forwarding.
-The playback retains its individual volume, rate, and other settings while reaped.
-Reaping does not call `cleanup()`; call `playback.cleanup()` when a retained playback
-is no longer needed.
-
-### Audio Sprites for Games
-
-Pack many short effects into one decoded WAV atlas while keeping each named
-region as an ordinary, independently configurable `Sound`:
-
-```bash
-cacophony sprite sfx/laser.wav sfx/engine.wav \
-  --out public/sfx-atlas.wav --map public/sfx-atlas.json --gap 10
-```
-
-```typescript
-import { Cacophony, type SpriteMap } from 'cacophony';
-
-const map = {
-  laser: { start: 0, duration: 0.35 },
-  engine: { start: 0.36, duration: 1.2, loopCount: 'infinite' },
-} as const satisfies SpriteMap;
-
-const cacophony = new Cacophony();
-const sprite = await cacophony.createSprite('/sfx-atlas.wav', map);
-
-// Literal keys stay typed. Each child uses the normal Sound API.
-sprite.sounds.laser.volume = 0.7;
-sprite.sounds.laser.play();
-
-// Dynamic names use the checked lookup.
-const selected: string = chooseEffectName();
-if (sprite.has(selected)) sprite.get(selected).play();
-
-// Child configuration is independent; the atlas has no shared play controls.
-sprite.sounds.engine.loop('infinite');
-sprite.sounds.engine.play();
-
-sprite.cleanup();
-```
-
-All child Sounds share the atlas `AudioBuffer`. `cleanup()` owns those children
-but not clones created with `sound.clone()`, which remain independently usable.
-
-## Sound Types
+sound.stop();  // Stops all three playbacks
+```
+
+Each playback exposes a read-only `state`: `"unplayed"`, `"playing"`, `"paused"`,
+or `"stopped"`. When `sound.preplay()` or `sound.play()` prepares a new voice,
+it removes stopped entries from `sound.playbacks`. Repeated play/stop calls
+therefore retain at most the most recently stopped voice in that collection.
+Unplayed, paused, and playing voices remain registered.
+
+An individual `playback.stop()` preserves the ability to call `playback.play()`
+again. A successfully restarted playback rejoins `sound.playbacks` and receives
+Sound controls again, even if it was previously reaped. Reaping disconnects its
+output and sends; replay restores the Sound's current routing and event forwarding.
+The playback retains its individual volume, rate, and other settings while reaped.
+Reaping does not call `cleanup()`; call `playback.cleanup()` when a retained playback
+is no longer needed.
+
+### Audio Sprites for Games
+
+Pack many short effects into one decoded WAV atlas while keeping each named
+region as an ordinary, independently configurable `Sound`:
+
+```bash
+cacophony sprite sfx/laser.wav sfx/engine.wav \
+  --out public/sfx-atlas.wav --map public/sfx-atlas.json --gap 10
+```
+
+```typescript
+import { Cacophony, type SpriteMap } from 'cacophony';
+
+const map = {
+  laser: { start: 0, duration: 0.35 },
+  engine: { start: 0.36, duration: 1.2, loopCount: 'infinite' },
+} as const satisfies SpriteMap;
+
+const cacophony = new Cacophony();
+const sprite = await cacophony.createSprite('/sfx-atlas.wav', map);
+
+// Literal keys stay typed. Each child uses the normal Sound API.
+sprite.sounds.laser.volume = 0.7;
+sprite.sounds.laser.play();
 
-Cacophony supports three URL-backed sound labels:
+// Dynamic names use the checked lookup.
+const selected: string = chooseEffectName();
+if (sprite.has(selected)) sprite.get(selected).play();
+
+// Child configuration is independent; the atlas has no shared play controls.
+sprite.sounds.engine.loop('infinite');
+sprite.sounds.engine.play();
+
+sprite.cleanup();
+```
+
+All child Sounds share the atlas `AudioBuffer`. `cleanup()` owns those children
+but not clones created with `sound.clone()`, which remain independently usable.
+
+## Sound Types
+
+Cacophony supports three URL-backed sound labels:
 
 | Type | Memory | Latency | Seeking | Multiple Instances | Best For |
 |------|--------|---------|---------|-------------------|----------|
 | **Buffer** (default) | High | None | Full | Yes | Sound effects, UI sounds, short music clips |
-| **HTML** | Medium | Low | Full | Yes | Media-element-backed background music, large audio files, and podcasts |
-| **Streaming** | Bounded | Low | Range-backed | One stream per source | Sample-accurate URL audio with effects, panning, and metering |
+| **HTML** | Medium | Low | Full | Yes | Media-element-backed background music, large audio files, and podcasts |
+| **Streaming** | Bounded | Low | Range-backed | One stream per source | Sample-accurate URL audio with effects, panning, and metering |
 
 ```typescript
 // Buffer - entire file loaded into memory
 const sfx = await cacophony.createSound('explosion.mp3', 'buffer');
 
-// HTML - media-element-backed playback, good for large files
-const music = await cacophony.createSound('bgm.mp3', 'html');
-
-// Streaming - incremental demux + WebCodecs decode into a PCM worklet
-const radio = await cacophony.createStream('https://example.com/live-radio.mp3');
-console.log(radio.streamCapabilities);
-// { transport: 'webcodecs', seekable: false, live: true, duration: Infinity }
-```
-
-`createStream(url)` uses a fetch → demux → WebCodecs `AudioDecoder` → PCM
-worklet path when WebCodecs is present and can decode the primary audio track.
-The returned source has `soundType === 'streaming'` and uses the same volume,
-pan/HRTF, filter, bus, send, and loudness-meter APIs as every other routable
-source. MP3, ADTS/MP4 AAC, Ogg, FLAC, and WAVE containers are supported.
-
-If WebCodecs is absent or the primary track has no WebCodecs decoder,
-`createStream()` falls back to a media-element `Sound`. Check
-`streamCapabilities.transport` for `'webcodecs'` or `'media-element'` rather
-than assuming a tier.
-
-Native HLS (`.m3u8`) playback, notably in Safari, uses the media element
-directly. In browsers without native HLS, `createStream()` lazily uses
-`hls.js`, declared as an optional peer dependency:
-
-```bash
-npm install hls.js
-```
-
-If neither native HLS nor an installed, MSE-capable `hls.js` is available,
-`createStream()` rejects with install guidance instead of leaving a media
-element silently waiting. hls.js failures after loading are emitted through
-the Sound's `soundError` event, and `sound.cleanup()` detaches and destroys the
-hls.js instance.
-
-### Format Fallback (Howler-style)
+// HTML - media-element-backed playback, good for large files
+const music = await cacophony.createSound('bgm.mp3', 'html');
+
+// Streaming - incremental demux + WebCodecs decode into a PCM worklet
+const radio = await cacophony.createStream('https://example.com/live-radio.mp3');
+console.log(radio.streamCapabilities);
+// { transport: 'webcodecs', seekable: false, live: true, duration: Infinity }
+```
+
+`createStream(url)` uses a fetch → demux → WebCodecs `AudioDecoder` → PCM
+worklet path when WebCodecs is present and can decode the primary audio track.
+The returned source has `soundType === 'streaming'` and uses the same volume,
+pan/HRTF, filter, bus, send, and loudness-meter APIs as every other routable
+source. MP3, ADTS/MP4 AAC, Ogg, FLAC, and WAVE containers are supported.
+
+If WebCodecs is absent or the primary track has no WebCodecs decoder,
+`createStream()` falls back to a media-element `Sound`. Check
+`streamCapabilities.transport` for `'webcodecs'` or `'media-element'` rather
+than assuming a tier.
+
+Native HLS (`.m3u8`) playback, notably in Safari, uses the media element
+directly. In browsers without native HLS, `createStream()` lazily uses
+`hls.js`, declared as an optional peer dependency:
+
+```bash
+npm install hls.js
+```
+
+If neither native HLS nor an installed, MSE-capable `hls.js` is available,
+`createStream()` rejects with install guidance instead of leaving a media
+element silently waiting. hls.js failures after loading are emitted through
+the Sound's `soundError` event, and `sound.cleanup()` detaches and destroys the
+hls.js instance.
+
+### Format Fallback (Howler-style)
 
 Pass an array of URLs and Cacophony picks the first one the browser can play.
 It queries `HTMLAudioElement.canPlayType` per extension and fetches only the
@@ -419,86 +536,86 @@ const playback = sound.play()[0];
 playback.filters[0].frequency.value = 500; // Only affects this playback
 ```
 
-See [TypeDoc](https://cacophony.js.org) for complete filter parameters and options.
-
-### Per-source effects
-
-Use `addEffect` for source character such as distortion, EQ, tremolo, or pitch
-processing. The source stores the `CacophonyEffect` as a recipe and builds a
-fresh effect instance for every playback, before that playback's panner. The
-returned playback handle can be automated without changing another playback.
-
-```typescript
-const guitar = await cacophony.createSound('guitar.mp3');
-const distortion = cacophony.createDistortion({ drive: 4 });
-guitar.addEffect(distortion);
-
-const [take] = guitar.play();
-const liveTremolo = await take.addEffect(cacophony.createTremolo({ rate: 5 }));
-take.rampEffectParam(liveTremolo, 'depth', 0.8, { duration: 250 });
-
-guitar.removeEffect(distortion); // future playbacks no longer build it
-```
-
-### Advanced paper-backed effects
-
-The advanced suite adds five non-neural effects derived from published DSP
-algorithms. They work as per-source recipes or shared bus effects and expose
-their live controls through `rampEffectParam`.
-
-```typescript
-// Equal-Hz SSB translation: harmonic material becomes bell-like/inharmonic.
-guitar.addEffect(cacophony.createFrequencyShifter({ frequency: 180 }));
-
-// Endlessly descending notches (use a positive rate to reverse direction).
-drums.addEffect(cacophony.createBarberpole({ rate: -0.1, stages: 32 }));
-
-// Dry voice plus a fifth and octave, all produced in one STFT analysis pass.
-vocals.addEffect(cacophony.createHarmonizer({
-  semitonesA: 7,
-  semitonesB: 12,
-  gainA: 0.6,
-  gainB: 0.45,
-}));
-
-// Capture/release a phase-continuing spectral texture at runtime.
-const freeze = await playback.addEffect(cacophony.createSpectralFreeze());
-playback.rampEffectParam(freeze, 'freeze', 1); // capture
-playback.rampEffectParam(freeze, 'freeze', 0); // return to live input
-
-// Convert mono or stereo material to transient-preserving decorrelated stereo.
-ambience.addEffect(cacophony.createStereoWidener({
-  width: 0.75,
-  decorrelation: 1,
-  transientProtection: 0.8,
-}));
-```
-
-`createFrequencyShifter` implements Wardle's Hilbert-transform single-sideband
-modulator (DAFx-98). `createBarberpole` implements the warped spectral-delay SSB
-structure of Esqueda, Valimaki and Parker (DAFx-15). `createHarmonizer` extends
-the Laroche-Dolson identity-phase-locked peak shifter to two simultaneous
-voices. `createSpectralFreeze` preserves measured inter-frame phase advance
-instead of looping one static FFT frame. `createStereoWidener` uses sparse
-velvet-noise decorrelation and temporarily retreats to the direct path for
-transients.
-
-Keep shared space effects such as reverb on a bus and feed them with a wet
-send. This leaves the playback's dry character chain intact while every source
-sent to the bus shares one live reverb instance.
-
-```typescript
-const vocals = await cacophony.createSound('vocals.mp3');
-vocals.addEffect(cacophony.createDistortion({ drive: 1.5 })); // dry, per playback
-
-const chamber = cacophony.createBus('chamber');
-await chamber.addFilter(cacophony.createReverb({ wet: 1, dry: 0 }));
-vocals.routeTo(chamber, 0.25); // 25% wet send; primary output stays on master
-
-vocals.play();
-```
-
-## Custom Audio Routing
+See [TypeDoc](https://cacophony.js.org) for complete filter parameters and options.
+
+### Per-source effects
+
+Use `addEffect` for source character such as distortion, EQ, tremolo, or pitch
+processing. The source stores the `CacophonyEffect` as a recipe and builds a
+fresh effect instance for every playback, before that playback's panner. The
+returned playback handle can be automated without changing another playback.
+
+```typescript
+const guitar = await cacophony.createSound('guitar.mp3');
+const distortion = cacophony.createDistortion({ drive: 4 });
+guitar.addEffect(distortion);
+
+const [take] = guitar.play();
+const liveTremolo = await take.addEffect(cacophony.createTremolo({ rate: 5 }));
+take.rampEffectParam(liveTremolo, 'depth', 0.8, { duration: 250 });
+
+guitar.removeEffect(distortion); // future playbacks no longer build it
+```
+
+### Advanced paper-backed effects
+
+The advanced suite adds five non-neural effects derived from published DSP
+algorithms. They work as per-source recipes or shared bus effects and expose
+their live controls through `rampEffectParam`.
+
+```typescript
+// Equal-Hz SSB translation: harmonic material becomes bell-like/inharmonic.
+guitar.addEffect(cacophony.createFrequencyShifter({ frequency: 180 }));
+
+// Endlessly descending notches (use a positive rate to reverse direction).
+drums.addEffect(cacophony.createBarberpole({ rate: -0.1, stages: 32 }));
+
+// Dry voice plus a fifth and octave, all produced in one STFT analysis pass.
+vocals.addEffect(cacophony.createHarmonizer({
+  semitonesA: 7,
+  semitonesB: 12,
+  gainA: 0.6,
+  gainB: 0.45,
+}));
+
+// Capture/release a phase-continuing spectral texture at runtime.
+const freeze = await playback.addEffect(cacophony.createSpectralFreeze());
+playback.rampEffectParam(freeze, 'freeze', 1); // capture
+playback.rampEffectParam(freeze, 'freeze', 0); // return to live input
+
+// Convert mono or stereo material to transient-preserving decorrelated stereo.
+ambience.addEffect(cacophony.createStereoWidener({
+  width: 0.75,
+  decorrelation: 1,
+  transientProtection: 0.8,
+}));
+```
+
+`createFrequencyShifter` implements Wardle's Hilbert-transform single-sideband
+modulator (DAFx-98). `createBarberpole` implements the warped spectral-delay SSB
+structure of Esqueda, Valimaki and Parker (DAFx-15). `createHarmonizer` extends
+the Laroche-Dolson identity-phase-locked peak shifter to two simultaneous
+voices. `createSpectralFreeze` preserves measured inter-frame phase advance
+instead of looping one static FFT frame. `createStereoWidener` uses sparse
+velvet-noise decorrelation and temporarily retreats to the direct path for
+transients.
+
+Keep shared space effects such as reverb on a bus and feed them with a wet
+send. This leaves the playback's dry character chain intact while every source
+sent to the bus shares one live reverb instance.
+
+```typescript
+const vocals = await cacophony.createSound('vocals.mp3');
+vocals.addEffect(cacophony.createDistortion({ drive: 1.5 })); // dry, per playback
+
+const chamber = cacophony.createBus('chamber');
+await chamber.addFilter(cacophony.createReverb({ wet: 1, dry: 0 }));
+vocals.routeTo(chamber, 0.25); // 25% wet send; primary output stays on master
+
+vocals.play();
+```
+
+## Custom Audio Routing
 
 Cacophony exposes the underlying Web Audio graph through Playback instances, enabling manual routing through custom effects chains. This is the low-level foundation for building complex audio processing pipelines.
 
@@ -556,9 +673,9 @@ API documented below. The Bus class supersedes the older user-built
 A `Bus` is a named summing node with its own filter chain and per-edge
 gain on outgoing connections. Sounds and synths route to buses via
 `routeTo`; buses can carry rich effects (not just BiquadFilter) by
-adding a `CacophonyEffect` to their filter chain. The built-in
-`cacophony.createReverb()` and `cacophony.createImpulseResponse()` effects
-are ready to drop into a bus.
+adding a `CacophonyEffect` to their filter chain. The built-in
+`cacophony.createReverb()` and `cacophony.createImpulseResponse()` effects
+are ready to drop into a bus.
 
 ```typescript
 // 1. Create a named bus
@@ -582,6 +699,28 @@ drums.routeTo(reverbBus, 0.3);
 drums.play();
 ```
 
+Source sends can be changed and removed while voices are playing:
+
+```typescript
+drums.routeTo(reverbBus, 0.1, { duration: 250 }); // ramp the existing send over 250 ms
+drums.routeTo(reverbBus, 0, { duration: 500, type: 'exponential' });
+drums.removeSend(reverbBus); // disconnect the send on every voice and forget it for future voices
+```
+
+Gain changes are immediate by default. Ramps reuse each voice's send GainNode,
+cancel earlier automation, and start from the current envelope value. New sends
+and future voices start at the requested gain. Exponential fades to zero reach
+exact silence at the endpoint; transitions from zero or involving negative gains
+use a linear ramp. Durations are finite, non-negative milliseconds and gains must
+be finite.
+
+`removeSend` leaves primary routing and other sends alone, even when the removed
+send's bus is also the primary target. It is a no-op if the source has no send to
+that bus. Both methods accept a registered bus name and work on Sound, Synth,
+stream sources, and Group members. To remove a send after its named bus has been
+destroyed, pass the retained bus reference; its name is no longer registered.
+Removal disconnects immediately.
+
 ### Looking up buses by name
 
 ```typescript
@@ -599,81 +738,81 @@ the same node as `cacophony.globalGainNode`, so the existing
 transparently. Routing a sound to `cacophony.master` (or never calling
 `routeTo`) sends it through the master path.
 
-### Bus-to-bus routing with per-edge gain
+### Bus-to-bus routing with per-edge gain
 
 ```typescript
 const groupBus = cacophony.createBus('group');
 const sendBus = cacophony.createBus('aux');
 groupBus.connect(sendBus, 0.2);   // 20% send: groupBus.output → sendGain(0.2) → sendBus.input
-groupBus.disconnect(sendBus);     // tears down the sendGain too
-```
-
-### Native impulse responses
-
-`createImpulseResponse()` builds a native `ConvolverNode` effect from an
-`AudioBuffer` or URL. URL-backed IRs are fetched and decoded once per audio
-context and URL; failed loads are evicted so a later call can retry. Convolver
-normalization defaults to `false`, preserving measured IR gain.
-
-```typescript
-// Wet-only send bus: returns a single ConvolverNode internally.
-const chamber = cacophony.createBus('chamber');
-await chamber.addFilter(cacophony.createImpulseResponse('/irs/chamber.wav'));
-vocals.routeTo(chamber, 0.25);
-
-// Inline dry/wet graph: exposes dry/wet AudioParams for bus automation.
-const room = cacophony.createImpulseResponse('/irs/room.wav', {
-  dry: 0.7,
-  wet: 0.3,
-  normalize: false,
-});
-const handle = await bus.addFilter(room);
-bus.rampFilterParam(handle, 'wet', 0.6, { duration: 500 });
-```
-
-### Adding custom effects to a bus
-
-Bus filter chains accept Cacophony-built BiquadFilters and any
-`CacophonyEffect`. Raw third-party AudioNodes are rejected unless you
-wrap them explicitly with `cacophony.shareEffect(node)` — this surfaces
-the shared-state intent (the same node will run on every bus that adds it).
-An effect can build either a single `AudioNode` or a `BuiltEffectGraph` with
-separate `input`/`output` endpoints for multi-node processors.
+groupBus.disconnect(sendBus);     // tears down the sendGain too
+```
+
+### Native impulse responses
+
+`createImpulseResponse()` builds a native `ConvolverNode` effect from an
+`AudioBuffer` or URL. URL-backed IRs are fetched and decoded once per audio
+context and URL; failed loads are evicted so a later call can retry. Convolver
+normalization defaults to `false`, preserving measured IR gain.
+
+```typescript
+// Wet-only send bus: returns a single ConvolverNode internally.
+const chamber = cacophony.createBus('chamber');
+await chamber.addFilter(cacophony.createImpulseResponse('/irs/chamber.wav'));
+vocals.routeTo(chamber, 0.25);
+
+// Inline dry/wet graph: exposes dry/wet AudioParams for bus automation.
+const room = cacophony.createImpulseResponse('/irs/room.wav', {
+  dry: 0.7,
+  wet: 0.3,
+  normalize: false,
+});
+const handle = await bus.addFilter(room);
+bus.rampFilterParam(handle, 'wet', 0.6, { duration: 500 });
+```
+
+### Adding custom effects to a bus
+
+Bus filter chains accept Cacophony-built BiquadFilters and any
+`CacophonyEffect`. Raw third-party AudioNodes are rejected unless you
+wrap them explicitly with `cacophony.shareEffect(node)` — this surfaces
+the shared-state intent (the same node will run on every bus that adds it).
+An effect can build either a single `AudioNode` or a `BuiltEffectGraph` with
+separate `input`/`output` endpoints for multi-node processors.
 
 ```typescript
 const eq = cacophony.createBiquadFilter({ type: 'highshelf', frequency: 4000, gain: 3 });
 await bus.addFilter(eq);
 
-const sharedWorklet = new AudioWorkletNode(cacophony.context, 'my-fx');
-await bus.addFilter(cacophony.shareEffect(sharedWorklet));
-```
-
-FOA binaural decoding is available in both forms. Use
-`createFoaDecoder()` when you want explicit custom wiring through
-`decoder.input` and `decoder.output`; use `createFoaDecoderEffect()` only on a
-dedicated 4-channel ACN/SN3D FOA bus, typically as the first and only filter
-that converts that bus to stereo binaural output.
-
-For physically correct mono positioning, use `encodeMonoToFoaSN3D()` and feed
-its ACN/SN3D `[W, Y, Z, X]` output to the decoder. Stereo recordings can instead
-be perceptually upmixed with `createStereoToBFormatNode()`. The default
-`algorithm: 'perceptual'` path preserves the existing three-band front cue;
-`algorithm: 'bcc'` uses frequency-domain coherence and pan analysis:
-
-```typescript
-const upmixer = await cacophony.createStereoToBFormatNode({ algorithm: 'bcc' });
-const decoder = await cacophony.createFoaDecoder();
-stereoSource.connect(upmixer);
-upmixer.connect(decoder.input);
-decoder.output.connect(cacophony.context.destination);
-
-// BCC analysis is stateful. Reset it after a seek or other discontinuity.
-upmixer.port.postMessage({ type: 'reset' });
-```
-
-Both stereo upmix algorithms emit ACN `[W, Y, Z, X]` but are perceptual
-approximations, neither N3D nor SN3D. The BCC path produces W/Y only and keeps
-Z/X at zero, trading the default path's front cue for per-band spatial analysis.
+const sharedWorklet = new AudioWorkletNode(cacophony.context, 'my-fx');
+await bus.addFilter(cacophony.shareEffect(sharedWorklet));
+```
+
+FOA binaural decoding is available in both forms. Use
+`createFoaDecoder()` when you want explicit custom wiring through
+`decoder.input` and `decoder.output`; use `createFoaDecoderEffect()` only on a
+dedicated 4-channel ACN/SN3D FOA bus, typically as the first and only filter
+that converts that bus to stereo binaural output.
+
+For physically correct mono positioning, use `encodeMonoToFoaSN3D()` and feed
+its ACN/SN3D `[W, Y, Z, X]` output to the decoder. Stereo recordings can instead
+be perceptually upmixed with `createStereoToBFormatNode()`. The default
+`algorithm: 'perceptual'` path preserves the existing three-band front cue;
+`algorithm: 'bcc'` uses frequency-domain coherence and pan analysis:
+
+```typescript
+const upmixer = await cacophony.createStereoToBFormatNode({ algorithm: 'bcc' });
+const decoder = await cacophony.createFoaDecoder();
+stereoSource.connect(upmixer);
+upmixer.connect(decoder.input);
+decoder.output.connect(cacophony.context.destination);
+
+// BCC analysis is stateful. Reset it after a seek or other discontinuity.
+upmixer.port.postMessage({ type: 'reset' });
+```
+
+Both stereo upmix algorithms emit ACN `[W, Y, Z, X]` but are perceptual
+approximations, neither N3D nor SN3D. The BCC path produces W/Y only and keeps
+Z/X at zero, trading the default path's front cue for per-band spatial analysis.
 
 ### Cleaning up
 
@@ -956,7 +1095,64 @@ stereoSound.stereoPan = 0.5;  // -1 (left) to 1 (right)
 stereoSound.play();
 ```
 
-See [TypeDoc](https://cacophony.js.org) for distance models, cone effects, and advanced 3D audio options.
+See [TypeDoc](https://cacophony.js.org) for distance models, cone effects, and advanced 3D audio options.
+
+`stereoPan` requires stereo mode; `position` and `threeDOptions` require HRTF mode.
+These setters validate the source and every voice before changing defaults or live
+settings. An incompatible mode, invalid value, or cleaned-up voice rejects the
+whole update. Group spatial setters also validate every member first.
+
+`threeDOptions` configures an HRTF panner without switching its mode. Select the
+mode when creating the source or with `play({ panType, ... })`. If per-playback
+overrides produce mixed stereo/HRTF voices, use each voice's spatial controls.
+
+`Sound.clone`, `Synth.clone`, and `Playback.clone` validate spatial overrides against
+the clone's target mode before allocation. Supply `stereoPan` for stereo clones,
+or `position` and `threeDOptions` for HRTF clones; incompatible overrides throw.
+
+### Motion smoothing
+
+Source position, source orientation, stereo pan, and modern listener pose updates can
+approach their targets exponentially instead of changing in steps. Smoothing is opt-in:
+the default time constant is `0`, which keeps immediate writes.
+
+```typescript
+const audio = new Cacophony(undefined, undefined, { spatialSmoothingTau: 0.03 });
+const moving = await audio.createSound('bird.mp3', 'buffer', 'HRTF');
+moving.position = [10, 5, 0];
+const [voice] = moving.play(); // Starts at this pose immediately
+
+moving.position = [12, 5, 0]; // Current voices approach the new position
+moving.spatialSmoothingTau = 0.05; // Applies to current and future voices
+voice.spatialSmoothingTau = 0.02; // Independent until the next source assignment
+audio.listenerSmoothingTau = 0.04; // Independent of source defaults
+audio.listenerPosition = [1, 0, 0];
+
+moving.spatialSmoothingTau = 0; // Snap pending motion to its target
+moving.position = [30, 5, 0]; // An immediate teleport
+```
+
+Time constants are **seconds**, unlike fade/ramp durations in milliseconds. After
+one time constant, roughly 63% of the change is complete; after three, roughly 95%.
+Negative or non-finite constants throw `RangeError`. The same runtime option is
+available on `createNodeCacophony()` and `createOfflineNodeCacophony()`.
+
+Sound, Synth, and stream sources inherit the instance default. A source assignment
+updates its current voices and the default for future voices. Sound, Synth, and
+Playback clones preserve the setting and requested pose. Initial source and
+`play(options)` poses are immediate; subsequent changes, including while paused,
+are smoothed. Stopping a voice snaps pending motion to its target, and a stopped
+voice takes new poses immediately, so a replayed voice starts where it was asked to.
+Partial `threeDOptions` updates leave omitted axes alone.
+
+Spatial getters report the last requested targets, including during transitions.
+Use these setters consistently: direct automation or mutation of the underlying
+panner parameters is outside this target-state contract. Orientation components
+are smoothed independently; this does not provide constant-speed angular rotation.
+HRTF processing uses control-rate parameters, so smoothing reduces motion artifacts
+without promising sample-perfect continuity. Legacy listeners using
+`setPosition`/`setOrientation`, and custom parameters lacking `setTargetAtTime`,
+continue to update immediately.
 
 ## Microphone Input
 
@@ -965,22 +1161,22 @@ Capture, process, and manipulate live audio input:
 ```typescript
 const cacophony = new Cacophony();
 
-try {
-  const micStream = await cacophony.getMicrophoneStream({
-    panType: 'stereo',
-    stereoPan: 0,
-    constraints: {
-      audio: { echoCancellation: true }
-    }
-  });
-
-  // Apply filters to microphone input
-  const lowPassFilter = cacophony.createBiquadFilter({ type: 'lowpass', frequency: 1000 });
-  micStream.addFilter(lowPassFilter);
-
-  // Control microphone volume
-  micStream.volume = 0.8;
-  micStream.play();
+try {
+  const micStream = await cacophony.getMicrophoneStream({
+    panType: 'stereo',
+    stereoPan: 0,
+    constraints: {
+      audio: { echoCancellation: true }
+    }
+  });
+
+  // Apply filters to microphone input
+  const lowPassFilter = cacophony.createBiquadFilter({ type: 'lowpass', frequency: 1000 });
+  micStream.addFilter(lowPassFilter);
+
+  // Control microphone volume
+  micStream.volume = 0.8;
+  micStream.play();
 
   // Pause and resume
   setTimeout(() => {
@@ -988,142 +1184,142 @@ try {
     setTimeout(() => micStream.resume(), 2000);
   }, 5000);
 
-} catch (error) {
-  // Permission and device failures reject getMicrophoneStream().
-  console.error("Error accessing microphone:", error);
-}
-```
-
-Microphone monitoring is routed through the master bus, so global volume,
-mute, master effects, and metering apply. Each playback exposes the standard
-play, pause, stop, and error event surface and is fully disconnected when the
-microphone is stopped.
+} catch (error) {
+  // Permission and device failures reject getMicrophoneStream().
+  console.error("Error accessing microphone:", error);
+}
+```
 
-## Audio Streaming
-
-`createStream()` incrementally fetches and demuxes MP3, ADTS/MP4 AAC, Ogg,
-FLAC, and WAVE audio. A WebCodecs `AudioDecoder` produces PCM chunks, which are
-resampled to the active audio context and written into the same AudioWorklet
-ring buffer used by `createPcmStreamSound()`. The returned stream is therefore
-sample-accurately scheduled, pannable, filterable, bus-routable, and meterable.
-
-The current streaming resampler uses linear interpolation without an
-anti-aliasing filter. When downsampling, source frequencies above the target
-Nyquist frequency can alias into the audible band; this is an accepted v1
-quality trade-off pending a future band-limited resampler.
-
-```typescript
-const controller = new AbortController();
-const stream = await cacophony.createStream('/music.ogg', controller.signal, 'stereo');
-
-console.log(stream.streamCapabilities);
-// {
-//   transport: 'webcodecs',
-//   seekable: true,
-//   live: false,
-//   duration: 183.42,
-// }
-
-stream.routeTo(musicBus);
-stream.addFilter(cacophony.createBiquadFilter({ type: 'lowpass', frequency: 1800 }));
-await cacophony.createLoudnessMeter(musicBus);
-stream.play();
-stream.seek(30); // reopens the decoder at 30s when the server supports byte ranges
-
-controller.abort(); // cancels fetch/decoder work and tears down the PCM worklet
-```
-
-`seekable` becomes `true` only after the server answers a byte-range request
-with a range response. Live sources report `live: true`, `seekable: false`, and
-`duration: Infinity`; calling `seek()` on one throws a clear error. A finite
-file whose duration metadata is unavailable also reports `Infinity` rather
-than inventing a duration.
-
-When `AudioDecoder` is unavailable, or the primary audio track cannot be
-decoded by WebCodecs, `createStream()` returns the compatibility
-media-element tier. Its `streamCapabilities.transport` is `'media-element'`;
-the browser owns buffering, seeking, and live-stream behavior in that tier.
-
-### Media-element streaming contract
-
-`createSound(url, 'streaming')` selects the media-element tier directly.
-`createStream(url)` returns the same tier when WebCodecs is unavailable or
-cannot decode the primary track, and always uses it for HLS. After metadata
-loads, `streamCapabilities` reports the browser's duration and whether it
-currently exposes a seekable range. A live source has `live: true` and
-`duration: Infinity`; an ordinary finite resource reports its real duration.
-The `Sound` itself has `duration === NaN` while unplayed because it has no
-playback yet. After `preplay()` or `play()`, `sound.duration` and
-`playback.duration` read the loaded media element and return the finite value
-or `Infinity` for a live source.
-
-Media playback moves from unplayed to playing only after the element's
-`play()` promise resolves. `pause()` moves it to paused, `resume()` calls
-`play()` again and returns it to playing, and `stop()` moves it to stopped and
-resets it. Playback events follow those accepted transitions: `play`, `pause`,
-then both `play` and `resume` on a resume, followed by `stop`. The owning
-`Sound` emits `play` after the initial accepted play, plus its collective
-`pause`, `resume`, and `stop` events.
-
-`seek(time)` writes the media element's `currentTime` only when the browser
-exposes a seekable range. A live or finite media source without such a range
-throws a descriptive error and remains at its current position. Infinite
-looping uses the media element's native `loop`; finite loop counts are managed
-by Cacophony and emit `loopEnd` between iterations before the final `ended`.
-
-Every `preplay()` creates an independent media element, so a media-backed
-`Sound` supports concurrent playback instances. `cleanup()` pauses each
-element, clears its `src`, calls `load()` to release the resource, disconnects
-its Web Audio nodes, and removes the playback. Offline `timeStretch()` requires
-a decoded `AudioBuffer`, so calling `timeStretch()` on this tier throws a
-predictable buffer-required error.
-
-For audio that arrives as decoded samples instead of a URL, use the
-AudioWorklet-backed push source:
-
-```typescript
-const pcm = await cacophony.createPcmStreamSound({
-  channelCount: 1,
-  bufferDuration: 1,
-  latency: 0.05,
-  signal: abortController.signal,
-});
-
-pcm.on('underrun', () => console.warn('PCM producer fell behind'));
-pcm.on('drain', () => writeNextChunk());
-pcm.on('ended', () => console.log('PCM playback finished'));
-
-pcm.play();
-const hasCapacity = pcm.write(samples); // interleaved Float32Array at context.sampleRate
-if (!hasCapacity) {
-  // The accepted write filled the ring buffer, or the chunk was rejected
-  // because it would exceed capacity. Wait for drain before writing again.
-}
-console.log(pcm.bufferedDuration);
-pcm.end(); // no more writes; "ended" fires after buffered PCM is consumed
-```
-
-`bufferDuration` fixes the ring-buffer capacity; `latency` sets how much PCM is
-collected before initial consumption. `write()` returns `false` when the buffer
-needs producer backpressure. An accepted write that fills the buffer also
-returns `false`; a chunk that would exceed remaining capacity is rejected and
-must be retried after `drain`.
-
-PCM underrun emits silence plus one `underrun` event per underrun episode;
-writing more samples recovers playback without repeating stale audio.
-`pause()` stops consuming and `resume()` continues from the buffered frame.
-Volume, stereo/HRTF pan, filters, buses, and sends use the same public APIs as
-other sources. Seek is not supported for a push PCM source. Loop is not
-supported because the source does not retain consumed samples.
-
-Adaptive HLS/DASH and DRM are outside the WebCodecs pull transport. `.m3u8`
-URLs use the media tier: native HLS where `HTMLAudioElement.canPlayType()`
-reports support (notably Safari), then the optional `hls.js` peer in
-MSE-capable browsers. Install that peer with `npm install hls.js`. DASH and DRM
-remain outside this integration.
-
-```typescript
-const cacophony = new Cacophony();
+Microphone monitoring is routed through the master bus, so global volume,
+mute, master effects, and metering apply. Each playback exposes the standard
+play, pause, stop, and error event surface and is fully disconnected when the
+microphone is stopped.
+
+## Audio Streaming
+
+`createStream()` incrementally fetches and demuxes MP3, ADTS/MP4 AAC, Ogg,
+FLAC, and WAVE audio. A WebCodecs `AudioDecoder` produces PCM chunks, which are
+resampled to the active audio context and written into the same AudioWorklet
+ring buffer used by `createPcmStreamSound()`. The returned stream is therefore
+sample-accurately scheduled, pannable, filterable, bus-routable, and meterable.
+
+The current streaming resampler uses linear interpolation without an
+anti-aliasing filter. When downsampling, source frequencies above the target
+Nyquist frequency can alias into the audible band; this is an accepted v1
+quality trade-off pending a future band-limited resampler.
+
+```typescript
+const controller = new AbortController();
+const stream = await cacophony.createStream('/music.ogg', controller.signal, 'stereo');
+
+console.log(stream.streamCapabilities);
+// {
+//   transport: 'webcodecs',
+//   seekable: true,
+//   live: false,
+//   duration: 183.42,
+// }
+
+stream.routeTo(musicBus);
+stream.addFilter(cacophony.createBiquadFilter({ type: 'lowpass', frequency: 1800 }));
+await cacophony.createLoudnessMeter(musicBus);
+stream.play();
+stream.seek(30); // reopens the decoder at 30s when the server supports byte ranges
+
+controller.abort(); // cancels fetch/decoder work and tears down the PCM worklet
+```
+
+`seekable` becomes `true` only after the server answers a byte-range request
+with a range response. Live sources report `live: true`, `seekable: false`, and
+`duration: Infinity`; calling `seek()` on one throws a clear error. A finite
+file whose duration metadata is unavailable also reports `Infinity` rather
+than inventing a duration.
+
+When `AudioDecoder` is unavailable, or the primary audio track cannot be
+decoded by WebCodecs, `createStream()` returns the compatibility
+media-element tier. Its `streamCapabilities.transport` is `'media-element'`;
+the browser owns buffering, seeking, and live-stream behavior in that tier.
+
+### Media-element streaming contract
+
+`createSound(url, 'streaming')` selects the media-element tier directly.
+`createStream(url)` returns the same tier when WebCodecs is unavailable or
+cannot decode the primary track, and always uses it for HLS. After metadata
+loads, `streamCapabilities` reports the browser's duration and whether it
+currently exposes a seekable range. A live source has `live: true` and
+`duration: Infinity`; an ordinary finite resource reports its real duration.
+The `Sound` itself has `duration === NaN` while unplayed because it has no
+playback yet. After `preplay()` or `play()`, `sound.duration` and
+`playback.duration` read the loaded media element and return the finite value
+or `Infinity` for a live source.
+
+Media playback moves from unplayed to playing only after the element's
+`play()` promise resolves. `pause()` moves it to paused, `resume()` calls
+`play()` again and returns it to playing, and `stop()` moves it to stopped and
+resets it. Playback events follow those accepted transitions: `play`, `pause`,
+then both `play` and `resume` on a resume, followed by `stop`. The owning
+`Sound` emits `play` after the initial accepted play, plus its collective
+`pause`, `resume`, and `stop` events.
+
+`seek(time)` writes the media element's `currentTime` only when the browser
+exposes a seekable range. A live or finite media source without such a range
+throws a descriptive error and remains at its current position. Infinite
+looping uses the media element's native `loop`; finite loop counts are managed
+by Cacophony and emit `loopEnd` between iterations before the final `ended`.
+
+Every `preplay()` creates an independent media element, so a media-backed
+`Sound` supports concurrent playback instances. `cleanup()` pauses each
+element, clears its `src`, calls `load()` to release the resource, disconnects
+its Web Audio nodes, and removes the playback. Offline `timeStretch()` requires
+a decoded `AudioBuffer`, so calling `timeStretch()` on this tier throws a
+predictable buffer-required error.
+
+For audio that arrives as decoded samples instead of a URL, use the
+AudioWorklet-backed push source:
+
+```typescript
+const pcm = await cacophony.createPcmStreamSound({
+  channelCount: 1,
+  bufferDuration: 1,
+  latency: 0.05,
+  signal: abortController.signal,
+});
+
+pcm.on('underrun', () => console.warn('PCM producer fell behind'));
+pcm.on('drain', () => writeNextChunk());
+pcm.on('ended', () => console.log('PCM playback finished'));
+
+pcm.play();
+const hasCapacity = pcm.write(samples); // interleaved Float32Array at context.sampleRate
+if (!hasCapacity) {
+  // The accepted write filled the ring buffer, or the chunk was rejected
+  // because it would exceed capacity. Wait for drain before writing again.
+}
+console.log(pcm.bufferedDuration);
+pcm.end(); // no more writes; "ended" fires after buffered PCM is consumed
+```
+
+`bufferDuration` fixes the ring-buffer capacity; `latency` sets how much PCM is
+collected before initial consumption. `write()` returns `false` when the buffer
+needs producer backpressure. An accepted write that fills the buffer also
+returns `false`; a chunk that would exceed remaining capacity is rejected and
+must be retried after `drain`.
+
+PCM underrun emits silence plus one `underrun` event per underrun episode;
+writing more samples recovers playback without repeating stale audio.
+`pause()` stops consuming and `resume()` continues from the buffered frame.
+Volume, stereo/HRTF pan, filters, buses, and sends use the same public APIs as
+other sources. Seek is not supported for a push PCM source. Loop is not
+supported because the source does not retain consumed samples.
+
+Adaptive HLS/DASH and DRM are outside the WebCodecs pull transport. `.m3u8`
+URLs use the media tier: native HLS where `HTMLAudioElement.canPlayType()`
+reports support (notably Safari), then the optional `hls.js` peer in
+MSE-capable browsers. Install that peer with `npm install hls.js`. DASH and DRM
+remain outside this integration.
+
+```typescript
+const cacophony = new Cacophony();
 
 try {
   const streamedSound = await cacophony.createStream('https://example.com/live_radio_stream');
@@ -1304,18 +1500,18 @@ synth.type = 'square';  // Triggers typeChange event
 | `pause` | `void` | Fired when playback pauses. |
 | `resume` | `void` | Fired when playback resumes after being paused. |
 | `ended` | `void` | Fired when playback ends naturally. |
-| `seek` | `number` | Fired once after a successful `Playback.seek(time)`, with the requested time in seconds. Rejected seeks do not emit. |
+| `seek` | `number` | Fired once after a successful `Playback.seek(time)`, with the requested time in seconds. Rejected seeks do not emit. |
 | `volumeChange` | `number` | Fired when playback volume changes. Receives new volume value. |
 | `error` | `PlaybackErrorEvent` | Fired on playback errors. Contains `error`, `errorType`, `timestamp`, `recoverable`. |
 
-`seek` is specific to `Playback` (buffer and media-element sources). Subscribe on
-each playback to observe seeks, including those requested through `Sound.seek()`.
-`Sound` does not relay a collective `seek`: its concurrent voices can have
-different positions, and a collective seek can fail after some voices have moved.
-For media elements, the event reports acceptance of the `currentTime` write;
-it does not wait for the browser's asynchronous `seeked` event or playback resumption.
-
-#### Synth Events
+`seek` is specific to `Playback` (buffer and media-element sources). Subscribe on
+each playback to observe seeks, including those requested through `Sound.seek()`.
+`Sound` does not relay a collective `seek`: its concurrent voices can have
+different positions, and a collective seek can fail after some voices have moved.
+For media elements, the event reports acceptance of the `currentTime` write;
+it does not wait for the browser's asynchronous `seeked` event or playback resumption.
+
+#### Synth Events
 
 | Event | Payload | Description |
 |-------|---------|-------------|
@@ -1336,29 +1532,29 @@ Cacophony implements intelligent three-layer caching for optimal performance:
 
 **Memory Cache (LRU)** → **Browser Cache API** → **Network**
 
-HTTP reuse decisions are made by `http-cache-semantics` for both decoded memory entries and persistent responses, using the response headers available to the runtime. Fresh responses can be reused; stale responses are conditionally validated when ETag or Last-Modified is available. `no-cache` requires validation, and `no-store` prevents retention in either layer. A successful matching 304 can reuse the decoded buffer while updating its policy.
-
-If a 304 cannot be matched to the stored representation, Cacophony retries with an unconditional Fetch reload. This includes a 304 that omits the ETag of an ETag-bearing stored response. Compared with the previous cache implementation, such servers can incur an additional request; return matching validators on 304 responses to allow reuse.
-
-A matching 304 emits `onCacheHit` with `cacheType: "conditional"`. When it reuses an already decoded buffer, it does not emit `onLoadingComplete`; when it decodes retained bytes, it emits both events. This differs from the previous implementation's completion event on every 304. Await `getAudioBuffer()` to observe completion regardless of the cache path.
-
-The 24-hour default TTL applies only when the response supplies no Cache-Control, Expires, Pragma, or validators. Explicit expiry never falls back to that TTL. Custom TTL values use milliseconds and are rounded down to whole seconds. Persistence uses a versioned response containing both bytes and policy; older cache entries are ignored and fetched again. On first persistent-cache access, Cacophony attempts to delete its legacy `audio-cache` namespace. Cleanup failure is reported through `onCacheError` and does not prevent loading or use of the current cache.
-
-`AudioCache.setCacheExpirationTime()` affects newly created response policies. Existing decoded and persisted entries keep the lifetime assigned when their policy was created, including across cache instances. Clearing decoded memory does not rewrite persistent policies. Unlike the previous implementation, negative or non-finite TTL values throw `RangeError` and leave the configured TTL unchanged; zero is valid and disables fallback freshness.
-
-Compatibility change: a response with only `Cache-Control: public` or `private` and no expiry or validators no longer receives the fallback TTL. These directives permit storage but do not specify how long the response is fresh. Such responses can be stored, but subsequent loads go through Fetch again. Cacophony deliberately does not assign heuristic freshness to responses with explicit cache directives. To enable fresh reuse, serve an appropriate `max-age` (for example, `private, max-age=60`) or `Expires`; increasing the fallback TTL does not override those responses.
-
-Cross-origin audio uses both decoded memory and persistent caching. CORS exposes Cache-Control, Expires, and Last-Modified without extra server configuration. For cross-origin entries requiring validation, Cacophony asks Fetch to revalidate through the browser HTTP cache, avoiding application-added conditional headers and their CORS preflight requirements. Browser HTTP caching remains enabled. A browser-validated response is decoded again because Fetch delivers the resulting representation rather than its internal 304 exchange.
-
-In browsers, the guarantee is HTTP policy based on browser-visible headers. Cross-origin caching remains enabled when CORS hides headers. A hidden Age can overestimate remaining freshness, and a hidden Vary cannot participate in application-cache matching. Browser validation applies when Fetch runs; a fresh application-cache hit does not consult the browser HTTP cache. This URL-only API explicitly controls Accept; a visible Vary on other, host-managed headers prevents application-cache retention. Data-URL decoding and caching are unchanged.
-
-For static audio, use versioned or content-hashed URLs such as `/audio/chime.a1b2c3.ogg` with a long `Cache-Control: max-age`. Publish changed audio at a new URL. For mutable audio requiring validation on every load, use `Cache-Control: no-cache`. Expose relevant response headers when freshness or variants depend on them:
-
-```http
-Access-Control-Expose-Headers: Age, Date, ETag, Vary
-```
-
-This header supplements the server's normal CORS access configuration. Exposing ETag does not cause Cacophony to add conditional request headers to cross-origin requests; Fetch still handles validation.
+HTTP reuse decisions are made by `http-cache-semantics` for both decoded memory entries and persistent responses, using the response headers available to the runtime. Fresh responses can be reused; stale responses are conditionally validated when ETag or Last-Modified is available. `no-cache` requires validation, and `no-store` prevents retention in either layer. A successful matching 304 can reuse the decoded buffer while updating its policy.
+
+If a 304 cannot be matched to the stored representation, Cacophony retries with an unconditional Fetch reload. This includes a 304 that omits the ETag of an ETag-bearing stored response. Compared with the previous cache implementation, such servers can incur an additional request; return matching validators on 304 responses to allow reuse.
+
+A matching 304 emits `onCacheHit` with `cacheType: "conditional"`. When it reuses an already decoded buffer, it does not emit `onLoadingComplete`; when it decodes retained bytes, it emits both events. This differs from the previous implementation's completion event on every 304. Await `getAudioBuffer()` to observe completion regardless of the cache path.
+
+The 24-hour default TTL applies only when the response supplies no Cache-Control, Expires, Pragma, or validators. Explicit expiry never falls back to that TTL. Custom TTL values use milliseconds and are rounded down to whole seconds. Persistence uses a versioned response containing both bytes and policy; older cache entries are ignored and fetched again. On first persistent-cache access, Cacophony attempts to delete its legacy `audio-cache` namespace. Cleanup failure is reported through `onCacheError` and does not prevent loading or use of the current cache.
+
+`AudioCache.setCacheExpirationTime()` affects newly created response policies. Existing decoded and persisted entries keep the lifetime assigned when their policy was created, including across cache instances. Clearing decoded memory does not rewrite persistent policies. Unlike the previous implementation, negative or non-finite TTL values throw `RangeError` and leave the configured TTL unchanged; zero is valid and disables fallback freshness.
+
+Compatibility change: a response with only `Cache-Control: public` or `private` and no expiry or validators no longer receives the fallback TTL. These directives permit storage but do not specify how long the response is fresh. Such responses can be stored, but subsequent loads go through Fetch again. Cacophony deliberately does not assign heuristic freshness to responses with explicit cache directives. To enable fresh reuse, serve an appropriate `max-age` (for example, `private, max-age=60`) or `Expires`; increasing the fallback TTL does not override those responses.
+
+Cross-origin audio uses both decoded memory and persistent caching. CORS exposes Cache-Control, Expires, and Last-Modified without extra server configuration. For cross-origin entries requiring validation, Cacophony asks Fetch to revalidate through the browser HTTP cache, avoiding application-added conditional headers and their CORS preflight requirements. Browser HTTP caching remains enabled. A browser-validated response is decoded again because Fetch delivers the resulting representation rather than its internal 304 exchange.
+
+In browsers, the guarantee is HTTP policy based on browser-visible headers. Cross-origin caching remains enabled when CORS hides headers. A hidden Age can overestimate remaining freshness, and a hidden Vary cannot participate in application-cache matching. Browser validation applies when Fetch runs; a fresh application-cache hit does not consult the browser HTTP cache. This URL-only API explicitly controls Accept; a visible Vary on other, host-managed headers prevents application-cache retention. Data-URL decoding and caching are unchanged.
+
+For static audio, use versioned or content-hashed URLs such as `/audio/chime.a1b2c3.ogg` with a long `Cache-Control: max-age`. Publish changed audio at a new URL. For mutable audio requiring validation on every load, use `Cache-Control: no-cache`. Expose relevant response headers when freshness or variants depend on them:
+
+```http
+Access-Control-Expose-Headers: Age, Date, ETag, Vary
+```
+
+This header supplements the server's normal CORS access configuration. Exposing ETag does not cause Cacophony to add conditional request headers to cross-origin requests; Fetch still handles validation.
 
 ```typescript
 const cacophony = new Cacophony();
@@ -1366,7 +1562,7 @@ const cacophony = new Cacophony();
 // First load - fetches from network, stores in cache
 const sound1 = await cacophony.createSound('audio.mp3');
 
-// Second load - from memory while the HTTP policy permits reuse
+// Second load - from memory while the HTTP policy permits reuse
 const sound2 = await cacophony.createSound('audio.mp3');
 
 // Monitor cache performance via events
@@ -1383,12 +1579,12 @@ cacophony.on('cacheMiss', (event) => {
 // Clear memory cache (browser cache persists)
 cacophony.clearMemoryCache();
 
-// Optional: configure TTL for responses without cache directives, expiry, or validators
+// Optional: configure TTL for responses without cache directives, expiry, or validators
 import { AudioCache } from 'cacophony';
 AudioCache.setCacheExpirationTime(60 * 60 * 1000); // 1 hour
 ```
 
-Decoded buffers remain bounded to 64 MiB per audio context. Concurrent callers share fetching and decoding; cancelling one caller does not cancel the others. Storage errors are reported through cacheError while a successfully downloaded response can still be delivered.
+Decoded buffers remain bounded to 64 MiB per audio context. Concurrent callers share fetching and decoding; cancelling one caller does not cancel the others. Storage errors are reported through cacheError while a successfully downloaded response can still be delivered.
 
 ## Cancellation with AbortSignal