@vestra-player/sdk 1.5.37 → 1.5.39

package/dist/plugin/testing.d.ts

@@ -15,6 +15,7 @@ import { IMAGE_LIMITS, UI_VALUE_LIMITS } from "./values.ts";
 import type { CommandDeclaration } from "../commands.ts";
 import type { SourceState } from "../source.ts";
 import type { SubtitleState } from "../subtitles.ts";
+import { VIDEO_PROCESSING_LIMITS } from "../processing.ts";
 import type { RenderingMode, RenderingPreference, RenderingReason, RenderSettings, UpscalingReason, ViewSettings } from "./types.ts";
 import type { MediaJob } from "../media.ts";
 import type { LanguagePreference, Locale, Plugin, TemplateArgs, TextValue, ThemeId } from "./types.ts";
@@ -41,6 +42,8 @@ export { SECRET_LIMITS };
 export { SESSION_STORAGE_LIMITS };
 /** The player's limits on loaded subtitle files, which the test host enforces as well. */
 export { SUBTITLE_LIMITS };
+/** The player's bounds on convolution, lut3d and shader-channel requests, which the test host enforces as well. */
+export { VIDEO_PROCESSING_LIMITS };
 /** The names bindings are made of. */
 export { BINDING_INPUTS };
 /** The colours of the player's palettes, by `Theme` token. */
@@ -535,6 +538,16 @@ export declare class TestHost implements Transport {
     readonly calls: Call[];
     /** The host events the plugin subscribed to (needs `events` etc.). */
     readonly subscriptions: Set<string>;
+    /**
+     * The subscribed events the plugin really listens to: an `onChange` and
+     * the like, or a binding that reads the state. The SDK's own copies of
+     * the state (what keeps `plugin.player.state` current) are left out.
+     * Empty means the player may stop the plugin while nothing uses it
+     * (unless it holds something else: a window, a panel, a filter…).
+     *
+     * @since 1.5.38
+     */
+    readonly listening: Set<string>;
     /**
      * The player's source facts (phase, position, duration, paused, rate,
      * audio tracks, loop, ...). Wire-level shape; change it with
@@ -1331,6 +1344,64 @@ export declare class TestHost implements Transport {
      * @since 1.0.0
      */
     failVideoRender(code: "failed" | "unsupported", message: string): void;
+    /**
+     * The shader channel (`plugin.video.shaders(id)`, SDK 1.5.39): the lists
+     * the player holds for this plugin's handles by id (the real paths, after
+     * following links), and how many shaders other plugins hold, which count
+     * against {@link VIDEO_PROCESSING_LIMITS}`.shaders` (`limit`). Files must
+     * be under {@link TestHost.fileRoots}; under software rendering
+     * (`videoRender.gpu = false`) a non-empty list fails with `unsupported`.
+     *
+     * @since 1.5.39
+     */
+    readonly videoShaders: {
+        /** This plugin's lists by handle id; a cleared handle has none. */
+        handles: Map<string, string[]>;
+        /** Shaders other plugins hold (0–16). */
+        others: number;
+    };
+    /**
+     * Where the plugin's own files may be: its package directory and its
+     * data directory ({@link startPlugin} sets both when the list is still
+     * empty). `lut3d` files and shader-channel files outside them fail with
+     * `invalid`, as in the player.
+     *
+     * @since 1.5.39
+     */
+    fileRoots: string[];
+    /**
+     * What the player pushes to a shader handle when mpv cannot compile a
+     * shader (code `failed`; the player cannot tell whose shader failed, so
+     * every handle with shaders hears it) or the player switches to software
+     * rendering (`unsupported`; use {@link TestHost.failVideoRender}, which
+     * also tells the handles). Pushed only to a handle that holds shaders.
+     *
+     * @capability None.
+     *
+     * @example Make the plugin's shader fail to compile
+     * The plugin's shader handle reports `failed`, as when mpv rejects a
+     * shader. The host pushes the failure only to a handle that holds
+     * shaders, which its accepted `set` made it; the SDK updates the
+     * handle's `status` when the push arrives, so the test settles first.
+     * ```ts
+     * import assert from "node:assert/strict";
+     * import { join } from "node:path";
+     * import { writeFileSync } from "node:fs";
+     * declare const host: TestHost;
+     * // ---cut---
+     * const file = join(plugin.dataDirectory, "sharpen.glsl");
+     * writeFileSync(file, "//!HOOK MAIN\n");
+     * const shaders = plugin.video.shaders("sharpen");
+     * shaders.set([file]); // the handle now holds a shader
+     * await host.settle();
+     * host.failVideoShaders("sharpen", "shader compile failed: ERROR: 0:3: ...");
+     * await host.settle();
+     * assert.equal(shaders.status.state, "failed");
+     * ```
+     *
+     * @since 1.5.39
+     */
+    failVideoShaders(id: string, message: string): void;
     /**
      * The player's processing (filter) state. Wire-level; may change in minor
      * versions. `resources` holds each `video.filter` / `audio.filter` chain the
@@ -1671,9 +1742,9 @@ export declare class TestHost implements Transport {
      * import activate from "../main.ts";
      *
      * const host = new TestHost();
-     * host.videoRender.gpu = false; // software draws now (Windows)
+     * host.videoRender.gpu = false; // software draws now (Linux)
      * host.rendering.startedWith = "software";
-     * host.rendering.reason = { code: "no-gpu-backend", message: "No GPU renderer on Windows" };
+     * host.rendering.reason = { code: "no-gpu-backend", message: "this player has no GPU renderer on Linux yet" };
      * host.rendering.gpu = { available: false, reason: host.rendering.reason };
      * const { stop } = await startPlugin(activate, {
      *   directory: new URL("..", import.meta.url),
@@ -1681,7 +1752,7 @@ export declare class TestHost implements Transport {
      * });
      * const item = host.command("gpu-rendering");
      * assert.equal(item.state.enabled, false);
-     * assert.equal(item.state.reason, "No GPU renderer on Windows");
+     * assert.equal(item.state.reason, "this player has no GPU renderer on Linux yet");
      * await stop();
      * ```
      *

package/dist/plugin/testing.js

@@ -64,12 +64,12 @@
  * @packageDocumentation
  * @module @vestra-player/sdk/testing
  */
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, openSync, readFileSync, readSync, closeSync, realpathSync, } from "node:fs";
 import { mkdirSync, mkdtempSync, rmSync, statSync } from "node:fs";
 import { createServer } from "node:net";
 import { randomBytes } from "node:crypto";
 import { tmpdir } from "node:os";
