cacophony 0.12.4 → 0.12.6

package/README.md

@@ -1,18 +1,20 @@
 
-## Cacophony: Advanced Browser Audio Library
+# Cacophony: Advanced Browser Audio Library
 
-Cacophony is an intuitive and powerful audio library designed for the modern web. It's built to simplify audio management within browser-based applications, offering a straightforward interface to the Web Audio API. Cacophony is ideal for projects that require detailed audio control, from simple sound playback to complex audio processing and 3D audio positioning.
+Cacophony is a powerful and intuitive audio library designed for modern web applications. It provides a high-level interface to the Web Audio API, simplifying complex audio operations while offering fine-grained control. Cacophony is perfect for projects ranging from simple sound playback to sophisticated audio processing and 3D audio positioning.
 
 ## Key Features
 
-- **Rich Audio Source Management**: Handle audio sources from `AudioBuffer`, URL strings, synthesizers, or user's microphone with ease.
-- **Detailed Audio Control**: Comprehensive control over audio playback including play, stop, pause, resume, and loop.
-- **3D Audio Positioning**: Create immersive audio experiences by positioning sounds in a three-dimensional space.
-- **Advanced Audio Effects**: Apply and manage a variety of audio filters for enhanced sound quality.
-- **Dynamic Volume and Muting**: Global and individual volume control, complete with smooth fade-in and fade-out effects.
-- **Live Audio Input**: Capture and process live audio input from the user's microphone.
-- **Synthesizer Functionality**: Create and manipulate synthesized sounds with customizable oscillator options.
-- **Group Management**: Organize and control multiple sounds or synthesizers as groups for efficient management.
+- **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
 
@@ -25,96 +27,260 @@ npm install cacophony
 ```typescript
 import { Cacophony } from 'cacophony';
 
-async function playSampleSound() {
+async function audioDemo() {
   const cacophony = new Cacophony();
   
-  // Create and play a sound
+  // Create and play a sound with 3D positioning
   const sound = await cacophony.createSound('path/to/audio.mp3');
   sound.play();
-  sound.position = [1, 1, 1]; // Set sound position in 3D space
+  sound.position = [1, 0, -1]; // Set sound position in 3D space
 
   // Create and play a synthesizer
   const synth = cacophony.createOscillator({ frequency: 440, type: 'sine' });
   synth.play();
 
+  // Apply a filter to the synth
+  const filter = cacophony.createBiquadFilter({ type: 'lowpass', frequency: 1000 });
+  synth.addFilter(filter);
+
   // Create a group of sounds
   const group = await cacophony.createGroupFromUrls(['sound1.mp3', 'sound2.mp3']);
   group.play(); // Play all sounds in the group
+
+  // Capture microphone input
+  const micStream = await cacophony.getMicrophoneStream();
+  micStream.play();
 }
 
-playSampleSound();
+audioDemo();
 ```
 
 ## Detailed API Documentation
 
