audio-mixer-engine 0.6.0 → 0.7.0

package/README.md

@@ -17,7 +17,7 @@ This library follows a **part-centric mixer design** where each musical part (so
 - **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  
+- **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
@@ -26,6 +26,7 @@ This library follows a **part-centric mixer design** where each musical part (so
 - **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
 
 ## Installation
 
@@ -84,6 +85,56 @@ for (const [partName, outputNode] of manager.getPartOutputs()) {
 await manager.play({ leadIn: true, metronome: true });
 ```
 
+## Initialization Progress Tracking
+
+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.
+
+```javascript
+import SpessaSynthAudioEngine from 'audio-mixer-engine';
+
+const audioEngine = new SpessaSynthAudioEngine(audioContext);
+
+// Listen for progress events
+audioEngine.on('initProgress', (event) => {
+  console.log(`[${event.stage}] ${event.message}`);
+
+  // Show progress bar for soundfont download
+  if (event.progress !== undefined) {
+    progressBar.style.width = `${event.progress * 100}%`;
+    statusText.textContent = event.message;
+  }
+});
+
+// Initialize with soundfont
+await audioEngine.initialize('./soundfont.sf3');
+```
+
+### Progress Event Format
+
+```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.
+
 ## Mixer Integration Pattern
 
 ```javascript
@@ -915,6 +966,7 @@ The library includes comprehensive test suites:
 
 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