@alpha2-sh/editor 0.0.0-stage → 0.1.0

package/dist/browser/worker.js

@@ -0,0 +1,239 @@
+import { SourcePixels } from "./runtime/sources.js";
+import { AudioWindowSupplier, mixBlock } from "./runtime/audio.js";
+/**
+ * Serves the editor's preview protocol (`createWorkerPreview`) on `scope`, a dedicated worker's
+ * global. Importing this module has no effect until this is called. Requests run one at a
+ * time in arrival order. A `cancel` or `replace-project` stops the render in flight and drops the
+ * seeks that arrived before it, not those sent after it. Requests from another session or an
+ * older revision are answered with an error.
+ * @param {import("./types.js").EditorWorkerScope} scope
+ * @returns {{ dispose(): Promise<void> }} Waits for queued requests, releases the engine and
+ *   decoders, and detaches the message handler.
+ */
+export function installEditorWorker(scope) {
+    let engine = null, pixels = null, audio = null, sessionId = null, bitmapOutput = false, currentProject = null, revision = -1, tail = Promise.resolve();
+    const assets = new Map(), library = { get: (id) => assets.get(id) };
+    const context = () => ({
+        width: engine.project.settings.width,
+        height: engine.project.settings.height,
+        liveSourceIds: new Set(engine.project.sources.map((s) => s.id)),
+        getLayer: (id) => {
+            const asset = library.get(id);
+            return asset?.kind === "text" ? { id, kind: "image", asset } : asset;
+        },
+    });
+    // Counts cancels and project replacements. A request remembers the count on arrival, so work
+    // queued before a cancel or replacement is dropped however long it waited.
+    let epoch = 0;
+    scope.onmessage = ({ data: request }) => {
+        if (request.type === "cancel" || request.type === "replace-project") {
+            epoch += 1;
+            // The render in flight is for what this replaces: it stops.
+            engine?.invalidate();
+        }
+        const arrived = epoch;
+        tail = tail.then(async () => {
+            const { requestId, type } = request;
+            const response = {
+                sessionId: request.sessionId,
+                revision: request.revision,
+                requestId,
+            };
+            try {
+                if (type === "init") {
+                    if (engine)
+                        throw Error("Worker already initialized");
+                    sessionId = request.sessionId;
+                    bitmapOutput = request.bitmapOutput === true;
+                    pixels = new SourcePixels(library, {
+                        extensionsWasmUrl: request.runtimeAssets?.extensionsWasmUrl,
+                    });
+                    const { Engine } = await import("./runtime/engine.js");
+                    engine = new Engine(request.canvas ??
+                        new OffscreenCanvas(request.width ?? 16, request.height ?? 16), pixels, library, request.runtimeAssets);
+                    audio = new AudioWindowSupplier(library);
+                    await engine.start();
+                }
+                else {
+                    if (!engine || request.sessionId !== sessionId)
+                        throw Error("Stale worker session");
+                    if (request.revision < revision)
+                        throw Error("Stale worker revision");
+                    if (type === "replace-project") {
+                        // What the previous project sent and still uses stays, decoders included.
+                        const keep = new Set(request.keep ?? []);
+                        for (const id of [...assets.keys()])
+                            if (!keep.has(id))
+                                assets.delete(id);
+                        await pixels.release(keep);
+                        for (const asset of request.assets ?? [])
+                            assets.set(asset.id, asset);
+                        if (request.fonts)
+                            engine.setCaptionFonts(request.fonts);
+                        currentProject = request.project;
+                        if (currentProject.timeline.tracks.some((track) => (track.clips?.length ?? 0) +
+                            (track.captions?.cues.length ?? 0)))
+                            engine.loadProject(request.project);
+                        engine.resize(request.project.settings.width, request.project.settings.height);
+                        pixels.setOutputSize(request.project.settings.width, request.project.settings.height);
+                        audio.configure(engine.audioEngine, request.project);
+                        revision = request.revision;
+                    }
+                    else if (type === "seek") {
+                        const generation = engine.generation;
+                        const rendered = arrived !== epoch ||
+                            !currentProject?.timeline.tracks.some((track) => (track.clips?.length ?? 0) +
+                                (track.captions?.cues.length ?? 0))
+                            ? false
+                            : await engine.render(request.tick / 120000, {
+                                generation,
+                                context: context(),
+                            });
+                        const bitmap = rendered && bitmapOutput
+                            ? engine.canvas.transferToImageBitmap()
+                            : null;
+                        scope.postMessage({
+                            ...response,
+                            ok: true,
+                            value: {
+                                rendered,
+                                diagnostics: pixels.diagnostics,
+                                ...(bitmap ? { bitmap } : {}),
+                            },
+                        }, bitmap ? [bitmap] : []);
+                        return;
+                    }
+                    else if (type === "audio-mix") {
+                        await audio.supply(request.startSample, request.frames);
+                        const planes = mixBlock(engine.audioEngine, request.startSample, request.frames, false);
+                        const owned = planes.map((p) => p.slice());
+                        scope.postMessage({ ...response, ok: true, value: owned }, owned.map((p) => p.buffer));
+                        return;
+                    }
+                    else if (type === "resize")
+                        engine.resize(request.width, request.height);
+                    else if (type === "register-fonts")
+                        engine.setCaptionFonts(request.fonts);
+                    else if (type === "dispose") {
+                        await audio.close();
+                        await engine.dispose();
+                        await pixels.dispose();
+                        assets.clear();
+                        engine = null;
+                    }
+                    else if (type !== "cancel")
+                        throw Error(`Unknown editor worker request ${type}`);
+                }
+                scope.postMessage({ ...response, ok: true });
+            }
+            catch (error) {
+                scope.postMessage({
+                    ...response,
+                    ok: false,
+                    error: {
+                        code: error.code ?? "worker_error",
+                        message: error.message ?? String(error),
+                    },
+                });
+            }
+        });
+    };
+    return {
+        async dispose() {
+            await tail;
+            await audio?.close();
+            await engine?.dispose();
+            await pixels?.dispose();
+            assets.clear();
+            scope.onmessage = null;
+        },
+    };
+}
+/**
+ * Drives a preview renderer in `worker`, which must run `installEditorWorker`. The caller owns
+ * the worker; `dispose()` terminates it. This port renders picture and mixes audio blocks only:
+ * it is separate from a bridge's main-thread audio output. Every call waits for `ready`, which
+ * rejects if the worker cannot start its engine; a disposed preview rejects new calls, and a
+ * worker error rejects every pending one.
+ * @param {Worker} worker
+ * @param {import("./types.js").WorkerPreviewOptions} [options]
+ * @returns {import("./types.js").WorkerPreview}
+ */
+export function createWorkerPreview(worker, { sessionId = crypto.randomUUID(), runtimeAssets = {}, canvas, bitmapOutput = false, width = 16, height = 16, } = {}) {
+    let nextId = 0, revision = 0, disposed = false;
+    const pending = new Map();
+    const rejectAll = (error) => {
+        for (const waiter of pending.values())
+            waiter.reject(error);
+        pending.clear();
+    };
+    worker.onmessage = ({ data }) => {
+        if (data.sessionId !== sessionId) {
+            data.value?.bitmap?.close();
+            return;
+        }
+        const waiter = pending.get(data.requestId);
+        if (!waiter) {
+            data.value?.bitmap?.close();
+            return;
+        }
+        pending.delete(data.requestId);
+        if (data.ok)
+            waiter.resolve(data.value);
+        else
+            waiter.reject(Object.assign(new Error(data.error.message), { code: data.error.code }));
+    };
+    worker.onerror = (event) => rejectAll(new Error(event.message));
+    const call = (type, body = {}, transfer = []) => {
+        if (disposed)
+            return Promise.reject(new Error("Worker preview disposed"));
+        const requestId = ++nextId;
+        return new Promise((resolve, reject) => {
+            pending.set(requestId, { resolve, reject });
+            try {
+                worker.postMessage({ type, sessionId, revision, requestId, ...body }, transfer);
+            }
+            catch (error) {
+                pending.delete(requestId);
+                reject(error);
+            }
+        });
+    };
+    const ready = call("init", {
+        runtimeAssets,
+        bitmapOutput,
+        width,
+        height,
+        ...(canvas ? { canvas } : {}),
+    }, canvas ? [canvas] : []);
+    return {
+        ready,
+        async replaceProject(project, nextRevision, assets = [], fonts = [], keep = []) {
+            await ready;
+            revision = nextRevision;
+            return call("replace-project", { project, assets, fonts, keep });
+        },
+        async seek(tick) {
+            await ready;
+            return call("seek", { tick });
+        },
+        async mix(startSample, frames) {
+            await ready;
+            return call("audio-mix", { startSample, frames });
+        },
+        cancel: () => call("cancel"),
+        async dispose() {
+            if (disposed)
+                return;
+            try {
+                await ready;
+                await call("dispose");
+            }
+            finally {
+                disposed = true;
+                worker.terminate();
+                rejectAll(new Error("Worker disposed"));
+            }
+        },
+    };
+}

