audio-mixer-engine 1.2.0 → 1.3.0

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "audio-mixer-engine",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Audio engine library for audio mixer applications with MIDI parsing, playback, and synthesis",
   "main": "dist/audio-mixer-engine.cjs.js",
   "module": "dist/audio-mixer-engine.es.js",

package/src/index.js

@@ -25,6 +25,9 @@ export { default as MidiPlayer } from './lib/midi-player.js';
 export { default as MusicXmlConverter } from './lib/musicxml-converter.js';
 export { loadMusicXml, loadMusicXmlSync } from './lib/musicxml/mxl-loader.js';
 
+// Shared metadata utilities
+export { resolveInstrument, normalizeLegacyMetadata } from './lib/metadata-utils.js';
+
 // Playback manager
 export { default as PlaybackManager } from './lib/playback-manager.js';
 

package/src/lib/metadata-utils.js

@@ -0,0 +1,140 @@
+/**
+ * Shared metadata utilities extracted from MidiParser.
+ * Pure functions for resolving instruments and normalizing legacy metadata formats.
+ */
+
+/**
+ * Resolve instrument to MIDI program number.
+ * Accepts a number (returned as-is), a string instrument name (looked up), or defaults to 0 (piano).
+ * @param {number|string} instrument - Instrument identifier
+ * @returns {number} MIDI program number
+ */
+export function resolveInstrument(instrument) {
+  if (typeof instrument === 'number') {
+    return instrument;
+  }
+
+  if (typeof instrument === 'string') {
+    const instrumentMap = {
+      'choir_aahs': 52,
+      'piano': 0,
+      'acoustic_grand_piano': 0,
+      'bright_acoustic_piano': 1,
+      'electric_grand_piano': 2,
+      'strings': 48,
+      'string_ensemble_1': 48,
+      'violin': 40,
+      'viola': 41,
+      'cello': 42,
+      'contrabass': 43
+    };
+
+    const normalized = instrument.toLowerCase().replace(/ /g, '_');
+    return instrumentMap[normalized] !== undefined ? instrumentMap[normalized] : 0;
+  }
+
+  return 0; // Default to piano
+}
+
+/**
+ * Parse URL query parameters.
+ * @param {string} url - URL string with query parameters
+ * @returns {Object} Object with parameter key-value pairs
+ */
+export function parseUrlParams(url) {
+  const params = {};
+
+  const queryStart = url.indexOf('?');
+  if (queryStart === -1) {
+    return params;
+  }
+
+  const queryString = url.substring(queryStart + 1);
+
+  const pairs = queryString.split('&');
+  for (const pair of pairs) {
+    const [key, value] = pair.split('=');
+    if (key && value !== undefined) {
+      params[key] = value;
+    }
+  }
+
+  return params;
+}
+
+/**
+ * Convert legacy parts array to current format object.
+ * Parses URL query parameters (track, prog) from legacy format.
+ * @param {Array} legacyParts - Array of part objects with url, name, volume
+ * @returns {Object} Parts object with channel and instrument
+ */
+export function convertLegacyParts(legacyParts) {
+  const parts = {};
+
+  for (const legacyPart of legacyParts) {
+    if (!legacyPart.name || !legacyPart.url) {
+      continue;
+    }
+
+    const partKey = legacyPart.name.toLowerCase();
+    const urlParams = parseUrlParams(legacyPart.url);
+    const partConfig = {};
+
+    if (urlParams.track !== undefined) {
+      partConfig.channel = parseInt(urlParams.track, 10);
+    }
+
+    if (urlParams.prog !== undefined) {
+      partConfig.instrument = parseInt(urlParams.prog, 10);
+    }
+
+    if (partConfig.channel !== undefined) {
+      parts[partKey] = partConfig;
+    }
+  }
+
+  return parts;
+}
+
+/**
+ * Normalize legacy metadata format (v1) to current format (v2).
+ * Detects and converts:
+ * - scores[] array wrapper -> unwraps scores[0]
+ * - parts array with URLs -> parts object with trackIndex/instrument
+ * - bars array -> preserved for beat mapping
+ *
+ * Mutates and returns the metadata object, or returns an empty object if input is falsy/empty.
+ * @param {Object|null} metadata - Raw metadata overrides
+ * @returns {Object} Normalized metadata object (same reference if mutated, or new empty object)
+ */
+export function normalizeLegacyMetadata(metadata) {
+  if (!metadata || Object.keys(metadata).length === 0) {
+    return metadata || {};
+  }
+
+  // Detect legacy format: has 'scores' array wrapper
+  if (metadata.scores && Array.isArray(metadata.scores) && metadata.scores.length > 0) {
+    const score = metadata.scores[0];
+
+    if (score.parts) {
+      metadata.parts = convertLegacyParts(score.parts);
+    }
+
+    if (score.bars) {
+      metadata.bars = score.bars;
+    }
+
+    delete metadata.scores;
+  }
+  // If no 'scores' wrapper but has legacy parts array (array instead of object)
+  else if (metadata.parts && Array.isArray(metadata.parts)) {
+    metadata.parts = convertLegacyParts(metadata.parts);
+  }
+
+  // Remove legacy fields that should be ignored
+  delete metadata.type;
+  delete metadata.version;
+  delete metadata.subtitle;
+
+  return metadata;
+}

