cacophony 0.15.2 → 0.16.1

package/README.md

@@ -5,16 +5,16 @@ Cacophony is a powerful and intuitive audio library designed for modern web appl
 
 ## Key Features
 
-- **Versatile Audio Source Handling**: Manage audio from various sources including `AudioBuffer`, URL strings, synthesizers, and live microphone input.
-- **Comprehensive Playback Control**: Play, stop, pause, resume, loop, and seek within audio with ease.
-- **3D Audio Positioning**: Create immersive soundscapes with precise spatial audio control.
-- **Advanced Audio Processing**: Apply and manage a variety of audio filters for enhanced sound manipulation.
-- **Dynamic Volume Control**: Adjust global and individual volume levels with support for smooth fading effects.
-- **Synthesizer Integration**: Create and manipulate synthesized sounds with customizable oscillator options.
-- **Efficient Group Management**: Organize and control multiple sounds or synthesizers as groups for streamlined audio management.
-- **Live Microphone Input**: Capture and process real-time audio input from the user's microphone.
-- **Audio Streaming**: Support for streaming audio directly from URLs.
-- **Flexible Caching**: Implement efficient audio caching strategies for improved performance.
+- **Versatile Audio Source Handling**: Manage audio from various sources including `AudioBuffer`, URL strings, synthesizers, and live microphone input
+- **Comprehensive Playback Control**: Play, stop, pause, resume, loop, and seek within audio with ease
+- **3D Audio Positioning**: Create immersive soundscapes with precise spatial audio control
+- **Advanced Audio Processing**: Apply and manage a variety of audio filters for enhanced sound manipulation
+- **Dynamic Volume Control**: Adjust global and individual volume levels with support for smooth fading effects
+- **Synthesizer Integration**: Create and manipulate synthesized sounds with customizable oscillator options
+- **Efficient Group Management**: Organize and control multiple sounds or synthesizers as groups for streamlined audio management
+- **Live Microphone Input**: Capture and process real-time audio input from the user's microphone
+- **Audio Streaming**: Support for streaming audio directly from URLs
+- **Flexible Caching**: Implement efficient audio caching strategies for improved performance
 
 ## Installation
 
