@vestra-player/sdk 1.5.38 → 1.5.39

package/llms-full.txt

@@ -1,4 +1,4 @@
-# @vestra-player/sdk 1.5.38: full reference
+# @vestra-player/sdk 1.5.39: full reference
 
 > Everything needed to write a Vestra Player plugin (plugin API `vestra/1`): the guides, every public declaration of `@vestra-player/sdk` and `@vestra-player/sdk/testing` with its documentation, and the complete source of the example plugins. Generated from the SDK's sources by scripts/llms.mjs; the short index is llms.txt.
 
@@ -2709,6 +2709,7 @@ The table lists the API whose documentation names a player version, newest last:
 | 0.5.12 | SystemInfo.rendering |
 | 0.5.13 | SystemInfo.renderingReason, RenderingMode, RenderingPreference, RenderingReasonCode, RenderingReason, RenderingState, Rendering |
 | 0.5.16 | UpscalingReasonCode, UpscalingReason, UpscalingState, VideoUpscaling |
+| 0.5.20 | VideoShaders |
 
 The Slint library carries no version tags: `Theme.danger` needs player 0.3.0; `@vestra/icons.slint` and the palette `vestra-light` need 0.4.0 (Theme).
 
@@ -2730,7 +2731,7 @@ A plugin lists what it may do in the manifest's `capabilities` (Manifest). A cal
 | `ui.mount` | Panels.mount, Panels.bottom, Panels.sidebar, Panels.backdrop, PanelSlot.onChange, Panel.onChange, BackdropSlot.onChange | — | Show panels in the bottom bar, the sidebar or behind the video |  |
 | `ui.dialog` | Dialogs.confirm, Dialogs.openFile, Dialogs.openFiles, Dialogs.openDirectory, Dialogs.saveFile | — | Show file pickers and confirmations |  |
 | `plugins.manage` | Packages.validate, Packages.validateArchive, Packages.setEnabled, Packages.reload, Packages.uninstall | — | Install, uninstall and disable other plugins | yes |
-| `processing.video` | Plugin.video.filter, Plugin.video.view, Plugin.video.render | `playback.read` | Process the picture (filters, shaders) |  |
+| `processing.video` | Plugin.video.filter, Plugin.video.view, Plugin.video.render, Plugin.video.shaders | `playback.read` | Process the picture (filters, shaders) |  |
 | `processing.audio` | Plugin.audio.filter | `playback.read`, `events` | Process the sound |  |
 | `subtitles.read` | Subtitles.state, Subtitles.onChange, Subtitles.refresh | — | Read subtitles |  |
 | `subtitles.control` | Subtitles.select, Subtitles.load, Subtitles.remove, Subtitles.setStyle | — | Load and change subtitles |  |
@@ -2897,7 +2898,23 @@ RenderSettings; more shaders fail with `invalid`.
 
 | Limit | Value | Meaning |
 | --- | --- | --- |
-| Entries of `RenderSettings.shaders` | 16 | mpv user shaders (`.glsl`): absolute paths of existing files, at most 16, in order. |
+| Entries of `RenderSettings.shaders` | 16 | mpv user shaders (`.glsl`): absolute paths of existing files, at most 16, in order. They run before the shaders of every plugin's `VideoShaders` handles. |
+
+#### Video primitives
+
+The `convolution` and `lut3d` VideoNodes and the shader channel VideoShaders (player 0.5.20). Values beyond them fail with `invalid`; more shaders than `shaders` across all plugins fail with `limit`.
+
+| Limit | Value | Meaning |
+| --- | --- | --- |
+| `VIDEO_PROCESSING_LIMITS.shaders` | 16 | Shaders across every plugin's `plugin.video.shaders()` handles. |
+| `VIDEO_PROCESSING_LIMITS.shaderBytes` | 16777216 (16 MiB) | Bytes of one shader file. |
+| `VIDEO_PROCESSING_LIMITS.shaderIdBytes` | 128 | Bytes of a shader handle's id. |
+| `VIDEO_PROCESSING_LIMITS.lutBytes` | 16777216 (16 MiB) | Bytes of one `lut3d` `.cube` file. |
+| `VIDEO_PROCESSING_LIMITS.lutSize` | 65 | Largest `LUT_3D_SIZE` of a `lut3d` file, points per axis. |
+| `VIDEO_PROCESSING_LIMITS.lutPathBytes` | 4096 (4 KiB) | Bytes of a `lut3d` file path. |
+| `VIDEO_PROCESSING_LIMITS.matrixValue` | 1024 | Largest magnitude of a `convolution` matrix entry. |
+| `VIDEO_PROCESSING_LIMITS.rdiv` | 256 | Largest `convolution` `rdiv`. |
+| `VIDEO_PROCESSING_LIMITS.bias` | 65535 | Largest `convolution` `bias`. |
 
 #### Limits documented at their API
 
