audio-mixer-engine 1.1.6 → 1.3.0

package/README.md

@@ -8,6 +8,7 @@ A part-centric JavaScript audio library for mixer applications. Provides individ
 - **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
+- **MusicXML support**: Load MusicXML/MXL files directly — repeats, voltas, jumps, lyrics, dynamics
 - **Mixer-ready**: Designed for solo/mute, routing, and level monitoring workflows
 
 ## Installation
@@ -63,6 +64,38 @@ for (const [partName, outputNode] of manager.getPartOutputs()) {
 await manager.play({ leadIn: true, metronome: true });
 ```
 
+### Loading MusicXML Files
+
+PlaybackManager auto-detects MusicXML strings and MXL/ZIP ArrayBuffers:
+
+```javascript
+import { loadMusicXml } from 'audio-mixer-engine';
+
+// MXL file (ArrayBuffer) — auto-detected from ZIP magic bytes
+await manager.load(mxlArrayBuffer);
+
+// MusicXML string — auto-detected from <?xml or <score-partwise> prefix
+const xmlString = await loadMusicXml(fileArrayBuffer);
+await manager.load(xmlString);
+
+// With metadata overrides (title, composer, per-part instrument mapping)
+await manager.load(xmlString, metadataOverrides);
+
+// From here on, playback works exactly the same as MIDI
+await manager.play({ leadIn: true, metronome: true });
+```
+
+You can also convert manually for more control:
+
+```javascript
+import { MusicXmlConverter, loadMusicXml } from 'audio-mixer-engine';
+
+const xmlString = await loadMusicXml(fileArrayBuffer);
+const converter = new MusicXmlConverter();
+const parsedData = converter.convert(xmlString, { defaultTempo: 120 }, metadataOverrides);
+await manager.load(parsedData);
+```
+
 ## Key Concepts
 
 **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.
@@ -80,8 +113,12 @@ await manager.play({ leadIn: true, metronome: true });
 ### PlaybackManager
 
 ```javascript
-// Lifecycle
-await manager.load(midiArrayBuffer, metadata, instrumentMap);
+// Lifecycle — load() auto-detects input type
+await manager.load(midiArrayBuffer);                 // MIDI ArrayBuffer
+await manager.load(mxlArrayBuffer);                  // MXL/ZIP ArrayBuffer (auto-detected)
+await manager.load(musicXmlString);                  // MusicXML string (auto-detected)
+await manager.load(parsedData);                      // Pre-parsed data object
+await manager.load(input, metadata, instrumentMap);  // With optional overrides
 manager.reset();
 
 // Transport
@@ -198,6 +235,42 @@ audioEngine.allSoundsOff();
 audioEngine.destroy();
 ```
 
+### MusicXML Processing
+
+```javascript
+import { MusicXmlConverter, loadMusicXml, loadMusicXmlSync } from 'audio-mixer-engine';
+
+// Load from ArrayBuffer (MXL or plain XML)
+const xmlString = await loadMusicXml(fileArrayBuffer);
+
+// Or load synchronously when data is already available
+const xmlString2 = loadMusicXmlSync(uint8ArrayData);
+
+// Convert to parsedData (same format as MidiParser output)
+const converter = new MusicXmlConverter();
+const parsedData = converter.convert(xmlString, {
+  defaultTempo: 120,      // Fallback tempo if none in score
+  defaultVelocity: 80     // Fallback note velocity
+}, metadataOverrides);    // Optional: override title, composer, per-part instruments
+
+// parsedData includes parts, barStructure, metadata, and structureMetadata
+// Use with PlaybackManager or MidiPlayer just like MIDI-parsed data
+```
+
+### Metadata Utilities
+
+```javascript
+import { resolveInstrument, normalizeLegacyMetadata } from 'audio-mixer-engine';
+
+// Map instrument names/numbers to MIDI program numbers
+resolveInstrument('piano');       // 0
+resolveInstrument('choir_aahs');  // 52
+resolveInstrument(40);            // 40
+
+// Normalize legacy v1 metadata format to v2
+const normalized = normalizeLegacyMetadata(legacyMetadata);
+```
+
 ## Mixer Example
 
 ```javascript
@@ -251,11 +324,13 @@ class AudioMixer {
 
 ## Additional Documentation
 
+- **[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
 - **[INTERFACE.md](./INTERFACE.md)** - Complete interface contract for UI integration
 - **[INIT_PROGRESS.md](./INIT_PROGRESS.md)** - Initialization progress tracking and best practices
+- **[IOS_AUDIO_RESUMPTION.md](./IOS_AUDIO_RESUMPTION.md)** - Handling iOS screen lock/background audio suspension
 
 ## Development
 
@@ -281,3 +356,4 @@ MIT License - see LICENSE file for details.
 
 - **Chromium browsers** (Chrome, Edge, Brave): May experience audio distortion due to Web Audio API bugs
 - **Safari**: Should work with standard Web Audio API support
+- **iOS Safari**: AudioContext is suspended on screen lock/app background. Consuming applications must handle resumption -- see [IOS_AUDIO_RESUMPTION.md](./IOS_AUDIO_RESUMPTION.md)