package/dist/core/captions.d.ts

@@ -0,0 +1,34 @@
+import type { CaptionCue, TextStyle } from "alpha2/project";
+import type { AssetDescriptor, Json } from "./document.js";
+import type { Command } from "./commands.js";
+/** The bin asset kind a subtitle file (SRT or WebVTT) imports as. */
+export declare const CAPTIONS_ASSET_KIND = "captions";
+/**
+ * A subtitle file in the bin: its cues split into rows, none overlapping another in its row, as
+ * `parseCaptions` reads them. The cues travel in the asset's authoring data, so the asset needs no
+ * file to stay online and saves with the document. Inserting it adds one caption track per row.
+ */
+export declare function captionsAsset(id: string, name: string, rows: readonly (readonly CaptionCue[])[]): AssetDescriptor;
+/**
+ * Whether a captions asset's authoring data is the cue rows {@link captionsAsset} writes;
+ * `validateDocument` refuses a captions asset with anything else.
+ */
+export declare function validCaptionsAuthoring(authoring: Json | undefined): boolean;
+/** A captions asset's cue rows; empty for any other asset or malformed authoring data. */
+export declare function captionRows(asset: AssetDescriptor | undefined): readonly (readonly CaptionCue[])[];
+/** Where a captions asset's last cue ends, in ticks from its start. */
+export declare function captionsDuration(asset: AssetDescriptor | undefined): number;
+/**
+ * The commands that put a captions asset on the timeline: a new caption track for each of its rows,
+ * with every cue moved `at` ticks later, in `style` when given. Track IDs come from `newId`,
+ * `crypto.randomUUID` by default.
+ *
+ * Throws when the asset has no cues.
+ */
+export declare function captionTrackCommands(asset: AssetDescriptor, at: number, options?: {
+    newId?: () => string;
+    style?: TextStyle;
+}): {
+    trackIds: string[];
+    commands: Command[];
+};

