@vestra-player/sdk 1.6.17 → 1.6.18

package/dist/plugin/testing/internals.d.ts

@@ -0,0 +1,76 @@
+import type { Json } from "../../wire.ts";
+import type { SourceStamp } from "../../source.ts";
+import type { Locale } from "../types.ts";
+import { Catalog } from "../../i18n.ts";
+import type { TestHost } from "./index.ts";
+/** A wire method's default or overriding handler (as `TestHost.handle` takes it). */
+export type Handler = Parameters<TestHost["handle"]>[1];
+/** The private state of one `TestHost`. */
+export declare class Internals {
+    locale: Locale | undefined;
+    /** The plugin's translations for `locale` (see `loadCatalog`). */
+    catalog: Catalog;
+    /**
+     * Row patches (player 0.6.0): the `seq` of each property's last write, by
+     * view and property (none: 0, the initial properties).
+     */
+    readonly writes: Map<string, number>;
+    /** The parts of a whole value held until its last part, by view and property. */
+    readonly parts: Map<string, {
+        seq: number;
+        rows: Json[];
+    }>;
+    nextOwner: number;
+    /** Owners of other plugins' panels, by plugin id ({@link TestHost.mountOther}). */
+    readonly others: Map<string, {
+        slot: string;
+        owner: number;
+    }>;
+    /** What each job was asked to write, for its outcome. */
+    readonly exportJobs: Map<number, {
+        destination: string;
+        clip: {
+            start: number;
+            end: number;
+            container: "mp4" | "mkv" | null;
+        } | null;
+    }>;
+    sentTypes: string;
+    readonly overrides: Map<string, (params: Record<string, Json>) => unknown>;
+    readonly listeners: Map<string, Set<(data: unknown) => void>>;
+    inFlight: number;
+    /** `disconnect()` of `startPlugin`: the player is gone. */
+    lost: boolean;
+    lose: (error: Error) => void;
+    /** Rejects when the player is lost: requests in flight fail with it. */
+    readonly gone: Promise<never>;
+    next: {
+        snapshot: number;
+        job: number;
+        producer: number;
+        source: number;
+        resolution: number;
+    };
+    sourceBook: Map<number, Json>;
+    /** The pending resolutions' stamps and operations (beside `resolutions`). */
+    resolving: Map<number, {
+        stamp: SourceStamp;
+        operation?: number;
+    }>;
+    /** The producer the source is (`openProvider`, a resolved stream). */
+    selected: number | null;
+    readonly scratch: string;
+    /** The labels `commands.keys` last answered or pushed, as JSON. */
+    keysSent: string;
+    /** The binding table revision of `commands.keys` (a counter here). */
+    keysRevision: number;
+    /**
+     * The resources this plugin loaded into the current source (resource id →
+     * bytes), removed ones included: like the player, a removed track frees
+     * its place among the live tracks but not among the loads.
+     */
+    subtitleResources: {
+        generation: number;
+        bytes: Map<string, number>;
+    };
+}

package/dist/plugin/testing/internals.js

@@ -0,0 +1,60 @@
+/**
+ * The private state of a `TestHost` (`./index.ts`): what the class keeps
+ * out of its public members. The host holds one in its private `#inner`
+ * field and passes it to the area modules' functions, so it is reachable
+ * only from inside the SDK.
+ */
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Catalog } from "../../i18n.js";
+/** The private state of one `TestHost`. */
+export class Internals {
+    locale;
+    /** The plugin's translations for `locale` (see `loadCatalog`). */
+    catalog = new Catalog();
+    /**
+     * Row patches (player 0.6.0): the `seq` of each property's last write, by
+     * view and property (none: 0, the initial properties).
+     */
+    writes = new Map();
+    /** The parts of a whole value held until its last part, by view and property. */
+    parts = new Map();
+    nextOwner = 2;
+    /** Owners of other plugins' panels, by plugin id ({@link TestHost.mountOther}). */
+    others = new Map();
+    /** What each job was asked to write, for its outcome. */
+    exportJobs = new Map();
+    sentTypes = "[]";
+    overrides = new Map();
+    listeners = new Map();
+    inFlight = 0;
+    /** `disconnect()` of `startPlugin`: the player is gone. */
+    lost = false;
+    lose = () => { };
+    /** Rejects when the player is lost: requests in flight fail with it. */
+    gone = (() => {
+        const gone = new Promise((_, reject) => {
+            this.lose = reject;
+        });
+        gone.catch(() => { });
+        return gone;
+    })();
+    next = { snapshot: 0, job: 0, producer: 0, source: 0, resolution: 0 };
+    sourceBook = new Map();
+    /** The pending resolutions' stamps and operations (beside `resolutions`). */
+    resolving = new Map();
+    /** The producer the source is (`openProvider`, a resolved stream). */
+    selected = null;
+    scratch = mkdtempSync(join(tmpdir(), "vestra-test-host-"));
+    /** The labels `commands.keys` last answered or pushed, as JSON. */
+    keysSent = "";
+    /** The binding table revision of `commands.keys` (a counter here). */
+    keysRevision = 0;
+    /**
+     * The resources this plugin loaded into the current source (resource id →
+     * bytes), removed ones included: like the player, a removed track frees
+     * its place among the live tracks but not among the loads.
+     */
+    subtitleResources = { generation: -1, bytes: new Map() };
+}

