@vestra-player/sdk 1.5.35 → 1.5.37

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 1.5.37
+
+**Who must change: nobody.** Additions only, `apiVersion` stays `vestra/1`. The new API needs player 0.5.16 (`"minPlayerVersion": "0.5.16"`): older players do not load a plugin that declares the new capability `video.upscaling` (an unknown capability). A plugin that does not use it sees no difference.
+
+- **`plugin.video.upscaling`** (player 0.5.16): the GPU's video upscaler, NVIDIA RTX Video Super Resolution on Windows. `state()` reports whether it works now (`available`) and why not (`reason`, `{ code, message }` with the stable codes of `UpscalingReasonCode`: `platform`, `no-gpu`, `driver`, `gpu-unsupported`, `rendering`, `adapter`, `decoding`, `unchecked`; a newer player may add codes), whether this plugin turned it on (`enabled`), and whether the player asked the GPU to upscale now (`requested`, with the scale `factor`). `set(enabled)` turns this plugin's request on or off and resolves with the new state; `true` rejects with `unsupported` where upscaling cannot work in this run: every reason except `decoding` (it can pass with the next file) and except `rendering` while GPU rendering is still starting, which are accepted and kept; `false` is always accepted and answered at once without the GPU check (before any check: `available: false` with `unchecked`); `invalid` for a non-boolean. The player checks the GPU once, at the first `state()` or `set(true)` (it wakes a sleeping discrete GPU, so the examples ask on the first pick of the item, not while the plugin starts), puts the upscaler last in the video filter chain scaled to the area the video is shown in (only above 1×), follows size changes, and takes it out when the last plugin turns it off or stops. There is no "upscaling active" signal: on Windows the user must also turn on Super Resolution in the NVIDIA app, which no program can read. New types `VideoUpscaling`, `UpscalingState`, `UpscalingReason`, `UpscalingReasonCode`.
+- **New capability `video.upscaling`** ("Upscale the video with the GPU's video upscaler", not highlighted in the store: it changes only how the picture is scaled while the plugin runs and touches no data), last in `CAPABILITIES`; both requests need it and reject with `capability` without it. The player's capability table copy, `CAPABILITY_INFO`, `vestra-plugin check` and the editor plugin know it.
+- **`TestHost.upscaling`** models the player: preset `reason` (`null`: it works) and `factor`, read `enabled` and `checked` (whether the plugin made the player check the GPU), set `renderingStarting`; `set(true)` refuses with `unsupported` unless the reason is `decoding`, or `rendering` with `renderingStarting`; `set(false)` checks nothing (`unchecked` before any check).
+- _Video and audio processing_ and _Platforms_ describe the upscaler.
+
+## 1.5.36
+
+**Who must change: nobody.** No API changes, `apiVersion` stays `vestra/1`, no player version needed.
+
+- **`BUILTIN_COMMANDS`** lists the Picture Adjustments plugin's (`vestra.video` 1.1.8) `Video ▸ GPU Rendering (Experimental)` (`video.gpu-rendering`, no default keys), after the color steps. Its `Video ▸ Restart Player to Apply` (`video.gpu-rendering.restart`) appears only while a rendering choice waits for the next start and is not listed, like other items of a passing state; the reference says so.
+
 ## 1.5.35
 
 **Who must change: nobody.** Additions only, `apiVersion` stays `vestra/1`. The new API needs player 0.5.13 (`"minPlayerVersion": "0.5.13"`): older players leave `SystemInfo.renderingReason` out, refuse `rendering.state` as an unknown request (`unsupported`), and do not load a plugin that declares the new capability `rendering.manage`. A plugin that uses none of it sees no difference.

package/dist/api-requests.js

@@ -143,4 +143,6 @@ export const API_REQUESTS = Object.freeze({
     "Rendering.state": [{ method: "rendering.state" }],
     "Rendering.setPreference": [{ method: "rendering.setPreference" }],
     "Rendering.restartPlayer": [{ method: "rendering.restart" }],
+    "VideoUpscaling.state": [{ method: "video.upscaling.state" }],
+    "VideoUpscaling.set": [{ method: "video.upscaling.set" }],
 });

package/dist/commands.d.ts