-import { extname, isAbsolute, join } from "node:path";
+import { extname, isAbsolute, join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
 import { HostError } from "../wire.js";
 import { localSocketPath } from "./local.js";
@@ -82,7 +82,8 @@ import { BINDING_INPUTS } from "./bindings.js";
 import { THEME_PALETTES } from "../palettes.js";
 import { IMAGE_LIMITS, UI_VALUE_LIMITS, valueLimitProblem } from "./values.js";
 import { validStep } from "./player.js";
-import { nodeProblem } from "../processing.js";
+import { nodeProblem, VIDEO_PROCESSING_LIMITS } from "../processing.js";
+import { shaderIdProblem, shaderListProblem } from "./shaders.js";
 import { RENDER_DEFAULTS, renderProblem, VIEW_DEFAULTS, viewProblem, } from "./view.js";
 import { createPlugin } from "./index.js";
 import { THEMES } from "./appearance.js";
@@ -107,6 +108,8 @@ export { SECRET_LIMITS };
 export { SESSION_STORAGE_LIMITS };
 /** The player's limits on loaded subtitle files, which the test host enforces as well. */
 export { SUBTITLE_LIMITS };
+/** The player's bounds on convolution, lut3d and shader-channel requests, which the test host enforces as well. */
+export { VIDEO_PROCESSING_LIMITS };
 /** The names bindings are made of. */
 export { BINDING_INPUTS };
 /** The colours of the player's palettes, by `Theme` token. */
@@ -188,6 +191,70 @@ const sessionCost = (key, value) => Buffer.byteLength(key) +
     SESSION_STORAGE_LIMITS.entryBytes;
 const kebab = (name) => name.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);
 const tick = () => new Promise((resolve) => setImmediate(resolve));
