@vestra-player/sdk 1.5.37 → 1.5.39

package/llms-full.txt

@@ -1,4 +1,4 @@
-# @vestra-player/sdk 1.5.37: 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.
 
@@ -329,11 +329,11 @@ The rule that follows: **state you change outside a handler, or after an `await`
 
 #### Stopping
 
-The player stops a plugin when the user disables or uninstalls it, when it is reloaded or upgraded, and when the player quits.
+The player stops a plugin when the user disables or uninstalls it, when it is reloaded or upgraded, when the player quits, and, with lazy activation, when nothing has used it for a while (Idle plugins).
 
 1. The player first removes everything the plugin owns on its side: menu items, windows, panels, settings pages, filter chains, subtitle layers, snapshots, export jobs, resolvers, generated streams.
 2. The SDK then refuses new requests, fails pending ones with `code: "disabled"` and disposes the root scope. That disposal only cleans up locally (timers, abort signals, sockets): the player-side resources are already gone.
-3. A process that has not exited 300 ms later is killed.
+3. A process that has not exited 300 ms later is killed (2 s later when it stops because it is idle).
 
 So `onDispose` cleanup must be quick and must not rely on the player. Media the plugin opened with player.open **keeps playing** after it stops.
 
@@ -344,7 +344,7 @@ A plugin's process does not live as long as the player. Within one player sessio
 - the plugin is **reloaded** (from the plugin manager, or a development load with `--plugin`) or **upgraded**;
 - it **crashed**, or failed to start, and is started again.
 
-A later player may restart a plugin in more cases: restarting plugins that share one process together when one of them faults or hangs, or stopping a plugin nobody uses and starting it on its next use. Write the plugin for those too.
+A later player may restart a plugin in more cases: restarting plugins that share one process together when one of them faults or hangs, or stopping a plugin nobody uses and starting it on its next use (Idle plugins). Write the plugin for those too.
 
 Everything in the process is gone after such a restart: variables, timers, caches, open sockets. The menus, windows and panels come back because `activate` creates them again. **Keep state that must survive a restart in session storage (or persistent storage):**
 
@@ -358,6 +358,16 @@ Session storage is for state that belongs to this run of the player: a queue the
 
 Write `activate` so that running it twice in one session is normal: read what you kept, then build the interface from it.
 
+#### Idle plugins are stopped
+
+With lazy activation (player 0.5.18 and later, while the player turns it on), the player works like a browser's extension service workers (Chrome Manifest V3): a plugin that holds nothing only its process can serve is stopped after about a minute without use, and started again by its next use.
+
+- **What stays while it is stopped**: its menu items and keys (with the last `enabled`, `checked` and `reason` it set), its settings pages, its file and link resolvers and its drop targets. Using one of them, or showing one of its settings pages, starts the plugin; it runs `activate`, registers them again, and then receives the click, the open or the drop. The player also remembers these between runs, so a plugin nobody uses is not started at launch at all.
+- **What keeps it running**: anything the player must deliver to it or that is its running work: a listener (`player.onChange`, `window.onChange`, `bindings.onChange`, `packages.onChange` and the other `onChange`, `onEnd`), a command state, panel or window binding that reads `plugin.player.state` or another state, an open window, a mounted panel, an OSD panel, a timeline layer, a filter chain, a stream or subtitle track it added, a next/previous provider, a sleep lease, a window setting, a job or snapshot in progress. Reading `plugin.player.state` inside a handler does not: the SDK reads the state again when the plugin starts.
+- **What does not keep it running**: work the player does not see. A `fetch`, a socket, a `setTimeout` or `setInterval`, or a promise the plugin awaits is lost when an idle plugin is stopped, as in Chrome. Set the command's `busy` while its work runs (a busy command keeps the plugin running), or keep what it needs in session storage and pick it up in `activate`.
+
+`TestHost.listening` lists the events a plugin really listens to; empty means listeners do not keep it running.
+
 #### The data directory
 
 plugin.dataDirectory is a writable directory for the plugin's own files (settings, caches, remembered folders). It needs no capability; the player creates it before it starts the plugin.
@@ -2699,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).
 
@@ -2720,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 |  |
@@ -2887,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
 
@@ -3879,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: {
     /**
@@ -3900,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.
      */
@@ -7445,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).
@@ -8213,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. */
@@ -9342,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;
@@ -9355,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)
 
