audio-mixer-engine 1.3.3 → 1.3.4

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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "audio-mixer-engine",
-  "version": "1.3.3",
+  "version": "1.3.4",
   "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/lib/musicxml/note-extractor.js

@@ -131,6 +131,7 @@ export class NoteExtractor {
       const isGrace = getChild(child, 'grace') !== null;
       const durationXml = getChildNumber(child, 'duration', 0);
       const durationTicks = this.timing.xmlDurationToTicks(durationXml);
+      const isTuplet = getChild(child, 'time-modification') !== null;
 
       // Grace notes: skip (no duration effect)
       if (isGrace) continue;
@@ -175,9 +176,11 @@ export class NoteExtractor {
         if (tieStart) {
           // Middle of a tie chain: extend the end tick
           pending.endTick = noteStart + durationTicks;
+          pending.isTuplet = pending.isTuplet || isTuplet;
         } else {
           // End of tie: emit the completed note
           pending.endTick = noteStart + durationTicks;
+          pending.isTuplet = pending.isTuplet || isTuplet;
           notes.push(this._buildNote(pending, partChannel, sourceTrackIndex));
           this.pendingTies.delete(midiPitch);
         }
@@ -187,7 +190,8 @@ export class NoteExtractor {
           pitch: midiPitch,
           startTick: noteStart,
           endTick: noteStart + durationTicks,
-          velocity: this.currentVelocity
+          velocity: this.currentVelocity,
+          isTuplet
         });
       } else {
         // Regular note (not tied)
@@ -195,7 +199,8 @@ export class NoteExtractor {
           pitch: midiPitch,
           startTick: noteStart,
           endTick: noteStart + durationTicks,
-          velocity: this.currentVelocity
+          velocity: this.currentVelocity,
+          isTuplet
         }, partChannel, sourceTrackIndex));
       }
 
@@ -209,7 +214,8 @@ export class NoteExtractor {
             text,
             syllabic: syllabic || 'single',
             tick: noteStart,
-            time: this.timing.tickToTime(noteStart)
+            time: this.timing.tickToTime(noteStart),
+            isTuplet
           });
         }
       }
@@ -257,7 +263,8 @@ export class NoteExtractor {
       endTime: this.timing.tickToTime(data.endTick),
       velocity: data.velocity,
       channel,
-      sourceTrackIndex
+      sourceTrackIndex,
+      isTuplet: data.isTuplet || false
     };
   }
 

package/src/lib/musicxml-converter.js

@@ -250,9 +250,13 @@ class MusicXmlConverter {
 
     // Apply swing timing if any swing directives were found.
     // Transforms note and lyric tick positions; does not affect barStructure.
-    if (timingEngine.swingMap.length > 0) {
-      for (const part of Object.values(parts)) {
-        for (const note of part.notes) {
+    // Tuplet notes (isTuplet=true) are excluded: their timing already embodies the
+    // subdivision that swing represents, so applying swing would double-count it.
+    // The isTuplet flag is an internal marker and is stripped here before output.
+    const hasSwing = timingEngine.swingMap.length > 0;
+    for (const part of Object.values(parts)) {
+      for (const note of part.notes) {
+        if (hasSwing && !note.isTuplet) {
           const s = timingEngine.applySwingToTick(note.startTick);
           const e = timingEngine.applySwingToTick(note.endTick);
           note.startTick = s;
@@ -261,11 +265,15 @@ class MusicXmlConverter {
           note.startTime = timingEngine.tickToTime(s);
           note.endTime = timingEngine.tickToTime(e);
         }
-        for (const lyric of part.lyrics) {
+        delete note.isTuplet;
+      }
+      for (const lyric of part.lyrics) {
+        if (hasSwing && !lyric.isTuplet) {
           const t = timingEngine.applySwingToTick(lyric.tick);
           lyric.tick = t;
           lyric.time = timingEngine.tickToTime(t);
         }
+        delete lyric.isTuplet;
       }
     }