audio-mixer-engine 0.9.0 → 0.9.2

package/README.md

@@ -1,32 +1,14 @@
 # Audio Mixer Engine
 
-A part-centric JavaScript audio library designed for audio mixer applications and mixer interfaces. Provides individual audio outputs per musical part, enabling advanced mixing workflows with per-part gain control, level monitoring, and analysis capabilities.
-
-## Architecture Overview
-
-This library follows a **part-centric mixer design** where each musical part (soprano, alto, tenor, bass, piano, etc.) gets its own:
-- Individual audio output node (`AudioNode`)
-- Independent volume and instrument control
-- Dedicated channel handle for note playback
-- Separate audio analysis capabilities
-
-**Key Design Philosophy**: Rather than mixing audio internally, the library provides individual part outputs that external mixer code can connect to gain controls, analyzers, effects, and routing - enabling sophisticated mixing interfaces.
+A part-centric JavaScript audio library for mixer applications. Provides individual audio outputs per musical part (soprano, alto, piano, etc.) enabling per-part gain control, level monitoring, and flexible routing.
 
 ## Features
 
-- **Part-Centric Architecture**: Each musical part gets independent control and output
-- **Individual Audio Outputs**: Access `AudioNode` outputs for each part for external mixing
-- **Dual Volume Control**: Internal MIDI volume + external gain node control
-- **Real-time Analysis**: Connect part outputs to analyzers for level metering and visualization
-- **MIDI Processing**: Parse and analyze MIDI files with part identification
-- **Audio Synthesis**: SpessaSynth-based engine with soundfont support
-- **Musical Navigation**: Beat mapping with bar-based navigation and real-time position tracking
-- **Advanced Playback**: Metronome, lead-in, and configurable startup timing for perfect synchronization
-- **Event-Driven**: Modern mitt-based event system with structured event data
-- **Master Volume Control**: Global volume management with emergency stop functionality
-- **Interface Compliance**: Full IAudioMixerEngine interface for seamless mixer integration
-- **Mixer Integration**: Designed for solo/mute, gain control, and routing workflows
-- **Initialization Progress Tracking**: Real-time progress events with download progress bars for soundfont loading
+- **Part-centric audio**: Individual `AudioNode` outputs per part with separate gain/analysis routing
+- **MIDI processing**: Parse files, beat/bar mapping, tempo changes, metadata extraction
+- **Dual audio engines**: SpessaSynth (soundfont, ~10-50MB) or Lightweight (samples, ~574KB bundle)
+- **Playback control**: Metronome, lead-in, seeking, speed changes, bar navigation, real-time events
+- **Mixer-ready**: Designed for solo/mute, routing, and level monitoring workflows
 
 ## Installation
 