package/dist/core/captions.js

@@ -0,0 +1,108 @@
+/** The bin asset kind a subtitle file (SRT or WebVTT) imports as. */
+export const CAPTIONS_ASSET_KIND = "captions";
+/**
+ * A subtitle file in the bin: its cues split into rows, none overlapping another in its row, as
+ * `parseCaptions` reads them. The cues travel in the asset's authoring data, so the asset needs no
+ * file to stay online and saves with the document. Inserting it adds one caption track per row.
+ */
+export function captionsAsset(id, name, rows) {
+    return {
+        id,
+        kind: CAPTIONS_ASSET_KIND,
+        name,
+        contentRevision: 0,
+        authoring: { captions: { rows } },
+    };
+}
+/**
+ * Whether `value` is a cue as a captions asset keeps it: text, and a non-empty range of safe
+ * integer ticks from the asset's start.
+ */
+function isCaptionCue(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const { text, timeline_range: range } = value;
+    if (typeof range !== "object" || range === null)
+        return false;
+    const { start, end } = range;
+    return (typeof text === "string" &&
+        Number.isSafeInteger(start) &&
+        Number.isSafeInteger(end) &&
+        start >= 0 &&
+        start < end);
+}
+/**
+ * The cue rows a captions asset's authoring data holds, or `undefined` when it holds anything else:
+ * `{ captions: { rows } }`, each row a list of cues.
+ */
+function rowsOf(authoring) {
+    const captions = typeof authoring === "object" &&
+        authoring !== null &&
+        !Array.isArray(authoring)
+        ? authoring.captions
+        : undefined;
+    const rows = typeof captions === "object" && captions !== null
+        ? captions.rows
+        : undefined;
+    if (!Array.isArray(rows) ||
+        !rows.every((row) => Array.isArray(row) && row.every(isCaptionCue)))
+        return undefined;
+    return rows;
+}
+/**
+ * Whether a captions asset's authoring data is the cue rows {@link captionsAsset} writes;
+ * `validateDocument` refuses a captions asset with anything else.
+ */
+export function validCaptionsAuthoring(authoring) {
+    return rowsOf(authoring) !== undefined;
+}
+/** A captions asset's cue rows; empty for any other asset or malformed authoring data. */
+export function captionRows(asset) {
+    if (asset?.kind !== CAPTIONS_ASSET_KIND)
+        return [];
+    return rowsOf(asset.authoring) ?? [];
+}
+/** Where a captions asset's last cue ends, in ticks from its start. */
+export function captionsDuration(asset) {
+    let end = 0;
+    for (const row of captionRows(asset))
+        for (const cue of row)
+            end = Math.max(end, cue.timeline_range.end);
+    return end;
+}
+/**
+ * The commands that put a captions asset on the timeline: a new caption track for each of its rows,
+ * with every cue moved `at` ticks later, in `style` when given. Track IDs come from `newId`,
+ * `crypto.randomUUID` by default.
+ *
+ * Throws when the asset has no cues.
+ */
+export function captionTrackCommands(asset, at, options = {}) {
+    const rows = captionRows(asset).filter((row) => row.length > 0);
+    if (!rows.length)
+        throw Error(`${asset.name} has no captions to insert.`);
+    const newId = options.newId ?? (() => crypto.randomUUID());
+    const base = asset.name.replace(/\.(srt|vtt)$/i, "");
+    const trackIds = [];
+    const commands = rows.map((row, i) => {
+        const track = {
+            id: newId(),
+            name: rows.length > 1 ? `${base} ${i + 1}` : base,
+            kind: "caption",
+            clips: [],
+            captions: {
+                ...(options.style ? { style: options.style } : {}),
+                cues: row.map((cue) => ({
+                    ...cue,
+                    timeline_range: {
+                        start: cue.timeline_range.start + at,
+                        end: cue.timeline_range.end + at,
+                    },
+                })),
+            },
+        };
+        trackIds.push(track.id);
+        return { type: "track.add", track };
+    });
+    return { trackIds, commands };
+}