package/dist/plugin/testing/jobs.d.ts

@@ -0,0 +1,9 @@
+import type { Json } from "../../wire.ts";
+import type { TestHost } from "./index.ts";
+import type { Handler, Internals } from "./internals.ts";
+/** `jobs.start`'s `encoding`, checked against the player's sets. */
+export declare function validEncoding(value: Json | undefined): boolean;
+/** Implements `TestHost.failStream`. */
+export declare function failStream(host: TestHost, inner: Internals, producerId: number, message: string): void;
+/** The default handlers of this area's wire methods, by method name. */
+export declare function jobsHandlers(host: TestHost, inner: Internals): Record<string, Handler>;

package/dist/plugin/testing/jobs.js

@@ -0,0 +1,304 @@
+/**
+ * Snapshots, export jobs and stream producers (`snapshot.*`, `jobs.*`,
+ * `producer.*`).
+ *
+ * Part of `TestHost` (`./index.ts`): functions over the host and its private
+ * state (`Internals`, `./internals.ts`) that the class delegates to.
+ * Internal to the SDK; not exported from `@vestra-player/sdk/testing`.
+ */
+import { createServer } from "node:net";
+import { randomBytes } from "node:crypto";
+import { HostError } from "../../wire.js";
+import { localSocketPath } from "../local.js";
+import { isCurrentProducer } from "./media.js";
+/** `jobs.start`'s `encoding`, checked against the player's sets. */
+export 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);
+}
+/** Implements `TestHost.failStream`. */
+export function failStream(host, inner, producerId, message) {
+    const producer = host.producers.get(producerId);
+    if (!producer || !isCurrentProducer(host, inner, producerId))
+        throw new Error(`producer ${producerId} is not the player's source`);
+    host.setSource({
+        phase: "error",
+        terminalReason: { failed: message },
+    });
+    producer.retired = true;
+}
+/** The default handlers of this area's wire methods, by method name. */
+export function jobsHandlers(host, inner) {
+    return {
+        "snapshot.capture": (p) => {
+            const expected = p.expected;
+            if (expected.generation !== host.source.stamp.generation ||
+                expected.intentVersion !== host.source.stamp.intentVersion)
+                throw new HostError("stale", "source changed");
+            const snapshotId = ++inner.next.snapshot;
+            const snapshot = {
+                snapshotId,
+                kind: p.mode === "processed" ? "processed" : "raw",
+                sourceStamp: expected,
+                time: Number(p.time ?? host.source.position ?? 0),
+                source: host.source.source ?? "",
+                duration: host.source.duration ?? 0,
+                audio: null,
+                ...(p.mode === "processed"
+                    ? {
+                        presentation: { width: 1920, height: 1080 },
+                        processing: { revision: host.processing.configurationRevision },
+                    }
+                    : {}),
+            };
+            host.snapshots.set(snapshotId, snapshot);
+            return snapshot;
+        },
+        "snapshot.state": (p) => host.snapshots.get(Number(p.snapshotId)) ?? null,
+        "snapshot.release": (p) => void host.snapshots.delete(Number(p.snapshotId)),
+        "jobs.start": (p) => {
+            if (!host.snapshots.has(Number(p.snapshotId)))
+                throw new HostError("missing", "snapshot released");
+            const kind = String(p.kind);
+            const snapshot = host.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}`);
+            host.exports.push(structuredClone(p));
+            const jobId = ++inner.next.job;
+            host.jobs.set(jobId, {
+                jobId,
+                status: "queued",
+                publicationStarted: false,
+                facts: null,
+                outcome: null,
+                progress: null,
+            });
+            inner.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. A
+        // clip reports half its progress while running.
+        "jobs.state": (p) => {
+            const job = host.jobs.get(Number(p.jobId));
+            if (!job)
+                throw new HostError("missing", "job");
+            const current = structuredClone(job);
+            const made = inner.exportJobs.get(job.jobId);
+            const clip = made?.clip;
+            if (job.status === "queued") {
+                job.status = "running";
+                if (clip) {
+                    const total = clip.end - clip.start;
+                    job.progress = { done: total / 2, total };
+                }
+            }
+            else if (job.status === "running" && host.exportFailure)
+                Object.assign(job, {
+                    status: "failed",
+                    outcome: { error: { ...host.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: 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",
+                    outcome: { cancelled: true },
+                });
+            return current;
+        },
+        "jobs.cancel": (p) => {
+            const job = host.jobs.get(Number(p.jobId));
+            if (!job)
+                throw new HostError("missing", "job");
+            if (["completed", "failed", "cancelled"].includes(job.status))
+                return { jobId: job.jobId, cancel: "terminal" };
+            job.status = "cancelling";
+            return { jobId: job.jobId, cancel: "requested" };
+        },
+        "jobs.operation": () => ({ status: "unknown" }),
+        "producer.prepare": async () => {
+            const id = ++inner.next.producer;
+            const tcp = host.producerTransport === "tcp";
+            const token = tcp ? randomBytes(32) : null;
+            // A Unix socket, or a named pipe on Windows (`localSocketPath`).
+            const path = localSocketPath(inner.scratch, `producer-${id}`);
+            const producer = {
+                id,
+                receivedFrames: 0,
+                videoFrames: 0,
+                released: false,
+                retired: false,
+                droppedWhileSelected: false,
+                path,
+                admitted: !tcp,
+                epoch: 1,
+                pending: null,
+                acknowledged: true,
+                active: false,
+                server: createServer(),
+            };
+            producer.server.on("connection", (socket) => {
+                let buffer = Buffer.alloc(0);
+                let admitted = !token;
+                socket.on("data", (data) => {
+                    buffer = Buffer.concat([buffer, data]);
+                    if (!admitted && token) {
+                        if (buffer.length < token.length)
+                            return;
+                        if (!buffer.subarray(0, token.length).equals(token))
+                            return void socket.destroy();
+                        admitted = producer.admitted = true;
+                        buffer = buffer.subarray(token.length);
+                    }
+                    while (buffer.length >= 32) {
+                        const length = buffer.readUInt32LE(24);
+                        if (buffer.length < 32 + length)
+                            break;
+                        if (buffer[4] === 1)
+                            producer.receivedFrames += length / 8;
+                        else
+                            producer.videoFrames++;
+                        buffer = buffer.subarray(32 + length);
+                    }
+                });
+                socket.on("error", () => { });
+                socket.on("close", () => {
+                    if (isCurrentProducer(host, inner, producer.id))
+                        producer.droppedWhileSelected = true;
+                });
+            });
+            let socket = path;
+            if (tcp) {
+                await new Promise((resolve) => producer.server.listen(0, "127.0.0.1", resolve));
+                const { port } = producer.server.address();
+                socket = `tcp://127.0.0.1:${port}`;
+            }
+            else
+                producer.server.listen(path);
+            host.producers.set(id, producer);
+            return {
+                producerId: id,
+                socket,
+                ...(token ? { token: token.toString("hex") } : {}),
+                epoch: 1,
+                sampleRate: 48000,
+                channels: 2,
+                sampleFormat: "f32le",
+                videoFormat: "rgba8",
+                maxAudioFrames: 4800,
+                audioCapacityFrames: 9600,
+                videoCapacity: 8,
+            };
+        },
+        "producer.state": (p) => {
+            const producer = host.producers.get(Number(p.producerId));
+            if (!producer)
+                throw new HostError("missing", "producer");
+            if (producer.retired || producer.released)
+                throw new HostError("unavailable", "producer absent");
+            const current = isCurrentProducer(host, inner, producer.id);
+            return {
+                input: null,
+                pendingControl: producer.pending,
+                producerId: producer.id,
+                epoch: producer.epoch,
+                acknowledged: producer.acknowledged,
+                paused: host.source.paused,
+                // The fake device consumes everything immediately.
+                consumedFrames: producer.receivedFrames,
+                underrunFrames: 0,
+                deviceErrors: 0,
+                health: "ok",
+                xrunEvents: 0,
+                deviceChangeEvents: 0,
+                errorDetails: [],
+                errorOverflow: 0,
+                buffer: {},
+                receivedFrames: producer.receivedFrames,
+                hasVideo: producer.videoFrames > 0,
+                error: null,
+                active: producer.active && current,
+            };
+        },
+        "producer.ack": (p) => {
+            const control = (p.control ?? {});
+            const producer = host.producers.get(Number(control.producerId));
+            if (!producer)
+                throw new HostError("missing", "producer");
+            if (producer.retired || producer.released)
+                throw new HostError("stale", "producer control changed");
+            producer.pending = null;
+            producer.acknowledged = true;
+            producer.epoch = Number(control.epoch);
+            producer.active = true;
+            return { status: "acknowledged", control };
+        },
+        "producer.ackInput": () => ({ status: "acknowledged", sequence: 0 }),
+        "producer.release": (p) => {
+            const producer = host.producers.get(Number(p.producerId));
+            if (!producer)
+                return;
+            producer.released = true;
+            producer.server.close();
+        },
+    };
+}

