audio-mixer-engine 0.1.0

package/README.md

@@ -0,0 +1,816 @@
+# 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.
+
+## 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
+
+## Installation
+
+```bash
+npm install audio-mixer-engine
+```
+
+## Quick Start - Basic Playback
+
+```javascript
+import { 
+  SpessaSynthAudioEngine, 
+  MidiParser, 
+  MidiPlayer 
+} from 'audio-mixer-engine';
+
+// Initialize audio context and engine
+const audioContext = new AudioContext();
+const audioEngine = new SpessaSynthAudioEngine(audioContext);
+
+// Load soundfont and parse MIDI
+await audioEngine.initialize('/path/to/soundfont.sf2');
+const parser = new MidiParser();
+const midiData = await parser.parse(midiArrayBuffer);
+
+// Create player with optional instrument mapping
+// Note: MIDI program changes from files are used by default
+// instrumentMap only needed to override or for parts without program changes
+const instrumentMap = {
+  soprano: { instrument: 'choir_aahs', volume: 1.0 }, // Overrides MIDI program
+  alto: { instrument: 'choir_aahs', volume: 1.0 },    // Overrides MIDI program  
+  piano: { instrument: 'piano', volume: 0.8 }         // Overrides MIDI program
+};
+
+// Optional structure metadata for advanced beat mapping
+const structureMetadata = {
+  sections: [{ startBar: 1, endBar: 8 }],
+  order: [{ section: 0 }]
+};
+
+const player = new MidiPlayer(audioEngine, instrumentMap, midiData, structureMetadata);
+
+// Set up event listeners
+player.on('timeupdate', ({ currentTime }) => {
+  console.log(`Playing: ${currentTime.toFixed(2)}s`);
+});
+
+player.on('barChanged', ({ bar, beat, time }) => {
+  console.log(`Bar ${bar}, Beat ${beat} at ${time.toFixed(2)}s`);
+});
+
+player.play();
+```
+
+## Mixer Integration Pattern
+
+```javascript
+// Create parts manually for mixing interface
+const sopranoChannel = audioEngine.createChannel('soprano', {
+  instrument: 'choir_aahs',
+  initialVolume: 1.0
+});
+
+// Get individual output node for external mixing
+const sopranoOutput = sopranoChannel.getOutputNode();
+
+// Set up mixer chain: Part Output -> External Gain -> Analyzer -> Master
+const sopranoGain = audioContext.createGain();
+const sopranoAnalyzer = audioContext.createAnalyser();
+
+sopranoOutput.connect(sopranoGain);
+sopranoGain.connect(sopranoAnalyzer);
+sopranoAnalyzer.connect(masterGain); // External master gain
+
+// External mixer controls
+sopranoGain.gain.value = 0.5; // 50% volume
+sopranoAnalyzer.getByteFrequencyData(dataArray); // Level metering
+
+// Play notes on individual parts
+sopranoChannel.noteOn(60, 100); // C4 at velocity 100
+sopranoChannel.noteOff(60);
+```
+
+## Audio Routing Architecture
+
+The library implements a sophisticated audio routing system designed for mixer applications:
+
+```
+MIDI File → Parser → Player → AudioEngine → Individual Part Outputs
+                                    ↓
+External Mixer Interface: Part Gain → Analyzer → Solo/Mute → Master → Destination
+```
+
+### Key Audio Routing Concepts
+
+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
+
+## API Reference
+
+### ChannelHandle Methods
+
+```javascript
+// Get output node for mixer connection
+const outputNode = channelHandle.getOutputNode();
+
+// Note control
+channelHandle.noteOn(pitch, velocity);
+channelHandle.noteOff(pitch);
+channelHandle.allNotesOff();
+
+// Scheduled note control
+const eventId = channelHandle.playNote(startTime, pitch, velocity, duration);
+
+// Internal synthesis controls
+await channelHandle.setInstrument('choir_aahs');
+channelHandle.setVolume(0.8); // Internal MIDI volume
+
+// Channel info
+const partId = channelHandle.getPartId();
+const isActive = channelHandle.isActive();
+```
+
+### MidiPlayer Methods
+
+```javascript
+// Transport controls
+player.play();
+player.pause();
+player.stop();
+player.skipToTime(30.5);
+player.setPlaybackSpeed(1.5);
+
+// Musical navigation
+player.setBar(4, 0);                    // Jump to bar 4, repeat 0
+const time = player.getTimeFromBar(2);   // Get time for bar 2
+const barInfo = player.getBarFromTime(15.3); // Get bar info at time
+
+// 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
+// Advanced playback with metronome, lead-in, and startup timing
+const playbackManager = new PlaybackManager(midiPlayer, {
+  metronome: { enabled: true, volume: 0.7 },
+  leadIn: { enabled: true, bars: 2 },
+  startup: { delayMs: 25 }
+});
+
+// Transport controls (wraps MidiPlayer)
+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(); // 'stopped', 'lead-in', 'playing', 'paused'
+const isPlaying = playbackManager.isPlaying();
+const currentTime = playbackManager.getCurrentTime();
+
+// 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
+await audioEngine.initialize('/path/to/soundfont.sf2');
+const isReady = audioEngine.isInitialized;
+
+// Engine controls
+audioEngine.setMasterVolume(0.7);
+const masterVol = audioEngine.getMasterVolume();
+audioEngine.allSoundsOff();
+
+// Channel creation
+const channelHandle = audioEngine.createChannel('partId', {
+  instrument: 'piano', // Can be string name or MIDI program number (0-127)
+  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
+```
+
+## Complete Mixer Example
+
+```javascript
+import { SpessaSynthAudioEngine } from 'audio-mixer-engine';
+
+class AudioMixer {
+  constructor(audioContext) {
+    this.audioContext = audioContext;
+    this.audioEngine = new SpessaSynthAudioEngine(audioContext);
+    this.parts = new Map(); // partId -> { channel, gain, analyzer, muted, soloed }
+    this.masterGain = audioContext.createGain();
+    this.masterGain.connect(audioContext.destination);
+  }
+
+  async initialize(soundfontPath) {
+    await this.audioEngine.initialize(soundfontPath);
+  }
+
+  addPart(partId, instrument = 'piano') {
+    // Create channel for this part
+    const channel = this.audioEngine.createChannel(partId, { instrument });
+    
+    // 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
+    const partOutput = channel.getOutputNode();
+    partOutput.connect(gain);
+    gain.connect(analyzer);
+    analyzer.connect(this.masterGain);
+    
+    // Track part in mixer
+    this.parts.set(partId, {
+      channel,
+      gain,
+      analyzer,
+      muted: false,
+      soloed: false
+    });
+    
+    return { channel, gain, analyzer };
+  }
+
+  // Mixer controls
+  setPartVolume(partId, volume) {
+    const part = this.parts.get(partId);
+    if (part) part.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;
+    }
+  }
+
+  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);
+    
+    // Calculate RMS level
+    let sum = 0;
+    for (let i = 0; i < bufferLength; i++) {
+      sum += dataArray[i] * dataArray[i];
+    }
+    return Math.sqrt(sum / bufferLength) / 255; // Normalized 0-1
+  }
+
+  // Play notes on specific parts
+  playNote(partId, pitch, velocity = 100) {
+    const part = this.parts.get(partId);
+    if (part) {
+      part.channel.noteOn(pitch, velocity);
+    }
+  }
+  
+  stopNote(partId, pitch) {
+    const part = this.parts.get(partId);
+    if (part) {
+      part.channel.noteOff(pitch);
+    }
+  }
+}
+
+// Usage
+const mixer = new AudioMixer(audioContext);
+await mixer.initialize('soundfont.sf2');
+
+// Add parts to mixer
+mixer.addPart('soprano', 'choir_aahs');
+mixer.addPart('piano', 'piano');
+
+// Mixer controls
+mixer.setPartVolume('soprano', 0.7);
+mixer.mutePart('piano');
+mixer.soloPart('soprano');
+
+// Play and monitor
+mixer.playNote('soprano', 60, 100); // C4 at velocity 100
+const level = mixer.getPartLevel('soprano'); // Get real-time level
+```
+
+## Common Mixer Patterns
+
+### 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
+    });
+  }
+};
+```
+
+### 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
+
+### PlaybackManager with Metronome and Lead-in
+
+```javascript
+import { PlaybackManager } from 'audio-mixer-engine';
+
+// Wrap MidiPlayer with PlaybackManager for advanced features
+const playbackManager = new PlaybackManager(player, {
+  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
+  }
+});
+
+// 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(player, {
+  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.getBarFromTime(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, instrumentMap, parsedData, structureMetadata);
+
+// Navigate by song sections
+player.setBar(9);  // Jump to Chorus
+player.setBar(1, 1); // Jump to Verse, second time through
+```
+
+## 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, instrumentMap, parsedData);
+
+// With structure metadata for advanced navigation
+new MidiPlayer(audioEngine, instrumentMap, parsedData, structureMetadata);
+```
+
+### New Methods
+```javascript
+// Musical navigation
+player.setBar(barNumber, repeat);
+player.getTimeFromBar(barNumber, repeat);
+player.getBarFromTime(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
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Run with coverage
+npm run test:coverage
+
+# Development server
+npm run dev
+```
+
+## Testing
+
+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
+- `test-player.js` - Command-line player example
+- `examples/midi-player-demo.js` - Basic usage example
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Browser Compatibility
+
+### Firefox Compatibility Notes
+
+This library uses SpessaSynth for audio synthesis, which has specific Firefox compatibility considerations:
+
+- **Firefox is recommended** over Chromium-based browsers due to better Web Audio API support and memory handling for large soundfonts
+- **Known Firefox crashes** have been addressed in recent SpessaSynth versions (fixed crash due to Firefox browser bug #1918506)
+- **Mitigation strategies implemented**:
+  - AudioWorklet module loading includes timing delays and retry logic to prevent initialization race conditions
+  - Soundfont loading includes progress feedback and chunked processing
+  - Engine initialization has automatic retry mechanism (3 attempts with exponential backoff)
+  - Memory management optimization before SpessaSynth initialization
+
+If experiencing intermittent crashes (~20% rate) during initialization in Firefox:
+1. Ensure you're using the latest SpessaSynth version
+2. The built-in retry mechanism should automatically handle most timing-related failures
+3. Consider implementing additional delays if crashes persist in your specific environment
+
+### Other 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
+
+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