package/dist/core/clip-time.d.ts

@@ -0,0 +1,31 @@
+import type { Clip } from "alpha2/project";
+/** A frame rate as the document holds it. */
+export interface FrameRateValue {
+    readonly num: number;
+    readonly den: number;
+}
+/**
+ * The source instant `clip`'s picture shows at timeline tick `tick`, as the engine draws it
+ * (`picture_source_time` in alpha2-eval). With `e` the ticks since the clip starts, `T` its
+ * timeline length, `S` its source length, and `F` one frame at `frameRate`:
+ *
+ * - forward: `floor(e*S/T)` past the source start;
+ * - reverse: the forward instant at the start of the mirrored project frame, less the time into the
+ *   frame, so a reversed clip shows the forward clip's frames in the opposite order, each at the
+ *   instant the forward clip shows it, at any rate and wherever the clip starts and ends (the
+ *   source start where that falls before it);
+ * - freeze: its instant;
+ * - a repeating loop: `e mod S` past the source start;
+ * - a ping-pong loop: the same on even passes, and on odd ones the pass mirrored by frame in the
+ *   same way.
+ *
+ * A clip with an empty range reads its source start.
+ */
+export declare function clipSourceTime(clip: Clip, tick: number, frameRate: FrameRateValue): number;
+/**
+ * The first timeline tick at which `clip`'s picture shows source time `time` (rounded up to a
+ * tick), or where it never shows exactly that, the first that shows it passed in the direction of
+ * play: the inverse of {@link clipSourceTime} on a clip's first pass. A freeze shows its instant
+ * from its start.
+ */
+export declare function clipTimelineTime(clip: Clip, time: number, frameRate: FrameRateValue): number;

package/dist/core/clip-time.js

