@vestra-player/sdk 1.5.26 → 1.5.27

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 1.5.27
+
+**Who must change: nobody.** No API changes, `apiVersion` stays `vestra/1`, no player version needed. Plugins pick the fix up with the player's next SDK upgrade (the player builds the `plugin` object with its own copy); nothing in a plugin changes.
+
+- **Generated streams reach their full frame rate on Windows.** A stream from `openStream` or a file resolver (the NES emulator: one 1/60 s picture per `frame()`) played at 23–26 frames a second on Windows instead of 60. The SDK asked the player how much audio the sound card had played, rendered at most one frame, and waited 5 ms before asking again; Windows rounds that wait up to its 15.6 ms timer tick, and with the round trip one pass took about 40 ms, so one frame per pass could not keep up. macOS timers are about 1 ms, which hid it. Each pass now calls `frame()` as many times in a row as it takes to refill the whole lead (about 50 ms of audio, unchanged, so latency is unchanged), at most 16 times, and stops early when a frame carries no audio; and a pass that rendered frames and already took longer than 5 ms is followed at once instead of after another timer tick. A pass that rendered nothing (paused, lead full) still waits 5 ms after it ends, so an idle or paused stream asks the player no more often than before. Measured against a real-time audio clock with the NES core and its homebrew ROM: with a 15–30 ms round trip 1.5.26 rendered 22–32 frames a second and let the device run dry, 1.5.27 renders 60 and keeps it fed; only a round trip near 50 ms (the whole lead) still lets it run dry now and then. Controls (start, pause, seek) still apply between frames and never while one renders, and `stop()` still ends after the frame being rendered.
+- Docs: *Example: signal generator* says `frame()` may be called several times back to back. `llms.txt` and `llms-full.txt` regenerated.
+
 ## 1.5.26
 
 **Who must change: authors whose plugin uses a member without one of the capabilities it needs, and only to `check`, `build` or `pack` again.** No API changes, `apiVersion` stays `vestra/1`, no player version needed, and packages already built keep running as before: the player decides at run time exactly as it did. What changes is that `vestra-plugin check` (and so `build` and `pack`) now fails on such a use, including uses that never failed at run time: a listener (`onChange`) without `events` never fires instead of failing; a subtitle change (`select`, `load`, `remove`, `setStyle`) without `subtitles.read` fails only when it reads the current selection; a capability's **Also needs** (`processing.video` without `playback.read`) was documented but not enforced. Such a plugin packed with 1.5.25 and stops packing with 1.5.26 until the missing capability is added to `manifest.json` (or the use removed). The player's built-in plugins and the plugin repository's plugins were checked with this release: no findings.

package/dist/plugin/stream.js

@@ -5,8 +5,33 @@
  */
 import { failure, sleep, toError } from "./runtime.js";
 import { abortError } from "./player.js";
-/** Frames of audio buffered ahead of the device before rendering pauses. */
+/**
+ * Frames of audio buffered ahead of the device before rendering pauses
+ * (50 ms). Each pump refills the whole lead, so it must outlast one pump
+ * period: the pump itself (a `producer.state` round trip and the frames),
+ * plus a Windows timer tick (15.6 ms) unless the pump rendered and already
+ * took {@link PERIOD}. Measured with a
+ * real-time clock, round trips up to about 30 ms never let the device run
+ * dry; near 50 ms they do now and then. A larger lead would add latency
+ * between input and picture.
+ */
 const AHEAD = 2400;
