@braccato/core 1.0.0 → 1.2.0

package/README.md

@@ -81,7 +81,7 @@ connects, and everything it was handed by then is applied at once.
 | `mediaElement`  |                | `HTMLMediaElement \| null` (get)    | `null`   | What `source` resolved to. Null while disconnected, and null for a selector that missed.                                                   |
 | `currentTime`   | `current-time` | `number`                            | `0`      | Playback position in **seconds**. Writing it renders the view again, so whoever holds the clock drives the lyrics by writing this.        |
 | `playing`       | `playing`      | `boolean`                           | `false`  | A paused view animates differently from a playing one.                                                                                     |
-| `tickOptions`   |                | `ElementTickOptions`                | `{}`     | The rest of a tick: four offsets taken off the clock before it is matched, whether passive scrolling is on, and when the clock was sampled. |
+| `tickOptions`   |                | `ElementTickOptions`                | `{}`     | The rest of a tick: four offsets taken off the clock before it is matched, whether passive scrolling is on, when the clock was sampled, and the rate the song is playing at. |
 | `theme`         | `theme`        | `string`                            | `""`     | A compiled stylesheet. See Theming.                                                                                                        |
 | `host`          |                | `Partial<LyricsRendererHost>`       | `{}`     | Overrides for what the renderer asks of its surroundings. Every member has a default. Writing it while connected rebuilds the view.        |
 | `renderer`      |                | `LyricsRenderer \| null` (get)      | `null`   | The renderer underneath, for the day the tag runs out. A different one after every reconnection.                                            |
@@ -179,6 +179,13 @@ The ones a theme reaches for first. `variables.css` declares the rest.
 `line-height`. Every word is given the glow, so a theme that wants it to mean something selects on
 `data-long-word`, which the module sets on any part held past `blyrics-long-word-threshold`.
 
+The instrumental ripple is the one place a property carries geometry rather than a value.
+`--blyrics-instrumental-wave-path-high` and `--blyrics-instrumental-wave-path-low` are the two shapes
+it morphs between, each a `path()`, and a theme redrawing them is how the wave changes amplitude or
+frequency. Both must use the same commands in the same order with the same number of arguments: a
+browser only interpolates two paths smoothly when their command sequences match, and a mismatched
+pair snaps at the halfway point instead of flowing.
+
 ### Class names
 
 These are published API rather than implementation. Renaming one costs a migration rather than a
@@ -256,6 +263,12 @@ either is dropped and the getter keeps reporting what the binding last read. Dro
 reported, because a consumer who bound a source and left their own frame loop running would otherwise
 be told about it sixty times a second. Unbind and the clock goes back to whoever asked for it.
 
+The rate is read off the media element too, and passed on as `tickOptions.playbackRate`, so a song at
+half or double speed animates at half or double speed rather than sweeping at 1x and being corrected
+on the next tick. A consumer driving the clock itself sets that option instead. Only the animations
+that follow the song are scaled: a line's exit, a word's fade and the scroll between lines keep the
+timing the theme asked for at every rate.
+
 A reading the media element has not refreshed yet is carried forward at the playback rate it was
 taken at, capped at 100ms of frame time. That cap is what covers a stall: the view runs at most 100ms
 past the last real reading and then waits with it. What it costs is a step backwards when the clock

package/dist/README.md

@@ -81,7 +81,7 @@ connects, and everything it was handed by then is applied at once.
 | `mediaElement`  |                | `HTMLMediaElement \| null` (get)    | `null`   | What `source` resolved to. Null while disconnected, and null for a selector that missed.                                                   |
 | `currentTime`   | `current-time` | `number`                            | `0`      | Playback position in **seconds**. Writing it renders the view again, so whoever holds the clock drives the lyrics by writing this.        |
 | `playing`       | `playing`      | `boolean`                           | `false`  | A paused view animates differently from a playing one.                                                                                     |
-| `tickOptions`   |                | `ElementTickOptions`                | `{}`     | The rest of a tick: four offsets taken off the clock before it is matched, whether passive scrolling is on, and when the clock was sampled. |
+| `tickOptions`   |                | `ElementTickOptions`                | `{}`     | The rest of a tick: four offsets taken off the clock before it is matched, whether passive scrolling is on, when the clock was sampled, and the rate the song is playing at. |
 | `theme`         | `theme`        | `string`                            | `""`     | A compiled stylesheet. See Theming.                                                                                                        |
 | `host`          |                | `Partial<LyricsRendererHost>`       | `{}`     | Overrides for what the renderer asks of its surroundings. Every member has a default. Writing it while connected rebuilds the view.        |
 | `renderer`      |                | `LyricsRenderer \| null` (get)      | `null`   | The renderer underneath, for the day the tag runs out. A different one after every reconnection.                                            |