@@ -9385,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).
@@ -9411,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) => {
@@ -9420,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.
@@ -10735,6 +10901,10 @@ interface PluginInfo {
    * The manifest's display texts in the interface language, translated with that package's catalog; absent from players before 0.4.3 (read `manifest.json` there).
    */
   display?: PluginDisplay;
+  /**
+   * For `state: "running"`: `"running"` while its process runs, `"idle"` while the player stopped it because nothing used it (lazy activation: it starts again on its next use, its menu items, keys, settings pages, resolvers and drop targets stay). Absent in other states and from players before 0.5.18. A change between the two alone does not fire Packages.onChange.
+   */
+  process?: "running" | "idle";
 }
 ```
 
@@ -11835,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. |
@@ -12203,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";
 };
 ```
 
@@ -12224,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
@@ -12796,6 +13009,10 @@ class TestHost implements Transport {
   readonly calls: Call[];
   /** The host events the plugin subscribed to (needs `events` etc.). */
   readonly subscriptions: Set<string>;
+  /**
+   * The subscribed events the plugin really listens to: an `onChange` and the like, or a binding that reads the state. The SDK's own copies of the state (what keeps `plugin.player.state` current) are left out. Empty means the player may stop the plugin while nothing uses it (unless it holds something else: a window, a panel, a filter…).
+   */
+  readonly listening: Set<string>;
   /**
    * The player's source facts (phase, position, duration, paused, rate, audio tracks, loop, ...). Wire-level shape; change it with TestHost.setSource, which also broadcasts it.
    */
@@ -13376,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
@@ -13637,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),
@@ -13647,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();
    * ```
    */
@@ -15082,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
@@ -15341,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.37: 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: L2636–2706.
+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: L2707–2767.
+- 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: L2077–2265; TestHost: L12744.
+**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,39 +108,39 @@ 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 L3770.
+- Others: PluginError, llms-full.txt L3797.
 
 ## Reference
 
 - [llms-full.txt](https://vestrasys.github.io/vestra-player-sdk/llms-full.txt), also node_modules/@vestra-player/sdk/llms-full.txt; pages: [site](https://vestrasys.github.io/vestra-player-sdk/).
 - Tutorials: Getting started L9–237
-- Concepts: How a plugin runs L238–408; Commands, menus and key bindings L409–520; Playback state, controls and sources L521–666; Video and audio processing L667–753; Windows, panels, settings pages, dialogs and the OSD L754–1042
-- How-to: Control playback L1043–1171; Store a plugin's data L1172–1239; Load subtitles from a plugin L1240–1318; Keep a slider responsive while dragging L1319–1493; Remember a window's state between runs L1494–1623; Offer a GPU rendering switch L1624–1744; Translate a plugin L1745–1928; Migrate a plugin to English source text L1929–2076; Test a plugin L2077–2265; Publish a plugin L2266–2354; Migrating off package rollback (1.5.16, removed in 1.5.17) L2355–2430
-- Guidelines: Interface guidelines L2431–2538; Menu guidelines L2539–2635
-- Reference: Manifest L2636–2706; Capabilities L2707–2767; Limits L2768–2897; Commands, menus and bindings L2898–3381; Platforms L3382–3412; Theme L3413–3634; Command line L3635–3692
-- [API: @vestra-player/sdk](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk.html): L3693–12428
-- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html): L12429–15144
+- 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–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 L4096, Scope L3845, PluginError L3770, Disposable L3708
-- Commands L4493; Windows L5430; Panels L6876; Dialogs L7544; Player L8285; video: VideoFilter L9165, VideoView L9265, RenderOptions L9352, VideoUpscaling L9548; audio: AudioFilter L9210; Subtitles L9744; media: MediaCapture L10148; Resolvers L10378; Packages L10776; Osd L9030; Host L8872; Clipboard L11104; Power L11191; Tools L11250; Storage L11402; System L11601; Secrets L11681; window: MainWindow L7193; App L7373; Rendering L11944; Bindings L11004; Ui L4782; Timeline L7105; Drops L6123; Appearance L6204; I18n L6437; Settings L6720.
+- 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. L15579–15668
-- blur: A tool window with one slider that blurs the playing video. L15669–15930
-- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L15931–16263
-- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L16264–16450
-- panel-menu: A sidebar panel with its own right-click menu. L16451–16659
-- menus: Radio menu items, separator groups and a menu item whose title changes. L16660–16819
-- theme-widgets: A tool window drawn with the player's theme and widgets. L16820–16983
-- markdown: A window that shows a Markdown document. L16984–17180
-- i18n: A plugin in the player's language: English source text, a Chinese translation. L17181–17348
+- 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.37",
+  "version": "1.5.39",
   "description": "Plugin API types, test host and plugin CLI for Vestra Player (apiVersion vestra/1)",
   "license": "Apache-2.0",
   "repository": {