@vestra-player/sdk 1.5.41 → 1.5.43

package/dist/plugin/types.d.ts

@@ -520,7 +520,7 @@ export interface Scope extends Disposable {
  * `dataDirectory`.
  *
  * @capability That of each module (see the modules).
- * @see [How a plugin runs](../../docs/concepts/plugins.md)
+ * @see [How a plugin runs](../../docs/explanation/plugins.md)
  * @since 1.0.0
  * @category Plugin
  */
@@ -540,7 +540,7 @@ export interface Plugin extends Scope {
      * {@link PluginInfo.dataDirectory}). Write files atomically (to a
      * temporary name, then rename); for JSON settings prefer
      * {@link Scope.storage}. Throws `unavailable` when the player provided
-     * none. See [How a plugin runs](../../docs/concepts/plugins.md#the-data-directory).
+     * none. See [How a plugin runs](../../docs/explanation/plugins.md#the-data-directory).
      */
     readonly dataDirectory: string;
 }
@@ -918,7 +918,7 @@ export interface CommandButton {
  * order, group or binding. The same path registered twice, or a path that
  * is both an item and a submenu, fails with `conflict` (through `ready`).
  *
- * @see {@link Commands.add}, [Commands, menus and key bindings](../../docs/concepts/commands.md)
+ * @see {@link Commands.add}, [Commands, menus and key bindings](../../docs/explanation/commands.md)
  * @since 1.0.0
  * @category Commands
  */
@@ -1085,7 +1085,7 @@ export interface CommandOptions {
  * exportCommand.set({ enabled: () => plugin.player.state.phase === "ready" });
  * ```
  *
- * @see {@link Commands.add}, [Commands, menus and key bindings](../../docs/concepts/commands.md)
+ * @see {@link Commands.add}, [Commands, menus and key bindings](../../docs/explanation/commands.md)
  * @since 1.0.0
  * @category Commands
  */
@@ -1171,7 +1171,7 @@ export interface Command extends Disposable {
  * });
  * ```
  *
- * @see {@link Command}, {@link CommandOptions}, [Commands, menus and key bindings](../../docs/concepts/commands.md)
+ * @see {@link Command}, {@link CommandOptions}, [Commands, menus and key bindings](../../docs/explanation/commands.md)
  * @since 1.0.0
  * @category Commands
  */
@@ -1261,7 +1261,7 @@ export interface Commands {
  * }));
  * ```
  *
- * @see {@link Ui.image}, [Windows, panels, settings pages, dialogs and the OSD](../../docs/concepts/ui.md)
+ * @see {@link Ui.image}, [Windows, panels, settings pages, dialogs and the OSD](../../docs/explanation/ui.md)
  * @since 1.0.0
  * @category UI
  */
@@ -1471,7 +1471,7 @@ export type Props = Record<string, PropValue>;
  *
  * {@includeCode ../../examples/markdown/ui/document.slint}
  *
- * @see {@link ImageRef}, {@link MarkdownRef}, [Windows, panels, settings pages, dialogs and the OSD](../../docs/concepts/ui.md)
+ * @see {@link ImageRef}, {@link MarkdownRef}, [Windows, panels, settings pages, dialogs and the OSD](../../docs/explanation/ui.md)
  * @since 1.0.0
  * @category UI
  */
@@ -1736,7 +1736,7 @@ export interface Ui {
  *
  * {@includeCode ../../examples/bookmark/ui/bookmark.slint}
  *
- * @see {@link Window}, {@link Panel}, {@link SettingsPage}, [Windows, panels, settings pages, dialogs and the OSD](../../docs/concepts/ui.md), [Keep a slider responsive while dragging](../../docs/how-to/slider.md)
+ * @see {@link Window}, {@link Panel}, {@link SettingsPage}, [Windows, panels, settings pages, dialogs and the OSD](../../docs/explanation/ui.md), [Keep a slider responsive while dragging](../../docs/how-to/slider.md)
  * @since 1.0.0
  * @category UI
  */
@@ -1947,7 +1947,7 @@ export interface View {
  * });
  * ```
  *
- * @see {@link Windows.create}, {@link View}, [Windows, panels, settings pages, dialogs and the OSD](../../docs/concepts/ui.md), [Remember a window's state between runs](../../docs/how-to/window-state.md)
+ * @see {@link Windows.create}, {@link View}, [Windows, panels, settings pages, dialogs and the OSD](../../docs/explanation/ui.md), [Remember a window's state between runs](../../docs/how-to/window-state.md)
  * @since 1.0.0
  * @category UI
  */
@@ -2129,7 +2129,7 @@ export interface Window extends View, Disposable {
  *
  * {@includeCode ../../examples/bookmark/main.ts#window,command}
  *
- * @see {@link Window}, [Windows, panels, settings pages, dialogs and the OSD](../../docs/concepts/ui.md)
+ * @see {@link Window}, [Windows, panels, settings pages, dialogs and the OSD](../../docs/explanation/ui.md)
  * @since 1.0.0
  * @category UI
  */
@@ -2534,7 +2534,7 @@ export interface SidebarSlot extends PanelSlot {
  *
  * {@includeCode ../../examples/panel-menu/ui/panel.slint}
  *
- * @see {@link Panels.mount}, {@link PanelSlot}, [Windows, panels, settings pages, dialogs and the OSD](../../docs/concepts/ui.md)
+ * @see {@link Panels.mount}, {@link PanelSlot}, [Windows, panels, settings pages, dialogs and the OSD](../../docs/explanation/ui.md)
  * @since 1.0.0
  * @category UI
  */
@@ -2972,7 +2972,7 @@ export type ThemeId = "vestra" | "vestra-light";
  * });
  * ```
  *
- * @see [Windows, panels, settings pages, dialogs and the OSD](../../docs/concepts/ui.md) (theme tokens)
+ * @see [Windows, panels, settings pages, dialogs and the OSD](../../docs/explanation/ui.md) (theme tokens)
  * @since 1.0.0
  * @category UI
  */
@@ -3493,7 +3493,7 @@ export type SettingsCategory = "general" | "playback" | "subtitles" | "video" |
  * }
  * ```
  *
- * @see {@link Settings.page}, [Windows, panels, settings pages, dialogs and the OSD](../../docs/concepts/ui.md)
+ * @see {@link Settings.page}, [Windows, panels, settings pages, dialogs and the OSD](../../docs/explanation/ui.md)
  * @since 1.0.0
  * @category UI
  */
@@ -3554,7 +3554,7 @@ export type SettingsPage = View & Disposable & {
  * page.on("resumeToggled", (on: boolean) => store.save({ ...store.value, resume: on }));
  * ```
  *
- * @see {@link SettingsPage}, [Windows, panels, settings pages, dialogs and the OSD](../../docs/concepts/ui.md)
+ * @see {@link SettingsPage}, [Windows, panels, settings pages, dialogs and the OSD](../../docs/explanation/ui.md)
  * @since 1.0.0
  * @category UI
  */
@@ -3746,7 +3746,7 @@ export interface BackdropSlot {
  *
  * {@includeCode ../../examples/panel-menu/ui/panel.slint}
  *
- * @see {@link Panel}, {@link PanelSlot}, [Windows, panels, settings pages, dialogs and the OSD](../../docs/concepts/ui.md)
+ * @see {@link Panel}, {@link PanelSlot}, [Windows, panels, settings pages, dialogs and the OSD](../../docs/explanation/ui.md)
  * @since 1.0.0
  * @category UI
  */
@@ -4469,7 +4469,7 @@ export interface ConfirmOptions {
  * }
  * ```
  *
- * @see [Windows, panels, settings pages, dialogs and the OSD](../../docs/concepts/ui.md)
+ * @see [Windows, panels, settings pages, dialogs and the OSD](../../docs/explanation/ui.md)
  * @since 1.0.0
  * @category UI
  */
@@ -4683,7 +4683,7 @@ export interface AudioTrack {
  * Without `events`, {@link Player.state} only updates at start and after
  * this plugin's own operations.
  *
- * @see {@link Player.state}, [Playback state, controls and sources](../../docs/concepts/playback.md)
+ * @see {@link Player.state}, [Playback state, controls and sources](../../docs/explanation/playback.md)
  * @since 1.0.0
  * @category Playback
  */
@@ -4816,7 +4816,7 @@ export interface Chapter {
  * });
  * ```
  *
- * @see [Playback state, controls and sources](../../docs/concepts/playback.md)
+ * @see [Playback state, controls and sources](../../docs/explanation/playback.md)
  * @since 1.0.0
  * @category Playback
  */
@@ -5335,7 +5335,7 @@ export interface PlaybackStats {
  * `events` to follow changes made elsewhere; `producer.av` for
  * {@link Player.openStream}.
  *
- * @see [Playback state, controls and sources](../../docs/concepts/playback.md), [Control playback](../../docs/how-to/control-playback.md)
+ * @see [Playback state, controls and sources](../../docs/explanation/playback.md), [Control playback](../../docs/how-to/control-playback.md)
  * @since 1.0.0
  * @category Playback
  */
@@ -6298,7 +6298,7 @@ export interface OsdPanelOptions {
  * say("Blur on");
  * ```
  *
- * @see {@link OsdPanel}, [Windows, panels, settings pages, dialogs and the OSD](../../docs/concepts/ui.md)
+ * @see {@link OsdPanel}, [Windows, panels, settings pages, dialogs and the OSD](../../docs/explanation/ui.md)
  * @since 1.0.0
  * @category UI
  */
@@ -6463,7 +6463,7 @@ interface Filter<T> extends Disposable {
  * never throws: a refused chain shows as `failed` in `status`.
  *
  * @capability processing.video, playback.read and events
- * @see [Video and audio processing](../../docs/concepts/processing.md)
+ * @see [Video and audio processing](../../docs/explanation/processing.md)
  * @since 1.0.0
  * @category Processing
  */
@@ -6492,7 +6492,7 @@ export type VideoFilter = Filter<VideoNode[]>;
  * result, `retry` applies it again, `dispose` withdraws it.
  *
  * @capability processing.audio, playback.read and events
- * @see [Video and audio processing](../../docs/concepts/processing.md)
+ * @see [Video and audio processing](../../docs/explanation/processing.md)
  * @since 1.0.0
  * @category Processing
  */
@@ -6551,7 +6551,7 @@ export interface ViewSettings {
  *
  * @capability processing.video, playback.read and events (like
  * {@link VideoFilter})
- * @see [Video and audio processing](../../docs/concepts/processing.md)
+ * @see [Video and audio processing](../../docs/explanation/processing.md)
  * @since 1.0.0
  * @category Processing
  */
@@ -6662,7 +6662,7 @@ export interface RenderSettings {
  *
  * @capability processing.video, playback.read and events (like
  * {@link VideoFilter})
- * @see [Video and audio processing](../../docs/concepts/processing.md)
+ * @see [Video and audio processing](../../docs/explanation/processing.md)
  * @since 1.0.0
  * @category Processing
  */
@@ -6766,7 +6766,7 @@ export interface RenderOptions extends Disposable {
  *
  * @capability processing.video
  * @player 0.5.20; older players refuse the request.
- * @see [Video and audio processing](../../docs/concepts/processing.md)
+ * @see [Video and audio processing](../../docs/explanation/processing.md)
  * @since 1.5.39
  * @category Processing
  */
@@ -6870,7 +6870,7 @@ export interface VideoShaders extends Disposable {
  * | `gpu-unsupported` | The driver does not offer upscaling on this GPU (Windows: not an RTX GPU), or the check failed. |
  * | `rendering` | The player renders in software, or GPU rendering is still starting; upscaling needs GPU rendering ({@link Rendering}). |
  * | `adapter` | GPU rendering runs on another GPU than the one that can upscale (a laptop with two GPUs; Windows: choose the high-performance GPU for Vestra in Settings ▸ System ▸ Display ▸ Graphics). |
- * | `decoding` | The video is not decoded on the GPU that renders it: copy-back or software decoding, for example while a {@link VideoFilter} needs the frames in memory. |
+ * | `decoding` | The video is not decoded on the GPU that renders it: copy-back or software decoding, for example while a {@link VideoFilter} needs the frames in memory. {@link UpscalingReason.cause} says which, and {@link UpscalingReason.plugins} whose filters (newer players; see there). |
  * | `unchecked` | The player has not checked the GPU yet. Only in the answer to `set(false)`, which never starts the check; `state()` and `set(true)` always check first. |
  *
  * `decoding` and `rendering` while GPU rendering is still starting can pass
@@ -6925,6 +6925,93 @@ export interface UpscalingReason {
      * and what to change; never branch on it.
      */
     readonly message: string;
+    /**
+     * With code `decoding` only: why the video is not decoded on the GPU
+     * that renders it ({@link UpscalingDecodingCause}). Absent with every
+     * other code, and from players before 0.5.25.
+     *
+     * @player 0.5.25; older players send `decoding` without a cause.
+     * @since 1.5.43
+     */
+    readonly cause?: UpscalingDecodingCause;
+    /**
+     * With cause `copy-back` only: the plugins whose video filters need the
+     * frames in memory, which is why the player switched to copy-back
+     * decoding, in the order the plugins started (each plugin once). Name
+     * them to the user, who can turn the filters off there. Empty when
+     * the copy-back decoding is not one the player chose for a filter (the
+     * user's own `hwdec` setting). Absent with any other cause, and from
+     * players before 0.5.25.
+     *
+     * @player 0.5.25
+     * @since 1.5.43
+     */
+    readonly plugins?: readonly UpscalingPlugin[];
+}
+/**
+ * Why the video is not decoded on the GPU that renders it: the
+ * {@link UpscalingReason.cause} of a `decoding` reason (player 0.5.25). A
+ * newer player may add causes: show {@link UpscalingReason.message} for the
+ * ones you do not handle.
+ *
+ * | Cause | Meaning |
+ * | --- | --- |
+ * | `copy-back` | Decoded on the GPU and copied back to memory, because a plugin's video filter needs the frames there ({@link UpscalingReason.plugins} names it), or because of the user's `hwdec` setting. |
+ * | `hwdec-off` | Hardware decoding is turned off (mpv's `hwdec` is `no`). |
+ * | `software` | This video is decoded in software: a cover picture, a format the GPU does not decode, or a hardware decoder that failed. It passes with the next video. |
+ * | `other-hwdec` | This video is decoded with another hardware decoder than the one the upscaler needs. |
+ *
+ * @example Name the plugins whose filters block upscaling
+ * A plugin's upscaling window explains a `decoding` reason by its cause,
+ * and for `copy-back` names the plugins whose filters stand in the way, so
+ * the user can turn them off there (a plugin cannot run another plugin's
+ * commands).
+ * ```ts
+ * const { reason } = await plugin.video.upscaling.state();
+ * if (reason?.code === "decoding" && reason.cause === "copy-back") {
+ *   const names = (reason.plugins ?? []).map((p) => p.name).join(", ");
+ *   // Ask the user to reset those filters; the manifest names are not translated.
+ *   console.log(names ? `Turn off the video filters of ${names}` : reason.message);
+ * } else if (reason) console.log(reason.message);
+ * ```
+ *
+ * @player 0.5.25
+ * @since 1.5.43
+ * @category Processing
+ */
+export type UpscalingDecodingCause = "copy-back" | "hwdec-off" | "software" | "other-hwdec" | (string & {});
+/**
+ * A plugin named in an {@link UpscalingReason}: its manifest id and its
+ * name for people, as its manifest gives it (not translated).
+ *
+ * @player 0.5.25
+ * @since 1.5.43
+ * @category Processing
+ */
+export interface UpscalingPlugin {
+    /** The plugin's manifest id, for example `vestra.video`. */
+    readonly id: string;
+    /** The manifest's `name` as is (its id without one), for people. */
+    readonly name: string;
+}
+/**
+ * The video's size as the upscaler gets it ({@link UpscalingState.video}):
+ * the decoder's frame size, width and height swapped for the file's
+ * quarter-turn rotation metadata.
+ *
+ * @player 0.5.25
+ * @since 1.5.43
+ * @category Processing
+ */
+export interface UpscalingVideoSize {
+    /** The frames' stored width in pixels. */
+    readonly width: number;
+    /** The frames' stored height in pixels. */
+    readonly height: number;
+    /** The width the video is meant to be shown at (non-square pixels). */
+    readonly displayWidth: number;
+    /** The height the video is meant to be shown at. */
+    readonly displayHeight: number;
 }
 /**
  * What {@link VideoUpscaling.state} and {@link VideoUpscaling.set} report:
@@ -6980,6 +7067,59 @@ export interface UpscalingState {
      * nothing is requested.
      */
     readonly factor: number | null;
+    /**
+     * The video's size as the upscaler gets it; `null` while no video
+     * decodes. With {@link UpscalingState.area} it explains the factor.
+     * Absent from players before 0.5.25.
+     *
+     * @player 0.5.25
+     * @since 1.5.43
+     */
+    readonly video?: UpscalingVideoSize | null;
+    /**
+     * The area the video is shown in, in pixels (the upscaler scales the
+     * video to fit it); `null` while the player shows no video area. Absent
+     * from players before 0.5.25.
+     *
+     * @player 0.5.25
+     * @since 1.5.43
+     */
+    readonly area?: {
+        /** Width in physical pixels. */
+        readonly width: number;
+        /** Height in physical pixels. */
+        readonly height: number;
+    } | null;
+    /**
+     * The name of the GPU that renders, for example `NVIDIA GeForce RTX 4070
+     * Laptop GPU`; `null` in software rendering and where the player does not
+     * know it (macOS, Linux). Absent from players before 0.5.25.
+     *
+     * @player 0.5.25
+     * @since 1.5.43
+     */
+    readonly gpu?: string | null;
+    /**
+     * The hardware decoder in use for this video, as mpv names it (`d3d11va`,
+     * `d3d11va-copy`; `no` for software decoding); `null` while no video
+     * decodes. For people and logs: branch on {@link UpscalingReason.cause}.
+     * Absent from players before 0.5.25.
+     *
+     * @player 0.5.25
+     * @since 1.5.43
+     */
+    readonly hwdecCurrent?: string | null;
+    /**
+     * The upscaler is in the player's video filter chain now, read from the
+     * chain itself (`requested` is what the player asked for; they differ
+     * only for a moment, while the chain changes). Still not a sign that the
+     * GPU upscales: the driver gives none (see the remarks). Absent from
+     * players before 0.5.25.
+     *
+     * @player 0.5.25
+     * @since 1.5.43
+     */
+    readonly inChain?: boolean;
 }
 /**
  * `plugin.video.upscaling`: the GPU's video upscaler, NVIDIA RTX Video
@@ -7119,6 +7259,57 @@ export interface VideoUpscaling {
      * @since 1.5.37
      */
     set(enabled: boolean): Promise<UpscalingState>;
+    /**
+     * Call `listener` with the new state whenever it changes while some
+     * plugin has upscaling on: the factor, whether the upscaler is in the
+     * chain, the reason, the video's and the area's size, the decoder. A
+     * window that shows how upscaling runs listens instead of polling
+     * {@link VideoUpscaling.state}.
+     *
+     * @remarks
+     * The player looks about five times a second while upscaling is on for
+     * any plugin (a window resize sends at most that many), and sends a
+     * change only when something differs; after the last plugin turns it
+     * off one more change says so, then nothing until it is on again: read
+     * {@link VideoUpscaling.state} when you need the state then. Nothing is
+     * sent before the player's GPU check ran (the first `state()` or
+     * `set(true)` of any plugin). `enabled` is this plugin's own request, as
+     * in `state()`. The message of a `rendering` reason can be shorter than
+     * the one `state()` gives (it may leave out what to do).
+     *
+     * **A listener keeps the plugin running.** `video.upscaling.changed` is
+     * not an event the player wakes a stopped plugin for: while the plugin
+     * listens, the player does not stop it while idle (lazy activation), even
+     * with upscaling off. Listen only while a window that shows the state is
+     * open, and dispose of the listener when it closes. Players before 0.5.25 do not know the event: the listener
+     * never fires and the SDK logs that the player refused the subscription.
+     *
+     * @capability video.upscaling
+     * @param listener - Receives the new state.
+     * @returns Stops listening; also when the scope that added it is
+     *   disposed.
+     * @throws `capability` (synchronously) The manifest does not declare
+     *   `video.upscaling`.
+     *
+     * @example Show how upscaling runs while a window is open
+     * The plugin's window shows the factor, the sizes and the GPU while it
+     * is open; the listener goes when the window closes, so the plugin can
+     * be stopped while idle again.
+     * ```ts
+     * // When the window opens:
+     * const watch = plugin.video.upscaling.onChange((state) => {
+     *   const video = state.video ? `${state.video.width}×${state.video.height}` : "no video";
+     *   const area = state.area ? `${state.area.width}×${state.area.height}` : "—";
+     *   console.log(`${video} → ${area}, ×${state.factor ?? 1}, ${state.gpu ?? "no GPU"}`);
+     * });
+     * // When it closes: stop listening (it keeps the plugin running).
+     * await watch.dispose();
+     * ```
+     *
+     * @player 0.5.25
+     * @since 1.5.43
+     */
+    onChange(listener: (state: UpscalingState) => void): Disposable;
 }
 /**
  * A subtitle track of the current source.
@@ -7977,7 +8168,7 @@ export interface Resolver extends Disposable {
  * another plugin), so the plugin does not intercept opens itself.
  *
  * @capability source.resolve (file resolvers also `producer.av`)
- * @see [Playback state, controls and sources](../../docs/concepts/playback.md)
+ * @see [Playback state, controls and sources](../../docs/explanation/playback.md)
  * @since 1.0.0
  * @category Sources
  */
@@ -8751,7 +8942,7 @@ export interface BindingInfo extends BindingRef {
  * applies the change at once to every running plugin.
  *
  * @capability bindings.manage
- * @see [Commands, menus and key bindings](../../docs/concepts/commands.md)
+ * @see [Commands, menus and key bindings](../../docs/explanation/commands.md)
  * @since 1.0.0
  * @category Commands
  */

package/dist/wire.d.ts

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