@real-music-packages/web-core 0.12.0 → 0.14.0

package/dist/scene/index.js

@@ -177,6 +177,10 @@ var easeOut = (t) => {
   const c = clamp(t, 0, 1);
   return 1 - (1 - c) * (1 - c);
 };
+var transitionProgress = (tMs, startMs, durationMs, easing = easeInOut) => {
+  if (durationMs <= 0) return 1;
+  return easing(invLerp(startMs, startMs + durationMs, tMs));
+};
 
 // src/scene/caption.ts
 function activeCue(script, tMs) {
@@ -2617,6 +2621,96 @@ registerLayer(circleOfFifthsFactory);
 registerLayer(pitchContourFactory);
 registerLayer(sectionMinimapFactory);
 
+// src/scene/audioLayers.ts
+function countInSchedule(opts) {
+  const beats = opts.beats ?? 4;
+  const accent = opts.accentDownbeat ?? true;
+  const beatSec = 60 / opts.bpm;
+  const events = [];
+  for (let i = 0; i < beats; i++) {
+    const isDownbeat = accent && i === 0;
+    events.push({
+      atSec: i * beatSec,
+      note: isDownbeat ? "C6" : "C5",
+      durSec: 0.05,
+      gain: isDownbeat ? 1 : 0.7,
+      kind: "count"
+    });
+  }
+  return events;
+}
+function countInLeadSec(opts) {
+  return (opts.beats ?? 4) * (60 / opts.bpm);
+}
+function clickTrackSchedule(opts) {
+  const beatSec = 60 / opts.bpm;
+  const bpb = opts.beatsPerBar ?? 4;
+  const start = opts.startSec ?? 0;
+  const events = [];
+  const n = Math.floor(opts.durationSec / beatSec);
+  for (let i = 0; i < n; i++) {
+    const isDownbeat = i % bpb === 0;
+    events.push({
+      atSec: start + i * beatSec,
+      note: isDownbeat ? "C6" : "C5",
+      durSec: 0.03,
+      gain: isDownbeat ? 0.6 : 0.4,
+      kind: "click"
+    });
+  }
+  return events;
+}
+function droneSchedule(opts) {
+  const gain = opts.gain ?? 0.15;
+  const events = [
+    { atSec: 0, note: opts.root, durSec: opts.durationSec, gain, kind: "drone" }
+  ];
+  if (opts.fifth ?? true) {
+    events.push({ atSec: 0, note: transposeFifth(opts.root), durSec: opts.durationSec, gain, kind: "drone" });
+  }
+  return events;
+}
+function transposeFifth(note) {
+  const m = /^([A-G])(#|b)?(\d)$/.exec(note);
+  if (!m) return note;
+  const order = ["C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B"];
+  const pcMap = { C: 0, D: 2, E: 4, F: 5, G: 7, A: 9, B: 11 };
+  let pc = pcMap[m[1]] + (m[2] === "#" ? 1 : m[2] === "b" ? -1 : 0);
+  let oct = parseInt(m[3], 10);
+  pc += 7;
+  if (pc >= 12) {
+    pc -= 12;
+    oct += 1;
+  }
+  return `${order[pc]}${oct}`;
+}
+function duckGainAt(windows, tSec, floor = 0.25, rampSec = 0.2) {
+  for (const w of windows) {
+    if (tSec >= w.startSec - rampSec && tSec <= w.endSec + rampSec) {
+      if (tSec < w.startSec) return lerpGain(1, floor, (tSec - (w.startSec - rampSec)) / rampSec);
+      if (tSec > w.endSec) return lerpGain(floor, 1, (tSec - w.endSec) / rampSec);
+      return floor;
+    }
+  }
+  return 1;
+}
+function lerpGain(a, b, t) {
+  const k = t < 0 ? 0 : t > 1 ? 1 : t;
+  return a + (b - a) * k;
+}
+function applySchedule(instrument, schedule, startTime) {
+  for (const ev of schedule) {
+    if (ev.note == null) continue;
+    instrument.triggerAttackRelease(
+      ev.note,
+      ev.durSec ?? 0.05,
+      startTime + ev.atSec,
+      ev.gain ?? 1
+    );
+  }
+  return schedule.length;
+}
+
 // src/scene/camera.ts
 function cameraTransform(cam, W, H) {
   const s = cam.zoom;
@@ -2658,7 +2752,13 @@ function resolveTimeline(spec, totalSec) {
   return spec.timeline.map((seg) => {
     const startSec = resolveAnchor(seg.at[0], totalSec);
     const endSec = resolveAnchor(seg.at[1], totalSec);
-    return { startMs: startSec * 1e3, endMs: endSec * 1e3, layers: seg.layers };
+    return {
+      startMs: startSec * 1e3,
+      endMs: endSec * 1e3,
+      layers: seg.layers,
+      audio: seg.audio,
+      transition: seg.transition
+    };
   });
 }
 function visualTimelineMs(resolved) {
@@ -2674,6 +2774,24 @@ var SCREEN_PINNED_KEYS = /* @__PURE__ */ new Set([
   "safe-guides",
   "mcq-card"
 ]);
+function defaultBufferFactory() {
+  const g = globalThis;
+  if (typeof g.OffscreenCanvas === "function") {
+    return (w, h) => {
+      const c = new g.OffscreenCanvas(w, h);
+      return { ctx: c.getContext("2d"), image: c };
+    };
+  }
+  if (typeof g.document !== "undefined" && g.document?.createElement) {
+    return (w, h) => {
+      const c = g.document.createElement("canvas");
+      c.width = w;
+      c.height = h;
+      return { ctx: c.getContext("2d"), image: c };
+    };
+  }
+  return void 0;
+}
 async function buildScene(opts) {
   const { spec, theme, score } = opts;
   const [W, H] = spec.size;
@@ -2681,6 +2799,8 @@ async function buildScene(opts) {
   const resolved = resolveTimeline(spec, opts.totalSec);
   const safe = safeBox(W, H);
   const camera = opts.camera ?? (() => identityCamera(W, H));
+  const bufferFactory = opts.bufferFactory ?? defaultBufferFactory();
+  const hasTransitions = resolved.some((s) => s.transition && s.transition.durationMs > 0);
   const clock = { nowMs: () => 0 };
   const baseCtx = {
     W,
@@ -2692,7 +2812,8 @@ async function buildScene(opts) {
     fps
   };
   const bound = [];
-  for (const seg of resolved) {
+  for (let segIndex = 0; segIndex < resolved.length; segIndex++) {
+    const seg = resolved[segIndex];
     for (const sl of seg.layers) {
       const factory = getLayerFactory(sl.k);
       if (!factory) {
@@ -2708,32 +2829,175 @@ async function buildScene(opts) {
         layer,
         startMs: seg.startMs,
         endMs: seg.endMs,
+        segIndex,
         screenPinned: SCREEN_PINNED_KEYS.has(sl.k)
       });
     }
   }
   const durationMs = visualTimelineMs(resolved);
-  function renderFrame(ctx2d, tMs) {
-    clock.nowMs = () => tMs;
-    const ctx = { ...baseCtx, ctx2d };
-    const cam = camera(tMs);
-    ctx2d.save();
-    applyToContext(ctx2d, cam, W, H);
+  function dirVec(dir) {
+    switch (dir) {
+      case "right":
+        return { x: 1, y: 0 };
+      case "up":
+        return { x: 0, y: -1 };
+      case "down":
+        return { x: 0, y: 1 };
+      case "left":
+      default:
+        return { x: -1, y: 0 };
+    }
+  }
+  function transitionEnvs(tr, p) {
+    if (tr.type === "push") {
+      const v = dirVec(tr.direction);
+      const span = Math.abs(v.x) ? W : H;
+      return {
+        incoming: { alpha: 1, dx: -v.x * span * (1 - p), dy: -v.y * span * (1 - p) },
+        outgoing: { alpha: 1, dx: v.x * span * p, dy: v.y * span * p }
+      };
+    }
+    if (tr.type === "wipe") {
+      const v = dirVec(tr.direction);
+      let inClip;
+      let outClip;
+      if (v.x !== 0) {
+        const w = W * p;
+        if (v.x < 0) {
+          inClip = { x: 0, y: 0, w, h: H };
+          outClip = { x: w, y: 0, w: W - w, h: H };
+        } else {
+          inClip = { x: W - w, y: 0, w, h: H };
+          outClip = { x: 0, y: 0, w: W - w, h: H };
+        }
+      } else {
+        const h = H * p;
+        if (v.y < 0) {
+          inClip = { x: 0, y: 0, w: W, h };
+          outClip = { x: 0, y: h, w: W, h: H - h };
+        } else {
+          inClip = { x: 0, y: H - h, w: W, h };
+          outClip = { x: 0, y: 0, w: W, h: H - h };
+        }
+      }
+      return {
+        incoming: { alpha: 1, dx: 0, dy: 0, clip: inClip },
+        outgoing: { alpha: 1, dx: 0, dy: 0, clip: outClip }
+      };
+    }
+    return {
+      incoming: { alpha: p, dx: 0, dy: 0 },
+      outgoing: { alpha: 1 - p, dx: 0, dy: 0 }
+    };
+  }
+  function frameplan(tMs) {
+    const plan = [];
+    for (let i = 0; i < resolved.length; i++) {
+      const seg = resolved[i];
+      if (tMs < seg.startMs || tMs >= seg.endMs) continue;
+      const tr = seg.transition;
+      const prev = i > 0 ? resolved[i - 1] : void 0;
+      const enterEnd = tr ? seg.startMs + Math.max(0, tr.durationMs) : seg.startMs;
+      const inEnter = tr && tr.durationMs > 0 && tMs < enterEnd && prev;
+      if (!inEnter) {
+        plan.push({ segIndex: i, drawTMs: tMs, env: null });
+        continue;
+      }
+      const p = transitionProgress(tMs, seg.startMs, tr.durationMs, tr.easing ?? easeInOut);
+      const { incoming, outgoing } = transitionEnvs(tr, p);
+      const heldTMs = clamp(tMs, prev.startMs, prev.endMs - 1);
+      plan.push({ segIndex: i - 1, drawTMs: heldTMs, env: outgoing });
+      plan.push({ segIndex: i, drawTMs: tMs, env: incoming });
+    }
+    return plan;
+  }
+  function drawSegmentInto(target, segIndex, drawTMs) {
+    const ctx = { ...baseCtx, ctx2d: target };
+    const cam = camera(drawTMs);
+    target.save();
+    applyToContext(target, cam, W, H);
     for (const b of bound) {
-      if (b.screenPinned) continue;
-      if (tMs < b.startMs || tMs >= b.endMs) continue;
-      b.layer.draw(ctx, tMs);
+      if (b.segIndex !== segIndex || b.screenPinned) continue;
+      if (drawTMs < b.startMs || drawTMs >= b.endMs) continue;
+      b.layer.draw(ctx, drawTMs);
     }
-    ctx2d.restore();
+    target.restore();
+    target.save();
+    target.setTransform(1, 0, 0, 1, 0, 0);
+    for (const b of bound) {
+      if (b.segIndex !== segIndex || !b.screenPinned) continue;
+      if (drawTMs < b.startMs || drawTMs >= b.endMs) continue;
+      b.layer.draw(ctx, drawTMs);
+    }
+    target.restore();
+  }
+  function compositeEntry(ctx2d, e) {
+    if (e.env === null) {
+      drawSegmentInto(ctx2d, e.segIndex, e.drawTMs);
+      return;
+    }
+    const env = e.env;
+    if (!bufferFactory) {
+      ctx2d.save();
+      ctx2d.globalAlpha = ctx2d.globalAlpha * env.alpha;
+      drawSegmentInto(ctx2d, e.segIndex, e.drawTMs);
+      ctx2d.restore();
+      return;
+    }
+    const buf = bufferFactory(W, H);
+    drawSegmentInto(buf.ctx, e.segIndex, e.drawTMs);
     ctx2d.save();
     ctx2d.setTransform(1, 0, 0, 1, 0, 0);
-    for (const b of bound) {
-      if (!b.screenPinned) continue;
-      if (tMs < b.startMs || tMs >= b.endMs) continue;
-      b.layer.draw(ctx, tMs);
+    if (env.alpha !== 1) ctx2d.globalAlpha = ctx2d.globalAlpha * env.alpha;
+    if (env.clip) {
+      ctx2d.beginPath();
+      ctx2d.rect(env.clip.x, env.clip.y, env.clip.w, env.clip.h);
+      ctx2d.clip();
     }
+    ctx2d.drawImage(buf.image, env.dx, env.dy, W, H);
     ctx2d.restore();
   }
+  function renderFrame(ctx2d, tMs) {
+    clock.nowMs = () => tMs;
+    const ctx = { ...baseCtx, ctx2d };
+    const cam = camera(tMs);
+    if (!hasTransitions) {
+      ctx2d.save();
+      applyToContext(ctx2d, cam, W, H);
+      for (const b of bound) {
+        if (b.screenPinned) continue;
+        if (tMs < b.startMs || tMs >= b.endMs) continue;
+        b.layer.draw(ctx, tMs);
+      }
+      ctx2d.restore();
+      ctx2d.save();
+      ctx2d.setTransform(1, 0, 0, 1, 0, 0);
+      for (const b of bound) {
+        if (!b.screenPinned) continue;
+        if (tMs < b.startMs || tMs >= b.endMs) continue;
+        b.layer.draw(ctx, tMs);
+      }
+      ctx2d.restore();
+      return;
+    }
+    const plan = frameplan(tMs);
+    for (const e of plan) compositeEntry(ctx2d, e);
+  }
+  function scheduleAudio(instrument, baseSec) {
+    let fired = 0;
+    for (const seg of resolved) {
+      if (!seg.audio) continue;
+      const segStartSec = baseSec + seg.startMs / 1e3;
+      if (seg.audio.schedule?.length) {
+        fired += applySchedule(instrument, seg.audio.schedule, segStartSec);
+      }
+      if (seg.audio.onEnter) {
+        const segClock = { nowMs: () => seg.startMs };
+        seg.audio.onEnter(segClock, { instrument, startSec: segStartSec, score });
+      }
+    }
+    return fired;
+  }
   return {
     W,
     H,
@@ -2741,6 +3005,7 @@ async function buildScene(opts) {
     durationMs,
     resolved,
     renderFrame,
+    scheduleAudio,
     dispose() {
       for (const b of bound) b.layer.dispose?.();
     }
@@ -2751,6 +3016,13 @@ async function recordSceneSpec(opts) {
   const record = opts.record ?? recordScenes;
   const composite = {
     durationMs: built.durationMs,
+    // Schedule any per-segment audio against the capture clock exactly when the
+    // first frame is entered, so it's anchored to the same start the recorder
+    // uses. onEnter fires once per Scene (see recordScenes), so this runs once.
+    onEnter: opts.segmentAudio ? () => {
+      const sa = opts.segmentAudio;
+      built.scheduleAudio(sa.instrument, sa.audioNow() + (sa.lookaheadSec ?? 0.1));
+    } : void 0,
     draw: (ctx, t01) => built.renderFrame(ctx, t01 * built.durationMs)
   };
   return record([composite], {
@@ -2763,96 +3035,6 @@ async function recordSceneSpec(opts) {
   });
 }
 
-// src/scene/audioLayers.ts
-function countInSchedule(opts) {
-  const beats = opts.beats ?? 4;
-  const accent = opts.accentDownbeat ?? true;
-  const beatSec = 60 / opts.bpm;
-  const events = [];
-  for (let i = 0; i < beats; i++) {
-    const isDownbeat = accent && i === 0;
-    events.push({
-      atSec: i * beatSec,
-      note: isDownbeat ? "C6" : "C5",
-      durSec: 0.05,
-      gain: isDownbeat ? 1 : 0.7,
-      kind: "count"
-    });
-  }
-  return events;
-}
-function countInLeadSec(opts) {
-  return (opts.beats ?? 4) * (60 / opts.bpm);
-}
-function clickTrackSchedule(opts) {
-  const beatSec = 60 / opts.bpm;
-  const bpb = opts.beatsPerBar ?? 4;
-  const start = opts.startSec ?? 0;
-  const events = [];
-  const n = Math.floor(opts.durationSec / beatSec);
-  for (let i = 0; i < n; i++) {
-    const isDownbeat = i % bpb === 0;
-    events.push({
-      atSec: start + i * beatSec,
-      note: isDownbeat ? "C6" : "C5",
-      durSec: 0.03,
-      gain: isDownbeat ? 0.6 : 0.4,
-      kind: "click"
-    });
-  }
-  return events;
-}
-function droneSchedule(opts) {
-  const gain = opts.gain ?? 0.15;
-  const events = [
-    { atSec: 0, note: opts.root, durSec: opts.durationSec, gain, kind: "drone" }
-  ];
-  if (opts.fifth ?? true) {
-    events.push({ atSec: 0, note: transposeFifth(opts.root), durSec: opts.durationSec, gain, kind: "drone" });
-  }
-  return events;
-}
-function transposeFifth(note) {
-  const m = /^([A-G])(#|b)?(\d)$/.exec(note);
-  if (!m) return note;
-  const order = ["C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B"];
-  const pcMap = { C: 0, D: 2, E: 4, F: 5, G: 7, A: 9, B: 11 };
-  let pc = pcMap[m[1]] + (m[2] === "#" ? 1 : m[2] === "b" ? -1 : 0);
-  let oct = parseInt(m[3], 10);
-  pc += 7;
-  if (pc >= 12) {
-    pc -= 12;
-    oct += 1;
-  }
-  return `${order[pc]}${oct}`;
-}
-function duckGainAt(windows, tSec, floor = 0.25, rampSec = 0.2) {
-  for (const w of windows) {
-    if (tSec >= w.startSec - rampSec && tSec <= w.endSec + rampSec) {
-      if (tSec < w.startSec) return lerpGain(1, floor, (tSec - (w.startSec - rampSec)) / rampSec);
-      if (tSec > w.endSec) return lerpGain(floor, 1, (tSec - w.endSec) / rampSec);
-      return floor;
-    }
-  }
-  return 1;
-}
-function lerpGain(a, b, t) {
-  const k = t < 0 ? 0 : t > 1 ? 1 : t;
-  return a + (b - a) * k;
-}
-function applySchedule(instrument, schedule, startTime) {
-  for (const ev of schedule) {
-    if (ev.note == null) continue;
-    instrument.triggerAttackRelease(
-      ev.note,
-      ev.durSec ?? 0.05,
-      startTime + ev.atSec,
-      ev.gain ?? 1
-    );
-  }
-  return schedule.length;
-}
-
 // src/scene/gate.ts
 var AV_TOLERANCE_MS = 60;
 async function runGate(input) {
@@ -3304,6 +3486,7 @@ export {
   staffAnchor,
   staffKeyboardRayFactory,
   staffRayDemoSpec,
+  transitionProgress,
   validateChordTrack,
   validateQuiz,
   validateSections,