package/src/lib/midi-parser.js

@@ -1,3 +1,5 @@
+import { resolveInstrument, normalizeLegacyMetadata, convertLegacyParts, parseUrlParams } from './metadata-utils.js';
+
 /**
  * MidiParser - A class for parsing MIDI files
  * Extracts parts, bar structure, and metadata
@@ -63,39 +65,7 @@ class MidiParser {
    * @private
    */
   _normalizeLegacyMetadata() {
-    if (!this.metadataOverrides || Object.keys(this.metadataOverrides).length === 0) {
-      return;
-    }
-
-    const metadata = this.metadataOverrides;
-
-    // Detect legacy format: has 'scores' array wrapper
-    if (metadata.scores && Array.isArray(metadata.scores) && metadata.scores.length > 0) {
-      const score = metadata.scores[0];
-
-      // Unwrap scores[0] - merge it with top-level metadata
-      if (score.parts) {
-        // Convert legacy parts array to current format object
-        metadata.parts = this._convertLegacyParts(score.parts);
-      }
-
-      // Preserve bars array if present
-      if (score.bars) {
-        metadata.bars = score.bars;
-      }
-
-      // Remove the scores wrapper
-      delete metadata.scores;
-    }
-    // If no 'scores' wrapper but has legacy parts array (array instead of object)
-    else if (metadata.parts && Array.isArray(metadata.parts)) {
-      metadata.parts = this._convertLegacyParts(metadata.parts);
-    }
-
-    // Remove legacy fields that should be ignored
-    delete metadata.type;
-    delete metadata.version;
-    delete metadata.subtitle;
+    this.metadataOverrides = normalizeLegacyMetadata(this.metadataOverrides);
   }
 
   /**
@@ -106,39 +76,7 @@ class MidiParser {
    * @returns {Object} Parts object with channel and instrument
    */
   _convertLegacyParts(legacyParts) {
-    const parts = {};
-
-    for (const legacyPart of legacyParts) {
-      if (!legacyPart.name || !legacyPart.url) {
-        continue;
-      }
-
-      // Convert part name to lowercase for consistency
-      const partKey = legacyPart.name.toLowerCase();
-
-      // Parse URL query parameters
-      const urlParams = this._parseUrlParams(legacyPart.url);
-
-      // Create part config
-      const partConfig = {};
-
-      // Extract channel from 'track' parameter (legacy 'track' actually meant MIDI channel)
-      if (urlParams.track !== undefined) {
-        partConfig.channel = parseInt(urlParams.track, 10);
-      }
-
-      // Extract instrument from 'prog' parameter
-      if (urlParams.prog !== undefined) {
-        partConfig.instrument = parseInt(urlParams.prog, 10);
-      }
-
-      // Only add part if it has a channel
-      if (partConfig.channel !== undefined) {
-        parts[partKey] = partConfig;
-      }
-    }
-
-    return parts;
+    return convertLegacyParts(legacyParts);
   }
 
   /**
@@ -148,26 +86,7 @@ class MidiParser {
    * @returns {Object} Object with parameter key-value pairs
    */
   _parseUrlParams(url) {
-    const params = {};
-
-    // Find query string (everything after '?')
-    const queryStart = url.indexOf('?');
-    if (queryStart === -1) {
-      return params;
-    }
-
-    const queryString = url.substring(queryStart + 1);
-
-    // Parse parameters
-    const pairs = queryString.split('&');
-    for (const pair of pairs) {
-      const [key, value] = pair.split('=');
-      if (key && value !== undefined) {
-        params[key] = value;
-      }
-    }
-
-    return params;
+    return parseUrlParams(url);
   }
 
   /**
@@ -895,33 +814,7 @@ class MidiParser {
    * @private
    */
   _resolveInstrument(instrument) {
-    if (typeof instrument === 'number') {
-      return instrument;
-    }
-
-    // String instrument name - convert to program number
-    // Import getInstrumentProgram if available, otherwise use simple mapping
-    if (typeof instrument === 'string') {
-      // Simple mapping for common instruments (can be expanded)
-      const instrumentMap = {
-        'choir_aahs': 52,
-        'piano': 0,
-        'acoustic_grand_piano': 0,
-        'bright_acoustic_piano': 1,
-        'electric_grand_piano': 2,
-        'strings': 48,
-        'string_ensemble_1': 48,
-        'violin': 40,
-        'viola': 41,
-        'cello': 42,
-        'contrabass': 43
-      };
-
-      const normalized = instrument.toLowerCase().replace(/ /g, '_');
-      return instrumentMap[normalized] !== undefined ? instrumentMap[normalized] : 0;
-    }
-
-    return 0; // Default to piano
+    return resolveInstrument(instrument);
   }
 
   /**

package/src/lib/musicxml-converter.js

@@ -20,6 +20,7 @@ import {
   generateBarsArray,
   extractRehearsalMarks
 } from './musicxml/structure-analyzer.js';
+import { resolveInstrument, normalizeLegacyMetadata } from './metadata-utils.js';
 
 class MusicXmlConverter {
   constructor() {
@@ -33,9 +34,10 @@ class MusicXmlConverter {
    * @param {Object} [options]
    * @param {number} [options.defaultTempo=120] - Default tempo if none specified in score
    * @param {number} [options.defaultVelocity=80] - Default note velocity
+   * @param {Object|null} [metadataOverrides=null] - Optional metadata overrides (title, composer, parts instrument mapping)
    * @returns {Object} parsedData with parts, barStructure, metadata, structureMetadata
    */
