audio-mixer-engine 1.2.0 → 1.3.1

package/README.md

@@ -66,21 +66,36 @@ await manager.play({ leadIn: true, metronome: true });
 
 ### Loading MusicXML Files
 
+PlaybackManager auto-detects MusicXML strings and MXL/ZIP ArrayBuffers:
+
 ```javascript
-import { MusicXmlConverter, loadMusicXml, PlaybackManager } from 'audio-mixer-engine';
+import { loadMusicXml } from 'audio-mixer-engine';
+
+// MXL file (ArrayBuffer) — auto-detected from ZIP magic bytes
+await manager.load(mxlArrayBuffer);
 
-// Load MusicXML or MXL file (auto-detects format)
+// MusicXML string — auto-detected from <?xml or <score-partwise> prefix
 const xmlString = await loadMusicXml(fileArrayBuffer);
+await manager.load(xmlString);
 
-// Convert to parsedData and load into PlaybackManager
-const converter = new MusicXmlConverter();
-const parsedData = converter.convert(xmlString);
-await manager.load(parsedData);
+// 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.
@@ -98,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
@@ -232,12 +251,26 @@ 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