@@ -0,0 +1,125 @@
+import { TICKS_PER_SECOND } from "alpha2/project";
+/**
+ * The source instant `clip`'s picture shows at timeline tick `tick`, as the engine draws it
+ * (`picture_source_time` in alpha2-eval). With `e` the ticks since the clip starts, `T` its
+ * timeline length, `S` its source length, and `F` one frame at `frameRate`:
+ *
+ * - forward: `floor(e*S/T)` past the source start;
+ * - reverse: the forward instant at the start of the mirrored project frame, less the time into the
+ *   frame, so a reversed clip shows the forward clip's frames in the opposite order, each at the
+ *   instant the forward clip shows it, at any rate and wherever the clip starts and ends (the
+ *   source start where that falls before it);
+ * - freeze: its instant;
+ * - a repeating loop: `e mod S` past the source start;
+ * - a ping-pong loop: the same on even passes, and on odd ones the pass mirrored by frame in the
+ *   same way.
+ *
+ * A clip with an empty range reads its source start.
+ */
+export function clipSourceTime(clip, tick, frameRate) {
+    const { timeline, source, span, length, per, frame } = parts(clip, frameRate);
+    const map = clip.time_map ?? { type: "forward" };
+    if (map.type === "freeze")
+        return map.source_time;
+    if (span <= 0n || length <= 0n)
+        return Number(source);
+    const elapsed = BigInt(Math.floor(tick)) - timeline;
+    let offset;
+    if (map.type === "reverse")
+        offset = mirrored(timeline, length, elapsed, span, frame, per);
+    else if (map.type === "loop") {
+        const within = euclid(elapsed, span);
+        const pass = floorDiv(elapsed, span);
+        offset =
+            map.mode === "ping_pong" && euclid(pass, 2n) === 1n
+                ? mirrored(timeline + pass * span, span, within, span, frame, per)
+                : within;
+    }
+    else
+        offset = floorDiv(elapsed * span, length);
+    return Number(source + offset);
+}
+/**
+ * The first timeline tick at which `clip`'s picture shows source time `time` (rounded up to a
+ * tick), or where it never shows exactly that, the first that shows it passed in the direction of
+ * play: the inverse of {@link clipSourceTime} on a clip's first pass. A freeze shows its instant
+ * from its start.
+ */
+export function clipTimelineTime(clip, time, frameRate) {
+    const { timeline, source, span, length, per, frame } = parts(clip, frameRate);
+    const map = clip.time_map ?? { type: "forward" };
+    if (map.type === "freeze" || span <= 0n || length <= 0n)
+        return Number(timeline);
+    const k = BigInt(Math.ceil(time)) - source;
+    let elapsed;
+    if (map.type === "loop")
+        elapsed = k;
+    else if (map.type === "reverse") {
+        // The mirrored instant never rises with `e`: binary-search the first `e` showing `k` or earlier.
+        let low = 0n;
+        let high = length;
+        while (low < high) {
+            const middle = (low + high) / 2n;
+            if (mirrored(timeline, length, middle, span, frame, per) <= k)
+                high = middle;
+            else
+                low = middle + 1n;
+        }
+        elapsed = low;
+    }
+    else
+        elapsed = ceilDiv(k * length, span);
+    return Number(timeline + elapsed);
+}
+function parts(clip, frameRate) {
+    const timeline = BigInt(clip.timeline_range.start);
+    const source = BigInt(clip.source_range.start);
+    return {
+        timeline,
+        source,
+        length: BigInt(clip.timeline_range.end) - timeline,
+        span: BigInt(clip.source_range.end) - source,
+        frame: BigInt(TICKS_PER_SECOND) * BigInt(frameRate.den),
+        per: BigInt(frameRate.num),
+    };
+}
+/**
+ * The forward offset `floor(e' * scale / length)` the mirror of `elapsed` shows within `length`
+ * ticks from timeline tick `start`, by project frames of `frame / per` ticks (alpha2-eval's
+ * `Mirror::offset`): with `k0` and `k1` the first and last frames starting inside and `k` the one
+ * containing the instant (`k0` before it, with no time into it), `e'` is the start of `k0 + k1 - k`
+ * less the time into `k`, from `start`, or zero where that falls before it. A window no frame
+ * starts in shows its start.
+ */
+function mirrored(start, length, elapsed, scale, frame, per) {
+    const startOf = (k) => floorDiv(k * frame, per);
+    const frameOf = (tick) => floorDiv((tick + 1n) * per - 1n, frame);
+    const first = frameOf(start - 1n) + 1n;
+    const last = frameOf(start + length - 1n);
+    if (first > last)
+        return 0n;
+    const tick = start + elapsed;
+    let k = frameOf(tick);
+    let into = 0n;
+    if (k < first)
+        k = first;
+    else
+        into = tick - startOf(k);
+    const position = startOf(first + last - k) - into - start;
+    if (position <= 0n)
+        return 0n;
+    return floorDiv(position * scale, length);
+}
+function floorDiv(value, divisor) {
+    const quotient = value / divisor;
+    return value % divisor !== 0n && value < 0n !== divisor < 0n
+        ? quotient - 1n
+        : quotient;
+}
+function ceilDiv(value, divisor) {
+    return -floorDiv(-value, divisor);
+}
+function euclid(value, divisor) {
+    const remainder = value % divisor;
+    return remainder < 0n ? remainder + divisor : remainder;
+}