audio-mixer-engine 1.3.3 → 1.3.5

package/README.md

@@ -17,21 +17,27 @@ A part-centric JavaScript audio library for mixer applications. Provides individ
 npm install audio-mixer-engine
 ```
 
-### Audio Engine Options
+### Choosing an Audio Engine
 
-- **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.
+| Engine | Bundle | Instruments | Best for |
+|--------|--------|-------------|----------|
+| **`LightweightAudioEngine`** | ~574KB | Piano, choir | Mobile, general web use |
+| **`SpessaSynthAudioEngine`** | +10-50MB soundfont | Full General MIDI | Desktop, full instrument range |
+
+For most deployments — especially mobile — use `LightweightAudioEngine`. See [LIGHTWEIGHT_ENGINE.md](./LIGHTWEIGHT_ENGINE.md) for setup details.
+
+`SpessaSynthAudioEngine` requires a separate soundfont download and has known audio performance issues on mobile (see [LATENCY_CALIBRATION.md](./LATENCY_CALIBRATION.md)).
 
 ## Quick Start
 
 ```javascript
-import { SpessaSynthAudioEngine, PlaybackManager } from 'audio-mixer-engine';
+import { LightweightAudioEngine, PlaybackManager } from 'audio-mixer-engine';
 
 const ac = new AudioContext();
 
-// Initialize audio engine
-const audioEngine = new SpessaSynthAudioEngine(ac);
-await audioEngine.initialize('/path/to/soundfont.sf2');
+// Initialize audio engine (no soundfont needed)
+const audioEngine = new LightweightAudioEngine(ac);
+await audioEngine.initialize();
 
 // Create PlaybackManager
 const manager = new PlaybackManager(audioEngine, {
@@ -267,7 +273,7 @@ resolveInstrument('piano');       // 0
 resolveInstrument('choir_aahs');  // 52
 resolveInstrument(40);            // 40
 
-// Normalize legacy v1 metadata format to v2
+// Normalize metadata with scores[] wrapper to flat format
 const normalized = normalizeLegacyMetadata(legacyMetadata);
 ```
 
@@ -326,11 +332,12 @@ class AudioMixer {
 
 - **[MUSICXML.md](./MUSICXML.md)** - MusicXML/MXL file loading, supported elements, and API reference
 - **[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
+- **[METADATA.md](./METADATA.md)** - Score metadata, part/instrument overrides, and playback modifiers
+- **[MIDI_METADATA.md](./MIDI_METADATA.md)** - MIDI bar structure format (repeats, jumps, pickup bars)
 - **[INTERFACE.md](./INTERFACE.md)** - Complete interface contract for UI integration
-- **[INIT_PROGRESS.md](./INIT_PROGRESS.md)** - Initialization progress tracking and best practices
+- **[INIT_PROGRESS.md](./INIT_PROGRESS.md)** - Initialization progress tracking (SpessaSynth only)
 - **[IOS_AUDIO_RESUMPTION.md](./IOS_AUDIO_RESUMPTION.md)** - Handling iOS screen lock/background audio suspension
+- **[LATENCY_CALIBRATION.md](./LATENCY_CALIBRATION.md)** - Audio latency measurement and drift detection (SpessaSynth)
 
 ## Development