@alpha2-sh/node 0.0.0 → 0.1.0

package/dist/index.js

@@ -0,0 +1,1054 @@
+import { spawn } from "node:child_process";
+import { constants, existsSync, statSync } from "node:fs";
+import { access } from "node:fs/promises";
+import { delimiter, dirname, join, resolve } from "node:path";
+import { createInterface } from "node:readline";
+import { fileURLToPath } from "node:url";
+import { failureForCode } from "alpha2/export-failure";
+import { MAX_PROJECT_JSON_BYTES, validateProject, validateProjectJson, } from "alpha2/project";
+import { createRequest, loaderRefused, parseHostMessage, } from "./protocol.js";
+export { PROTOCOL_VERSION } from "./protocol.js";
+const VIDEO_DECODE_MODES = [
+    "software",
+    "auto",
+    "hardware-required",
+];
+/**
+ * Refuses a `field` that is set and not a {@link VideoDecodeMode}: the host would refuse it at its
+ * start, after the process was made.
+ */
+function checkVideoDecode(field, value) {
+    if (value !== undefined &&
+        !VIDEO_DECODE_MODES.includes(value))
+        throw new Alpha2HostError("INVALID_INPUT", `${field} must be software, auto, or hardware-required`);
+}
+/** Every {@link QualityLevel}, lowest first. */
+export const QUALITY_LEVELS = [
+    "very-low",
+    "low",
+    "medium",
+    "high",
+    "very-high",
+];
+/** Bytes of the host's standard error an error keeps. */
+export const STDERR_TAIL_BYTES = 16_384;
+/**
+ * Every error this client rejects with. Its `failure` classifies it for a retry policy
+ * (`alpha2/export-retry`): the host's own report when the host sent one, and otherwise the class
+ * its code is evidence of (`failureForCode`), as the host would have classified the same code, so a
+ * refusal made here or before an export started is as final as the host's.
+ */
+export class Alpha2HostError extends Error {
+    /** A machine-readable code, such as `HOST_NOT_FOUND`, `INVALID_INPUT` or `DECODE_STALLED`. */
+    code;
+    failure;
+    stderr;
+    exitCode;
+    signal;
+    constructor(code, message, options) {
+        super(message, options);
+        this.name = "Alpha2HostError";
+        this.code = code;
+        this.failure =
+            options?.failure ??
+                failureForCode(code, {
+                    message,
+                    origin: "node",
+                    backend: "native",
+                    phase: options?.phase ?? "prepare",
+                    ...(options?.stderr === undefined ? {} : { stderr: options.stderr }),
+                    ...(options?.exitCode === undefined
+                        ? {}
+                        : { exitCode: options.exitCode }),
+                    ...(options?.signal === undefined ? {} : { signal: options.signal }),
+                });
+        if (options?.stderr !== undefined)
+            this.stderr = options.stderr;
+        if (options?.exitCode !== undefined)
+            this.exitCode = options.exitCode;
+        if (options?.signal !== undefined)
+            this.signal = options.signal;
+    }
+}
+/** An export refused before it rendered: the project's media is not ready. */
+export class Alpha2ConformError extends Alpha2HostError {
+    /** What each source would read and what blocks it. */
+    report;
+    constructor(message, report, options) {
+        super("CONFORM_FAILED", message, options);
+        this.name = "Alpha2ConformError";
+        this.report = report;
+    }
+}
+/** The host could not create its GPU device (`GPU_INIT_FAILED`). */
+export class Alpha2GpuInitializationError extends Alpha2HostError {
+    constructor(message, options) {
+        super("GPU_INIT_FAILED", message, options);
+        this.name = "Alpha2GpuInitializationError";
+    }
+}
+/** The project failed validation before a host started (`INVALID_INPUT`); `problems` lists why. */
+export class Alpha2ProjectValidationError extends Alpha2HostError {
+    problems;
+    constructor(problems) {
+        super("INVALID_INPUT", `invalid alpha2 project:\n${problems.join("\n")}`);
+        this.name = "Alpha2ProjectValidationError";
+        this.problems = problems;
+    }
+}
+/** The request's `signal` aborted it (`ABORTED`). */
+export class Alpha2AbortError extends Alpha2HostError {
+    constructor() {
+        super("ABORTED", "alpha2 export was aborted");
+        this.name = "Alpha2AbortError";
+    }
+}
+/**
+ * The file name `alpha2-host` has on `platform`: Windows executables carry `.exe`, and nothing
+ * there adds it to a path that lacks it.
+ */
+export function hostExecutableName(platform = process.platform) {
+    return platform === "win32" ? "alpha2-host.exe" : "alpha2-host";
+}
+/** Where the native archives that carry `alpha2-host` are published. */
+const HOST_RELEASES_URL = "https://github.com/alpha2-sh/alpha2/releases";
+/**
+ * Locates `alpha2-host` without loading Electron. The package does not ship the binary: it comes
+ * in the platform's native archive on https://github.com/alpha2-sh/alpha2/releases, as
+ * `bin/alpha2-host` beside the `lib/` it loads. Native archives and Electron applications should
+ * keep `bin/` and `lib/` together and unpack both from ASAR. Resolution order is explicit path,
+ * `ALPHA2_HOST_PATH`, Electron resources (`bin/`, then the directory itself), this package's own
+ * `bin/`, then `PATH`.
+ *
+ * Throws an {@link Alpha2HostError}: `INVALID_INPUT` for an empty `hostPath`, `HOST_NOT_FOUND` when
+ * an explicit path is not a file or no candidate exists; the latter message names the native
+ * archive. An empty `ALPHA2_HOST_PATH` is unset.
+ */
+export function resolveHostBinary(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const executable = hostExecutableName();
+    if (options.hostPath !== undefined && options.hostPath.trim() === "")
+        throw new Alpha2HostError("INVALID_INPUT", "hostPath must not be empty");
+    // An empty variable is an unset one, as a shell or Compose leaves a variable it was given blank.
+    const fromEnvironment = process.env.ALPHA2_HOST_PATH;
+    const explicit = options.hostPath ?? (fromEnvironment?.trim() ? fromEnvironment : undefined);
+    if (explicit !== undefined) {
+        const candidate = asarUnpacked(resolve(cwd, explicit));
+        if (isFile(candidate))
+            return candidate;
+        throw new Alpha2HostError("HOST_NOT_FOUND", `alpha2-host does not exist: ${candidate}`);
+    }
+    const processResources = process.resourcesPath;
+    const resourcesPath = options.resourcesPath ?? processResources;
+    const moduleDirectory = dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        resourcesPath && join(resourcesPath, "bin", executable),
+        resourcesPath && join(resourcesPath, executable),
+        join(moduleDirectory, "..", "bin", executable),
+    ];
+    for (const raw of candidates) {
+        if (!raw)
+            continue;
+        const candidate = asarUnpacked(raw);
+        if (isFile(candidate))
+            return candidate;
+    }
+    for (const directory of (process.env.PATH ?? "").split(delimiter)) {
+        if (!directory)
+            continue;
+        const candidate = join(directory, executable);
+        if (isFile(candidate))
+            return candidate;
+    }
+    throw new Alpha2HostError("HOST_NOT_FOUND", `could not locate ${executable}; download the native archive for this platform from ` +
+        `${HOST_RELEASES_URL} and set hostPath or ALPHA2_HOST_PATH to its bin/${executable}, ` +
+        "or put that bin/ on PATH");
+}
+/**
+ * Runs requests on `alpha2-host` sidecar processes, one process per request, at most
+ * `concurrency` at a time; further requests wait for a slot. Every rejection is an
+ * {@link Alpha2HostError}.
+ */
+export class Alpha2NodeClient {
+    #binary;
+    #slots;
+    #videoDecode;
+    /** Capability probes by decode mode: running, or answered. */
+    #probes = new Map();
+    /**
+     * Resolves the host binary now. Throws a `RangeError` for a `concurrency` that is not a positive
+     * integer, and an {@link Alpha2HostError} when `videoDecode` is not a mode (`INVALID_INPUT`) or
+     * the binary cannot be found.
+     */
+    constructor(options = {}) {
+        const concurrency = options.concurrency ?? 1;
+        if (!Number.isSafeInteger(concurrency) || concurrency < 1) {
+            throw new RangeError("concurrency must be a positive integer");
+        }
+        checkVideoDecode("videoDecode", options.videoDecode);
+        this.#binary = resolveHostBinary(options);
+        this.#slots = new Semaphore(concurrency);
+        this.#videoDecode = options.videoDecode;
+    }
+    /**
+     * What the host can decode, render and encode, for the client's decode mode or
+     * `options.videoDecode`. The first call for a mode starts a host, in a slot like any request;
+     * calls made while it runs share it, and its report answers every later call for that mode on
+     * this client, since the same binary and mode report the same. A probe that fails is not kept:
+     * the next call starts another.
+     *
+     * `options.signal` withdraws this call (`Alpha2AbortError`); the probe goes on while another call
+     * still waits for it, and is withdrawn, from its slot or its host, when none does.
+     */
+    async getCapabilities(options = {}) {
+        checkVideoDecode("videoDecode", options.videoDecode);
+        const { signal } = options;
+        if (signal?.aborted)
+            throw new Alpha2AbortError();
+        const videoDecode = options.videoDecode ?? this.#videoDecode;
+        // Unset, the mode is the host's default or the one this process's environment names.
+        const key = videoDecode ?? `environment:${process.env.ALPHA2_VIDEO_DECODE ?? ""}`;
+        let probe = this.#probes.get(key);
+        if (probe === undefined) {
+            const controller = new AbortController();
+            const result = (async () => {
+                const release = await this.#slots.acquire(controller.signal);
+                try {
+                    return (await requestHost(this.#binary, "capabilities", {}, { videoDecode }, controller.signal));
+                }
+                finally {
+                    release();
+                }
+            })();
+            const started = {
+                result,
+                controller,
+                waiting: 0,
+                settled: false,
+            };
+            probe = started;
+            this.#probes.set(key, started);
+            result.then(() => {
+                started.settled = true;
+            }, () => {
+                started.settled = true;
+                if (this.#probes.get(key) === started)
+                    this.#probes.delete(key);
+            });
+        }
+        if (probe.settled)
+            return probe.result;
+        // Every call waiting counts, a call without a signal too: it holds the probe until it settles.
+        const waited = probe;
+        waited.waiting += 1;
+        return new Promise((resolveCall, rejectCall) => {
+            const leave = () => {
+                signal?.removeEventListener("abort", withdraw);
+                waited.waiting -= 1;
+            };
+            const withdraw = () => {
+                leave();
+                if (waited.waiting === 0 && !waited.settled) {
+                    if (this.#probes.get(key) === waited)
+                        this.#probes.delete(key);
+                    waited.controller.abort();
+                }
+                rejectCall(new Alpha2AbortError());
+            };
+            signal?.addEventListener("abort", withdraw, { once: true });
+            waited.result.then((report) => {
+                leave();
+                resolveCall(report);
+            }, (error) => {
+                leave();
+                rejectCall(error);
+            });
+        });
+    }
+    /**
+     * Which media a purpose would read for each source, and what blocks it, without rendering. The
+     * host hashes an original only when the project recorded a hash to compare. Rejects with an
+     * {@link Alpha2ProjectValidationError} for an invalid project.
+     */
+    async conform(request) {
+        const problems = projectProblems(request.project);
+        if (problems.length > 0)
+            throw new Alpha2ProjectValidationError(problems);
+        validateMediaPaths(request, false);
+        const release = await this.#slots.acquire(request.signal);
+        try {
+            return (await requestHost(this.#binary, "conform", {
+                project: request.project,
+                assets: request.assets ?? {},
+                proxies: proxiesPayload(request.proxies),
+                frames: request.frames ?? {},
+                purpose: (request.purpose ?? "export_original").replace(/_/g, "-"),
+            }, { videoDecode: this.#videoDecode }, request.signal));
+        }
+        finally {
+            release();
+        }
+    }
+    /**
+     * Renders and encodes `request.project` to `request.output` and resolves with that path.
+     *
+     * Rejects with an {@link Alpha2ProjectValidationError} or an `INVALID_INPUT` error before a host
+     * starts when the project or request is invalid, an {@link Alpha2ConformError} when the media is
+     * not ready, an {@link Alpha2AbortError} when `signal` aborts, and an {@link Alpha2HostError}
+     * otherwise. Under the `auto` decode mode, an export whose hardware decoder stalls
+     * (`DECODE_STALLED`) runs once more decoding in software; its progress starts over. When that
+     * run fails too, its error is the export's, with the stall as its `cause` and in
+     * `failure.diagnostics.decodeStall`.
+     */
+    async exportProject(request) {
+        const problems = projectProblems(request.project);
+        if (problems.length > 0)
+            throw new Alpha2ProjectValidationError(problems);
+        validateExportRequest(request);
+        const release = await this.#slots.acquire(request.signal);
+        const videoDecode = request.videoDecode ?? this.#videoDecode;
+        try {
+            const run = (mode) => requestHost(this.#binary, "export", {
+                project: request.project,
+                assets: request.assets,
+                proxies: proxiesPayload(request.proxies),
+                frames: request.frames ?? {},
+                resources: request.resources ?? {},
+                media: request.media ?? "original",
+                effectAssets: request.effectAssets ?? {},
+                fonts: request.fonts ?? [],
+                effects: request.effects ?? [],
+                startTicks: request.startTicks,
+                endTicks: request.endTicks,
+                frameRate: request.frameRate,
+                includeAudio: request.includeAudio ?? true,
+                videoCodec: request.videoCodec ?? "h264",
+                videoEncoder: request.videoEncoder,
+                inputPolicy: request.inputPolicy ?? "auto",
+                strategy: request.strategy ?? "render",
+                videoQuality: request.videoQuality,
+                audioCodec: request.audioCodec ?? "aac",
+                audioQuality: request.audioQuality,
+                loudness: request.loudness,
+                renderCache: request.renderCache,
+                ...(request.memory === undefined ? {} : { memory: request.memory }),
+                output: request.output,
+            }, { videoDecode: mode }, request.signal, request.onProgress);
+            let result;
+            try {
+                result = (await run(videoDecode));
+            }
+            catch (error) {
+                // A hardware decoder stuck inside the driver cannot be recovered by its host, so the export
+                // reruns in a new host decoding on the CPU. Only a stall with a hardware session (resource
+                // "gpu") is retried: a software stall would recur, and `hardware-required` rules it out.
+                if (!(error instanceof Alpha2HostError) ||
+                    error.code !== "DECODE_STALLED" ||
+                    error.failure?.resource !== "gpu" ||
+                    (videoDecode ?? process.env.ALPHA2_VIDEO_DECODE) ===
+                        "hardware-required")
+                    throw error;
+                try {
+                    result = (await run("software"));
+                }
+                catch (retryError) {
+                    throw recordDecodeStall(retryError, error);
+                }
+            }
+            await request.onResult?.(result);
+            return request.output;
+        }
+        finally {
+            release();
+        }
+    }
+}
+/**
+ * `retryError`, the failure of the software run a hardware decode stall led to, with the stall
+ * kept: as its `cause` unless it has one, and in its failure's diagnostics as `decodeStall`, which
+ * crosses process boundaries with the failure. The retry's failure stays the export's: a retry
+ * policy judges what the last run did.
+ */
+function recordDecodeStall(retryError, stall) {
+    if (!(retryError instanceof Alpha2HostError))
+        return retryError;
+    if (retryError.cause === undefined)
+        Object.defineProperty(retryError, "cause", {
+            value: stall,
+            writable: true,
+            configurable: true,
+        });
+    retryError.failure = {
+        ...retryError.failure,
+        diagnostics: {
+            ...retryError.failure.diagnostics,
+            decodeStall: {
+                hostCode: stall.code,
+                code: stall.failure.code,
+                phase: stall.failure.phase,
+                message: stall.message,
+                ...(stall.stderr === undefined ? {} : { stderr: stall.stderr }),
+            },
+        },
+    };
+    return retryError;
+}
+/**
+ * What the host's engine would refuse in `project`, found before a host starts: the shape the SDK
+ * validator checks, and the size the engine checks in the text it is sent
+ * (`MAX_PROJECT_JSON_BYTES`), which an object cannot show.
+ */
+function projectProblems(project) {
+    // `undefined` and the like have no text; the object validator says what they lack.
+    const json = JSON.stringify(project);
+    return json === undefined
+        ? validateProject(project)
+        : validateProjectJson(json);
+}
+const convenienceClients = new Map();
+/**
+ * {@link Alpha2NodeClient.getCapabilities} on a client shared by every module-level call with the
+ * same `concurrency` and resolved binary, for `options.videoDecode`.
+ */
+export async function getCapabilities(options = {}) {
+    return sharedClient(options).getCapabilities({
+        ...(options.signal === undefined ? {} : { signal: options.signal }),
+        ...(options.videoDecode === undefined
+            ? {}
+            : { videoDecode: options.videoDecode }),
+    });
+}
+/**
+ * {@link Alpha2NodeClient.exportProject} on a client shared by every module-level call with the
+ * same `concurrency` and resolved binary, so `concurrency` holds across calls whatever decode mode
+ * each asks for. `options.videoDecode` applies where the request names none.
+ */
+export async function exportProject(request, options = {}) {
+    return sharedClient(options).exportProject(request.videoDecode === undefined && options.videoDecode !== undefined
+        ? { ...request, videoDecode: options.videoDecode }
+        : request);
+}
+/**
+ * The pool is the host binary and `concurrency`: the decode mode travels with each request, so
+ * calls that differ only in it still share the bound.
+ */
+function sharedClient(options) {
+    const concurrency = options.concurrency ?? 1;
+    if (!Number.isSafeInteger(concurrency) || concurrency < 1) {
+        throw new RangeError("concurrency must be a positive integer");
+    }
+    checkVideoDecode("videoDecode", options.videoDecode);
+    const binary = resolveHostBinary(options);
+    const key = `${concurrency}\0${binary}`;
+    let client = convenienceClients.get(key);
+    if (client === undefined) {
+        client = new Alpha2NodeClient({ hostPath: binary, concurrency });
+        convenienceClients.set(key, client);
+    }
+    return client;
+}
+function validateExportRequest(request) {
+    const integer = (value) => Number.isSafeInteger(value);
+    if (!integer(request.startTicks) ||
+        !integer(request.endTicks) ||
+        request.endTicks <= request.startTicks) {
+        throw new Alpha2HostError("INVALID_INPUT", "export range must be a non-empty integer tick range");
+    }
+    if (!Number.isSafeInteger(request.frameRate.num) ||
+        request.frameRate.num <= 0 ||
+        !Number.isSafeInteger(request.frameRate.den) ||
+        request.frameRate.den <= 0) {
+        throw new Alpha2HostError("INVALID_INPUT", "frameRate must be a positive rational");
+    }
+    for (const [field, value] of Object.entries(request.memory ?? {})) {
+        if (field === "scale") {
+            if (value !== undefined &&
+                (typeof value !== "number" || !(value > 0 && value <= 1)))
+                throw new Alpha2HostError("INVALID_INPUT", "memory.scale must be above 0 and at most 1");
+            continue;
+        }
+        if (![
+            "inFlightBytes",
+            "decodeQueueBytes",
+            "reverseCacheBytes",
+            "audioWindowBytes",
+            "providerSourceBytes",
+        ].includes(field))
+            throw new Alpha2HostError("INVALID_INPUT", `memory has an unknown field "${field}"`);
+        if (value !== undefined && (!Number.isSafeInteger(value) || value <= 0))
+            throw new Alpha2HostError("INVALID_INPUT", `memory.${field} must be a positive byte count`);
+    }
+    // Media usability is the host's conform check, which answers with a structured report.
+    validateMediaPaths(request, true);
+    checkPathRecord("effectAssets", request.effectAssets, "effect asset path");
+    if (request.resources !== undefined) {
+        if (!isRecord(request.resources))
+            invalidShape("resources must map source ids to their files");
+        for (const [id, files] of Object.entries(request.resources))
+            checkPathRecord(`resources.${id}`, files, "resource path");
+    }
+    if (request.effects !== undefined && !Array.isArray(request.effects))
+        invalidShape("effects must be a list of effect definitions");
+    if (request.media !== undefined &&
+        !["original", "proxies"].includes(request.media)) {
+        throw new Alpha2HostError("INVALID_INPUT", 'media must be "original" or "proxies"');
+    }
+    if (request.fonts !== undefined &&
+        (!Array.isArray(request.fonts) || !request.fonts.every(nonEmptyString)))
+        invalidShape("fonts must be a list of font file paths");
+    for (const resource of request.project.effect_resources ?? []) {
+        const path = request.effectAssets?.[resource.id];
+        if (typeof path !== "string" || path.length === 0) {
+            throw new Alpha2HostError("MISSING_INPUT", `missing effect asset path for resource ${resource.id}`);
+        }
+    }
+    if (typeof request.output !== "string" || request.output.length === 0) {
+        throw new Alpha2HostError("INVALID_INPUT", "output must not be empty");
+    }
+    checkVideoDecode("videoDecode", request.videoDecode);
+    if (request.videoEncoder !== undefined &&
+        (typeof request.videoEncoder !== "string" ||
+            request.videoEncoder.length === 0)) {
+        throw new Alpha2HostError("INVALID_INPUT", "videoEncoder must be a non-empty FFmpeg encoder name");
+    }
+    if (request.strategy !== undefined &&
+        !["render", "prefer-copy", "require-copy"].includes(request.strategy)) {
+        throw new Alpha2HostError("INVALID_INPUT", "strategy must be render, prefer-copy, or require-copy");
+    }
+    if (request.inputPolicy !== undefined &&
+        !["auto", "gpu-required", "cpu-readback"].includes(request.inputPolicy)) {
+        throw new Alpha2HostError("INVALID_INPUT", "inputPolicy must be auto, gpu-required, or cpu-readback");
+    }
+    validateQuality("videoQuality", request.videoQuality, [
+        "bitrate",
+        "mode",
+        "quantizer",
+    ]);
+    validateQuality("audioQuality", request.audioQuality, ["bitrate"]);
+    validateLoudness(request);
+    const cache = request.renderCache;
+    if (cache !== undefined &&
+        (typeof cache.directory !== "string" ||
+            cache.directory.length === 0 ||
+            (cache.quotaBytes !== undefined &&
+                (!Number.isSafeInteger(cache.quotaBytes) || cache.quotaBytes <= 0)) ||
+            (cache.backlog !== undefined &&
+                cache.backlog !== "skip" &&
+                cache.backlog !== "wait")))
+        throw new Alpha2HostError("INVALID_INPUT", 'renderCache takes a non-empty directory, an optional positive integer quotaBytes, and an optional backlog "skip" or "wait"');
+}
+/**
+ * Refuses `assets`, `proxies` and `frames` not shaped as the host reads them (paths per source id)
+ * before a host starts; the host would refuse them as `INVALID_REQUEST`.
+ */
+function validateMediaPaths(request, assetsRequired) {
+    if (assetsRequired && request.assets === undefined)
+        invalidShape("assets must map source ids to paths");
+    checkPathRecord("assets", request.assets, "asset path");
+    if (request.proxies !== undefined) {
+        if (!isRecord(request.proxies))
+            invalidShape("proxies must map source ids to lists of proxy files");
+        for (const [id, files] of Object.entries(request.proxies))
+            if (!Array.isArray(files) ||
+                !files.every((file) => isRecord(file) && nonEmptyString(file.path)))
+                invalidShape(`proxies for source ${id} must be a list of { path } proxy files`);
+    }
+    if (request.frames !== undefined) {
+        if (!isRecord(request.frames))
+            invalidShape("frames must map source ids to lists of frame files");
+        for (const [id, files] of Object.entries(request.frames))
+            if (!Array.isArray(files) ||
+                !files.every((file) => file === null || nonEmptyString(file)))
+                invalidShape(`frames for source ${id} must be a list of frame file paths, null for a gap`);
+    }
+}
+/** Refuses a `field` that is not a record of non-empty path strings. */
+function checkPathRecord(field, value, what) {
+    if (value === undefined)
+        return;
+    if (!isRecord(value))
+        invalidShape(`${field} must map ids to paths`);
+    for (const [id, path] of Object.entries(value))
+        if (!nonEmptyString(path))
+            invalidShape(`${what} for ${id} must be a non-empty string`);
+}
+function invalidShape(message) {
+    throw new Alpha2HostError("INVALID_INPUT", message);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function nonEmptyString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+/** The host's `loudness` checks, with its messages. */
+function validateLoudness(request) {
+    const loudness = request.loudness;
+    if (loudness === undefined)
+        return;
+    const invalid = (message) => {
+        throw new Alpha2HostError("INVALID_INPUT", message);
+    };
+    if (typeof loudness !== "object" || loudness === null)
+        invalid("loudness must be an object { targetLufs, truePeakCeilingDbtp }");
+    const unknown = Object.keys(loudness).find((key) => key !== "targetLufs" && key !== "truePeakCeilingDbtp");
+    if (unknown !== undefined)
+        invalid(`loudness has an unknown key "${unknown}"; it takes targetLufs and truePeakCeilingDbtp`);
+    const within = (key, low) => {
+        const value = loudness[key];
+        if (typeof value !== "number" || !(value >= low && value <= 0))
+            invalid(`loudness.${key} must be within ${low}..=0, received ${value}`);
+    };
+    within("targetLufs", -60);
+    within("truePeakCeilingDbtp", -20);
+    if (request.includeAudio === false)
+        invalid("loudness normalizes the export's audio and needs includeAudio: true");
+}
+/**
+ * Rejects what the host would reject, with the same field names, before a process is started. The
+ * host checks again; this only moves the error earlier.
+ */
+function validateQuality(field, quality, keys) {
+    if (quality === undefined)
+        return;
+    const invalid = (message) => {
+        throw new Alpha2HostError("INVALID_INPUT", `${field}${message}`);
+    };
+    if (typeof quality === "string") {
+        if (!QUALITY_LEVELS.includes(quality))
+            invalid(` must be one of ${QUALITY_LEVELS.join(", ")}, received "${quality}"`);
+        return;
+    }
+    if (typeof quality !== "object" || quality === null || Array.isArray(quality))
+        invalid(" must be a quality level name or an explicit rate object");
+    const rate = quality;
+    const unknown = Object.keys(rate).find((key) => !keys.includes(key));
+    if (unknown !== undefined)
+        invalid(` has an unknown key "${unknown}"; an explicit rate takes ${keys.join(" and ")}`);
+    if (typeof rate.bitrate !== "number" ||
+        !Number.isSafeInteger(rate.bitrate) ||
+        rate.bitrate <= 0)
+        invalid(".bitrate must be a positive integer number of bits per second");
+    if (rate.mode !== undefined &&
+        rate.mode !== "constant" &&
+        rate.mode !== "variable")
+        invalid('.mode must be "constant" or "variable"');
+    if (rate.quantizer !== undefined &&
+        (typeof rate.quantizer !== "number" ||
+            !Number.isInteger(rate.quantizer) ||
+            rate.quantizer < 0 ||
+            rate.quantizer > 255))
+        invalid(".quantizer must be an integer from 0 to 255");
+}
+async function requestHost(binary, operation, payload, settings, signal, onProgress) {
+    if (signal?.aborted)
+        throw new Alpha2AbortError();
+    // Windows Node starts a batch file only through a shell, which this never asks for: the spawn
+    // would fail with EINVAL, a start that no retry mends.
+    if (process.platform === "win32" && /\.(bat|cmd)$/i.test(binary))
+        throw new Alpha2HostError("HOST_NOT_EXECUTABLE", `alpha2-host must be the executable, not a batch file: ${binary}`);
+    await access(binary, process.platform === "win32" ? constants.F_OK : constants.X_OK).catch((cause) => {
+        throw new Alpha2HostError("HOST_NOT_EXECUTABLE", `cannot execute alpha2-host: ${binary}`, {
+            cause,
+        });
+    });
+    const requestId = `node-${process.pid}-${Date.now()}-${nextRequestSequence++}`;
+    // The request becomes its line before a host starts: a value JSON cannot carry (a BigInt, a
+    // cycle, a throwing `toJSON`) refuses the request and starts nothing.
+    let requestLine;
+    try {
+        requestLine = `${JSON.stringify(createRequest(operation, requestId, payload))}\n`;
+    }
+    catch (cause) {
+        throw new Alpha2HostError("INVALID_INPUT", `the ${operation} request cannot be written as JSON: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+    }
+    // The host would make its GPU device before refusing a line this long, unread.
+    const lineBytes = Buffer.byteLength(requestLine) - 1;
+    if (lineBytes > MAX_REQUEST_LINE_BYTES)
+        throw new Alpha2HostError("INVALID_INPUT", `the ${operation} request is ${lineBytes} bytes of JSON; the host reads at most ${MAX_REQUEST_LINE_BYTES}`);
+    return new Promise((resolvePromise, rejectPromise) => {
+        const startFailed = (cause) => new Alpha2HostError("HOST_START_FAILED", `could not start alpha2-host: ${String(cause)}`, { cause });
+        let child;
+        try {
+            child = spawn(binary, ["serve"], {
+                stdio: ["pipe", "pipe", "pipe"],
+                windowsHide: true,
+                // The host chooses its decode path while it creates the renderer device, before any request
+                // arrives, so the mode travels in the environment rather than in the request.
+                env: settings.videoDecode === undefined
+                    ? process.env
+                    : { ...process.env, ALPHA2_VIDEO_DECODE: settings.videoDecode },
+            });
+        }
+        catch (cause) {
+            rejectPromise(startFailed(cause));
+            return;
+        }
+        let settled = false;
+        let outcome;
+        let forceKillTimer;
+        let writeFailedTimer;
+        // The last bytes of the host's standard error, cut to a character when read.
+        let stderr = Buffer.alloc(0);
+        let lastPhase;
+        let reader;
+        let requestPipe;
+        // What an async onProgress returned and has not settled: the request settles after them, so a
+        // callback never runs past its promise.
+        const pendingCallbacks = new Set();
+        let callbackFailure;
+        const stderrTail = () => utf8Tail(stderr, STDERR_TAIL_BYTES);
+        const phaseNow = () => lastPhase === "finalizing"
+            ? "mux"
+            : lastPhase === "frames"
+                ? "render"
+                : "prepare";
+        const finish = (nextOutcome) => {
+            if (settled || outcome !== undefined)
+                return;
+            outcome = nextOutcome;
+            signal?.removeEventListener("abort", abort);
+            reader?.close();
+            requestPipe?.end();
+            if (child.exitCode === null && child.signalCode === null)
+                child.kill("SIGTERM");
+            forceKillTimer = setTimeout(() => {
+                if (child.exitCode === null && child.signalCode === null)
+                    child.kill("SIGKILL");
+            }, HOST_SHUTDOWN_TIMEOUT_MS);
+        };
+        const fail = (error) => finish({ ok: false, error });
+        // A host error becomes the call's error once the host has ended: stderr written before the
+        // answer may be read after it (often on macOS).
+        const failFromHost = (error) => {
+            const phase = phaseNow();
+            finish({
+                ok: false,
+                error: () => errorFromHost(error, stderrTail(), phase),
+            });
+        };
+        const abort = () => fail(new Alpha2AbortError());
+        const callbackFailed = (error) => {
+            callbackFailure ??= error;
+            fail(error);
+        };
+        const track = (returned) => {
+            if (!isThenable(returned))
+                return;
+            const pending = Promise.resolve(returned).then(() => undefined, (cause) => callbackFailed(new Alpha2HostError("PROGRESS_CALLBACK_FAILED", "onProgress callback rejected", { cause, phase: phaseNow() })));
+            pendingCallbacks.add(pending);
+            void pending.then(() => pendingCallbacks.delete(pending));
+        };
+        const conclude = (code, exitSignal) => {
+            if (outcome?.ok === true && callbackFailure !== undefined) {
+                rejectPromise(callbackFailure);
+            }
+            else if (outcome?.ok === true) {
+                resolvePromise(outcome.result);
+            }
+            else if (outcome?.ok === false) {
+                rejectPromise(typeof outcome.error === "function" ? outcome.error() : outcome.error);
+            }
+            else {
+                const tail = stderrTail();
+                const ended = `exit ${exitSignal ?? code ?? "unknown"}`;
+                const detail = tail.trim() || ended;
+                if (code === 70 || detail.includes("GPU_INIT_FAILED")) {
+                    rejectPromise(new Alpha2GpuInitializationError(detail, {
+                        stderr: tail,
+                        exitCode: code,
+                        signal: exitSignal,
+                    }));
+                }
+                else if (loaderRefused(code, tail)) {
+                    // The loader refused the executable before it ran (a missing or mismatched FFmpeg):
+                    // the same host on the same machine fails the same way, so no retry is asked for.
+                    rejectPromise(new Alpha2HostError("HOST_LOAD_FAILED", `alpha2-host could not be loaded: ${detail}`, { stderr: tail, exitCode: code, signal: exitSignal }));
+                }
+                else {
+                    // Nothing the host said names a cause, so none is claimed: a SIGKILL is as consistent
+                    // with an external kill as with the OOM killer.
+                    const failure = {
+                        code: "HOST_EXITED",
+                        message: `alpha2-host exited before responding (${ended})`,
+                        origin: "node",
+                        operation: "export",
+                        backend: "native",
+                        phase: phaseNow(),
+                        resource: "unknown",
+                        stderr: tail,
+                        exitCode: code,
+                        signal: exitSignal,
+                    };
+                    rejectPromise(new Alpha2HostError("HOST_EXITED", `alpha2-host exited before responding: ${detail}`, {
+                        failure,
+                        stderr: tail,
+                        exitCode: code,
+                        signal: exitSignal,
+                    }));
+                }
+            }
+        };
+        // A spawn without its standard streams (EMFILE, ENFILE) has no host to end and may never close:
+        // it settles as it fails.
+        const failWithoutHost = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            if (child.pid !== undefined)
+                child.kill("SIGKILL");
+            rejectPromise(error);
+        };
+        const { stdin, stdout, stderr: errorPipe } = child;
+        const streamsMissing = !stdin || !stdout || !errorPipe;
+        // Before anything else: a spawn that fails reports it as this event, which would otherwise end
+        // this process unheard.
+        child.on("error", (cause) => {
+            if (streamsMissing)
+                failWithoutHost(startFailed(cause));
+            else
+                fail(startFailed(cause));
+        });
+        child.on("close", (code, exitSignal) => {
+            if (settled)
+                return;
+            settled = true;
+            signal?.removeEventListener("abort", abort);
+            reader?.close();
+            if (forceKillTimer !== undefined)
+                clearTimeout(forceKillTimer);
+            if (writeFailedTimer !== undefined)
+                clearTimeout(writeFailedTimer);
+            if (pendingCallbacks.size === 0)
+                conclude(code, exitSignal);
+            else
+                void Promise.allSettled(pendingCallbacks).then(() => conclude(code, exitSignal));
+        });
+        if (streamsMissing) {
+            // Node reports the cause on the next tick; this names the failure if it does not.
+            setImmediate(() => failWithoutHost(startFailed("its standard streams could not be created")));
+            return;
+        }
+        try {
+            requestPipe = stdin;
+            // A pipe fails when the host goes away; its stream `error` event would end this process
+            // unheard, and the host's own report or exit is the outcome, so it is only noted.
+            const ignore = () => { };
+            stdin.on("error", ignore);
+            stdout.on("error", ignore);
+            errorPipe.on("error", ignore);
+            errorPipe.on("data", (chunk) => {
+                stderr = Buffer.concat([stderr, chunk]);
+                if (stderr.length > STDERR_TAIL_BYTES)
+                    stderr = stderr.subarray(stderr.length - STDERR_TAIL_BYTES);
+            });
+            reader = createInterface({ input: stdout });
+            reader.on("line", (line) => {
+                // Every message is a JSON object. A line that does not start as one is a library's the host
+                // loaded (a Vulkan validation layer prints to stdout): diagnostic output, kept with stderr.
+                if (!line.startsWith("{")) {
+                    stderr = Buffer.concat([stderr, Buffer.from(`${line}\n`)]);
+                    if (stderr.length > STDERR_TAIL_BYTES)
+                        stderr = stderr.subarray(stderr.length - STDERR_TAIL_BYTES);
+                    return;
+                }
+                let message;
+                try {
+                    message = parseHostMessage(line);
+                }
+                catch (cause) {
+                    fail(new Alpha2HostError("INVALID_RESPONSE", "alpha2-host returned invalid JSON", { cause, phase: phaseNow() }));
+                    return;
+                }
+                if ("type" in message) {
+                    if (message.type === "fatal") {
+                        failFromHost(message.error);
+                        return;
+                    }
+                    if (message.requestId === requestId) {
+                        lastPhase = message.phase ?? "frames";
+                        notifyProgress(message, onProgress, callbackFailed, track, phaseNow());
+                    }
+                    return;
+                }
+                // A process serves this one request, so an answer to a line the host could not read an id
+                // from is its answer.
+                if (message.requestId !== requestId &&
+                    message.requestId !== UNREAD_REQUEST_ID)
+                    return;
+                if (message.ok)
+                    finish({ ok: true, result: message.result });
+                else
+                    failFromHost(message.error);
+            });
+            if (signal?.aborted) {
+                abort();
+                return;
+            }
+            signal?.addEventListener("abort", abort, { once: true });
+            stdin.write(requestLine, (error) => {
+                if (!error) {
+                    stdin.end();
+                    return;
+                }
+                // The host's own report (a fatal line) and its exit arrive after this: they name the cause.
+                // Only a host that stays up without taking its request fails as unwritten.
+                writeFailedTimer = setTimeout(() => {
+                    fail(new Alpha2HostError("HOST_WRITE_FAILED", error.message, {
+                        cause: error,
+                    }));
+                }, HOST_SHUTDOWN_TIMEOUT_MS);
+            });
+        }
+        catch (cause) {
+            fail(startFailed(cause));
+        }
+    });
+}
+function isThenable(value) {
+    return ((typeof value === "object" || typeof value === "function") &&
+        value !== null &&
+        typeof value.then === "function");
+}
+/**
+ * Calls `callback` with a progress report. A throw fails the request; a promise it returns is
+ * `track`ed, whose rejection fails it too.
+ */
+function notifyProgress(message, callback, fail, track, phase) {
+    try {
+        track(callback?.({
+            phase: message.phase ?? "frames",
+            completed: message.completed,
+            total: message.total,
+        }));
+    }
+    catch (cause) {
+        fail(new Alpha2HostError("PROGRESS_CALLBACK_FAILED", "onProgress callback threw", { cause, phase }));
+    }
+}
+/**
+ * The error the host reported, with its failure report, or, when it sent none (a request it could
+ * not read, a start that failed), the failure its code is evidence of at `phase`.
+ */
+function errorFromHost(error, stderr, phase) {
+    const failure = error.failure === undefined
+        ? undefined
+        : {
+            ...error.failure,
+            message: error.message,
+            stderr,
+        };
+    if (error.code === "GPU_INIT_FAILED")
+        return new Alpha2GpuInitializationError(error.message, {
+            failure,
+            stderr,
+            phase,
+        });
+    if (error.code === "CONFORM_FAILED" && error.details !== undefined)
+        return new Alpha2ConformError(error.message, error.details, { failure, stderr, phase });
+    return new Alpha2HostError(error.code, error.message, {
+        failure,
+        stderr,
+        phase,
+    });
+}
+function proxiesPayload(proxies) {
+    return Object.fromEntries(Object.entries(proxies ?? {}).map(([id, files]) => [
+        id,
+        files.map((file) => ({
+            path: file.path,
+            ...(file.madeFrom === undefined ? {} : { madeFrom: file.madeFrom }),
+            ...(file.colorPipeline === undefined
+                ? {}
+                : { colorPipeline: file.colorPipeline }),
+        })),
+    ]));
+}
+function asarUnpacked(path) {
+    return path.replace(/([\\/])app\.asar([\\/])/, "$1app.asar.unpacked$2");
+}
+function isFile(path) {
+    try {
+        return existsSync(path) && statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The last at most `limit` bytes of `bytes` as text, from the first whole character: a byte bound,
+ * as {@link STDERR_TAIL_BYTES} says, for text that is not ASCII too.
+ */
+function utf8Tail(bytes, limit) {
+    let start = Math.max(0, bytes.length - limit);
+    // A continuation byte (10xxxxxx) is the middle of a character.
+    while (start < bytes.length && ((bytes[start] ?? 0) & 0xc0) === 0x80)
+        start += 1;
+    const text = bytes.subarray(start).toString("utf8");
+    // A byte that is not UTF-8 becomes U+FFFD, three bytes: drop characters from the front to fit.
+    let excess = Buffer.byteLength(text) - limit;
+    let index = 0;
+    while (excess > 0 && index < text.length) {
+        const point = text.codePointAt(index) ?? 0;
+        excess -= Buffer.byteLength(String.fromCodePoint(point));
+        index += point > 0xffff ? 2 : 1;
+    }
+    return text.slice(index);
+}
+const HOST_SHUTDOWN_TIMEOUT_MS = 5_000;
+/** The longest request line the host reads (`MAX_REQUEST_LINE_BYTES`), newline excluded. */
+const MAX_REQUEST_LINE_BYTES = 2 * MAX_PROJECT_JSON_BYTES;
+/** The `requestId` the host answers a line with when it could not read the line's own. */
+const UNREAD_REQUEST_ID = "unknown";
+class Semaphore {
+    #available;
+    #waiting = [];
+    constructor(limit) {
+        this.#available = limit;
+    }
+    acquire(signal) {
+        if (signal?.aborted)
+            return Promise.reject(new Alpha2AbortError());
+        if (this.#available > 0) {
+            this.#available -= 1;
+            return Promise.resolve(this.#release());
+        }
+        return new Promise((resolveWaiter, reject) => {
+            const waiter = {
+                resolve: resolveWaiter,
+                reject,
+                signal,
+                abort: undefined,
+            };
+            const abort = () => {
+                const index = this.#waiting.indexOf(waiter);
+                if (index >= 0)
+                    this.#waiting.splice(index, 1);
+                reject(new Alpha2AbortError());
+            };
+            waiter.abort = abort;
+            this.#waiting.push(waiter);
+            signal?.addEventListener("abort", abort, { once: true });
+            if (signal?.aborted)
+                abort();
+        });
+    }
+    #release() {
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            const waiter = this.#waiting.shift();
+            if (waiter) {
+                if (waiter.abort)
+                    waiter.signal?.removeEventListener("abort", waiter.abort);
+                waiter.resolve(this.#release());
+            }
+            else {
+                this.#available += 1;
+            }
+        };
+    }
+}
+let nextRequestSequence = 0;