-For a complete overview of all functionality, classes, and methods, please refer to our [detailed documentation](https://cacophony.js.org).
+For a comprehensive overview of all classes, methods, and features, please refer to our [detailed documentation](https://cacophony.js.org).
 
-## Synthesizer Functionality
+## Audio Filters
 
-Cacophony provides powerful synthesizer capabilities through the `Synth` class:
+Cacophony provides powerful audio filtering capabilities:
 
 ```typescript
 const cacophony = new Cacophony();
-const synth = cacophony.createOscillator({ frequency: 440, type: 'sine' });
+
+// Create a lowpass filter
+const lowpassFilter = cacophony.createBiquadFilter({
+  type: 'lowpass',
+  frequency: 1000,
+  Q: 1
+});
+
+// Apply filter to a Sound
+const sound = await cacophony.createSound('path/to/audio.mp3');
+sound.addFilter(lowpassFilter);
+sound.play();
+
+// Apply filter to a Synth
+const synth = cacophony.createOscillator({ frequency: 440, type: 'sawtooth' });
+synth.addFilter(lowpassFilter);
 synth.play();
-synth.frequency = 880; // Change frequency
-synth.type = 'square'; // Change waveform
+```
+
+## Synthesizer Functionality
+
+Create and manipulate synthesized sounds with advanced control:
+
+```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);
 ```
 
 ## Group Functionality
 
-Organize and control multiple sounds or synthesizers with the `Group` and `SynthGroup` classes:
+Efficiently manage and control multiple sounds or synthesizers:
 
 ```typescript
-const soundGroup = await cacophony.createGroupFromUrls(['sound1.mp3', 'sound2.mp3']);
-soundGroup.play(); // Play all sounds in the group
+const cacophony = new Cacophony();
+
+// Create a group of sounds
+const soundGroup = await cacophony.createGroupFromUrls(['drum.mp3', 'bass.mp3', 'synth.mp3']);
 
+// Play all sounds in the group
+soundGroup.play();
+
+// Control volume for all sounds
+soundGroup.volume = 0.7;
+
+// Apply 3D positioning to the entire group
+soundGroup.position = [1, 0, -1];
+
+// 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);
-synthGroup.play(); // Play all synths in the group
+
+// Play and control all synths in the group
+synthGroup.play();
+synthGroup.setVolume(0.5);
+synthGroup.stereoPan = -0.3; // Pan slightly to the left
+
+// Remove a synth from the group
+synthGroup.removeSynth(synth2);
 ```
 
-## Additional Highlights
+## Microphone Input
+
+Capture, process, and manipulate live audio input:
 
-- **Streaming Audio**: Stream live audio directly from a URL.
-- **Volume Transitions**: Employ `fadeIn` and `fadeOut` for nuanced volume control.
-- **Flexible Synthesizer Options**: Create complex sounds with customizable oscillator settings.
-- **Efficient Group Management**: Control multiple audio sources simultaneously for complex audio scenarios.
-- **Audio Filters**: Apply various audio filters, such as lowpass, highpass, and bandpass, to Sounds or Synths and their playbacks.
+```typescript
+const cacophony = new Cacophony();
+
+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);
+  }
+}
+
+setupMicrophone();
+```
 
-## Using Audio Filters
+## 3D Audio Positioning
 
-Cacophony supports applying audio filters to both Sounds and Synths. Here's an example of using a lowpass filter:
+Create immersive soundscapes with precise spatial audio control:
 
 ```typescript
 const cacophony = new Cacophony();
 
-// Create a lowpass filter
-const lowpassFilter = cacophony.createBiquadFilter({
-  type: 'lowpass',
-  frequency: 1000,
-  Q: 1
-});
+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);
+}
 
-// Apply filter to a Sound
-const sound = await cacophony.createSound('path/to/audio.mp3');
-sound.addFilter(lowpassFilter);
-sound.play();
+create3DAudioScene();
+```
 
-// Apply filter to a Synth
-const synth = cacophony.createOscillator({ frequency: 440, type: 'sawtooth' });
-synth.addFilter(lowpassFilter);
-synth.play();
+## Audio Streaming
 
-// Filters affect all playbacks of the Sound or Synth
-const playback1 = sound.play()[0];
-const playback2 = sound.play()[0];
-// Both playback1 and playback2 will have the lowpass filter applied
+Stream audio content efficiently:
+
+```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);
+  }
+}
+
+streamAudio();
 ```
 
-This example demonstrates how to create and apply a lowpass filter to both a Sound and a Synth. The filter affects all playbacks of the Sound or Synth, allowing for consistent audio processing across multiple instances.
+## Additional Highlights
+
+- **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.
 
 ## License
 
-Cacophony is open-source software licensed under the [MIT License](LICENSE.txt)
+Cacophony is open-source software licensed under the [MIT License](LICENSE.txt).