+/**
+ * The player's `playback/plugin_files.rs`: a file the plugin names for its
+ * video processing is an absolute path inside one of `roots` after
+ * following links, a regular file of at most `max` bytes. Returns the real
+ * path or throws the player's error.
+ */
+function ownFile(path, roots, what, max) {
+    if (!isAbsolute(path))
+        throw new HostError("invalid", `${what} path must be absolute: ${path}`);
+    let real;
+    try {
+        real = realpathSync(path);
+    }
+    catch {
+        throw new HostError("missing", `${what} not found: ${path}`);
+    }
+    const inside = roots.some((root) => {
+        let base;
+        try {
+            base = realpathSync(root);
+        }
+        catch {
+            return false;
+        }
+        const rel = relative(base, real);
+        return rel === "" || (!/^\.\.([\\/]|$)/.test(rel) && !isAbsolute(rel));
+    });
+    if (!inside)
+        throw new HostError("invalid", `${what} must be in the plugin's package or data directory: ${path}`);
+    const stat = statSync(real);
+    if (!stat.isFile())
+        throw new HostError("invalid", `${what} is not a file: ${path}`);
+    if (stat.size > max)
+        throw new HostError("invalid", `${what} is larger than ${max / 1024 / 1024} MiB: ${path}`);
+    return real;
+}
+/** The `LUT_3D_SIZE` check of `plugin_files::lut` on the first 64 KiB. */
+function cubeProblem(file) {
+    const buffer = Buffer.alloc(64 * 1024);
+    const fd = openSync(file, "r");
+    let read;
+    try {
+        read = readSync(fd, buffer, 0, buffer.length, 0);
+    }
+    finally {
+        closeSync(fd);
+    }
+    for (const line of buffer.subarray(0, read).toString("utf8").split("\n")) {
+        const [word, value] = line.trim().split(/\s+/);
+        if (word === "LUT_3D_SIZE") {
+            const size = Number(value);
+            return Number.isInteger(size) &&
+                size >= 2 &&
+                size <= VIDEO_PROCESSING_LIMITS.lutSize
+                ? null
+                : `LUT_3D_SIZE must be 2 to ${VIDEO_PROCESSING_LIMITS.lutSize}`;
+        }
+        if (word === "LUT_1D_SIZE")
+            return "a 1D LUT; lut3d needs LUT_3D_SIZE";
+        if (word !== undefined && word !== "" && Number.isFinite(Number(word)))
+            break;
+    }
+    return "no LUT_3D_SIZE line before the data";
+}
 function initialSource() {
     return {
         kind: "media",
@@ -333,6 +400,16 @@ export class TestHost {
     calls = [];
     /** The host events the plugin subscribed to (needs `events` etc.). */
     subscriptions = new Set();
+    /**
+     * The subscribed events the plugin really listens to: an `onChange` and
+     * the like, or a binding that reads the state. The SDK's own copies of
+     * the state (what keeps `plugin.player.state` current) are left out.
+     * Empty means the player may stop the plugin while nothing uses it
+     * (unless it holds something else: a window, a panel, a filter…).
+     *
+     * @since 1.5.38
+     */
+    listening = new Set();
     /**
      * The player's source facts (phase, position, duration, paused, rate,
      * audio tracks, loop, ...). Wire-level shape; change it with
@@ -1301,6 +1378,78 @@ export class TestHost {
                 state: "failed",
                 error: { code, message },
             });
+        // The player tells every shader handle too (`failVideoShaders`).
+        // and, like the player, removes their lists.
+        if (code === "unsupported") {
+            for (const [id, paths] of this.videoShaders.handles)
+                if (paths.length > 0)
+                    this.emit("video.shaders.status", {
+                        id,
+                        state: "failed",
+                        error: { code, message },
+                    });
+            this.videoShaders.handles.clear();
+        }
+    }
+    /**
+     * The shader channel (`plugin.video.shaders(id)`, SDK 1.5.39): the lists
+     * the player holds for this plugin's handles by id (the real paths, after
+     * following links), and how many shaders other plugins hold, which count
+     * against {@link VIDEO_PROCESSING_LIMITS}`.shaders` (`limit`). Files must
+     * be under {@link TestHost.fileRoots}; under software rendering
+     * (`videoRender.gpu = false`) a non-empty list fails with `unsupported`.
+     *
+     * @since 1.5.39
+     */
+    videoShaders = { handles: new Map(), others: 0 };
+    /**
+     * Where the plugin's own files may be: its package directory and its
+     * data directory ({@link startPlugin} sets both when the list is still
+     * empty). `lut3d` files and shader-channel files outside them fail with
+     * `invalid`, as in the player.
+     *
+     * @since 1.5.39
+     */
+    fileRoots = [];
+    /**
+     * What the player pushes to a shader handle when mpv cannot compile a
+     * shader (code `failed`; the player cannot tell whose shader failed, so
+     * every handle with shaders hears it) or the player switches to software
+     * rendering (`unsupported`; use {@link TestHost.failVideoRender}, which
+     * also tells the handles). Pushed only to a handle that holds shaders.
+     *
+     * @capability None.
+     *
+     * @example Make the plugin's shader fail to compile
+     * The plugin's shader handle reports `failed`, as when mpv rejects a
+     * shader. The host pushes the failure only to a handle that holds
+     * shaders, which its accepted `set` made it; the SDK updates the
+     * handle's `status` when the push arrives, so the test settles first.
+     * ```ts
+     * import assert from "node:assert/strict";
+     * import { join } from "node:path";
+     * import { writeFileSync } from "node:fs";
+     * declare const host: TestHost;
+     * // ---cut---
+     * const file = join(plugin.dataDirectory, "sharpen.glsl");
+     * writeFileSync(file, "//!HOOK MAIN\n");
+     * const shaders = plugin.video.shaders("sharpen");
+     * shaders.set([file]); // the handle now holds a shader
+     * await host.settle();
+     * host.failVideoShaders("sharpen", "shader compile failed: ERROR: 0:3: ...");
+     * await host.settle();
+     * assert.equal(shaders.status.state, "failed");
+     * ```
+     *
+     * @since 1.5.39
+     */
+    failVideoShaders(id, message) {
+        if ((this.videoShaders.handles.get(id)?.length ?? 0) > 0)
+            this.emit("video.shaders.status", {
+                id,
+                state: "failed",
+                error: { code: "failed", message },
+            });
     }
     /**
      * The player's processing (filter) state. Wire-level; may change in minor
@@ -1600,9 +1749,9 @@ export class TestHost {
      * import activate from "../main.ts";
      *
      * const host = new TestHost();
-     * host.videoRender.gpu = false; // software draws now (Windows)
+     * host.videoRender.gpu = false; // software draws now (Linux)
      * host.rendering.startedWith = "software";
-     * host.rendering.reason = { code: "no-gpu-backend", message: "No GPU renderer on Windows" };
+     * host.rendering.reason = { code: "no-gpu-backend", message: "this player has no GPU renderer on Linux yet" };
      * host.rendering.gpu = { available: false, reason: host.rendering.reason };
      * const { stop } = await startPlugin(activate, {
      *   directory: new URL("..", import.meta.url),
@@ -1610,7 +1759,7 @@ export class TestHost {
      * });
      * const item = host.command("gpu-rendering");
      * assert.equal(item.state.enabled, false);
-     * assert.equal(item.state.reason, "No GPU renderer on Windows");
+     * assert.equal(item.state.reason, "this player has no GPU renderer on Linux yet");
      * await stop();
      * ```
      *
@@ -3377,8 +3526,18 @@ export class TestHost {
         };
     }
     #defaults = {
-        "events.subscribe": (p) => void this.subscriptions.add(String(p.event)),
-        "events.unsubscribe": (p) => void this.subscriptions.delete(String(p.event)),
+        "events.subscribe": (p) => {
+            const event = String(p.event);
+            this.subscriptions.add(event);
+            if (p.mirror === true)
+                this.listening.delete(event);
+            else
+                this.listening.add(event);
+        },
+        "events.unsubscribe": (p) => {
+            this.subscriptions.delete(String(p.event));
+            this.listening.delete(String(p.event));
+        },
         "commands.register": (p) => {
             const id = String(p.id);
             // The player's built-in menu ids (MENU_IDS) in the first path segment.
@@ -3965,6 +4124,34 @@ export class TestHost {
                 this.setVideoRenderOwner(null);
             return null;
         },
+        // The player's capability layer and `video_shaders.rs`.
+        "video.shaders.set": (p) => {
+            const idProblem = shaderIdProblem(p.id);
+            if (idProblem)
+                throw new HostError("invalid", idProblem);
+            if (!Array.isArray(p.paths) ||
+                p.paths.some((path) => typeof path !== "string"))
+                throw new HostError("invalid", "paths must be an array of paths");
+            const id = p.id;
+            const list = p.paths;
+            const listProblem = shaderListProblem(list);
+            if (listProblem?.startsWith("at most"))
+                throw new HostError("limit", listProblem);
+            const paths = list.map((path) => ownFile(path, this.fileRoots, "shader", VIDEO_PROCESSING_LIMITS.shaderBytes));
+            if (paths.length > 0 && !this.videoRender.gpu)
+                throw new HostError("unsupported", "shaders need GPU rendering; the player renders in software");
+            const mine = [...this.videoShaders.handles]
+                .filter(([other]) => other !== id)
+                .reduce((sum, [, held]) => sum + held.length, 0);
+            const others = mine + this.videoShaders.others;
+            if (others + paths.length > VIDEO_PROCESSING_LIMITS.shaders)
+                throw new HostError("limit", `at most ${VIDEO_PROCESSING_LIMITS.shaders} shaders across all plugins: ${others} are in use, this list has ${paths.length}`);
+            if (paths.length > 0)
+                this.videoShaders.handles.set(id, paths);
+            else
+                this.videoShaders.handles.delete(id);
+            return { state: this.source.phase === "ready" ? "applied" : "waiting" };
+        },
         "timeline.set": (p) => {
             if (p.sourceId !== undefined &&
                 p.sourceId !== this.source.stamp.generation)
@@ -4192,6 +4379,30 @@ export class TestHost {
                     status: "failed",
                     error: { code: "invalid", message: (problem ?? blend ?? delay) },
                 });
+            // `lut3d` files: the plugin's own `.cube` files (`plugin_files.rs`).
+            if (stage === "video")
+                for (const node of (p.nodes ?? []))
+                    if (node.kind === "lut3d") {
+                        let cube;
+                        try {
+                            const real = ownFile(node.file, this.fileRoots, "lut3d file", VIDEO_PROCESSING_LIMITS.lutBytes);
+                            cube = /\.cube$/i.test(real)
+                                ? cubeProblem(real)
+                                : "lut3d file must be a .cube file";
+                        }
+                        catch (error) {
+                            const { code, message } = error;
+                            return finish({ status: "failed", error: { code, message } });
+                        }
+                        if (cube)
+                            return finish({
+                                status: "failed",
+                                error: {
+                                    code: "invalid",
+                                    message: `lut3d file ${node.file}: ${cube}`,
+                                },
+                            });
+                    }
             if (this.source.phase !== "ready")
                 return finish({
                     status: "failed",
@@ -4824,6 +5035,8 @@ export async function startPlugin(activate, options = {}) {
     for (const [key, value] of options.sessionStorage ?? [])
         host.sessionStorage.set(key, sortedJson(value));
     mkdirSync(data, { recursive: true });
+    if (host.fileRoots.length === 0)
+        host.fileRoots = [directory, data];
     const instance = await createPlugin(host, manifest, directory, data, host.app);
     await activate(instance.plugin);
     // Like the player: a position or resolver another plugin holds is not an

package/dist/plugin/timeline.d.ts

@@ -16,7 +16,7 @@ export declare class TimelineService {
     accept(marks: WireMark[]): void;
     read(): Promise<void>;
     watch(listener: (marks: readonly TimelineMark[]) => void): {
-        dispose: () => Promise<undefined>;
+        dispose: () => Promise<void>;
     };
 }
 export declare const timelineOf: (runtime: Runtime) => TimelineService;

package/dist/plugin/timeline.js

@@ -27,13 +27,14 @@ export class TimelineService {
         if (this.#started)
             return;
         this.#started = true;
+        // A mirror: a plugin listens through `watch` and bindings.
         this.#runtime.on("timeline.changed", (data) => {
             const marks = data?.marks;
             if (Array.isArray(marks))
                 this.accept(marks);
             else
                 void this.read();
-        });
+        }, "events", true);
     }
     accept(marks) {
         const next = view(marks);
@@ -51,7 +52,13 @@ export class TimelineService {
     }
     watch(listener) {
         this.#listeners.add(listener);
-        return { dispose: async () => void this.#listeners.delete(listener) };
+        const held = this.#runtime.hold("timeline.changed");
+        return {
+            dispose: async () => {
+                this.#listeners.delete(listener);
+                await held.dispose();
+            },
+        };
     }
 }
 export const timelineOf = (runtime) => runtime.service("timeline", () => new TimelineService(runtime));
@@ -60,6 +67,7 @@ export function timeline(scope) {
     return {
         get marks() {
             service().start();
+            scope.runtime.reading("timeline.changed");
             return service().marks;
         },
         onChange(listener) {