@vestra-player/sdk 1.5.25 → 1.5.27

package/dist/capability-rules.js

@@ -0,0 +1,132 @@
+/**
+ * The capability rule, as data: which manifest capability a request needs
+ * (the player's table, `HOST_CAPABILITIES`, synced from its
+ * `src/host/capabilities.json`) and which requests each public member of the
+ * plugin API sends (`API_REQUESTS`). `CAPABILITY_INFO`, `vestra-plugin check`
+ * and the TypeScript language-service plugin are all built from these two
+ * tables, so they and the player cannot disagree.
+ *
+ * @internal
+ */
+import { API_REQUESTS } from "./api-requests.js";
+import { HOST_CAPABILITIES } from "./host-capabilities.js";
+/** @internal The SDK's rules: the synced player table and `API_REQUESTS`. */
+export const RULES = {
+    host: HOST_CAPABILITIES,
+    apis: API_REQUESTS,
+};
+/**
+ * The player's entry for a method, as the player routes it: the exact name
+ * first, then the first `prefix.*` entry whose prefix it starts with.
+ * `undefined`: the player does not know the method.
+ *
+ * @internal
+ */
+export function hostMethod(method, host = RULES.host) {
+    const all = [
+        ...host.capabilities.flatMap((capability) => capability.methods),
+        ...host.uncapable,
+    ];
+    return (all.find((entry) => entry.name === method) ??
+        all.find((entry) => entry.name.endsWith(".*") && method.startsWith(entry.name.slice(0, -1))));
+}
+/**
+ * The capability one request needs, as the player decides it
+ * (`capabilities::Route::needs`): `null` for none, `undefined` for a method
+ * the player does not know.
+ *
+ * @param method - The wire method.
+ * @param params - Its string parameters that a `Needs::Param` rule reads.
+ * @param declared - Whether the plugin declared a capability.
+ *
+ * @internal
+ */
+export function requestNeeds(method, params, declared, host = RULES.host) {
+    const entry = hostMethod(method, host);
+    if (!entry)
+        return undefined;
+    const needs = entry.needs;
+    if (needs === null || typeof needs === "string")
+        return needs;
+    if ("param" in needs) {
+        const value = params?.[needs.param];
+        return value !== undefined && Object.hasOwn(needs.cases, value)
+            ? needs.cases[value]
+            : needs.otherwise;
+    }
+    return declared(needs.ifDeclared) ? needs.then : needs.otherwise;
+}
+/**
+ * Every capability a member of the plugin API needs with the given manifest:
+ * those its requests need and, through `requires`, those they need in turn.
+ * `undefined`: the member is not in the table (it needs none).
+ *
+ * @param api - The member as `Interface.member` (`Player.seek`).
+ * @param capabilities - The manifest's capabilities.
+ *
+ * @internal
+ */
+export function memberNeeds(api, capabilities, rules = RULES) {
+    const requests = rules.apis[api];
+    if (!requests)
+        return undefined;
+    // An `ifDeclared` rule is decided last, as if the plugin had declared what
+    // the member's other requests need: `Player.seek` needs `playback.control`
+    // for `source.submit`, and with it `source.operation` needs nothing more.
+    const declared = (name) => capabilities.includes(name) ||
+        needs.some((need) => need.capability === name);
+    const conditional = (request) => {
+        const rule = hostMethod(request.method, rules.host)?.needs;
+        return typeof rule === "object" && rule !== null && "ifDeclared" in rule;
+    };
+    const needs = [];
+    const add = (need) => {
+        if (needs.some((each) => each.capability === need.capability))
+            return;
+        needs.push(need);
+        const entry = rules.host.capabilities.find((capability) => capability.name === need.capability);
+        for (const required of entry?.requires ?? [])
+            add({
+                capability: required,
+                method: need.method,
+                requiredBy: need.capability,
+            });
+    };
+    for (const request of [
+        ...requests.filter((request) => !conditional(request)),
+        ...requests.filter(conditional),
+    ]) {
+        const capability = requestNeeds(request.method, request.params, declared, rules.host);
+        if (capability)
+            add({ capability, method: request.method });
+    }
+    return needs;
+}
+/**
+ * `CAPABILITY_INFO` from the tables: the label, highlight and requirements
+ * from the player's table; the members from `API_REQUESTS` (every member a
+ * request of which needs the capability, in the table's order; requests
+ * marked `also` are left out, as they are documented at the member).
+ *
+ * @internal
+ */
+export function capabilityInfo(rules = RULES) {
+    const info = {};
+    for (const capability of rules.host.capabilities)
+        info[capability.name] = {
+            apis: [],
+            requires: [...capability.requires],
+            label: capability.label,
+            risky: capability.risky,
+        };
+    for (const [api, requests] of Object.entries(rules.apis))
+        for (const request of requests) {
+            if (request.also)
+                continue;
+            const capability = requestNeeds(request.method, request.params, () => true, rules.host);
+            const entry = capability ? info[capability] : undefined;
+            if (entry && !entry.apis.includes(api))
+                entry.apis.push(api);
+        }
+    return info;
+}