package/dist/plugin/testing/layout.d.ts

@@ -0,0 +1,85 @@
+import type { Json, LayoutPanel } from "../../wire.ts";
+import type { FakePanel, TestHost } from "./index.ts";
+import type { Handler, Internals } from "./internals.ts";
+export declare const kebab: (name: string) => string;
+export declare const SLOT_LABELS: Record<string, string>;
+/** The view a panel's writes are kept under (the player's, per slot). */
+export declare const mountView: (slot: string) => string;
+/** The positions that hold tabs: any number of plugins, one tab each. */
+export type TabSlot = "bottom" | "sidebar" | "adjust";
+export type WireRowOp = {
+    op: "set";
+    at: number;
+    row: Json;
+} | {
+    op: "insert";
+    at: number;
+    rows: Json[];
+} | {
+    op: "remove";
+    at: number;
+    count: number;
+} | {
+    op: "move";
+    from: number;
+    count: number;
+    to: number;
+};
+/**
+ * A patch's ops checked against an array of `length` rows, as the player
+ * checks them (`ui_patch.rs`): in order, each on the result of the ones
+ * before; at most {@link PATCH_OPS}; the result at most
+ * `UI_VALUE_LIMITS.arrayRows` rows.
+ */
+/** The player takes no Markdown documents in parts of a value (`invalid`). */
+export declare function noMarkdownParts(rows: Json[]): void;
+export declare function patchOps(ops: unknown, length: number): WireRowOp[];
+export declare function timelineChanged(host: TestHost, _inner: Internals): void;
+export declare function resetWrites(_host: TestHost, inner: Internals, view: string): void;
+/**
+ * A property write as the player takes it, returning the value the
+ * property shows after it: a whole `value`, or a `patch` of the array
+ * `current` applying on the write numbered `base` (code `stale`
+ * otherwise). The result is checked against the value limits whole: the
+ * player counts the rows a patch keeps too.
+ */
+export declare function writeProperty(host: TestHost, inner: Internals, view: string, property: string, p: Record<string, Json>, current: Json | undefined): Json | undefined;
+/**
+ * Refuse property values over the player's limits ({@link UI_VALUE_LIMITS})
+ * with `limit`, naming the property, as the player does.
+ */
+export declare function checkValues(_host: TestHost, _inner: Internals, values: Record<string, Json>): void;
+/**
+ * A panel's or settings page's initial properties, as the player keeps
+ * them: one over the limits is left out (the property keeps its default)
+ * and reported with `ui.error`, the request itself succeeds.
+ */
+export declare function initialValues(host: TestHost, _inner: Internals, values: Record<string, Json>): Record<string, Json>;
+export declare function seeImages(host: TestHost, _inner: Internals, values: Record<string, Json> | Json[]): void;
+export declare function addPanel(host: TestHost, _inner: Internals, slot: TabSlot, panel: LayoutPanel): void;
+export declare function removePanel(host: TestHost, _inner: Internals, slot: TabSlot, owner: number): void;
+/** The panel a request is about: its `slot`, else the only one. */
+export declare function panelFor(host: TestHost, _inner: Internals, p: Record<string, unknown>): FakePanel;
+/** Implements `TestHost.mountOther`. */
+export declare function mountOther(host: TestHost, inner: Internals, slot: "bottom" | "sidebar" | "adjust" | "backdrop", plugin: string, options?: {
+    title?: string;
+}): void;
+/** Implements `TestHost.unmountOther`. */
+export declare function unmountOther(host: TestHost, inner: Internals, plugin: string): void;
+/** Implements `TestHost.mounted`. */
+export declare function mounted(host: TestHost, _inner: Internals, slot?: "bottom" | "sidebar" | "adjust" | "backdrop"): FakePanel;
+/** Implements `TestHost.setTimelineRanges`. */
+export declare function setTimelineRanges(host: TestHost, inner: Internals, pluginId: string, ranges: {
+    start: number;
+    end: number;
+    style: string;
+    title?: string | null;
+}[]): void;
+/** Implements `TestHost.setTimelineLayer`. */
+export declare function setTimelineLayer(host: TestHost, inner: Internals, pluginId: string, marks: {
+    time: number;
+    kind: string;
+    title?: string | null;
+}[]): void;
+/** The default handlers of this area's wire methods, by method name. */
+export declare function layoutHandlers(host: TestHost, inner: Internals): Record<string, Handler>;