@@ -179,6 +179,13 @@ The ones a theme reaches for first. `variables.css` declares the rest.
 `line-height`. Every word is given the glow, so a theme that wants it to mean something selects on
 `data-long-word`, which the module sets on any part held past `blyrics-long-word-threshold`.
 
+The instrumental ripple is the one place a property carries geometry rather than a value.
+`--blyrics-instrumental-wave-path-high` and `--blyrics-instrumental-wave-path-low` are the two shapes
+it morphs between, each a `path()`, and a theme redrawing them is how the wave changes amplitude or
+frequency. Both must use the same commands in the same order with the same number of arguments: a
+browser only interpolates two paths smoothly when their command sequences match, and a mismatched
+pair snaps at the halfway point instead of flowing.
+
 ### Class names
 
 These are published API rather than implementation. Renaming one costs a migration rather than a
@@ -256,6 +263,12 @@ either is dropped and the getter keeps reporting what the binding last read. Dro
 reported, because a consumer who bound a source and left their own frame loop running would otherwise
 be told about it sixty times a second. Unbind and the clock goes back to whoever asked for it.
 
+The rate is read off the media element too, and passed on as `tickOptions.playbackRate`, so a song at
+half or double speed animates at half or double speed rather than sweeping at 1x and being corrected
+on the next tick. A consumer driving the clock itself sets that option instead. Only the animations
+that follow the song are scaled: a line's exit, a word's fade and the scroll between lines keep the
+timing the theme asked for at every rate.
+
 A reading the media element has not refreshed yet is carried forward at the playback rate it was
 taken at, capped at 100ms of frame time. That cap is what covers a stall: the view runs at most 100ms
 past the last real reading and then waits with it. What it costs is a step backwards when the clock

package/dist/element.js

@@ -422,8 +422,15 @@ export class BraccatoLyricsElement extends HTMLElement {
         // consumer whose clock runs before the lyrics arrive is the ordinary case rather than a fault.
         if (renderer === null || renderer.container === null)
             return;
+        // The rate a bound media element is playing at is the element's to report, the same way the
+        // clock is, so it overrides what the consumer wrote for exactly as long as the binding lasts.
+        const boundRate = this.#media === null ? undefined : this.#media.playbackRate;
         // The play state last, so a consumer writing plain JavaScript cannot answer that question twice.
-        renderer.tick(this.#currentTimeS, { ...this.#tickOptions, isPlaying: this.#playing });
+        renderer.tick(this.#currentTimeS, {
+            ...this.#tickOptions,
+            ...(boundRate === undefined ? {} : { playbackRate: boundRate }),
+            isPlaying: this.#playing,
+        });
     }
     #upgradeProperty(name) {
         // Written through the class rather than `this`: TypeScript refuses an indexed write to a

package/dist/engine.d.ts

