@braccato/core 1.0.0 → 1.1.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.                                            |
@@ -256,6 +256,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.                                            |
@@ -256,6 +256,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;

package/dist/engine.js

@@ -145,6 +145,7 @@ export function createAnimationEngineInstance(engineDocument, engineWindow, host
         cachedCSSValues: new Map(),
         cachedAnimationSettings: null,
         passiveScrollEnabled: false,
+        playbackRate: 1,
         passiveRAFId: null,
         pendingLyricsUpdateFrame: null,
         learnedAnimationTimingOffsetMs: 0,
@@ -351,8 +352,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);
@@ -1452,14 +1474,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";

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.1.0",
   "description": "Synchronized lyrics renderer with word-by-word animations",
   "type": "module",
   "license": "MIT",