@vestra-player/sdk 1.5.38 → 1.5.39

package/dist/plugin/types.d.ts

@@ -9,11 +9,11 @@
  * object, so a built plugin has no runtime dependency on this package.
  */
 import type { Json } from "../wire.ts";
-import type { AudioNode, VideoNode } from "../processing.ts";
+import type { AudioNode, ConvolutionPlane, VideoNode } from "../processing.ts";
 import type { SubtitleStyle } from "../subtitles.ts";
 import type { ResolvedMedia } from "../source-resolvers.ts";
 import type { MediaJob } from "../media.ts";
-export type { Json, AudioNode, VideoNode, SubtitleStyle, ResolvedMedia };
+export type { Json, AudioNode, ConvolutionPlane, VideoNode, SubtitleStyle, ResolvedMedia, };
 /**
  * Anything that owns player-side or local resources: every handle the API
  * returns (commands, windows, panels, filters, snapshots, listeners…).
@@ -214,10 +214,11 @@ export interface Scope extends Disposable {
     readonly player: Player;
     /**
      * Video processing: this plugin's filter chain, the display layer, the
-     * GPU render options and the GPU's video upscaler. The first three need
-     * `processing.video` and `playback.read`; the filter chain also needs
-     * `events` (without it the SDK never sees the media become ready and the
-     * chain stays `waiting`). The upscaler needs `video.upscaling` only.
+     * GPU render options, this plugin's shaders and the GPU's video
+     * upscaler. The first four need `processing.video` and `playback.read`;
+     * the filter chain also needs `events` (without it the SDK never sees
+     * the media become ready and the chain stays `waiting`). The upscaler
+     * needs `video.upscaling` only.
      */
     readonly video: {
         /**
@@ -250,6 +251,24 @@ export interface Scope extends Disposable {
          *   while the first handle is not disposed.
          */
         render(): RenderOptions;
+        /**
+         * This plugin's own GPU shaders named `id` (default `"shaders"`;
+         * needs `processing.video`; SDK 1.5.39, player 0.5.20). Unlike
+         * {@link Scope.video | render()}, every plugin may hold shader
+         * handles at the same time; the player joins their lists. Nothing is
+         * sent until the first `set()`.
+         *
+         * @param id - Local name of the handle, 1–128 bytes, unique within
+         *   the plugin.
+         * @returns A {@link VideoShaders} owned by this scope.
+         * @throws `capability` (throws) The manifest does not declare
+         *   `processing.video`.
+         * @throws `invalid` (throws) `id` is empty, longer than 128 bytes or
+         *   has control characters.
+         * @throws `Error` without a code (throws) A second handle with the
+         *   same `id` while the first is not disposed.
+         */
+        shaders(id?: string): VideoShaders;
         /**
          * The GPU's video upscaler (NVIDIA RTX Video Super Resolution on
          * Windows; needs `video.upscaling`, player 0.5.16): whether it works
@@ -4055,8 +4074,10 @@ export interface SystemInfo {
      * Absent (`undefined`) on players before 0.5.12, which do not report it:
      * the renderer is then unknown, not software.
      *
-     * Today the player renders on the GPU on macOS and in software on
-     * Windows, Linux and without a user interface (see
+     * Today the player renders on the GPU on macOS, on Windows when the
+     * user turned on Video ▸ GPU Rendering (Experimental) (since version 0.5.14;
+     * off by default), and in software otherwise: on Windows by default, on
+     * Linux and without a user interface (see
      * [Platforms](../../docs/reference/platforms.md)); test this field
      * rather than {@link SystemInfo.os}.
      *
@@ -4954,9 +4975,11 @@ export interface SequenceProvider {
  */
 export interface PlaybackStats {
     /**
-     * The rendering path: "libmpv · GPU 渲染（OpenGL）" (GPU, macOS default) or
-     * "libmpv · 软件渲染" (software: Windows, Linux, headless, fallback).
-     * The strings are the player's display text.
+     * The rendering path: "libmpv · GPU 渲染（OpenGL）" (GPU on macOS, the
+     * default there), "libmpv · GPU 渲染（Direct3D）" (GPU on Windows, when
+     * turned on; version 0.5.14 and later) or "libmpv · 软件渲染" (software: Windows by
+     * default, Linux, headless, fallback). The strings are the player's
+     * display text in the interface language (shown here in Chinese).
      */
     backend: string;
     /** The playback session number. */
@@ -6357,7 +6380,11 @@ export interface RenderSettings {
     targetPeak: number;
     /** Per-scene peak estimation (where the GPU supports it). */
     peakDetect: boolean;
-    /** mpv user shaders (`.glsl`): absolute paths of existing files, at most 16, in order. */
+    /**
+     * mpv user shaders (`.glsl`): absolute paths of existing files, at most
+     * 16, in order. They run before the shaders of every plugin's
+     * {@link VideoShaders} handles.
+     */
     shaders: string[];
     /** Motion interpolation, resampled to the display's refresh rate. */
     interpolation: boolean;
@@ -6367,10 +6394,12 @@ export interface RenderSettings {
  * (`processing.video`). Single owner, like {@link VideoView}; the two are
  * independent handles.
  *
- * Platforms: only macOS renders on the GPU. Under software rendering
- * (Windows, Linux, headless, fallback) every `set` fails with
- * `unsupported`; {@link SystemInfo.rendering} tells which renderer draws
- * without creating the handle. macOS OpenGL 4.1 has no
+ * Platforms: macOS renders on the GPU by default; Windows does since
+ * version 0.5.14 of the player when the user turns on Video ▸ GPU Rendering
+ * (Experimental) (off by default, {@link Rendering}). Under software
+ * rendering (Windows by default, Linux, headless, fallback) every `set`
+ * fails with `unsupported`; {@link SystemInfo.rendering} tells which
+ * renderer draws without creating the handle. macOS OpenGL 4.1 has no
  * compute shaders, so `peakDetect` is accepted but has no effect; output
  * is always SDR.
  *
@@ -6379,7 +6408,8 @@ export interface RenderSettings {
  * 250-nit display; under software rendering the plugin hides its HDR menu.
  * `set` merges the values into the plugin's render options and the
  * player reports the result through `onStatus`: `failed` with
- * `unsupported` means the player renders in software (Windows, Linux).
+ * `unsupported` means the player renders in software (Linux, or Windows
+ * while GPU rendering is off).
  * ```ts
  * declare function hideHdrMenu(): void;
  * // ---cut---
@@ -6392,11 +6422,13 @@ export interface RenderSettings {
  *
  * @remarks
  * GPU renderer options (tone mapping, peak detection, shaders,
- * interpolation). Only the GPU renderer has them, which today means macOS;
+ * interpolation). Only the GPU renderer has them (macOS; Windows with GPU
+ * rendering turned on, version 0.5.14 and later);
  * under software rendering the handle is `failed` with `unsupported` after
  * the player's first answer to `render()` (reported to `onError` too), and so is
  * every `set`. Single owner, like {@link VideoView}. `set` never throws; the
- * result shows in `status`.
+ * result shows in `status`. For shaders that several plugins add at the
+ * same time, use {@link VideoShaders} (SDK 1.5.39).
  *
  * @capability processing.video, playback.read and events (like
  * {@link VideoFilter})
@@ -6423,7 +6455,9 @@ export interface RenderOptions extends Disposable {
     set(value: Partial<RenderSettings>): void;
     /**
      * `failed` with `unsupported` while the player renders in software;
-     * `failed` with `failed` when mpv cannot compile a shader (pushed later).
+     * `failed` with `failed` when mpv cannot compile a shader (pushed later;
+     * while other plugins' {@link VideoShaders} are on too, the player
+     * cannot tell whose shader failed and says so in the message).
      */
     readonly status: FilterStatus;
     /**
@@ -6446,6 +6480,152 @@ export interface RenderOptions extends Disposable {
      */
     onStatus(listener: (status: FilterStatus) => void): Disposable;
 }
+/**
+ * This plugin's own GPU shaders, from `plugin.video.shaders(id)`
+ * (`processing.video`, SDK 1.5.39, player 0.5.20): mpv user shaders
+ * (`.glsl`, `//!HOOK` …) that the GPU renderer runs on every frame.
+ *
+ * @remarks
+ * Any number of plugins hold shader handles at the same time (unlike
+ * {@link RenderOptions}, which has one owner). The player joins every
+ * handle's list in a stable order, after the render options' own
+ * `shaders`: built-in plugins first, then installed plugins in the order
+ * they were first installed, then development loads (`--plugin`); ties by
+ * plugin id, and a plugin's handles by `id`. At most 16 shaders across all
+ * handles (`limit` beyond, nothing changes); the render options keep their
+ * own 16.
+ *
+ * Files must be this plugin's own: absolute paths inside its package
+ * directory or {@link Plugin.dataDirectory} after following links, each
+ * at most 16 MiB. Elsewhere: `invalid`; a file that does not exist:
+ * `missing`. The player reads the files when the list is set.
+ *
+ * GPU rendering only (macOS; Windows with Video ▸ GPU Rendering
+ * (Experimental) turned on): under software rendering a non-empty list is
+ * `failed` with `unsupported`, and a switch to software during the run
+ * pushes `unsupported` to every handle with shaders and removes every
+ * list (they no longer count against the 16); set them again once the
+ * player draws on the GPU (after a restart). Shaders act when a
+ * frame is drawn, so processed snapshots and exports never contain them
+ * (use a {@link VideoNode} for that). When mpv cannot compile a shader the
+ * handle turns `failed` with `failed` (pushed later); mpv does not say
+ * which file failed, so while several plugins' shaders are on, each of
+ * them hears it and the message says the player cannot tell whose.
+ *
+ * `set` sends the whole list (last write wins); `clear` and `dispose`
+ * withdraw it; the player removes a stopped plugin's shaders itself.
+ * Players before 0.5.20 refuse the request (the handle is `failed`): declare
+ * `"minPlayerVersion": "0.5.20"`.
+ *
+ * @example Add a sharpening shader the plugin ships
+ * The video looks sharper on the GPU renderer; under software rendering
+ * the OSD says why it is not. The shader file lives in the plugin's
+ * package, and the player puts it after other plugins' shaders that come
+ * earlier in its order.
+ * ```ts
+ * import { join } from "node:path";
+ * declare const packageDirectory: string;
+ * // ---cut---
+ * const shaders = plugin.video.shaders("sharpen");
+ * shaders.onStatus((s) => {
+ *   // `unsupported`: software rendering; `failed`: mpv could not compile it.
+ *   if (s.state === "failed") void plugin.osd.show("Sharpen: {}", [s.error.message]);
+ * });
+ * shaders.set([join(packageDirectory, "shaders", "sharpen.glsl")]);
+ * ```
+ *
+ * @capability processing.video
+ * @player 0.5.20; older players refuse the request.
+ * @see [Video and audio processing](../../docs/concepts/processing.md)
+ * @since 1.5.39
+ * @category Processing
+ */
+export interface VideoShaders extends Disposable {
+    /**
+     * Replace this handle's shader list (last write wins); `[]` withdraws
+     * it.
+     *
+     * @remarks
+     * Never throws: a refused list shows in `status` (`invalid`, `missing`,
+     * `limit`, `unsupported`) and goes to {@link Scope.onError}, and what the
+     * player held stays.
+     *
+     * @capability processing.video
+     * @param paths - Absolute paths of shader files in this plugin's package
+     *   or data directory, in the order they run.
+     *
+     * @example Switch between two shader presets
+     * The plugin offers a light and a strong preset; picking one replaces
+     * the handle's list in one request. The files were written to the
+     * plugin's data directory when the user imported them.
+     * ```ts
+     * import { join } from "node:path";
+     * // ---cut---
+     * const presets: Record<string, string[]> = {
+     *   light: [join(plugin.dataDirectory, "denoise.glsl")],
+     *   strong: [join(plugin.dataDirectory, "denoise.glsl"), join(plugin.dataDirectory, "sharpen.glsl")],
+     * };
+     * plugin.video.shaders("presets").set(presets.strong!);
+     * ```
+     *
+     * @since 1.5.39
+     */
+    set(paths: readonly string[]): void;
+    /**
+     * Withdraw this handle's shaders (the same as `set([])`).
+     *
+     * @capability processing.video
+     *
+     * @example Turn the plugin's shaders off from a menu item
+     * A Video menu item turns the plugin's shader on and off. Clearing
+     * keeps the handle, so the next pick sets the list again.
+     * ```ts
+     * declare const file: string;
+     * // ---cut---
+     * const shaders = plugin.video.shaders();
+     * let on = false;
+     * plugin.commands.add({
+     *   id: "toggle-shader",
+     *   path: ["@video", "Sharpen (Shader)"],
+     *   checked: () => on,
+     *   run: () => {
+     *     on = !on;
+     *     // Clearing keeps the handle; the next pick sets the list again.
+     *     if (on) shaders.set([file]);
+     *     else shaders.clear();
+     *   },
+     * });
+     * ```
+     *
+     * @since 1.5.39
+     */
+    clear(): void;
+    /**
+     * Current status: `waiting` before ready media, `applying`, `applied`,
+     * or `failed` with the reason (see the remarks).
+     */
+    readonly status: FilterStatus;
+    /**
+     * The status changed, including later pushes (a compile failure, a
+     * switch to software rendering).
+     *
+     * @capability processing.video
+     *
+     * @example Report a shader that does not compile
+     * The OSD shows mpv's message when the plugin's shader fails to compile.
+     * The player pushes that failure after the list was accepted, so it
+     * arrives through `onStatus`, not as a refused `set`.
+     * ```ts
+     * const shaders = plugin.video.shaders();
+     * shaders.onStatus((status) => {
+     *   if (status.state === "failed") void plugin.osd.show("Shader: {}", [status.error.message]);
+     * });
+     * ```
+     *
+     * @since 1.5.39
+     */
+    onStatus(listener: (status: FilterStatus) => void): Disposable;
+}
 /**
  * Why the GPU's video upscaler does not work, as a stable kebab-case code.
  * A newer player may add codes: compare with the ones you handle and show
@@ -9295,10 +9475,10 @@ export type RenderingPreference = "auto" | "gpu" | "software";
  *
  * | Code | Meaning |
  * | --- | --- |
- * | `default` | Nothing ruled the GPU out; the platform's default. |
+ * | `default` | Nothing ruled the GPU out; the platform's default (macOS: GPU; Windows since version 0.5.14: software until the user turns on GPU rendering). |
  * | `pending` | GPU rendering is starting. |
  * | `headless` | The player runs without a user interface. |
- * | `no-gpu-backend` | This player has no GPU renderer on this system (Windows today). |
+ * | `no-gpu-backend` | This player has no GPU renderer on this system (Linux today; Windows has one since version 0.5.14, off by default, which reports `default`). |
  * | `env` | The environment chose it (`VESTRA_RENDER`, `VESTRA_SOFTWARE_RENDER`). |
  * | `preference` | The user chose software rendering ({@link Rendering.setPreference}); GPU chosen and available reports `default`. |
  * | `denylist` | The graphics driver is on the player's denylist. |

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

@@ -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>;

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", {