@@ -29,7 +29,7 @@ import { Cacophony } from 'cacophony';
 
 async function audioDemo() {
   const cacophony = new Cacophony();
-  
+
   // Create and play a sound with 3D positioning
   const sound = await cacophony.createSound('path/to/audio.mp3');
   sound.play();
@@ -55,47 +55,556 @@ async function audioDemo() {
 audioDemo();
 ```
 
-## Detailed API Documentation
+## Core Concepts
+
+### Sound vs Playback Architecture
+
+Cacophony uses a two-tier architecture that separates audio assets from their playback instances:
+
+- **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.).
+
+```typescript
+const sound = await cacophony.createSound('laser.mp3');
+
+// Play the same sound three times with different settings
+const [playback1] = sound.play();
+playback1.volume = 0.3;
+playback1.playbackRate = 1.0;
+
+const [playback2] = sound.play();
+playback2.volume = 0.8;
+playback2.playbackRate = 1.5;  // Higher pitched
+
+const [playback3] = sound.play();
+playback3.volume = 0.5;
+playback3.position = [5, 0, 0];  // Positioned to the right
+
+// Control individual playbacks
+setTimeout(() => playback1.pause(), 1000);
+setTimeout(() => playback2.stop(), 2000);
+
+// Or control all playbacks through the Sound
+sound.stop();  // Stops all three playbacks
+```
+
+## Sound Types
+
+Cacophony supports three sound types, each optimized for different use cases:
+
+| 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 | Limited | Background music, large audio files, podcasts |
+| **Streaming** | Low | Medium | Limited | No | Internet radio, live streams, very large files |
+
+```typescript
+// Buffer - entire file loaded into memory
+const sfx = await cacophony.createSound('explosion.mp3', SoundType.Buffer);
+
+// HTML - streams from network, good for large files
+const music = await cacophony.createSound('bgm.mp3', SoundType.HTML);
+
+// Streaming - for live streams
+const radio = await cacophony.createStream('https://example.com/stream.m3u8');
+```
+
+## Playback Control
+
+### Seeking
+
+```typescript
+const sound = await cacophony.createSound('podcast.mp3');
+sound.play();
+
+// Seek to 30 seconds
+sound.seek(30);
+
+// Seek on individual playback
+const [playback] = sound.play();
+playback.seek(45);
+
+// Get current time
+console.log(playback.currentTime);  // Current position in seconds
+console.log(playback.duration);     // Total duration
+```
+
+### Playback Rate
+
+Control the speed of playback (affects pitch):
+
+```typescript
+const sound = await cacophony.createSound('audio.mp3');
+
+sound.playbackRate = 1.0;   // Normal speed
+sound.playbackRate = 2.0;   // Double speed (higher pitch)
+sound.playbackRate = 0.5;   // Half speed (lower pitch)
+
+// Apply to individual playback
+const [playback] = sound.play();
+playback.playbackRate = 1.25;
+```
+
+### Looping
+
+```typescript
+const sound = await cacophony.createSound('music.mp3');
+
+// Loop indefinitely
+sound.loop('infinite');
+sound.play();
+
+// Loop exactly 3 times
+sound.loop(3);
+sound.play();
+
+// No looping (default)
+sound.loop(0);
+```
+
+## Volume Control
+
+Cacophony provides a hierarchical volume control system:
+
+```typescript
+const cacophony = new Cacophony();
+const sound = await cacophony.createSound('audio.mp3');
+const [playback] = sound.play();
+
+// Global volume (affects all audio)
+cacophony.volume = 0.5;  // 50% of original volume
 
-For a comprehensive overview of all classes, methods, and features, please refer to our [detailed documentation](https://cacophony.js.org).
+// Sound volume (affects all playbacks of this sound)
+sound.volume = 0.8;      // 80% of global volume
+
+// Individual playback volume
+playback.volume = 0.6;   // 60% of sound volume
+
+// Final volume = global × sound × playback = 0.5 × 0.8 × 0.6 = 0.24
+
+// Mute/unmute
+cacophony.mute();
+cacophony.unmute();
+```
 
 ## Audio Filters
 
-Cacophony provides powerful audio filtering capabilities:
+Cacophony provides powerful audio filtering capabilities using BiquadFilterNode. Filters can be applied to Sounds, Synths, Playbacks, and Groups.
+
+Supported filter types: `lowpass`, `highpass`, `bandpass`, `lowshelf`, `highshelf`, `peaking`, `notch`, `allpass`.
 
 ```typescript
 const cacophony = new Cacophony();
+const sound = await cacophony.createSound('audio.mp3');
 
-// Create a lowpass filter
-const lowpassFilter = cacophony.createBiquadFilter({
-  type: 'lowpass',
-  frequency: 1000,
-  Q: 1
-});
+// Create filters
+const lowpass = cacophony.createBiquadFilter({ type: 'lowpass', frequency: 1000, Q: 1 });
+const highshelf = cacophony.createBiquadFilter({ type: 'highshelf', frequency: 5000, gain: -6 });
 
-// Apply filter to a Sound
-const sound = await cacophony.createSound('path/to/audio.mp3');
-sound.addFilter(lowpassFilter);
-sound.play();
+// Apply filters (they are chained in order)
+sound.addFilter(lowpass);
+sound.addFilter(highshelf);
 
-// Apply filter to a Synth
+// Apply to Synth
 const synth = cacophony.createOscillator({ frequency: 440, type: 'sawtooth' });
-synth.addFilter(lowpassFilter);
-synth.play();
+synth.addFilter(lowpass);
+
+// Remove filters
+sound.removeFilter(lowpass);
+```
+
+See [TypeDoc](https://cacophony.js.org) for complete filter parameters and options.
+
+## 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.
+
+### Accessing the Audio Graph
+
+Every Playback instance exposes its output node and standard Web Audio connection methods:
+
+```typescript
+const sound = await cacophony.createSound('audio.mp3');
+const [playback] = sound.play();
+
+// Access the output node (final node in the internal chain)
+const outputNode = playback.outputNode;  // Returns GainNode
+
+// Connect to custom destination
+const customEffect = cacophony.context.createDelay(0.5);
+playback.connect(customEffect);
+customEffect.connect(cacophony.context.destination);
+
+// Disconnect from default routing
+playback.disconnect();  // Disconnect from all
+playback.disconnect(specificNode);  // Disconnect from specific node
+```
+
+### Building Effect Chains
+
+Route playbacks through multiple effects:
+
+```typescript
+const sound = await cacophony.createSound('guitar.mp3');
+const [playback] = sound.play();
+
+// Create effect nodes
+const distortion = cacophony.context.createWaveShaper();
+const delay = cacophony.context.createDelay(1.0);
+const reverb = cacophony.context.createConvolver();
+
+// Chain: playback → distortion → delay → reverb → destination
+playback.disconnect();  // Disconnect from default
+playback.connect(distortion)
+        .connect(delay)
+        .connect(reverb)
+        .connect(cacophony.context.destination);
+```
+
+### Parallel Effects (Send/Return)
+
+Create parallel effect sends like a mixing console:
+
+```typescript
+const sound = await cacophony.createSound('vocals.mp3');
+const [playback] = sound.play();
+
+// Create send effects
+const reverb = cacophony.context.createConvolver();
+const reverbReturn = cacophony.context.createGain();
+reverbReturn.gain.value = 0.3;  // 30% wet
+
+// Dry signal to destination
+playback.connect(cacophony.context.destination);
+
+// Parallel wet signal: playback → reverb → reverbReturn → destination
+playback.connect(reverb)
+        .connect(reverbReturn)
+        .connect(cacophony.context.destination);
+```
+
+### Dynamic Routing
+
+Change routing in real-time:
+
+```typescript
+const sound = await cacophony.createSound('audio.mp3');
+const [playback] = sound.play();
+
+const cleanPath = cacophony.context.destination;
+const fxPath = cacophony.context.createConvolver();
+fxPath.connect(cacophony.context.destination);
+
+// Toggle between clean and effects
+let useFx = false;
+button.addEventListener('click', () => {
+  playback.disconnect();
+
+  if (useFx) {
+    playback.connect(fxPath);
+  } else {
+    playback.connect(cleanPath);
+  }
+
+  useFx = !useFx;
+});
+```
+
+### Integrating with Web Audio Nodes
+
+Cacophony works seamlessly with any Web Audio API nodes:
+
+```typescript
+const [playback] = sound.play();
+
+// Built-in nodes
+const analyser = cacophony.context.createAnalyser();
+const compressor = cacophony.context.createDynamicsCompressor();
+const panner = cacophony.context.createStereoPanner();
+
+// AudioWorklet processors
+const customProcessor = new AudioWorkletNode(cacophony.context, 'my-processor');
+
+// Chain them together
+playback.disconnect();
+playback.connect(compressor)
+        .connect(analyser)
+        .connect(panner)
+        .connect(customProcessor)
+        .connect(cacophony.context.destination);
+
+// Visualize with analyser
+const dataArray = new Uint8Array(analyser.frequencyBinCount);
+function draw() {
+  analyser.getByteFrequencyData(dataArray);
+  // ... draw visualization
+  requestAnimationFrame(draw);
+}
+```
+
+### Architecture Notes
+
+- **Internal chain**: `source → panner → [filters] → gainNode`
+- **outputNode** exposes the final `gainNode` in this chain
+- Default routing: `outputNode → globalGainNode → destination`
+- Calling `disconnect()` breaks the default routing, allowing full manual control
+
+## Cloning
+
+Clone sounds to create variations without reloading files. Clones share the same AudioBuffer but have independent settings.
+
+```typescript
+const footstep = await cacophony.createSound('footstep.mp3');
+
+// Create variations for different enemy sizes
+const largeEnemy = footstep.clone({
+  position: [10, 0, -5],
+  playbackRate: 0.8,  // Slower/lower pitch
+  volume: 0.9
+});
+
+const smallEnemy = footstep.clone({
+  position: [-5, 0, -10],
+  playbackRate: 1.25,  // Faster/higher pitch
+  volume: 0.4
+});
+
+largeEnemy.play();
+smallEnemy.play();
+
+// Weapon sound variants
+const gunshotBase = await cacophony.createSound('gunshot.mp3');
+
+const weapons = {
+  pistol: gunshotBase.clone({ volume: 0.6, playbackRate: 1.2 }),
+  rifle: gunshotBase.clone({ volume: 1.0, playbackRate: 1.0 }),
+  shotgun: gunshotBase.clone({
+    volume: 1.2,
+    playbackRate: 0.8,
+    filters: [cacophony.createBiquadFilter({ type: 'lowpass', frequency: 1200 })]
+  })
+};
+
+// Musical instrument samples by pitch-shifting
+const pianoC4 = await cacophony.createSound('piano_c4.mp3');
+const keyboard = {
+  C4: pianoC4,
+  D4: pianoC4.clone({ playbackRate: 1.122 }),  // +2 semitones
+  E4: pianoC4.clone({ playbackRate: 1.260 }),  // +4 semitones
+  F4: pianoC4.clone({ playbackRate: 1.335 }),  // +5 semitones
+  G4: pianoC4.clone({ playbackRate: 1.498 }),  // +7 semitones
+};
+```
+
+## Group Functionality
+
+Groups allow controlling multiple sounds or synthesizers as a single unit.
+
+```typescript
+const cacophony = new Cacophony();
+
+// Create from URLs
+const soundGroup = await cacophony.createGroupFromUrls(['drum.mp3', 'bass.mp3', 'synth.mp3']);
+
+// Or create from existing Sound instances
+const sound1 = await cacophony.createSound('drum.mp3');
+const sound2 = await cacophony.createSound('bass.mp3');
+const sound3 = await cacophony.createSound('synth.mp3');
+const soundGroup2 = await cacophony.createGroup([sound1, sound2, sound3]);
+
+// Play all sounds simultaneously
+soundGroup.play();
+
+// Control all sounds at once
+soundGroup.volume = 0.7;
+soundGroup.playbackRate = 1.2;
+soundGroup.position = [5, 0, 0];
+soundGroup.loop('infinite');
+
+// Apply filters to entire group
+const lowpass = cacophony.createBiquadFilter({ type: 'lowpass', frequency: 1000 });
+soundGroup.addFilter(lowpass);
+
+// Play random sound from group
+const footsteps = await cacophony.createGroupFromUrls([
+  'footstep1.mp3',
+  'footstep2.mp3',
+  'footstep3.mp3',
+  'footstep4.mp3'
+]);
+
+footsteps.playRandom();  // Picks one at random
+
+// Play sounds in sequence
+const dialog = await cacophony.createGroupFromUrls(['line1.mp3', 'line2.mp3', 'line3.mp3']);
+dialog.playOrdered(true);  // Plays: 1, 2, 3, 1, 2, 3...
+
+// SynthGroup for synthesizers
+const synthGroup = new SynthGroup();
+const synth1 = cacophony.createOscillator({ frequency: 440, type: 'sine' });
+const synth2 = cacophony.createOscillator({ frequency: 660, type: 'square' });
+synthGroup.addSynth(synth1);
+synthGroup.addSynth(synth2);
+synthGroup.play();
+synthGroup.setVolume(0.5);
+
+// Remove a synth from the group
+synthGroup.removeSynth(synth1);
+```
+
+## Synthesizer Functionality
+
+Create oscillator-based sounds with four waveform types: `sine`, `square`, `sawtooth`, `triangle`.
+
+```typescript
+const cacophony = new Cacophony();
+
+// Create oscillators
+const sineOsc = cacophony.createOscillator({ frequency: 440, type: 'sine' });
+sineOsc.play();
+
+// Change parameters in real-time
+sineOsc.frequency = 880;  // Change frequency
+sineOsc.type = 'sawtooth';  // Change waveform
+sineOsc.detune = 10;  // Detune in cents (1/100th of a semitone)
+
+// Layer multiple oscillators
+const bass = cacophony.createOscillator({ frequency: 110, type: 'sine' });
+const lead = cacophony.createOscillator({ frequency: 440, type: 'sawtooth' });
+bass.volume = 0.7;
+lead.volume = 0.5;
+bass.addFilter(cacophony.createBiquadFilter({ type: 'lowpass', frequency: 1000 }));
+bass.play();
+lead.play();
+
+// Modulate frequency over time
+let time = 0;
+setInterval(() => {
+  const frequency = 440 + Math.sin(time) * 100;
+  sineOsc.frequency = frequency;
+  time += 0.1;
+}, 50);
+```
+
+## 3D Audio Positioning
+
+Create immersive soundscapes with precise spatial audio control using HRTF (Head-Related Transfer Function) or stereo panning.
+
+```typescript
+const cacophony = new Cacophony();
+
+// Create sounds with HRTF panning
+const ambience = await cacophony.createSound('forest_ambience.mp3', SoundType.Buffer, 'HRTF');
+const birdSound = await cacophony.createSound('bird_chirp.mp3', SoundType.Buffer, 'HRTF');
+const footsteps = await cacophony.createSound('footsteps.mp3', SoundType.Buffer, 'HRTF');
+
+// Position sounds in 3D space
+// Coordinate system: X (left- to right+), Y (down- to up+), Z (front+ to back-)
+ambience.position = [0, 0, -5];  // Slightly behind the listener
+birdSound.position = [10, 5, 0];  // To the right and above
+footsteps.position = [-2, -1, 2];  // Slightly to the left and in front
+
+// Configure distance attenuation
+birdSound.threeDOptions = {
+  distanceModel: 'inverse',  // 'linear', 'inverse', or 'exponential'
+  refDistance: 1,
+  rolloffFactor: 1
+};
+
+// Play the sounds
+ambience.play();
+birdSound.play();
+footsteps.play();
+
+// Set listener position and orientation
+cacophony.listenerPosition = [0, 0, 0];
+cacophony.listenerOrientation = {
+  forward: [0, 0, -1],  // Looking towards negative Z
+  up: [0, 1, 0]
+};
+
+// Animate bird sound position
+let time = 0;
+setInterval(() => {
+  const x = Math.sin(time) * 10;
+  birdSound.position = [x, 5, 0];
+  time += 0.05;
+}, 50);
+
+// Stereo panning (simple left-right)
+const stereoSound = await cacophony.createSound('audio.mp3', SoundType.Buffer, 'stereo');
+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.
+
+## Microphone Input
+
+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;
+
+  // Pause and resume
+  setTimeout(() => {
+    micStream.pause();
+    setTimeout(() => micStream.resume(), 2000);
+  }, 5000);
+
+} catch (error) {
+  console.error("Error accessing microphone:", error);
+}
+```
+
+## Audio Streaming
+
+Stream audio content efficiently:
+
+```typescript
+const cacophony = new Cacophony();
+
+try {
+  const streamedSound = await cacophony.createStream('https://example.com/live_radio_stream');
+  streamedSound.play();
+
+  // Apply real-time effects to the stream
+  const highPassFilter = cacophony.createBiquadFilter({ type: 'highpass', frequency: 500 });
+  streamedSound.addFilter(highPassFilter);
+
+  // Control streaming playback
+  setTimeout(() => {
+    streamedSound.pause();
+    setTimeout(() => streamedSound.play(), 5000);
+  }, 10000);
+
+} catch (error) {
+  console.error("Error streaming audio:", error);
+}
 ```
 
 ## Event System
 
-Cacophony provides a comprehensive event system for monitoring loading progress, cache performance, and audio playback state:
+Cacophony provides a comprehensive event system for monitoring loading progress, cache performance, and audio playback state.
 
 ### Loading Progress
 
-Track download progress with real-time updates:
-
 ```typescript
 const cacophony = new Cacophony();
 
-// Show loading progress
 cacophony.on('loadingStart', (event) => {
   console.log(`Started loading: ${event.url}`);
   showSpinner();
@@ -103,7 +612,6 @@ cacophony.on('loadingStart', (event) => {
 
 cacophony.on('loadingProgress', (event) => {
   const percent = event.progress * 100;
-  console.log(`Progress: ${percent.toFixed(1)}%`);
   updateProgressBar(event.progress);
 });
 
@@ -117,8 +625,6 @@ const sound = await cacophony.createSound('large-audio-file.mp3');
 
 ### Error Handling
 
-Handle loading and playback errors:
-
 ```typescript
 // Global error handling
 cacophony.on('loadingError', (event) => {
@@ -130,31 +636,15 @@ cacophony.on('loadingError', (event) => {
 sound.on('soundError', (event) => {
   if (event.recoverable) {
     console.log('Retrying...');
-    sound.play(); // Retry playback
+    sound.play();
   } else {
     console.error('Unrecoverable error:', event.error);
   }
 });
 ```
 
-### Cache Monitoring
-
-Monitor cache performance:
-
-```typescript
-cacophony.on('cacheHit', (event) => {
-  console.log(`Cache hit: ${event.url} (${event.cacheType})`);
-});
-
-cacophony.on('cacheMiss', (event) => {
-  console.log(`Cache miss: ${event.url} (${event.reason})`);
-});
-```
-
 ### Global Playback Events
 
-Track all audio activity across your application:
-
 ```typescript
 // Monitor all playback globally
 cacophony.on('globalPlay', (event) => {
@@ -170,20 +660,10 @@ cacophony.on('globalStop', (event) => {
 cacophony.on('globalPause', (event) => {
   console.log('Audio paused:', event.source);
 });
-
-// Use case: pause all audio when app backgrounds
-document.addEventListener('visibilitychange', () => {
-  if (document.hidden) {
-    // Global events let you track what's playing without manual state management
-    console.log('App backgrounded - track via global events');
-  }
-});
 ```
 
 ### Playback Events
 
-React to playback state changes:
-
 ```typescript
 const sound = await cacophony.createSound('audio.mp3');
 
@@ -199,14 +679,42 @@ sound.on('pause', () => {
 sound.on('volumeChange', (volume) => {
   updateVolumeSlider(volume);
 });
+
+// Playback instance events
+const [playback] = sound.play();
+playback.on('play', (pb) => {
+  console.log('Playback started:', pb.currentTime);
+});
+
+playback.on('error', (event) => {
+  if (event.recoverable) {
+    console.log('Recoverable error, retrying...');
+    playback.play();
+  }
+});
+```
+
+### Synth Events
+
+```typescript
+const synth = cacophony.createOscillator({ frequency: 440, type: 'sine' });
+
+synth.on('frequencyChange', (freq) => {
+  console.log('Frequency changed to:', freq, 'Hz');
+});
+
+synth.on('typeChange', (type) => {
+  console.log('Waveform changed to:', type);
+});
+
+synth.frequency = 880;  // Triggers frequencyChange event
+synth.type = 'square';  // Triggers typeChange event
 ```
 
 ### Complete Event Reference
 
 #### Cacophony Events
 
-The main Cacophony instance emits global events for loading, caching, and errors:
-
 | Event | Payload | Description |
 |-------|---------|-------------|
 | `loadingStart` | `LoadingStartEvent` | Fired when audio loading begins. Contains `url` and `timestamp`. |
@@ -219,274 +727,170 @@ The main Cacophony instance emits global events for loading, caching, and errors
 | `globalPlay` | `GlobalPlaybackEvent` | Fired when any Sound or Synth starts playing. Contains `source`, `timestamp`. |
 | `globalStop` | `GlobalPlaybackEvent` | Fired when any Sound or Synth stops. Contains `source`, `timestamp`. |
 | `globalPause` | `GlobalPlaybackEvent` | Fired when any Sound or Synth pauses. Contains `source`, `timestamp`. |
+| `volumeChange` | `number` | Fired when global volume changes. Receives new volume value. |
+| `mute` | `void` | Fired when audio is muted globally. |
+| `unmute` | `void` | Fired when audio is unmuted globally. |
+| `suspend` | `void` | Fired when audio context is suspended. |
+| `resume` | `void` | Fired when audio context is resumed. |
 
 #### Sound Events
 
-Sound instances emit events for playback state and property changes:
-
 | Event | Payload | Description |
 |-------|---------|-------------|
 | `play` | `Playback` | Fired when sound starts playing. Receives the Playback instance. |
 | `stop` | `void` | Fired when sound stops. |
 | `pause` | `void` | Fired when sound pauses. |
+| `resume` | `void` | Fired when sound resumes after being paused. |
+| `ended` | `void` | Fired when sound playback ends naturally. |
+| `loopEnd` | `void` | Fired when a loop iteration completes. |
 | `volumeChange` | `number` | Fired when volume changes. Receives new volume value. |
 | `rateChange` | `number` | Fired when playback rate changes. Receives new rate value. |
 | `soundError` | `SoundErrorEvent` | Fired on playback errors. Contains `url`, `error`, `errorType`, `timestamp`, `recoverable`. |
 
 #### Playback Events
 
-Individual Playback instances emit fine-grained playback events:
-
 | Event | Payload | Description |
 |-------|---------|-------------|
 | `play` | `BasePlayback` | Fired when playback starts. Receives the Playback instance. |
 | `stop` | `void` | Fired when playback stops. |
+| `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 when playback position changes. Receives new time in seconds. |
+| `volumeChange` | `number` | Fired when playback volume changes. Receives new volume value. |
 | `error` | `PlaybackErrorEvent` | Fired on playback errors. Contains `error`, `errorType`, `timestamp`, `recoverable`. |
 
-```typescript
-const sound = await cacophony.createSound('audio.mp3');
-const [playback] = sound.play();
-
-playback.on('play', (pb) => {
-  console.log('Playback started:', pb.currentTime);
-});
-
-playback.on('error', (event) => {
-  if (event.recoverable) {
-    console.log('Recoverable error, retrying...');
-    playback.play();
-  }
-});
-```
-
 #### Synth Events
 
-Synth instances emit events for synthesis parameter changes:
-
 | Event | Payload | Description |
 |-------|---------|-------------|
 | `play` | `SynthPlayback` | Fired when synth starts playing. Receives the SynthPlayback instance. |
 | `stop` | `void` | Fired when synth stops. |
 | `pause` | `void` | Fired when synth pauses. |
+| `resume` | `void` | Fired when synth resumes after being paused. |
+| `ended` | `void` | Fired when synth playback ends naturally. |
 | `frequencyChange` | `number` | Fired when frequency changes. Receives new frequency in Hz. |
 | `typeChange` | `OscillatorType` | Fired when waveform type changes. Receives new type ('sine'\|'square'\|'sawtooth'\|'triangle'). |
 | `detuneChange` | `number` | Fired when detune changes. Receives new detune value in cents. |
 | `volumeChange` | `number` | Fired when volume changes. Receives new volume value. |
 | `error` | `PlaybackErrorEvent` | Fired on playback errors. Contains `error`, `errorType`, `timestamp`, `recoverable`. |
 
-```typescript
-const synth = cacophony.createOscillator({ frequency: 440, type: 'sine' });
+## Caching
 
-synth.on('frequencyChange', (freq) => {
-  console.log('Frequency changed to:', freq, 'Hz');
-  updateFrequencyDisplay(freq);
-});
+Cacophony implements intelligent three-layer caching for optimal performance:
 
-synth.on('typeChange', (type) => {
-  console.log('Waveform changed to:', type);
-  updateWaveformDisplay(type);
-});
-
-synth.frequency = 880; // Triggers frequencyChange event
-synth.type = 'square'; // Triggers typeChange event
-```
-
-## Synthesizer Functionality
+**Memory Cache (LRU)** → **Browser Cache API** → **Network**
 
-Create and manipulate synthesized sounds with advanced control:
+The cache system is fully automatic and HTTP-compliant, respecting standard cache headers (ETag, Last-Modified). When cache validation tokens are available, Cacophony makes lightweight conditional requests (304 responses have no body). When tokens are unavailable, it falls back to TTL-based caching (24 hours default).
 
 ```typescript
 const cacophony = new Cacophony();
 
-// Create a simple sine wave oscillator
-const sineOsc = cacophony.createOscillator({ frequency: 440, type: 'sine' });
-sineOsc.play();
-
-// Create a complex sound with multiple oscillators
-const complexSynth = cacophony.createOscillator({ frequency: 220, type: 'sawtooth' });
-const subOsc = cacophony.createOscillator({ frequency: 110, type: 'sine' });
-complexSynth.addFilter(cacophony.createBiquadFilter({ type: 'lowpass', frequency: 1000 }));
-complexSynth.play();
-subOsc.play();
-
-// Modulate frequency over time
-let time = 0;
-setInterval(() => {
-  const frequency = 440 + Math.sin(time) * 100;
-  sineOsc.frequency = frequency;
-  time += 0.1;
-}, 50);
-
-// Apply envelope to volume
-complexSynth.volume = 0;
-complexSynth.fadeIn(0.5, 'linear');
-setTimeout(() => complexSynth.fadeOut(1, 'exponential'), 2000);
-```
+// First load - fetches from network, stores in cache
+const sound1 = await cacophony.createSound('audio.mp3');
 
-## Group Functionality
+// Second load - instant from memory cache
+const sound2 = await cacophony.createSound('audio.mp3');
 
-Efficiently manage and control multiple sounds or synthesizers:
-
-```typescript
-const cacophony = new Cacophony();
-
-// Create a group of sounds
-const soundGroup = await cacophony.createGroupFromUrls(['drum.mp3', 'bass.mp3', 'synth.mp3']);
+// Monitor cache performance via events
+cacophony.on('cacheHit', (event) => {
+  console.log(`${event.cacheType} cache hit: ${event.url}`);
+  // cacheType: 'memory' | 'browser' | 'conditional'
+});
 
-// Play all sounds in the group
-soundGroup.play();
+cacophony.on('cacheMiss', (event) => {
+  console.log(`Cache miss: ${event.url} - ${event.reason}`);
+  // reason: 'not-found' | 'expired' | 'invalid'
+});
 
-// Control volume for all sounds
-soundGroup.volume = 0.7;
+// Clear memory cache (browser cache persists)
+cacophony.clearMemoryCache();
 
-// Apply 3D positioning to the entire group
-soundGroup.position = [1, 0, -1];
+// Optional: configure TTL for when no validation tokens exist
+import { AudioCache } from 'cacophony';
+AudioCache.setCacheExpirationTime(60 * 60 * 1000); // 1 hour
+```
 
-// Create a group of synthesizers
-const synthGroup = new SynthGroup();
-const synth1 = cacophony.createOscillator({ frequency: 440, type: 'sine' });
-const synth2 = cacophony.createOscillator({ frequency: 660, type: 'square' });
-synthGroup.addSynth(synth1);
-synthGroup.addSynth(synth2);
+The caching system requires no configuration in most cases. It automatically optimizes for performance while respecting HTTP standards.
 
-// Play and control all synths in the group
-synthGroup.play();
-synthGroup.setVolume(0.5);
-synthGroup.stereoPan = -0.3; // Pan slightly to the left
+## Cancellation with AbortSignal
 
-// Remove a synth from the group
-synthGroup.removeSynth(synth2);
-```
+Cancel audio loading operations:
 
-## Microphone Input
+```typescript
+const controller = new AbortController();
 
-Capture, process, and manipulate live audio input:
+const soundPromise = cacophony.createSound(
+  'large-file.mp3',
+  SoundType.Buffer,
+  'HRTF',
+  controller.signal
+);
 
-```typescript
-const cacophony = new Cacophony();
+// Cancel loading
+router.on('navigate', () => controller.abort());
 
-async function setupMicrophone() {
-  try {
-    const micStream = await cacophony.getMicrophoneStream();
-    micStream.play();
-
-    // Apply a low-pass filter to the microphone input
-    const lowPassFilter = cacophony.createBiquadFilter({ type: 'lowpass', frequency: 1000 });
-    micStream.addFilter(lowPassFilter);
-
-    // Add a delay effect
-    const delayFilter = cacophony.createBiquadFilter({ type: 'delay', delayTime: 0.5 });
-    micStream.addFilter(delayFilter);
-
-    // Control microphone volume
-    micStream.volume = 0.8;
-
-    // Pause and resume microphone input
-    setTimeout(() => {
-      micStream.pause();
-      console.log("Microphone paused");
-      setTimeout(() => {
-        micStream.resume();
-        console.log("Microphone resumed");
-      }, 2000);
-    }, 5000);
-
-  } catch (error) {
-    console.error("Error accessing microphone:", error);
+try {
+  const sound = await soundPromise;
+  sound.play();
+} catch (error) {
+  if (error.name === 'AbortError') {
+    console.log('Loading was cancelled');
   }
 }
 
-setupMicrophone();
+// Works with groups too
+const group = await cacophony.createGroupFromUrls(
+  ['a.mp3', 'b.mp3', 'c.mp3'],
+  SoundType.Buffer,
+  'HRTF',
+  controller.signal
+);
 ```
 
-## 3D Audio Positioning
+## Resource Management
 
-Create immersive soundscapes with precise spatial audio control:
+Call `cleanup()` when done with sounds to free resources:
 
 ```typescript
-const cacophony = new Cacophony();
-
-async function create3DAudioScene() {
-  // Create sounds with HRTF panning
-  const ambience = await cacophony.createSound('forest_ambience.mp3', SoundType.Buffer, 'HRTF');
-  const birdSound = await cacophony.createSound('bird_chirp.mp3', SoundType.Buffer, 'HRTF');
-  const footsteps = await cacophony.createSound('footsteps.mp3', SoundType.Buffer, 'HRTF');
-
-  // Position sounds in 3D space
-  ambience.position = [0, 0, -5]; // Slightly behind the listener
-  birdSound.position = [10, 5, 0]; // To the right and above
-  footsteps.position = [-2, -1, 2]; // Slightly to the left and in front
-
-  // Play the sounds
-  ambience.play();
-  birdSound.play();
-  footsteps.play();
-
-  // Update listener position and orientation
-  cacophony.listenerPosition = [0, 0, 0];
-  cacophony.listenerOrientation = {
-    forward: [0, 0, -1],
-    up: [0, 1, 0]
-  };
-
-  // Animate bird sound position
-  let time = 0;
-  setInterval(() => {
-    const x = Math.sin(time) * 10;
-    birdSound.position = [x, 5, 0];
-    time += 0.05;
-  }, 50);
-
-  // Change listener position over time
-  setTimeout(() => {
-    cacophony.listenerPosition = [0, 0, 5];
-    console.log("Listener moved forward");
-  }, 5000);
-}
+const sound = await cacophony.createSound('temp.mp3');
+sound.play();
+sound.cleanup();  // Disconnects nodes, removes playbacks, clears listeners
 
-create3DAudioScene();
+// Clear memory cache
+cacophony.clearMemoryCache();
 ```
 
-## Audio Streaming
+Cacophony uses `FinalizationRegistry` for automatic cleanup when objects are garbage collected, but explicit cleanup is recommended for large applications.
 
-Stream audio content efficiently:
+## Audio Context Control
+
+Suspend and resume the entire audio context to pause all audio processing. Useful for mobile apps when entering background mode or for performance optimization:
 
 ```typescript
 const cacophony = new Cacophony();
 
-async function streamAudio() {
-  try {
-    const streamedSound = await cacophony.createStream('https://example.com/live_radio_stream');
-    streamedSound.play();
-
-    // Apply real-time effects to the stream
-    const highPassFilter = cacophony.createBiquadFilter({ type: 'highpass', frequency: 500 });
-    streamedSound.addFilter(highPassFilter);
-
-    // Control streaming playback
-    setTimeout(() => {
-      streamedSound.pause();
-      console.log("Stream paused");
-      setTimeout(() => {
-        streamedSound.play();
-        console.log("Stream resumed");
-      }, 5000);
-    }, 10000);
-
-  } catch (error) {
-    console.error("Error streaming audio:", error);
-  }
-}
+// Suspend audio context (pauses ALL audio, saves battery)
+cacophony.pause();
+
+// Resume audio context
+cacophony.resume();
 
-streamAudio();
+// Example: pause when app goes to background
+document.addEventListener('visibilitychange', () => {
+  if (document.hidden) {
+    cacophony.pause();
+  } else {
+    cacophony.resume();
+  }
+});
 ```
 
-## Additional Highlights
+Note: This is different from `sound.pause()` which pauses individual sounds. `cacophony.pause()` suspends the entire audio engine.
+
+## API Documentation
 
-- **Efficient Caching**: Implement smart caching strategies for improved performance and reduced bandwidth usage.
-- **Flexible Sound Types**: Support for various sound types including buffered audio, HTML5 audio, and streaming.
-- **Advanced Looping Control**: Fine-grained control over audio looping, including infinite loops and specific loop counts.
-- **Detailed Playback Information**: Access and control various playback parameters such as current time, duration, and playback rate.
+For complete API documentation including all methods, parameters, and options, see the [TypeDoc documentation](https://cacophony.js.org).
 
 ## License