@vestra-player/sdk 1.6.9 → 1.6.10

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # 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.
@@ -29,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/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/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/testing.d.ts

@@ -1654,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

package/dist/plugin/testing.js

@@ -167,6 +167,24 @@ export { LIST_SEPARATORS };
  * ```
  */
 export { LOCALES };
+/** `jobs.start`'s `encoding`, checked against the player's sets. */
+function validEncoding(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const sets = {
+        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"],
+    };
+    const fields = value;
+    if (fields.crf !== undefined && fields.videoBitrate !== undefined)
+        return false;
+    return Object.entries(value).every(([key, v]) => sets[key]?.includes(v) ?? false);
+}
 /** A `plugin.storage.session` key, checked as the player does. */
 function sessionKey(key) {
     if (typeof key !== "string" ||
@@ -1809,9 +1827,24 @@ export class TestHost {
     /**
      * 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.
      */
     jobs = new Map();
+    /**
+     * 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 = null;
+    /** What each job was asked to write, for its outcome. */
+    #exportJobs = new Map();
     /**
      * `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
@@ -5637,8 +5670,18 @@ export class TestHost {
         "jobs.start": (p) => {
             if (!this.snapshots.has(Number(p.snapshotId)))
                 throw new HostError("missing", "snapshot released");
-            if (!/^(raw|processed)(Png|Jpeg|Bmp|Mp4)$/.test(String(p.kind)) ||
-                (p.quality !== undefined && !String(p.kind).endsWith("Jpeg")))
+            const kind = String(p.kind);
+            const snapshot = this.snapshots.get(Number(p.snapshotId));
+            const clip = /^(rawMp4|processedMp4|rawCopy)$/.test(kind);
+            if (!(/^(raw|processed)(Png|Jpeg|Bmp)$/.test(kind) || clip) ||
+                (p.quality !== undefined && !kind.endsWith("Jpeg")) ||
+                (p.encoding !== undefined &&
+                    (!kind.endsWith("Mp4") || !validEncoding(p.encoding))) ||
+                (p.container !== undefined &&
+                    (kind !== "rawCopy" ||
+                        !["auto", "mp4", "mkv"].includes(String(p.container)))) ||
+                (clip && typeof p.end !== "number") ||
+                !kind.startsWith(snapshot.kind))
                 throw new HostError("invalid", `unknown job kind ${p.kind}`);
             this.exports.push(structuredClone(p));
             const jobId = ++this.#next.job;
@@ -5648,23 +5691,71 @@ export class TestHost {
                 publicationStarted: false,
                 facts: null,
                 outcome: null,
+                progress: null,
+            });
+            this.#exportJobs.set(jobId, {
+                destination: String(p.destination),
+                // A copy starts 1 s early (on a "keyframe"), the player's own way of
+                // saying the start moved; a re-encode starts on the frame.
+                clip: clip
+                    ? {
+                        start: kind === "rawCopy"
+                            ? Math.max(0, snapshot.time - 1)
+                            : snapshot.time,
+                        end: Number(p.end),
+                        container: kind !== "rawCopy"
+                            ? null
+                            : p.container === "mkv"
+                                ? "mkv"
+                                : "mp4",
+                    }
+                    : null,
             });
             return { jobId, status: "queued", snapshotId: p.snapshotId };
         },