@@ -34,162 +16,145 @@ This library follows a **part-centric mixer design** where each musical part (so
 npm install audio-mixer-engine
 ```
 
-## Quick Start - Basic Playback
+### Audio Engine Options
+
+- **SpessaSynthAudioEngine**: Soundfont-based synthesis, requires separate soundfont file (~10-50MB)
+- **LightweightAudioEngine**: Sample-based with smaller bundle (~574KB). See [LIGHTWEIGHT_ENGINE.md](./LIGHTWEIGHT_ENGINE.md) for setup.
+
+## Quick Start
 
 ```javascript
-import {
-  SpessaSynthAudioEngine,
-  PlaybackManager
-} from 'audio-mixer-engine';
+import { SpessaSynthAudioEngine, PlaybackManager } from 'audio-mixer-engine';
 
-// Initialize audio context
 const ac = new AudioContext();
 
-// Setup the audio engine - use the spessasynth engine with a soundfont
+// Initialize audio engine
 const audioEngine = new SpessaSynthAudioEngine(ac);
 await audioEngine.initialize('/path/to/soundfont.sf2');
 
-// Create PlaybackManager with optional configuration
+// Create PlaybackManager
 const manager = new PlaybackManager(audioEngine, {
   metronome: { enabled: true, volume: 0.7 },
   leadIn: { enabled: true, bars: 1 },
   startup: { delayMs: 25 }
 });
 
-// Load MIDI data - this parses the file and creates the player automatically
+// Load MIDI file
 await manager.load(midiArrayBuffer);
 
 // Set up event listeners
-manager.on('timeupdate', ({currentTime}) => {
-  console.log(`Playing: ${currentTime.toFixed(2)}s`);
-});
-
-manager.on('beatChanged', ({bar, beat, time}) => {
-  console.log(`Bar ${bar}, Beat ${beat} at ${time.toFixed(2)}s`);
-});
+manager.on('timeupdate', ({currentTime}) => console.log(currentTime));
+manager.on('beatChanged', ({bar, beat}) => console.log(`Bar ${bar}, Beat ${beat}`));
 
-// Setup audio routing - REQUIRED for audio output
+// Setup audio routing (REQUIRED for audio output)
 // Metronome
 const metGain = ac.createGain();
 metGain.gain.value = 0.5;
 manager.getMetronomeOutput().connect(metGain).connect(ac.destination);
 
-// Part outputs using iterator pattern
+// Part outputs
 for (const [partName, outputNode] of manager.getPartOutputs()) {
   const gain = ac.createGain();
   gain.gain.value = 0.75;
   outputNode.connect(gain).connect(ac.destination);
 }
 
-// Start playback with lead-in metronome ticks
+// Start playback
 await manager.play({ leadIn: true, metronome: true });
 ```
 
-## Initialization Progress Tracking
+## Key Concepts
 
-The library provides real-time progress events during initialization, particularly useful for showing progress bars during soundfont downloads which can take 20+ seconds over the internet.
+**Part-centric design**: Each musical part gets an independent `ChannelHandle` with its own `AudioNode` output. Your application connects these outputs to gain controls, analyzers, and effects.
 
-```javascript
-import SpessaSynthAudioEngine from 'audio-mixer-engine';
+**External routing required**: The library provides individual part outputs but doesn't mix them internally. You must connect part outputs to `AudioContext.destination` (see Quick Start example).
 
-const audioEngine = new SpessaSynthAudioEngine(audioContext);
+**Dual volume control**:
+- Internal: `channelHandle.setVolume()` - affects MIDI synthesis
+- External: Your gain nodes - affects final output and enables solo/mute
 
-// Listen for progress events
-audioEngine.on('initProgress', (event) => {
-  console.log(`[${event.stage}] ${event.message}`);
+**PlaybackManager vs MidiPlayer**: `PlaybackManager` adds metronome, lead-in, and convenience methods. `MidiPlayer` provides lower-level playback control.
 
-  // Show progress bar for soundfont download
-  if (event.progress !== undefined) {
-    progressBar.style.width = `${event.progress * 100}%`;
-    statusText.textContent = event.message;
-  }
-});
+## API Overview
 
-// Initialize with soundfont
-await audioEngine.initialize('./soundfont.sf3');
-```
-
-### Progress Event Format
+### PlaybackManager
 
 ```javascript
-{
-  stage: 'loading-soundfont',      // Stage identifier
-  message: 'Downloading soundfont: 45% (234 KB / 520 KB)', // Human-readable message
-  progress: 0.45                    // Optional: 0.0-1.0 for stages with progress bars
-}
-```
-
-### Initialization Stages
-
-| Stage | Description | Has Progress | Typical Duration |
-|-------|-------------|--------------|------------------|
-| `importing` | Loading SpessaSynth library | No | ~20ms local, ~1.5s remote |
-| `loading-soundfont` | **Downloading soundfont** | **Yes** | ~2s local, **~20s remote** |
-| `loading-worklet` | Loading audio worklet | No | ~100ms local, ~2s remote |
-| `creating-synth` | Setting up audio channels | No | ~60ms |
-| `loading-soundbank` | Loading soundbank | No | ~100ms |
-| `finalizing` | Finalizing setup | No | <10ms |
-| `ready` | Complete | No | N/A |
-
-**See [INIT_PROGRESS.md](./INIT_PROGRESS.md) for complete documentation, examples, and best practices.**
-
-**Demo:** `demo/initialization-progress-demo.html` shows a working implementation with visual progress indicators.
+// Lifecycle
+await manager.load(midiArrayBuffer, metadata, instrumentMap);
+manager.reset();
 
-## Mixer Integration Pattern
-
-```javascript
-// Create parts manually for mixing interface
-const partChannel = audioEngine.createChannel('soprano', {
+// Transport
+await manager.play({ leadIn: true, metronome: true });
+manager.pause();
+manager.resume();
+manager.stop();
+
+// Configuration
+manager.setMetronomeEnabled(true);
+manager.setMetronomeSettings({ volume: 0.8 });
+manager.setLeadInEnabled(true);
+manager.setLeadInBars(2);
+manager.setStartupDelay(50);
+
+// Audio routing
+const metronomeOutput = manager.getMetronomeOutput();
+for (const [partName, outputNode] of manager.getPartOutputs()) { /* ... */ }
+const partNames = manager.getPartNames();
+
+// State
+const state = manager.getState(); // 'reset'|'ready'|'stopped'|'lead-in'|'playing'|'paused'
+const isPlaying = manager.isPlaying();
+const currentTime = manager.getCurrentTime();
+
+// Preview next notes (pitch reference for singers)
+const result = manager.previewNextNotes({
   instrument: 'piano',
-  initialVolume: 1.0
+  delayBetweenParts: 0.4,
+  duration: 0.6,
+  velocity: 110
 });
 
-// Get individual output node for external mixing
-const partOutput = partChannel.getOutputNode();
-
-// Set up mixer chain: Part Output -> External Gain -> Analyzer -> Master
-const partGain = audioContext.createGain();
-const partAnalyzer = audioContext.createAnalyser();
-
-partOutput.connect(partGain);
-partGain.connect(partAnalyzer);
-partAnalyzer.connect(masterGain); // External master gain
-
-// External mixer controls
-partGain.gain.value = 0.5; // 50% volume
-partAnalyzer.getByteFrequencyData(dataArray); // Level metering
-
-// Play a note
-const ac = audioEngine.audioContext;
-// In half a second play a C4 (pitch=60) at velocity of 100, and will last half a second
-partChannel.playNote(ac.currentTime + 0.5, 60, 100, 0.5)
+// Events
+manager.on('timeupdate', ({currentTime}) => {});
+manager.on('beatChanged', ({bar, beat, isLeadIn, time}) => {});
+manager.on('leadInStarted', ({bars, totalBeats, startupDelayMs}) => {});
+manager.on('leadInEnded', () => {});
 ```
 
-## Audio Routing Architecture
+### MidiPlayer
 
-The library implements a sophisticated audio routing system designed for mixer applications:
+```javascript
+// Transport
+player.play();
+player.pause();
+player.stop();
+player.skipToTime(30.5);
+player.setPlaybackSpeed(1.5);
 
-```
-MIDI File → Parser → Player → AudioEngine → Individual Part Outputs
-                                    ↓
-External Mixer Interface: Part Gain → Analyzer → Solo/Mute → Master → Destination
-```
+// Musical navigation
+player.setBar(4, 1); // Jump to bar 4, repeat 1
+const time = player.getTimeFromBar(2);
+const barInfo = player.getBeatFromTime(15.3);
 
-### Key Audio Routing Concepts
+// Part access
+const outputNode = player.getPartOutput('soprano');
+const channelHandle = player.getPartChannel('soprano');
 
-1. **Individual Part Outputs**: Each musical part provides an `AudioNode` output via `channelHandle.getOutputNode()`
-2. **External Volume Control**: Mixer interfaces control gain via external `GainNode` instances connected to part outputs
-3. **Internal vs External Volume**: 
-   - Internal: MIDI volume controlled via `channelHandle.setVolume()` (affects synthesis)
-   - External: Mixer volume controlled via external gain nodes (affects final output)
-4. **Analysis Integration**: Connect part outputs to `AnalyserNode` for real-time level metering and visualization
+// Controls
+player.setMasterVolume(0.7);
+player.allSoundsOff();
 
-## API Reference
+// Events
+player.on('timeupdate', ({currentTime}) => {});
+player.on('ended', ({finalTime}) => {});
+player.on('barChanged', ({bar, beat, repeat, time}) => {});
+```
 
-### ChannelHandle Methods
+### ChannelHandle
 
 ```javascript
-// Get output node for mixer connection
+// Output routing
 const outputNode = channelHandle.getOutputNode();
 
 // Note control
@@ -197,792 +162,122 @@ channelHandle.noteOn(pitch, velocity);
 channelHandle.noteOff(pitch);
 channelHandle.allNotesOff();
 
-// Scheduled note control
+// Scheduled notes
 const eventId = channelHandle.playNote(startTime, pitch, velocity, duration);
 
-// Internal synthesis controls
-await channelHandle.setInstrument('choir_aahs');
+// Configuration
+await channelHandle.setInstrument('choir_aahs'); // String name or MIDI program number
 channelHandle.setVolume(0.8); // Internal MIDI volume
 
-// Channel info
+// Info
 const partId = channelHandle.getPartId();
 const isActive = channelHandle.isActive();
 ```
 
-### MidiPlayer Methods
+### AudioEngine
 
 ```javascript
-// Transport controls
-player.play();
-player.pause();
-player.stop();
-player.skipToTime(30.5);
-player.setPlaybackSpeed(1.5);
-
-// Musical navigation
-player.setBar(4, 1);                    // Jump to bar 4, repeat 1
-const time = player.getTimeFromBar(2);   // Get time for bar 2
-const barInfo = player.getBeatFromTime(15.3); // Get beat info at time (includes bar, beat, time signature)
-
-// Emergency stop
-player.allSoundsOff();
-
-// Part access for mixer integration
-const sopranoOutput = player.getPartOutput('soprano');
-const sopranoChannel = player.getPartChannel('soprano');
-
-// REQUIRED: Set up external mixer routing for all parts
-const masterGain = audioContext.createGain();
-masterGain.connect(audioContext.destination);
-
-const sopranoGain = audioContext.createGain();
-const sopranoAnalyzer = audioContext.createAnalyser();
-
-sopranoOutput.connect(sopranoGain);
-sopranoGain.connect(sopranoAnalyzer);
-sopranoAnalyzer.connect(masterGain); // External master gain
-
-// Control volume/mute/solo via external gain nodes
-sopranoGain.gain.value = 0.5;          // 50% volume
-sopranoGain.gain.value = 0;            // Mute
-masterGain.gain.value = 0.8;           // Master volume
-
-// Solo functionality: mute all other parts' external gain nodes
-// (Implementation depends on your specific mixer setup)
-
-// Level monitoring
-sopranoAnalyzer.getByteFrequencyData(dataArray);
-
-// Event handling
-player.on('timeupdate', ({currentTime}) => { /* */
-});
-player.on('ended', ({finalTime}) => { /* */
-});
-player.on('barChanged', ({bar, beat, repeat, time}) => { /* */
-});
-```
-
-### PlaybackManager Methods
-
-```javascript
-// Create PlaybackManager with audio engine and optional configuration
-const playbackManager = new PlaybackManager(audioEngine, {
-  metronome: { enabled: true, volume: 0.7, tickInstrument: 115, accentInstrument: 116 },
-  leadIn: { enabled: true, bars: 2 },
-  startup: { delayMs: 25 }
-});
-
-// Load MIDI data - parses and creates player automatically
-await playbackManager.load(midiArrayBuffer);
-// Or with metadata and custom instrument mapping
-await playbackManager.load(midiArrayBuffer, structureMetadata, instrumentMap);
-
-// Reset and load new MIDI file
-playbackManager.reset();
-await playbackManager.load(newMidiArrayBuffer);
-
-// Transport controls
-await playbackManager.play({ leadIn: true, metronome: true });
-playbackManager.pause();
-playbackManager.resume();
-playbackManager.stop();
-
-// Metronome configuration
-playbackManager.setMetronomeEnabled(true);
-playbackManager.setMetronomeSettings({ volume: 0.8, tickInstrument: 115 });
-const metronomeSettings = playbackManager.getMetronomeSettings();
-
-// Lead-in configuration
-playbackManager.setLeadInEnabled(true);
-playbackManager.setLeadInBars(3);
-const leadInSettings = playbackManager.getLeadInSettings();
-
-// Startup timing configuration
-playbackManager.setStartupDelay(50);  // 50ms delay
-const startupSettings = playbackManager.getStartupSettings();
-
-// State and timing
-const state = playbackManager.getState(); // 'reset', 'ready', 'stopped', 'lead-in', 'playing', 'paused'
-const isPlaying = playbackManager.isPlaying();
-const currentTime = playbackManager.getCurrentTime();
-
-// Audio routing access
-const metronomeOutput = playbackManager.getMetronomeOutput();
-for (const [partName, outputNode] of playbackManager.getPartOutputs()) {
-  // Set up external routing for each part
-}
-const partNames = playbackManager.getPartNames(); // Array of part names
-
-// Preview next notes (useful for pitch reference before singing)
-const result = playbackManager.previewNextNotes({
-  instrument: 'piano',           // Optional instrument override for all parts
-  delayBetweenParts: 0.4,        // Time between each part (seconds)
-  duration: 0.6,                 // Duration of each note (seconds)
-  velocity: 110,                 // Velocity for all notes
-  partOrder: ['soprano', 'alto'] // Optional custom part order
-});
-// Returns: { parts: [{partName, pitch, startTime}, ...], totalDuration }
-// Automatically skips muted parts
-
-// Enhanced event handling
-playbackManager.on('leadInStarted', ({ bars, totalBeats, startupDelayMs }) => {});
-playbackManager.on('leadInEnded', () => {});
-playbackManager.on('beatChanged', ({ bar, beat, isLeadIn, time }) => {});
-playbackManager.on('startupSettingsChanged', ({ delayMs }) => {});
-```
-
-### Audio Engine Management
-
-```javascript
-// Engine lifecycle
+// Initialization
 await audioEngine.initialize('/path/to/soundfont.sf2');
 const isReady = audioEngine.isInitialized;
 
-// Engine controls
-audioEngine.setMasterVolume(0.7);
-const masterVol = audioEngine.getMasterVolume();
-audioEngine.allSoundsOff();
+// Progress tracking (SpessaSynth only)
+audioEngine.on('initProgress', ({stage, message, progress}) => {
+  // Show progress bar for soundfont downloads (20+ seconds)
+});
 
 // Channel creation
 const channelHandle = audioEngine.createChannel('partId', {
-  instrument: 'piano', // Can be string name or MIDI program number (0-127)
+  instrument: 'piano',
   initialVolume: 1.0
 });
 
-// Engine lifecycle
-const activeChannels = audioEngine.getActiveChannels();
-audioEngine.destroy(); // Cleanup all resources
-```
-
-## Mixer-Oriented Design vs Traditional Audio Libraries
-
-Unlike traditional audio libraries that output mixed audio directly to speakers, this library is designed specifically for **mixer interfaces** and **interactive practice applications**:
-
-### Traditional Audio Library Pattern:
-```javascript
-// Traditional libraries mix everything internally
-player.setVolume(0.5);           // Global volume only
-player.play();                   // Mixed audio to speakers
-// ❌ No individual part control
-// ❌ No real-time level analysis per part
-// ❌ No external routing flexibility
-```
-
-### Audio Mixer Engine Pattern:
-```javascript
-// Part-centric with individual outputs for mixer control
-const sopranoChannel = engine.createChannel('soprano');
-const sopranoOutput = sopranoChannel.getOutputNode(); // ← Key difference!
-
-// External mixer has full control
-sopranoOutput.connect(mixerGainNode);
-sopranoOutput.connect(levelAnalyzer);
-// ✅ Individual part control
-// ✅ Real-time analysis per part  
-// ✅ Full routing flexibility
+// Controls
+audioEngine.setMasterVolume(0.7);
+audioEngine.allSoundsOff();
+audioEngine.destroy();
 ```
 
-## Complete Mixer Example
+## Mixer Example
 
 ```javascript
-import { SpessaSynthAudioEngine, PlaybackManager } from 'audio-mixer-engine';
-
+// Typical mixer integration
 class AudioMixer {
   constructor(audioContext) {
     this.audioContext = audioContext;
-    this.audioEngine = new SpessaSynthAudioEngine(audioContext);
-    this.playbackManager = null;
-    this.parts = new Map(); // partId -> { gain, analyzer, muted, soloed }
+    this.parts = new Map(); // partId -> { gain, analyzer }
     this.masterGain = audioContext.createGain();
     this.masterGain.connect(audioContext.destination);
   }
 
-  async initialize(soundfontPath) {
-    await this.audioEngine.initialize(soundfontPath);
+  async loadMidiFile(manager, midiBuffer) {
+    await manager.load(midiBuffer);
 
-    // Create PlaybackManager with configuration
-    this.playbackManager = new PlaybackManager(this.audioEngine, {
-      metronome: { enabled: false, volume: 0.7 },
-      leadIn: { enabled: false, bars: 1 },
-      startup: { delayMs: 25 }
-    });
-  }
+    // Set up routing for each part
+    for (const [partName, outputNode] of manager.getPartOutputs()) {
+      const gain = this.audioContext.createGain();
+      const analyzer = this.audioContext.createAnalyser();
 
-  async loadMidiFile(midiArrayBuffer, metadata = null) {
-    // Load MIDI data into PlaybackManager
-    await this.playbackManager.load(midiArrayBuffer, metadata);
+      outputNode.connect(gain);
+      gain.connect(analyzer);
+      analyzer.connect(this.masterGain);
 
-    // Set up mixer routing for all parts
-    for (const [partName, outputNode] of this.playbackManager.getPartOutputs()) {
-      this.addPartToMixer(partName, outputNode);
+      this.parts.set(partName, { gain, analyzer });
     }
   }
 
-  addPartToMixer(partId, partOutput) {
-    // Set up mixer chain for this part
-    const gain = this.audioContext.createGain();
-    const analyzer = this.audioContext.createAnalyser();
-    analyzer.fftSize = 256;
-
-    // Audio routing: Part → Gain → Analyzer → Master → Destination
-    partOutput.connect(gain);
-    gain.connect(analyzer);
-    analyzer.connect(this.masterGain);
-
-    // Track part in mixer
-    this.parts.set(partId, {
-      gain,
-      analyzer,
-      muted: false,
-      soloed: false
-    });
-
-    return { gain, analyzer };
-  }
-
-  // Mixer controls
   setPartVolume(partId, volume) {
-    const part = this.parts.get(partId);
-    if (part) part.gain.gain.value = volume;
+    this.parts.get(partId).gain.gain.value = volume;
   }
 
   mutePart(partId) {
-    const part = this.parts.get(partId);
-    if (part) {
-      part.muted = !part.muted;
-      part.gain.gain.value = part.muted ? 0 : 1;
-    }
+    this.parts.get(partId).gain.gain.value = 0;
   }
 
-  soloPart(partId) {
-    // Toggle solo state
-    const part = this.parts.get(partId);
-    if (!part) return;
-
-    part.soloed = !part.soloed;
-
-    // Apply solo logic: if any parts are soloed, mute non-soloed parts
-    const hasAnySoloed = Array.from(this.parts.values()).some(p => p.soloed);
-
-    this.parts.forEach((partData, id) => {
-      if (hasAnySoloed) {
-        partData.gain.gain.value = partData.soloed ? 1 : 0;
-      } else {
-        partData.gain.gain.value = partData.muted ? 0 : 1;
-      }
-    });
-  }
-
-  // Real-time level monitoring
   getPartLevel(partId) {
-    const part = this.parts.get(partId);
-    if (!part) return 0;
-
-    const bufferLength = part.analyzer.frequencyBinCount;
-    const dataArray = new Uint8Array(bufferLength);
-    part.analyzer.getByteFrequencyData(dataArray);
+    const { analyzer } = this.parts.get(partId);
+    const dataArray = new Uint8Array(analyzer.frequencyBinCount);
+    analyzer.getByteFrequencyData(dataArray);
 
     // Calculate RMS level
     let sum = 0;
-    for (let i = 0; i < bufferLength; i++) {
+    for (let i = 0; i < dataArray.length; i++) {
       sum += dataArray[i] * dataArray[i];
     }
-    return Math.sqrt(sum / bufferLength) / 255; // Normalized 0-1
-  }
-
-  // Playback controls (delegated to PlaybackManager)
-  async play(options = {}) {
-    await this.playbackManager.play(options);
-  }
-
-  pause() {
-    this.playbackManager.pause();
-  }
-
-  stop() {
-    this.playbackManager.stop();
+    return Math.sqrt(sum / dataArray.length) / 255;
   }
 }
-
-// Usage
-const mixer = new AudioMixer(audioContext);
-await mixer.initialize('soundfont.sf2');
-
-// Load MIDI file
-await mixer.loadMidiFile(midiArrayBuffer);
-
-// Mixer controls
-mixer.setPartVolume('soprano', 0.7);
-mixer.mutePart('piano');
-mixer.soloPart('soprano');
-
-// Playback
-await mixer.play({ leadIn: true, metronome: true });
-
-// Monitor levels
-const level = mixer.getPartLevel('soprano'); // Get real-time level
 ```
 
-## Common Mixer Patterns
+## Additional Documentation
 
-### Pattern 1: Practice App with Part Isolation
-```javascript
-// Enable users to practice by isolating their part
-const practiceApp = {
-  async setupPractice(userPart, otherParts) {
-    // Create channels for all parts
-    const channels = {};
-    for (const part of [userPart, ...otherParts]) {
-      channels[part] = await this.createPartWithMixer(part);
-    }
-
-    // Set up practice mode: user part at full volume, others quieter
-    channels[userPart].gain.gain.value = 1.0;
-    otherParts.forEach(part => {
-      channels[part].gain.gain.value = 0.3; // Background level
-    });
-  },
-
-  // Preview starting pitch before singing
-  playStartingPitch() {
-    // Preview next notes using piano for clear pitch reference
-    const result = this.playbackManager.previewNextNotes({
-      instrument: 'piano',      // Clear pitch reference
-      delayBetweenParts: 0.4,   // Sequence parts left-to-right
-      duration: 0.6,            // 600ms per note
-      velocity: 110             // Clear and audible
-    });
-
-    // Shows which parts will play (automatically skips muted parts)
-    console.log(`Playing pitches for: ${result.parts.map(p => p.partName).join(', ')}`);
-  }
-};
-```
-
-### Pattern 2: Live Mixer Interface  
-```javascript
-// Real-time mixer with visual feedback
-class LiveMixer {
-  updateLevels() {
-    // Update level meters for all parts in real-time
-    this.parts.forEach((partData, partId) => {
-      const level = this.getPartLevel(partId);
-      this.updateLevelMeter(partId, level);
-      
-      // Highlight active parts
-      const isActive = level > 0.02;
-      this.highlightPart(partId, isActive);
-    });
-  }
-  
-  // Mixer UI controls map directly to audio nodes
-  onVolumeSlider(partId, value) {
-    this.parts.get(partId).gain.gain.value = value;
-  }
-  
-  onMuteButton(partId) {
-    const part = this.parts.get(partId);
-    part.muted = !part.muted;
-    part.gain.gain.value = part.muted ? 0 : 1;
-  }
-}
-```
-
-### Pattern 3: Recording/Export with Part Separation
-```javascript
-// Record individual parts or create stems
-class PartRecorder {
-  async recordPart(partId, duration) {
-    const part = this.parts.get(partId);
-    
-    // Connect part to MediaRecorder via MediaStreamDestination
-    const dest = this.audioContext.createMediaStreamDestination();
-    part.gain.connect(dest);
-    
-    const recorder = new MediaRecorder(dest.stream);
-    // Record just this part's audio...
-  }
-}
-```
-
-## Advanced Usage Examples
-
-### Preview Next Notes (Pitch Reference)
-
-For choir practice apps, singers often need to hear their starting pitch before singing:
-
-```javascript
-// Pause playback and preview the next notes
-playbackManager.pause();
-
-// Play next note for all unmuted parts in sequence
-const result = playbackManager.previewNextNotes({
-  instrument: 'piano',        // Use piano for clear pitch reference
-  delayBetweenParts: 0.4,     // 400ms between each part
-  duration: 0.6,              // 600ms note duration
-  velocity: 110               // Clear, audible level
-});
-
-// Result shows which parts were previewed
-console.log(`Previewed notes for: ${result.parts.map(p => p.partName).join(', ')}`);
-// Example output: {
-//   parts: [
-//     { partName: 'soprano', pitch: 64, startTime: 0.01 },
-//     { partName: 'alto', pitch: 60, startTime: 0.41 }
-//   ],
-//   totalDuration: 0.8
-// }
-
-// Automatically skips muted parts (checked via partOutput.gain.value === 0)
-// Notes play through each part's channel, so level indicators will respond
-// Can specify custom part order: partOrder: ['soprano', 'alto', 'tenor', 'bass']
-```
-
-**How it works:**
-1. **MidiPlayer.getAllNextNotes()** - Finds the next note for each part after current time
-2. **ChannelHandle.playPreviewNote()** - Plays a single note with optional instrument override
-3. **PlaybackManager.previewNextNotes()** - Orchestrates sequential playback of all parts
-
-**Key features:**
-- Plays through actual part channels (level meters show activity)
-- Automatically skips muted parts
-- Supports instrument override (e.g., piano instead of choir_aahs)
-- Configurable timing, duration, and velocity
-- Custom part ordering support
-
-### PlaybackManager with Metronome and Lead-in
-
-```javascript
-import { SpessaSynthAudioEngine, PlaybackManager } from 'audio-mixer-engine';
-
-// Initialize audio engine
-const audioEngine = new SpessaSynthAudioEngine(audioContext);
-await audioEngine.initialize('/path/to/soundfont.sf2');
-
-// Create PlaybackManager with advanced features
-const playbackManager = new PlaybackManager(audioEngine, {
-  metronome: {
-    enabled: true,
-    tickInstrument: 115,     // Woodblock for regular beats
-    accentInstrument: 116,   // Taiko drum for downbeats
-    volume: 0.7
-  },
-  leadIn: {
-    enabled: true,
-    bars: 2                  // 2-bar lead-in
-  },
-  startup: {
-    delayMs: 25             // 25ms startup delay for better timing
-  }
-});
-
-// Load MIDI data
-await playbackManager.load(midiArrayBuffer);
-
-// Enhanced event handling
-playbackManager.on('leadInStarted', ({ bars, totalBeats, startupDelayMs }) => {
-  console.log(`Lead-in: ${bars} bars (${totalBeats} beats), ${startupDelayMs}ms startup delay`);
-});
-
-playbackManager.on('beatChanged', ({ bar, beat, isLeadIn }) => {
-  if (isLeadIn) {
-    console.log(`Lead-in: Bar ${bar}, Beat ${beat}`);
-  } else {
-    console.log(`Playing: Bar ${bar}, Beat ${beat}`);
-  }
-});
-
-// Runtime configuration
-playbackManager.setStartupDelay(50);      // Adjust startup delay
-playbackManager.setMetronomeEnabled(true); // Toggle metronome
-playbackManager.setLeadInBars(1);         // Change lead-in length
-
-// Start with features
-await playbackManager.play({ leadIn: true, metronome: true });
-```
-
-### Startup Timing Control
-
-The PlaybackManager includes configurable startup delays to ensure perfect timing synchronization between metronome ticks and initial notes:
-
-```javascript
-// Configure startup delay during construction
-const playbackManager = new PlaybackManager(audioEngine, {
-  startup: {
-    delayMs: 25  // Default: 25ms delay before audio starts
-  }
-});
-
-// Runtime adjustment of startup delay
-playbackManager.setStartupDelay(50);  // 50ms delay
-
-// Get current settings
-const settings = playbackManager.getStartupSettings();
-console.log(`Current delay: ${settings.delayMs}ms`);
-
-// Listen for configuration changes
-playbackManager.on('startupSettingsChanged', ({ delayMs }) => {
-  console.log(`Startup delay changed to ${delayMs}ms`);
-});
-```
-
-**Why Startup Delays Matter:**
-- **Timing Synchronization**: Ensures metronome ticks and first notes start together
-- **Scheduling Setup**: Allows audio context and synthesis engines time to prepare
-- **Reduced Audio Glitches**: Prevents initial audio stuttering on some systems
-- **Consistent Timing**: Eliminates variable delays in first few notes
-
-**Recommended Values:**
-- `0ms` - No delay (fastest start, may have timing issues)
-- `25ms` - Default (good balance of speed and timing)
-- `50ms` - Conservative (ensures reliable timing on slower systems)
-- `100ms` - High latency systems (older devices or complex audio setups)
-
-**Behavior:**
-- The `play()` method returns immediately and state changes to 'playing'
-- Events are emitted immediately (playbackStarted, leadInStarted)
-- Actual audio output begins after the specified delay
-- Works with both direct playback and lead-in modes
-
-### Musical Navigation
-
-```javascript
-// Set up event listener for bar changes
-player.on('barChanged', ({bar, beat, repeat, time}) => {
-  console.log(`Now at Bar ${bar}, Beat ${beat} (${time.toFixed(2)}s)`);
-  updateScoreHighlight(bar);
-});
-
-// Navigate to specific bars
-player.setBar(5);                    // Jump to bar 5
-player.setBar(3, 1);                // Jump to bar 3, repeat 1
-
-// Time/bar conversion
-const bar8Time = player.getTimeFromBar(8);  // Get time for bar 8
-const currentBar = player.getBeatFromTime(player.getCurrentTime());
-```
-
-### Event-Driven Mixer Integration
-
-```javascript
-// Set up comprehensive event handling
-player.on('timeupdate', ({ currentTime }) => {
-  updateProgressBar(currentTime / player.getTotalDuration());
-});
-
-player.on('ended', ({ finalTime }) => {
-  console.log(`Playback completed at ${finalTime}s`);
-  showPlaybackComplete();
-});
-
-player.on('masterVolumeChanged', ({ volume }) => {
-  updateMasterVolumeSlider(volume);
-});
-
-// Master volume control with events
-player.setMasterVolume(0.8);  // Triggers masterVolumeChanged event
-```
-
-### Structure Metadata Integration
-
-```javascript
-// Advanced beat mapping with song structure
-const structureMetadata = {
-  sections: [
-    {startBar: 1, endBar: 8, name: "Verse"},
-    {startBar: 9, endBar: 16, name: "Chorus"},
-    {startBar: 17, endBar: 24, name: "Bridge"}
-  ],
-  order: [
-    {section: 0},           // Verse
-    {section: 1, repeat: 2}, // Chorus x2
-    {section: 2},           // Bridge
-    {section: 1}            // Chorus
-  ]
-};
-
-const player = new MidiPlayer(audioEngine, parsedData, instrumentMap, structureMetadata);
-
-// Navigate by song sections
-player.setBar(9);  // Jump to Chorus
-player.setBar(1, 1); // Jump to Verse, second time through
-```
-
-## Metadata and Score Configuration
-
-The library supports comprehensive metadata to override MIDI file information and configure playback behavior. See [METADATA.md](./METADATA.md) for the complete metadata specification including:
-
-- **Score metadata overrides**: Title, composer, arranger, copyright
-- **Part configuration**: Custom part names, track mapping, instrument overrides
-- **Playback modifiers**: Semitone shift, playback speed adjustment
-- **Structure metadata**: Non-linear playback with sections and repeats (see also [BEATMAPPING.md](./BEATMAPPING.md))
-
-```javascript
-// Example: Load with metadata overrides
-const metadata = {
-  title: "Amazing Grace",
-  composer: "John Newton",
-  semitoneShift: -2,           // Transpose down 2 semitones
-  playbackSpeed: 0.8,          // Slow to 80% speed
-  parts: {
-    "soprano": { trackIndex: 0, instrument: 52 },
-    "alto": { trackIndex: 1, instrument: 52 }
-  },
-  sections: [...],             // Structure for non-linear playback
-  order: [...]
-};
-
-await playbackManager.load(midiBuffer, metadata);
-```
-
-## Use Cases
-
-This library is specifically designed for:
-
-- **Choir Practice Apps**: Individual part control for learning and practice
-- **Music Education Software**: Part isolation and analysis for teaching
-- **Live Performance Tools**: Real-time mixing during rehearsals or performances  
-- **Audio Workstations**: Part-based stems and multi-track recording
-- **Interactive Score Viewers**: Dynamic part highlighting and playback control
-- **Rehearsal Tools**: Director interfaces with part-specific controls
-
-**Not intended for**: Simple audio playback, games, or applications that don't need per-part control.
-
-## Updated API (v0.1.0)
-
-### New Event System
-All events now use structured data objects:
-```javascript
-// Old format (deprecated)
-player.on('timeupdate', (currentTime) => { /* */ });
-
-// New format (current)
-player.on('timeupdate', ({ currentTime }) => { /* */ });
-player.on('ended', ({ finalTime }) => { /* */ });
-player.on('barChanged', ({ bar, beat, repeat, time }) => { /* */ });
-```
-
-### Enhanced Constructor
-
-```javascript
-// Basic usage (backward compatible)
-new MidiPlayer(audioEngine, parsedData, instrumentMap);
-
-// With structure metadata for advanced navigation
-new MidiPlayer(audioEngine, parsedData, instrumentMap, structureMetadata);
-```
-
-### New Methods
-
-```javascript
-// Musical navigation
-player.setBar(barNumber, repeat);
-player.getTimeFromBar(barNumber, repeat);
-player.getBeatFromTime(timeInSeconds);
-
-// Master volume control
-player.setMasterVolume(0.7);
-player.getMasterVolume();
-player.allSoundsOff();
-```
-
-## Interface Contract
-
-This library implements a specific interface contract for integration with UI layers. See [INTERFACE.md](./INTERFACE.md) for the complete specification of methods, events, and data structures that external coordination layers can depend on.
-
-## Core Components
-
-### AudioEngine (Abstract Base)
-Defines the contract for part-centric audio synthesis:
-- **Part-based channel creation**: Each musical part gets its own `ChannelHandle`
-- **Individual output routing**: Provides separate `AudioNode` outputs per part
-- **Master volume control**: Global volume affecting all parts
-- **Resource management**: Clean lifecycle management for channels and audio nodes
-
-### SpessaSynthAudioEngine
-SpessaSynth-based implementation with mixer-focused features:
-- **Individual MIDI channel outputs**: Creates separate audio outputs for each of 16 MIDI channels
-- **External routing support**: Part outputs designed for connection to external gain/analysis nodes
-- **Soundfont-based synthesis**: High-quality GM-compatible audio synthesis
-- **Fallback audio routing**: Graceful degradation when individual outputs aren't available
-
-### ChannelHandle (Abstract Interface)
-Represents one musical part with full control interface:
-- **Output node access**: `getOutputNode()` provides `AudioNode` for mixer connection
-- **Note playback control**: Start/stop notes with velocity and duration control  
-- **Instrument management**: Runtime instrument changes per part
-- **Volume control**: Internal MIDI volume (separate from external mixer volume)
-
-### MidiParser
-MIDI file parser:
-- **Part identification**: Automatically identifies separate instrument parts
-- **Program change support**: Preserves MIDI instrument assignments (program numbers 0-127)
-- **Track analysis**: Extracts tempo changes, time signatures, and structural data
-
-### AudioEngineUtils
-Utility functions for instrument handling:
-- **`getInstrumentProgram(instrument)`**: Converts instrument names to MIDI program numbers
-- **`getProgramName(programNumber)`**: Converts MIDI program numbers to display names
-- **Complete MIDI coverage**: Supports all 128 General MIDI instruments
-
-### MidiPlayer  
-High-level playback controller with mixer integration:
-- **Part-centric playback**: Routes notes to appropriate channel handles
-- **External mixer support**: Provides `getPartOutput()` for mixer connection
-- **Convenience controls**: Built-in solo/mute/volume methods for rapid prototyping
-- **Precise timing**: Advanced scheduling with tempo change support
-
-### BeatMapper
-Advanced beat mapping for musical analysis:
-- **Beat position calculation**: Maps time positions to musical beats
-- **Tempo change handling**: Accurately tracks tempo variations
-- **Measure boundary detection**: Identifies bar lines and structural elements
+- **[LIGHTWEIGHT_ENGINE.md](./LIGHTWEIGHT_ENGINE.md)** - Lightweight engine setup and sample file configuration
+- **[METADATA.md](./METADATA.md)** - Score metadata, part configuration, and playback modifiers
+- **[BEATMAPPING.md](./BEATMAPPING.md)** - Beat mapping and non-linear playback structures
+- **[INTERFACE.md](./INTERFACE.md)** - Complete interface contract for UI integration
+- **[INIT_PROGRESS.md](./INIT_PROGRESS.md)** - Initialization progress tracking and best practices
 
 ## Development
 
 ```bash
-# Install dependencies
 npm install
-
-# Run tests
 npm test
-
-# Run with coverage
 npm run test:coverage
-
-# Development server
 npm run dev
+npm run build
 ```
 
-## Testing
+## Examples
 
-The library includes comprehensive test suites:
-- Unit tests for all core components
-- MIDI parsing validation
-- Audio engine integration tests
-- Mock audio engine for testing
-
-## Demo
-
-Check out the demo files:
 - `demo/part-audio-engine-demo.html` - Interactive browser demo
-- `demo/initialization-progress-demo.html` - Progress tracking demo with timing breakdown
-- `test-player.js` - Command-line player example
-- `examples/midi-player-demo.js` - Basic usage example
+- `demo/initialization-progress-demo.html` - Progress tracking demo
+- `examples/midi-player-demo.js` - Basic usage
 
 ## License
 
 MIT License - see LICENSE file for details.
 
-### Browsers
-- **Chromium-based browsers** (Chrome, Edge, Brave): May experience audio distortion due to Chromium Web Audio API bugs
-- **Safari**: Not extensively tested but should work with Web Audio API polyfills
-
-## Contributing
+## Browser Compatibility
 
-This library was extracted from a larger choir practice application. Contributions are welcome for:
-- Additional audio engine implementations
-- MIDI parsing improvements
-- Performance optimizations
-- Documentation enhancements
-- Browser compatibility improvements
+- **Chromium browsers** (Chrome, Edge, Brave): May experience audio distortion due to Web Audio API bugs
+- **Safari**: Should work with standard Web Audio API support