-  convert(input, options = {}) {
+  convert(input, options = {}, metadataOverrides = null) {
     const doc = typeof input === 'string' ? parseXml(input) : input;
     const root = doc.documentElement;
 
@@ -238,7 +240,8 @@ class MusicXmlConverter {
       };
     }
 
-    return {
+    // Build result object
+    const result = {
       parts,
       barStructure,
       metadata: {
@@ -258,6 +261,79 @@ class MusicXmlConverter {
         parts: structureParts
       }
     };
+
+    // Apply metadata overrides if provided
+    if (metadataOverrides) {
+      this._applyMetadataOverrides(result, metadataOverrides);
+    }
+
+    return result;
+  }
+
+  /**
+   * Apply metadata overrides to the converted result.
+   * Handles legacy format normalization, title/composer overrides,
+   * and per-part instrument/order overrides via case-insensitive name matching.
+   * @param {Object} result - The parsedData result to modify in place
+   * @param {Object} overrides - Raw metadata overrides
+   * @private
+   */
+  _applyMetadataOverrides(result, overrides) {
+    // Normalize legacy metadata format (scores[] wrapper, parts array, etc.)
+    const normalized = normalizeLegacyMetadata(
+      typeof overrides === 'string' ? JSON.parse(overrides) : { ...overrides }
+    );
+
+    // Override title/composer/arranger/copyright
+    if (normalized.title !== undefined) {
+      result.metadata.title = normalized.title;
+      result.structureMetadata.title = normalized.title;
+    }
+    if (normalized.composer !== undefined) {
+      result.metadata.composer = normalized.composer;
+      result.structureMetadata.composer = normalized.composer;
+    }
+    if (normalized.arranger !== undefined) {
+      result.metadata.arranger = normalized.arranger;
+    }
+    if (normalized.copyright !== undefined) {
+      result.metadata.copyright = normalized.copyright;
+    }
+
+    // Apply per-part overrides (instrument, order) via case-insensitive name matching
+    if (normalized.parts && typeof normalized.parts === 'object') {
+      // Build lowercase→originalName lookup from XML parts
+      const lowerToOriginal = {};
+      for (const xmlPartName of Object.keys(result.parts)) {
+        lowerToOriginal[xmlPartName.toLowerCase()] = xmlPartName;
+      }
+
+      for (const [metaKey, partConfig] of Object.entries(normalized.parts)) {
+        const matchedName = lowerToOriginal[metaKey.toLowerCase()];
+        if (!matchedName) {
+          console.warn(`Metadata override: part "${metaKey}" does not match any XML part. Available: ${Object.keys(result.parts).join(', ')}`);
+          continue;
+        }
+
+        // Apply instrument override
+        if (partConfig.instrument !== undefined && partConfig.instrument !== null) {
+          const resolvedInstrument = resolveInstrument(partConfig.instrument);
+          result.parts[matchedName].defaultInstrument = resolvedInstrument;
+          result.parts[matchedName].programChanges = [];
+          if (result.structureMetadata.parts[matchedName]) {
+            result.structureMetadata.parts[matchedName].instrument = resolvedInstrument;
+          }
+        }
+
+        // Apply order override
+        if (partConfig.order !== undefined && typeof partConfig.order === 'number') {
+          if (result.structureMetadata.parts[matchedName]) {
+            result.structureMetadata.parts[matchedName].order = partConfig.order;
+          }
+        }
+      }
+    }
+
   }
 
   /**

package/src/lib/playback-manager.js

@@ -1,6 +1,8 @@
 import mitt from 'mitt';
 import MidiParser from './midi-parser.js';
 import MidiPlayer from './midi-player.js';
+import MusicXmlConverter from './musicxml-converter.js';
+import { loadMusicXmlSync } from './musicxml/mxl-loader.js';
 
 /**
  * PlaybackManager - High-level orchestration for MIDI playback, metronome, and lead-in
@@ -44,6 +46,7 @@ export default class PlaybackManager {
 
     this.eventBus = mitt();
     this._parser = new MidiParser(); // Internal MIDI parser
+    this._musicXmlConverter = new MusicXmlConverter(); // Internal MusicXML converter
     this._partOutputsMap = new Map(); // Track part outputs for iteration
 
     // Store instrument map separately (allows parsing before audio engine ready)
@@ -171,19 +174,53 @@ export default class PlaybackManager {
       }
       // Otherwise, player will be created when setAudioEngine() is called
 
+    } else if (typeof input === 'string') {
+      // String input - check if it looks like MusicXML
+      const trimmed = input.trimStart();
+      if (trimmed.startsWith('<?xml') || trimmed.startsWith('<score-partwise') || trimmed.startsWith('<score-timewise')) {
+        // MusicXML string - convert directly (use trimmed to avoid XML parse errors from leading whitespace)
+        this.parsedData = this._musicXmlConverter.convert(trimmed, {}, metadata);
+        this.instrumentMap = instrumentMap || this._createDefaultInstrumentMap(this.parsedData.parts);
+
+        if (this._audioEngineReady) {
+          this._setupPlayerWithAudio();
+        }
+      } else {
+        throw new Error('Invalid input string. Expected MusicXML content (must start with <?xml, <score-partwise>, or <score-timewise>)');
+      }
+
     } else if (input instanceof ArrayBuffer) {
-      // Parse raw MIDI data (with metadata for normalization)
-      // This works WITHOUT audio engine - key benefit!
-      this.parsedData = await this._parser.parse(input, metadata);
+      // ArrayBuffer input - detect format from magic bytes
+      const data = new Uint8Array(input);
 
-      // Create instrument mapping if not provided
-      this.instrumentMap = instrumentMap || this._createDefaultInstrumentMap(this.parsedData.parts);
+      if (data.length >= 4 && data[0] === 0x4D && data[1] === 0x54 && data[2] === 0x68 && data[3] === 0x64) {
+        // MThd magic bytes - MIDI file
+        this.parsedData = await this._parser.parse(input, metadata);
+        this.instrumentMap = instrumentMap || this._createDefaultInstrumentMap(this.parsedData.parts);
 
-      // If audio engine ready, create player now
-      if (this._audioEngineReady) {
-        this._setupPlayerWithAudio();
+        if (this._audioEngineReady) {
+          this._setupPlayerWithAudio();
+        }
+
+      } else if (data.length >= 4 && data[0] === 0x50 && data[1] === 0x4B && data[2] === 0x03 && data[3] === 0x04) {
+        // PK\x03\x04 magic bytes - ZIP/MXL file
+        const xmlString = loadMusicXmlSync(input);
+        this.parsedData = this._musicXmlConverter.convert(xmlString, {}, metadata);
+        this.instrumentMap = instrumentMap || this._createDefaultInstrumentMap(this.parsedData.parts);
+
+        if (this._audioEngineReady) {
+          this._setupPlayerWithAudio();
+        }
+
+      } else {
+        // Unknown format - try MIDI parser for backwards compatibility
+        this.parsedData = await this._parser.parse(input, metadata);
+        this.instrumentMap = instrumentMap || this._createDefaultInstrumentMap(this.parsedData.parts);
+
+        if (this._audioEngineReady) {
+          this._setupPlayerWithAudio();
+        }
       }
-      // Otherwise, player will be created when setAudioEngine() is called
 
     } else if (input && typeof input === 'object' && input.parts) {
       // Parsed MIDI data object
@@ -205,7 +242,7 @@ export default class PlaybackManager {
       // Otherwise, player will be created when setAudioEngine() is called
 
     } else {
-      throw new Error('Invalid input type. Expected MidiPlayer, parsed MIDI data, or ArrayBuffer');
+      throw new Error('Invalid input type. Expected MidiPlayer, parsed data object, ArrayBuffer (MIDI/MXL), or MusicXML string');
     }
   }