@vestra-player/sdk 1.5.33 → 1.5.35

package/dist/plugin/types.d.ts

@@ -293,6 +293,8 @@ export interface Scope extends Disposable {
     readonly window: MainWindow;
     /** The player's version and components, and the system it runs on. */
     readonly app: App;
+    /** GPU or software rendering: read the choice, change it (`rendering.manage`). */
+    readonly rendering: Rendering;
     /** Every command's bindings and the user's overrides (`bindings.manage`). */
     readonly bindings: Bindings;
     /** Runtime images for Slint `image` properties. */
@@ -3991,8 +3993,9 @@ export interface AppInfo {
  */
 export interface App extends AppInfo {
     /**
-     * The operating system and the displays, read when called (displays come
-     * and go). No capability. CPU and memory: Node's `os` module.
+     * The operating system, the displays and the renderer, read when called
+     * (displays come and go; the renderer can fall back from GPU to software
+     * once). No capability. CPU and memory: Node's `os` module.
      *
      * @capability None.
      * @throws `busy` (rejects) The player could not start the request (no
@@ -4034,6 +4037,71 @@ export interface SystemInfo {
     readonly arch: string;
     /** Primary display first; empty without a user interface. */
     readonly displays: readonly DisplayInfo[];
+    /**
+     * Which renderer draws the video now: `"gpu"` (the GPU renderer, so
+     * {@link RenderOptions | render options} apply) or `"software"` (they
+     * fail with `unsupported`). Read at each call. It changes at most once
+     * while the player runs, from `"gpu"` to `"software"` when a window
+     * cannot show GPU frames; the owner of the render options hears that
+     * switch through {@link RenderOptions.onStatus}.
+     *
+     * Absent (`undefined`) on players before 0.5.12, which do not report it:
+     * the renderer is then unknown, not software.
+     *
+     * Today the player renders on the GPU on macOS and in software on
+     * Windows, Linux and without a user interface (see
+     * [Platforms](../../docs/reference/platforms.md)); test this field
+     * rather than {@link SystemInfo.os}.
+     *
+     * @example Offer the HDR menu only where render options work
+     * The plugin adds its HDR command only when the player renders on the
+     * GPU, instead of creating the render options just to find out from a
+     * failed status. `system()` asks the player, which reports the renderer
+     * drawing at that moment; no capability is needed to ask. A player before
+     * 0.5.12 leaves the field out, so the test is for `"gpu"` exactly (an
+     * older player gets no HDR command).
+     * ```ts
+     * const { rendering } = await plugin.app.system();
+     * if (rendering === "gpu") {
+     *   const render = plugin.video.render(); // one handle, kept
+     *   plugin.commands.add({
+     *     id: "hdr",
+     *     path: ["@video", "HDR Tone Mapping"],
+     *     run: () => render.set({ toneMapping: "bt.2390", targetPeak: 250 }),
+     *   });
+     * }
+     * ```
+     *
+     * @player 0.5.12; older players leave it out (declare
+     * `"minPlayerVersion": "0.5.12"` when the plugin relies on it).
+     * @since 1.5.34
+     */
+    readonly rendering?: "gpu" | "software";
+    /**
+     * Why {@link SystemInfo.rendering} is what it is now: the same reason as
+     * {@link RenderingState.reason} (`default`, `no-gpu-backend`,
+     * `preference`, `denylist`, `window-fallback`…, see
+     * {@link RenderingReasonCode}). Read at each call, like `rendering`.
+     *
+     * Absent (`undefined`) on players before 0.5.13.
+     *
+     * @example Say why the video is drawn in software
+     * An About page explains a software renderer with the player's own words,
+     * for example that the graphics driver is on the player's denylist.
+     * `system()` reports the renderer and its reason together, with no
+     * capability; the message is English text that may name the adapter and
+     * the driver version.
+     * ```ts
+     * const { rendering, renderingReason } = await plugin.app.system();
+     * if (rendering === "software" && renderingReason)
+     *   console.log(`Rendering: software (${renderingReason.message})`);
+     * ```
+     *
+     * @player 0.5.13; older players leave it out (declare
+     * `"minPlayerVersion": "0.5.13"` when the plugin relies on it).
+     * @since 1.5.35
+     */
+    readonly renderingReason?: RenderingReason;
 }
 /**
  * One display in {@link SystemInfo.displays}.
@@ -6294,8 +6362,10 @@ export interface RenderSettings {
  *
  * Platforms: only macOS renders on the GPU. Under software rendering
  * (Windows, Linux, headless, fallback) every `set` fails with
- * `unsupported`. macOS OpenGL 4.1 has no compute shaders, so `peakDetect`
- * is accepted but has no effect; output is always SDR.
+ * `unsupported`; {@link SystemInfo.rendering} tells which renderer draws
+ * without creating the handle. macOS OpenGL 4.1 has no
+ * compute shaders, so `peakDetect` is accepted but has no effect; output
+ * is always SDR.
  *
  * @example Tone-map HDR video and hide the menu where it cannot work
  * On a GPU-rendering player HDR video is tone-mapped with BT.2390 for a
@@ -6591,7 +6661,10 @@ export interface Subtitles {
      *
      * Limits: SRT ≤ 2 MiB and ≤ 10,000 cues; ASS ≤ 2 MiB with `[Script Info]`
      * and `[Events]` and 1–20,000 `Dialogue:` lines. Convert other formats
-     * (VTT, SAMI) to SRT first.
+     * (VTT, SAMI) to SRT first. Per source, a plugin has at most 4 loaded
+     * tracks at once and loads at most 16 files (removed ones count), and
+     * every plugin together at most 16 tracks; see `SUBTITLE_LIMITS` in
+     * `@vestra-player/sdk/testing`.
      *
      * @capability subtitles.control and subtitles.read
      * @throws `invalid` (rejects) A bad `format` or `title`, or a file over the
@@ -6602,7 +6675,10 @@ export interface Subtitles {
      *   loading.
      * @throws `aborted` (rejects) `signal` aborted before the commit (an
      *   `AbortError`); the upload is discarded.
-     * @throws `busy` (rejects) Too many subtitle operations at once.
+     * @throws `busy` (rejects) Too many subtitle operations at once, or a
+     *   limit of `SUBTITLE_LIMITS` is reached (4 tracks of this plugin, 16
+     *   loads of this plugin or 16 tracks in the source, or another of its
+     *   limits); nothing is loaded.
      * @throws `capability` (rejects) The manifest does not declare
      *   `subtitles.control` and `subtitles.read`.
      *
@@ -8885,3 +8961,329 @@ export interface Secrets {
      */
     delete(name: string): Promise<void>;
 }
+/**
+ * Which renderer draws the video: `"gpu"` (the GPU renderer, where
+ * {@link RenderOptions | render options} apply) or `"software"` (they fail
+ * with `unsupported`). The same values as {@link SystemInfo.rendering}.
+ *
+ * @example Tell the user which renderer draws the video
+ * The plugin shows "Rendering: GPU" or "Rendering: software" on the
+ * video. `state()` asks the player; `mode` is the renderer drawing now,
+ * which can differ from the saved choice until the next start.
+ * ```ts
+ * const { mode } = await plugin.rendering.state();
+ * const label: Record<RenderingMode, string> = { gpu: "GPU", software: "software" };
+ * await plugin.osd.show("Rendering: {}", [label[mode]]);
+ * ```
+ *
+ * @player 0.5.13
+ * @since 1.5.35
+ * @category Services
+ */
+export type RenderingMode = "gpu" | "software";
+/**
+ * The user's saved rendering choice: `"auto"` (the player decides: the GPU
+ * where this system has a GPU renderer that is not ruled out, software
+ * elsewhere), `"gpu"` or `"software"`. It applies from the next start.
+ *
+ * @example Describe the saved choice on a settings page
+ * The plugin turns the saved choice into the words its settings page
+ * shows. `preference` is what the user chose, not what draws now:
+ * {@link RenderingState.nextMode} says what the next start will use.
+ * ```ts
+ * const { preference } = await plugin.rendering.state();
+ * // One word per choice; the Record type makes sure none is missing.
+ * const words: Record<RenderingPreference, string> = {
+ *   auto: "Automatic",
+ *   gpu: "GPU",
+ *   software: "Software",
+ * };
+ * console.log(words[preference]);
+ * ```
+ *
+ * @player 0.5.13
+ * @since 1.5.35
+ * @category Services
+ */
+export type RenderingPreference = "auto" | "gpu" | "software";
+/**
+ * Why the player renders the way it does, as a stable kebab-case code. A
+ * newer player may add codes: compare with the ones you handle and show
+ * {@link RenderingReason.message} for the rest. The codes of player 0.5.13:
+ *
+ * | Code | Meaning |
+ * | --- | --- |
+ * | `default` | Nothing ruled the GPU out; the platform's default. |
+ * | `pending` | GPU rendering is starting. |
+ * | `headless` | The player runs without a user interface. |
+ * | `no-gpu-backend` | This player has no GPU renderer on this system (Windows today). |
+ * | `env` | The environment chose it (`VESTRA_RENDER`, `VESTRA_SOFTWARE_RENDER`). |
+ * | `preference` | The user chose software rendering ({@link Rendering.setPreference}); GPU chosen and available reports `default`. |
+ * | `denylist` | The graphics driver is on the player's denylist. |
+ * | `previous-crash` | GPU rendering crashed at an earlier start; it is tried again after a driver or player update, or after 7 days. |
+ * | `init-failed` | GPU rendering could not start. |
+ * | `window-fallback` | A window could not show GPU frames; the player switched to software during the run. |
+ *
+ * @example Explain a driver problem differently from a user choice
+ * The plugin adds advice only when the graphics driver is the cause.
+ * `reason.code` is looked up among the codes the plugin knows; an unknown
+ * code from a newer player falls through to the player's own message.
+ * ```ts
+ * const { reason } = await plugin.rendering.state();
+ * // Advice for the codes this plugin knows; any other code shows the message.
+ * const advice: Partial<Record<RenderingReasonCode, string>> = {
+ *   denylist: "Update the graphics driver to use the GPU.",
+ *   "previous-crash": "The GPU renderer crashed earlier; it is retried after an update.",
+ * };
+ * console.log(advice[reason.code] ?? reason.message);
+ * ```
+ *
+ * @player 0.5.13
+ * @since 1.5.35
+ * @category Services
+ */
+export type RenderingReasonCode = "default" | "pending" | "headless" | "no-gpu-backend" | "env" | "preference" | "denylist" | "previous-crash" | "init-failed" | "window-fallback" | (string & {});
+/**
+ * Why the player renders, or will render, the way it does: a stable
+ * {@link RenderingReasonCode} to branch on and a sentence to show.
+ *
+ * @example Show why GPU rendering is off
+ * The plugin logs the player's explanation when the video is drawn in
+ * software. `message` is the player's English text and may name the
+ * graphics adapter and driver version; `code` is for decisions.
+ * ```ts
+ * const { mode, reason } = await plugin.rendering.state();
+ * if (mode === "software") console.log(`${reason.code}: ${reason.message}`);
+ * ```
+ *
+ * @player 0.5.13
+ * @since 1.5.35
+ * @category Services
+ */
+export interface RenderingReason {
+    /** The reason as a stable kebab-case code; branch on this. */
+    readonly code: RenderingReasonCode;
+    /**
+     * The reason as English text for people, for example with the graphics
+     * adapter's name and driver version; never branch on it.
+     */
+    readonly message: string;
+}
+/**
+ * What {@link Rendering.state} and {@link Rendering.setPreference} report:
+ * the renderer drawing now and why, the saved choice, what the next start
+ * will use, and whether `"gpu"` can be chosen.
+ *
+ * @example Label a menu item while a change waits for a restart
+ * The plugin adds "(Restart to Apply)" to its GPU item after the user
+ * changed the choice. `restartPending` compares the mode the next start
+ * will use with the mode this run started with, so it turns false again
+ * when the user changes the choice back.
+ * ```ts
+ * const state = await plugin.rendering.state();
+ * const title = state.restartPending
+ *   ? "GPU Rendering (Experimental) (Restart to Apply)"
+ *   : "GPU Rendering (Experimental)";
+ * console.log(title, state.nextMode, state.nextReason.message);
+ * ```
+ *
+ * @player 0.5.13
+ * @since 1.5.35
+ * @category Services
+ */
+export interface RenderingState {
+    /** The renderer drawing the video now; the same as {@link SystemInfo.rendering}. */
+    readonly mode: RenderingMode;
+    /** Why {@link RenderingState.mode} is what it is now. */
+    readonly reason: RenderingReason;
+    /** The saved choice; it applies from the next start. */
+    readonly preference: RenderingPreference;
+    /**
+     * The renderer the next start will use, as far as the player knows now:
+     * from the saved choice, the environment, the driver denylist and an
+     * earlier GPU crash.
+     */
+    readonly nextMode: RenderingMode;
+    /** Why the next start will use {@link RenderingState.nextMode}. */
+    readonly nextReason: RenderingReason;
+    /**
+     * `true` while {@link RenderingState.nextMode} differs from the mode this
+     * run started with, so a restart would change the renderer; `false` again
+     * when the user changes the choice back.
+     */
+    readonly restartPending: boolean;
+    /** Whether the user can choose `"gpu"` now. */
+    readonly gpu: {
+        /** `true` when `setPreference("gpu")` would be accepted. */
+        readonly available: boolean;
+        /**
+         * Why `"gpu"` cannot be chosen (`no-gpu-backend`, `headless`,
+         * `denylist`, `previous-crash`…); `null` while it is available.
+         */
+        readonly reason: RenderingReason | null;
+    };
+}
+/**
+ * `plugin.rendering`: the player's rendering choice, GPU or software.
+ * Reading it needs no capability; changing the saved choice and restarting
+ * the player need `rendering.manage`.
+ *
+ * @remarks
+ * The choice works like a browser's hardware acceleration switch: the
+ * player saves it in its own settings at once, and the running player
+ * keeps its renderer. The next start uses it, whether the user restarts
+ * now through {@link Rendering.restartPlayer} or quits and starts the
+ * player later. The player can still rule the GPU out at a start (an
+ * environment variable, a graphics driver on its denylist, a GPU crash at
+ * an earlier start); {@link RenderingState.nextMode} and
+ * {@link RenderingState.nextReason} say what the next start will do.
+ *
+ * The renderer is a choice for the whole player and a restart stops every
+ * plugin, so change it only when the user asks. A plugin that only needs
+ * to know whether render options work reads {@link SystemInfo.rendering}.
+ *
+ * Players before 0.5.13 do not know these requests: `state()` rejects with
+ * `unsupported`, and they do not load a plugin that declares
+ * `rendering.manage` (an unknown capability). Declare
+ * `"minPlayerVersion": "0.5.13"` when the plugin needs this.
+ *
+ * @example Offer GPU rendering as a menu item
+ * Settings ▸ GPU Rendering (Experimental) carries a check mark while the
+ * next start will draw on the GPU, is greyed out with the player's reason
+ * where the GPU cannot be chosen, and saves the other choice when picked.
+ * `state()` reads the player's view once; `setPreference` saves the choice
+ * and resolves with the new state, which the item's bound values read
+ * again after the handler. The how-to guide adds the restart.
+ * ```ts
+ * let state = await plugin.rendering.state();
+ * plugin.commands.add({
+ *   id: "gpu-rendering",
+ *   path: ["@settings", "GPU Rendering (Experimental)"],
+ *   checked: () => state.nextMode === "gpu", // also for "auto" on a GPU system
+ *   enabled: () => state.gpu.available,
+ *   reason: () => state.gpu.reason?.message ?? null, // shown while disabled
+ *   run: async () => {
+ *     const choice = state.nextMode === "gpu" ? "software" : "gpu";
+ *     state = await plugin.rendering.setPreference(choice);
+ *   },
+ * });
+ * ```
+ *
+ * @capability None to read the state; `rendering.manage` to change the
+ *   choice or restart the player.
+ * @see [Offer a GPU rendering switch](../../docs/how-to/gpu-rendering.md)
+ * @player 0.5.13; older players reject the requests as unknown
+ * (`unsupported`).
+ * @since 1.5.35
+ * @category Services
+ */
+export interface Rendering {
+    /**
+     * Read the renderer drawing now, the saved choice, what the next start
+     * will use and whether `"gpu"` can be chosen. No capability.
+     *
+     * @capability None.
+     * @throws `unsupported` (rejects) A player before 0.5.13, which does not
+     *   know the request.
+     *
+     * @example Find out whether the GPU can be chosen
+     * The plugin reads the state once while it starts and keeps it for its
+     * menu. Each call asks the player; `gpu.available` is false, with a
+     * reason, where this player has no GPU renderer, without a user
+     * interface, or when the driver is ruled out. An older player rejects
+     * with `unsupported`, and the plugin then offers nothing.
+     * ```ts
+     * const state = await plugin.rendering.state().catch((error: PluginError) => {
+     *   if (error.code === "unsupported") return null; // a player before 0.5.13
+     *   throw error;
+     * });
+     * if (state && !state.gpu.available) console.log(state.gpu.reason?.message);
+     * ```
+     *
+     * @since 1.5.35
+     */
+    state(): Promise<RenderingState>;
+    /**
+     * Save the user's rendering choice. The player writes it to its settings
+     * at once; the running player keeps its renderer, and the next start
+     * uses the choice whether or not the user restarts now. `"auto"` and
+     * `"software"` are always accepted.
+     *
+     * @param preference - `"auto"`, `"gpu"` or `"software"`.
+     * @returns The new state; {@link RenderingState.restartPending} tells
+     *   whether a restart would change the renderer.
+     *
+     * @capability rendering.manage
+     * @throws `invalid` (rejects) `preference` is not `"auto"`, `"gpu"` or
+     *   `"software"`.
+     * @throws `unsupported` (rejects) `"gpu"` where this player has no GPU
+     *   renderer on this system, or runs without a user interface; also any
+     *   value on a player before 0.5.13.
+     * @throws `unavailable` (rejects) `"gpu"` while it is ruled out: the
+     *   graphics driver is on the player's denylist, or GPU rendering crashed
+     *   at an earlier start. The message says which, with the adapter's name
+     *   and the driver version.
+     * @throws `failed` (rejects) The player could not write its settings file.
+     * @throws `capability` (rejects) The manifest does not declare
+     *   `rendering.manage`.
+     *
+     * @example Switch back to the automatic choice
+     * A Reset item returns the renderer to the player's own choice and tells
+     * the user when it takes effect. `setPreference` saves the choice and
+     * resolves with the new state; `restartPending` is true when the next
+     * start will draw differently from this run. A refused save leaves the
+     * old choice in place.
+     * ```ts
+     * try {
+     *   const state = await plugin.rendering.setPreference("auto");
+     *   if (state.restartPending) await plugin.osd.show("Applies after a restart");
+     * } catch (error) {
+     *   // `failed`: the player's settings file could not be written.
+     *   await plugin.osd.show("Not saved ({})", [(error as PluginError).code]);
+     * }
+     * ```
+     *
+     * @since 1.5.35
+     */
+    setPreference(preference: RenderingPreference): Promise<RenderingState>;
+    /**
+     * Restart the player so that a changed choice applies now. Resolves once
+     * the player has accepted; the player then quits normally, which stops
+     * every plugin (this one included), and starts again with the same
+     * plugins. A local file that was open continues at its position, paused
+     * or playing as it was; a stream or another source that is not a file is
+     * not reopened.
+     *
+     * @capability rendering.manage
+     * @throws `unsupported` (rejects) The player runs without a user
+     *   interface; also a player before 0.5.13.
+     * @throws `busy` (rejects) A restart is already under way, or this player
+     *   was itself started by a restart less than 30 seconds ago (so a plugin
+     *   that restarts on activation cannot make a loop).
+     * @throws `failed` (rejects) The new player process could not be started;
+     *   the player keeps running.
+     * @throws `capability` (rejects) The manifest does not declare
+     *   `rendering.manage`.
+     *
+     * @example Restart after asking the user
+     * After the user changed the renderer, the plugin offers to restart now.
+     * `confirm` asks first, because a restart closes every window (it needs
+     * `ui.dialog`); once `restartPlayer` resolves, the player is quitting and
+     * will stop this plugin, so nothing else is started after it.
+     * ```ts
+     * const { confirmed } = await plugin.dialogs.confirm({
+     *   message: "Restart the player now?",
+     *   detail: "The new renderer is used from the restart on. The video continues where it is.",
+     *   confirm: "Restart",
+     * });
+     * if (confirmed)
+     *   await plugin.rendering.restartPlayer().catch((error: PluginError) => {
+     *     // `failed`: the new player could not start; this one keeps running.
+     *     void plugin.osd.show("Could not restart ({})", [error.code]);
+     *   });
+     * ```
+     *
+     * @since 1.5.35
+     */
+    restartPlayer(): Promise<void>;
+}

package/dist/wire.d.ts

@@ -297,7 +297,7 @@ export interface LocalServices {
         signal: AbortSignal;
     }): Promise<Uint8Array>;
 }
