cacophony 0.28.0 → 0.30.3

package/README.md

@@ -129,26 +129,53 @@ sound.stop();  // Stops all three playbacks
 
 ## Sound Types
 
-Cacophony supports three 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 | Background music, large audio files, podcasts |
-| **Streaming** | Medium | Low | Full | Yes | Network-backed playback created via `createStream()` |
+| **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 - streams from network, good for large files
-const music = await cacophony.createSound('bgm.mp3', 'html');
-
-// Streaming - convenience helper for network-backed playback
-const radio = await cacophony.createStream('https://example.com/stream.m3u8');
-```
-
-### 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
@@ -290,9 +317,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.
-
-## 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.
 
@@ -738,16 +842,22 @@ Capture, process, and manipulate live audio input:
 ```typescript
 const cacophony = new Cacophony();
 
-try {
-  const micStream = await cacophony.getMicrophoneStream();
-  micStream.play();
-
-  // Apply filters to microphone input
-  const lowPassFilter = cacophony.createBiquadFilter({ type: 'lowpass', frequency: 1000 });
-  micStream.addFilter(lowPassFilter);
-
-  // Control microphone volume
-  micStream.volume = 0.8;
+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(() => {
@@ -755,17 +865,142 @@ try {
     setTimeout(() => micStream.resume(), 2000);
   }, 5000);
 
-} catch (error) {
-  console.error("Error accessing microphone:", error);
-}
-```
-
-## Audio Streaming
-
-Stream audio content efficiently:
+} 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.
 
-```typescript
-const cacophony = new Cacophony();
+## 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');

package/bin/cacophony.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+// Thin entry for the cacophony CLI. Imports the BUILT dispatch from
+// dist/cli/index.mjs (so `npm i -g cacophony` works) and runs it with argv.
+import { main } from "../dist/cli/index.mjs";
+
+await main(process.argv.slice(2));

package/dist/autoplayUnlock.d.ts

@@ -16,12 +16,12 @@ export interface AutoplayUnlockOptions {
     onUnlock: () => void;
 }
 /**
- * Install one-time unlock listeners. Returns a cleanup function that removes
- * the listeners if they have not already fired (e.g. when a `Cacophony`
- * instance is torn down before the user interacts).
+ * Watch for context suspension and install unlock listeners while needed.
+ * Returns a cleanup function that removes both the context watcher and any
+ * armed gesture listeners (e.g. when a `Cacophony` instance is torn down).
  *
- * If the environment is non-browser (`document` is undefined) or the context
- * is not in `suspended` state, this is a no-op and returns a no-op cleanup.
+ * If the environment is non-browser (`document` is undefined), this is a
+ * no-op and returns a no-op cleanup.
  *
  * @internal
  */

package/dist/backend-available.d.ts

@@ -0,0 +1 @@
+export declare const nodeBackendAvailable: boolean;

package/dist/bus.d.ts

@@ -39,16 +39,7 @@ export declare class Bus {
      */
     readonly output: GainNode;
     private readonly _context;
-    private readonly _filterEntries;
-    /**
-     * Filter nodes currently bypassed (skipped in the audible chain). A bypassed
-     * node stays in {@link _filterEntries} — so {@link filters} order, identity, and
-     * its live AudioParams are preserved — but {@link _desiredFilterChainEdges}
-     * builds the series chain over the NON-bypassed filters only, wiring the
-     * signal around it. Membership is by node identity.
-     */
-    private readonly _bypassedFilters;
-    private readonly _filterChainEdges;
+    private readonly _effectChain;
     private readonly _sendGains;
     private readonly _directConnections;
     /**
@@ -64,6 +55,7 @@ export declare class Bus {
      * the named-bus registry on destroy. Anonymous buses leave this undefined.
      */
     private readonly _onDestroy?;
+    private readonly _destroyable;
     private _destroyed;
     /**
      * @param context Web Audio context the bus's nodes live on.
@@ -72,8 +64,9 @@ export declare class Bus {
      *   the `master` bus to alias `cacophony.globalGainNode`. If omitted, a
      *   fresh GainNode is allocated.
      * @param onDestroy Optional registry-cleanup hook fired by destroy().
+     * @param destroyable Whether destroy() may tear down this bus.
      */
-    constructor(context: BaseContext, name?: string | null, input?: GainNode, onDestroy?: () => void);
+    constructor(context: BaseContext, name?: string | null, input?: GainNode, onDestroy?: () => void, destroyable?: boolean);
     /** True after {@link destroy} has been called. */
     get destroyed(): boolean;
     /** Output node gain — controls the overall level the bus sends downstream. */
@@ -111,9 +104,9 @@ export declare class Bus {
     /**
      * Reorder the existing filter chain. `nodes` must be a PERMUTATION of the
      * current filters — the same set of node objects (matched by identity), the
-     * same length, with no duplicates — just in a new order. Because
-     * {@link _refreshFilters} is incremental, only the edges that actually move
-     * are reconnected; unchanged edges are left untouched.
+     * same length, with no duplicates — just in a new order. Because the owned
+     * {@link EffectChain} reconciles incrementally, only the edges that actually
+     * move are reconnected; unchanged edges are left untouched.
      *
      * @throws if the bus has been destroyed, or if `nodes` is not a permutation
      *   of the current filters.
@@ -126,8 +119,8 @@ export declare class Bus {
      * it is skipped in the audible series chain: the signal is wired around it.
      * Un-bypassing wires it back in at its original position.
      *
-     * The reconnect goes through the incremental {@link _refreshFilters}, so only
-     * the seam around `node` is touched — the rest of the chain is left connected.
+     * The reconnect goes through the incremental {@link EffectChain}, so only the
+     * seam around `node` is touched — the rest of the chain is left connected.
      *
      * @param node A filter node currently on this bus (from {@link addFilter} or
      *   {@link filters}).
@@ -180,21 +173,6 @@ export declare class Bus {
         duration?: number;
         type?: FadeType;
     }): void;
-    /**
-     * Resolve the named {@link AudioParam} on a node. Tries the worklet
-     * `parameters` map first, then a directly-exposed native param
-     * (`node[paramName]`). Returns `undefined` if neither yields an AudioParam.
-     *
-     * Detection is structural (duck-typed), never `instanceof` — the mocked test
-     * context may not provide the `AudioParam` global.
-     */
-    private _resolveAudioParam;
-    /**
-     * Structural AudioParam check: a value is treated as an AudioParam if it
-     * exposes the ramp scheduling methods. Avoids `instanceof AudioParam` so it
-     * works under the standardized-audio-context mock (which may lack the global).
-     */
-    private _isAudioParam;
     /**
      * Connect this bus's output to another bus or to a raw AudioNode.
      *
@@ -258,32 +236,5 @@ export declare class Bus {
     destroy(options?: {
         drainTo?: Bus;
     }): void;
-    /**
-     * Reconcile the live chain to `input → [filter1 → ... → filterN] → output`.
-     * Called after any add/remove/reorder of a filter. This is an INCREMENTAL
-     * diff, not a full rebuild: it disconnects only edges that are no longer part
-     * of the desired chain and connects only edges that are newly required,
-     * leaving edges present in both the old and new chain connected and
-     * untouched (no audible click on the unchanged portion of the chain).
-     *
-     * Edges are matched by OBJECT IDENTITY on both endpoints. Only this bus's own
-     * internal `input → ... → output` edges are touched — never a broad
-     * `node.disconnect()`, never the outbound send/direct edges.
-     */
-    private _refreshFilters;
-    /**
-     * Compute the desired ordered chain edge list from the current
-     * `_filterEntries`, skipping any node in {@link _bypassedFilters}: the series
-     * chain is built over the NON-bypassed filters only. With no active (non-
-     * bypassed) filters — whether the bus has no filters at all or every filter is
-     * bypassed — the desired list is `[[input, output]]` (the direct edge);
-     * otherwise `[[input, a1], [a1, a2], ..., [aN, output]]` over the active
-     * filters `a1..aN`. Bypassed nodes stay in {@link _filterEntries} (and thus in
-     * {@link filters}) but receive no inbound/outbound chain edge.
-     */
-    private _desiredFilterChainEdges;
-    private _normalizeBuiltEffect;
-    private _connectFilterChainEdge;
-    private _disconnectFilterChainEdges;
     private _throwIfDestroyed;
 }

package/dist/cache.d.ts

@@ -33,11 +33,19 @@ export interface ICache {
  * ```
  */
 export declare class AudioCache implements ICache {
-    private static pendingRequests;
-    private static pendingCallbacks;
-    private static decodedBuffers;
+    private pendingRequests;
+    private pendingCallbacks;
+    private decodedBuffers;
     private static cacheExpirationTime;
     static setCacheExpirationTime(time: number): void;
+    /**
+     * Whether the browser Cache API (`caches`) global is available in the
+     * current runtime. Uses `typeof` so it never throws when the global is
+     * entirely absent (e.g. Node). When this returns `false`, the URL path
+     * degrades to fetch + decode (still using the in-memory LRU) instead of
+     * touching the persistent Cache API.
+     */
+    private static isCacheApiAvailable;
     private static openCache;
     /**
      * Calls all registered callbacks for a specific event type on a URL.
@@ -45,10 +53,10 @@ export declare class AudioCache implements ICache {
      * the canonical {@link CacheCallbacks} shape rather than `any`.
      */
     private static callAllCallbacks;
-    private static getOrCreatePendingRequest;
+    private getOrCreatePendingRequest;
     private static updateMetadata;
     private static getBufferFromCache;
-    private static fetchAndCacheBuffer;
+    private fetchAndCacheBuffer;
     /**
      * Atomically write a response body and its metadata into the cache.
      * On failure, deletes both partial entries (best-effort via `allSettled`)
@@ -65,13 +73,31 @@ export declare class AudioCache implements ICache {
      * @param signal - Optional AbortSignal observed at chunk boundaries
      * @returns Object containing the progress-tracking stream and total size
      */
-    private static createProgressTrackingStream;
+    private createProgressTrackingStream;
     /**
      * Collects all chunks from a ReadableStream into a single ArrayBuffer
      * @param stream - The ReadableStream to collect from
      * @returns Promise that resolves to the complete ArrayBuffer
      */
     private static collectStreamToArrayBuffer;
+    /**
+     * Fetch + decode an audio URL WITHOUT touching the persistent Cache API.
+     * Used when the Cache API global (`caches`) is unavailable (e.g. Node).
+     *
+     * Mirrors the network branch of {@link fetchAndCacheBuffer}/{@link getAudioBuffer}
+     * but never reads from or writes to `caches`. Still:
+     * - uses the in-memory decoded-buffer LRU (write happens in {@link getAudioBuffer}),
+     * - emits progress callbacks via {@link createProgressTrackingStream},
+     * - is deduped through {@link getOrCreatePendingRequest} by the caller.
+     */
+    private fetchAndDecodeWithoutCache;
+    /**
+     * Run the shared network-result pipeline: fetch bytes, decode them, emit
+     * loading callbacks, and retain the decoded buffer in the in-memory LRU.
+     * The caller supplies the fetch strategy so persistent-cache and degraded
+     * runtimes share this plumbing without changing their network behavior.
+     */
+    private fetchDecodeAndCache;
     private static decodeAudioData;
     private static getMetadataFromCache;
     /**