audio-mixer-engine 1.1.5 → 1.2.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,23 @@ for (const [partName, outputNode] of manager.getPartOutputs()) {
 await manager.play({ leadIn: true, metronome: true });
 ```
 
+### Loading MusicXML Files
+
+```javascript
+import { MusicXmlConverter, loadMusicXml, PlaybackManager } from 'audio-mixer-engine';
+
+// Load MusicXML or MXL file (auto-detects format)
+const xmlString = await loadMusicXml(fileArrayBuffer);
+
+// Convert to parsedData and load into PlaybackManager
+const converter = new MusicXmlConverter();
+const parsedData = converter.convert(xmlString);
+await manager.load(parsedData);
+
+// From here on, playback works exactly the same as MIDI
+await manager.play({ leadIn: true, metronome: true });
+```
+
 ## 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.
@@ -198,6 +216,28 @@ 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
+});
+
+// parsedData includes parts, barStructure, metadata, and structureMetadata
+// Use with PlaybackManager or MidiPlayer just like MIDI-parsed data
+```
+
 ## Mixer Example
 
 ```javascript
@@ -251,11 +291,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 +323,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)