@vestra-player/sdk 1.5.38 → 1.5.40

package/dist/plugin/when.js

@@ -0,0 +1,106 @@
+import { LOCALES } from "../i18n.js";
+import { THEMES } from "./appearance.js";
+const PHASES = [
+    "empty",
+    "loading",
+    "ready",
+    "ended",
+    "error",
+];
+const CONTROLS = [
+    "pause",
+    "seek",
+    "rate",
+    "restart",
+    "close",
+    "snapshot",
+    "next",
+    "previous",
+];
+class ConditionImpl {
+    #json;
+    constructor(json) {
+        this.#json = json;
+        Object.freeze(this);
+    }
+    and(...others) {
+        return new ConditionImpl({
+            all: [this.#json, ...others.map(conditionJson)],
+        });
+    }
+    or(...others) {
+        return new ConditionImpl({
+            any: [this.#json, ...others.map(conditionJson)],
+        });
+    }
+    not() {
+        return new ConditionImpl({ not: this.#json });
+    }
+    toJSON() {
+        return this.#json;
+    }
+    static json(condition) {
+        return condition.#json;
+    }
+}
+/** Whether `value` is a condition made by `plugin.when`. */
+export const isCondition = (value) => value instanceof ConditionImpl;
+/** A condition's wire form; throws for anything else. */
+export function conditionJson(condition) {
+    if (!(condition instanceof ConditionImpl))
+        throw new TypeError("a condition comes from plugin.when");
+    return ConditionImpl.json(condition);
+}
+const make = (json) => new ConditionImpl(json);
+/** The one `plugin.when` (conditions hold no plugin state). */
+export const WHEN = Object.freeze({
+    open: make({ not: { phase: ["empty"] } }),
+    ready: make({ phase: ["ready"] }),
+    playing: make({ all: [{ phase: ["ready"] }, { paused: false }] }),
+    paused: make({ all: [{ phase: ["ready"] }, { paused: true }] }),
+    stream: make({ kind: "stream" }),
+    fullscreen: make({ fullscreen: true }),
+    phase(...phases) {
+        if (!phases.length || phases.some((phase) => !PHASES.includes(phase)))
+            throw new TypeError(`phase is one or more of ${PHASES.join(", ")}`);
+        return make({ phase: [...phases] });
+    },
+    can(control) {
+        if (!CONTROLS.includes(control))
+            throw new TypeError(`can is one of ${CONTROLS.join(", ")}`);
+        return make({ can: control });
+    },
+    theme(theme) {
+        if (!THEMES.includes(theme))
+            throw new TypeError(`theme is ${THEMES.map((t) => `"${t}"`).join(" or ")}`);
+        return make({ theme });
+    },
+    language(language) {
+        if (language !== "system" &&
+            !LOCALES.includes(language))
+            throw new TypeError(`language is "system" or one of ${LOCALES.map((l) => `"${l}"`).join(", ")}`);
+        return make({ language });
+    },
+});
+/** Evaluate a wire condition as the player does (for the test host). */
+export function evaluate(json, facts) {
+    if ("phase" in json)
+        return json.phase.includes(facts.phase);
+    if ("paused" in json)
+        return facts.paused === json.paused;
+    if ("kind" in json)
+        return facts.kind === json.kind;
+    if ("can" in json)
+        return facts.can[json.can] === true;
+    if ("fullscreen" in json)
+        return facts.fullscreen === json.fullscreen;
+    if ("theme" in json)
+        return facts.theme === json.theme;
+    if ("language" in json)
+        return facts.language === json.language;
+    if ("all" in json)
+        return json.all.every((each) => evaluate(each, facts));
+    if ("any" in json)
+        return json.any.some((each) => evaluate(each, facts));
+    return !evaluate(json.not, facts);
+}

package/dist/processing.d.ts

@@ -1,7 +1,3 @@
-/**
- * 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 type { Transport } from "./wire.ts";
 /**
  * One node of a {@link VideoFilter} chain, by `kind`. Values outside the
@@ -165,7 +161,114 @@ export type VideoNode =
     kind: "frameBlend";
     /** Output frame rate, integer 24–120. */
     fps: number;
+}
+/**
+ * A convolution matrix of your own per plane (FFmpeg `convolution`, SDK
+ * 1.5.39, player 0.5.20): sharpen, blur, emboss or detect edges with a
+ * 3×3, 5×5 or 7×7 kernel, or a row or column kernel. `planes[i]` is
+ * plane `i` of the decoded picture: for the usual YUV video 0 is luma
+ * (brightness), 1 and 2 are the colour planes, 3 is alpha. A missing
+ * entry or `null` leaves that plane as it is; at least one entry has a
+ * matrix. Players before 0.5.20 refuse the kind with `invalid`.
+ */
+ | {
+    /** The node type. */
+    kind: "convolution";
+    /** 1–4 entries, by plane; `null` passes the plane through. */
+    planes: (ConvolutionPlane | null)[];
+}
+/**
+ * Recolour the picture with a 3D look-up table (FFmpeg `lut3d`, SDK
+ * 1.5.39, player 0.5.20): a `.cube` file the plugin ships in its package
+ * or wrote to its {@link Plugin.dataDirectory}. The player reads the file
+ * when the chain is set (and again for each new source, snapshot or
+ * export), so it must stay there while the chain uses it. The table is
+ * applied to RGB; the player converts the picture to RGB and back.
+ * Players before 0.5.20 refuse the kind with `invalid`.
+ */
+ | {
+    /** The node type. */
+    kind: "lut3d";
+    /**
+     * Absolute path of a `.cube` file (`LUT_3D_SIZE` 2–65, at most
+     * 16 MiB) inside the plugin's package directory or data directory
+     * after following links; a path with `[` or `]` is refused. Outside
+     * those: `invalid`; a file that does not exist: `missing`.
+     */
+    file: string;
+    /** How colours between the table's points are computed; `tetrahedral` is FFmpeg's default. */
+    interpolation: "nearest" | "trilinear" | "tetrahedral" | "pyramid" | "prism";
+};
+/**
+ * One plane's kernel of a `convolution` {@link VideoNode}: each output
+ * sample is `(sum of matrix × neighbourhood) × rdiv + bias`, clipped to the
+ * sample range.
+ *
+ * @since 1.5.39
+ * @category Processing
+ */
+export type ConvolutionPlane = {
+    /**
+     * `square`: `matrix` is a 3×3, 5×5 or 7×7 kernel, row by row (9, 25 or
+     * 49 entries); `row` / `column`: a horizontal / vertical kernel with an
+     * odd number of entries up to 49.
+     */
+    mode: "square" | "row" | "column";
+    /** Integers −1024–1024 (FFmpeg reads whole numbers only). */
+    matrix: number[];
+    /**
+     * Multiplier 0–256; 0 divides by the sum of the matrix (by 1 when it
+     * sums to 0), which keeps the brightness of a blur.
+     */
+    rdiv: number;
+    /** Added after the multiplication, 0–65535 in the plane's sample units (128 is mid grey for 8-bit video). */
+    bias: number;
 };
+/**
+ * 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 declare const VIDEO_PROCESSING_LIMITS: Readonly<{
+    /** Shaders across every plugin's `plugin.video.shaders()` handles (16). */
+    shaders: 16;
+    /** Bytes of one shader file (16 MiB). */
+    shaderBytes: number;
+    /** Bytes of a shader handle's id (128). */
+    shaderIdBytes: 128;
+    /** Bytes of one `lut3d` `.cube` file (16 MiB). */
+    lutBytes: number;
+    /** 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;
+}>;
 /**
  * One node of an {@link AudioFilter} chain, by `kind`. Values outside the
  * ranges fail with `invalid`; "live" fields change in place while playing.
@@ -236,6 +339,17 @@ export type AudioNode =
     /** `stereo` leaves it unchanged. */
     mode: "stereo" | "left" | "right" | "mono" | "swap";
 };
+/**
+ * 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 declare function hasControl(text: string): boolean;
+/**
+ * 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 declare function lutPathProblem(file: unknown): string | 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.

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

@@ -376,11 +376,11 @@ export declare function createWire(transport: Transport): {
         operation: (token: import("./processing.ts").ProcessingToken) => Promise<import("./processing.ts").ProcessingOperation>;
     };
     commands: {
-        register: (id: string, revision: number, declaration: import("./commands.ts").CommandDeclaration, state: import("./commands.ts").CommandState) => Promise<{
+        register: (id: string, revision: number, declaration: import("./commands.ts").CommandDeclaration, state: import("./commands.ts").CommandState, when?: import("./commands.ts").CommandWhen) => Promise<{
             revision: number;
         }>;
         unregister: (id: string) => Promise<void>;
-        update: (id: string, revision: number, state: import("./commands.ts").CommandState) => Promise<{
+        update: (id: string, revision: number, state: import("./commands.ts").CommandState, when?: import("./commands.ts").CommandWhen) => Promise<{
             revision: number;
         }>;
     };
@@ -481,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>;
@@ -608,14 +615,14 @@ export declare function createWire(transport: Transport): {
          * 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>>;
+        subscribe(event: HostEvent, listener: (data: unknown) => void, mirror?: boolean, why?: string[]): 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>;
+        listen: (event: HostEvent, active: boolean, why?: string[]) => 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", {
@@ -260,13 +265,19 @@ export function createWire(transport) {
              * 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) {
+            async subscribe(event, listener, mirror = false, 
+            /** What listens (player 0.5.21 logs it; older players ignore it). */
+            why) {
                 const off = transport.on(event, listener);
                 let subscription = subscriptions.get(event);
                 if (!subscription) {
                     subscription = {
                         count: 0,
-                        ready: transport.request("events.subscribe", mirror ? { event, mirror: true } : { event }),
+                        ready: transport.request("events.subscribe", mirror
+                            ? { event, mirror: true }
+                            : why?.length
+                                ? { event, why }
+                                : { event }),
                     };
                     subscriptions.set(event, subscription);
                 }
@@ -297,7 +308,11 @@ export function createWire(transport) {
              * 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 }),
+            listen: (event, active, why) => transport.request("events.subscribe", active
+                ? why?.length
+                    ? { event, why }
+                    : { event }
+                : { event, mirror: true }),
         },
         ui: {
             /** Player 0.2.0: the remote images a Markdown document shows. */