@vestra-player/sdk 1.5.37 → 1.5.39

package/dist/processing.js

@@ -1,3 +1,53 @@
+/**
+ * Processing chains for the player's video and audio filters. Applied means
+ * the backend accepted the chain, not that a frame with it is visible yet.
+ */
+import { isAbsolute } from "node:path";
+/**
+ * The player's bounds for the video primitives of SDK 1.5.39 (player
+ * 0.5.20): `convolution` and `lut3d` {@link VideoNode}s and the shader
+ * channel (`plugin.video.shaders()`). Values beyond them fail with
+ * `invalid`; more shaders than `shaders` fail with `limit`.
+ *
+ * @example Refuse a shader list the player would not take
+ * The plugin checks a shader list against the player's limit before it
+ * sets it, and says so on the OSD instead of waiting for a `limit` failure.
+ * The limit counts every plugin's shaders, so the player still decides.
+ * ```ts
+ * import type { Plugin } from "@vestra-player/sdk";
+ * declare const plugin: Plugin;
+ * declare const files: string[];
+ * // ---cut---
+ * import { VIDEO_PROCESSING_LIMITS } from "@vestra-player/sdk/testing";
+ *
+ * if (files.length > VIDEO_PROCESSING_LIMITS.shaders)
+ *   void plugin.osd.show("Too many shaders");
+ * else plugin.video.shaders().set(files);
+ * ```
+ *
+ * @since 1.5.39
+ * @category Testing
+ */
+export const VIDEO_PROCESSING_LIMITS = Object.freeze({
+    /** Shaders across every plugin's `plugin.video.shaders()` handles (16). */
+    shaders: 16,
+    /** Bytes of one shader file (16 MiB). */
+    shaderBytes: 16 * 1024 * 1024,
+    /** Bytes of a shader handle's id (128). */
+    shaderIdBytes: 128,
+    /** Bytes of one `lut3d` `.cube` file (16 MiB). */
+    lutBytes: 16 * 1024 * 1024,
+    /** Largest `LUT_3D_SIZE` of a `lut3d` file, points per axis (65). */
+    lutSize: 65,
+    /** Bytes of a `lut3d` file path (4096). */
+    lutPathBytes: 4096,
+    /** Largest magnitude of a `convolution` matrix entry (1024). */
+    matrixValue: 1024,
+    /** Largest `convolution` `rdiv` (256). */
+    rdiv: 256,
+    /** Largest `convolution` `bias` (65535). */
+    bias: 65535,
+});
 const BOOL = [true, false];
 /** Value ranges, the same as the host's `src/host/src/playback/effects.rs` (the host is authoritative). */
 const RULES = {
@@ -25,6 +75,12 @@ const RULES = {
     },
     reframe: { mode: ["crop", "pad"], aspect: [0.25, 4], x: [-1, 1], y: [-1, 1] },
     frameBlend: { fps: [24, 120] },
+    // Checked by `convolutionProblem` / `lutProblem` below.
+    convolution: { planes: [] },
+    lut3d: {
+        file: [],
+        interpolation: ["nearest", "trilinear", "tetrahedral", "pyramid", "prism"],
+    },
     volume: { gainDb: [-60, 0] },
     equalizer: { frequency: [20, 20000], q: [1], gainDb: [-6, 6] },
     treble: { frequency: [3000], slope: [0.5], gainDb: [0, 6] },
@@ -43,7 +99,77 @@ const VIDEO = new Set([
     "deinterlace",
     "reframe",
     "frameBlend",
+    "convolution",
+    "lut3d",
 ]);
+/** `convolution` nodes: the player's rules (`effects.rs ConvolutionPlane`). */
+function convolutionProblem(planes) {
+    if (!Array.isArray(planes) || planes.length < 1 || planes.length > 4)
+        return "convolution planes must have 1 to 4 entries";
+    if (planes.every((plane) => plane === null))
+        return "convolution needs at least one plane with a matrix";
+    const limits = VIDEO_PROCESSING_LIMITS;
+    for (const [index, plane] of planes.entries()) {
+        if (plane === null)
+            continue;
+        if (typeof plane !== "object" || Array.isArray(plane))
+            return `convolution plane ${index} must be an object or null`;
+        const fields = Object.keys(plane);
+        const unknown = fields.find((field) => !["mode", "matrix", "rdiv", "bias"].includes(field));
+        if (unknown)
+            return `convolution plane ${index}: unknown field ${unknown}`;
+        const { mode, matrix, rdiv, bias } = plane;
+        if (!["square", "row", "column"].includes(mode))
+            return `convolution plane ${index}: mode must be square, row or column`;
+        if (!Array.isArray(matrix))
+            return `convolution plane ${index}: matrix must be an array of integers`;
+        const sized = mode === "square"
+            ? [9, 25, 49].includes(matrix.length)
+            : matrix.length % 2 === 1 && matrix.length <= 49;
+        if (!sized)
+            return `convolution plane ${index}: a square matrix has 9, 25 or 49 entries, a row or column an odd number up to 49 (got ${matrix.length})`;
+        if (matrix.some((value) => !Number.isInteger(value) || Math.abs(value) > limits.matrixValue))
+            return `convolution plane ${index}: matrix entries must be integers in -${limits.matrixValue}..${limits.matrixValue}`;
+        const outside = (value, max) => typeof value !== "number" ||
+            !Number.isFinite(value) ||
+            value < 0 ||
+            value > max;
+        if (outside(rdiv, limits.rdiv))
+            return `convolution plane ${index} rdiv must be finite in 0..=${limits.rdiv}`;
+        if (outside(bias, limits.bias))
+            return `convolution plane ${index} bias must be finite in 0..=${limits.bias}`;
+    }
+    return null;
+}
+/**
+ * Whether `text` has a control character as Rust's `char::is_control`
+ * sees one (C0, DEL and C1: U+0000–U+001F, U+007F–U+009F).
+ */
+export function hasControl(text) {
+    return [...text].some((c) => {
+        const code = c.codePointAt(0);
+        return code < 0x20 || (code >= 0x7f && code <= 0x9f);
+    });
+}
+/**
+ * The form of a `lut3d` path (the player's `effects.rs lut_path`); where
+ * the file is and what it holds the player checks when the request arrives
+ * (the test host too, `TestHost.fileRoots`).
+ */
+export function lutPathProblem(file) {
+    const max = VIDEO_PROCESSING_LIMITS.lutPathBytes;
+    if (typeof file !== "string" ||
+        Buffer.byteLength(file) > max ||
+        hasControl(file))
+        return `lut3d file must be a path of at most ${max} bytes without control characters`;
+    if (/[[\]]/.test(file))
+        return "lut3d file path must not contain [ or ]";
+    if (!isAbsolute(file))
+        return "lut3d file must be an absolute path";
+    if (!/\.cube$/i.test(file))
+        return "lut3d file must be a .cube file";
+    return null;
+}
 /**
  * Why `nodes` would be refused (`null` when valid): unknown kinds or fields,
  * values out of range, more than 64 nodes. Used by the test host.
@@ -59,7 +185,20 @@ export function nodeProblem(stage, nodes) {
         for (const field of fields)
             if (!(field in rule))
                 return `${node.kind}: unknown field ${field}`;
+        if (node.kind === "convolution") {
+            const problem = convolutionProblem(node.planes);
+            if (problem)
+                return problem;
+            continue;
+        }
+        if (node.kind === "lut3d") {
+            const problem = lutPathProblem(node.file);
+            if (problem)
+                return problem;
+        }
         for (const [field, allowed] of Object.entries(rule)) {
+            if (allowed.length === 0)
+                continue;
             const value = node[field];
             const ok = allowed.length === 2 &&
                 typeof allowed[0] === "number" &&

package/dist/wire.d.ts

@@ -141,6 +141,8 @@ export interface PackageInfo {
         description: string | null;
         tags: string[];
     };
+    /** Whether it has a process now (player 0.5.18, `state: "running"`). */
+    process?: "running" | "idle";
 }
 /** Where an installed package came from (`packages.install` `source`). */
 export type WireSource = {
@@ -365,6 +367,8 @@ export interface Transport {
      */
     locale?: string;
 }
+/** The events a plugin subscribes to (`events.subscribe`). */
+type HostEvent = "source.state" | "playback.backend" | "window.state" | "packages.changed" | "bindings.changed" | "timeline.changed" | "appearance.changed" | "resolvers.fileTypes";
 export declare function createWire(transport: Transport): {
     processing: {
         state: () => Promise<import("./processing.ts").ProcessingState>;
@@ -477,6 +481,13 @@ export declare function createWire(transport: Transport): {
             state: "applied" | "waiting";
         }>;
         renderRelease: () => Promise<void>;
+        /**
+         * One shader channel handle's list (`plugin.video.shaders(id)`, player
+         * 0.5.20); `[]` removes it.
+         */
+        shadersSet: (id: string, paths: string[]) => Promise<{
+            state: "applied" | "waiting";
+        }>;
         /** The GPU's video upscaler (`plugin.video.upscaling`, player 0.5.16). */
         upscalingState: () => Promise<WireUpscalingState>;
         upscalingSet: (enabled: boolean) => Promise<WireUpscalingState>;
@@ -599,8 +610,19 @@ export declare function createWire(transport: Transport): {
         }) => Promise<void>;
     };
     events: {
-        /** One `events.subscribe` per name however many listeners. */
-        subscribe(event: "source.state" | "playback.backend" | "window.state" | "packages.changed" | "bindings.changed" | "timeline.changed" | "appearance.changed", listener: (data: unknown) => void): Promise<() => Promise<void>>;
+        /**
+         * One `events.subscribe` per name however many listeners. `mirror`:
+         * only the SDK keeps a copy of the state (player 0.5.18; older
+         * players ignore it); `listen` changes it.
+         */
+        subscribe(event: HostEvent, listener: (data: unknown) => void, mirror?: boolean): Promise<() => Promise<void>>;
+        /**
+         * Tell the player whether a subscribed event has a real listener
+         * (`active`) or only the SDK's copy of the state: `events.subscribe`
+         * again, which replaces the mark (player 0.5.18; older players keep
+         * one subscription per name and ignore the mark).
+         */
+        listen: (event: HostEvent, active: boolean) => Promise<void>;
     };
     ui: {
         /** Player 0.2.0: the remote images a Markdown document shows. */

package/dist/wire.js

@@ -138,6 +138,11 @@ export function createWire(transport) {
             /** The GPU renderer's options (`plugin.video.render()`). */
             renderSet: (values) => transport.request("video.render.set", { values }),
             renderRelease: () => transport.request("video.render.release"),
+            /**
+             * One shader channel handle's list (`plugin.video.shaders(id)`, player
+             * 0.5.20); `[]` removes it.
+             */
+            shadersSet: (id, paths) => transport.request("video.shaders.set", { id, paths }),
             /** The GPU's video upscaler (`plugin.video.upscaling`, player 0.5.16). */
             upscalingState: () => transport.request("video.upscaling.state"),
             upscalingSet: (enabled) => transport.request("video.upscaling.set", {
@@ -255,14 +260,18 @@ export function createWire(transport) {
             set: (options) => transport.request("layout.set", options),
         },
         events: {
-            /** One `events.subscribe` per name however many listeners. */
-            async subscribe(event, listener) {
+            /**
+             * One `events.subscribe` per name however many listeners. `mirror`:
+             * only the SDK keeps a copy of the state (player 0.5.18; older
+             * players ignore it); `listen` changes it.
+             */
+            async subscribe(event, listener, mirror = false) {
                 const off = transport.on(event, listener);
                 let subscription = subscriptions.get(event);
                 if (!subscription) {
                     subscription = {
                         count: 0,
-                        ready: transport.request("events.subscribe", { event }),
+                        ready: transport.request("events.subscribe", mirror ? { event, mirror: true } : { event }),
                     };
                     subscriptions.set(event, subscription);
                 }
@@ -287,6 +296,13 @@ export function createWire(transport) {
                     }
                 };
             },
+            /**
+             * Tell the player whether a subscribed event has a real listener
+             * (`active`) or only the SDK's copy of the state: `events.subscribe`
+             * again, which replaces the mark (player 0.5.18; older players keep
+             * one subscription per name and ignore the mark).
+             */
+            listen: (event, active) => transport.request("events.subscribe", active ? { event } : { event, mirror: true }),
         },
         ui: {
             /** Player 0.2.0: the remote images a Markdown document shows. */