@braccato/core 1.16.4 → 1.16.6

package/dist/engine.d.ts

@@ -272,6 +272,11 @@ export interface LetterMaskSweep {
     easing: string;
 }
 export declare function planLetterMaskSweep(swipe: SwipeRamp, letterCount: number, swipeDurationMs: number, rtl: boolean): LetterMaskSweep[];
+export interface LetterWaveTiming {
+    delayMs: number;
+    durationMs: number;
+}
+export declare function planLetterWave(swipe: SwipeRamp, letterCount: number, wordDurationMs: number, swipeDurationMs: number, swipeLeadMs: number, floatDurationMs: number): LetterWaveTiming[];
 export declare function clearStyleCaches(engine: AnimationEngineInstance): void;
 export declare function parseColorAlpha(value: string): number | null;
 interface PreparedLineScroll {

package/dist/engine.js

@@ -436,7 +436,7 @@ function mirrorImageHighlightAnimations(part, animations) {
         mirror.currentTime = animation.currentTime;
         const timing = animationTimingTracks.get(animation);
         if (timing)
-            animationTimingTracks.set(mirror, timing);
+            animationTimingTracks.set(mirror, { ...timing, skipDriftSample: true });
         mirrors.push(mirror);
     }
     return mirrors;
@@ -529,8 +529,11 @@ function timingValueToMs(value) {
 function animationCurrentTimeMs(animation) {
     return timingValueToMs(animation.currentTime);
 }
-function animationActiveDurationMs(animation) {
-    return timingValueToMs(animation.effect?.getComputedTiming().activeDuration);
+// A finished animation's currentTime stops at its end time, which counts the delay, so that is where
+// the expected time has to stop too. Clamping to the active duration alone saturates a delayed
+// animation as soon as it is created and hides any drift in it.
+function animationEndTimeMs(animation) {
+    return timingValueToMs(animation.effect?.getComputedTiming().endTime);
 }
 function wrappedTimingOffsetMs(actualTimeMs, expectedTimeMs, wrapDurationMs) {
     return positiveModulo(actualTimeMs - expectedTimeMs + wrapDurationMs / 2, wrapDurationMs) - wrapDurationMs / 2;
@@ -542,18 +545,18 @@ function normalizeAnimationTimeMs(animation, timeMs, timing) {
     if (timing.wrapDurationMs && timing.wrapDurationMs > 0) {
         return positiveModulo(timeMs, timing.wrapDurationMs);
     }
-    const activeDurationMs = animationActiveDurationMs(animation);
-    if (activeDurationMs !== null && Number.isFinite(activeDurationMs)) {
-        return Math.min(timeMs, activeDurationMs);
+    const endTimeMs = animationEndTimeMs(animation);
+    if (endTimeMs !== null && Number.isFinite(endTimeMs)) {
+        return Math.min(timeMs, endTimeMs);
     }
     return timeMs;
 }
 function animationTimingSample(part, animation, currentTime) {
-    if (animation.playState === "idle") {
+    const timing = animationTimingTracks.get(animation);
+    if (!timing || timing.skipDriftSample) {
         return null;
     }
-    const timing = animationTimingTracks.get(animation);
-    if (!timing) {
+    if (animation.playState === "idle") {
         return null;
     }
     const actualTimeMs = animationCurrentTimeMs(animation);
@@ -833,6 +836,43 @@ export function planLetterMaskSweep(swipe, letterCount, swipeDurationMs, rtl) {
         return { keyframes, delayMs: 0, durationMs, easing: swipe.easing };
     });
 }
+function swipeRamp(config) {
+    return {
+        easing: config.highlight.swipeEasing,
+        startFrom: config.highlight.swipeStartFrom,
+        startTo: config.highlight.swipeStartTo,
+        endFrom: config.highlight.swipeEndFrom,
+        endTo: config.highlight.swipeEndTo,
+    };
+}
+// How far through its float a letter crests, as a keyframe offset.
+const LETTER_WAVE_CREST_OFFSET = 0.4;
+// When each letter's wave starts, counted from the start of the word, and how long it lasts. A letter
+// crests just as the swipe finishes lighting it. If the swipe lights it faster than the float rises,
+// it starts early enough to make that, which on a short word means before the word itself does. If the
+// swipe lights it slower, it starts as the swipe touches it and its float stretches to crest on time.
+export function planLetterWave(swipe, letterCount, wordDurationMs, swipeDurationMs, swipeLeadMs, floatDurationMs) {
+    const riseMs = floatDurationMs * LETTER_WAVE_CREST_OFFSET;
+    const windows = computeLetterSwipeWindows({ ...swipe, easing: "linear" }, letterCount, swipeDurationMs);
+    const timings = [];
+    for (let index = 0; index < letterCount; index++) {
+        if (!windows) {
+            // No windows for this ramp, so spread the letters evenly over the word.
+            timings.push({ delayMs: (wordDurationMs * index) / letterCount, durationMs: floatDurationMs });
+            continue;
+        }
+        // The swipe runs swipeLeadMs ahead of the word, so take the lead back off.
+        const touchedMs = windows[index].delayMs - swipeLeadMs;
+        const litMs = touchedMs + windows[index].durationMs;
+        if (litMs - riseMs > touchedMs) {
+            timings.push({ delayMs: touchedMs, durationMs: (litMs - touchedMs) / LETTER_WAVE_CREST_OFFSET });
+        }
+        else {
+            timings.push({ delayMs: litMs - riseMs, durationMs: floatDurationMs });
+        }
+    }
+    return timings;
+}
 function startRichSyncedHighlightAnimations(engine, part, config, swipeTimeMs, wordTimeMs, swipeDurationMs, glowDurationMs, appliedTimingOffsetMs) {
     const animations = [];
     const highlight = part.highlightElement;
@@ -842,13 +882,7 @@ function startRichSyncedHighlightAnimations(engine, part, config, swipeTimeMs, w
         const swipeCurrentTimeMs = correctedAnimationTimeMs(swipeTimeMs, appliedTimingOffsetMs, swipeDurationMs);
         const highlightLetters = part.highlightLetterElements;
         if (highlightLetters && highlightLetters.length > 0) {
-            const sweeps = planLetterMaskSweep({
-                easing: config.highlight.swipeEasing,
-                startFrom: config.highlight.swipeStartFrom,
-                startTo: config.highlight.swipeStartTo,
-                endFrom: config.highlight.swipeEndFrom,
-                endTo: config.highlight.swipeEndTo,
-            }, highlightLetters.length, swipeDurationMs, part.highlightElement.classList.contains(RTL_CLASS));
+            const sweeps = planLetterMaskSweep(swipeRamp(config), highlightLetters.length, swipeDurationMs, part.highlightElement.classList.contains(RTL_CLASS));
             sweeps.forEach((sweep, index) => {
                 const targets = [highlightLetters[index], part.imageLayers?.glowLetters[index]].filter((target) => target !== undefined);
                 for (const target of targets) {
@@ -856,7 +890,11 @@ function startRichSyncedHighlightAnimations(engine, part, config, swipeTimeMs, w
                         offset: frame.offset,
                         maskPosition: frame.maskPosition,
                         WebkitMaskPosition: frame.maskPosition,
-                    })), { duration: sweep.durationMs, delay: sweep.delayMs, easing: sweep.easing, fill: "both" }), swipeTiming);
+                    })), { duration: sweep.durationMs, delay: sweep.delayMs, easing: sweep.easing, fill: "both" }), 
+                    // The last letter's sweep ends last, so it alone covers the whole word.
+                    index === sweeps.length - 1 && target === highlightLetters[index]
+                        ? swipeTiming
+                        : { ...swipeTiming, skipDriftSample: true });
                     animation.currentTime = swipeCurrentTimeMs;
                     if (index === 0)
                         swipeAnimation = animation;
@@ -1000,27 +1038,51 @@ function startWordAnimations(engine, part, config, currentTime, appliedTimingOff
                 { transform: `translateY(0)${emphasisRest}`, easing: config.letterWave.riseEasing },
                 {
                     transform: `${config.letterWave.transform}${emphasisPeak}`,
-                    offset: 0.4,
+                    offset: LETTER_WAVE_CREST_OFFSET,
                     easing: config.letterWave.fallEasing,
                 },
                 { transform: `${config.letterWave.settle}${emphasisRest}` },
             ];
             const letterCount = letters.length;
-            const staggerMs = timedDurationMs > 0 ? timedDurationMs / 2.5 / letterCount : 0;
-            const cascadeDurationMs = config.letterWave.durationMs + (letterCount - 1) * staggerMs;
-            const floatStartMs = correctedAnimationTimeMs(wordTimeMs, appliedTimingOffsetMs, cascadeDurationMs);
+            const waves = planLetterWave(swipeRamp(config), letterCount, timedDurationMs, swipeDurationMs, swipeLeadMs, config.letterWave.durationMs);
+            // A letter that starts before the word would have a negative delay, which the drift check reads
+            // as the wave running behind once it finishes. Run the wave's clock ahead by the head start
+            // instead, the way the swipe carries its lead, so every delay stays at zero or above.
+            const waveLeadMs = Math.max(0, -Math.min(...waves.map(wave => wave.delayMs)));
+            const waveEndsMs = waves.map(wave => wave.delayMs + wave.durationMs);
+            const lastWaveEndMs = Math.max(...waveEndsMs);
+            const lastEndingWaveIndex = waveEndsMs.lastIndexOf(lastWaveEndMs);
+            const cascadeDurationMs = waveLeadMs + lastWaveEndMs;
+            const floatStartMs = correctedAnimationTimeMs(wordTimeMs + waveLeadMs, appliedTimingOffsetMs, cascadeDurationMs);
             const floatKeyframeSignature = JSON.stringify(floatKeyframes);
-            for (const set of [part.letterElements, part.highlightLetterElements, part.imageLayers?.glowLetters]) {
-                set?.forEach((letterElement, index) => {
+            // Glow letters only show while the glow does: never when it is off or renders nothing for this
+            // word, and not once it has faded out. Their waves stop there instead of running to the end.
+            const glowLetters = config.enabled.highlightGlow && !part.glowSuppressed ? part.imageLayers?.glowLetters : undefined;
+            const glowEndMs = Number.parseFloat(config.highlight.imageGlowOpacityTo) === 0 ? waveLeadMs + glowDurationMs : Infinity;
+            const animateLetters = (letters, endMs, sampled) => {
+                letters?.forEach((letterElement, index) => {
+                    const delayMs = waves[index].delayMs + waveLeadMs;
+                    if (delayMs >= endMs)
+                        return;
+                    const endDelayMs = Math.min(0, endMs - delayMs - waves[index].durationMs);
                     const animation = trackLyricAnimationTiming(engine, acquireWaveAnimation(engine, letterElement, floatKeyframes, floatKeyframeSignature, {
-                        duration: config.letterWave.durationMs,
-                        delay: index * staggerMs,
+                        duration: waves[index].durationMs,
+                        delay: delayMs,
+                        endDelay: endDelayMs,
                         fill: "forwards",
-                    }), { appliedTimingOffsetMs, offsetMs: 0 });
+                    }), {
+                        appliedTimingOffsetMs,
+                        offsetMs: waveLeadMs,
+                        // The wave that ends last covers the whole word. A theme's swipe ramp can make that an early letter.
+                        skipDriftSample: !sampled || index !== lastEndingWaveIndex,
+                    });
                     animation.currentTime = floatStartMs;
                     wobbleAnimations.push(animation);
                 });
-            }
+            };
+            animateLetters(part.letterElements, Infinity, true);
+            animateLetters(part.highlightLetterElements, Infinity, false);
+            animateLetters(glowLetters, glowEndMs, false);
         }
     }
     part.animations = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@braccato/core",
-  "version": "1.16.4",
+  "version": "1.16.6",
   "description": "Synchronized lyrics renderer with word-by-word animations",
   "type": "module",
   "license": "MIT",