@@ -3889,7 +3906,7 @@ interface Scope extends Disposable {
   /** Playback state and controls (`playback.read`, `events`, `playback.control`). */
   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.
+   * Video processing: this plugin's filter chain, the display layer, the 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: {
     /**
@@ -3910,6 +3927,15 @@ interface Scope extends Disposable {
      * @throws Error without a code (throws) A second call in the same plugin 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 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 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 here and why not, and turning it on or off for this plugin.
      */
@@ -7455,8 +7481,10 @@ 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); test this field
    * rather than SystemInfo.os.
    * @player 0.5.12; older players leave it out (declare `"minPlayerVersion": "0.5.12"` when the plugin relies on it).
@@ -8223,7 +8251,7 @@ What Player.stats reports. Every field is the backend's own value
 ```ts
 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. */
@@ -9352,7 +9380,7 @@ 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 VideoShaders handles. */
   shaders: string[];
   /** Motion interpolation, resampled to the display's refresh rate. */
   interpolation: boolean;
@@ -9365,19 +9393,23 @@ The GPU renderer's options, from `plugin.video.render()`
 (`processing.video`). Single owner, like 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`; 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, Rendering). Under software
+rendering (Windows by default, Linux, headless, fallback) every `set`
+fails with `unsupported`; 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.
 
 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 VideoView. `set` never throws; the
-result shows in `status`.
+result shows in `status`. For shaders that several plugins add at the
+same time, use VideoShaders (SDK 1.5.39).
 
 - @capability processing.video, playback.read and events (like VideoFilter)
 
@@ -9395,7 +9427,9 @@ 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 `unsupported` while the player renders in software; `failed` with `failed` when mpv cannot compile a shader (pushed later; while other plugins' VideoShaders are on too, the player cannot tell whose shader failed and says so in the message).
+   */
   readonly status: FilterStatus;
   /**
    * The status changed (including later pushes such as shader compile errors).
@@ -9421,7 +9455,8 @@ On a GPU-rendering player HDR video is tone-mapped with BT.2390 for a
 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
 const render = plugin.video.render();
 render.onStatus((s) => {
@@ -9430,6 +9465,127 @@ render.onStatus((s) => {
 render.set({ toneMapping: "bt.2390", targetPeak: 250 }); // nits
 ```
 
+### VideoShaders
+
+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.
+
+Any number of plugins hold shader handles at the same time (unlike
+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 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 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"`.
+
+- @capability processing.video
+- @player 0.5.20; older players refuse the request.
+
+```ts
+interface VideoShaders extends Disposable {
+  /**
+   * Replace this handle's shader list (last write wins); `[]` withdraws it.
+   *
+   * Never throws: a refused list shows in `status` (`invalid`, `missing`,
+   * `limit`, `unsupported`) and goes to 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
+   * 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!);
+   * ```
+   */
+  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
+   * 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();
+   *   },
+   * });
+   * ```
+   */
+  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]);
+   * });
+   * ```
+   */
+  onStatus(listener: (status: FilterStatus) => void): Disposable;
+}
+```
+
+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
+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")]);
+```
+
 ### UpscalingReasonCode
 
 Why the GPU's video upscaler does not work, as a stable kebab-case code.