+/**
+ * At most this many frames per pump. A lead is a few frames (three of
+ * 1/60 s); the cap only stops a plugin whose frames carry next to no audio
+ * from rendering without pause.
+ */
+const BATCH = 16;
+/**
+ * Milliseconds from the start of one pump to the start of the next. A pump
+ * that rendered frames and already took longer is followed at once: a timer
+ * on top would add a whole Windows tick (15.6 ms; a timer there never fires
+ * sooner) to every pump while playing, and the period must stay well inside
+ * the lead. A pump that rendered nothing (paused, lead full, a control not
+ * yet acknowledged) waits this long after it ends, so an idle stream polls
+ * the player no more often than it always did.
+ */
+const PERIOD = 5;
 /** Frames written before the host is asked to select the stream. */
 const PREROLL = 2048;
 class StreamHandle {
@@ -23,6 +48,7 @@ class StreamHandle {
     #sample;
     #sequence;
     #timer;
+    #immediate;
     #pumping = Promise.resolve();
     constructor(scope, service, setup) {
         this.#scope = scope;
@@ -48,6 +74,7 @@ class StreamHandle {
     }
     async #pump() {
         const producer = this.#service.runtime.host.producer;
+        const begun = performance.now();
         try {
             const state = await producer.state(this.#producer);
             if (!this.#running)
@@ -67,16 +94,36 @@ class StreamHandle {
             if (state.input?.pending)
                 await producer.ackInput(state.input.pending);
             const paused = control ? control.paused : state.paused;
+            let rendered = 0;
+            // Refill the whole lead now, not one frame per pump: a pump period (a
+            // round trip, and a timer tick after a short pump: 16–40 ms on Windows)
+            // is longer than a 1/60 s frame. No control lands while this loop runs: the next one is
+            // read by the next pump, at a frame boundary.
             if (!control &&
                 state.acknowledged &&
                 state.epoch === this.#epoch &&
-                !paused &&
-                this.#sample - state.consumedFrames < AHEAD)
-                await this.#render();
-            if (this.#running)
-                this.#timer = setTimeout(() => {
-                    this.#pumping = this.#pump();
-                }, 5);
+                !paused)
+                while (this.#running &&
+                    rendered < BATCH &&
+                    this.#sample - state.consumedFrames < AHEAD) {
+                    const before = this.#sample;
+                    await this.#render();
+                    // A frame without audio does not move the clock: wait for the next
+                    // pump, after a full PERIOD (it does not count as rendered).
+                    if (this.#sample === before)
+                        break;
+                    rendered++;
+                }
+            if (!this.#running)
+                return;
+            const next = () => {
+                this.#pumping = this.#pump();
+            };
+            const wait = rendered ? PERIOD - (performance.now() - begun) : PERIOD;
+            if (wait > 0)
+                this.#timer = setTimeout(next, wait);
+            else
+                this.#immediate = setImmediate(next);
         }
         catch (error) {
             const retired = await retirement(this.#service, this.#generation, error);
@@ -114,6 +161,7 @@ class StreamHandle {
         this.#stopping ??= (async () => {
             this.#running = false;
             clearTimeout(this.#timer);
+            clearImmediate(this.#immediate);
             await this.#pumping.catch(() => { });
             try {
                 await this.#service.closeIfCurrent(this.#generation);

package/llms-full.txt

@@ -1,4 +1,4 @@
-# @vestra-player/sdk 1.5.26: full reference
+# @vestra-player/sdk 1.5.27: full reference
 
 > Everything needed to write a Vestra Player plugin (plugin API `vestra/1`): the guides, every public declaration of `@vestra-player/sdk` and `@vestra-player/sdk/testing` with its documentation, and the complete source of the example plugins. Generated from the SDK's sources by scripts/llms.mjs; the short index is llms.txt.
 
@@ -9096,7 +9096,7 @@ Usually the player plays a file: it decodes the picture and the sound and keeps
 The plugin does not push frames on a timer of its own. **The player pulls them:** the SDK calls `frame()` whenever the player needs more.
 
 - `frame()` is never called twice at the same time, and not at all while the player is paused.
-- It is paced by the **audio clock**. The SDK keeps a little audio queued ahead of the sound card (about 50 ms) and calls `frame()` when the queue runs low.
+- It is paced by the **audio clock**. The SDK keeps a little audio queued ahead of the sound card (about 50 ms). Regularly, several times per frame, it checks how much the sound card has played and calls `frame()` as many times in a row as it takes to fill the queue again: two or three calls back to back are normal, so do not time anything by the gap between calls.
 - It is **synchronous**: it cannot `await`, so everything it needs must already be in memory. If it is slow, the sound drops out.
 
 Each call returns one picture and **the audio that plays while that picture is on screen**. The stream's timeline is its audio: the player plays the samples at 48 000 per second and shows each picture when the audio reaches it. A frame that carries 1600 samples therefore lasts 1600 / 48 000 s = 1/30 s. The number of samples per frame _is_ the frame rate; there is no separate setting.

package/llms.txt

@@ -1,6 +1,6 @@
 # Vestra Player SDK
 
-> @vestra-player/sdk 1.5.26: write plugins for Vestra Player in TypeScript (plugin API `vestra/1`). A plugin is a folder with `manifest.json` and an entry module whose default export `activate(plugin)` the player calls; it runs in its own Node.js process. Everything a plugin creates (commands, windows, panels, filters, listeners…) is a handle that is released automatically when the plugin stops. L<n> are line numbers in llms-full.txt, next to this file: every page, declaration and example.
+> @vestra-player/sdk 1.5.27: write plugins for Vestra Player in TypeScript (plugin API `vestra/1`). A plugin is a folder with `manifest.json` and an entry module whose default export `activate(plugin)` the player calls; it runs in its own Node.js process. Everything a plugin creates (commands, windows, panels, filters, listeners…) is a handle that is released automatically when the plugin stops. L<n> are line numbers in llms-full.txt, next to this file: every page, declaration and example.
 
 **Rules**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vestra-player/sdk",
-  "version": "1.5.26",
+  "version": "1.5.27",
   "description": "Plugin API types, test host and plugin CLI for Vestra Player (apiVersion vestra/1)",
   "license": "Apache-2.0",
   "repository": {