-        // Each read advances a job one step: queued → running → completed.
+        // Each read advances a job one step: queued → running → completed. A
+        // clip reports half its progress while running.
         "jobs.state": (p) => {
             const job = this.jobs.get(Number(p.jobId));
             if (!job)
                 throw new HostError("missing", "job");
             const current = structuredClone(job);
-            if (job.status === "queued")
+            const made = this.#exportJobs.get(job.jobId);
+            const clip = made?.clip;
+            if (job.status === "queued") {
                 job.status = "running";
-            else if (job.status === "running")
+                if (clip) {
+                    const total = clip.end - clip.start;
+                    job.progress = { done: total / 2, total };
+                }
+            }
+            else if (job.status === "running" && this.exportFailure)
+                Object.assign(job, {
+                    status: "failed",
+                    outcome: { error: { ...this.exportFailure } },
+                });
+            else if (job.status === "running") {
+                const destination = clip?.container === "mkv"
+                    ? made.destination.replace(/(\.(mp4|m4v|mov|mkv|webm))?$/i, ".mkv")
+                    : clip?.container === "mp4"
+                        ? made.destination.replace(/(\.(mp4|m4v|mov|mkv|webm))?$/i, ".mp4")
+                        : "/tmp/output";
                 Object.assign(job, {
                     status: "completed",
                     publicationStarted: true,
-                    outcome: { destination: "/tmp/output" },
+                    outcome: clip
+                        ? { destination, start: clip.start, end: clip.end }
+                        : { destination },
+                    ...(job.progress
+                        ? {
+                            progress: {
+                                done: job.progress.total,
+                                total: job.progress.total,
+                            },
+                        }
+                        : {}),
                 });
+            }
             else if (job.status === "cancelling")
                 Object.assign(job, {
                     status: "cancelled",

package/dist/plugin/types.d.ts

@@ -93,7 +93,7 @@ export interface Disposable {
  * | `busy` | The player is still doing a previous call of the same kind (a dialog is open, a step is in flight). |
  * | `conflict` | Another plugin owns the resource (the sequence provider, the display layer, the backdrop, a menu path), or this plugin already uses the id (a window or command id). |
  * | `unavailable` | Not possible right now (no ready media, no user interface, fullscreen, a disabled core action). |
- * | `unsupported` | Not possible on this system, build or source (a platform gap, software rendering, a source that cannot seek, a filter on a generated stream). |
+ * | `unsupported` | Not possible on this system, build or source (a platform gap, software rendering, a source that cannot seek, a filter on a generated stream, an export the player cannot make as asked: a stream copy, a source bitrate it cannot tell). |
  * | `backend` | Loading or resolving failed; `message` is the backend's reason. |
  * | `failed` | The operation ran and failed (`media.ready()` load error, a non-zero `tools.run` exit, the system refused). |
  * | `replaced` | Accepted, but another source replaced it before it finished. |
@@ -114,6 +114,7 @@ export interface Disposable {
  * | `unknown`, `rejected`, `expired` | After a transport problem the SDK could not confirm the outcome (does not happen in normal operation). |
  * | `activation` | The plugin opened a tool window while its activation was still pending and the player could not track it. |
  * | `command` | The player could not run or update a command it no longer knows for this plugin (removed meanwhile, or another plugin's). |
+ * | `export-failed` | An export job ({@link ExportJob}) failed: the code of its `outcome.error`, not a rejection; `message` has the worker's or FFmpeg's reason. |
  * | `input-overflow` | `openStream` input: the player's queue of physical key transitions was full; the input was revoked and its keys released. |
  * | `internal` | An internal step of the player failed (keeping an operation's result, a subtitle or media job); `message` has the reason. |
  * | `javascript`, `slint` | {@link Packages.validate}: the package's entry module does not pass `node --check` / one of its Slint files does not compile; `message` has the diagnostics. |
@@ -8294,11 +8295,30 @@ export interface Snapshot extends Disposable {
      * Start exporting; the job runs in the host's offline worker.
      * One snapshot can be exported several times.
      *
+     * A **stream copy** (`format: "copy"`, player 0.7.6) writes the video
+     * stream and the snapshot's audio track as they are in the file, without
+     * decoding: lossless and about as fast as the disk, but a copy can only
+     * begin on a keyframe. It starts at the video's last keyframe at or before
+     * the snapshot time (its first keyframe when the video itself starts
+     * later; keyframes an MP4 edit list discards do not count) and is cut at
+     * `end`, where it may run a few frames past `end`. An open GOP can write
+     * a frame or two that present before the keyframe; `start` includes them.
+     * The finished job's `outcome` gives the `start` and `end` actually
+     * written; a plugin that previews the cut (with `plugin.tools.run`
+     * and ffprobe's packet flags, say) shows those once the job is done.
+     * Copies need a raw snapshot (effects and burned-in subtitles need a
+     * re-encode) and leave subtitle tracks and chapters out. `auto` writes
+     * MP4 for H.264, HEVC, AV1 or MPEG-4 video with AAC, MP3, AC-3, E-AC-3 or
+     * ALAC audio (or none), and MKV for anything else. A copy the player
+     * cannot make (no video stream, a cover image, an external audio track,
+     * codecs `mp4` cannot hold) ends `failed` with the code `unsupported`.
+     *
      * @capability media.read and media.control
      * @throws `released` (rejects) The snapshot was already released.
      * @throws `invalid` (rejects) Bad options (`quality` outside 1–100, a
      *   relative destination, a clip `end` not after the snapshot time or
-     *   past the duration).
+     *   past the duration, an {@link ExportEncoding} value outside its set,
+     *   `copy` from a processed snapshot).
      * @throws `busy` (rejects) This plugin runs 2 exports (or the player 8).
      * @throws `unavailable` (rejects) No FFmpeg, or the export worker could not
      *   start.
@@ -8318,18 +8338,48 @@ export interface Snapshot extends Disposable {
      * if (end.status !== "completed") await plugin.osd.show("Export {}", [end.status]);
      * ```
      *
+     * @example Cut without re-encoding and report where it starts
+     * The clip is copied as it is in the file. A copy starts on a keyframe,
+     * so the OSD says where it actually starts; a file the player cannot
+     * copy ends with `unsupported`, and the plugin offers a re-encode instead.
+     * ```ts
+     * declare const snapshot: Snapshot;
+     * // ---cut---
+     * const job = await snapshot.export({ format: "copy", destination: "/tmp/clip.mp4", end: snapshot.time + 20 });
+     * const state = await job.done;
+     * const outcome = state.outcome;
+     * // The copy starts on a keyframe: outcome.start says where.
+     * if (outcome && "destination" in outcome)
+     *   await plugin.osd.show("Saved {} from {} s", [outcome.destination, (outcome.start ?? snapshot.time).toFixed(1)]);
+     * // Codecs the container cannot hold, a cover image, …
+     * else if (outcome && "error" in outcome && outcome.error.code === "unsupported")
+     *   await plugin.osd.show("Fast cut is not possible for this file");
+     * ```
+     *
      * @since 1.0.0
      */
     export(options: ExportOptions): Promise<ExportJob>;
 }
 /**
  * One frame as PNG, JPEG (`quality` 1–100, default 90) or BMP (24-bit), or
- * a clip as MP4.
+ * a clip: re-encoded as MP4 (`mp4`, frame-accurate, optional
+ * {@link ExportEncoding}) or copied without re-encoding (`copy`, player
+ * 0.7.6, starting on a keyframe).
  *
  * `destination` is never overwritten if it exists. The extension does not
- * choose the format. `sampleTime` picks the frame (default: the snapshot
- * time); `end` is the clip's end in source seconds. On Windows the export
- * worker needs FFmpeg 6.1 or newer.
+ * choose the format (a copy's extension is set to its container).
+ * `sampleTime` picks the frame (default: the snapshot time); `end` is the
+ * clip's end in source seconds. On Windows the export worker needs FFmpeg
+ * 6.1 or newer.
+ *
+ * **Which players have `copy`, `encoding` and the progress and range of
+ * a job**: player 0.7.6 and later. Declare `"minPlayerVersion": "0.7.6"`,
+ * or, to keep older players and offer these only where they exist, compare
+ * {@link AppInfo.version | plugin.app.version} with `0.7.6`, as for any
+ * newer API. Do not probe by trying: on an older player the `plugin`
+ * object comes from that player's own, older SDK, which rejects `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.
  *
  * @since 1.0.0
  * @category Media
@@ -8351,19 +8401,132 @@ export type ExportOptions = {
     /** Integer 1–100, default 90. */
     quality?: number;
 } | {
-    /** A clip from the snapshot time. */
+    /** A clip from the snapshot time, re-encoded as H.264 + AAC. */
     format: "mp4";
     /** Absolute path of the new file. */
     destination: string;
     /** Clip end, source seconds. */
     end: number;
+    /**
+     * Encoder settings (player 0.7.6); without it, the settings before
+     * they existed.
+     *
+     * @since 1.6.10
+     */
+    encoding?: ExportEncoding;
+} | {
+    /**
+     * A clip copied stream by stream, without re-encoding (player 0.7.6):
+     * lossless and about as fast as the disk. It starts on the video
+     * keyframe at or before the snapshot time; see {@link Snapshot.export}.
+     *
+     * @since 1.6.10
+     */
+    format: "copy";
+    /**
+     * Absolute path of the new file. The player gives it the extension of
+     * the container it writes (`.mp4` or `.mkv`); the finished job's
+     * `outcome.destination` is the actual path.
+     */
+    destination: string;
+    /** Clip end, source seconds. */
+    end: number;
+    /**
+     * `auto` (default): MP4 when the codecs fit it, otherwise MKV. `mp4`
+     * fails with `unsupported` when they do not; `mkv` always writes MKV.
+     */
+    container?: "auto" | "mp4" | "mkv";
 };
+/**
+ * The encoder settings of a re-encoded clip (`format: "mp4"`, player
+ * 0.7.6): a closed set of values, never encoder arguments. Every field is
+ * optional; the defaults are the settings clips had before: CRF 18, the
+ * fastest speed, the source's size and frame rate, AAC 192 kb/s, one thread.
+ * A value outside its set rejects the export with `invalid`. `videoBitrate:
+ * "source"` replaces the CRF with the source's bitrate, for a "Same as
+ * source" preset.
+ *
+ * @example A small file
+ * A 720p, 30 fps clip at a lower quality, encoded with the cores the player
+ * can spare.
+ * ```ts
+ * declare const snapshot: Snapshot;
+ * // ---cut---
+ * // Each field is a ceiling or a choice from a closed set.
+ * const job = await snapshot.export({
+ *   format: "mp4",
+ *   destination: "/tmp/small.mp4",
+ *   end: snapshot.time + 30,
+ *   encoding: { crf: 26, maxHeight: 720, fps: 30, audioBitrate: 128, threads: "auto" },
+ * });
+ * ```
+ *
+ * @since 1.6.10
+ * @category Media
+ */
+export interface ExportEncoding {
+    /**
+     * H.264 quality, an integer 14–30 (x264's CRF): lower is a better picture
+     * and a bigger file. Default 18.
+     */
+    crf?: number;
+    /**
+     * Encoding effort: `faster` (default), `balanced` or `smaller` (slower,
+     * a smaller file at the same quality); x264's `veryfast`, `medium` and
+     * `slow`.
+     */
+    speed?: "faster" | "balanced" | "smaller";
+    /**
+     * The tallest picture: a taller one is scaled down to this height,
+     * keeping its shape; a shorter one is left as it is. Default: the
+     * source's size.
+     */
+    maxHeight?: 1080 | 720 | 480;
+    /**
+     * The highest frame rate: a faster source drops frames to it; a slower
+     * one is left as it is. Default: the source's rate.
+     */
+    fps?: 60 | 30;
+    /** AAC audio bitrate in kb/s. Default 192. */
+    audioBitrate?: 128 | 192 | 256;
+    /**
+     * `single` (default) encodes on one thread, leaving the other cores to
+     * playback. `auto` lets the player use more: half the logical
+     * processors, at most 8, so playback and the interface keep their rate.
+     * From player 0.7.6 every export runs at below-normal priority (as
+     * HandBrake and OBS run their encoders), with either setting.
+     */
+    threads?: "single" | "auto";
+    /**
+     * `source`: aim at the source video's average bitrate instead of a
+     * quality level (peaks up to 1.5 times it), so the file comes out about
+     * the size of that stretch of the source: a "Same as source" preset. Not
+     * together with `crf` (`invalid`). A source whose bitrate the player
+     * cannot tell ends the job `failed` with `unsupported`.
+     */
+    videoBitrate?: "source";
+}
 /**
  * An export job's state. `status` is `queued`, `running`, `cancelling`,
  * `completed`, `failed` or `cancelled`; once terminal, `outcome` is
  * `{ destination }`, `{ error: { code, message } }` or `{ cancelled: true }`.
  * `facts` describes what the worker produced (versions, range, streams).
  *
+ * From player 0.7.6:
+ * - a finished clip's `outcome` also has `start` and `end`, the source
+ *   times of its first frame and of the end of its last frame as written: a
+ *   copy's earliest written frame (its keyframe, or the leading frames of
+ *   an open GOP) and actual end; a re-encode's start and start
+ *   plus the encoded length.
+ * - `progress` is `{ done, total }` in seconds of the clip while FFmpeg
+ *   writes it (at most 4 updates a second; the SDK reads it about every
+ *   350 ms), `null` while unknown: before writing starts, and always for a
+ *   frame. Show an indeterminate bar then. After `done` reaches `total` the
+ *   player still checks the file before the job completes.
+ * - `error.code` is `export-failed`, or `unsupported` for an export the
+ *   player cannot make as asked (a stream copy it cannot make, a
+ *   `videoBitrate: "source"` whose source bitrate it cannot tell).
+ *
  * @since 1.0.0
  * @category Media
  */

package/dist/wire.d.ts

@@ -798,6 +798,11 @@ export declare function createWire(transport: Transport): {
         } | {
             kind: "rawMp4" | "processedMp4";
             end: number;
+            encoding?: import("./media.ts").WireEncoding;
+        } | {
+            kind: "rawCopy";
+            end: number;
+            container?: "auto" | "mp4" | "mkv";
         })) => Promise<{
             jobId: number;
             status: "queued";

package/llms.txt

@@ -1,6 +1,6 @@
 # Vestra Player SDK
 
-> @vestra-player/sdk 1.6.9: 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. The documentation is a tree of short pages read by path, like `go doc`: the same pages and API as https://vestrasys.github.io/vestra-player-sdk/.
+> @vestra-player/sdk 1.6.10: 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. The documentation is a tree of short pages read by path, like `go doc`: the same pages and API as https://vestrasys.github.io/vestra-player-sdk/.
 
 ## Read the documentation
 
@@ -29,7 +29,7 @@
 ## API
 
 - `/API/Commands`: 15 entries: CommandState, Bindable, Condition, When, MenuId, BarButtonIcon, CommandButton, CommandOptions, Command, Commands, HostAction, Host, BindingRef, BindingInfo, Bindings
-- `/API/Media`: 6 entries: CaptureOptions, Snapshot, ExportOptions, JobState, ExportJob, MediaCapture
+- `/API/Media`: 7 entries: CaptureOptions, Snapshot, ExportOptions, ExportEncoding, JobState, ExportJob, MediaCapture
 - `/API/Packages`: 10 entries: PackageManifest, PackageSource, InstallOptions, PackageCandidate, PackageChangeStatus, PackageChange, PluginInfo, PluginDisplay, PluginWarning, Packages
 - `/API/Playback`: 20 entries: MarkKind, TimelineMark, RangeStyle, TimelineRange, TimelineLayer, Timeline, AudioTrack, PlayerState, AudioDevice, Chapter, Conditional, Media, Scrub, StreamFrame, StreamOptions,…
 - `/API/Plugin`: 13 entries: Disposable, PluginError, Scope, Plugin, StopReason, DisposeInfo, WindowState, MainWindow, AppInfo, App, SystemInfo, DisplayInfo, Json

package/package.json

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