@@ -11849,10 +12005,10 @@ RenderingReason.message for the rest. The codes of player 0.5.13:
 
 | 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 (Rendering.setPreference); GPU chosen and available reports `default`. |
 | `denylist` | The graphics driver is on the player's denylist. |
@@ -12217,6 +12373,28 @@ 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 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";
 };
 ```
 
@@ -12238,6 +12416,27 @@ const chain: VideoNode[] = [
 plugin.video.filter("picture").set(chain);
 ```
 
+### ConvolutionPlane
+
+One plane's kernel of a `convolution` VideoNode: each output
+sample is `(sum of matrix × neighbourhood) × rdiv + bias`, clipped to the
+sample range.
+
+```ts
+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;
+};
+```
+
 ### AudioNode
 
 One node of an AudioFilter chain, by `kind`. Values outside the
@@ -13394,6 +13593,39 @@ class TestHost implements Transport {
    * ```
    */
   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 VIDEO_PROCESSING_LIMITS`.shaders` (`limit`). Files must be under TestHost.fileRoots; under software rendering (`videoRender.gpu = false`) a non-empty list fails with `unsupported`.
+   */
+  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 (startPlugin sets both when the list is still empty). `lut3d` files and shader-channel files outside them fail with `invalid`, as in the player.
+   */
+  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 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
+   * 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");
+   * ```
+   */
+  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 plugin applied, keyed by the SDK's resource id.
    * @example Check the filter chain the plugin applied
@@ -13655,9 +13887,9 @@ 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),
@@ -13665,7 +13897,7 @@ 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();
    * ```
    */
@@ -15100,6 +15332,49 @@ const IMAGE_LIMITS: Readonly<{
 }>;
 ```
 
+### VIDEO_PROCESSING_LIMITS
+
+The player's bounds for the video primitives of SDK 1.5.39 (player
+0.5.20): `convolution` and `lut3d` VideoNodes and the shader
+channel (`plugin.video.shaders()`). Values beyond them fail with
+`invalid`; more shaders than `shaders` fail with `limit`.
+
+```ts
+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;
+}>;
+```
+
+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 { 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);
+```
+
 ### HostError
 
 A definite refusal from the player (or the plugin runner), with a stable
@@ -15359,7 +15634,7 @@ What Player.stats reports. Every field is the backend's own value
 ```ts
 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. */

package/llms.txt

@@ -1,6 +1,6 @@
 # Vestra Player SDK
 
-> @vestra-player/sdk 1.5.38: write plugins for Vestra Player in TypeScript (plugin API `vestra/1`). A plugin is a folder with `manifest.json` and an entry module whose default export `activate(plugin)` the player calls; it runs in its own Node.js process. Everything a plugin creates (commands, windows, panels, filters, listeners…) is a handle that is released automatically when the plugin stops. L<n>: a line of llms-full.txt (next to this file), which has every page, declaration and example.
+> @vestra-player/sdk 1.5.39: write plugins for Vestra Player in TypeScript (plugin API `vestra/1`). A plugin is a folder with `manifest.json` and an entry module whose default export `activate(plugin)` the player calls; it runs in its own Node.js process. Everything a plugin creates (commands, windows, panels, filters, listeners…) is a handle that is released automatically when the plugin stops. L<n>: a line of llms-full.txt (next to this file), which has every page, declaration and example.
 
 **Rules**
 
