audio-mixer-engine 1.3.1 → 1.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "audio-mixer-engine",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "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/timing-engine.js

@@ -38,6 +38,10 @@ export class TimingEngine {
 
     // Time signature changes: array of { tick, numerator, denominator }
     this.timeSigChanges = [{ tick: 0, numerator: 4, denominator: 4 }];
+
+    // Swing map: array of { tick, first, second, swingType } or { tick, straight: true }
+    // Built during the main walk; always starts empty and is populated measure by measure.
+    this.swingMap = [];
   }
 
   /**
@@ -87,6 +91,69 @@ export class TimingEngine {
     }
   }
 
+  /**
+   * Record a swing directive at the current tick position.
+   * Called when a <swing> element is found inside a <sound> direction.
+   *
+   * @param {Object} params
+   * @param {boolean} [params.straight] - If true, turns swing off (play straight)
+   * @param {number} [params.first] - Ratio numerator for the on-beat note
+   * @param {number} [params.second] - Ratio denominator for the off-beat note
+   * @param {string} [params.swingType] - 'eighth' (default) or 'sixteenth'
+   */
+  processSwing(params) {
+    this.swingMap.push({ tick: this.currentTick, ...params });
+  }
+
+  /**
+   * Apply swing timing transformation to a straight tick position.
+   *
+   * For each beat (defined by the swing type), the straight midpoint is shifted
+   * to the swing ratio point:
+   *   swingPoint = swingUnit × first / (first + second)
+   * Notes before the midpoint are stretched; notes after are compressed.
+   * Beat boundaries (multiples of swingUnit) are never moved.
+   *
+   * @param {number} tick - Original (straight) canonical tick
+   * @returns {number} Swung canonical tick
+   */
+  applySwingToTick(tick) {
+    // Find the active swing parameters at this tick
+    let active = null;
+    for (const entry of this.swingMap) {
+      if (entry.tick > tick) break;
+      active = entry.straight ? null : entry;
+    }
+    if (!active) return tick; // No swing active — return unchanged
+
+    const { first, second, swingType } = active;
+
+    // Swing unit: the note-pair duration that gets swung
+    // 'eighth' → quarter note = ticksPerBeat; 'sixteenth' → eighth note = ticksPerBeat/2
+    const swingUnit = swingType === 'sixteenth'
+      ? this.ticksPerBeat / 2
+      : this.ticksPerBeat;
+
+    const straightHalf = swingUnit / 2;
+    const swingPoint = swingUnit * first / (first + second);
+
+    const beatIndex = Math.floor(tick / swingUnit);
+    const beatOffset = tick - beatIndex * swingUnit;
+
+    let mappedOffset;
+    if (beatOffset <= straightHalf) {
+      // First half: stretch from [0, straightHalf] → [0, swingPoint]
+      mappedOffset = beatOffset * swingPoint / straightHalf;
+    } else {
+      // Second half: compress from (straightHalf, swingUnit] → (swingPoint, swingUnit]
+      mappedOffset = swingPoint +
+        (beatOffset - straightHalf) * (swingUnit - swingPoint) / straightHalf;
+    }
+
+    return Math.round(beatIndex * swingUnit + mappedOffset);
+  }
+
+
   /**
    * Convert a MusicXML duration value (in source divisions) to canonical ticks.
    * @param {number} xmlDuration - Duration from <duration> element

package/src/lib/musicxml-converter.js

@@ -10,7 +10,7 @@
  *   const parsedData = converter.convert(musicXmlString, { defaultTempo: 120 });
  *   await playbackManager.load(parsedData);
  */
-import { parseXml, getChild, getChildren, getAttr } from './musicxml/xml-helpers.js';
+import { parseXml, getChild, getChildren, getAttr, getChildText, getChildNumber } from './musicxml/xml-helpers.js';
 import { extractMetadata } from './musicxml/metadata-extractor.js';
 import { TimingEngine, DEFAULT_TICKS_PER_BEAT } from './musicxml/timing-engine.js';
 import { NoteExtractor } from './musicxml/note-extractor.js';
@@ -147,13 +147,28 @@ class MusicXmlConverter {
           }
         }
       }
-      // Check for tempo in directions
+      // Check for tempo and swing in directions
       const directions = getChildren(m, 'direction');
       for (const dir of directions) {
         const sound = getChild(dir, 'sound');
         if (sound) {
           const tempo = parseFloat(sound.getAttribute('tempo'));
           if (!isNaN(tempo) && tempo > 0) cache.tempo = tempo;
+
+          // Detect <swing> element
+          const swingEl = getChild(sound, 'swing');
+          if (swingEl) {
+            if (getChild(swingEl, 'straight')) {
+              cache.swing = { straight: true };
+            } else {
+              const first = getChildNumber(swingEl, 'first');
+              const second = getChildNumber(swingEl, 'second');
+              const swingType = getChildText(swingEl, 'swing-type') || 'eighth';
+              if (first !== null && second !== null && first > 0 && second > 0) {
+                cache.swing = { first, second, swingType };
+              }
+            }
+          }
         }
       }
       measureTimingCache.set(mi, cache);
@@ -182,6 +197,9 @@ class MusicXmlConverter {
       if (cachedTiming.tempo) {
         timingEngine.processTempo(cachedTiming.tempo);
       }
+      if (cachedTiming.swing) {
+        timingEngine.processSwing(cachedTiming.swing);
+      }
 
       // Generate barStructure entry at current tick position
       // Use actual beats from unrolled entry (handles partial bars)
@@ -223,6 +241,34 @@ class MusicXmlConverter {
       parts[partName].notes.push(...remainingNotes);
     }
 
+    // Sort notes by startTick within each part.
+    // Multi-staff parts (e.g. piano) use <backup> elements which produce
+    // unsorted notes when staves/voices are interleaved in the XML.
+    for (const part of Object.values(parts)) {
+      part.notes.sort((a, b) => a.startTick - b.startTick || a.pitch - b.pitch);
+    }
+
+    // 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) {
+          const s = timingEngine.applySwingToTick(note.startTick);
+          const e = timingEngine.applySwingToTick(note.endTick);
+          note.startTick = s;
+          note.endTick = e;
+          note.duration = e - s;
+          note.startTime = timingEngine.tickToTime(s);
+          note.endTime = timingEngine.tickToTime(e);
+        }
+        for (const lyric of part.lyrics) {
+          const t = timingEngine.applySwingToTick(lyric.tick);
+          lyric.tick = t;
+          lyric.time = timingEngine.tickToTime(t);
+        }
+      }
+    }
+
     // 7. Build the parsedData output
     const partNames = metadata.partInfos.map((p, i) => ({
       index: i,