package/dist/host-capabilities.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The player's capability table, copied from its `src/host/capabilities.json`
+ * by `npm run capabilities:sync -- <player repository>`. Do not edit: change
+ * the player's capability modules, regenerate its JSON and sync again.
+ *
+ * @internal
+ */
+import type { HostCapabilities } from "./capability-rules.ts";
+/** @internal */
+export declare const HOST_CAPABILITIES: HostCapabilities;

package/dist/host-capabilities.js

@@ -0,0 +1,360 @@
+// "then" is a field of the player's IfDeclared rule, not a thenable.
+/* oxlint-disable unicorn/no-thenable */
+/** @internal */
+export const HOST_CAPABILITIES = {
+    about: "Generated from src/host/src/capabilities/ (VESTRA_UPDATE_CAPABILITIES=1 cargo test capabilities); do not edit. A method's needs: null (none), a capability name, {param, cases, otherwise} (by a string parameter) or {ifDeclared, then, otherwise}. A method name ending in .* covers the prefix's other methods.",
+    apiVersion: "vestra/1",
+    capabilities: [
+        {
+            label: "Provide audio and video it generates itself",
+            methods: [
+                { name: "producer.prepare", needs: "producer.av" },
+                { name: "producer.state", needs: "producer.av" },
+                { name: "producer.release", needs: "producer.av" },
+                { name: "producer.ack", needs: "producer.av" },
+                { name: "producer.declareInput", needs: "producer.av" },
+                { name: "producer.ackInput", needs: "producer.av" },
+            ],
+            name: "producer.av",
+            requires: ["playback.control"],
+            residency: "live",
+            risky: false,
+        },
+        {
+            label: "Read what is playing and the position",
+            methods: [
+                { name: "source.state", needs: "playback.read" },
+                { name: "processing.state", needs: "playback.read" },
+                { name: "playback.stats", needs: "playback.read" },
+                { name: "player.chapters", needs: "playback.read" },
+                { name: "player.audioDevices", needs: "playback.read" },
+                { name: "timeline.marks", needs: "playback.read" },
+            ],
+            name: "playback.read",
+            requires: [],
+            residency: "none",
+            risky: false,
+        },
+        {
+            label: "Open media, control playback, keep the computer awake",
+            methods: [
+                { name: "playback.set", needs: "playback.control" },
+                { name: "source.submit", needs: "playback.control" },
+                {
+                    name: "source.operation",
+                    needs: {
+                        ifDeclared: "playback.control",
+                        otherwise: "playback.read",
+                        then: "playback.control",
+                    },
+                },
+                { name: "audio.addTrack", needs: "playback.control" },
+                { name: "audio.selectTrack", needs: "playback.control" },
+                { name: "player.setLoop", needs: "playback.control" },
+                { name: "player.setAudioDevice", needs: "playback.control" },
+                { name: "player.step", needs: "playback.control" },
+                { name: "player.setStepSeek", needs: "playback.control" },
+                { name: "power.preventSleep", needs: "playback.control" },
+                { name: "sequence.set", needs: "playback.control" },
+                { name: "sequence.step", needs: "playback.control" },
+            ],
+            name: "playback.control",
+            requires: [],
+            residency: "live",
+            risky: false,
+        },
+        {
+            label: "Resolve online video addresses",
+            methods: [
+                { name: "sourceResolvers.register", needs: "source.resolve" },
+                { name: "sourceResolvers.unregister", needs: "source.resolve" },
+                { name: "sourceResolvers.respond", needs: "source.resolve" },
+                { name: "sourceResolvers.*", needs: "source.resolve" },
+            ],
+            name: "source.resolve",
+            requires: [],
+            residency: "recordable",
+            risky: false,
+        },
+        {
+            label: "Receive playback changes as they happen",
+            methods: [
+                {
+                    name: "events.subscribe",
+                    needs: {
+                        cases: {
+                            "bindings.changed": "bindings.manage",
+                            "packages.changed": null,
+                        },
+                        otherwise: "events",
+                        param: "event",
+                    },
+                },
+                {
+                    name: "events.unsubscribe",
+                    needs: {
+                        cases: {
+                            "bindings.changed": "bindings.manage",
+                            "packages.changed": null,
+                        },
+                        otherwise: "events",
+                        param: "event",
+                    },
+                },
+            ],
+            name: "events",
+            requires: [],
+            residency: "live",
+            risky: false,
+        },
+        {
+            label: "Add menu commands and shortcuts",
+            methods: [
+                { name: "commands.register", needs: "commands" },
+                { name: "commands.update", needs: "commands" },
+                { name: "commands.unregister", needs: "commands" },
+                { name: "host.run", needs: "commands" },
+            ],
+            name: "commands",
+            requires: [],
+            residency: "recordable",
+            risky: false,
+        },
+        {
+            label: "Open tool windows",
+            methods: [
+                { name: "ui.open", needs: "ui.window" },
+                { name: "ui.set", needs: "ui.window" },
+                { name: "ui.show", needs: "ui.window" },
+                { name: "ui.close", needs: "ui.window" },
+            ],
+            name: "ui.window",
+            requires: [],
+            residency: "live",
+            risky: false,
+        },
+        {
+            label: "Show panels in the bottom bar, the sidebar or behind the video",
+            methods: [
+                { name: "ui.mount", needs: "ui.mount" },
+                { name: "ui.setMount", needs: "ui.mount" },
+                { name: "ui.unmount", needs: "ui.mount" },
+                { name: "ui.interaction", needs: "ui.mount" },
+                { name: "ui.menu", needs: "ui.mount" },
+                { name: "layout.state", needs: "ui.mount" },
+                { name: "layout.set", needs: "ui.mount" },
+            ],
+            name: "ui.mount",
+            requires: [],
+            residency: "live",
+            risky: false,
+        },
+        {
+            label: "Show file pickers and confirmations",
+            methods: [
+                { name: "dialogs.open", needs: "ui.dialog" },
+                { name: "dialogs.confirm", needs: "ui.dialog" },
+            ],
+            name: "ui.dialog",
+            requires: [],
+            residency: "none",
+            risky: false,
+        },
+        {
+            label: "Install, uninstall and disable other plugins",
+            methods: [{ name: "packages.*", needs: "plugins.manage" }],
+            name: "plugins.manage",
+            requires: [],
+            residency: "none",
+            risky: true,
+        },
+        {
+            label: "Process the picture (filters, shaders)",
+            methods: [
+                {
+                    name: "processing.replace",
+                    needs: {
+                        cases: { video: "processing.video" },
+                        otherwise: "processing.audio",
+                        param: "stage",
+                    },
+                },
+                {
+                    name: "processing.operation",
+                    needs: {
+                        cases: { video: "processing.video" },
+                        otherwise: "processing.audio",
+                        param: "stage",
+                    },
+                },
+                { name: "video.view.set", needs: "processing.video" },
+                { name: "video.view.release", needs: "processing.video" },
+                { name: "video.render.set", needs: "processing.video" },
+                { name: "video.render.release", needs: "processing.video" },
+            ],
+            name: "processing.video",
+            requires: ["playback.read"],
+            residency: "live",
+            risky: false,
+        },
+        {
+            label: "Process the sound",
+            methods: [],
+            name: "processing.audio",
+            requires: ["playback.read", "events"],
+            residency: "live",
+            risky: false,
+        },
+        {
+            label: "Read subtitles",
+            methods: [{ name: "subtitles.state", needs: "subtitles.read" }],
+            name: "subtitles.read",
+            requires: [],
+            residency: "none",
+            risky: false,
+        },
+        {
+            label: "Load and change subtitles",
+            methods: [{ name: "subtitles.*", needs: "subtitles.control" }],
+            name: "subtitles.control",
+            requires: [],
+            residency: "live",
+            risky: false,
+        },
+        {
+            label: "Take snapshots and export clips",
+            methods: [
+                { name: "snapshot.state", needs: "media.read" },
+                { name: "jobs.state", needs: "media.read" },
+                { name: "jobs.operation", needs: "media.read" },
+            ],
+            name: "media.read",
+            requires: ["media.control"],
+            residency: "none",
+            risky: false,
+        },
+        {
+            label: "Take snapshots and export clips",
+            methods: [
+                { name: "snapshot.*", needs: "media.control" },
+                { name: "jobs.*", needs: "media.control" },
+            ],
+            name: "media.control",
+            requires: ["media.read"],
+            residency: "live",
+            risky: false,
+        },
+        {
+            label: "Show messages on the video",
+            methods: [
+                { name: "osd.show", needs: "ui.osd" },
+                { name: "osd.panel", needs: "ui.osd" },
+            ],
+            name: "ui.osd",
+            requires: [],
+            residency: "live",
+            risky: false,
+        },
+        {
+            label: "Read and write the clipboard",
+            methods: [
+                { name: "clipboard.readText", needs: "clipboard" },
+                { name: "clipboard.writeText", needs: "clipboard" },
+                { name: "clipboard.writeImage", needs: "clipboard" },
+            ],
+            name: "clipboard",
+            requires: [],
+            residency: "none",
+            risky: true,
+        },
+        {
+            label: "Adjust the main window (size, on top, picture-in-picture)",
+            methods: [
+                { name: "window.setVideoArea", needs: "window.control" },
+                { name: "window.setAlwaysOnTop", needs: "window.control" },
+                { name: "window.setCursorAutoHide", needs: "window.control" },
+                { name: "window.setPictureInPicture", needs: "window.control" },
+            ],
+            name: "window.control",
+            requires: [],
+            residency: "live",
+            risky: false,
+        },
+        {
+            label: "Change all shortcuts",
+            methods: [
+                { name: "bindings.list", needs: "bindings.manage" },
+                { name: "bindings.set", needs: "bindings.manage" },
+                { name: "bindings.reset", needs: "bindings.manage" },
+            ],
+            name: "bindings.manage",
+            requires: [],
+            residency: "none",
+            risky: true,
+        },
+        {
+            label: "Show marks on the progress bar",
+            methods: [{ name: "timeline.set", needs: "timeline.marks" }],
+            name: "timeline.marks",
+            requires: [],
+            residency: "live",
+            risky: false,
+        },
+        {
+            label: "Receive files dropped on the player",
+            methods: [
+                { name: "drops.provide", needs: "ui.drop" },
+                { name: "drops.withdraw", needs: "ui.drop" },
+                { name: "drops.listen", needs: "ui.drop" },
+            ],
+            name: "ui.drop",
+            requires: [],
+            residency: "recordable",
+            risky: false,
+        },
+        {
+            label: "Add pages to the Options window",
+            methods: [{ name: "settings.*", needs: "ui.settings" }],
+            name: "ui.settings",
+            requires: [],
+            residency: "recordable",
+            risky: false,
+        },
+        {
+            label: "Change the player's palette",
+            methods: [
+                { name: "appearance.set", needs: "ui.theme" },
+                { name: "appearance.setLanguage", needs: "ui.theme" },
+            ],
+            name: "ui.theme",
+            requires: [],
+            residency: "none",
+            risky: false,
+        },
+        {
+            label: "Store sign-in details in the system keychain",
+            methods: [
+                { name: "secrets.get", needs: "secrets" },
+                { name: "secrets.set", needs: "secrets" },
+                { name: "secrets.delete", needs: "secrets" },
+            ],
+            name: "secrets",
+            requires: [],
+            residency: "none",
+            risky: true,
+        },
+    ],
+    uncapable: [
+        { name: "packages.list", needs: null },
+        { name: "window.state", needs: null },
+        { name: "system.reveal", needs: null },
+        { name: "system.openPath", needs: null },
+        { name: "system.openUrl", needs: null },
+        { name: "app.system", needs: null },
+        { name: "ui.markdownScan", needs: null },
+        { name: "storage.session.get", needs: null },
+        { name: "storage.session.set", needs: null },
+        { name: "storage.session.delete", needs: null },
+        { name: "storage.session.keys", needs: null },
+    ],
+};