@@ -33,7 +33,7 @@ my-plugin/
 }
 ```
 
-Fields: `id`, `version`, `apiVersion`, `entry`, `capabilities`, `name`, `author`, `punchline`, `description`, `tags`, `icon`, `readme`, `changelog`, `sourceUrl`, `license`, `minPlayerVersion`; unknown fields and capabilities are rejected. Rules and limits: L2646–2716.
+Fields: `id`, `version`, `apiVersion`, `entry`, `capabilities`, `name`, `author`, `punchline`, `description`, `tags`, `icon`, `readme`, `changelog`, `sourceUrl`, `license`, `minPlayerVersion`; unknown fields and capabilities are rejected. Rules and limits: L2646–2717.
 
 **main.ts**
 
@@ -61,7 +61,7 @@ export default async function activate(plugin: Plugin) {
 - `ui.mount`: Panels.mount/bottom/sidebar/backdrop, PanelSlot/Panel/BackdropSlot.onChange
 - `ui.dialog`: Dialogs.confirm/openFile/openFiles/openDirectory/saveFile
 - `plugins.manage`: Packages.validate/validateArchive/setEnabled/reload/uninstall
-- `processing.video`: Plugin.video.filter/video.view/video.render (also `playback.read`)
+- `processing.video`: Plugin.video.filter/video.view/video.render/video.shaders (also `playback.read`)
 - `processing.audio`: Plugin.audio.filter (also `playback.read`, `events`)
 - `subtitles.read`: Subtitles.state/onChange/refresh
 - `subtitles.control`: Subtitles.select/load/remove/setStyle
@@ -78,9 +78,9 @@ export default async function activate(plugin: Plugin) {
 - `secrets`: Secrets.get/set/delete
 - `rendering.manage`: Rendering.setPreference/restartPlayer
 - `video.upscaling`: VideoUpscaling.state/set
-- No capability: `tools`, `storage`, `system`, `app`, `ui` (images and Markdown), `i18n`, reading window.state, appearance.theme, packages.list and rendering.state. Details: L2717–2777.
+- No capability: `tools`, `storage`, `system`, `app`, `ui` (images and Markdown), `i18n`, reading window.state, appearance.theme, packages.list and rendering.state. Details: L2718–2778.
 
-**Test**: `tests/*.test.ts` with `node:test`, run by `vestra-plugin test`. `startPlugin(activate, { directory: new URL("..", import.meta.url) })` from `@vestra-player/sdk/testing` returns `{ host, stop }`, `host` an in-memory player (TestHost): act (`host.command(id).run()`, `host.press(key)`), `await host.settle()`, assert on `host.osd`, `host.window(id).props`… Guide: L2087–2275; TestHost: L12758.
+**Test**: `tests/*.test.ts` with `node:test`, run by `vestra-plugin test`. `startPlugin(activate, { directory: new URL("..", import.meta.url) })` from `@vestra-player/sdk/testing` returns `{ host, stop }`, `host` an in-memory player (TestHost): act (`host.command(id).run()`, `host.press(key)`), `await host.settle()`, assert on `host.osd`, `host.window(id).props`… Guide: L2087–2275; TestHost: L12957.
 
 **Command line**
 
@@ -108,7 +108,7 @@ export default async function activate(plugin: Plugin) {
 - `limit`: A player-wide limit was reached, a property value is over the limits of PropValue
 - `reserved`: The id is `vestra` or starts with `vestra.`
 - `versionMismatch`: The package needs a newer player
-- Others: PluginError, llms-full.txt L3780.
+- Others: PluginError, llms-full.txt L3797.
 
 ## Reference
 
@@ -117,30 +117,30 @@ export default async function activate(plugin: Plugin) {
 - Concepts: How a plugin runs L238–418; Commands, menus and key bindings L419–530; Playback state, controls and sources L531–676; Video and audio processing L677–763; Windows, panels, settings pages, dialogs and the OSD L764–1052
 - How-to: Control playback L1053–1181; Store a plugin's data L1182–1249; Load subtitles from a plugin L1250–1328; Keep a slider responsive while dragging L1329–1503; Remember a window's state between runs L1504–1633; Offer a GPU rendering switch L1634–1754; Translate a plugin L1755–1938; Migrate a plugin to English source text L1939–2086; Test a plugin L2087–2275; Publish a plugin L2276–2364; Migrating off package rollback (1.5.16, removed in 1.5.17) L2365–2440
 - Guidelines: Interface guidelines L2441–2548; Menu guidelines L2549–2645
-- Reference: Manifest L2646–2716; Capabilities L2717–2777; Limits L2778–2907; Commands, menus and bindings L2908–3391; Platforms L3392–3422; Theme L3423–3644; Command line L3645–3702
-- [API: @vestra-player/sdk](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk.html): L3703–12442
-- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html): L12443–15162
+- Reference: Manifest L2646–2717; Capabilities L2718–2778; Limits L2779–2924; Commands, menus and bindings L2925–3408; Platforms L3409–3439; Theme L3440–3661; Command line L3662–3719
+- [API: @vestra-player/sdk](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk.html): L3720–12641
+- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html): L12642–15437
 
 ## API
 
 Where each `plugin.<module>` is declared:
 
-- Plugin L4106, Scope L3855, PluginError L3780, Disposable L3718
-- Commands L4503; Windows L5440; Panels L6886; Dialogs L7554; Player L8295; video: VideoFilter L9175, VideoView L9275, RenderOptions L9362, VideoUpscaling L9558; audio: AudioFilter L9220; Subtitles L9754; media: MediaCapture L10158; Resolvers L10388; Packages L10790; Osd L9040; Host L8882; Clipboard L11118; Power L11205; Tools L11264; Storage L11416; System L11615; Secrets L11695; window: MainWindow L7203; App L7383; Rendering L11958; Bindings L11018; Ui L4792; Timeline L7115; Drops L6133; Appearance L6214; I18n L6447; Settings L6730.
+- Plugin L4132, Scope L3872, PluginError L3797, Disposable L3735
+- Commands L4529; Windows L5466; Panels L6912; Dialogs L7582; Player L8323; video: VideoFilter L9203, VideoView L9303, RenderOptions L9390, VideoShaders L9468, VideoUpscaling L9714; audio: AudioFilter L9248; Subtitles L9910; media: MediaCapture L10314; Resolvers L10544; Packages L10946; Osd L9068; Host L8910; Clipboard L11274; Power L11361; Tools L11420; Storage L11572; System L11771; Secrets L11851; window: MainWindow L7229; App L7409; Rendering L12114; Bindings L11174; Ui L4818; Timeline L7141; Drops L6159; Appearance L6240; I18n L6473; Settings L6756.
 
 ## Examples
 
 Tested plugins in [examples/](https://github.com/vestrasys/vestra-player-sdk/tree/main/examples):
 
-- hello: The README Quick start: one menu command and an on-screen message. L15597–15686
-- blur: A tool window with one slider that blurs the playing video. L15687–15948
-- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L15949–16281
-- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L16282–16468
-- panel-menu: A sidebar panel with its own right-click menu. L16469–16677
-- menus: Radio menu items, separator groups and a menu item whose title changes. L16678–16837
-- theme-widgets: A tool window drawn with the player's theme and widgets. L16838–17001
-- markdown: A window that shows a Markdown document. L17002–17198
-- i18n: A plugin in the player's language: English source text, a Chinese translation. L17199–17366
+- hello: The README Quick start: one menu command and an on-screen message. L15872–15961
+- blur: A tool window with one slider that blurs the playing video. L15962–16223
+- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L16224–16556
+- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L16557–16743
+- panel-menu: A sidebar panel with its own right-click menu. L16744–16952
+- menus: Radio menu items, separator groups and a menu item whose title changes. L16953–17112
+- theme-widgets: A tool window drawn with the player's theme and widgets. L17113–17276
+- markdown: A window that shows a Markdown document. L17277–17473
+- i18n: A plugin in the player's language: English source text, a Chinese translation. L17474–17641
 
 ## Optional
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vestra-player/sdk",
-  "version": "1.5.38",
+  "version": "1.5.39",
   "description": "Plugin API types, test host and plugin CLI for Vestra Player (apiVersion vestra/1)",
   "license": "Apache-2.0",
   "repository": {