@vestra-player/sdk 1.5.42 → 1.5.43

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 1.5.43
+
+**Who must change: nobody.** Additions only, `apiVersion` stays `vestra/1`, no new capability. The new API needs player 0.5.25 (`"minPlayerVersion": "0.5.25"`); older players leave the new fields out and refuse the new event (the listener never fires). The `decoding` reason code stays as it is: the cause is a new optional field beside it.
+
+- **`UpscalingReason.cause`** (player 0.5.25): with code `decoding`, why the video is not decoded on the GPU that renders it, as a stable `UpscalingDecodingCause`: `copy-back` (decoded on the GPU and copied back to memory, usually because a plugin's video filter needs the frames there), `hwdec-off` (hardware decoding off), `software` (this video is decoded in software: a cover picture, an unsupported format), `other-hwdec` (another hardware decoder). A newer player may add causes. With `copy-back`, **`UpscalingReason.plugins`** lists whose video filters made the player switch (`UpscalingPlugin`: manifest `id` and `name`; empty when the copy-back mode is the user's own setting), and the message names them ("…because the video filter of Picture Adjustments needs the frames in memory").
+- **Monitoring fields in `UpscalingState`** (player 0.5.25, optional: absent from older players): `video` (the video's stored and display size as the upscaler gets it, `UpscalingVideoSize`), `area` (the video area in pixels), `gpu` (the rendering GPU's name), `hwdecCurrent` (mpv's decoder for this video), `inChain` (the upscaler is in the filter chain now, read from the chain). The driver still gives no sign that it upscales.
+- **`plugin.video.upscaling.onChange(listener)`** (player 0.5.25, `video.upscaling`): the state whenever it changes while some plugin has upscaling on (the player looks about five times a second and sends only differences), so a window can show it live without polling. Wire: event `video.upscaling.changed` with the state without `enabled` (the SDK adds this plugin's own); subscribing needs `video.upscaling`, not `events`. A listener keeps the plugin running (it is not an event the player wakes a stopped plugin for): listen only while a window shows the state. The manifest names in `plugins` and the message are not translated.
+- **`TestHost`**: `upscalingDecoding(cause, plugins?)` fakes each cause with the player's message (and a matching `upscaling.hwdecCurrent`); `upscaling.video`, `area`, `gpu`, `hwdecCurrent` (defaults: 1080p on a 4K area, an RTX 4070, `d3d11va`; `inChain` follows `requested`); `upscalingChanged()` sends the event to a listening plugin.
+- The player's capability table copy (`video.upscaling.changed` under `video.upscaling`) and `CAPABILITY_INFO` (`VideoUpscaling.onChange`) follow.
+
+
 ## 1.5.42
 
 **Who must change: nobody.** Documentation only: no API changes, `apiVersion` stays `vestra/1`, no player version needed. The package's code is the same as 1.5.41; the doc comments' `@see` links (27 in `src/plugin/types.ts`) now point at `docs/explanation/` instead of `docs/concepts/`. The site's page addresses stay the same, and the old _Concepts_ group address redirects to _Explanation_; `llms.txt` and `llms-full.txt` follow the new pages.

package/dist/api-requests.js

@@ -146,4 +146,5 @@ export const API_REQUESTS = Object.freeze({
     "Rendering.restartPlayer": [{ method: "rendering.restart" }],
     "VideoUpscaling.state": [{ method: "video.upscaling.state" }],
     "VideoUpscaling.set": [{ method: "video.upscaling.set" }],
+    "VideoUpscaling.onChange": [listen("video.upscaling.changed")],
 });

package/dist/host-capabilities.js

@@ -85,6 +85,7 @@ export const HOST_CAPABILITIES = {
                         cases: {
                             "bindings.changed": "bindings.manage",
                             "packages.changed": null,
+                            "video.upscaling.changed": "video.upscaling",
                         },
                         otherwise: "events",
                         param: "event",
@@ -96,6 +97,7 @@ export const HOST_CAPABILITIES = {
                         cases: {
                             "bindings.changed": "bindings.manage",
                             "packages.changed": null,
+                            "video.upscaling.changed": "video.upscaling",
                         },
                         otherwise: "events",
                         param: "event",

package/dist/plugin/services.js

@@ -508,16 +508,38 @@ export const videoUpscaling = (scope) => {
         if (!scope.runtime.can("video.upscaling"))
             throw failure("capability", "video.upscaling must be declared in manifest");
     };
+    // This plugin's own request, kept from every answer for `onChange`: the
+    // event leaves it out (it is each plugin's own), and only this plugin's
+    // `set` changes it.
+    const noted = (state) => {
+        enabledOf.set(scope.runtime, state.enabled);
+        return state;
+    };
     return {
         async state() {
             declared();
-            return (await scope.runtime.host.video.upscalingState());
+            return noted(await scope.runtime.host.video.upscalingState());
         },
         async set(enabled) {
             declared();
             if (typeof enabled !== "boolean")
                 throw failure("invalid", "enabled must be true or false");
-            return (await scope.runtime.host.video.upscalingSet(enabled));
+            return noted(await scope.runtime.host.video.upscalingSet(enabled));
+        },
+        onChange(listener) {
+            declared();
+            const watch = scope.runtime.on("video.upscaling.changed", (data) => scope.run(listener, {
+                ...data,
+                enabled: enabledOf.get(scope.runtime) ?? false,
+            }), "video.upscaling");
+            return scope.add({
+                dispose: async () => {
+                    scope.forget(watch);
+                    await watch.dispose();
+                },
+            });
         },
     };
 };
+/** Each plugin's own upscaling request, as its last answer said. */
+const enabledOf = new WeakMap();

package/dist/plugin/testing.d.ts

@@ -16,7 +16,7 @@ import type { CommandDeclaration } from "../commands.ts";
 import type { SourceState } from "../source.ts";
 import type { SubtitleState } from "../subtitles.ts";
 import { VIDEO_PROCESSING_LIMITS } from "../processing.ts";
-import type { RenderingMode, RenderingPreference, RenderingReason, RenderSettings, UpscalingReason, ViewSettings } from "./types.ts";
+import type { RenderingMode, RenderingPreference, RenderingReason, RenderSettings, UpscalingDecodingCause, UpscalingPlugin, UpscalingReason, UpscalingVideoSize, ViewSettings } from "./types.ts";
 import type { MediaJob } from "../media.ts";
 import type { LanguagePreference, Locale, Plugin, TemplateArgs, TextValue, ThemeId } from "./types.ts";
 import { LOCALES, LIST_SEPARATORS, TEXT_LIMITS } from "../i18n.ts";
@@ -1862,7 +1862,71 @@ export declare class TestHost implements Transport {
         checked: boolean;
         /** GPU rendering is still starting: a `rendering` reason then lets `set(true)` keep the request. */
         renderingStarting: boolean;
+        /** The video's size the state reports (player 0.5.25); `null`: no video. */
+        video: UpscalingVideoSize | null;
+        /** The video area the state reports (player 0.5.25); `null`: none. */
+        area: {
+            /** Width in physical pixels. */
+            width: number;
+            /** Height in physical pixels. */
+            height: number;
+        } | null;
+        /** The rendering GPU's name the state reports (player 0.5.25). */
+        gpu: string | null;
+        /** mpv's decoder the state reports (player 0.5.25); `null`: no video. */
+        hwdecCurrent: string | null;
     };
+    /**
+     * Make the upscaler's reason `decoding` with `cause`, with the player's
+     * message (player 0.5.25), and set `upscaling.hwdecCurrent` to match
+     * (`d3d11va-copy`, `no`, `nvdec`). `plugins` are named for `copy-back`
+     * only, as the player does. Returns the reason; call
+     * {@link TestHost.upscalingChanged} to tell a listening plugin.
+     *
+     * @example Test the window's advice for each cause
+     * The plugin's window explains why upscaling waits. The test fakes the
+     * copy-back cause that Picture Adjustments' filters cause and checks
+     * that the window names the plugin.
+     * ```ts
+     * import assert from "node:assert/strict";
+     * declare const host: TestHost;
+     * // ---cut---
+     * host.upscalingDecoding("copy-back", [{ id: "vestra.video", name: "Picture Adjustments" }]);
+     * host.upscalingChanged();
+     * await host.settle();
+     * assert.match(String(host.window("upscale").props.blocker), /Picture Adjustments/);
+     * ```
+     *
+     * @capability None.
+     * @since 1.5.43
+     */
+    upscalingDecoding(cause: UpscalingDecodingCause, plugins?: readonly UpscalingPlugin[]): UpscalingReason;
+    /**
+     * Send `video.upscaling.changed` with the state {@link TestHost.upscaling}
+     * describes now (without `enabled`), as the player does when it changes
+     * (player 0.5.25); a plugin listening with
+     * `plugin.video.upscaling.onChange` receives it. Nothing reaches a plugin
+     * that does not listen.
+     *
+     * @capability None.
+     *
+     * @example Show the new factor in the plugin's window
+     * The window resized: the test changes the area and the factor, sends
+     * the change, and checks that the plugin's window shows the new factor.
+     * ```ts
+     * import assert from "node:assert/strict";
+     * declare const host: TestHost;
+     * // ---cut---
+     * host.upscaling.area = { width: 2560, height: 1440 };
+     * host.upscaling.factor = 1.33; // 1080p in a 1440p area
+     * host.upscalingChanged(); // as the player after the resize settled
+     * await host.settle();
+     * assert.equal(host.window("upscale").props.factor, "×1.33");
+     * ```
+     *
+     * @since 1.5.43
+     */
+    upscalingChanged(): void;
     /** What `player.chapters()` lists while media is ready. */
     chapters: {
         /** The chapter title, `null` without one. */

package/dist/plugin/testing.js

@@ -1837,7 +1837,104 @@ export class TestHost {
         factor: 2,
         checked: false,
         renderingStarting: false,
+        video: {
+            width: 1920,
+            height: 1080,
+            displayWidth: 1920,
+            displayHeight: 1080,
+        },
+        area: { width: 3840, height: 2160 },
+        gpu: "NVIDIA GeForce RTX 4070 Laptop GPU",
+        hwdecCurrent: "d3d11va",
     };
+    /**
+     * Make the upscaler's reason `decoding` with `cause`, with the player's
+     * message (player 0.5.25), and set `upscaling.hwdecCurrent` to match
+     * (`d3d11va-copy`, `no`, `nvdec`). `plugins` are named for `copy-back`
+     * only, as the player does. Returns the reason; call
+     * {@link TestHost.upscalingChanged} to tell a listening plugin.
+     *
+     * @example Test the window's advice for each cause
+     * The plugin's window explains why upscaling waits. The test fakes the
+     * copy-back cause that Picture Adjustments' filters cause and checks
+     * that the window names the plugin.
+     * ```ts
+     * import assert from "node:assert/strict";
+     * declare const host: TestHost;
+     * // ---cut---
+     * host.upscalingDecoding("copy-back", [{ id: "vestra.video", name: "Picture Adjustments" }]);
+     * host.upscalingChanged();
+     * await host.settle();
+     * assert.match(String(host.window("upscale").props.blocker), /Picture Adjustments/);
+     * ```
+     *
+     * @capability None.
+     * @since 1.5.43
+     */
+    upscalingDecoding(cause, plugins = []) {
+        const needs = "upscaling needs it decoded on the GPU that renders it (d3d11va)";
+        const names = plugins.map((p) => p.name);
+        const because = names.length === 0
+            ? "for example because a video filter needs the frames in memory"
+            : names.length === 1
+                ? `because the video filter of ${names[0]} needs the frames in memory`
+                : `because the video filters of ${names.join(", ")} need the frames in memory`;
+        const [message, current] = cause === "copy-back"
+            ? [
+                `the video is decoded with copy-back (auto-copy-safe), ${because}; ${needs}`,
+                "d3d11va-copy",
+            ]
+            : cause === "hwdec-off"
+                ? [
+                    "hardware decoding is off; upscaling needs the video decoded on the GPU that renders it (d3d11va)",
+                    "no",
+                ]
+                : cause === "software"
+                    ? [`this video is decoded in software; ${needs}`, "no"]
+                    : [`this video is decoded with nvdec; ${needs}`, "nvdec"];
+        const reason = cause === "copy-back"
+            ? {
+                code: "decoding",
+                message,
+                cause,
+                plugins: plugins.map(({ id, name }) => ({ id, name })),
+            }
+            : { code: "decoding", message, cause };
+        this.upscaling.reason = reason;
+        this.upscaling.hwdecCurrent = current;
+        return reason;
+    }
+    /**
+     * Send `video.upscaling.changed` with the state {@link TestHost.upscaling}
+     * describes now (without `enabled`), as the player does when it changes
+     * (player 0.5.25); a plugin listening with
+     * `plugin.video.upscaling.onChange` receives it. Nothing reaches a plugin
+     * that does not listen.
+     *
+     * @capability None.
+     *
+     * @example Show the new factor in the plugin's window
+     * The window resized: the test changes the area and the factor, sends
+     * the change, and checks that the plugin's window shows the new factor.
+     * ```ts
+     * import assert from "node:assert/strict";
+     * declare const host: TestHost;
+     * // ---cut---
+     * host.upscaling.area = { width: 2560, height: 1440 };
+     * host.upscaling.factor = 1.33; // 1080p in a 1440p area
+     * host.upscalingChanged(); // as the player after the resize settled
+     * await host.settle();
+     * assert.equal(host.window("upscale").props.factor, "×1.33");
+     * ```
+     *
+     * @since 1.5.43
+     */
+    upscalingChanged() {
+        if (!this.subscriptions.has("video.upscaling.changed"))
+            return;
+        const { enabled: _, ...state } = this.#upscalingState(false);
+        this.emit("video.upscaling.changed", state);
+    }
     /** What `player.chapters()` lists while media is ready. */
     chapters = [];
     #overrides = new Map();
@@ -3481,12 +3578,20 @@ export class TestHost {
                 message: "the player has not checked the GPU yet; state() or set(true) checks it",
             };
         const requested = enabled && reason === null && factor !== null && factor > 1;
+        const { video, area, gpu, hwdecCurrent } = this.upscaling;
         return {
             available: reason === null,
-            reason: reason ? { ...reason } : null,
+            reason: reason
+                ? structuredClone(reason)
+                : null,
             enabled,
             requested,
             factor: requested ? factor : null,
+            video: video ? { ...video } : null,
+            area: area ? { ...area } : null,
+            gpu,
+            hwdecCurrent,
+            inChain: requested,
         };
     }
     /** `rendering.state` from {@link TestHost.rendering} and `videoRender.gpu`. */

package/dist/plugin/types.d.ts

@@ -6870,7 +6870,7 @@ export interface VideoShaders extends Disposable {
  * | `gpu-unsupported` | The driver does not offer upscaling on this GPU (Windows: not an RTX GPU), or the check failed. |
  * | `rendering` | The player renders in software, or GPU rendering is still starting; upscaling needs GPU rendering ({@link Rendering}). |
  * | `adapter` | GPU rendering runs on another GPU than the one that can upscale (a laptop with two GPUs; Windows: choose the high-performance GPU for Vestra in Settings ▸ System ▸ Display ▸ Graphics). |
- * | `decoding` | The video is not decoded on the GPU that renders it: copy-back or software decoding, for example while a {@link VideoFilter} needs the frames in memory. |
+ * | `decoding` | The video is not decoded on the GPU that renders it: copy-back or software decoding, for example while a {@link VideoFilter} needs the frames in memory. {@link UpscalingReason.cause} says which, and {@link UpscalingReason.plugins} whose filters (newer players; see there). |
  * | `unchecked` | The player has not checked the GPU yet. Only in the answer to `set(false)`, which never starts the check; `state()` and `set(true)` always check first. |
  *
  * `decoding` and `rendering` while GPU rendering is still starting can pass
@@ -6925,6 +6925,93 @@ export interface UpscalingReason {
      * and what to change; never branch on it.
      */
     readonly message: string;
+    /**
+     * With code `decoding` only: why the video is not decoded on the GPU
+     * that renders it ({@link UpscalingDecodingCause}). Absent with every
+     * other code, and from players before 0.5.25.
+     *
+     * @player 0.5.25; older players send `decoding` without a cause.
+     * @since 1.5.43
+     */
+    readonly cause?: UpscalingDecodingCause;
+    /**
+     * With cause `copy-back` only: the plugins whose video filters need the
+     * frames in memory, which is why the player switched to copy-back
+     * decoding, in the order the plugins started (each plugin once). Name
+     * them to the user, who can turn the filters off there. Empty when
+     * the copy-back decoding is not one the player chose for a filter (the
+     * user's own `hwdec` setting). Absent with any other cause, and from
+     * players before 0.5.25.
+     *
+     * @player 0.5.25
+     * @since 1.5.43
+     */
+    readonly plugins?: readonly UpscalingPlugin[];
+}
+/**
+ * Why the video is not decoded on the GPU that renders it: the
+ * {@link UpscalingReason.cause} of a `decoding` reason (player 0.5.25). A
+ * newer player may add causes: show {@link UpscalingReason.message} for the
+ * ones you do not handle.
+ *
+ * | Cause | Meaning |
+ * | --- | --- |
+ * | `copy-back` | Decoded on the GPU and copied back to memory, because a plugin's video filter needs the frames there ({@link UpscalingReason.plugins} names it), or because of the user's `hwdec` setting. |
+ * | `hwdec-off` | Hardware decoding is turned off (mpv's `hwdec` is `no`). |
+ * | `software` | This video is decoded in software: a cover picture, a format the GPU does not decode, or a hardware decoder that failed. It passes with the next video. |
+ * | `other-hwdec` | This video is decoded with another hardware decoder than the one the upscaler needs. |
+ *
+ * @example Name the plugins whose filters block upscaling
+ * A plugin's upscaling window explains a `decoding` reason by its cause,
+ * and for `copy-back` names the plugins whose filters stand in the way, so
+ * the user can turn them off there (a plugin cannot run another plugin's
+ * commands).
+ * ```ts
+ * const { reason } = await plugin.video.upscaling.state();
+ * if (reason?.code === "decoding" && reason.cause === "copy-back") {
+ *   const names = (reason.plugins ?? []).map((p) => p.name).join(", ");
+ *   // Ask the user to reset those filters; the manifest names are not translated.
+ *   console.log(names ? `Turn off the video filters of ${names}` : reason.message);
+ * } else if (reason) console.log(reason.message);
+ * ```
+ *
+ * @player 0.5.25
+ * @since 1.5.43
+ * @category Processing
+ */
+export type UpscalingDecodingCause = "copy-back" | "hwdec-off" | "software" | "other-hwdec" | (string & {});
+/**
+ * A plugin named in an {@link UpscalingReason}: its manifest id and its
+ * name for people, as its manifest gives it (not translated).
+ *
+ * @player 0.5.25
+ * @since 1.5.43
+ * @category Processing
+ */
+export interface UpscalingPlugin {
+    /** The plugin's manifest id, for example `vestra.video`. */
+    readonly id: string;
+    /** The manifest's `name` as is (its id without one), for people. */
+    readonly name: string;
+}
+/**
+ * The video's size as the upscaler gets it ({@link UpscalingState.video}):
+ * the decoder's frame size, width and height swapped for the file's
+ * quarter-turn rotation metadata.
+ *
+ * @player 0.5.25
+ * @since 1.5.43
+ * @category Processing
+ */
+export interface UpscalingVideoSize {
+    /** The frames' stored width in pixels. */
+    readonly width: number;
+    /** The frames' stored height in pixels. */
+    readonly height: number;
+    /** The width the video is meant to be shown at (non-square pixels). */
+    readonly displayWidth: number;
+    /** The height the video is meant to be shown at. */
+    readonly displayHeight: number;
 }
 /**
  * What {@link VideoUpscaling.state} and {@link VideoUpscaling.set} report:
@@ -6980,6 +7067,59 @@ export interface UpscalingState {
      * nothing is requested.
      */
     readonly factor: number | null;
+    /**
+     * The video's size as the upscaler gets it; `null` while no video
+     * decodes. With {@link UpscalingState.area} it explains the factor.
+     * Absent from players before 0.5.25.
+     *
+     * @player 0.5.25
+     * @since 1.5.43
+     */
+    readonly video?: UpscalingVideoSize | null;
+    /**
+     * The area the video is shown in, in pixels (the upscaler scales the
+     * video to fit it); `null` while the player shows no video area. Absent
+     * from players before 0.5.25.
+     *
+     * @player 0.5.25
+     * @since 1.5.43
+     */
+    readonly area?: {
+        /** Width in physical pixels. */
+        readonly width: number;
+        /** Height in physical pixels. */
+        readonly height: number;
+    } | null;
+    /**
+     * The name of the GPU that renders, for example `NVIDIA GeForce RTX 4070
+     * Laptop GPU`; `null` in software rendering and where the player does not
+     * know it (macOS, Linux). Absent from players before 0.5.25.
+     *
+     * @player 0.5.25
+     * @since 1.5.43
+     */
+    readonly gpu?: string | null;
+    /**
+     * The hardware decoder in use for this video, as mpv names it (`d3d11va`,
+     * `d3d11va-copy`; `no` for software decoding); `null` while no video
+     * decodes. For people and logs: branch on {@link UpscalingReason.cause}.
+     * Absent from players before 0.5.25.
+     *
+     * @player 0.5.25
+     * @since 1.5.43
+     */
+    readonly hwdecCurrent?: string | null;
+    /**
+     * The upscaler is in the player's video filter chain now, read from the
+     * chain itself (`requested` is what the player asked for; they differ
+     * only for a moment, while the chain changes). Still not a sign that the
+     * GPU upscales: the driver gives none (see the remarks). Absent from
+     * players before 0.5.25.
+     *
+     * @player 0.5.25
+     * @since 1.5.43
+     */
+    readonly inChain?: boolean;
 }
 /**
  * `plugin.video.upscaling`: the GPU's video upscaler, NVIDIA RTX Video
@@ -7119,6 +7259,57 @@ export interface VideoUpscaling {
      * @since 1.5.37
      */
     set(enabled: boolean): Promise<UpscalingState>;
+    /**
+     * Call `listener` with the new state whenever it changes while some
+     * plugin has upscaling on: the factor, whether the upscaler is in the
+     * chain, the reason, the video's and the area's size, the decoder. A
+     * window that shows how upscaling runs listens instead of polling
+     * {@link VideoUpscaling.state}.
+     *
+     * @remarks
+     * The player looks about five times a second while upscaling is on for
+     * any plugin (a window resize sends at most that many), and sends a
+     * change only when something differs; after the last plugin turns it
+     * off one more change says so, then nothing until it is on again: read
+     * {@link VideoUpscaling.state} when you need the state then. Nothing is
+     * sent before the player's GPU check ran (the first `state()` or
+     * `set(true)` of any plugin). `enabled` is this plugin's own request, as
+     * in `state()`. The message of a `rendering` reason can be shorter than
+     * the one `state()` gives (it may leave out what to do).
+     *
+     * **A listener keeps the plugin running.** `video.upscaling.changed` is
+     * not an event the player wakes a stopped plugin for: while the plugin
+     * listens, the player does not stop it while idle (lazy activation), even
+     * with upscaling off. Listen only while a window that shows the state is
+     * open, and dispose of the listener when it closes. Players before 0.5.25 do not know the event: the listener
+     * never fires and the SDK logs that the player refused the subscription.
+     *
+     * @capability video.upscaling
+     * @param listener - Receives the new state.
+     * @returns Stops listening; also when the scope that added it is
+     *   disposed.
+     * @throws `capability` (synchronously) The manifest does not declare
+     *   `video.upscaling`.
+     *
+     * @example Show how upscaling runs while a window is open
+     * The plugin's window shows the factor, the sizes and the GPU while it
+     * is open; the listener goes when the window closes, so the plugin can
+     * be stopped while idle again.
+     * ```ts
+     * // When the window opens:
+     * const watch = plugin.video.upscaling.onChange((state) => {
+     *   const video = state.video ? `${state.video.width}×${state.video.height}` : "no video";
+     *   const area = state.area ? `${state.area.width}×${state.area.height}` : "—";
+     *   console.log(`${video} → ${area}, ×${state.factor ?? 1}, ${state.gpu ?? "no GPU"}`);
+     * });
+     * // When it closes: stop listening (it keeps the plugin running).
+     * await watch.dispose();
+     * ```
+     *
+     * @player 0.5.25
+     * @since 1.5.43
+     */
+    onChange(listener: (state: UpscalingState) => void): Disposable;
 }
 /**
  * A subtitle track of the current source.

package/dist/wire.d.ts

@@ -338,14 +338,41 @@ export interface WireRenderingState {
         reason: WireRenderingReason | null;
     };
 }
-/** `video.upscaling.state` and `video.upscaling.set` (player 0.5.16). */
+/**
+ * An upscaling reason: `{ code, message }` as a rendering reason; with
+ * `decoding` a `cause`, with cause `copy-back` the `plugins` (player 0.5.25).
+ */
+export interface WireUpscalingReason extends WireRenderingReason {
+    cause?: string;
+    plugins?: {
+        id: string;
+        name: string;
+    }[];
+}
+/**
+ * `video.upscaling.state` and `video.upscaling.set` (player 0.5.16); the
+ * monitoring fields from player 0.5.25, which also sends the state without
+ * `enabled` as the event `video.upscaling.changed`.
+ */
 export interface WireUpscalingState {
     available: boolean;
-    /** The same `{ code, message }` shape as a rendering reason. */
-    reason: WireRenderingReason | null;
+    reason: WireUpscalingReason | null;
     enabled: boolean;
     requested: boolean;
     factor: number | null;
+    video?: {
+        width: number;
+        height: number;
+        displayWidth: number;
+        displayHeight: number;
+    } | null;
+    area?: {
+        width: number;
+        height: number;
+    } | null;
+    gpu?: string | null;
+    hwdecCurrent?: string | null;
+    inChain?: boolean;
 }
 /**
  * Template arguments on the wire (`osd.show`, `osd.panel`, `dialogs.confirm`,
@@ -368,7 +395,7 @@ export interface Transport {
     locale?: string;
 }
 /** The events a plugin subscribes to (`events.subscribe`). */
-type HostEvent = "source.state" | "playback.backend" | "window.state" | "packages.changed" | "bindings.changed" | "timeline.changed" | "appearance.changed" | "resolvers.fileTypes";
+type HostEvent = "source.state" | "playback.backend" | "window.state" | "packages.changed" | "bindings.changed" | "timeline.changed" | "appearance.changed" | "resolvers.fileTypes" | "video.upscaling.changed";
 export declare function createWire(transport: Transport): {
     processing: {
         state: () => Promise<import("./processing.ts").ProcessingState>;

package/llms-full.txt

@@ -1,4 +1,4 @@
-# @vestra-player/sdk 1.5.42: full reference
+# @vestra-player/sdk 1.5.43: 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.
 
@@ -2281,6 +2281,7 @@ The table lists the API whose documentation names a player version, newest last:
 | 0.5.16 | UpscalingReasonCode, UpscalingReason, UpscalingState, VideoUpscaling |
 | 0.5.20 | VideoShaders |
 | 0.5.21 | Scope.when, When, Bindings.onChange |
+| 0.5.25 | UpscalingReason.cause, UpscalingReason.plugins, UpscalingDecodingCause, UpscalingPlugin, UpscalingVideoSize, UpscalingState.video, UpscalingState.area, UpscalingState.gpu, UpscalingState.hwdecCurrent, UpscalingState.inChain, VideoUpscaling.onChange |
 
 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).
 
@@ -2318,7 +2319,7 @@ A plugin lists what it may do in the manifest's `capabilities` (Manifest). A cal
 | `ui.theme` | Appearance.set, Appearance.setLanguage | — | Change the player's palette |  |
 | `secrets` | Secrets.get, Secrets.set, Secrets.delete | — | Store sign-in details in the system keychain | yes |
 | `rendering.manage` | Rendering.setPreference, Rendering.restartPlayer | — | Choose GPU or software rendering and restart the player | yes |
-| `video.upscaling` | VideoUpscaling.state, VideoUpscaling.set | — | Upscale the video with the GPU's video upscaler |  |
+| `video.upscaling` | VideoUpscaling.state, VideoUpscaling.set, VideoUpscaling.onChange | — | Upscale the video with the GPU's video upscaler |  |
 
 **Also needs** applies to every member of the row: declare those capabilities as well. A few members or options need one more, documented at the member:
 
@@ -3654,6 +3655,8 @@ It rejects when nothing is bound to the key or the command it would run is busy.
 | TestHost.app | What `plugin.app` reports. |
 | TestHost.rendering | The player's rendering choice behind `plugin.rendering` (player 0.5.13). |
 | TestHost.upscaling | The GPU's video upscaler behind `plugin.video.upscaling` (player 0.5.16), answered as the player would: - `state()` and `set(true)` set `checked` (the player's one GPU check; a plugin that should not wake the GPU while it starts can assert it is still `false`) and report `available` from `reason` (`null`: it works), this plugin's `enabled`, and `requested` with `factor` while enabled, available and `factor` is above 1. |
+| TestHost.upscalingDecoding() | Make the upscaler's reason `decoding` with `cause`, with the player's message (player 0.5.25), and set `upscaling.hwdecCurrent` to match (`d3d11va-copy`, `no`, `nvdec`). |
+| TestHost.upscalingChanged() | Send `video.upscaling.changed` with the state `TestHost.upscaling` describes now (without `enabled`), as the player does when it changes (player 0.5.25); a plugin listening with `plugin.video.upscaling.onChange` receives it. |
 | TestHost.chapters | What `player.chapters()` lists while media is ready. |
 | TestHost.dataDirectory | `plugin.dataDirectory`: a fresh empty temporary directory, removed with the host on `stop()`. |
 | TestHost.manifestId | The manifest id of the plugin under test (set by `startPlugin`; `"test.plugin"` by default). |
@@ -4324,8 +4327,9 @@ plugin.video.shaders(id) (player 0.5.20) returns a VideoShaders handle: a list o
 plugin.video.upscaling (capability `video.upscaling`, player 0.5.16) turns on the GPU's AI upscaler, NVIDIA RTX Video Super Resolution on Windows. It is not a handle: `set(true)` is the plugin's request, and the player keeps the upscaler last in the filter chain, after every plugin's chain, while any plugin has it on and it can work, scaled to the area the video is shown in. Like render options it acts at display time only.
 
 - **Ask when needed.** The player checks the GPU at the first `state()` or `set(true)` and keeps the answer; the check wakes a sleeping discrete GPU, so ask on the first pick of the item, not while the plugin starts. `set(false)` never checks.
-- **It needs GPU rendering on the upscaler's GPU, with the video decoded there.** A filter chain that needs the frames in memory switches decoding to copy-back, and the upscaler waits (`decoding`) until it is gone.
+- **It needs GPU rendering on the upscaler's GPU, with the video decoded there.** A filter chain that needs the frames in memory switches decoding to copy-back, and the upscaler waits (`decoding`) until it is gone. From player 0.5.25 the reason's `cause` says which decoding stands in the way (`copy-back`, `hwdec-off`, `software`, `other-hwdec`), and with `copy-back` its `plugins` say whose filters, so a window can ask the user to turn them off there.
 - **No sign that it runs.** `requested` says the player asked the driver; on Windows the user must also turn on Super Resolution in the NVIDIA app, which no program can read.
+- **Watch it while it runs.** From player 0.5.25 the state also has the video's and the area's size, the rendering GPU, the decoder and `inChain`, and onChange sends it as it changes while some plugin has upscaling on. A listener keeps the plugin running, so listen only while a window shows it.
 
 ## Explanation: Windows, panels, settings pages, dialogs and the OSD
 
@@ -5708,6 +5712,7 @@ Every SDK release's CHANGELOG entry opens with who must change and what happens
 
 | Release | Who must change | Guide |
 | --- | --- | --- |
+| [1.5.43](https://github.com/vestrasys/vestra-player-sdk/blob/main/CHANGELOG.md#1543) | **Nobody.** Additions only, `apiVersion` stays `vestra/1`, no new capability. | — |
 | [1.5.42](https://github.com/vestrasys/vestra-player-sdk/blob/main/CHANGELOG.md#1542) | **Nobody.** Documentation only: no API changes, `apiVersion` stays `vestra/1`, no player version needed. | — |
 | [1.5.41](https://github.com/vestrasys/vestra-player-sdk/blob/main/CHANGELOG.md#1541) | **Nobody.** No API changes, `apiVersion` stays `vestra/1`, no player version needed. | — |
 | [1.5.40](https://github.com/vestrasys/vestra-player-sdk/blob/main/CHANGELOG.md#1540) | **Nobody.** Additions only, `apiVersion` stays `vestra/1`. | — |
@@ -11839,7 +11844,7 @@ in the order the player checks them (the first that holds is reported):
 | `gpu-unsupported` | The driver does not offer upscaling on this GPU (Windows: not an RTX GPU), or the check failed. |
 | `rendering` | The player renders in software, or GPU rendering is still starting; upscaling needs GPU rendering (Rendering). |
 | `adapter` | GPU rendering runs on another GPU than the one that can upscale (a laptop with two GPUs; Windows: choose the high-performance GPU for Vestra in Settings ▸ System ▸ Display ▸ Graphics). |
-| `decoding` | The video is not decoded on the GPU that renders it: copy-back or software decoding, for example while a VideoFilter needs the frames in memory. |
+| `decoding` | The video is not decoded on the GPU that renders it: copy-back or software decoding, for example while a VideoFilter needs the frames in memory. UpscalingReason.cause says which, and UpscalingReason.plugins whose filters (newer players; see there). |
 | `unchecked` | The player has not checked the GPU yet. Only in the answer to `set(false)`, which never starts the check; `state()` and `set(true)` always check first. |
 
 `decoding` and `rendering` while GPU rendering is still starting can pass
@@ -11883,6 +11888,16 @@ interface UpscalingReason {
   readonly code: UpscalingReasonCode;
   /** The reason as English text for people, for example with the GPU's name and what to change; never branch on it. */
   readonly message: string;
+  /**
+   * With code `decoding` only: why the video is not decoded on the GPU that renders it (UpscalingDecodingCause). Absent with every other code, and from players before 0.5.25.
+   * @player 0.5.25; older players send `decoding` without a cause.
+   */
+  readonly cause?: UpscalingDecodingCause;
+  /**
+   * With cause `copy-back` only: the plugins whose video filters need the frames in memory, which is why the player switched to copy-back decoding, in the order the plugins started (each plugin once). Name them to the user, who can turn the filters off there. Empty when the copy-back decoding is not one the player chose for a filter (the user's own `hwdec` setting). Absent with any other cause, and from players before 0.5.25.
+   * @player 0.5.25
+   */
+  readonly plugins?: readonly UpscalingPlugin[];
 }
 ```
 
@@ -11897,6 +11912,78 @@ const { available, reason } = await plugin.video.upscaling.state();
 if (!available && reason) console.log(`${reason.code}: ${reason.message}`);
 ```
 
+### UpscalingDecodingCause
+
+Why the video is not decoded on the GPU that renders it: the
+UpscalingReason.cause of a `decoding` reason (player 0.5.25). A
+newer player may add causes: show UpscalingReason.message for the
+ones you do not handle.
+
+| Cause | Meaning |
+| --- | --- |
+| `copy-back` | Decoded on the GPU and copied back to memory, because a plugin's video filter needs the frames there (UpscalingReason.plugins names it), or because of the user's `hwdec` setting. |
+| `hwdec-off` | Hardware decoding is turned off (mpv's `hwdec` is `no`). |
+| `software` | This video is decoded in software: a cover picture, a format the GPU does not decode, or a hardware decoder that failed. It passes with the next video. |
+| `other-hwdec` | This video is decoded with another hardware decoder than the one the upscaler needs. |
+
+- @player 0.5.25
+
+```ts
+type UpscalingDecodingCause = "copy-back" | "hwdec-off" | "software" | "other-hwdec" | (string & {});
+```
+
+Example: Name the plugins whose filters block upscaling
+
+A plugin's upscaling window explains a `decoding` reason by its cause,
+and for `copy-back` names the plugins whose filters stand in the way, so
+the user can turn them off there (a plugin cannot run another plugin's
+commands).
+```ts
+const { reason } = await plugin.video.upscaling.state();
+if (reason?.code === "decoding" && reason.cause === "copy-back") {
+  const names = (reason.plugins ?? []).map((p) => p.name).join(", ");
+  // Ask the user to reset those filters; the manifest names are not translated.
+  console.log(names ? `Turn off the video filters of ${names}` : reason.message);
+} else if (reason) console.log(reason.message);
+```
+
+### UpscalingPlugin
+
+A plugin named in an UpscalingReason: its manifest id and its
+name for people, as its manifest gives it (not translated).
+
+- @player 0.5.25
+
+```ts
+interface UpscalingPlugin {
+  /** The plugin's manifest id, for example `vestra.video`. */
+  readonly id: string;
+  /** The manifest's `name` as is (its id without one), for people. */
+  readonly name: string;
+}
+```
+
+### UpscalingVideoSize
+
+The video's size as the upscaler gets it (UpscalingState.video):
+the decoder's frame size, width and height swapped for the file's
+quarter-turn rotation metadata.
+
+- @player 0.5.25
+
+```ts
+interface UpscalingVideoSize {
+  /** The frames' stored width in pixels. */
+  readonly width: number;
+  /** The frames' stored height in pixels. */
+  readonly height: number;
+  /** The width the video is meant to be shown at (non-square pixels). */
+  readonly displayWidth: number;
+  /** The height the video is meant to be shown at. */
+  readonly displayHeight: number;
+}
+```
+
 ### UpscalingState
 
 What VideoUpscaling.state and VideoUpscaling.set report:
@@ -11928,6 +12015,36 @@ interface UpscalingState {
    * The scale factor the upscaler was asked for (the area the video is shown in over the video's size, in hundredths, above 1); `null` while nothing is requested.
    */
   readonly factor: number | null;
+  /**
+   * The video's size as the upscaler gets it; `null` while no video decodes. With UpscalingState.area it explains the factor. Absent from players before 0.5.25.
+   * @player 0.5.25
+   */
+  readonly video?: UpscalingVideoSize | null;
+  /**
+   * The area the video is shown in, in pixels (the upscaler scales the video to fit it); `null` while the player shows no video area. Absent from players before 0.5.25.
+   * @player 0.5.25
+   */
+  readonly area?: {
+    /** Width in physical pixels. */
+    readonly width: number;
+    /** Height in physical pixels. */
+    readonly height: number;
+  } | null;
+  /**
+   * The name of the GPU that renders, for example `NVIDIA GeForce RTX 4070 Laptop GPU`; `null` in software rendering and where the player does not know it (macOS, Linux). Absent from players before 0.5.25.
+   * @player 0.5.25
+   */
+  readonly gpu?: string | null;
+  /**
+   * The hardware decoder in use for this video, as mpv names it (`d3d11va`, `d3d11va-copy`; `no` for software decoding); `null` while no video decodes. For people and logs: branch on UpscalingReason.cause. Absent from players before 0.5.25.
+   * @player 0.5.25
+   */
+  readonly hwdecCurrent?: string | null;
+  /**
+   * The upscaler is in the player's video filter chain now, read from the chain itself (`requested` is what the player asked for; they differ only for a moment, while the chain changes). Still not a sign that the GPU upscales: the driver gives none (see the remarks). Absent from players before 0.5.25.
+   * @player 0.5.25
+   */
+  readonly inChain?: boolean;
 }
 ```
 
@@ -12036,6 +12153,46 @@ interface VideoUpscaling {
    * ```
    */
   set(enabled: boolean): Promise<UpscalingState>;
+  /**
+   * Call `listener` with the new state whenever it changes while some plugin has upscaling on: the factor, whether the upscaler is in the chain, the reason, the video's and the area's size, the decoder. A window that shows how upscaling runs listens instead of polling VideoUpscaling.state.
+   *
+   * The player looks about five times a second while upscaling is on for
+   * any plugin (a window resize sends at most that many), and sends a
+   * change only when something differs; after the last plugin turns it
+   * off one more change says so, then nothing until it is on again: read
+   * VideoUpscaling.state when you need the state then. Nothing is
+   * sent before the player's GPU check ran (the first `state()` or
+   * `set(true)` of any plugin). `enabled` is this plugin's own request, as
+   * in `state()`. The message of a `rendering` reason can be shorter than
+   * the one `state()` gives (it may leave out what to do).
+   *
+   * **A listener keeps the plugin running.** `video.upscaling.changed` is
+   * not an event the player wakes a stopped plugin for: while the plugin
+   * listens, the player does not stop it while idle (lazy activation), even
+   * with upscaling off. Listen only while a window that shows the state is
+   * open, and dispose of the listener when it closes. Players before 0.5.25 do not know the event: the listener
+   * never fires and the SDK logs that the player refused the subscription.
+   * @capability video.upscaling
+   * @param listener - Receives the new state.
+   * @returns Stops listening; also when the scope that added it is disposed.
+   * @throws capability (synchronously) The manifest does not declare `video.upscaling`.
+   * @player 0.5.25
+   * @example Show how upscaling runs while a window is open
+   * The plugin's window shows the factor, the sizes and the GPU while it
+   * is open; the listener goes when the window closes, so the plugin can
+   * be stopped while idle again.
+   * ```ts
+   * // When the window opens:
+   * const watch = plugin.video.upscaling.onChange((state) => {
+   *   const video = state.video ? `${state.video.width}×${state.video.height}` : "no video";
+   *   const area = state.area ? `${state.area.width}×${state.area.height}` : "—";
+   *   console.log(`${video} → ${area}, ×${state.factor ?? 1}, ${state.gpu ?? "no GPU"}`);
+   * });
+   * // When it closes: stop listening (it keeps the plugin running).
+   * await watch.dispose();
+   * ```
+   */
+  onChange(listener: (state: UpscalingState) => void): Disposable;
 }
 ```
 
@@ -16227,7 +16384,50 @@ class TestHost implements Transport {
     checked: boolean;
     /** GPU rendering is still starting: a `rendering` reason then lets `set(true)` keep the request. */
     renderingStarting: boolean;
+    /** The video's size the state reports (player 0.5.25); `null`: no video. */
+    video: UpscalingVideoSize | null;
+    /** The video area the state reports (player 0.5.25); `null`: none. */
+    area: {
+      /** Width in physical pixels. */
+      width: number;
+      /** Height in physical pixels. */
+      height: number;
+    } | null;
+    /** The rendering GPU's name the state reports (player 0.5.25). */
+    gpu: string | null;
+    /** mpv's decoder the state reports (player 0.5.25); `null`: no video. */
+    hwdecCurrent: string | null;
   };
+  /**
+   * Make the upscaler's reason `decoding` with `cause`, with the player's message (player 0.5.25), and set `upscaling.hwdecCurrent` to match (`d3d11va-copy`, `no`, `nvdec`). `plugins` are named for `copy-back` only, as the player does. Returns the reason; call TestHost.upscalingChanged to tell a listening plugin.
+   * @capability None.
+   * @example Test the window's advice for each cause
+   * The plugin's window explains why upscaling waits. The test fakes the
+   * copy-back cause that Picture Adjustments' filters cause and checks
+   * that the window names the plugin.
+   * ```ts
+   * host.upscalingDecoding("copy-back", [{ id: "vestra.video", name: "Picture Adjustments" }]);
+   * host.upscalingChanged();
+   * await host.settle();
+   * assert.match(String(host.window("upscale").props.blocker), /Picture Adjustments/);
+   * ```
+   */
+  upscalingDecoding(cause: UpscalingDecodingCause, plugins?: readonly UpscalingPlugin[]): UpscalingReason;
+  /**
+   * Send `video.upscaling.changed` with the state TestHost.upscaling describes now (without `enabled`), as the player does when it changes (player 0.5.25); a plugin listening with `plugin.video.upscaling.onChange` receives it. Nothing reaches a plugin that does not listen.
+   * @capability None.
+   * @example Show the new factor in the plugin's window
+   * The window resized: the test changes the area and the factor, sends
+   * the change, and checks that the plugin's window shows the new factor.
+   * ```ts
+   * host.upscaling.area = { width: 2560, height: 1440 };
+   * host.upscaling.factor = 1.33; // 1080p in a 1440p area
+   * host.upscalingChanged(); // as the player after the resize settled
+   * await host.settle();
+   * assert.equal(host.window("upscale").props.factor, "×1.33");
+   * ```
+   */
+  upscalingChanged(): void;
   /** What `player.chapters()` lists while media is ready. */
   chapters: {
     /** The chapter title, `null` without one. */

package/llms.txt

@@ -1,6 +1,6 @@
 # Vestra Player SDK
 
-> @vestra-player/sdk 1.5.42: 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 (the player's built-in plugins share one). 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.43: 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 (the player's built-in plugins share one). 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: L2216–2288.
+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: L2216–2289.
 
 **main.ts**
 
@@ -77,10 +77,10 @@ export default async function activate(plugin: Plugin) {
 - `ui.theme`: Appearance.set/setLanguage
 - `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: L2289–2349.
+- `video.upscaling`: VideoUpscaling.state/set/onChange
+- No capability: `tools`, `storage`, `system`, `app`, `ui` (images and Markdown), `i18n`, reading window.state, appearance.theme, packages.list and rendering.state. Details: L2290–2350.
 
-**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: L1861–2019; TestHost: L15207.
+**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: L1861–2019; TestHost: L15364.
 
 **Command line**
 
@@ -108,40 +108,40 @@ 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 L5841.
+- Others: PluginError, llms-full.txt L5846.
 
 ## 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–134; Add a window L135–213; Add settings and translations L214–367; Test, check, pack and publish L368–424; Write your own blur kernel L425–685
 - How-to: Control playback L686–854; Store a plugin's data L855–961; Load subtitles from a plugin L962–1074; Keep a slider responsive while dragging L1075–1262; Remember a window's state between runs L1263–1414; Offer a GPU rendering switch L1415–1540; Keep a command's state without keeping the plugin running L1541–1697; Translate a plugin L1698–1860; Test a plugin L1861–2019; Publish a plugin L2020–2121; Troubleshooting L2122–2215
-- Reference: Manifest L2216–2288; Capabilities L2289–2349; Limits L2350–2495; Commands, menus and bindings L2496–3021; Platforms L3022–3052; Theme L3053–3311; Command line L3312–3369; Error codes L3370–3417; Translations L3418–3510; Test host L3511–3695
-- Explanation: How a plugin runs L3696–3894; Commands, menus and key bindings L3895–4049; Playback state, controls and sources L4050–4209; Video and audio processing L4210–4329; Windows, panels, settings pages, dialogs and the OSD L4330–4585; GPU and software rendering L4586–4602; The player's Rust core L4603–4944; How the player runs and talks to plugins L4945–5284
-- Guidelines: Plugin rules L5285–5296; Interface guidelines L5297–5413; Menu guidelines L5414–5472
-- Upgrading: Migrate a plugin to English source text L5473–5622; Migrating off package rollback (1.5.16, removed in 1.5.17) L5623–5700; Who must change, release by release L5701–5763
-- [API: @vestra-player/sdk](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk.html): L5764–14880
-- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html): L14881–17705
+- Reference: Manifest L2216–2289; Capabilities L2290–2350; Limits L2351–2496; Commands, menus and bindings L2497–3022; Platforms L3023–3053; Theme L3054–3312; Command line L3313–3370; Error codes L3371–3418; Translations L3419–3511; Test host L3512–3698
+- Explanation: How a plugin runs L3699–3897; Commands, menus and key bindings L3898–4052; Playback state, controls and sources L4053–4212; Video and audio processing L4213–4333; Windows, panels, settings pages, dialogs and the OSD L4334–4589; GPU and software rendering L4590–4606; The player's Rust core L4607–4948; How the player runs and talks to plugins L4949–5288
+- Guidelines: Plugin rules L5289–5300; Interface guidelines L5301–5417; Menu guidelines L5418–5476
+- Upgrading: Migrate a plugin to English source text L5477–5626; Migrating off package rollback (1.5.16, removed in 1.5.17) L5627–5704; Who must change, release by release L5705–5768
+- [API: @vestra-player/sdk](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk.html): L5769–15037
+- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html): L15038–17905
 
 ## API
 
 Where each `plugin.<module>` is declared:
 
-- Plugin L6180, Scope L5916, PluginError L5841, Disposable L5779
-- Commands L6767; When L6365; Windows L7704; Panels L9150; Dialogs L9820; Player L10561; video: VideoFilter L11441, VideoView L11541, RenderOptions L11628, VideoShaders L11706, VideoUpscaling L11952; audio: AudioFilter L11486; Subtitles L12148; media: MediaCapture L12552; Resolvers L12782; Packages L13184; Osd L11306; Host L11148; Clipboard L13513; Power L13600; Tools L13659; Storage L13811; System L14010; Secrets L14090; window: MainWindow L9467; App L9647; Rendering L14353; Bindings L13412; Ui L7056; Timeline L9379; Drops L8397; Appearance L8478; I18n L8711; Settings L8994.
+- Plugin L6185, Scope L5921, PluginError L5846, Disposable L5784
+- Commands L6772; When L6370; Windows L7709; Panels L9155; Dialogs L9825; Player L10566; video: VideoFilter L11446, VideoView L11546, RenderOptions L11633, VideoShaders L11711, VideoUpscaling L12069; audio: AudioFilter L11491; Subtitles L12305; media: MediaCapture L12709; Resolvers L12939; Packages L13341; Osd L11311; Host L11153; Clipboard L13670; Power L13757; Tools L13816; Storage L13968; System L14167; Secrets L14247; window: MainWindow L9472; App L9652; Rendering L14510; Bindings L13569; Ui L7061; Timeline L9384; Drops L8402; Appearance L8483; I18n L8716; Settings L8999.
 
 ## 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. L18140–18235
-- blur: A tool window with one slider that blurs the playing video. L18236–18503
-- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L18504–18842
-- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L18843–19035
-- panel-menu: A sidebar panel with its own right-click menu. L19036–19250
-- menus: Radio menu items, separator groups and a menu item whose title changes. L19251–19416
-- theme-widgets: A tool window drawn with the player's theme and widgets. L19417–19586
-- markdown: A window that shows a Markdown document. L19587–19789
-- i18n: A plugin in the player's language: English source text, a Chinese translation. L19790–19963
+- hello: The README Quick start: one menu command and an on-screen message. L18340–18435
+- blur: A tool window with one slider that blurs the playing video. L18436–18703
+- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L18704–19042
+- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L19043–19235
+- panel-menu: A sidebar panel with its own right-click menu. L19236–19450
+- menus: Radio menu items, separator groups and a menu item whose title changes. L19451–19616
+- theme-widgets: A tool window drawn with the player's theme and widgets. L19617–19786
+- markdown: A window that shows a Markdown document. L19787–19989
+- i18n: A plugin in the player's language: English source text, a Chinese translation. L19990–20163
 
 ## Optional
 

package/package.json

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