@@ -205,7 +205,10 @@ export interface BuiltinCommand {
  * a menu place and default keys that do not collide with the player's (the
  * user's own changes come on top; see {@link @vestra-player/sdk!Bindings | Bindings}). Menu items built
  * from content (tracks, recent files, output devices) are not listed; their
- * placeholders (`No Audio Tracks`) are. The player's tests check that this
+ * placeholders (`No Audio Tracks`) are. Items that appear only in a
+ * passing state are not listed either: the Picture Adjustments plugin's
+ * `Video ▸ Restart Player to Apply` (`video.gpu-rendering.restart`), shown
+ * while a rendering choice waits for the next start. The player's tests check that this
  * list agrees with what the player and its built-in plugins register.
  *
  * @example Check in a test that a default key is still free

package/dist/commands.js

@@ -464,6 +464,7 @@ vestra.video | video.saturation.down | Video ▸ Saturation -1% | Y
 vestra.video | video.saturation.up | Video ▸ Saturation +1% | U
 vestra.video | video.hue.down | Video ▸ Hue -1% | I
 vestra.video | video.hue.up | Video ▸ Hue +1% | O
+vestra.video | video.gpu-rendering | Video ▸ GPU Rendering (Experimental)
 host | volume-up | Audio ▸ Volume + | ArrowUp, Mouse:WheelUp
 host | volume-down | Audio ▸ Volume − | ArrowDown, Mouse:WheelDown
 host | mute | Audio ▸ Mute | M
@@ -577,7 +578,10 @@ vestra.playlist | playlist.settings | (Playlist Settings…) | F5 | panel
  * a menu place and default keys that do not collide with the player's (the
  * user's own changes come on top; see {@link @vestra-player/sdk!Bindings | Bindings}). Menu items built
  * from content (tracks, recent files, output devices) are not listed; their
- * placeholders (`No Audio Tracks`) are. The player's tests check that this
+ * placeholders (`No Audio Tracks`) are. Items that appear only in a
+ * passing state are not listed either: the Picture Adjustments plugin's
+ * `Video ▸ Restart Player to Apply` (`video.gpu-rendering.restart`), shown
+ * while a rendering choice waits for the next start. The player's tests check that this
  * list agrees with what the player and its built-in plugins register.
  *
  * @example Check in a test that a default key is still free

package/dist/host-capabilities.js

@@ -354,6 +354,17 @@ export const HOST_CAPABILITIES = {
             residency: "none",
             risky: true,
         },
+        {
+            label: "Upscale the video with the GPU's video upscaler",
+            methods: [
+                { name: "video.upscaling.state", needs: "video.upscaling" },
+                { name: "video.upscaling.set", needs: "video.upscaling" },
+            ],
+            name: "video.upscaling",
+            requires: [],
+            residency: "live",
+            risky: false,
+        },
     ],
     uncapable: [
         { name: "packages.list", needs: null },

package/dist/plugin/scope.d.ts

@@ -15,6 +15,7 @@ export declare class ScopeImpl implements Plugin {
     readonly video: {
         view: () => import("./types.ts").VideoView;
         render: () => import("./types.ts").RenderOptions;
+        upscaling: import("./types.ts").VideoUpscaling;
         filter(id: string): import("./types.ts").VideoFilter;
     };
     readonly audio: {

package/dist/plugin/scope.js

@@ -17,7 +17,7 @@ import { packages } from "./packages.js";
 import { osd } from "./osd.js";
 import { mainWindow } from "./window.js";
 import { bindingsApi } from "./bindings.js";
-import { clipboard, host, power, rendering, secrets, storage, system, tools, } from "./services.js";
+import { clipboard, host, power, rendering, secrets, storage, system, tools, videoUpscaling, } from "./services.js";
 export class ScopeImpl {
     runtime;
     #parent;
@@ -49,6 +49,7 @@ export class ScopeImpl {
         ...videoFilters(this),
         view: () => videoView(this),
         render: () => videoRender(this),
+        upscaling: videoUpscaling(this),
     };
     audio = audioFilters(this);
     subtitles = subtitles(this);

package/dist/plugin/services.d.ts

@@ -1,5 +1,5 @@
 import type { ScopeImpl } from "./scope.ts";
-import type { Clipboard, Host, Power, Rendering, Secrets, Storage, System, Tools } from "./types.ts";
+import type { Clipboard, Host, Power, Rendering, Secrets, Storage, System, Tools, VideoUpscaling } from "./types.ts";
 export declare const clipboard: (scope: ScopeImpl) => Clipboard;
 export declare const host: (scope: ScopeImpl) => Host;
 export declare const power: (scope: ScopeImpl) => Power;
@@ -113,3 +113,9 @@ export declare const SECRET_LIMITS: Readonly<{
 }>;
 export declare const secrets: (scope: ScopeImpl) => Secrets;
 export declare const rendering: (scope: ScopeImpl) => Rendering;
+/**
+ * `plugin.video.upscaling` (player 0.5.16): both requests need
+ * `video.upscaling`; the player answers once its GPU check ran (the first
+ * call starts it).
+ */
+export declare const videoUpscaling: (scope: ScopeImpl) => VideoUpscaling;

package/dist/plugin/services.js

@@ -1,7 +1,8 @@
 /**
  * Shared services: the clipboard, sleep prevention, showing and opening files
- * and links, secrets, session storage and the rendering choice go to the
- * host; external tools and settings files run in this plugin's own process.
+ * and links, secrets, session storage, the rendering choice and the video
+ * upscaler go to the host; external tools and settings files run in this
+ * plugin's own process.
  */
 import { existsSync, readFileSync, renameSync } from "node:fs";
 import { mkdir, open, rename, rm, stat } from "node:fs/promises";
@@ -497,3 +498,26 @@ export const rendering = (scope) => {
         },
     };
 };
+/**
+ * `plugin.video.upscaling` (player 0.5.16): both requests need
+ * `video.upscaling`; the player answers once its GPU check ran (the first
+ * call starts it).
+ */
+export const videoUpscaling = (scope) => {
+    const declared = () => {
+        if (!scope.runtime.can("video.upscaling"))
+            throw failure("capability", "video.upscaling must be declared in manifest");
+    };
+    return {
+        async state() {
+            declared();
+            return (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));
+        },
+    };
+};

package/dist/plugin/testing.d.ts

@@ -15,7 +15,7 @@ import { IMAGE_LIMITS, UI_VALUE_LIMITS } from "./values.ts";
 import type { CommandDeclaration } from "../commands.ts";
 import type { SourceState } from "../source.ts";
 import type { SubtitleState } from "../subtitles.ts";
-import type { RenderingMode, RenderingPreference, RenderingReason, RenderSettings, ViewSettings } from "./types.ts";
+import type { RenderingMode, RenderingPreference, RenderingReason, RenderSettings, UpscalingReason, 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";
@@ -469,7 +469,8 @@ export interface MarkdownWire {
  *   {@link TestHost.app}, {@link TestHost.systemInfo},
  *   {@link TestHost.chapters}, {@link TestHost.audioDevices},
  *   {@link TestHost.secrets}, {@link TestHost.clipboard},
- *   {@link TestHost.tools}, {@link TestHost.rendering}.
+ *   {@link TestHost.tools}, {@link TestHost.rendering},
+ *   {@link TestHost.upscaling}.
  * - **Assert** on records: {@link TestHost.osd}, {@link TestHost.calls},
  *   {@link TestHost.sent}, {@link TestHost.conflicts},
  *   {@link TestHost.layout}, {@link TestHost.menus}, and many more.
@@ -1703,6 +1704,65 @@ export declare class TestHost implements Transport {
         /** Accepted `restartPlayer` calls. */
         restarts: number;
     };
+    /**
+     * 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.
+     * - `set(true)` refuses with `unsupported` and the reason's message while
+     *   `reason` is set, unless its code is `decoding`, or `rendering` with
+     *   `renderingStarting` (GPU rendering still starting): those can pass
+     *   during the run, so the player keeps the request. Nothing changes when
+     *   it refuses.
+     * - `set(false)` always succeeds and does not check the GPU: before any
+     *   check it reports `available: false` with the reason `unchecked`.
+     *
+     * Inject other answers with `host.handle("video.upscaling.set", …)`. The
+     * defaults are a player where upscaling works and a 1080p video shown
+     * full screen on a 4K display (`factor` 2), whatever `systemInfo` says.
+     *
+     * @example Test the menu item on a computer without an RTX GPU
+     * The plugin's upscaling item is greyed out with the player's reason after
+     * the user first picks it. Starting the plugin checks nothing (`checked`
+     * stays false, so no GPU wakes up); the first pick reads the state, and
+     * `set(true)` would reject with `unsupported`, as in the player.
+     * ```ts
+     * import assert from "node:assert/strict";
+     * import { startPlugin, TestHost } from "@vestra-player/sdk/testing";
+     * import activate from "../main.ts";
+     *
+     * const host = new TestHost();
+     * host.upscaling.reason = { code: "no-gpu", message: "no NVIDIA GPU" };
+     * const { stop } = await startPlugin(activate, {
+     *   directory: new URL("..", import.meta.url),
+     *   host,
+     * });
+     * assert.equal(host.upscaling.checked, false); // starting woke no GPU
+     * const item = host.command("upscaling");
+     * await item.run(); // the first pick checks the GPU
+     * assert.equal(item.state.enabled, false); // greyed out
+     * assert.equal(item.state.reason, "no NVIDIA GPU"); // the player's message
+     * await stop();
+     * ```
+     *
+     * @since 1.5.37
+     */
+    readonly upscaling: {
+        /** Why upscaling does not work; `null` while it does. */
+        reason: UpscalingReason | null;
+        /** Whether this plugin has upscaling on (`set`); a test may preset it. */
+        enabled: boolean;
+        /** The factor the player would request; `null` or at most 1: the video needs no upscaling. */
+        factor: number | null;
+        /** Whether the plugin made the player check the GPU (`state`, `set(true)`). */
+        checked: boolean;
+        /** GPU rendering is still starting: a `rendering` reason then lets `set(true)` keep the request. */
+        renderingStarting: boolean;
+    };
     /** What `player.chapters()` lists while media is ready. */
     chapters: {
         /** The chapter title, `null` without one. */

package/dist/plugin/testing.js

@@ -268,7 +268,8 @@ const MAX_SIDEBAR_TABS = 8;
  *   {@link TestHost.app}, {@link TestHost.systemInfo},
  *   {@link TestHost.chapters}, {@link TestHost.audioDevices},
  *   {@link TestHost.secrets}, {@link TestHost.clipboard},
- *   {@link TestHost.tools}, {@link TestHost.rendering}.
+ *   {@link TestHost.tools}, {@link TestHost.rendering},
+ *   {@link TestHost.upscaling}.
  * - **Assert** on records: {@link TestHost.osd}, {@link TestHost.calls},
  *   {@link TestHost.sent}, {@link TestHost.conflicts},
  *   {@link TestHost.layout}, {@link TestHost.menus}, and many more.
@@ -1622,6 +1623,60 @@ export class TestHost {
         gpu: { available: true, reason: null },
         restarts: 0,
     };
+    /**
+     * 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.
+     * - `set(true)` refuses with `unsupported` and the reason's message while
+     *   `reason` is set, unless its code is `decoding`, or `rendering` with
+     *   `renderingStarting` (GPU rendering still starting): those can pass
+     *   during the run, so the player keeps the request. Nothing changes when
+     *   it refuses.
+     * - `set(false)` always succeeds and does not check the GPU: before any
+     *   check it reports `available: false` with the reason `unchecked`.
+     *
+     * Inject other answers with `host.handle("video.upscaling.set", …)`. The
+     * defaults are a player where upscaling works and a 1080p video shown
+     * full screen on a 4K display (`factor` 2), whatever `systemInfo` says.
+     *
+     * @example Test the menu item on a computer without an RTX GPU
+     * The plugin's upscaling item is greyed out with the player's reason after
+     * the user first picks it. Starting the plugin checks nothing (`checked`
+     * stays false, so no GPU wakes up); the first pick reads the state, and
+     * `set(true)` would reject with `unsupported`, as in the player.
+     * ```ts
+     * import assert from "node:assert/strict";
+     * import { startPlugin, TestHost } from "@vestra-player/sdk/testing";
+     * import activate from "../main.ts";
+     *
+     * const host = new TestHost();
+     * host.upscaling.reason = { code: "no-gpu", message: "no NVIDIA GPU" };
+     * const { stop } = await startPlugin(activate, {
+     *   directory: new URL("..", import.meta.url),
+     *   host,
+     * });
+     * assert.equal(host.upscaling.checked, false); // starting woke no GPU
+     * const item = host.command("upscaling");
+     * await item.run(); // the first pick checks the GPU
+     * assert.equal(item.state.enabled, false); // greyed out
+     * assert.equal(item.state.reason, "no NVIDIA GPU"); // the player's message
+     * await stop();
+     * ```
+     *
+     * @since 1.5.37
+     */
+    upscaling = {
+        reason: null,
+        enabled: false,
+        factor: 2,
+        checked: false,
+        renderingStarting: false,
+    };
     /** What `player.chapters()` lists while media is ready. */
     chapters = [];
     #overrides = new Map();
@@ -3252,6 +3307,27 @@ export class TestHost {
             revision: stamp.revision + 1,
         };
     }
+    /** `video.upscaling.state` from {@link TestHost.upscaling}. */
+    #upscalingState(check = true) {
+        if (check)
+            this.upscaling.checked = true;
+        const { enabled, factor } = this.upscaling;
+        // `set(false)` before any check: the player answers without checking.
+        const reason = this.upscaling.checked
+            ? this.upscaling.reason
+            : {
+                code: "unchecked",
+                message: "the player has not checked the GPU yet; state() or set(true) checks it",
+            };
+        const requested = enabled && reason === null && factor !== null && factor > 1;
+        return {
+            available: reason === null,
+            reason: reason ? { ...reason } : null,
+            enabled,
+            requested,
+            factor: requested ? factor : null,
+        };
+    }
     /** `rendering.state` from {@link TestHost.rendering} and `videoRender.gpu`. */
     #renderingState() {
         const { reason, preference, startedWith, gpu } = this.rendering;
@@ -3640,6 +3716,26 @@ export class TestHost {
             this.rendering.restarts++;
             return null;
         },
+        // As the player 0.5.16 (see TestHost.upscaling for the model).
+        "video.upscaling.state": () => this.#upscalingState(),
+        "video.upscaling.set": (p) => {
+            if (typeof p.enabled !== "boolean")
+                throw new HostError("invalid", "enabled must be a boolean");
+            const { reason, renderingStarting } = this.upscaling;
+            // Off: always, without the GPU check.
+            if (!p.enabled) {
+                this.upscaling.enabled = false;
+                return this.#upscalingState(false);
+            }
+            const passes = reason?.code === "decoding" ||
+                (reason?.code === "rendering" && renderingStarting);
+            if (reason && !passes) {
+                this.upscaling.checked = true;
+                throw new HostError("unsupported", `video upscaling cannot work here: ${reason.message}`);
+            }
+            this.upscaling.enabled = true;
+            return this.#upscalingState();
+        },
         "clipboard.readText": () => this.clipboard.text,
         "clipboard.writeText": (p) => {
             if (typeof p.text !== "string")

package/dist/plugin/types.d.ts

@@ -213,10 +213,11 @@ export 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 and the
-     * GPU render options. All 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`).
+     * 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.
      */
     readonly video: {
         /**
@@ -249,6 +250,12 @@ export interface Scope extends Disposable {
          *   while the first handle is not disposed.
          */
         render(): RenderOptions;
+        /**
+         * 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.
+         */
+        readonly upscaling: VideoUpscaling;
     };
     /**
      * Audio processing: this plugin's filter chain and delay
@@ -6439,6 +6446,270 @@ export interface RenderOptions extends Disposable {
      */
     onStatus(listener: (status: FilterStatus) => void): Disposable;
 }
+/**
+ * Why the GPU's video upscaler does not work, as a stable kebab-case code.
+ * A newer player may add codes: compare with the ones you handle and show
+ * {@link UpscalingReason.message} for the rest. The codes of player 0.5.16,
+ * in the order the player checks them (the first that holds is reported):
+ *
+ * | Code | Meaning |
+ * | --- | --- |
+ * | `platform` | The player has no video upscaler on this system (macOS, Linux). |
+ * | `no-gpu` | No GPU that can upscale video (Windows: no NVIDIA GPU). |
+ * | `driver` | The graphics driver is too old (Windows: an NVIDIA driver before 530). |
+ * | `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. |
+ * | `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
+ * during the run, so `set(true)` accepts them and keeps the request; every
+ * other reason holds until the player restarts, and `set(true)` rejects it.
+ * Turning upscaling off is always accepted.
+ *
+ * @example Advise the user by reason
+ * The plugin shows its own advice for the reasons the user can act on and
+ * the player's message for the rest. `reason.code` is looked up among the
+ * codes the plugin knows; an unknown code from a newer player falls
+ * through to the message, which names the GPU and what to do.
+ * ```ts
+ * const { reason } = await plugin.video.upscaling.state();
+ * // Advice for the codes this plugin knows; any other code shows the message.
+ * const advice: Partial<Record<UpscalingReasonCode, string>> = {
+ *   driver: "Update the NVIDIA driver to 530 or newer.",
+ *   rendering: "Turn on Video ▸ GPU Rendering (Experimental) and restart.",
+ * };
+ * if (reason) console.log(advice[reason.code] ?? reason.message);
+ * ```
+ *
+ * @player 0.5.16
+ * @since 1.5.37
+ * @category Processing
+ */
+export type UpscalingReasonCode = "platform" | "no-gpu" | "driver" | "gpu-unsupported" | "rendering" | "adapter" | "decoding" | "unchecked" | (string & {});
+/**
+ * Why the GPU's video upscaler does not work: a stable
+ * {@link UpscalingReasonCode} to branch on and a sentence to show, the same
+ * shape as {@link RenderingReason}.
+ *
+ * @example Grey out a menu item with the player's reason
+ * The plugin disables its upscaling item and shows why. `message` is the
+ * player's English text, naming the GPU and what the user can do (turn on
+ * GPU rendering, choose the other GPU, update the driver); `code` is for
+ * decisions.
+ * ```ts
+ * const { available, reason } = await plugin.video.upscaling.state();
+ * if (!available && reason) console.log(`${reason.code}: ${reason.message}`);
+ * ```
+ *
+ * @player 0.5.16
+ * @since 1.5.37
+ * @category Processing
+ */
+export interface UpscalingReason {
+    /** The reason as a stable kebab-case code; branch on this. */
+    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;
+}
+/**
+ * What {@link VideoUpscaling.state} and {@link VideoUpscaling.set} report:
+ * whether the upscaler works now and why not, whether this plugin turned
+ * it on, and whether the player asked the GPU to upscale.
+ *
+ * @remarks
+ * `requested` is as far as the player can see. The player puts the
+ * upscaler last in the video filter chain, scaling the video to the area it
+ * is shown in; the driver gives no sign that it upscales. On Windows the
+ * user must also turn on Super Resolution in the NVIDIA app (System ▸ Video
+ * ▸ RTX Video Enhancement), which no program can read: say so next to the
+ * switch.
+ *
+ * @example Label the item with what happens now
+ * The plugin's menu item says whether upscaling is on and whether the
+ * video is being upscaled. `enabled` is this plugin's own request;
+ * `requested` is true while the player has the upscaler in the filter
+ * chain, which needs a video shown larger than its own size (`factor`
+ * above 1).
+ * ```ts
+ * const state = await plugin.video.upscaling.state();
+ * // `enabled`: this plugin's request; `requested`: in the filter chain now.
+ * const label = !state.enabled
+ *   ? "AI Upscaling: Off"
+ *   : state.requested
+ *     ? `AI Upscaling: On (×${state.factor?.toFixed(2)})`
+ *     : "AI Upscaling: On (not needed for this video)";
+ * console.log(label);
+ * ```
+ *
+ * @player 0.5.16
+ * @since 1.5.37
+ * @category Processing
+ */
+export interface UpscalingState {
+    /** Whether the upscaler works now; `false` with {@link UpscalingState.reason}. */
+    readonly available: boolean;
+    /** Why it does not work now; `null` while it does. */
+    readonly reason: UpscalingReason | null;
+    /** This plugin asked for upscaling ({@link VideoUpscaling.set}) and has not turned it off. */
+    readonly enabled: boolean;
+    /**
+     * The player has the upscaler in the video filter chain now, for this
+     * plugin or another one: upscaling is enabled and available and the
+     * video is shown larger than its own size. Not a sign that the GPU
+     * upscales (see the remarks).
+     */
+    readonly requested: boolean;
+    /**
+     * 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;
+}
+/**
+ * `plugin.video.upscaling`: the GPU's video upscaler, NVIDIA RTX Video
+ * Super Resolution on Windows (`video.upscaling`). Read whether it works
+ * here and why not; turn it on or off for this plugin.
+ *
+ * @remarks
+ * The player checks the GPU once, when a plugin first asks, and keeps the
+ * answer: the check wakes a sleeping discrete GPU, so call
+ * {@link VideoUpscaling.state} when the plugin first needs the answer (the
+ * first time the user picks its upscaling item), not while the plugin
+ * starts, and do not poll it. `set(false)` never starts the check. It works
+ * only with GPU rendering, on the GPU the upscaler runs on, with the video decoded on that GPU; {@link UpscalingReasonCode}
+ * lists what can stand in the way.
+ *
+ * While some plugin has it on and it works, the player puts the upscaler
+ * last in the video filter chain and scales the video to the area it is
+ * shown in, following window and video size changes (a resize waits until
+ * the size holds). A video already shown at its own size or smaller is not
+ * upscaled. The upscaler stays while any plugin has it on; it goes when the
+ * last one turns it off or stops: the player revokes a stopped plugin's
+ * request.
+ *
+ * **Windows:** the user must turn on Super Resolution in the NVIDIA app
+ * (System ▸ Video ▸ RTX Video Enhancement); no program can read that
+ * switch, and the driver gives no sign that it upscales
+ * ({@link UpscalingState.requested} is as far as the player can see). It
+ * uses the NVIDIA GPU, so power use and heat go up, and on a laptop with
+ * two GPUs the whole player must run on the NVIDIA one.
+ * **macOS, Linux:** `available` is `false` with `platform`.
+ *
+ * Players before 0.5.16 do not know `video.upscaling` and do not load a
+ * plugin that declares it: declare `"minPlayerVersion": "0.5.16"`.
+ *
+ * @example Offer AI upscaling as a menu item
+ * A Video menu item turns upscaling on and off; once the player said it
+ * cannot work here, the item is greyed out with the player's reason. The
+ * state is read the first time the user picks the item (that runs the
+ * player's GPU check, so nothing wakes the GPU while the plugin starts) and
+ * again after each pick; `set` resolves with the new state, or rejects with
+ * `unsupported` where upscaling cannot work in this run.
+ * ```ts
+ * let state: UpscalingState | null = null; // unknown until first picked
+ * plugin.commands.add({
+ *   id: "upscaling",
+ *   path: ["@video", "AI Upscaling"],
+ *   checked: () => state?.enabled ?? false,
+ *   // Greyed only once the player said it cannot work (`decoding` can pass).
+ *   enabled: () => state === null || state.available || state.reason?.code === "decoding",
+ *   reason: () => state?.reason?.message ?? null, // shown while disabled
+ *   run: async () => {
+ *     state ??= await plugin.video.upscaling.state(); // the first pick checks the GPU
+ *     try {
+ *       state = await plugin.video.upscaling.set(!(state?.enabled ?? false));
+ *     } catch (error) {
+ *       // Cannot work in this run (no RTX GPU, software rendering…).
+ *       if ((error as PluginError).code !== "unsupported") throw error;
+ *       state = await plugin.video.upscaling.state();
+ *     }
+ *   },
+ * });
+ * ```
+ *
+ * @capability video.upscaling
+ * @player 0.5.16; older players do not load a plugin that declares
+ * `video.upscaling`.
+ * @since 1.5.37
+ * @category Processing
+ */
+export interface VideoUpscaling {
+    /**
+     * Read whether the upscaler works now and why not, whether this plugin
+     * turned it on and what the player asked the GPU for.
+     *
+     * @capability video.upscaling
+     * @returns The state, once the player's GPU check ran (the first call
+     *   starts it and may take a moment).
+     * @throws `capability` (rejects) The manifest does not declare
+     *   `video.upscaling`.
+     *
+     * @example Find out whether upscaling can work here
+     * The plugin reads the state the first time the user picks its upscaling
+     * item and keeps it for the item. The first call makes the player check the GPU (which
+     * wakes a sleeping discrete GPU) and later calls reuse the answer; the
+     * rest (GPU rendering, the GPU it runs on, the decoding) is read at
+     * each call.
+     * ```ts
+     * const { available, reason } = await plugin.video.upscaling.state();
+     * if (!available) console.log(reason?.message);
+     * ```
+     *
+     * @since 1.5.37
+     */
+    state(): Promise<UpscalingState>;
+    /**
+     * Turn upscaling on or off for this plugin.
+     *
+     * @remarks
+     * On stays this plugin's request until it turns it off or stops; the
+     * player upscales whenever the request can take effect (a `decoding`
+     * reason can pass with the next file). Off takes the upscaler out at
+     * once unless another plugin has it on. Upscaling is a request of the
+     * whole plugin, not of a {@link Scope}: disposing a scope does not turn
+     * it off.
+     *
+     * @capability video.upscaling
+     * @param enabled - `true` to ask for upscaling, `false` to withdraw the
+     *   request.
+     * @returns The new state.
+     * @throws `capability` (rejects) The manifest does not declare
+     *   `video.upscaling`.
+     * @throws `invalid` (rejects) `enabled` is not a boolean.
+     * @throws `unsupported` (rejects) `true` where upscaling cannot work in
+     *   this run: every {@link UpscalingReasonCode} except `decoding`, and
+     *   except `rendering` while GPU rendering is still starting (those two
+     *   are accepted and the request is kept until they pass); `message` is
+     *   the reason. Nothing changes. `false` is always accepted and answered
+     *   at once without the GPU check (before any check, `available` is
+     *   `false` with `unchecked`).
+     *
+     * @example Turn upscaling on and explain what is needed
+     * The plugin turns upscaling on from its settings and tells the user what
+     * else to switch on. `set(true)` records the request and resolves with the
+     * new state; where upscaling cannot work in this run it rejects with
+     * `unsupported` and the player's reason instead.
+     * ```ts
+     * try {
+     *   const state = await plugin.video.upscaling.set(true);
+     *   // The driver's own switch cannot be read: remind the user once.
+     *   if (state.enabled) await plugin.osd.show("Turn on Super Resolution in the NVIDIA app");
+     * } catch (error) {
+     *   if ((error as PluginError).code !== "unsupported") throw error;
+     *   await plugin.osd.show("AI upscaling: {}", [(error as PluginError).message]);
+     * }
+     * ```
+     *
+     * @since 1.5.37
+     */
+    set(enabled: boolean): Promise<UpscalingState>;
+}
 /**
  * A subtitle track of the current source.
  *

package/dist/wire.d.ts

@@ -336,6 +336,15 @@ export interface WireRenderingState {
         reason: WireRenderingReason | null;
     };
 }
+/** `video.upscaling.state` and `video.upscaling.set` (player 0.5.16). */
+export interface WireUpscalingState {
+    available: boolean;
+    /** The same `{ code, message }` shape as a rendering reason. */
+    reason: WireRenderingReason | null;
+    enabled: boolean;
+    requested: boolean;
+    factor: number | null;
+}
 /**
  * Template arguments on the wire (`osd.show`, `osd.panel`, `dialogs.confirm`,
  * a text's `args`): data, or text values (player 0.4.3).
@@ -468,6 +477,9 @@ export declare function createWire(transport: Transport): {
             state: "applied" | "waiting";
         }>;
         renderRelease: () => Promise<void>;
+        /** The GPU's video upscaler (`plugin.video.upscaling`, player 0.5.16). */
+        upscalingState: () => Promise<WireUpscalingState>;
+        upscalingSet: (enabled: boolean) => Promise<WireUpscalingState>;
     };
     /** Mark layers on the seek bar (`plugin.timeline`). */
     timeline: {

package/dist/wire.js

@@ -138,6 +138,11 @@ export function createWire(transport) {
             /** The GPU renderer's options (`plugin.video.render()`). */
             renderSet: (values) => transport.request("video.render.set", { values }),
             renderRelease: () => transport.request("video.render.release"),
+            /** The GPU's video upscaler (`plugin.video.upscaling`, player 0.5.16). */
+            upscalingState: () => transport.request("video.upscaling.state"),
+            upscalingSet: (enabled) => transport.request("video.upscaling.set", {
+                enabled,
+            }),
         },
         /** Mark layers on the seek bar (`plugin.timeline`). */
         timeline: {

package/llms-full.txt

@@ -1,4 +1,4 @@
-# @vestra-player/sdk 1.5.35: full reference
+# @vestra-player/sdk 1.5.37: 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.
 
@@ -743,6 +743,14 @@ plugin.video.render() returns the RenderOptions of the GPU renderer: HDR to SDR
 - **Only the GPU renderer has them.** Under software rendering every `set` fails with `unsupported`; see Reference: platforms for where the player renders on the GPU. Treat `unsupported` as "hide these settings", not as an error. To know before creating the handle, read rendering from `plugin.app.system()` (player 0.5.12, no capability): `"gpu"` or `"software"`.
 - A shader that does not compile is reported later: the status first becomes `applied`, then `failed` with code `failed` and the compiler's first error line once mpv first uses the shader.
 
+#### The GPU's video upscaler
+
+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.
+- **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.
+
 ## Concept: Windows, panels, settings pages, dialogs and the OSD
 
 A plugin can show its own user interface in five places. Three of them are drawn by the plugin's own Slint files: **tool windows**, **panels** and **settings pages**. Two are drawn by the player or the system from plain values: **dialogs** and the **on-screen display (OSD)**. This page explains what each one is, how to choose, how each one lives and dies, how Slint and TypeScript talk to each other, and what to watch out for.
@@ -2690,6 +2698,7 @@ The table lists the API whose documentation names a player version, newest last:
 | 0.5.10 | CommandButton, CommandOptions.button |
 | 0.5.12 | SystemInfo.rendering |
 | 0.5.13 | SystemInfo.renderingReason, RenderingMode, RenderingPreference, RenderingReasonCode, RenderingReason, RenderingState, Rendering |
+| 0.5.16 | UpscalingReasonCode, UpscalingReason, UpscalingState, VideoUpscaling |
 
 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).
 
@@ -2727,6 +2736,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 |  |
 
 **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:
 
@@ -3175,6 +3185,7 @@ Every command the player (`host`) and its built-in plugins register when the pla
 | Video ▸ Saturation +1% | `U` | `vestra.video/video.saturation.up` |
 | Video ▸ Hue -1% | `I` | `vestra.video/video.hue.down` |
 | Video ▸ Hue +1% | `O` | `vestra.video/video.hue.up` |
+| Video ▸ GPU Rendering (Experimental) |  | `vestra.video/video.gpu-rendering` |
 | Audio ▸ Volume + | `ArrowUp`, `Mouse:WheelUp` | `host/volume-up` |
 | Audio ▸ Volume − | `ArrowDown`, `Mouse:WheelDown` | `host/volume-down` |
 | Audio ▸ Mute | `M` | `host/mute` |
@@ -3389,6 +3400,7 @@ A plugin uses the same API on macOS and Windows; the player does the system-spec
 | Rendering | On the GPU (OpenGL), with hardware decoding. | In software, with hardware decoding copied back (`d3d11va-copy` and similar). |
 | plugin.rendering (player 0.5.13) | `"gpu"` can be chosen unless the driver is ruled out (`denylist`, `previous-crash`). | `gpu.available` is `false` (`no-gpu-backend`); `setPreference("gpu")` fails with `unsupported`. |
 | Render options (RenderOptions) | Available; `peakDetect` has no effect. | `unsupported` (software rendering). |
+| plugin.video.upscaling (player 0.5.16) | `available` is `false` (`platform`); `set(true)` fails with `unsupported`. | NVIDIA RTX Video Super Resolution: an RTX GPU with driver 530 or newer, GPU rendering on that GPU, the video decoded on it (`d3d11va`); the user must also turn on Super Resolution in the NVIDIA app, which no program can read. |
 | Bindings | `Ctrl` also matches ⌘; `Cmd` is ⌘. | `Cmd` is the Windows logo key; `Cmd+Q` does not quit. |
 | Keys taken first, standard close keys | See Keys the system takes first. | See Keys the system takes first. |
 | Interface font | The system font; CJK falls back per character to the system's fonts (PingFang, Hiragino). | The system font; CJK falls back per character to Windows' CJK fonts in the interface language's order, then the bundled Noto Sans CJK SC (the chain). |
@@ -3867,7 +3879,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 and the GPU render options. All 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`).
+   * 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.
    */
   readonly video: {
     /**
@@ -3888,6 +3900,10 @@ 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;
+    /**
+     * 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.
+     */
+    readonly upscaling: VideoUpscaling;
   };
   /** Audio processing: this plugin's filter chain and delay (`processing.audio`, `playback.read` and `events`, as for VideoFilter). */
   readonly audio: {
@@ -9404,6 +9420,251 @@ render.onStatus((s) => {
 render.set({ toneMapping: "bt.2390", targetPeak: 250 }); // nits
 ```
 
+### UpscalingReasonCode
+
+Why the GPU's video upscaler does not work, as a stable kebab-case code.
+A newer player may add codes: compare with the ones you handle and show
+UpscalingReason.message for the rest. The codes of player 0.5.16,
+in the order the player checks them (the first that holds is reported):
+
+| Code | Meaning |
+| --- | --- |
+| `platform` | The player has no video upscaler on this system (macOS, Linux). |
+| `no-gpu` | No GPU that can upscale video (Windows: no NVIDIA GPU). |
+| `driver` | The graphics driver is too old (Windows: an NVIDIA driver before 530). |
+| `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. |
+| `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
+during the run, so `set(true)` accepts them and keeps the request; every
+other reason holds until the player restarts, and `set(true)` rejects it.
+Turning upscaling off is always accepted.
+
+- @player 0.5.16
+
+```ts
+type UpscalingReasonCode = "platform" | "no-gpu" | "driver" | "gpu-unsupported" | "rendering" | "adapter" | "decoding" | "unchecked" | (string & {});
+```
+
+Example: Advise the user by reason
+
+The plugin shows its own advice for the reasons the user can act on and
+the player's message for the rest. `reason.code` is looked up among the
+codes the plugin knows; an unknown code from a newer player falls
+through to the message, which names the GPU and what to do.
+```ts
+const { reason } = await plugin.video.upscaling.state();
+// Advice for the codes this plugin knows; any other code shows the message.
+const advice: Partial<Record<UpscalingReasonCode, string>> = {
+  driver: "Update the NVIDIA driver to 530 or newer.",
+  rendering: "Turn on Video ▸ GPU Rendering (Experimental) and restart.",
+};
+if (reason) console.log(advice[reason.code] ?? reason.message);
+```
+
+### UpscalingReason
+
+Why the GPU's video upscaler does not work: a stable
+UpscalingReasonCode to branch on and a sentence to show, the same
+shape as RenderingReason.
+
+- @player 0.5.16
+
+```ts
+interface UpscalingReason {
+  /** The reason as a stable kebab-case code; branch on this. */
+  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;
+}
+```
+
+Example: Grey out a menu item with the player's reason
+
+The plugin disables its upscaling item and shows why. `message` is the
+player's English text, naming the GPU and what the user can do (turn on
+GPU rendering, choose the other GPU, update the driver); `code` is for
+decisions.
+```ts
+const { available, reason } = await plugin.video.upscaling.state();
+if (!available && reason) console.log(`${reason.code}: ${reason.message}`);
+```
+
+### UpscalingState
+
+What VideoUpscaling.state and VideoUpscaling.set report:
+whether the upscaler works now and why not, whether this plugin turned
+it on, and whether the player asked the GPU to upscale.
+
+`requested` is as far as the player can see. The player puts the
+upscaler last in the video filter chain, scaling the video to the area it
+is shown in; the driver gives no sign that it upscales. On Windows the
+user must also turn on Super Resolution in the NVIDIA app (System ▸ Video
+▸ RTX Video Enhancement), which no program can read: say so next to the
+switch.
+
+- @player 0.5.16
+
+```ts
+interface UpscalingState {
+  /** Whether the upscaler works now; `false` with UpscalingState.reason. */
+  readonly available: boolean;
+  /** Why it does not work now; `null` while it does. */
+  readonly reason: UpscalingReason | null;
+  /** This plugin asked for upscaling (VideoUpscaling.set) and has not turned it off. */
+  readonly enabled: boolean;
+  /**
+   * The player has the upscaler in the video filter chain now, for this plugin or another one: upscaling is enabled and available and the video is shown larger than its own size. Not a sign that the GPU upscales (see the remarks).
+   */
+  readonly requested: boolean;
+  /**
+   * 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;
+}
+```
+
+Example: Label the item with what happens now
+
+The plugin's menu item says whether upscaling is on and whether the
+video is being upscaled. `enabled` is this plugin's own request;
+`requested` is true while the player has the upscaler in the filter
+chain, which needs a video shown larger than its own size (`factor`
+above 1).
+```ts
+const state = await plugin.video.upscaling.state();
+// `enabled`: this plugin's request; `requested`: in the filter chain now.
+const label = !state.enabled
+  ? "AI Upscaling: Off"
+  : state.requested
+    ? `AI Upscaling: On (×${state.factor?.toFixed(2)})`
+    : "AI Upscaling: On (not needed for this video)";
+console.log(label);
+```
+
+### VideoUpscaling
+
+`plugin.video.upscaling`: the GPU's video upscaler, NVIDIA RTX Video
+Super Resolution on Windows (`video.upscaling`). Read whether it works
+here and why not; turn it on or off for this plugin.
+
+The player checks the GPU once, when a plugin first asks, and keeps the
+answer: the check wakes a sleeping discrete GPU, so call
+VideoUpscaling.state when the plugin first needs the answer (the
+first time the user picks its upscaling item), not while the plugin
+starts, and do not poll it. `set(false)` never starts the check. It works
+only with GPU rendering, on the GPU the upscaler runs on, with the video decoded on that GPU; UpscalingReasonCode
+lists what can stand in the way.
+
+While some plugin has it on and it works, the player puts the upscaler
+last in the video filter chain and scales the video to the area it is
+shown in, following window and video size changes (a resize waits until
+the size holds). A video already shown at its own size or smaller is not
+upscaled. The upscaler stays while any plugin has it on; it goes when the
+last one turns it off or stops: the player revokes a stopped plugin's
+request.
+
+**Windows:** the user must turn on Super Resolution in the NVIDIA app
+(System ▸ Video ▸ RTX Video Enhancement); no program can read that
+switch, and the driver gives no sign that it upscales
+(UpscalingState.requested is as far as the player can see). It
+uses the NVIDIA GPU, so power use and heat go up, and on a laptop with
+two GPUs the whole player must run on the NVIDIA one.
+**macOS, Linux:** `available` is `false` with `platform`.
+
+Players before 0.5.16 do not know `video.upscaling` and do not load a
+plugin that declares it: declare `"minPlayerVersion": "0.5.16"`.
+
+- @capability video.upscaling
+- @player 0.5.16; older players do not load a plugin that declares `video.upscaling`.
+
+```ts
+interface VideoUpscaling {
+  /**
+   * Read whether the upscaler works now and why not, whether this plugin turned it on and what the player asked the GPU for.
+   * @capability video.upscaling
+   * @returns The state, once the player's GPU check ran (the first call starts it and may take a moment).
+   * @throws capability (rejects) The manifest does not declare `video.upscaling`.
+   * @example Find out whether upscaling can work here
+   * The plugin reads the state the first time the user picks its upscaling
+   * item and keeps it for the item. The first call makes the player check the GPU (which
+   * wakes a sleeping discrete GPU) and later calls reuse the answer; the
+   * rest (GPU rendering, the GPU it runs on, the decoding) is read at
+   * each call.
+   * ```ts
+   * const { available, reason } = await plugin.video.upscaling.state();
+   * if (!available) console.log(reason?.message);
+   * ```
+   */
+  state(): Promise<UpscalingState>;
+  /**
+   * Turn upscaling on or off for this plugin.
+   *
+   * On stays this plugin's request until it turns it off or stops; the
+   * player upscales whenever the request can take effect (a `decoding`
+   * reason can pass with the next file). Off takes the upscaler out at
+   * once unless another plugin has it on. Upscaling is a request of the
+   * whole plugin, not of a Scope: disposing a scope does not turn
+   * it off.
+   * @capability video.upscaling
+   * @param enabled - `true` to ask for upscaling, `false` to withdraw the request.
+   * @returns The new state.
+   * @throws capability (rejects) The manifest does not declare `video.upscaling`.
+   * @throws invalid (rejects) `enabled` is not a boolean.
+   * @throws unsupported (rejects) `true` where upscaling cannot work in this run: every UpscalingReasonCode except `decoding`, and except `rendering` while GPU rendering is still starting (those two are accepted and the request is kept until they pass); `message` is the reason. Nothing changes. `false` is always accepted and answered at once without the GPU check (before any check, `available` is `false` with `unchecked`).
+   * @example Turn upscaling on and explain what is needed
+   * The plugin turns upscaling on from its settings and tells the user what
+   * else to switch on. `set(true)` records the request and resolves with the
+   * new state; where upscaling cannot work in this run it rejects with
+   * `unsupported` and the player's reason instead.
+   * ```ts
+   * try {
+   *   const state = await plugin.video.upscaling.set(true);
+   *   // The driver's own switch cannot be read: remind the user once.
+   *   if (state.enabled) await plugin.osd.show("Turn on Super Resolution in the NVIDIA app");
+   * } catch (error) {
+   *   if ((error as PluginError).code !== "unsupported") throw error;
+   *   await plugin.osd.show("AI upscaling: {}", [(error as PluginError).message]);
+   * }
+   * ```
+   */
+  set(enabled: boolean): Promise<UpscalingState>;
+}
+```
+
+Example: Offer AI upscaling as a menu item
+
+A Video menu item turns upscaling on and off; once the player said it
+cannot work here, the item is greyed out with the player's reason. The
+state is read the first time the user picks the item (that runs the
+player's GPU check, so nothing wakes the GPU while the plugin starts) and
+again after each pick; `set` resolves with the new state, or rejects with
+`unsupported` where upscaling cannot work in this run.
+```ts
+let state: UpscalingState | null = null; // unknown until first picked
+plugin.commands.add({
+  id: "upscaling",
+  path: ["@video", "AI Upscaling"],
+  checked: () => state?.enabled ?? false,
+  // Greyed only once the player said it cannot work (`decoding` can pass).
+  enabled: () => state === null || state.available || state.reason?.code === "decoding",
+  reason: () => state?.reason?.message ?? null, // shown while disabled
+  run: async () => {
+    state ??= await plugin.video.upscaling.state(); // the first pick checks the GPU
+    try {
+      state = await plugin.video.upscaling.set(!(state?.enabled ?? false));
+    } catch (error) {
+      // Cannot work in this run (no RTX GPU, software rendering…).
+      if ((error as PluginError).code !== "unsupported") throw error;
+      state = await plugin.video.upscaling.state();
+    }
+  },
+});
+```
+
 ### SubtitleTrack
 
 A subtitle track of the current source.
@@ -12503,7 +12764,8 @@ Members fall into a few groups:
   TestHost.app, TestHost.systemInfo,
   TestHost.chapters, TestHost.audioDevices,
   TestHost.secrets, TestHost.clipboard,
-  TestHost.tools, TestHost.rendering.
+  TestHost.tools, TestHost.rendering,
+  TestHost.upscaling.
 - **Assert** on records: TestHost.osd, TestHost.calls,
   TestHost.sent, TestHost.conflicts,
   TestHost.layout, TestHost.menus, and many more.
@@ -13406,6 +13668,62 @@ class TestHost implements Transport {
     /** Accepted `restartPlayer` calls. */
     restarts: number;
   };
+  /**
+   * 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.
+   * - `set(true)` refuses with `unsupported` and the reason's message while
+   *   `reason` is set, unless its code is `decoding`, or `rendering` with
+   *   `renderingStarting` (GPU rendering still starting): those can pass
+   *   during the run, so the player keeps the request. Nothing changes when
+   *   it refuses.
+   * - `set(false)` always succeeds and does not check the GPU: before any
+   *   check it reports `available: false` with the reason `unchecked`.
+   *
+   * Inject other answers with `host.handle("video.upscaling.set", …)`. The
+   * defaults are a player where upscaling works and a 1080p video shown
+   * full screen on a 4K display (`factor` 2), whatever `systemInfo` says.
+   * @example Test the menu item on a computer without an RTX GPU
+   * The plugin's upscaling item is greyed out with the player's reason after
+   * the user first picks it. Starting the plugin checks nothing (`checked`
+   * stays false, so no GPU wakes up); the first pick reads the state, and
+   * `set(true)` would reject with `unsupported`, as in the player.
+   * ```ts
+   * import assert from "node:assert/strict";
+   * import { startPlugin, TestHost } from "@vestra-player/sdk/testing";
+   * import activate from "../main.ts";
+   *
+   * const host = new TestHost();
+   * host.upscaling.reason = { code: "no-gpu", message: "no NVIDIA GPU" };
+   * const { stop } = await startPlugin(activate, {
+   *   directory: new URL("..", import.meta.url),
+   *   host,
+   * });
+   * assert.equal(host.upscaling.checked, false); // starting woke no GPU
+   * const item = host.command("upscaling");
+   * await item.run(); // the first pick checks the GPU
+   * assert.equal(item.state.enabled, false); // greyed out
+   * assert.equal(item.state.reason, "no NVIDIA GPU"); // the player's message
+   * await stop();
+   * ```
+   */
+  readonly upscaling: {
+    /** Why upscaling does not work; `null` while it does. */
+    reason: UpscalingReason | null;
+    /** Whether this plugin has upscaling on (`set`); a test may preset it. */
+    enabled: boolean;
+    /** The factor the player would request; `null` or at most 1: the video needs no upscaling. */
+    factor: number | null;
+    /** Whether the plugin made the player check the GPU (`state`, `set(true)`). */
+    checked: boolean;
+    /** GPU rendering is still starting: a `rendering` reason then lets `set(true)` keep the request. */
+    renderingStarting: boolean;
+  };
   /** What `player.chapters()` lists while media is ready. */
   chapters: {
     /** The chapter title, `null` without one. */
@@ -14329,7 +14647,10 @@ menu last): their key paths, default bindings and owners. Use it to pick
 a menu place and default keys that do not collide with the player's (the
 user's own changes come on top; see Bindings). Menu items built
 from content (tracks, recent files, output devices) are not listed; their
-placeholders (`No Audio Tracks`) are. The player's tests check that this
+placeholders (`No Audio Tracks`) are. Items that appear only in a
+passing state are not listed either: the Picture Adjustments plugin's
+`Video ▸ Restart Player to Apply` (`video.gpu-rendering.restart`), shown
+while a rendering choice waits for the next start. The player's tests check that this
 list agrees with what the player and its built-in plugins register.
 
 ```ts

package/llms.txt

@@ -1,6 +1,6 @@
 # Vestra Player SDK
 
-> @vestra-player/sdk 1.5.35: 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.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.
 
 **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: L2628–2697.
+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.
 
 **main.ts**
 
@@ -77,9 +77,10 @@ export default async function activate(plugin: Plugin) {
 - `ui.theme`: Appearance.set/setLanguage
 - `secrets`: Secrets.get/set/delete
 - `rendering.manage`: Rendering.setPreference/restartPlayer
-- No capability: `tools`, `storage`, `system`, `app`, `ui` (images and Markdown), `i18n`, reading window.state, appearance.theme, packages.list and rendering.state. Details: L2698–2757.
+- `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.
 
-**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: L2069–2257; TestHost: L12483.
+**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.
 
 **Command line**
 
@@ -107,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 L3758.
+- Others: PluginError, llms-full.txt L3770.
 
 ## 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–745; Windows, panels, settings pages, dialogs and the OSD L746–1034
-- How-to: Control playback L1035–1163; Store a plugin's data L1164–1231; Load subtitles from a plugin L1232–1310; Keep a slider responsive while dragging L1311–1485; Remember a window's state between runs L1486–1615; Offer a GPU rendering switch L1616–1736; Translate a plugin L1737–1920; Migrate a plugin to English source text L1921–2068; Test a plugin L2069–2257; Publish a plugin L2258–2346; Migrating off package rollback (1.5.16, removed in 1.5.17) L2347–2422
-- Guidelines: Interface guidelines L2423–2530; Menu guidelines L2531–2627
-- Reference: Manifest L2628–2697; Capabilities L2698–2757; Limits L2758–2887; Commands, menus and bindings L2888–3370; Platforms L3371–3400; Theme L3401–3622; Command line L3623–3680
-- [API: @vestra-player/sdk](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk.html): L3681–12167
-- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html): L12168–14823
+- 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
 
 ## API
 
 Where each `plugin.<module>` is declared:
 
-- Plugin L4080, Scope L3833, PluginError L3758, Disposable L3696
-- Commands L4477; Windows L5414; Panels L6860; Dialogs L7528; Player L8269; video: VideoFilter L9149, VideoView L9249, RenderOptions L9336; audio: AudioFilter L9194; Subtitles L9483; media: MediaCapture L9887; Resolvers L10117; Packages L10515; Osd L9014; Host L8856; Clipboard L10843; Power L10930; Tools L10989; Storage L11141; System L11340; Secrets L11420; window: MainWindow L7177; App L7357; Rendering L11683; Bindings L10743; Ui L4766; Timeline L7089; Drops L6107; Appearance L6188; I18n L6421; Settings L6704.
+- 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.
 
 ## 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. L15258–15347
-- blur: A tool window with one slider that blurs the playing video. L15348–15609
-- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L15610–15942
-- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L15943–16129
-- panel-menu: A sidebar panel with its own right-click menu. L16130–16338
-- menus: Radio menu items, separator groups and a menu item whose title changes. L16339–16498
-- theme-widgets: A tool window drawn with the player's theme and widgets. L16499–16662
-- markdown: A window that shows a Markdown document. L16663–16859
-- i18n: A plugin in the player's language: English source text, a Chinese translation. L16860–17027
+- 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
 
 ## Optional
 

package/package.json

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