@vestra-player/sdk 1.6.8 → 1.6.10

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 1.6.10
+
+**Who must change: nobody.** Additions only: a clip format, optional export fields, two optional `JobState` fields, an error code and a `TestHost` field. `apiVersion` stays `vestra/1`, no new capability (`media.control` covers them). A plugin that does not use them sends exactly what it sent before; one that uses them needs player 0.7.6: declare `"minPlayerVersion": "0.7.6"`, or compare `plugin.app.version` with 0.7.6 to offer them only where they exist (do not probe by trying: on an older player `plugin` comes from that player's own, older SDK, which rejects `format: "copy"` with `invalid` but builds a re-encode request without the `encoding` it does not know, so the clip is encoded with the fixed settings and no error), and leave `progress`, `start` and `end` out.
+
+- **Stream-copied clips** (`Snapshot.export({ format: "copy", destination, end, container? })`, player 0.7.6): the video and the snapshot's audio track are copied as they are in the file, without re-encoding: lossless and about as fast as the disk. A copy can only begin on a keyframe: it starts at the video's last keyframe at or before the snapshot time (the first keyframe when the video itself starts later; keyframes an MP4 edit list discards do not count) and is cut at `end`, a few frames past it at most. `container` is `auto` (default: MP4 for H.264, HEVC, AV1 or MPEG-4 video with AAC, MP3, AC-3, E-AC-3 or ALAC audio, MKV for anything else), `mp4` or `mkv`; the player gives `destination` the container's extension and never overwrites a file. A copy needs a raw snapshot (`invalid` from a processed one), leaves subtitle tracks and chapters out, and keeps the snapshot lease, the job limits and cancellation of every export. One the player cannot make (no video stream, a cover image, an external audio track, codecs `mp4` cannot hold) ends `failed` with the new code **`unsupported`**. See `Snapshot.export`.
+- **The range written** (player 0.7.6): a finished clip's `outcome` has `start` and `end`, the source times of its first frame and of the end of its last frame: a copy's earliest written frame (its keyframe, or an open GOP's leading frames) and its actual end, a re-encode's start and start plus the encoded length.
+- **`JobState.progress`** (player 0.7.6): `{ done, total }`, seconds of the clip written and to write, from FFmpeg's progress output, at most 4 updates a second; `null` while unknown (before writing starts, and for frames). The player still checks the file after `done` reaches `total`.
+- **`ExportEncoding`** (`encoding` of `format: "mp4"`, player 0.7.6): `crf` (14–30), `speed` (`faster`, `balanced`, `smaller`), `maxHeight` (1080, 720, 480; a ceiling), `fps` (60, 30; a ceiling), `audioBitrate` (128, 192, 256 kb/s) `threads` (`single`, or `auto`: half the logical processors, at most 8) and `videoBitrate: "source"` (aim at the source video's average bitrate instead of a CRF, peaks up to 1.5 times it: a "Same as source" preset; not with `crf`; `unsupported` when the player cannot tell the source's bitrate). A closed set, never encoder arguments; the SDK and the player refuse other values with `invalid`. Without it, clips are encoded as before.
+- **Error codes**: `export-failed` (an export job's failure) and `unsupported` (a copy the player cannot make, a source bitrate it cannot tell) are listed in [Reference: errors](docs/reference/errors.md).
+- **`TestHost`**: `jobs.start` takes `rawCopy`, `encoding` and `container` and refuses what the player refuses, now also a job kind that does not match the snapshot (`rawPng` from a processed snapshot, say: `invalid`, as the player answers; plugins that go through `Snapshot.export` never send one); a running clip reports half its `progress`, and a finished one `start` and `end` (a copy 1 s before the snapshot time, as if snapped to a keyframe, its destination named for the container). **`TestHost.exportFailure`** makes running exports fail with a given code, for testing a plugin's `unsupported` path.
+- **Exports run at below-normal priority** (player 0.7.6): the player starts the FFmpeg that writes a frame or a clip below normal priority (Windows `BELOW_NORMAL_PRIORITY_CLASS`, `nice 10` elsewhere), so playback keeps its rate while an export uses the cores; probes stay at normal priority.
+
+## 1.6.9
+
+**Who must change: nobody.** Additions only: timeline ranges, OSD messages with action buttons, a limits constant, a wire method and `TestHost` support, and documentation of a bottom bar's `content-full-width`. `apiVersion` stays `vestra/1`, no new capability (`timeline.marks`, `playback.read` and `ui.osd` cover them). A plugin that does not use them sends exactly what it sent before; `onChange` of `plugin.timeline` still runs only when the marks change. One that uses them needs player 0.7.6 (`"minPlayerVersion": "0.7.6"`): the player builds `plugin` from its own SDK, so on older players `setRanges` and `ranges` do not exist (a `TypeError`), and `osd.show` there takes no options.
+
+- **Timeline ranges** (player 0.7.6): `TimelineLayer.setRanges(ranges, { ifCurrent? })` puts spans of the media on the seek bar, each `{ start, end, style, title? }` with `style` `"selection"` (a span the user picked to act on, such as a clip to export; drawn in the accent colour) or `"region"` (a part of the media the plugin describes; drawn dimmer). A layer's marks and ranges are replaced on their own (`set` keeps the ranges, `setRanges` keeps the marks); disposing the layer, its scope or stopping the plugin removes both, and a new source clears every layer. At most 100 ranges per layer, `0 ≤ start < end`, `end` within the media, titles ≤ 100 characters (`TIMELINE_LIMITS`, new, with the marks' 1000); failures go to `onError` as for marks. `plugin.timeline.ranges` (new, `playback.read`) is every layer's ranges merged by start, with `TimelineRange` (`start`, `end`, `style`, `title`, `plugin`); read it in a binding to follow it. Wire: `timeline.setRanges` (needs `timeline.marks`), and `ranges` beside `marks` in `timeline.marks` and `timeline.changed`.
+- **OSD messages with actions** (player 0.7.6): `plugin.osd.show(text, args?, { actions })` ends the message in up to two buttons (`OsdAction`: `title`, translated like the text, 1–40 characters; `command`, the local id of one of the plugin's own commands). The message stays about 4 seconds instead of 2 and does not fade while the pointer is on it and moving (it goes 2 seconds after the pointer leaves or rests, and at the latest 30 seconds after it showed); a click runs the command as if picked from a menu and removes the message. It stays one line, and nothing in it is created or removed while the pointer moves. A newer message replaces it with its buttons; the buttons go when the plugin stops, and while they show the plugin is not stopped for being idle. `osd.show` rejects with `invalid` for more than two actions, a bad title or a command the plugin has not declared. `OSD_LIMITS` gains `actions` (2) and `actionChars` (40). Older players ignore `actions`.
+- **`TestHost`**: `timeline.rangeLayers`, `timeline.ranges` and `setTimelineRanges(pluginId, ranges)` (another plugin's ranges); `timeline.setRanges` checked as the player does; `osdActions` (each message's buttons, in step with `osd`) and `pressOsdAction(index)`, which runs the command like a click.
+- **A bottom bar's `content-full-width`** (player 0.7.6, docs only): a bar that drops controls of its own also reports its row with every control shown in `content-full-width`, a public `length` property declared like `content-min-width`. The player then gives plugin buttons only the width beyond it, so every plugin button moves to » before the bar drops a control, and narrowing the window never brings a button back. A bar with only `content-min-width` keeps the earlier rule. [Writing a bottom bar](docs/guidelines/interface.md#writing-a-bottom-bar) and [Reference: theme](docs/reference/theme.md#bar-buttons) say so.
+
 ## 1.6.8
 
 **Who must change: nobody; authors of a bottom bar should move to `content-min-width`.** Documentation, a read-only Slint property and a removed CLI warning: no change to the TypeScript API, the wire or `TestHost`, `apiVersion` stays `vestra/1`, no new capability. A plugin's `button` declarations stay as they are. A bottom bar that still places `BarButtons` keeps working on player 0.7.6 (it shows that strip, and the player draws no second one); it is deprecated and goes in a later patch.
@@ -20,7 +41,7 @@
 - **`plugin.commands.keys(id)`** (player 0.7.6): the keys of one of the plugin's **own** commands, as the player's menus and command palette write them (`["W"]`, `["Ctrl+B"]`, `["⌘B"]` on macOS, arrows as `←`), always the current binding: the user's keys after a change, `[]` when the user cleared them or turned on Ignore Default Shortcuts, `[]` for a key another command holds; mouse bindings and (outside macOS) `Cmd` bindings left out. Read-only and synchronous; read in a `bind` function, the view follows every change. Another plugin's commands, or an unknown id, read `[]`; it needs `commands` only, not `bindings.manage`. The first read asks the player (`commands.keys`) and subscribes to the `commands.keys` event, which the player sends only to the plugin whose own labels changed, at most every 200 ms; until the first answer every command reads `[]`. See [Key hints beside controls](docs/explanation/commands.md#key-hints-beside-controls).
 - **`plugin.commands.onKeysChange(listener)`** (player 0.7.6): runs after any of the plugin's keys changed. `commands.keys` is a wake event, like `bindings.changed`: a listener (or a binding that reads `keys`) does not keep a plugin running while idle, and a plugin in standby is started for a change of its keys.
 - **`KeyHint`** in `@vestra/widgets.slint`: a key cap (monospace `font-xs`, `text-dim`, a 1px border, both palettes); an empty `text` draws nothing and takes no space.
-- **`ToolTipArea.keys`** (a list of the new struct `ToolTipKey`, `{ key, text }`) and **`ToolTipArea.detail`**: the tip reads "Brightness  [W] −  [E] +  · double-click: Default" with key caps. Without them the tip is the plain text tip as before.
+- **`ToolTipArea.keys`** (a list of the new struct `ToolTipKey`, `{ key, text }`) and **`ToolTipArea.detail`**: the tip reads "Brightness [W] − [E] + · double-click: Default" with key caps. Without them the tip is the plain text tip as before.
 - **`TestHost.rebind(command, inputs | null)`** changes or clears a key of the plugin's command as the user does; `TestHost` answers `commands.keys` and pushes the event like the player, writing labels for `host.systemInfo.os` (macOS by default: `⇧W`, `⌘B`). `bindings.set` and `bindings.reset` push it too.
 - The [theme-widgets example](examples/theme-widgets) shows a slider's two commands (F7, F8) as key caps and in its tooltip.
 

package/dist/api-requests.js

@@ -71,8 +71,12 @@ export const API_REQUESTS = Object.freeze({
     "Subtitles.remove": [{ method: "subtitles.remove" }, readsSubtitles],
     "Subtitles.setStyle": [{ method: "subtitles.style" }, readsSubtitles],
     "Timeline.marks": [{ method: "timeline.marks" }],
+    "Timeline.ranges": [{ method: "timeline.marks" }],
     "Timeline.onChange": [listen("timeline.changed")],
-    "Timeline.layer": [{ method: "timeline.set" }],
+    "Timeline.layer": [
+        { method: "timeline.set" },
+        { method: "timeline.setRanges" },
+    ],
     "MainWindow.onChange": [listen("window.state")],
     "MainWindow.setVideoArea": [{ method: "window.setVideoArea" }],
     "MainWindow.setAlwaysOnTop": [{ method: "window.setAlwaysOnTop" }],

package/dist/host-capabilities.js

@@ -300,7 +300,10 @@ export const HOST_CAPABILITIES = {
         },
         {
             label: "Show marks on the progress bar",
-            methods: [{ name: "timeline.set", needs: "timeline.marks" }],
+            methods: [
+                { name: "timeline.set", needs: "timeline.marks" },
+                { name: "timeline.setRanges", needs: "timeline.marks" },
+            ],
             name: "timeline.marks",
             requires: [],
             residency: "live",

package/dist/media.d.ts

@@ -160,9 +160,27 @@ export type MediaJob = {
                 duration: string;
             };
         };
+        /** A stream copy (player 0.7.6): what was copied and from where. */
+        copy?: {
+            container: "mp4" | "mkv";
+            videoCodec: string;
+            audioCodec: string | null;
+            /** The keyframe the copy starts on, source seconds. */
+            keyframe: number;
+            /** FFmpeg's input seek, the keyframe rounded down to a microsecond. */
+            seek: number;
+            written: {
+                start: number;
+                end: number;
+            };
+        };
     };
     outcome: null | {
         destination: string;
+        /** Clips (player 0.7.6): first frame, source seconds. */
+        start?: number;
+        /** Clips (player 0.7.6): end of the last frame, source seconds. */
+        end?: number;
     } | {
         error: {
             code: string;
@@ -171,6 +189,24 @@ export type MediaJob = {
     } | {
         cancelled: true;
     };
+    /**
+     * Player 0.7.6: seconds of a clip written and to write while FFmpeg runs;
+     * `null` (or absent from older players) while unknown.
+     */
+    progress?: {
+        done: number;
+        total: number;
+    } | null;
+};
+/** The wire form of `ExportEncoding` (`jobs.start`). */
+export type WireEncoding = {
+    crf?: number;
+    speed?: "faster" | "balanced" | "smaller";
+    maxHeight?: 1080 | 720 | 480;
+    fps?: 60 | 30;
+    audioBitrate?: 128 | 192 | 256;
+    threads?: "single" | "auto";
+    videoBitrate?: "source";
 };
 export type MediaOperation = {
     status: "pending" | "unknown" | "unknownExpired";
@@ -210,6 +246,13 @@ export declare function mediaClients(transport: Transport): {
         } | {
             kind: "rawMp4" | "processedMp4";
             end: number;
+            /** Player 0.7.6. */
+            encoding?: WireEncoding;
+        } | {
+            /** Stream copy, player 0.7.6. */
+            kind: "rawCopy";
+            end: number;
+            container?: "auto" | "mp4" | "mkv";
         })) => Promise<{
             jobId: number;
             status: "queued";

package/dist/player-runtime.d.ts

@@ -16,6 +16,7 @@ export { HOST_CAPABILITIES } from "./host-capabilities.ts";
 export { BAR_BUTTON_ICONS, BAR_BUTTON_LIMITS, BUILTIN_COMMANDS, BUILTIN_SUBMENUS, COMMAND_LIMITS, MENU_IDS, } from "./commands.ts";
 export { BINDING_INPUTS } from "./plugin/bindings.ts";
 export { OSD_LIMITS } from "./plugin/osd.ts";
+export { TIMELINE_LIMITS } from "./plugin/timeline.ts";
 export { SECRET_LIMITS, SESSION_STORAGE_LIMITS } from "./plugin/services.ts";
 export { SUBTITLE_LIMITS } from "./plugin/subtitles.ts";
 export { VIDEO_PROCESSING_LIMITS } from "./processing.ts";

package/dist/player-runtime.js

@@ -14,6 +14,7 @@ export { HOST_CAPABILITIES } from "./host-capabilities.js";
 export { BAR_BUTTON_ICONS, BAR_BUTTON_LIMITS, BUILTIN_COMMANDS, BUILTIN_SUBMENUS, COMMAND_LIMITS, MENU_IDS, } from "./commands.js";
 export { BINDING_INPUTS } from "./plugin/bindings.js";
 export { OSD_LIMITS } from "./plugin/osd.js";
+export { TIMELINE_LIMITS } from "./plugin/timeline.js";
 export { SECRET_LIMITS, SESSION_STORAGE_LIMITS } from "./plugin/services.js";
 export { SUBTITLE_LIMITS } from "./plugin/subtitles.js";
 export { VIDEO_PROCESSING_LIMITS } from "./processing.js";

package/dist/plugin/media.js

@@ -1,6 +1,31 @@
 import { failure, sleep, uncertain } from "./runtime.js";
 import { playerOf } from "./player.js";
 const TERMINAL = ["completed", "failed", "cancelled"];
+/** The player's sets for each {@link ExportEncoding} field. */
+const ENCODING = {
+    crf: Array.from({ length: 17 }, (_, i) => i + 14),
+    speed: ["faster", "balanced", "smaller"],
+    maxHeight: [1080, 720, 480],
+    fps: [60, 30],
+    audioBitrate: [128, 192, 256],
+    threads: ["single", "auto"],
+    videoBitrate: ["source"],
+};
+/** Refuse what the player would refuse, with the field named. */
+function checkEncoding(encoding) {
+    if (typeof encoding !== "object" || encoding === null)
+        throw failure("invalid", "encoding must be an object");
+    for (const [key, value] of Object.entries(encoding)) {
+        const allowed = ENCODING[key];
+        if (!allowed)
+            throw failure("invalid", `unknown encoding option ${key}`);
+        if (value !== undefined && !allowed.includes(value))
+            throw failure("invalid", `encoding.${key} must be one of ${allowed.join(", ")}`);
+    }
+    if (encoding.crf !== undefined && encoding.videoBitrate !== undefined)
+        throw failure("invalid", "encoding takes crf or videoBitrate, not both");
+    return Object.fromEntries(Object.entries(encoding).filter(([, value]) => value !== undefined));
+}
 /** One counter for snapshot and job operations, as the host's book expects. */
 class MediaService {
     runtime;
@@ -159,8 +184,28 @@ class SnapshotHandle {
         let job;
         switch (options.format) {
             case "mp4":
-                job = { kind: `${mode}Mp4`, end: options.end };
+                job = {
+                    kind: `${mode}Mp4`,
+                    end: options.end,
+                    ...(options.encoding === undefined
+                        ? {}
+                        : { encoding: checkEncoding(options.encoding) }),
+                };
                 break;
+            case "copy": {
+                if (processed)
+                    throw failure("invalid", "a stream copy needs a raw snapshot: effects need a re-encode");
+                const container = options.container;
+                if (container !== undefined &&
+                    !["auto", "mp4", "mkv"].includes(container))
+                    throw failure("invalid", "container must be auto, mp4 or mkv");
+                job = {
+                    kind: "rawCopy",
+                    end: options.end,
+                    ...(container === undefined ? {} : { container }),
+                };
+                break;
+            }
             case "jpeg": {
                 const quality = options.quality;
                 if (quality !== undefined &&

package/dist/plugin/osd.d.ts

@@ -46,6 +46,10 @@ export declare const OSD_LIMITS: Readonly<{
     readonly minColumns: 8;
     /** The largest `OsdPanelOptions.maxColumns` (1000). */
     readonly maxColumns: 1000;
+    /** Action buttons of one `osd.show` message (`OsdShowOptions.actions`; player 0.7.6) (2). */
+    readonly actions: 2;
+    /** Characters of an action's title, as shown (40; at least 1 that is not white space). */
+    readonly actionChars: 40;
 }>;
 /**
  * Copy and check template arguments: an array or object of at most 16

package/dist/plugin/osd.js

@@ -47,7 +47,32 @@ export const OSD_LIMITS = Object.freeze({
     minColumns: 8,
     /** The largest `OsdPanelOptions.maxColumns` (1000). */
     maxColumns: 1000,
+    /** Action buttons of one `osd.show` message (`OsdShowOptions.actions`; player 0.7.6) (2). */
+    actions: 2,
+    /** Characters of an action's title, as shown (40; at least 1 that is not white space). */
+    actionChars: 40,
 });
+/** Copy and check `OsdShowOptions.actions`: what the SDK can check before the player does. */
+function osdActions(options) {
+    if (options === undefined || options === null)
+        return undefined;
+    if (typeof options !== "object")
+        throw failure("invalid", "options is an object");
+    const actions = options.actions;
+    if (actions === undefined)
+        return undefined;
+    if (!Array.isArray(actions) || actions.length > OSD_LIMITS.actions)
+        throw failure("invalid", `actions is a list of at most ${OSD_LIMITS.actions}`);
+    return actions.map((action, i) => {
+        const { title, command } = (action ?? {});
+        if (typeof command !== "string" || command === "")
+            throw failure("invalid", `actions[${i}].command is a command id`);
+        return {
+            title: shownText(title, undefined, `actions[${i}].title`),
+            command,
+        };
+    });
+}
 /**
  * Copy and check template arguments: an array or object of at most 16
  * strings, finite numbers, texts and lists (`TEXT_LIMITS`).
@@ -134,6 +159,6 @@ class PanelHandle {
     }
 }
 export const osd = (scope) => ({
-    show: async (text, args) => scope.runtime.host.osd.show(shownText(text, args), templateArgs(args)),
+    show: async (text, args, options) => scope.runtime.host.osd.show(shownText(text, args), templateArgs(args), osdActions(options)),
     panel: () => new PanelHandle(scope),
 });

package/dist/plugin/testing.d.ts

@@ -7,6 +7,7 @@ import type { BuiltinCommand, BuiltinSubmenu } from "../commands.ts";
 import { CAPABILITY_INFO, MESSAGE_LIMIT } from "../capabilities.ts";
 import type { CapabilityInfo } from "../capabilities.ts";
 import { OSD_LIMITS } from "./osd.ts";
+import { TIMELINE_LIMITS } from "./timeline.ts";
 import { SECRET_LIMITS, SESSION_STORAGE_LIMITS } from "./services.ts";
 import { SUBTITLE_LIMITS } from "./subtitles.ts";
 import { BINDING_INPUTS } from "./bindings.ts";
@@ -36,6 +37,8 @@ export type { CapabilityInfo };
 export { MESSAGE_LIMIT };
 /** The player's limits on the on-screen display. */
 export { OSD_LIMITS };
+/** The player's limits on a timeline layer. */
+export { TIMELINE_LIMITS };
 /** The player's limits on stored secrets. */
 export { SECRET_LIMITS };
 /** The player's limits on `plugin.storage.session`. */
@@ -647,6 +650,43 @@ export declare class TestHost implements Transport {
      * template and args the plugin sent are in `host.sent("osd.show")`.
      */
     readonly osd: string[];
+    /**
+     * The action buttons of each `osd.show` message, in step with `osd`
+     * (index for index): each button's title as shown and its command; `[]`
+     * for a message without actions (SDK 1.6.9).
+     */
+    readonly osdActions: {
+        /** The button title as shown, in the plugin's locale. */
+        title: string;
+        /** The local id of the plugin's command the button runs. */
+        command: string;
+    }[][];
+    /**
+     * Press button `index` of the newest OSD message, as the user does
+     * (player 0.7.6): its command runs as if picked from a menu, and settles.
+     * A disabled or busy command does nothing, as in the player.
+     *
+     * @param index - 0 or 1.
+     *
+     * @throws `Error` (rejects) The newest message has no button `index`.
+     *
+     * @example Press "Show in Folder" on the saved message
+     * The test checks the button the plugin put on its newest message, then
+     * presses it as the user would: the plugin's `reveal` command runs.
+     * ```ts
+     * import assert from "node:assert/strict";
+     * declare const host: TestHost;
+     * // ---cut---
+     * assert.deepEqual(host.osdActions.at(-1), [
+     *   { title: "Show in Folder", command: "reveal" },
+     * ]);
+     * await host.pressOsdAction(0); // runs the plugin's `reveal` command
+     * ```
+     *
+     * @capability None.
+     * @since 1.6.9
+     */
+    pressOsdAction(index: number): Promise<void>;
     /** The text of this plugin's osd panel as shown, `null` when hidden. */
     osdPanel: string | null;
     /**
@@ -948,7 +988,65 @@ export declare class TestHost implements Transport {
             /** The mark's title, `null` without one. */
             title: string | null;
         }[];
+        /**
+         * Each plugin's ranges by plugin id; layers without ranges are absent
+         * (SDK 1.6.9).
+         */
+        rangeLayers: Map<string, {
+            /** Seconds from the start. */
+            start: number;
+            /** Seconds from the start, after `start`. */
+            end: number;
+            /** `"selection"` or `"region"`. */
+            style: string;
+            /** The range's title, `null` without one. */
+            title: string | null;
+        }[]>;
+        /** Every layer's ranges merged, sorted by start, with the plugin's id. */
+        readonly ranges: {
+            /** The manifest id of the plugin that published the range. */
+            plugin: string;
+            /** Seconds from the start. */
+            start: number;
+            /** Seconds from the start, after `start`. */
+            end: number;
+            /** `"selection"` or `"region"`. */
+            style: string;
+            /** The range's title, `null` without one. */
+            title: string | null;
+        }[];
     };
+    /**
+     * Simulate another plugin publishing its timeline ranges (or clearing
+     * them with `[]`); pushes `timeline.changed` when the plugin subscribed.
+     *
+     * @param pluginId - The other plugin's manifest id.
+     * @param ranges - All its ranges.
+     *
+     * @example Let another plugin publish a clip range
+     * The plugin under test sees a range another plugin put on the seek bar:
+     * `setTimelineRanges` stores that plugin's ranges and pushes
+     * `timeline.changed`, and `settle()` lets it arrive.
+     * ```ts
+     * import assert from "node:assert/strict";
+     * declare const host: TestHost;
+     * // ---cut---
+     * host.setTimelineRanges("community.clips", [
+     *   { start: 40, end: 52.5, style: "selection", title: "Clip" },
+     * ]);
+     * await host.settle();
+     * assert.equal(plugin.timeline.ranges[0]?.plugin, "community.clips");
+     * ```
+     *
+     * @capability None.
+     * @since 1.6.9
+     */
+    setTimelineRanges(pluginId: string, ranges: {
+        start: number;
+        end: number;
+        style: string;
+        title?: string | null;
+    }[]): void;
     /**
      * Simulate another plugin publishing its timeline layer (or clearing it
      * with `[]`); pushes `timeline.changed` when the plugin subscribed.
@@ -1556,9 +1654,27 @@ export declare class TestHost implements Transport {
     /**
      * Export jobs by job id. Each state query advances a job one step
      * (`queued` → `running` → `completed`; `cancelling` → `cancelled`).
-     * Wire-level.
+     * A running clip reports half its `progress`; a finished clip's
+     * `outcome` has `start` and `end` (a stream copy starts 1 s before the
+     * snapshot time, as if snapped to a keyframe, and its destination gets
+     * the extension of its container: `.mkv` for `container: "mkv"`, else
+     * `.mp4`). Wire-level.
      */
     readonly jobs: Map<number, MediaJob>;
+    /**
+     * Set it to make every running export end `failed` with this error on
+     * its next state query, as the player reports one (`unsupported` for a
+     * stream copy it cannot make, `export-failed` otherwise); `null` (the
+     * default) completes them.
+     *
+     * @since 1.6.10
+     */
+    exportFailure: {
+        /** The `outcome.error.code`. */
+        code: string;
+        /** The `outcome.error.message`. */
+        message: string;
+    } | null;
     /**
      * `openStream`'s transport: a local stream (a Unix socket on macOS and
      * Linux, a named pipe on Windows) or, with `"tcp"`, loopback TCP where the