musicxml-io 0.7.0 → 0.7.2

package/dist/{chunk-LS5OLRZP.mjs → chunk-IM3FS32Q.mjs}

@@ -8,7 +8,7 @@ import {
   getMeasureEndPosition,
   pitchToSemitone,
   semitoneToKeyAwarePitch
-} from "./chunk-CCSOG7HU.mjs";
+} from "./chunk-VQUFSGB5.mjs";
 
 // src/id.ts
 import { customAlphabet } from "nanoid";

package/dist/{chunk-YCNKCOR2.js → chunk-S5MWUJU2.js}

@@ -8,7 +8,7 @@
 
 
 
-var _chunkCJZK2DGVjs = require('./chunk-CJZK2DGV.js');
+var _chunkCHMV7XWYjs = require('./chunk-CHMV7XWY.js');
 
 // src/id.ts
 var _nanoid = require('nanoid');
@@ -1562,18 +1562,18 @@ function setNotePitchBySemitone(score, options) {
   const result = cloneScore(score);
   const measure = result.parts[options.partIndex].measures[options.measureIndex];
   const measureNumber = _nullishCoalesce(measure.number, () => ( String(options.measureIndex + 1)));
-  const attrs = _chunkCJZK2DGVjs.getAttributesAtMeasure.call(void 0, result, { part: options.partIndex, measure: measureNumber });
+  const attrs = _chunkCHMV7XWYjs.getAttributesAtMeasure.call(void 0, result, { part: options.partIndex, measure: measureNumber });
   const keySignature = _nullishCoalesce(attrs.key, () => ( { fifths: 0 }));
   let noteCount = 0;
   for (const entry of measure.entries) {
     if (entry.type === "note" && !entry.rest) {
       if (noteCount === options.noteIndex) {
-        const notePosition = _chunkCJZK2DGVjs.getAbsolutePositionForNote.call(void 0, entry, measure);
-        const accidentalsInMeasure = _chunkCJZK2DGVjs.getAccidentalsInMeasure.call(void 0, measure, notePosition, entry.voice);
-        const newPitch = _chunkCJZK2DGVjs.semitoneToKeyAwarePitch.call(void 0, options.semitone, keySignature, {
+        const notePosition = _chunkCHMV7XWYjs.getAbsolutePositionForNote.call(void 0, entry, measure);
+        const accidentalsInMeasure = _chunkCHMV7XWYjs.getAccidentalsInMeasure.call(void 0, measure, notePosition, entry.voice);
+        const newPitch = _chunkCHMV7XWYjs.semitoneToKeyAwarePitch.call(void 0, options.semitone, keySignature, {
           preferSharp: options.preferSharp
         });
-        const accidental = _chunkCJZK2DGVjs.determineAccidental.call(void 0, newPitch, keySignature, accidentalsInMeasure);
+        const accidental = _chunkCHMV7XWYjs.determineAccidental.call(void 0, newPitch, keySignature, accidentalsInMeasure);
         entry.pitch = newPitch;
         if (accidental) {
           entry.accidental = { value: accidental };
@@ -1607,7 +1607,7 @@ function shiftNotePitch(score, options) {
         if (!entry.pitch) {
           return failure([operationError("NOTE_NOT_FOUND", "Note has no pitch", { partIndex: options.partIndex, measureIndex: options.measureIndex })]);
         }
-        currentSemitone = _chunkCJZK2DGVjs.pitchToSemitone.call(void 0, entry.pitch);
+        currentSemitone = _chunkCHMV7XWYjs.pitchToSemitone.call(void 0, entry.pitch);
         break;
       }
       noteCount++;
@@ -1635,7 +1635,7 @@ function raiseAccidental(score, options) {
   const result = cloneScore(score);
   const measure = result.parts[options.partIndex].measures[options.measureIndex];
   const measureNumber = _nullishCoalesce(measure.number, () => ( String(options.measureIndex + 1)));
-  const attrs = _chunkCJZK2DGVjs.getAttributesAtMeasure.call(void 0, result, { part: options.partIndex, measure: measureNumber });
+  const attrs = _chunkCHMV7XWYjs.getAttributesAtMeasure.call(void 0, result, { part: options.partIndex, measure: measureNumber });
   const keySignature = _nullishCoalesce(attrs.key, () => ( { fifths: 0 }));
   let noteCount = 0;
   for (const entry of measure.entries) {
@@ -1650,9 +1650,9 @@ function raiseAccidental(score, options) {
           return failure([operationError("ACCIDENTAL_OUT_OF_BOUNDS", `Cannot raise accidental beyond double-sharp (current: ${currentAlter})`, { partIndex: options.partIndex, measureIndex: options.measureIndex })]);
         }
         entry.pitch.alter = newAlter === 0 ? void 0 : newAlter;
-        const notePosition = _chunkCJZK2DGVjs.getAbsolutePositionForNote.call(void 0, entry, measure);
-        const accidentalsInMeasure = _chunkCJZK2DGVjs.getAccidentalsInMeasure.call(void 0, measure, notePosition, entry.voice);
-        const accidental = _chunkCJZK2DGVjs.determineAccidental.call(void 0, entry.pitch, keySignature, accidentalsInMeasure);
+        const notePosition = _chunkCHMV7XWYjs.getAbsolutePositionForNote.call(void 0, entry, measure);
+        const accidentalsInMeasure = _chunkCHMV7XWYjs.getAccidentalsInMeasure.call(void 0, measure, notePosition, entry.voice);
+        const accidental = _chunkCHMV7XWYjs.determineAccidental.call(void 0, entry.pitch, keySignature, accidentalsInMeasure);
         if (accidental) {
           entry.accidental = { value: accidental };
         } else {
@@ -1676,7 +1676,7 @@ function lowerAccidental(score, options) {
   const result = cloneScore(score);
   const measure = result.parts[options.partIndex].measures[options.measureIndex];
   const measureNumber = _nullishCoalesce(measure.number, () => ( String(options.measureIndex + 1)));
-  const attrs = _chunkCJZK2DGVjs.getAttributesAtMeasure.call(void 0, result, { part: options.partIndex, measure: measureNumber });
+  const attrs = _chunkCHMV7XWYjs.getAttributesAtMeasure.call(void 0, result, { part: options.partIndex, measure: measureNumber });
   const keySignature = _nullishCoalesce(attrs.key, () => ( { fifths: 0 }));
   let noteCount = 0;
   for (const entry of measure.entries) {
@@ -1691,9 +1691,9 @@ function lowerAccidental(score, options) {
           return failure([operationError("ACCIDENTAL_OUT_OF_BOUNDS", `Cannot lower accidental beyond double-flat (current: ${currentAlter})`, { partIndex: options.partIndex, measureIndex: options.measureIndex })]);
         }
         entry.pitch.alter = newAlter === 0 ? void 0 : newAlter;
-        const notePosition = _chunkCJZK2DGVjs.getAbsolutePositionForNote.call(void 0, entry, measure);
-        const accidentalsInMeasure = _chunkCJZK2DGVjs.getAccidentalsInMeasure.call(void 0, measure, notePosition, entry.voice);
-        const accidental = _chunkCJZK2DGVjs.determineAccidental.call(void 0, entry.pitch, keySignature, accidentalsInMeasure);
+        const notePosition = _chunkCHMV7XWYjs.getAbsolutePositionForNote.call(void 0, entry, measure);
+        const accidentalsInMeasure = _chunkCHMV7XWYjs.getAccidentalsInMeasure.call(void 0, measure, notePosition, entry.voice);
+        const accidental = _chunkCHMV7XWYjs.determineAccidental.call(void 0, entry.pitch, keySignature, accidentalsInMeasure);
         if (accidental) {
           entry.accidental = { value: accidental };
         } else {
@@ -1727,7 +1727,7 @@ function addVoice(score, options) {
   const context = getMeasureContext(result, options.partIndex, options.measureIndex);
   const measureDuration = context.time ? getMeasureDuration(context.divisions, context.time) : context.divisions * 4;
   const rest = createRest(measureDuration, options.voice, options.staff);
-  const currentEnd = _chunkCJZK2DGVjs.getMeasureEndPosition.call(void 0, measure);
+  const currentEnd = _chunkCHMV7XWYjs.getMeasureEndPosition.call(void 0, measure);
   if (currentEnd > 0) {
     measure.entries.push({ _id: generateId(), type: "backup", duration: currentEnd });
   }
@@ -1735,14 +1735,14 @@ function addVoice(score, options) {
   return success(result);
 }
 function transposePitch(pitch, semitones) {
-  const currentSemitone = _chunkCJZK2DGVjs.STEP_SEMITONES[pitch.step] + (_nullishCoalesce(pitch.alter, () => ( 0))) + pitch.octave * 12;
+  const currentSemitone = _chunkCHMV7XWYjs.STEP_SEMITONES[pitch.step] + (_nullishCoalesce(pitch.alter, () => ( 0))) + pitch.octave * 12;
   const targetSemitone = currentSemitone + semitones;
   const targetOctave = Math.floor(targetSemitone / 12);
   const targetPitchClass = (targetSemitone % 12 + 12) % 12;
   let bestStep = "C";
   let bestAlter = 99;
-  for (const step of _chunkCJZK2DGVjs.STEPS) {
-    const stepSemitone = _chunkCJZK2DGVjs.STEP_SEMITONES[step];
+  for (const step of _chunkCHMV7XWYjs.STEPS) {
+    const stepSemitone = _chunkCHMV7XWYjs.STEP_SEMITONES[step];
     let diff = targetPitchClass - stepSemitone;
     if (diff > 6) diff -= 12;
     if (diff < -6) diff += 12;
@@ -3805,7 +3805,7 @@ function addDaCapo(score, options) {
   }
   const result = cloneScore(score);
   const measure = result.parts[partIndex].measures[measureIndex];
-  const attrs = _chunkCJZK2DGVjs.getAttributesAtMeasure.call(void 0, result, { part: partIndex, measure: measureIndex });
+  const attrs = _chunkCHMV7XWYjs.getAttributesAtMeasure.call(void 0, result, { part: partIndex, measure: measureIndex });
   const measureDuration = getMeasureDuration(_nullishCoalesce(attrs.divisions, () => ( 1)), _nullishCoalesce(attrs.time, () => ( { beats: "4", beatType: 4 })));
   const insertPos = _nullishCoalesce(position, () => ( measureDuration));
   const direction = {
@@ -3834,7 +3834,7 @@ function addDalSegno(score, options) {
   }
   const result = cloneScore(score);
   const measure = result.parts[partIndex].measures[measureIndex];
-  const attrs = _chunkCJZK2DGVjs.getAttributesAtMeasure.call(void 0, result, { part: partIndex, measure: measureIndex });
+  const attrs = _chunkCHMV7XWYjs.getAttributesAtMeasure.call(void 0, result, { part: partIndex, measure: measureIndex });
   const measureDuration = getMeasureDuration(_nullishCoalesce(attrs.divisions, () => ( 1)), _nullishCoalesce(attrs.time, () => ( { beats: "4", beatType: 4 })));
   const insertPos = _nullishCoalesce(position, () => ( measureDuration));
   const direction = {
@@ -3863,7 +3863,7 @@ function addFine(score, options) {
   }
   const result = cloneScore(score);
   const measure = result.parts[partIndex].measures[measureIndex];
-  const attrs = _chunkCJZK2DGVjs.getAttributesAtMeasure.call(void 0, result, { part: partIndex, measure: measureIndex });
+  const attrs = _chunkCHMV7XWYjs.getAttributesAtMeasure.call(void 0, result, { part: partIndex, measure: measureIndex });
   const measureDuration = getMeasureDuration(_nullishCoalesce(attrs.divisions, () => ( 1)), _nullishCoalesce(attrs.time, () => ( { beats: "4", beatType: 4 })));
   const insertPos = _nullishCoalesce(position, () => ( measureDuration));
   const direction = {
@@ -3892,7 +3892,7 @@ function addToCoda(score, options) {
   }
   const result = cloneScore(score);
   const measure = result.parts[partIndex].measures[measureIndex];
-  const attrs = _chunkCJZK2DGVjs.getAttributesAtMeasure.call(void 0, result, { part: partIndex, measure: measureIndex });
+  const attrs = _chunkCHMV7XWYjs.getAttributesAtMeasure.call(void 0, result, { part: partIndex, measure: measureIndex });
   const measureDuration = getMeasureDuration(_nullishCoalesce(attrs.divisions, () => ( 1)), _nullishCoalesce(attrs.time, () => ( { beats: "4", beatType: 4 })));
   const insertPos = _nullishCoalesce(position, () => ( measureDuration));
   const direction = {

package/dist/{chunk-CCSOG7HU.mjs → chunk-VQUFSGB5.mjs}

@@ -509,6 +509,363 @@ function hasPlaybackControls(score, options) {
   return controls.repeatStarts.length > 0 || controls.repeatEnds.length > 0 || controls.voltas.length > 0 || controls.jumps.length > 0 || controls.segnoIndex !== null || controls.codaIndex !== null;
 }
 
+// src/query/playback-timeline.ts
+var DEFAULT_FERMATA_HOLD = 1.75;
+var DEFAULT_CAESURA_SECONDS = 0.4;
+var DEFAULT_BREATH_SECONDS = 0.25;
+var DEFAULT_RAMP_STEPS = 12;
+function metronomeBpm(perMinute) {
+  if (perMinute === void 0) return null;
+  const bpm = typeof perMinute === "number" ? perMinute : parseFloat(perMinute);
+  return isNaN(bpm) ? null : bpm;
+}
+function measureMaxPosition(measure) {
+  let position = 0;
+  let max = 0;
+  for (const entry of measure.entries) {
+    if (entry.type === "note") {
+      if (!entry.chord && !entry.grace) {
+        position += entry.duration;
+        if (position > max) max = position;
+      }
+    } else if (entry.type === "backup") {
+      position -= entry.duration;
+    } else if (entry.type === "forward") {
+      position += entry.duration;
+      if (position > max) max = position;
+    }
+  }
+  return max;
+}
+function findTimeSignature(part, measureNumber) {
+  const targetMeasure = parseInt(String(measureNumber), 10);
+  let time;
+  for (const measure of part.measures) {
+    const mNum = parseInt(measure.number, 10);
+    if (!isNaN(targetMeasure) && !isNaN(mNum) && mNum > targetMeasure) break;
+    if (measure.attributes?.time) {
+      time = {
+        beats: parseInt(measure.attributes.time.beats, 10) || 4,
+        beatType: measure.attributes.time.beatType
+      };
+    }
+  }
+  return time;
+}
+function measureEndTick(measure, part, divisions, measureStartTick, maxPosition, ticksPerQuarterNote) {
+  const actualTicks = Math.round(maxPosition * ticksPerQuarterNote / divisions);
+  if (measure.implicit) {
+    return measureStartTick + actualTicks;
+  }
+  const timeAttrs = findTimeSignature(part, measure.number);
+  if (timeAttrs) {
+    const measureDuration = timeAttrs.beats / timeAttrs.beatType * 4 * divisions;
+    const calculatedTicks = Math.round(measureDuration * ticksPerQuarterNote / divisions);
+    const ticksToAdd = Math.min(calculatedTicks, actualTicks > 0 ? actualTicks : calculatedTicks);
+    return measureStartTick + ticksToAdd;
+  }
+  return measureStartTick + actualTicks;
+}
+function hasFermata(note) {
+  return note.notations?.some((n) => n.type === "fermata") ?? false;
+}
+function pauseArticulation(note) {
+  if (!note.notations) return null;
+  for (const n of note.notations) {
+    if (n.type === "articulation") {
+      if (n.articulation === "caesura") return "caesura";
+      if (n.articulation === "breath-mark") return "breath";
+    }
+  }
+  return null;
+}
+function tempoRampWord(text) {
+  const t = text.trim().toLowerCase().replace(/[.\s]+$/, "");
+  if (!t) return null;
+  if (/^(rit|riten|rall|allarg|slarg|cala|smorz|morend)/.test(t)) return "rit";
+  if (/^(accel|string|affret|incalz|pi[uù]\s*mosso)/.test(t)) return "accel";
+  return null;
+}
+function buildGridTimeline(score, ticksPerQuarterNote, sequence, options = {}) {
+  const rawTempo = [];
+  const measures = [];
+  const rampMarkers = [];
+  const stretches = [];
+  if (score.parts.length === 0) {
+    return { tempoEvents: [], measures, totalTicks: 0, expressions: [] };
+  }
+  const fermataHold = options.fermataHoldMultiplier ?? DEFAULT_FERMATA_HOLD;
+  const caesuraSeconds = options.caesuraSeconds ?? DEFAULT_CAESURA_SECONDS;
+  const breathSeconds = options.breathSeconds ?? DEFAULT_BREATH_SECONDS;
+  const rampSteps = Math.max(1, Math.round(options.tempoRampSteps ?? DEFAULT_RAMP_STEPS));
+  const defaultTempo = options.defaultTempo ?? 120;
+  const part = score.parts[0];
+  let divisions = 1;
+  let currentTick = 0;
+  let prevailingBpm = defaultTempo;
+  const pauseFactor = (windowTicks, bpm, pauseSeconds) => {
+    const baseSeconds = windowTicks / ticksPerQuarterNote * (60 / bpm);
+    if (baseSeconds <= 0) return 1;
+    return (baseSeconds + pauseSeconds) / baseSeconds;
+  };
+  for (const { measureIndex, repeatIteration } of sequence) {
+    const measure = part.measures[measureIndex];
+    if (!measure) continue;
+    if (measure.attributes?.divisions) {
+      divisions = measure.attributes.divisions;
+    }
+    const measureStartTick = currentTick;
+    let position = 0;
+    let chordBasePosition = 0;
+    const tickAt = (pos) => measureStartTick + Math.round(pos * ticksPerQuarterNote / divisions);
+    for (const entry of measure.entries) {
+      if (entry.type === "direction") {
+        for (const dirType of entry.directionTypes) {
+          if (dirType.kind === "metronome") {
+            const bpm = metronomeBpm(dirType.perMinute);
+            if (bpm !== null) {
+              rawTempo.push({ tick: tickAt(position), bpm });
+              prevailingBpm = bpm;
+            }
+          } else if (dirType.kind === "words") {
+            const kind = tempoRampWord(dirType.text);
+            if (kind) rampMarkers.push({ tick: tickAt(position), kind });
+          }
+        }
+        if (entry.sound?.tempo) {
+          rawTempo.push({ tick: tickAt(position), bpm: entry.sound.tempo });
+          prevailingBpm = entry.sound.tempo;
+        }
+      } else if (entry.type === "sound") {
+        if (entry.tempo) {
+          rawTempo.push({ tick: tickAt(position), bpm: entry.tempo });
+          prevailingBpm = entry.tempo;
+        }
+      } else if (entry.type === "note") {
+        const notePos = entry.chord ? chordBasePosition : position;
+        const noteStartTick = tickAt(notePos);
+        const noteEndTick = tickAt(notePos + entry.duration);
+        if (noteEndTick > noteStartTick) {
+          if (fermataHold !== 1 && hasFermata(entry)) {
+            stretches.push({
+              startTick: noteStartTick,
+              endTick: noteEndTick,
+              factor: fermataHold,
+              type: "fermata"
+            });
+          }
+          const pause = pauseArticulation(entry);
+          if (pause) {
+            const seconds = pause === "caesura" ? caesuraSeconds : breathSeconds;
+            if (seconds > 0) {
+              const window = Math.min(noteEndTick - noteStartTick, ticksPerQuarterNote);
+              stretches.push({
+                startTick: noteEndTick - window,
+                endTick: noteEndTick,
+                factor: pauseFactor(window, prevailingBpm, seconds),
+                type: pause
+              });
+            }
+          }
+        }
+        if (!entry.chord) {
+          chordBasePosition = position;
+          position += entry.duration;
+        }
+      } else if (entry.type === "backup") {
+        position -= entry.duration;
+      } else if (entry.type === "forward") {
+        position += entry.duration;
+      }
+    }
+    const endTick = measureEndTick(
+      measure,
+      part,
+      divisions,
+      measureStartTick,
+      measureMaxPosition(measure),
+      ticksPerQuarterNote
+    );
+    measures.push({
+      measureIndex,
+      repeatIteration,
+      measureNumber: measure.number,
+      startTick: measureStartTick,
+      endTick
+    });
+    currentTick = endTick;
+  }
+  const { tempoEvents, expressions } = bakeTempoMap(
+    rawTempo,
+    rampMarkers,
+    stretches,
+    defaultTempo,
+    rampSteps
+  );
+  return { tempoEvents, measures, totalTicks: currentTick, expressions };
+}
+function bakeTempoMap(rawTempo, rampMarkers, stretches, defaultTempo, rampSteps) {
+  const sortedRaw = [...rawTempo].sort((a, b) => a.tick - b.tick);
+  const startBpm = sortedRaw.length > 0 && sortedRaw[0].tick === 0 ? sortedRaw[0].bpm : defaultTempo;
+  const baseChanges = [{ tick: 0, bpm: startBpm }];
+  let lastBpm = startBpm;
+  for (const ev of sortedRaw) {
+    if (ev.tick === 0) continue;
+    if (ev.bpm === lastBpm) continue;
+    if (baseChanges[baseChanges.length - 1].tick === ev.tick) {
+      baseChanges[baseChanges.length - 1].bpm = ev.bpm;
+    } else {
+      baseChanges.push({ tick: ev.tick, bpm: ev.bpm });
+    }
+    lastBpm = ev.bpm;
+  }
+  const baseBpmAt = (tick) => {
+    let i = baseChanges.length - 1;
+    while (i > 0 && baseChanges[i].tick > tick) i--;
+    return baseChanges[i].bpm;
+  };
+  const rampExpressions = [];
+  const rampPoints = [];
+  for (const marker of rampMarkers) {
+    const from = baseBpmAt(marker.tick);
+    const next = baseChanges.find((c) => c.tick > marker.tick && c.bpm !== from);
+    if (!next) continue;
+    const span = next.tick - marker.tick;
+    if (span <= 0) continue;
+    for (let k = 1; k < rampSteps; k++) {
+      const tick = Math.round(marker.tick + span * k / rampSteps);
+      if (tick <= marker.tick || tick >= next.tick) continue;
+      const bpm = from + (next.bpm - from) * k / rampSteps;
+      rampPoints.push({ tick, bpm });
+    }
+    rampExpressions.push({ type: marker.kind, startTick: marker.tick, endTick: next.tick });
+  }
+  const baseTicks = new Set(baseChanges.map((c) => c.tick));
+  const stepList = [...baseChanges];
+  for (const p of rampPoints) {
+    if (!baseTicks.has(p.tick)) stepList.push(p);
+  }
+  stepList.sort((a, b) => a.tick - b.tick);
+  const stepBpmAt = (tick) => {
+    let i = stepList.length - 1;
+    while (i > 0 && stepList[i].tick > tick) i--;
+    return stepList[i].bpm;
+  };
+  const boundaries = new Set(stepList.map((s) => s.tick));
+  for (const s of stretches) {
+    boundaries.add(s.startTick);
+    boundaries.add(s.endTick);
+  }
+  const sortedBoundaries = [...boundaries].sort((a, b) => a - b);
+  const tempoEvents = [];
+  let emittedBpm = null;
+  for (const tick of sortedBoundaries) {
+    let bpm = stepBpmAt(tick);
+    for (const s of stretches) {
+      if (tick >= s.startTick && tick < s.endTick) bpm /= s.factor;
+    }
+    if (emittedBpm === null || bpm !== emittedBpm) {
+      tempoEvents.push({ tick, bpm });
+      emittedBpm = bpm;
+    }
+  }
+  const expressions = [
+    ...stretches.map((s) => ({ type: s.type, startTick: s.startTick, endTick: s.endTick })),
+    ...rampExpressions
+  ].sort((a, b) => a.startTick - b.startTick || a.endTick - b.endTick);
+  return { tempoEvents, expressions };
+}
+function bpmToUsPerQuarter(bpm) {
+  return Math.round(6e7 / bpm);
+}
+function makeTickToSec(tempoEvents, defaultTempo, ticksPerQuarterNote) {
+  const sorted = [...tempoEvents].sort((a, b) => a.tick - b.tick);
+  const startBpm = sorted.length > 0 && sorted[0].tick === 0 ? sorted[0].bpm : defaultTempo;
+  const changes = [
+    { tick: 0, usPerQuarter: bpmToUsPerQuarter(startBpm) }
+  ];
+  let lastBpm = startBpm;
+  for (const ev of sorted) {
+    if (ev.tick === 0) continue;
+    if (ev.bpm === lastBpm) continue;
+    changes.push({ tick: ev.tick, usPerQuarter: bpmToUsPerQuarter(ev.bpm) });
+    lastBpm = ev.bpm;
+  }
+  const secPerTick = (usPerQuarter) => usPerQuarter / 1e6 / ticksPerQuarterNote;
+  const cumSec = [0];
+  for (let i = 1; i < changes.length; i++) {
+    const dTick = changes[i].tick - changes[i - 1].tick;
+    cumSec[i] = cumSec[i - 1] + dTick * secPerTick(changes[i - 1].usPerQuarter);
+  }
+  return (tick) => {
+    let i = changes.length - 1;
+    while (i > 0 && changes[i].tick > tick) i--;
+    return cumSec[i] + (tick - changes[i].tick) * secPerTick(changes[i].usPerQuarter);
+  };
+}
+function buildTimingSidecar(grid, defaultTempo, ticksPerQuarterNote) {
+  const tickToSec = makeTickToSec(grid.tempoEvents, defaultTempo, ticksPerQuarterNote);
+  const breakpoints = [];
+  const measureStartTicks = new Set(grid.measures.map((m) => m.startTick));
+  for (const m of grid.measures) {
+    breakpoints.push({
+      midiSec: tickToSec(m.startTick),
+      quarterPos: m.startTick / ticksPerQuarterNote,
+      measureNumber: m.measureNumber,
+      beatInMeasure: 0,
+      repeatIteration: m.repeatIteration
+    });
+  }
+  for (const ev of grid.tempoEvents) {
+    if (measureStartTicks.has(ev.tick)) continue;
+    const m = grid.measures.find((mm) => ev.tick >= mm.startTick && ev.tick < mm.endTick);
+    if (!m) continue;
+    breakpoints.push({
+      midiSec: tickToSec(ev.tick),
+      quarterPos: ev.tick / ticksPerQuarterNote,
+      measureNumber: m.measureNumber,
+      beatInMeasure: (ev.tick - m.startTick) / ticksPerQuarterNote,
+      repeatIteration: m.repeatIteration
+    });
+  }
+  const last = grid.measures[grid.measures.length - 1];
+  breakpoints.push({
+    midiSec: tickToSec(grid.totalTicks),
+    quarterPos: grid.totalTicks / ticksPerQuarterNote,
+    measureNumber: last ? last.measureNumber : "0",
+    beatInMeasure: last ? (grid.totalTicks - last.startTick) / ticksPerQuarterNote : 0,
+    repeatIteration: last ? last.repeatIteration : 0
+  });
+  breakpoints.sort((a, b) => a.midiSec - b.midiSec || a.quarterPos - b.quarterPos);
+  const sidecar = {
+    version: "1",
+    durationSec: tickToSec(grid.totalTicks),
+    ticksPerQuarterNote,
+    breakpoints
+  };
+  if (grid.expressions.length > 0) {
+    sidecar.expressions = grid.expressions.map((e) => ({
+      type: e.type,
+      fromMidiSec: tickToSec(e.startTick),
+      toMidiSec: tickToSec(e.endTick)
+    })).sort((a, b) => a.fromMidiSec - b.fromMidiSec || a.toMidiSec - b.toMidiSec);
+  }
+  return sidecar;
+}
+function generatePlaybackTimeline(score, options = {}) {
+  const ticksPerQuarterNote = options.ticksPerQuarterNote ?? 480;
+  const defaultTempo = options.defaultTempo ?? 120;
+  const sequence = generatePlaybackSequence(score);
+  const grid = buildGridTimeline(score, ticksPerQuarterNote, sequence, {
+    defaultTempo,
+    fermataHoldMultiplier: options.fermataHoldMultiplier,
+    caesuraSeconds: options.caesuraSeconds,
+    breathSeconds: options.breathSeconds,
+    tempoRampSteps: options.tempoRampSteps
+  });
+  return buildTimingSidecar(grid, defaultTempo, ticksPerQuarterNote);
+}
+
 // src/query/index.ts
 function getNotesForVoice(measure, filter) {
   return measure.entries.filter((entry) => {
@@ -2062,6 +2419,11 @@ export {
   extractPlaybackControls,
   generatePlaybackSequence,
   hasPlaybackControls,
+  measureEndTick,
+  buildGridTimeline,
+  bpmToUsPerQuarter,
+  buildTimingSidecar,
+  generatePlaybackTimeline,
   STEPS,
   STEP_SEMITONES,
   pitchToSemitone,

package/dist/index.d.mts

@@ -2,7 +2,8 @@ import { S as Score, P as Pitch, M as Measure, D as DirectionType, a as Directio
 export { A as Accidental, j as AccidentalInfo, O as AdjacentNotes, a4 as AssembledLyrics, B as BackupEntry, p as Barline, a5 as BarlineWithContext, a0 as BeamGroup, k as BeamInfo, s as Chord, C as Clef, aa as ClefChangeInfo, w as Credit, v as Defaults, Q as DirectionKind, z as DirectionWithContext, R as DynamicWithContext, m as DynamicsValue, a7 as EndingInfo, E as EntryWithContext, F as ForwardEntry, a2 as HarmonyWithContext, a8 as KeyChangeInfo, K as KeySignature, L as Lyric, a3 as LyricWithContext, g as MeasureAttributes, h as MeasureEntry, l as Notation, a1 as NotationType, t as NoteIteratorItem, i as NoteType, y as NoteWithContext, r as NoteWithPosition, Y as OctaveShiftWithContext, f as Part, e as PartGroup, W as PedalWithContext, H as PositionQueryOptions, u as Print, a6 as RepeatInfo, d as ScoreMetadata, _ as SlurSpan, q as StaffGroup, G as StaffRange, ab as StructuralChanges, U as TempoWithContext, T as TieInfo, Z as TiedNoteGroup, a9 as TimeChangeInfo, n as TimeSignature, o as Transpose, $ as TupletGroup, I as VerticalSlice, V as VoiceGroup, J as VoiceLine, x as VoiceToStaffMap, X as WedgeWithContext } from './types-CkeI8vw6.mjs';
 import { V as ValidateOptions, a as ValidationResult } from './index-8MkN7sbm.mjs';
 export { ba as AddArticulationOptions, bj as AddBeamOptions, c8 as AddBowingOptions, ch as AddBreathMarkOptions, ck as AddCaesuraOptions, aW as AddChordOptions, c2 as AddChordSymbolOptions, bS as AddCodaOptions, bc as AddDynamicsOptions, bM as AddEndingOptions, bz as AddFermataOptions, c5 as AddFingeringOptions, bU as AddGraceNoteOptions, b$ as AddHarmonyOptions, bX as AddLyricOptions, bT as AddNavigationOptions, cd as AddOctaveShiftOptions, bB as AddOrnamentOptions, b2 as AddPartOptions, bD as AddPedalOptions, bH as AddRehearsalMarkOptions, bI as AddRepeatBarlineOptions, bK as AddRepeatOptions, bR as AddSegnoOptions, b8 as AddSlurOptions, ca as AddStringNumberOptions, bu as AddTempoOptions, bF as AddTextDirectionOptions, bG as AddTextOptions, b6 as AddTieOptions, b1 as AddVoiceOptions, bx as AddWedgeOptions, bl as AutoBeamOptions, bQ as BarStyle, c7 as BowingType, cg as BreathMarkValue, cj as CaesuraValue, bO as ChangeBarlineOptions, bg as ChangeClefOptions, aX as ChangeNoteDurationOptions, bW as ConvertToGraceOptions, br as CopyNotesMultiMeasureOptions, bo as CopyNotesOptions, bh as CreateTupletOptions, bq as CutNotesOptions, b3 as DuplicatePartOptions, b_ as HarmonyKind, bf as InsertClefChangeOptions, aU as InsertNoteOptions, cM as LocalValidateOptions, b0 as LowerAccidentalOptions, cL as MeasureValidationContext, be as ModifyDynamicsOptions, bw as ModifyTempoOptions, b5 as MoveNoteToStaffOptions, bs as MultiMeasureSelection, bn as NoteSelection, cc as OctaveShiftType, aT as OperationErrorCode, aS as OperationResult, bt as PasteNotesMultiMeasureOptions, bp as PasteNotesOptions, a$ as RaiseAccidentalOptions, bb as RemoveArticulationOptions, bk as RemoveBeamOptions, c9 as RemoveBowingOptions, ci as RemoveBreathMarkOptions, cl as RemoveCaesuraOptions, c3 as RemoveChordSymbolOptions, bd as RemoveDynamicsOptions, bN as RemoveEndingOptions, bA as RemoveFermataOptions, c6 as RemoveFingeringOptions, bV as RemoveGraceNoteOptions, c0 as RemoveHarmonyOptions, bY as RemoveLyricOptions, aV as RemoveNoteOptions, cf as RemoveOctaveShiftOptions, bC as RemoveOrnamentOptions, bE as RemovePedalOptions, bJ as RemoveRepeatBarlineOptions, bL as RemoveRepeatOptions, b9 as RemoveSlurOptions, cb as RemoveStringNumberOptions, bv as RemoveTempoOptions, b7 as RemoveTieOptions, bi as RemoveTupletOptions, by as RemoveWedgeOptions, bP as SetBarlineOptions, bm as SetBeamingOptions, aZ as SetNotePitchBySemitoneOptions, aY as SetNotePitchOptions, b4 as SetStavesOptions, a_ as ShiftNotePitchOptions, ce as StopOctaveShiftOptions, c4 as UpdateChordSymbolOptions, c1 as UpdateHarmonyOptions, bZ as UpdateLyricOptions, cH as ValidationError, cJ as ValidationErrorCode, cD as ValidationException, cK as ValidationLevel, cI as ValidationLocation, K as addArticulation, T as addBeam, aH as addBowing, aO as addBreathMark, aQ as addCaesura, b as addChord, j as addChordNote, p as addChordNoteChecked, aC as addChordSymbol, ao as addCoda, ap as addDaCapo, aq as addDalSegno, M as addDynamics, aj as addEnding, a6 as addFermata, ar as addFine, aF as addFingering, at as addGraceNote, az as addHarmony, aw as addLyric, g as addNote, n as addNoteChecked, aL as addOctaveShift, a8 as addOrnament, x as addPart, aa as addPedal, ae as addRehearsalMark, ah as addRepeat, af as addRepeatBarline, an as addSegno, I as addSlur, aJ as addStringNumber, a1 as addTempo, ad as addText, ac as addTextDirection, G as addTie, as as addToCoda, w as addVoice, a4 as addWedge, cG as assertMeasureValid, co as assertValid, W as autoBeam, al as changeBarline, Q as changeClef, C as changeKey, e as changeNoteDuration, D as changeTime, av as convertToGrace, Y as copyNotes, $ as copyNotesMultiMeasure, R as createTuplet, _ as cutNotes, F as deleteMeasure, h as deleteNote, o as deleteNoteChecked, z as duplicatePart, cC as formatLocation, cF as getMeasureContext, P as insertClefChange, E as insertMeasure, i as insertNote, cn as isValid, l as lowerAccidental, O as modifyDynamics, k as modifyNoteDuration, u as modifyNoteDurationChecked, m as modifyNotePitch, q as modifyNotePitchChecked, a3 as modifyTempo, B as moveNoteToStaff, Z as pasteNotes, a0 as pasteNotesMultiMeasure, f as raiseAccidental, L as removeArticulation, U as removeBeam, aI as removeBowing, aP as removeBreathMark, aR as removeCaesura, aD as removeChordSymbol, N as removeDynamics, ak as removeEnding, a7 as removeFermata, aG as removeFingering, au as removeGraceNote, aA as removeHarmony, ax as removeLyric, r as removeNote, aN as removeOctaveShift, a9 as removeOrnament, y as removePart, ab as removePedal, ai as removeRepeat, ag as removeRepeatBarline, J as removeSlur, aK as removeStringNumber, a2 as removeTempo, H as removeTie, S as removeTuplet, a5 as removeWedge, am as setBarline, X as setBeaming, s as setNotePitch, c as setNotePitchBySemitone, A as setStaves, d as shiftNotePitch, aM as stopOctaveShift, t as transpose, v as transposeChecked, aE as updateChordSymbol, aB as updateHarmony, ay as updateLyric, cm as validate, cr as validateBackupForward, ct as validateBeams, cp as validateDivisions, cq as validateMeasureDuration, cE as validateMeasureLocal, cw as validatePartReferences, cx as validatePartStructure, cu as validateSlurs, cB as validateSlursAcrossMeasures, cy as validateStaffStructure, cs as validateTies, cA as validateTiesAcrossMeasures, cv as validateTuplets, cz as validateVoiceStaff } from './index-8MkN7sbm.mjs';
-export { FindNotesFilter, NormalizedPositionOptions, PitchRange, PlaybackControls, PlaybackMeasure, RoundtripMetrics, VoiceFilter, buildVoiceToStaffMap, buildVoiceToStaffMapForPart, countNotes, extractPlaybackControls, findBarlines, findDirectionsByType, findNotes, findNotesWithNotation, generatePlaybackSequence, getAbsolutePosition, getAdjacentNotes, getAllNotes, getAttributesAtMeasure, getBeamGroups, getChordProgression, getChords, getClefChanges, getClefForStaff, getDirections, getDirectionsAtPosition, getDivisions, getDuration, getDynamics, getEffectiveStaff, getEndings, getEntriesAtPosition, getEntriesForStaff, getEntriesInRange, getHarmonies, getHarmonyAtPosition, getKeyChanges, getLyricText, getLyrics, getMeasure, getMeasureByIndex, getMeasureCount, getNextNote, getNormalizedDuration, getNormalizedPosition, getNotesAtPosition, getNotesForStaff, getNotesForVoice, getNotesInRange, getOctaveShifts, getPartById, getPartByIndex, getPartCount, getPartIds, getPartIndex, getPedalMarkings, getPrevNote, getRepeatStructure, getSlurSpans, getStaffRange, getStaveCount, getStaves, getStructuralChanges, getTempoMarkings, getTiedNoteGroups, getTimeChanges, getTupletGroups, getVerseCount, getVerticalSlice, getVoiceLine, getVoiceLineInRange, getVoices, getVoicesForStaff, getWedges, groupByStaff, groupByVoice, hasMultipleStaves, hasNotes, hasPlaybackControls, inferStaff, isRestMeasure, iterateEntries, iterateNotes, measureRoundtrip, scoresEqual, withAbsolutePositions } from './query/index.mjs';
+import { ExpressionOptions, TimingSidecar } from './query/index.mjs';
+export { ExpressionHint, ExpressionKind, FindNotesFilter, NormalizedPositionOptions, PitchRange, PlaybackControls, PlaybackMeasure, RoundtripMetrics, TimingBreakpoint, TimingMapOptions, VoiceFilter, buildVoiceToStaffMap, buildVoiceToStaffMapForPart, countNotes, extractPlaybackControls, findBarlines, findDirectionsByType, findNotes, findNotesWithNotation, generatePlaybackSequence, generatePlaybackTimeline, getAbsolutePosition, getAdjacentNotes, getAllNotes, getAttributesAtMeasure, getBeamGroups, getChordProgression, getChords, getClefChanges, getClefForStaff, getDirections, getDirectionsAtPosition, getDivisions, getDuration, getDynamics, getEffectiveStaff, getEndings, getEntriesAtPosition, getEntriesForStaff, getEntriesInRange, getHarmonies, getHarmonyAtPosition, getKeyChanges, getLyricText, getLyrics, getMeasure, getMeasureByIndex, getMeasureCount, getNextNote, getNormalizedDuration, getNormalizedPosition, getNotesAtPosition, getNotesForStaff, getNotesForVoice, getNotesInRange, getOctaveShifts, getPartById, getPartByIndex, getPartCount, getPartIds, getPartIndex, getPedalMarkings, getPrevNote, getRepeatStructure, getSlurSpans, getStaffRange, getStaveCount, getStaves, getStructuralChanges, getTempoMarkings, getTiedNoteGroups, getTimeChanges, getTupletGroups, getVerseCount, getVerticalSlice, getVoiceLine, getVoiceLineInRange, getVoices, getVoicesForStaff, getWedges, groupByStaff, groupByVoice, hasMultipleStaves, hasNotes, hasPlaybackControls, inferStaff, isRestMeasure, iterateEntries, iterateNotes, measureRoundtrip, scoresEqual, withAbsolutePositions } from './query/index.mjs';
 
 declare function parse(input: string | Uint8Array): Score;
 
@@ -75,8 +76,11 @@ declare function serializeCompressed(score: Score, options?: SerializeOptions):
 
 /**
  * MIDI export options
+ *
+ * Extends {@link ExpressionOptions} so fermata holds and rit./accel. ramps land
+ * in the exported tempo map (and the timing sidecar) identically.
  */
-interface MidiExportOptions {
+interface MidiExportOptions extends ExpressionOptions {
     /** Ticks per quarter note (default: 480) */
     ticksPerQuarterNote?: number;
     /** Default tempo in BPM (default: 120) */
@@ -84,6 +88,22 @@ interface MidiExportOptions {
     /** Default velocity for notes when no dynamics are present (default: 80) */
     defaultVelocity?: number;
 }
+/**
+ * A single point on the timing sidecar: a correspondence between a time in the
+ * generated MIDI and a conceptual musical position (measure + beat).
+ *
+ * Breakpoints are emitted at every played-measure start and every tempo change
+ * (plus a terminal point). Between two consecutive breakpoints the relationship
+ * `midiSec ↔ quarterPos` is linear (tempo is piecewise-constant), so a consumer
+ * can interpolate any intermediate time exactly.
+ */
+/** Result of {@link exportMidiWithTimingMap}. */
+interface MidiWithTimingMap {
+    /** The Standard MIDI File data. */
+    midi: Uint8Array;
+    /** The MIDI-time ↔ musical-position sidecar. */
+    sidecar: TimingSidecar;
+}
 /**
  * Export a Score to Standard MIDI File format (SMF Type 1)
  * @param score - The Score to export
@@ -91,6 +111,18 @@ interface MidiExportOptions {
  * @returns The MIDI file data as Uint8Array
  */
 declare function exportMidi(score: Score, options?: MidiExportOptions): Uint8Array;
+/**
+ * Export a Score to MIDI together with a timing sidecar that maps the generated
+ * MIDI timeline to conceptual musical positions (measure + beat).
+ *
+ * The MIDI bytes are byte-for-byte identical to {@link exportMidi}; the sidecar
+ * is derived from the same internal time computation so the two can never drift.
+ *
+ * @param score - The Score to export
+ * @param options - Export options (must match those used for any aligned audio)
+ * @returns The MIDI data and its timing sidecar
+ */
+declare function exportMidiWithTimingMap(score: Score, options?: MidiExportOptions): MidiWithTimingMap;
 
 /**
  * ABC Notation Serializer
@@ -346,4 +378,4 @@ declare function getPartNameMap(score: Score): Record<string, string | undefined
  */
 declare function generateId(): string;
 
-export { type AbcSerializeOptions, DirectionEntry, DirectionType, type DirectionTypeOfKind, Measure, type MidiExportOptions, NoteEntry, PartInfo, PartListEntry, Pitch, STEPS, STEP_SEMITONES, Score, type SerializeOptions, ValidateOptions, ValidationResult, decodeBuffer, exportMidi, generateId, getAllPartInfos, getDirectionOfKind, getDirectionsOfKind, getMeasureEndPosition, getPartAbbreviation, getPartInfo, getPartName, getPartNameMap, getSoundDamperPedal, getSoundDynamics, getSoundSoftPedal, getSoundSostenutoPedal, getSoundTempo, hasBeam, hasDirectionOfKind, hasLyrics, hasNotations, hasTie, hasTieStart, hasTieStop, hasTuplet, isChordNote, isCompressed, isCueNote, isGraceNote, isPartInfo, isPitchedNote, isRest, isUnpitchedNote, parse, parseAbc, parseAuto, parseCompressed, parseFile, pitchToSemitone, serialize, serializeAbc, serializeCompressed, serializeToFile };
+export { type AbcSerializeOptions, DirectionEntry, DirectionType, type DirectionTypeOfKind, ExpressionOptions, Measure, type MidiExportOptions, type MidiWithTimingMap, NoteEntry, PartInfo, PartListEntry, Pitch, STEPS, STEP_SEMITONES, Score, type SerializeOptions, TimingSidecar, ValidateOptions, ValidationResult, decodeBuffer, exportMidi, exportMidiWithTimingMap, generateId, getAllPartInfos, getDirectionOfKind, getDirectionsOfKind, getMeasureEndPosition, getPartAbbreviation, getPartInfo, getPartName, getPartNameMap, getSoundDamperPedal, getSoundDynamics, getSoundSoftPedal, getSoundSostenutoPedal, getSoundTempo, hasBeam, hasDirectionOfKind, hasLyrics, hasNotations, hasTie, hasTieStart, hasTieStop, hasTuplet, isChordNote, isCompressed, isCueNote, isGraceNote, isPartInfo, isPitchedNote, isRest, isUnpitchedNote, parse, parseAbc, parseAuto, parseCompressed, parseFile, pitchToSemitone, serialize, serializeAbc, serializeCompressed, serializeToFile };