package/dist/player-runtime.d.ts

@@ -12,6 +12,7 @@ export type { PluginInstance, PluginManifest } from "./plugin/index.ts";
 export { HostError } from "./wire.ts";
 export type { Json, Transport } from "./wire.ts";
 export { API_VERSION, CAPABILITIES, CAPABILITY_INFO, MESSAGE_LIMIT, } from "./capabilities.ts";
+export { HOST_CAPABILITIES } from "./host-capabilities.ts";
 export { BUILTIN_COMMANDS, BUILTIN_SUBMENUS, COMMAND_LIMITS, MENU_IDS, } from "./commands.ts";
 export { BINDING_INPUTS } from "./plugin/bindings.ts";
 export { OSD_LIMITS } from "./plugin/osd.ts";

package/dist/player-runtime.js

@@ -10,6 +10,7 @@
 export { createPlugin } from "./plugin/index.js";
 export { HostError } from "./wire.js";
 export { API_VERSION, CAPABILITIES, CAPABILITY_INFO, MESSAGE_LIMIT, } from "./capabilities.js";
+export { HOST_CAPABILITIES } from "./host-capabilities.js";
 export { BUILTIN_COMMANDS, BUILTIN_SUBMENUS, COMMAND_LIMITS, MENU_IDS, } from "./commands.js";
 export { BINDING_INPUTS } from "./plugin/bindings.js";
 export { OSD_LIMITS } from "./plugin/osd.js";

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/dist/plugin/types.d.ts