@@ -56,6 +56,7 @@ export interface AnimationEngineInstance extends AnimEngineViewState {
      * from a tick, so it has no options object to read.
      */
     passiveScrollEnabled: boolean;
+    playbackRate: number;
     passiveRAFId: number | null;
     pendingLyricsUpdateFrame: number | null;
     learnedAnimationTimingOffsetMs: number;
@@ -183,6 +184,8 @@ interface AnimationConfig {
         waveFrom: string;
         waveTo: string;
         waveEasing: string;
+        wavePathHigh: string;
+        wavePathLow: string;
         waveOscillationDurationMs: number;
         waveOscillationEasing: string;
     };

package/dist/engine.js

@@ -17,6 +17,7 @@
 // module is bundled into the isolated world and the page world separately, so those are two clocks
 // that never meet. `themeSettings.ts` holds the third thing under that rule.
 import { ANIMATING_CLASS, CURRENT_LYRICS_CLASS, FOOTER_CLASS, LINE_CLASS, PAUSED_CLASS, USER_SCROLLING_CLASS, } from "./constants.js";
+import { INSTRUMENTAL_WAVE_PATH_HIGH, INSTRUMENTAL_WAVE_PATH_LOW } from "./instrumental.js";
 import { registerThemeSetting } from "./themeSettings.js";
 import { clamp, getRelativeLayoutBounds, positiveModulo, roundedMs, toMs } from "./util.js";
 const NO_LYRICS_ELEMENT_LOG = "No lyrics element found on the page, skipping lyrics injection";
@@ -145,6 +146,7 @@ export function createAnimationEngineInstance(engineDocument, engineWindow, host
         cachedCSSValues: new Map(),
         cachedAnimationSettings: null,
         passiveScrollEnabled: false,
+        playbackRate: 1,
         passiveRAFId: null,
         pendingLyricsUpdateFrame: null,
         learnedAnimationTimingOffsetMs: 0,
@@ -325,8 +327,8 @@ const WORD_HIGHLIGHT_SELECTOR = ".blyrics-word-highlight";
 const INSTRUMENTAL_FILL_SELECTOR = ".blyrics--instrumental-fill";
 const INSTRUMENTAL_WAVE_CLIP_SELECTOR = ".blyrics--wave-clip";
 const INSTRUMENTAL_WAVE_PATH_SELECTOR = ".blyrics--wave-path";
-const INSTRUMENTAL_WAVE_PATH_HIGH = 'path("M -4 3 Q 1 2 5 3 Q 10 4 14 3 Q 18 2 22 3 Q 26 4 30 3 L 30 4 L -4 4 Z")';
-const INSTRUMENTAL_WAVE_PATH_LOW = 'path("M -4 3 Q 1 4 5 3 Q 10 2 14 3 Q 18 4 22 3 Q 26 2 30 3 L 30 4 L -4 4 Z")';
+const INSTRUMENTAL_WAVE_PATH_HIGH_FALLBACK = `path("${INSTRUMENTAL_WAVE_PATH_HIGH}")`;
+const INSTRUMENTAL_WAVE_PATH_LOW_FALLBACK = `path("${INSTRUMENTAL_WAVE_PATH_LOW}")`;
 const LINE_SCROLL_INDEX_PROPERTY = "--blyrics-line-scroll-index";
 const LINE_SCROLL_ACTIVE_INDEX_PROPERTY = "--blyrics-line-scroll-active-index";
 const LINE_SCROLL_RELATIVE_INDEX_PROPERTY = "--blyrics-line-scroll-relative-index";
@@ -351,8 +353,29 @@ function trackLyricAnimationTiming(engine, animation, timing) {
         ...timing,
         appliedTimingOffsetMs: timing.appliedTimingOffsetMs ?? engine.learnedAnimationTimingOffsetMs,
     });
+    // Being tracked is what makes an animation the song's rather than the interface's, so it is also
+    // what decides which ones follow the song's rate.
+    animation.playbackRate = engine.playbackRate;
     return animation;
 }