-/** `app.system`: the operating system and the displays. */
+/** `app.system`: the operating system, the displays and the renderer. */
 export interface WireSystemInfo {
     os: "macos" | "windows" | "linux" | "other";
     name: string;
@@ -313,6 +313,28 @@ export interface WireSystemInfo {
         refreshRate: number | null;
         primary: boolean;
     }[];
+    /** Player 0.5.12; older players leave it out. */
+    rendering?: "gpu" | "software";
+    /** Why `rendering` is what it is (player 0.5.13; older players leave it out). */
+    renderingReason?: WireRenderingReason;
+}
+/** A rendering reason: a stable kebab-case `code` and English text. */
+export interface WireRenderingReason {
+    code: string;
+    message: string;
+}
+/** `rendering.state` and `rendering.setPreference` (player 0.5.13). */
+export interface WireRenderingState {
+    mode: "gpu" | "software";
+    reason: WireRenderingReason;
+    preference: "auto" | "gpu" | "software";
+    nextMode: "gpu" | "software";
+    nextReason: WireRenderingReason;
+    restartPending: boolean;
+    gpu: {
+        available: boolean;
+        reason: WireRenderingReason | null;
+    };
 }
 /**
  * Template arguments on the wire (`osd.show`, `osd.panel`, `dialogs.confirm`,
@@ -525,6 +547,15 @@ export declare function createWire(transport: Transport): {
     app: {
         system: () => Promise<WireSystemInfo>;
     };
+    /**
+     * The rendering choice (player 0.5.13): `state` needs no capability,
+     * `setPreference` and `restart` need `rendering.manage`.
+     */
+    rendering: {
+        state: () => Promise<WireRenderingState>;
+        setPreference: (preference: string) => Promise<WireRenderingState>;
+        restart: () => Promise<null>;
+    };
     power: {
         preventSleep: (mode: "off" | "playing") => Promise<void>;
     };

package/dist/wire.js

@@ -214,6 +214,17 @@ export function createWire(transport) {
         app: {
             system: () => transport.request("app.system"),
         },
+        /**
+         * The rendering choice (player 0.5.13): `state` needs no capability,
+         * `setPreference` and `restart` need `rendering.manage`.
+         */
+        rendering: {
+            state: () => transport.request("rendering.state"),
+            setPreference: (preference) => transport.request("rendering.setPreference", {
+                preference,
+            }),
+            restart: () => transport.request("rendering.restart"),
+        },
         power: {
             preventSleep: (mode) => transport.request("power.preventSleep", { mode }),
         },