@@ -4390,7 +4390,8 @@ export interface SubtitleConditional {
 }
 /**
  * `plugin.subtitles`: tracks, uploads and style. Reading needs
- * `subtitles.read`, changes need `subtitles.control`.
+ * `subtitles.read`; changes need `subtitles.control` and also
+ * `subtitles.read`, since they read the current selection first.
  *
  * @example Load an SRT file as the secondary subtitle
  * ```ts

package/dist/ts-plugin.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The TypeScript language-service plugin `@vestra-player/sdk/ts-plugin`: the
+ * capability checker of `vestra-plugin check` in the editor. A use of an API
+ * member whose capability `manifest.json` does not declare is an error at
+ * the member, with the quick fix "Add '<capability>' to manifest.json".
+ *
+ * A project enables it in its tsconfig.json:
+ *
+ *   { "compilerOptions": { "plugins": [{ "name": "@vestra-player/sdk/ts-plugin" }] } }
+ *
+ * The editor must run the project's own TypeScript (VS Code: "TypeScript:
+ * Select TypeScript Version" → "Use Workspace Version"); `tsc` ignores
+ * language-service plugins, which is why `vestra-plugin check` runs the same
+ * checker. The manifest is the nearest `manifest.json` above the file; files
+ * in its `tests/`, `node_modules/`, `dist/` and `vendor/` are not checked.
+ *
+ * @internal
+ */
+import type TS from "typescript";
+/** @internal The plugin factory tsserver calls (`ts-plugin/index.js`). */
+export default function init(modules: {
+    typescript: typeof TS;
+}): TS.server.PluginModule;