@real-music-packages/web-core 0.32.0 → 0.34.0

package/dist/audio.js

@@ -1,6 +1,10 @@
 import {
   KEYS_PREFER_FLATS
 } from "./chunk-BYZBLH25.js";
+import {
+  getMidiNote,
+  midiToNoteName
+} from "./chunk-GORQ5YMR.js";
 import {
   SALAMANDER_CDN_BASE,
   SALAMANDER_URLS_8,
@@ -8,10 +12,6 @@ import {
   createSalamanderSampler,
   generateReverb
 } from "./chunk-JVGAABTK.js";
-import {
-  getMidiNote,
-  midiToNoteName
-} from "./chunk-GORQ5YMR.js";
 
 // src/engine.ts
 var browser = typeof window !== "undefined";

package/dist/index.js

@@ -1,8 +1,3 @@
-import {
-  KEYS_PREFER_FLATS,
-  useFlatsForKeyFifths,
-  useFlatsForKeyName
-} from "./chunk-BYZBLH25.js";
 import {
   INTERVALS,
   MAX_FRET,
@@ -17,6 +12,11 @@ import {
   midiToPositions,
   noteToFret
 } from "./chunk-ILIXNGPE.js";
+import {
+  KEYS_PREFER_FLATS,
+  useFlatsForKeyFifths,
+  useFlatsForKeyName
+} from "./chunk-BYZBLH25.js";
 import {
   ALL_KEYS,
   MAJOR_SCALE_INTERVALS,

package/dist/playback.d.ts

@@ -0,0 +1,61 @@
+import { S as Score } from './waveform-DdSMAbYQ.js';
+import './video.js';
+
+/** createScorePlayer — play a `Score` (from `scoreFromMusicXML`) through a sink.
+ *
+ * The standard Web Audio lookahead pattern: a coarse `setTimeout` tick fires
+ * every ~100ms and schedules every note whose onset falls inside the next
+ * ~300ms at its *exact* time on the sink's audio clock. Timer jitter moves the
+ * tick, never the note — the audio clock is the only clock the ear hears.
+ *
+ * Deliberately Tone-free, like the rest of this package's audio layer: the sink
+ * owns the instrument (a Tone.Sampler, an oscillator, a test fake) and this
+ * module owns nothing but time. Position is score-time in ms; wall time maps to
+ * it through `rate`, and every rate change or seek re-anchors the mapping so
+ * position is continuous.
+ *
+ * Seeking is onset-faithful, not state-faithful: a note whose onset is behind
+ * the new position does not sound, even if it would still be ringing there.
+ * Mid-note pickup needs per-note release tracking for a payoff nobody asked
+ * for yet; the seam is `scheduleWindow`.
+ */
+
+interface PlaybackSink {
+    /** Sound `midi` for `durSec` starting at `atAudioTime` on the sink's clock. */
+    noteAt(midi: number, durSec: number, atAudioTime: number): void;
+    /** The sink's audio clock, in seconds (AudioContext.currentTime). */
+    now(): number;
+    /** Silence everything — pause, seek, teardown. */
+    releaseAll(): void;
+}
+interface ScorePlayerOpts {
+    /** Playback rate; 1 plays the score's own tempo. */
+    rate?: number;
+    /** Scheduler granularity — how often the tick fires. */
+    tickMs?: number;
+    /** How far ahead each tick schedules. Must exceed tickMs comfortably. */
+    lookaheadMs?: number;
+}
+interface ScorePlayer {
+    play(): void;
+    pause(): void;
+    /** Jump to a position in score-time. Keeps playing/paused state. */
+    seekMs(ms: number): void;
+    setRate(rate: number): void;
+    loop: boolean;
+    /** ~Every tick while playing: the current position in score-ms. */
+    onTick?: (positionMs: number) => void;
+    /** The piece ran out (never fires when looping). */
+    onEnd?: () => void;
+    readonly positionMs: number;
+    readonly playing: boolean;
+    readonly rate: number;
+}
+declare function createScorePlayer(score: Score, sink: PlaybackSink, opts?: ScorePlayerOpts): ScorePlayer;
+/** Per printed bar: where it starts in score-ms. For bar-wise scrub and cursor. */
+declare function measureStartsMs(score: Score): Array<{
+    measure: number;
+    atMs: number;
+}>;
+
+export { type PlaybackSink, type ScorePlayer, type ScorePlayerOpts, createScorePlayer, measureStartsMs };

package/dist/playback.js

@@ -0,0 +1,128 @@
+// src/playback.ts
+var DEFAULT_TICK_MS = 100;
+var DEFAULT_LOOKAHEAD_MS = 300;
+function createScorePlayer(score, sink, opts = {}) {
+  const tickMs = opts.tickMs ?? DEFAULT_TICK_MS;
+  const lookaheadMs = opts.lookaheadMs ?? DEFAULT_LOOKAHEAD_MS;
+  const notes = [...score.notes].sort((a, b) => a.onsetMs - b.onsetMs);
+  let rate = opts.rate ?? 1;
+  let playing = false;
+  let loop = false;
+  let anchorScoreMs = 0;
+  let anchorAudioSec = 0;
+  let restingMs = 0;
+  let nextIndex = 0;
+  let timer = null;
+  const positionNow = () => playing ? anchorScoreMs + (sink.now() - anchorAudioSec) * 1e3 * rate : restingMs;
+  function indexAt(scoreMs) {
+    let lo = 0, hi = notes.length;
+    while (lo < hi) {
+      const mid = lo + hi >> 1;
+      if (notes[mid].onsetMs < scoreMs) lo = mid + 1;
+      else hi = mid;
+    }
+    return lo;
+  }
+  function scheduleWindow() {
+    const pos = positionNow();
+    const horizon = pos + lookaheadMs * rate;
+    while (nextIndex < notes.length && notes[nextIndex].onsetMs < horizon) {
+      const n = notes[nextIndex++];
+      if (n.onsetMs < pos - 1) continue;
+      const at = anchorAudioSec + (n.onsetMs - anchorScoreMs) / 1e3 / rate;
+      sink.noteAt(n.pitchMidi, n.durMs / 1e3 / rate, at);
+    }
+  }
+  function tick() {
+    if (!playing) return;
+    scheduleWindow();
+    const pos = positionNow();
+    player.onTick?.(Math.min(pos, score.durationMs));
+    if (nextIndex >= notes.length && pos >= score.durationMs) {
+      if (loop) {
+        anchorScoreMs = 0;
+        anchorAudioSec = sink.now();
+        nextIndex = 0;
+        scheduleWindow();
+      } else {
+        stopClock(score.durationMs);
+        player.onEnd?.();
+        return;
+      }
+    }
+    timer = setTimeout(tick, tickMs);
+  }
+  function stopClock(atMs) {
+    restingMs = atMs;
+    playing = false;
+    if (timer) {
+      clearTimeout(timer);
+      timer = null;
+    }
+  }
+  const player = {
+    play() {
+      if (playing) return;
+      if (restingMs >= score.durationMs) restingMs = 0;
+      playing = true;
+      anchorScoreMs = restingMs;
+      anchorAudioSec = sink.now();
+      nextIndex = indexAt(restingMs);
+      tick();
+    },
+    pause() {
+      if (!playing) return;
+      stopClock(positionNow());
+      sink.releaseAll();
+    },
+    seekMs(ms) {
+      const target = Math.max(0, Math.min(score.durationMs, ms));
+      if (playing) {
+        sink.releaseAll();
+        anchorScoreMs = target;
+        anchorAudioSec = sink.now();
+        nextIndex = indexAt(target);
+      } else {
+        restingMs = target;
+        nextIndex = indexAt(target);
+      }
+    },
+    setRate(next) {
+      if (next <= 0 || next === rate) return;
+      if (playing) {
+        anchorScoreMs = positionNow();
+        anchorAudioSec = sink.now();
+      }
+      rate = next;
+    },
+    get loop() {
+      return loop;
+    },
+    set loop(v) {
+      loop = v;
+    },
+    get positionMs() {
+      return Math.min(positionNow(), score.durationMs);
+    },
+    get playing() {
+      return playing;
+    },
+    get rate() {
+      return rate;
+    }
+  };
+  return player;
+}
+function measureStartsMs(score) {
+  const starts = /* @__PURE__ */ new Map();
+  for (const n of score.notes) {
+    const seen = starts.get(n.measure);
+    if (seen === void 0 || n.onsetMs < seen) starts.set(n.measure, n.onsetMs);
+  }
+  return [...starts.entries()].map(([measure, atMs]) => ({ measure, atMs })).sort((a, b) => a.atMs - b.atMs);
+}
+export {
+  createScorePlayer,
+  measureStartsMs
+};
+//# sourceMappingURL=playback.js.map

package/dist/playback.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/playback.ts"],"sourcesContent":["/** createScorePlayer — play a `Score` (from `scoreFromMusicXML`) through a sink.\n *\n * The standard Web Audio lookahead pattern: a coarse `setTimeout` tick fires\n * every ~100ms and schedules every note whose onset falls inside the next\n * ~300ms at its *exact* time on the sink's audio clock. Timer jitter moves the\n * tick, never the note — the audio clock is the only clock the ear hears.\n *\n * Deliberately Tone-free, like the rest of this package's audio layer: the sink\n * owns the instrument (a Tone.Sampler, an oscillator, a test fake) and this\n * module owns nothing but time. Position is score-time in ms; wall time maps to\n * it through `rate`, and every rate change or seek re-anchors the mapping so\n * position is continuous.\n *\n * Seeking is onset-faithful, not state-faithful: a note whose onset is behind\n * the new position does not sound, even if it would still be ringing there.\n * Mid-note pickup needs per-note release tracking for a payoff nobody asked\n * for yet; the seam is `scheduleWindow`.\n */\n\nimport type { Score } from './scene/index';\n\nexport interface PlaybackSink {\n  /** Sound `midi` for `durSec` starting at `atAudioTime` on the sink's clock. */\n  noteAt(midi: number, durSec: number, atAudioTime: number): void;\n  /** The sink's audio clock, in seconds (AudioContext.currentTime). */\n  now(): number;\n  /** Silence everything — pause, seek, teardown. */\n  releaseAll(): void;\n}\n\nexport interface ScorePlayerOpts {\n  /** Playback rate; 1 plays the score's own tempo. */\n  rate?: number;\n  /** Scheduler granularity — how often the tick fires. */\n  tickMs?: number;\n  /** How far ahead each tick schedules. Must exceed tickMs comfortably. */\n  lookaheadMs?: number;\n}\n\nexport interface ScorePlayer {\n  play(): void;\n  pause(): void;\n  /** Jump to a position in score-time. Keeps playing/paused state. */\n  seekMs(ms: number): void;\n  setRate(rate: number): void;\n  loop: boolean;\n  /** ~Every tick while playing: the current position in score-ms. */\n  onTick?: (positionMs: number) => void;\n  /** The piece ran out (never fires when looping). */\n  onEnd?: () => void;\n  readonly positionMs: number;\n  readonly playing: boolean;\n  readonly rate: number;\n}\n\nconst DEFAULT_TICK_MS = 100;\nconst DEFAULT_LOOKAHEAD_MS = 300;\n\nexport function createScorePlayer(\n  score: Score,\n  sink: PlaybackSink,\n  opts: ScorePlayerOpts = {},\n): ScorePlayer {\n  const tickMs = opts.tickMs ?? DEFAULT_TICK_MS;\n  const lookaheadMs = opts.lookaheadMs ?? DEFAULT_LOOKAHEAD_MS;\n  // Sorted by onset once; the scheduler walks `nextIndex` forward and never\n  // rescans, so a tick is O(notes due), not O(all notes).\n  const notes = [...score.notes].sort((a, b) => a.onsetMs - b.onsetMs);\n\n  let rate = opts.rate ?? 1;\n  let playing = false;\n  let loop = false;\n  // The wall↔score mapping: score-ms = anchorScoreMs + (now - anchorAudioSec) * 1000 * rate.\n  let anchorScoreMs = 0;\n  let anchorAudioSec = 0;\n  // Where the playhead rests while paused.\n  let restingMs = 0;\n  let nextIndex = 0;\n  let timer: ReturnType<typeof setTimeout> | null = null;\n\n  const positionNow = (): number =>\n    playing ? anchorScoreMs + (sink.now() - anchorAudioSec) * 1000 * rate : restingMs;\n\n  function indexAt(scoreMs: number): number {\n    let lo = 0, hi = notes.length;\n    while (lo < hi) {\n      const mid = (lo + hi) >> 1;\n      if (notes[mid].onsetMs < scoreMs) lo = mid + 1;\n      else hi = mid;\n    }\n    return lo;\n  }\n\n  /** Schedule everything with an onset inside [position, position + lookahead). */\n  function scheduleWindow() {\n    const pos = positionNow();\n    const horizon = pos + lookaheadMs * rate;\n    while (nextIndex < notes.length && notes[nextIndex].onsetMs < horizon) {\n      const n = notes[nextIndex++];\n      if (n.onsetMs < pos - 1) continue; // behind the playhead (post-seek edge)\n      const at = anchorAudioSec + (n.onsetMs - anchorScoreMs) / 1000 / rate;\n      sink.noteAt(n.pitchMidi, n.durMs / 1000 / rate, at);\n    }\n  }\n\n  function tick() {\n    if (!playing) return;\n    scheduleWindow();\n    const pos = positionNow();\n    player.onTick?.(Math.min(pos, score.durationMs));\n\n    if (nextIndex >= notes.length && pos >= score.durationMs) {\n      if (loop) {\n        anchorScoreMs = 0;\n        anchorAudioSec = sink.now();\n        nextIndex = 0;\n        scheduleWindow();\n      } else {\n        stopClock(score.durationMs);\n        player.onEnd?.();\n        return;\n      }\n    }\n    timer = setTimeout(tick, tickMs);\n  }\n\n  function stopClock(atMs: number) {\n    restingMs = atMs;\n    playing = false;\n    if (timer) { clearTimeout(timer); timer = null; }\n  }\n\n  const player: ScorePlayer = {\n    play() {\n      if (playing) return;\n      if (restingMs >= score.durationMs) restingMs = 0; // play again from the top\n      playing = true;\n      anchorScoreMs = restingMs;\n      anchorAudioSec = sink.now();\n      nextIndex = indexAt(restingMs);\n      tick();\n    },\n\n    pause() {\n      if (!playing) return;\n      stopClock(positionNow());\n      sink.releaseAll();\n    },\n\n    seekMs(ms: number) {\n      const target = Math.max(0, Math.min(score.durationMs, ms));\n      if (playing) {\n        sink.releaseAll();\n        anchorScoreMs = target;\n        anchorAudioSec = sink.now();\n        nextIndex = indexAt(target);\n      } else {\n        restingMs = target;\n        nextIndex = indexAt(target);\n      }\n    },\n\n    setRate(next: number) {\n      if (next <= 0 || next === rate) return;\n      // Re-anchor at the current position so the playhead does not jump.\n      if (playing) {\n        anchorScoreMs = positionNow();\n        anchorAudioSec = sink.now();\n      }\n      rate = next;\n    },\n\n    get loop() { return loop; },\n    set loop(v: boolean) { loop = v; },\n    get positionMs() { return Math.min(positionNow(), score.durationMs); },\n    get playing() { return playing; },\n    get rate() { return rate; },\n  };\n\n  return player;\n}\n\n/** Per printed bar: where it starts in score-ms. For bar-wise scrub and cursor. */\nexport function measureStartsMs(score: Score): Array<{ measure: number; atMs: number }> {\n  const starts = new Map<number, number>();\n  for (const n of score.notes) {\n    const seen = starts.get(n.measure);\n    if (seen === undefined || n.onsetMs < seen) starts.set(n.measure, n.onsetMs);\n  }\n  return [...starts.entries()]\n    .map(([measure, atMs]) => ({ measure, atMs }))\n    .sort((a, b) => a.atMs - b.atMs);\n}\n"],"mappings":"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","names":[]}

package/dist/scene/index.d.ts

@@ -1,145 +1,8 @@
-import { PromoTheme, SafeBox, RecordOpts, Scene } from '../video.js';
+import { A as AudioClock, S as Score, a as LayerFactory, R as RenderCtx, b as ScoreFromMusicXMLOpts, T as TempoMap, c as ScoreNote } from '../waveform-DdSMAbYQ.js';
+export { L as Layer, d as SpectrumInput, e as SpectrumProps, W as WaveformInput, f as WaveformProps, s as scoreFromMusicXML, g as spectrumFactory, w as waveformFactory } from '../waveform-DdSMAbYQ.js';
+import { PromoTheme, RecordOpts, Scene, SafeBox } from '../video.js';
 import { RenderedNotation, Box, StaffMeasureBox, MeasureColumnBox } from '../promo.js';
 
-interface ScoreNote {
-    /** MIDI note number (middle C = 60). */
-    pitchMidi: number;
-    /** Diatonic letter name: C D E F G A B. */
-    step: string;
-    /** Chromatic alteration in semitones: -1 flat, +1 sharp, 0 natural, ±2 double. */
-    alter: number;
-    /** Scientific octave (middle C = C4). */
-    octave: number;
-    /** Onset on the linear playback clock, in ms (repeats expanded). */
-    onsetMs: number;
-    /** Sounding duration in ms (tie chains merged). */
-    durMs: number;
-    /** Staff index within the whole sheet (0-based). */
-    staff: number;
-    /** Voice id within the part. */
-    voice: number;
-    /** Performing hand: grand-staff top -> "R", bottom -> "L" (see hand-inference stub). */
-    hand: 'L' | 'R';
-    /** Lyric syllable attached to this note, if any. */
-    lyric?: string;
-    /** Fingering digit attached to this note, if any. */
-    fingering?: number;
-}
-/**
- * Tempo map. v1 is a single constant tempo (one segment at t=0). The piecewise
- * shape is the documented seam for rubato / multiple `<sound tempo>` — see the
- * tempo-map stub note in scoreFromMusicXML.
- */
-interface TempoMap {
-    /** Where the tempo came from: the XML's notated tempo, the fallback, or an override. */
-    source: 'xml' | 'fallback' | 'override';
-    /** Piecewise-constant segments, ordered by onset. v1 always has exactly one (at 0). */
-    segments: Array<{
-        atMs: number;
-        bpm: number;
-    }>;
-}
-interface Score {
-    notes: ScoreNote[];
-    tempoMap: TempoMap;
-    /** End of the last sounding note, in ms. */
-    durationMs: number;
-    key?: string;
-    timeSig?: string;
-    title?: string;
-    composer?: string;
-}
-interface ScoreFromMusicXMLOpts {
-    /** bpm to use when the XML has no notated tempo (DefaultStartTempoInBpm === 0). Default 100. */
-    tempoFallback?: number;
-    /** Force this bpm regardless of the XML's notated tempo (per-recipe override). */
-    tempoOverride?: number;
-    /**
-     * Provide the OSMD instance. Defaults to a literal `import('opensheetmusicdisplay')`
-     * + a detached div (works in a browser, or in Node after `setupHeadlessDom()`).
-     * Inject for tests or non-DOM environments.
-     */
-    osmdFactory?: () => any;
-}
-/**
- * Parse MusicXML into a timed, typed Score via OSMD's source model.
- *
- * @param xml  MusicXML document (uncompressed string; unzip .mxl first).
- * @param opts tempoFallback / tempoOverride / osmdFactory.
- */
-declare function scoreFromMusicXML(xml: string, opts?: ScoreFromMusicXMLOpts): Promise<Score>;
-
-/**
- * Audio clock the runner exposes to layers. `nowMs` is the current playback
- * position in milliseconds (audio-clock-driven, NOT wall-clock). During an
- * offline/deterministic render the runner supplies the frame time directly, so
- * `nowMs` and the `tMs` passed to `draw` agree.
- */
-interface AudioClock {
-    /** Current playback position in ms. */
-    nowMs(): number;
-}
-/**
- * Everything a layer needs to draw a frame. Constructed once per render and
- * passed to every `init`/`draw`. World coordinates: layers draw in the frame's
- * pixel space (0,0 top-left, W×H); the camera primitive (./camera) applies any
- * pan/zoom transform to `ctx2d` BEFORE the layer's `draw` runs, so a layer never
- * re-derives the viewport.
- */
-interface RenderCtx {
-    /** The shared 2D context all layers draw onto. */
-    ctx2d: CanvasRenderingContext2D;
-    /** Frame width in px. */
-    W: number;
-    /** Frame height in px. */
-    H: number;
-    /** The parsed Score (timing/pitch/hands/lyrics). May be undefined for
-     *  non-musical scenes (a pure hook/CTA card). */
-    score?: Score;
-    /** Audio playback clock. */
-    audioClock: AudioClock;
-    /** Per-app theme tokens (colours/fonts/brand). */
-    theme: PromoTheme;
-    /** Phone-safe content rectangle (./video safeBox) — layers anchor to this
-     *  instead of re-deriving insets. */
-    safeBox: SafeBox;
-    /** Capture frame rate. */
-    fps: number;
-}
-/**
- * A composable, time-synced render component.
- *
- * @typeParam P  the layer's prop type (what a SceneSpec passes as `p`).
- */
-interface Layer<P = unknown> {
-    /** Stable identity, e.g. "notation" | "falling-notes" | "caption". */
-    readonly key: string;
-    /**
-     * One-time setup: load assets, lay out, rasterize an offscreen bitmap, etc.
-     * Runs before the first captured frame. May be async (e.g. font/IR load).
-     */
-    init(ctx: RenderCtx, props: P): void | Promise<void>;
-    /**
-     * Per-frame draw. MUST be cheap and a pure function of `tMs` (no rAF / wall
-     * clock). `tMs` is the absolute playback time in ms.
-     */
-    draw(ctx: RenderCtx, tMs: number): void;
-    /** Optional teardown (free bitmaps / audio nodes). */
-    dispose?(): void;
-}
-/**
- * A layer factory keyed by name, with a runtime prop validator so the runner /
- * pre-render gate can reject an unknown prop before capture (spec: "unknown
- * layer/prop → fail fast"). `validateProps` returns an array of human-readable
- * errors ([] = valid).
- */
-interface LayerFactory<P = unknown> {
-    key: string;
-    create(): Layer<P>;
-    /** Validate a SceneSpec's `p` object. Return [] when valid. */
-    validateProps(props: unknown): string[];
-}
-
 /** One scheduled audio event, in seconds RELATIVE to the schedule start. */
 interface AudioEvent {
     /** Offset from schedule start, seconds. */
@@ -1130,36 +993,6 @@ interface PortraitProps extends WindowProps {
 }
 declare const portraitFactory: LayerFactory<PortraitProps>;
 
-/** Host-provided level source attached to RenderCtx by the app/capture harness. */
-interface SpectrumInput {
-    /** Normalized 0..1 magnitudes for `bands` bars at time tMs (preferred). */
-    levels?(tMs: number, bands: number): Float32Array | number[] | null | undefined;
-    /** Raw byte-FFT (0..255), log-binned by the layer (AnalyserNode shape). */
-    byteFreq?(tMs: number): Uint8Array | null | undefined;
-}
-/** Augment RenderCtx with the optional spectrum input (declaration merging). */
-declare module '../layer' {
-    interface RenderCtx {
-        /** Optional audio-reactive level source for the spectrum layer (host-wired). */
-        spectrum?: SpectrumInput;
-    }
-}
-interface SpectrumProps {
-    /** Number of bars. Default 44 (whozart SPEC_BARS). */
-    bars?: number;
-    /** Vertical center as a fraction of H. Default 0.46 (whozart). */
-    centerFrac?: number;
-    /** Max half-height as a fraction of H. Default 0.135 (whozart). */
-    maxHeightFrac?: number;
-    /** Bar fill at low magnitude (wine). Default theme.accent. */
-    colorLow?: string;
-    /** Bar fill at high magnitude (gold). Default theme.gold. */
-    colorHigh?: string;
-    /** Per-frame level provider (overrides ctx.spectrum). Pure fn of t for tests. */
-    levelsFn?: (tMs: number, bands: number) => Float32Array | number[] | null;
-}
-declare const spectrumFactory: LayerFactory<SpectrumProps>;
-
 interface BrandingProps {
     /** Wordmark to draw. Default theme.brand. */
     logo?: string;
@@ -1837,33 +1670,6 @@ interface CountdownProps {
 }
 declare const countdownFactory: LayerFactory<CountdownProps>;
 
-/** Host-provided time-domain sample source (AnalyserNode shape). */
-interface WaveformInput {
-    /** 0..255 samples centered ~128 (AnalyserNode.getByteTimeDomainData). */
-    byteTime?(tMs: number): Uint8Array | null | undefined;
-}
-declare module '../layer' {
-    interface RenderCtx {
-        /** Optional time-domain source for the waveform layer (host-wired). */
-        waveform?: WaveformInput;
-    }
-}
-interface WaveformProps {
-    /** Number of samples plotted. Default 128. */
-    samples?: number;
-    /** Vertical center as a fraction of H. Default 0.46. */
-    centerFrac?: number;
-    /** Max deflection as a fraction of H. Default 0.10. */
-    amplitudeFrac?: number;
-    /** Line width px. Default 5. */
-    lineWidth?: number;
-    /** Line colour. Default theme.accent. */
-    color?: string;
-    /** Per-frame sample provider returning -1..1 (overrides ctx.waveform). */
-    samplesFn?: (tMs: number, n: number) => Float32Array | number[] | null;
-}
-declare const waveformFactory: LayerFactory<WaveformProps>;
-
 /** Semitone interval sets (from the root) for the supported scales/modes. */
 declare const SCALE_INTERVALS: Record<string, number[]>;
 interface ScaleHighlightProps {
@@ -1990,6 +1796,14 @@ interface EndCardProps {
 declare const endCardFactory: LayerFactory<EndCardProps>;
 
 type ImageRevealMode = 'pixelate' | 'shuffle' | 'blur';
+/**
+ * Reveal pacing curve applied to linear progress before it drives the effect.
+ * - 'linear'        : constant rate (default — unchanged behavior).
+ * - 'easeOut'       : fast at first, SLOWER near the end (quadratic).
+ * - 'easeOutStrong' : like easeOut but a more DRAMATIC, drawn-out final reveal (cubic).
+ * - 'easeInOut'     : slow start (stays obscured), then a slow settle at the end.
+ */
+type RevealEasing = 'linear' | 'easeOut' | 'easeOutStrong' | 'easeInOut';
 interface ImageRevealProps {
     /** The image to reveal. Any CanvasImageSource (HTMLImageElement, OffscreenCanvas, …). */
     image: CanvasImageSource;
@@ -2006,7 +1820,9 @@ interface ImageRevealProps {
      * - blur:     controls maximum blur radius in px (0→mild, 1→extreme; default 0.5 ≈ 40px).
      */
     difficulty?: number;
+    /** Pacing curve for the reveal. Default 'linear'. See RevealEasing. */
+    easing?: RevealEasing;
 }
 declare const imageRevealFactory: LayerFactory<ImageRevealProps>;
 
-export { type Affine, type AudioClock, type AudioEvent, type BackgroundProps, type BeatGridOpts, type BeatPulseProps, type BeatTick, type BrandingProps, type BufferFactory, type BuildSceneOpts, type BuiltScene, type CameraState, type CaptionCue, type CaptionProps, type CaptionScript, type CaptionStyle, type ChordRibbonProps, type ChordSpan, type CircleOfFifthsProps, type CirclePoint, type ClickTrackOpts, type ColorBy, type ContourPlot, type ContourPoint, type CountInOpts, type CountdownProps, type CountingTrackProps, type CtaProps, DEFAULT_FUNCTION_COLORS, type DegreeLabel, type DegreeLabelsProps, type DroneOpts, type DuckWindow, type Easing, type EndCardProps, type ExtendedDemoOpts, FIFTHS_MAJOR, FIFTHS_MINOR, FOLLOW_BARS, FOLLOW_PAD, type FallingKeyboardDemoOpts, type FallingNotesProps, type FretboardProps, type FunctionColors, type FunctionalHarmonyProps, type GateError, type GateInput, type HandColors, type HarmonicFunction, type HarmonyMode, type HighlightRegion, type HookProps, type ImageRevealMode, type ImageRevealProps, type IntervalArcsProps, type KaraokeCaptionProps, type KaraokeWord, type KeyRect, type KeyboardLayout, type KeyboardLayoutOpts, type KeyboardProps, type KineticMode, type KineticTextProps, type LabelMode, type Layer, type LayerFactory, type McqCardProps, type NotationEngraving, type NotationLayout, type NotationLayoutOpts, type NotationProps, type NotationRect, type OutputProbe, PIANO_HIGH, PIANO_LOW, type ParticleBurstProps, type PitchContourProps, type Placement, type PlayheadLine, type PortraitProps, type ProgressRingProps, type PromoCardsDemoOpts, type PulseStyle, type Quiz, type QuizOption, type QuizPhase, type RadialSpectrumProps, type RayEndpoints, type RecordSceneSpecOpts, type Rect, type RenderCtx, type ResolvedSegment, type RevealProps, SCALE_INTERVALS, type SafeGuidesProps, type ScaleHighlightProps, type SceneSpec, type ScheduleTarget, type Score, type ScoreFromMusicXMLOpts, type ScoreNote, type ScrollCursorProps, type Section, type SectionMinimapProps, type SegmentAudio, type SegmentAudioCtx, type SegmentTransition, type SpecLayer, type SpectrumInput, type SpectrumProps, type StaffKeyboardRayProps, type StatCounterProps, type TempoMap, type TensionGraphProps, type TensionPoint, type TextureProps, type TimeAnchor, type TimelineSegment, type WaveformInput, type WaveformProps, activeChord, activeCue, activeSection, animatedSlot, applySchedule, applyToContext, assertGate, audioPlayheadLine, ballArc, ballX, beatGrid, beatPhase, beatPulseFactory, blackKeys, bpmOf, brandingFactory, buildScene, cameraForFollow, cameraTransform, chordRibbonFactory, circleOfFifthsDemoSpec, circleOfFifthsFactory, clamp, clickTrackSchedule, contourMinimapDemoSpec, contourPoints, contourPolyline, countInLeadSec, countInSchedule, countdownFactory, countdownRemaining, countdownSeconds, countingDegreeDemoSpec, countingTrackFactory, cropAroundBox, ctaFactory, cubicEaseInOut, cueOpacity, degreeLabel, degreeLabelsFactory, distinctMeasureIndices, distinctOnsets, dotAt, drawCaption, drawHighlight, droneSchedule, duckGainAt, easeIn, easeInOut, easeOut, endCardFactory, fallingKeyboardDemoScore, fallingKeyboardDemoSpec, fallingNotesFactory, firstMeasureBox, followBoxAt, followSrcBox, followWindowStart, fracSlotPoint, frameRect, fretboardFactory, functionColor, functionalHarmonyFactory, getKeyboardLayout, getLayerFactory, getNotationEngraving, harmonyDemoSpec, highlightIntensity, hookFactory, identityCamera, imageRevealFactory, inRange, intervalArcsFactory, invLerp, isBlackKey, karaokeCaptionFactory, kenBurns, keyCenterX, keyColumnWidth, keyRect, keySlot, keyboardFactory, keyboardLayout, kineticTextFactory, lerp, lerpBox, lerpCamera, linear, mapBoxThroughLayout, mcqCardFactory, mcqDemoSpec, measureColumnsFromLayout, measureCount, measureSpanBox, measureSpans, measureSystemMap, timeToX as minimapTimeToX, msPerBeat, notationFactory, notationLayout, noteColor, noteSetXRange, parseKey, parseTimeSig, particleBurstFactory, pcToSlot, pitchAt, pitchContourFactory, pitchRange, playheadLine, portraitFactory, progress01, progressRingFactory, projectPoint, promoCardsDemoSpec, pulseAt, quizPhase, radialSpectrumFactory, rayEndpoints, rayPointAt, recordSceneSpec, registerLayer, registeredKeys, resolveAnchor, resolveKeyboardLayout, resolveTimeline, revealFactory, revealProgress, runGate, safeGuidesFactory, scaleHighlightFactory, scoreFromMusicXML, scorePitchSpan, scrollCursorFactory, sectionMinimapFactory, setFollowLayoutProvider, setKeyboardLayout, setNotationEngraving, slotAngle, slotPc, slotPoint, spectrumFactory, staffAnchor, staffKeyboardRayFactory, staffRayDemoSpec, statCounterFactory, systemBox, tensionGraphFactory, textureFactory, transitionProgress, validateChordTrack, validateQuiz, validateSections, visualTimelineMs, vstackAudioPlayheadLine, vstackFollowBox, waveformFactory, whiteKeys, worldToViewport };
+export { type Affine, AudioClock, type AudioEvent, type BackgroundProps, type BeatGridOpts, type BeatPulseProps, type BeatTick, type BrandingProps, type BufferFactory, type BuildSceneOpts, type BuiltScene, type CameraState, type CaptionCue, type CaptionProps, type CaptionScript, type CaptionStyle, type ChordRibbonProps, type ChordSpan, type CircleOfFifthsProps, type CirclePoint, type ClickTrackOpts, type ColorBy, type ContourPlot, type ContourPoint, type CountInOpts, type CountdownProps, type CountingTrackProps, type CtaProps, DEFAULT_FUNCTION_COLORS, type DegreeLabel, type DegreeLabelsProps, type DroneOpts, type DuckWindow, type Easing, type EndCardProps, type ExtendedDemoOpts, FIFTHS_MAJOR, FIFTHS_MINOR, FOLLOW_BARS, FOLLOW_PAD, type FallingKeyboardDemoOpts, type FallingNotesProps, type FretboardProps, type FunctionColors, type FunctionalHarmonyProps, type GateError, type GateInput, type HandColors, type HarmonicFunction, type HarmonyMode, type HighlightRegion, type HookProps, type ImageRevealMode, type ImageRevealProps, type IntervalArcsProps, type KaraokeCaptionProps, type KaraokeWord, type KeyRect, type KeyboardLayout, type KeyboardLayoutOpts, type KeyboardProps, type KineticMode, type KineticTextProps, type LabelMode, LayerFactory, type McqCardProps, type NotationEngraving, type NotationLayout, type NotationLayoutOpts, type NotationProps, type NotationRect, type OutputProbe, PIANO_HIGH, PIANO_LOW, type ParticleBurstProps, type PitchContourProps, type Placement, type PlayheadLine, type PortraitProps, type ProgressRingProps, type PromoCardsDemoOpts, type PulseStyle, type Quiz, type QuizOption, type QuizPhase, type RadialSpectrumProps, type RayEndpoints, type RecordSceneSpecOpts, type Rect, RenderCtx, type ResolvedSegment, type RevealEasing, type RevealProps, SCALE_INTERVALS, type SafeGuidesProps, type ScaleHighlightProps, type SceneSpec, type ScheduleTarget, Score, ScoreFromMusicXMLOpts, ScoreNote, type ScrollCursorProps, type Section, type SectionMinimapProps, type SegmentAudio, type SegmentAudioCtx, type SegmentTransition, type SpecLayer, type StaffKeyboardRayProps, type StatCounterProps, TempoMap, type TensionGraphProps, type TensionPoint, type TextureProps, type TimeAnchor, type TimelineSegment, activeChord, activeCue, activeSection, animatedSlot, applySchedule, applyToContext, assertGate, audioPlayheadLine, ballArc, ballX, beatGrid, beatPhase, beatPulseFactory, blackKeys, bpmOf, brandingFactory, buildScene, cameraForFollow, cameraTransform, chordRibbonFactory, circleOfFifthsDemoSpec, circleOfFifthsFactory, clamp, clickTrackSchedule, contourMinimapDemoSpec, contourPoints, contourPolyline, countInLeadSec, countInSchedule, countdownFactory, countdownRemaining, countdownSeconds, countingDegreeDemoSpec, countingTrackFactory, cropAroundBox, ctaFactory, cubicEaseInOut, cueOpacity, degreeLabel, degreeLabelsFactory, distinctMeasureIndices, distinctOnsets, dotAt, drawCaption, drawHighlight, droneSchedule, duckGainAt, easeIn, easeInOut, easeOut, endCardFactory, fallingKeyboardDemoScore, fallingKeyboardDemoSpec, fallingNotesFactory, firstMeasureBox, followBoxAt, followSrcBox, followWindowStart, fracSlotPoint, frameRect, fretboardFactory, functionColor, functionalHarmonyFactory, getKeyboardLayout, getLayerFactory, getNotationEngraving, harmonyDemoSpec, highlightIntensity, hookFactory, identityCamera, imageRevealFactory, inRange, intervalArcsFactory, invLerp, isBlackKey, karaokeCaptionFactory, kenBurns, keyCenterX, keyColumnWidth, keyRect, keySlot, keyboardFactory, keyboardLayout, kineticTextFactory, lerp, lerpBox, lerpCamera, linear, mapBoxThroughLayout, mcqCardFactory, mcqDemoSpec, measureColumnsFromLayout, measureCount, measureSpanBox, measureSpans, measureSystemMap, timeToX as minimapTimeToX, msPerBeat, notationFactory, notationLayout, noteColor, noteSetXRange, parseKey, parseTimeSig, particleBurstFactory, pcToSlot, pitchAt, pitchContourFactory, pitchRange, playheadLine, portraitFactory, progress01, progressRingFactory, projectPoint, promoCardsDemoSpec, pulseAt, quizPhase, radialSpectrumFactory, rayEndpoints, rayPointAt, recordSceneSpec, registerLayer, registeredKeys, resolveAnchor, resolveKeyboardLayout, resolveTimeline, revealFactory, revealProgress, runGate, safeGuidesFactory, scaleHighlightFactory, scorePitchSpan, scrollCursorFactory, sectionMinimapFactory, setFollowLayoutProvider, setKeyboardLayout, setNotationEngraving, slotAngle, slotPc, slotPoint, staffAnchor, staffKeyboardRayFactory, staffRayDemoSpec, statCounterFactory, systemBox, tensionGraphFactory, textureFactory, transitionProgress, validateChordTrack, validateQuiz, validateSections, visualTimelineMs, vstackAudioPlayheadLine, vstackFollowBox, whiteKeys, worldToViewport };

package/dist/scene/index.js

@@ -44,6 +44,7 @@ async function scoreFromMusicXML(xml, opts = {}) {
   while (!it.EndReached && steps++ < MAX_ITERATOR_STEPS) {
     const enrolled = it.CurrentEnrolledTimestamp?.RealValue ?? 0;
     const onsetMs = wholeNoteToMs(enrolled);
+    const measure = it.CurrentMeasure?.MeasureNumber ?? (it.CurrentMeasureIndex ?? 0) + 1;
     const voiceEntries = it.CurrentAudibleVoiceEntries?.() ?? [];
     for (const ve of voiceEntries) {
       const voiceId = ve.ParentVoice?.VoiceId ?? 1;
@@ -69,7 +70,8 @@ async function scoreFromMusicXML(xml, opts = {}) {
           durMs: Math.round(wholeNoteToMs(wholeNoteLen)),
           staff: staffIdx,
           voice: voiceId,
-          hand
+          hand,
+          measure
         };
         const lyric = extractLyric(ve);
         if (lyric != null) note.lyric = lyric;
@@ -4766,11 +4768,18 @@ var endCardFactory = {
 };
 
 // src/scene/layers/imageReveal.ts
+function applyEasing(p, easing) {
+  if (easing === "easeOut") return 1 - (1 - p) * (1 - p);
+  if (easing === "easeOutStrong") return 1 - (1 - p) * (1 - p) * (1 - p);
+  if (easing === "easeInOut") return p * p * (3 - 2 * p);
+  return p;
+}
 var DEFAULTS11 = {
   mode: "pixelate",
   startMs: 0,
   durationMs: 6e3,
-  difficulty: 0.5
+  difficulty: 0.5,
+  easing: "linear"
 };
 function clamp017(x) {
   return x < 0 ? 0 : x > 1 ? 1 : x;
@@ -4799,6 +4808,7 @@ function imageRevealLayer() {
   let startMs = DEFAULTS11.startMs;
   let durationMs = DEFAULTS11.durationMs;
   let difficulty = DEFAULTS11.difficulty;
+  let easing = DEFAULTS11.easing;
   let image = null;
   let offscreen = null;
   let offCtx = null;
@@ -4832,6 +4842,7 @@ function imageRevealLayer() {
       startMs = props.startMs ?? DEFAULTS11.startMs;
       durationMs = props.durationMs ?? DEFAULTS11.durationMs;
       difficulty = props.difficulty ?? DEFAULTS11.difficulty;
+      easing = props.easing ?? DEFAULTS11.easing;
       image = props.image;
       const src = props.image;
       imgW = src["naturalWidth"] ?? src["displayWidth"] ?? src["width"] ?? 0;
@@ -4839,7 +4850,8 @@ function imageRevealLayer() {
     },
     draw(ctx, tMs) {
       if (!image || imgW === 0 || imgH === 0) return;
-      const p = clamp017((tMs - startMs) / (durationMs > 0 ? durationMs : 1));
+      const raw = clamp017((tMs - startMs) / (durationMs > 0 ? durationMs : 1));
+      const p = applyEasing(raw, easing);
       const sb = ctx.safeBox;
       const fit = fitRect(imgW, imgH, sb.left, sb.top, sb.w, sb.h);
       const c = ctx.ctx2d;
@@ -4951,6 +4963,7 @@ function drawShuffle(c, image, fit, p, difficulty, imgW, imgH) {
   }
 }
 var VALID_MODES = ["pixelate", "shuffle", "blur"];
+var VALID_EASINGS = ["linear", "easeOut", "easeOutStrong", "easeInOut"];
 var imageRevealFactory = {
   key: "image-reveal",
   create: imageRevealLayer,
@@ -4967,6 +4980,8 @@ var imageRevealFactory = {
       errs.push("image-reveal.durationMs must be a positive number");
     if (p["difficulty"] != null && (typeof p["difficulty"] !== "number" || p["difficulty"] < 0 || p["difficulty"] > 1))
       errs.push("image-reveal.difficulty must be a number in [0, 1]");
+    if (p["easing"] != null && !VALID_EASINGS.includes(p["easing"]))
+      errs.push(`image-reveal.easing must be one of: ${VALID_EASINGS.join(", ")}`);
     return errs;
   }
 };