+/**
+ * Puts the animations already running onto a new rate. Setting `playbackRate` keeps `currentTime`,
+ * so each one carries on from where the song left it rather than restarting.
+ */
+function applyPlaybackRateToRunningAnimations(engine) {
+    for (const line of engine.lines) {
+        for (const animation of line.animations) {
+            if (animationTimingTracks.has(animation))
+                animation.playbackRate = engine.playbackRate;
+        }
+        for (const part of line.parts) {
+            for (const animation of part.animations) {
+                if (animationTimingTracks.has(animation))
+                    animation.playbackRate = engine.playbackRate;
+            }
+        }
+    }
+}
 function correctedAnimationTimeMs(targetTimeMs, appliedTimingOffsetMs, maxTimeMs) {
     const scheduledTimeMs = targetTimeMs - appliedTimingOffsetMs;
     return maxTimeMs === undefined ? scheduledTimeMs : Math.min(scheduledTimeMs, maxTimeMs);
@@ -834,9 +857,9 @@ function startInstrumentalAnimations(engine, lineData, config, currentTime, appl
             fill: "both",
         }, { appliedTimingOffsetMs, offsetMs: 0 });
         waveOscillationAnimation = animateInstrumentalChild(engine, lineData, INSTRUMENTAL_WAVE_PATH_SELECTOR, [
-            { d: INSTRUMENTAL_WAVE_PATH_HIGH },
-            { d: INSTRUMENTAL_WAVE_PATH_LOW, offset: 0.5 },
-            { d: INSTRUMENTAL_WAVE_PATH_HIGH },
+            { d: config.instrumental.wavePathHigh },
+            { d: config.instrumental.wavePathLow, offset: 0.5 },
+            { d: config.instrumental.wavePathHigh },
         ], {
             duration: config.instrumental.waveOscillationDurationMs,
             easing: config.instrumental.waveOscillationEasing,
@@ -994,6 +1017,8 @@ function readAnimationConfig(engine, lyricsElement) {
             waveFrom: getCSSValue(engine, lyricsElement, "--blyrics-instrumental-wave-transform-from", "scaleY(1.2)"),
             waveTo: getCSSValue(engine, lyricsElement, "--blyrics-instrumental-wave-transform-to", "scaleY(0.0001)"),
             waveEasing: getCSSValue(engine, lyricsElement, "--blyrics-instrumental-wave-easing", "ease-in"),
+            wavePathHigh: getCSSValue(engine, lyricsElement, "--blyrics-instrumental-wave-path-high", INSTRUMENTAL_WAVE_PATH_HIGH_FALLBACK),
+            wavePathLow: getCSSValue(engine, lyricsElement, "--blyrics-instrumental-wave-path-low", INSTRUMENTAL_WAVE_PATH_LOW_FALLBACK),
             waveOscillationDurationMs: getCSSDurationWithFallback(engine, lyricsElement, "--blyrics-instrumental-wave-oscillation-duration", "1.25s"),
             waveOscillationEasing: getCSSValue(engine, lyricsElement, "--blyrics-instrumental-wave-oscillation-easing", "ease-in-out"),
         },
@@ -1452,14 +1477,24 @@ export function resolveTickOptions(options) {
         richsyncOffsetTrim: options.richsyncOffsetTrim ?? 0,
         lineOffsetTrim: options.lineOffsetTrim ?? 0,
         passiveScrollEnabled: options.passiveScrollEnabled ?? false,
+        playbackRate: resolvePlaybackRate(options.playbackRate),
     };
 }
+// A rate of zero or less would freeze every animation that follows the song, which is a second
+// answer to the question `isPlaying` already answers.
+function resolvePlaybackRate(rate) {
+    return rate !== undefined && Number.isFinite(rate) && rate > 0 ? rate : 1;
+}
 /**
  * Renders one view against a tick with nothing left out.
  */
 export function tickView(engine, currentTime, options) {
     const { eventCreationTime, isPlaying, smoothScroll } = options;
     engine.passiveScrollEnabled = options.passiveScrollEnabled;
+    if (engine.playbackRate !== options.playbackRate) {
+        engine.playbackRate = options.playbackRate;
+        applyPlaybackRateToRunningAnimations(engine);
+    }
     const now = Date.now();
     if (currentTime === 0 && !isPlaying) {
         return "ok";
@@ -1528,6 +1563,7 @@ export function tickView(engine, currentTime, options) {
         }
         const tabRendererHeight = engine.cachedTabRendererHeight ?? tabRenderer.getBoundingClientRect().height;
         let scrollTop = tabRenderer.scrollTop;
+        const maxScrollTop = Math.max(0, tabRenderer.scrollHeight - tabRenderer.clientHeight);
         if (animationConfig.enabled.scroll) {
             updateVisibleLyricWillChange(engine, lines, scrollTop, engine.pendingLineScroll?.toScrollTop ?? scrollTop, tabRendererHeight);
         }
@@ -1681,8 +1717,9 @@ export function tickView(engine, currentTime, options) {
             scrollPos = Math.max(scrollPos, lastActiveLyric.position - tabRendererHeight + lastActiveLyric.height);
             // Make sure top of last active lyric is visible.
             scrollPos = Math.min(scrollPos, lastActiveLyric.position);
-            // Make sure we're not trying to scroll to negative values
-            scrollPos = Math.max(0, scrollPos);
+            // Past either end the browser clamps the write and reports nothing, leaving the view aiming
+            // at a position it never reached and re-aiming once per remaining line.
+            scrollPos = clamp(scrollPos, 0, maxScrollTop);
             if (ENABLE_DEBUG_RENDER.getBooleanValue()) {
                 let transform = engine.window.getComputedStyle(lyricsElement).transform;
                 const matrix = new engine.window.DOMMatrix(transform);
@@ -1867,6 +1904,9 @@ function applyScrollPadding(engine) {
     });
     engine.document.documentElement.style.setProperty("--blyrics-padding-top", top + "px");
     engine.document.documentElement.style.setProperty("--blyrics-padding-bottom", bottom + "px");
+    // Inline, because a theme's own `.blyrics-container { padding }` is appended after the package's
+    // stylesheet at the same weight and would otherwise take this room away.
+    lyricsElement.style.setProperty("padding-bottom", bottom + "px");
 }
 /**
  * Re-reads the view's layout: the scroll padding first, then the line positions the padding moved.

package/dist/instrumental.d.ts

@@ -1,3 +1,5 @@
+export declare const INSTRUMENTAL_WAVE_PATH_HIGH = "M -4 3 Q 1 2 5 3 Q 10 4 14 3 Q 18 2 22 3 Q 26 4 30 3 L 30 4 L -4 4 Z";
+export declare const INSTRUMENTAL_WAVE_PATH_LOW = "M -4 3 Q 1 4 5 3 Q 10 2 14 3 Q 18 4 22 3 Q 26 2 30 3 L 30 4 L -4 4 Z";
 /**
  * Creates an HTML element representing an instrumental break in the lyrics.
  *

package/dist/instrumental.js

@@ -1,3 +1,5 @@
+export const INSTRUMENTAL_WAVE_PATH_HIGH = "M -4 3 Q 1 2 5 3 Q 10 4 14 3 Q 18 2 22 3 Q 26 4 30 3 L 30 4 L -4 4 Z";
+export const INSTRUMENTAL_WAVE_PATH_LOW = "M -4 3 Q 1 4 5 3 Q 10 2 14 3 Q 18 4 22 3 Q 26 2 30 3 L 30 4 L -4 4 Z";
 /**
  * Creates an HTML element representing an instrumental break in the lyrics.
  *
@@ -56,8 +58,7 @@ export function createInstrumentalElement(doc, container, durationMs, lineIndex)
     // This only contains the surface water. It closes at y=4.
     const wavePath = doc.createElementNS(svgNS, "path");
     wavePath.classList.add("blyrics--wave-path");
-    // Initial draw (matches the 0% keyframe below)
-    wavePath.setAttribute("d", "M -4 3 Q 1 2 5 3 Q 10 4 14 3 Q 18 2 22 3 Q 26 4 30 3 L 30 4 L -4 4 Z");
+    wavePath.setAttribute("d", INSTRUMENTAL_WAVE_PATH_HIGH);
     clipPath.appendChild(wavePath);
     defs.appendChild(clipPath);
     svg.appendChild(defs);

package/dist/renderer.js

@@ -269,6 +269,10 @@ export function createLyricsRenderer(rendererOptions) {
             // Everything the engine resolved off the document was resolved against the theme that just
             // went away.
             clearEngineStyleCaches(engine);
+            // The target scroll position is one of the settings a theme carries, and the scroll padding is
+            // sized against it, so a theme that moves the target moves the layout even when no rule in it
+            // does.
+            measure();
             return needsLyricRebuild;
         },
         tick(currentTimeS, options) {

package/dist/styles/instrumental.css

@@ -69,6 +69,8 @@
 
 	/* Prepare the WAAPI flatten transition. */
 	transform: scaleY(1.2);
+
+	d: var(--blyrics-instrumental-wave-path-high);
 }
 
 /* Trigger the Flattening */
@@ -90,14 +92,3 @@
 	transition-timing-function: ease-out;
 	transition-delay: 0s;
 }
-
-/* Update Keyframes for the "Split" shape */
-/* These paths must close at 'L 30 4 L -4 4' to match the static rect overlap */
-@keyframes blyrics-wave {
-	0%, 100% {
-		d: path("M -4 3 Q 1 2 5 3 Q 10 4 14 3 Q 18 2 22 3 Q 26 4 30 3 L 30 4 L -4 4 Z");
-	}
-	50% {
-		d: path("M -4 3 Q 1 4 5 3 Q 10 2 14 3 Q 18 4 22 3 Q 26 2 30 3 L 30 4 L -4 4 Z");
-	}
-}

package/dist/styles/variables.css

@@ -117,6 +117,8 @@
 	--blyrics-instrumental-wave-transform-from: scaleY(1.2);
 	--blyrics-instrumental-wave-transform-to: scaleY(0.0001);
 	--blyrics-instrumental-wave-easing: ease-in;
+	--blyrics-instrumental-wave-path-high: path("M -4 3 Q 1 2 5 3 Q 10 4 14 3 Q 18 2 22 3 Q 26 4 30 3 L 30 4 L -4 4 Z");
+	--blyrics-instrumental-wave-path-low: path("M -4 3 Q 1 4 5 3 Q 10 2 14 3 Q 18 4 22 3 Q 26 2 30 3 L 30 4 L -4 4 Z");
 	--blyrics-instrumental-wave-oscillation-duration: 1.25s;
 	--blyrics-instrumental-wave-oscillation-easing: ease-in-out;
 

package/dist/types.d.ts

@@ -28,6 +28,13 @@ export interface TickOptions {
      * false.
      */
     passiveScrollEnabled?: boolean;
+    /**
+     * How fast the song moves through its own timeline, as a multiple of real time. Defaults to 1, and
+     * zero or less reads as 1 because `isPlaying` is what says a song is stopped. Scales the animations
+     * that follow the song; a line's exit, a word's fade and the scroll between lines are the
+     * interface's own gestures and keep the timing the theme asked for at every rate.
+     */
+    playbackRate?: number;
 }
 /**
  * A tick with nothing left out. The engine reads every field unconditionally, so the defaults are

package/package.json

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