@braccato/core 1.16.3 → 1.16.5

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

@@ -833,6 +833,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 +879,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) {
@@ -1000,23 +1031,27 @@ 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 cascadeDurationMs = waveLeadMs + Math.max(...waves.map(wave => wave.delayMs + wave.durationMs));
+            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) => {
                     const animation = trackLyricAnimationTiming(engine, acquireWaveAnimation(engine, letterElement, floatKeyframes, floatKeyframeSignature, {
-                        duration: config.letterWave.durationMs,
-                        delay: index * staggerMs,
+                        duration: waves[index].durationMs,
+                        delay: waves[index].delayMs + waveLeadMs,
                         fill: "forwards",
-                    }), { appliedTimingOffsetMs, offsetMs: 0 });
+                    }), { appliedTimingOffsetMs, offsetMs: waveLeadMs });
                     animation.currentTime = floatStartMs;
                     wobbleAnimations.push(animation);
                 });

package/dist/styles/instrumental.css

@@ -57,11 +57,6 @@
 	transform: translateY(-4%);
 }
 
-.blyrics--paused .blyrics--wave-clip {
-	transition-duration: 100000000s !important;
-	transform: translateY(100%) !important;
-}
-
 .blyrics--wave-path {
 	/* Set the transform origin to the bottom of the wave shape (y=4). */
 	transform-box: fill-box;

package/package.json

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