Skip to content

The VS Code of video editing, built for agents.

TypeScript
7.8 KB
Raw Blame
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

/**
 * The world an encode runs against: the project rendered a second time, into
 * a world of its own, reduced to the one node being encoded.
 *
 * Rendered rather than copied, because a copy of the entities is only what
 * the composition holds as data — a `<surface>`'s drawing, an `<html>`
 * subtree and every value a `useTicker` memo feeds live in the node the
 * project's render made, and the offline world has to have its own. So the
 * bundle that is on the canvas is mounted again here, against an offline
 * world at the export's frame rate, and the encoder is handed the result.
 *
 * The whole project renders, not the one scene: a scene is not a project, and
 * what each of them holds is only known by running the whole thing. The stage
 * is reduced to the scene straight after, before a system has looked at any
 * of it, so nothing outside it is ever drawn, decoded, mixed or advanced, nor
 * is any `src` of it resolved.
 */

import { mount } from '@diffusionstudio/reconciler';
import {
	ChildOf, FramePromises, FrameRate, Fonts, Hidden, Library, Mode, Project,
	RenderSurface, Root, Source,
	createRuntimeWorld, disposeDecoders, getParentNode, removeChild, resetCamera,
} from '@diffusionstudio/runtime';

import { loadProjectBundle } from '@/lib/db';
import { compileProject, isDesktop } from '@/projects';

import type { RuntimeMode } from '@diffusionstudio/runtime';
import type { Entity, World } from 'koota';

export interface CaptureOptions {
	/** Frames per second the copy is timed at; the source world's by default. */
	frameRate?: number;
	/** What is being encoded. Audio-only skips nothing, it just draws nothing. */
	mode?: RuntimeMode;
	/** The project's folder, to compile it fresh; the remembered bundle otherwise. */
	dir?: string;
}

/**
 * The code an encode mounts. Compiled fresh when the project's folder is
 * known: an element the editor inserted reaches the file without a recompile
 * (its own writes are kept from the watcher), so the bundle the last mount
 * remembered may predate it — and an encode of it would come up empty. The
 * remembered bundle answers off the desktop, where there is no compiler.
 */
async function bundleFor(source: World, dir?: string): Promise<string> {
	if (dir && isDesktop()) {
		const result = await compileProject(dir);
		if (!result.ok) throw new Error(result.error);
		return result.code;
	}

	const code = await loadProjectBundle(source.get(Project)?.id ?? '');
	if (!code) throw new Error('There is no project to render');
	return code;
}

export interface Capture {
	/** The world to hand to an encoder. */
	world: World;
	/** The node in it — the stage's only child. */
	node: Entity;
	/** Drops the render, the canvas, the decoders it opened, and the world. */
	dispose(): void;
}

/**
 * Builds the capture world for an encode of `node`, an entity of `source` —
 * the editor's world. A scene, for a render of the composition; any node for
 * an image capture of it alone. Throws when there is no project to render (or
 * it no longer compiles), when the node has no source stamp yet (an element
 * the writer has not put in the file), or when rendering the project produces
 * nothing for that stamp.
 */
export async function createCapture(source: World, node: Entity, options: CaptureOptions = {}): Promise<Capture> {
	const code = await bundleFor(source, options.dir);

	// The stamp, not the entity: the two worlds hand out ids of their own, and
	// the stamp is the same element in both.
	const stamp = node.get(Source)?.value;
	if (!stamp) {
		throw new Error('This element is not in the project source yet — save the project and try again.');
	}

	const mode = options.mode ?? 'offline-video';
	const frameRate = options.frameRate ?? source.get(FrameRate)?.value ?? 30;

	// Created before the world is filled: the DOM-backed paints (`<html>`,
	// `<htmlPaint>`) attach their layout roots to it as their element is made.
	// The encoder sizes it once it knows how big the picture is. It sits inside
	// the viewport, behind the app, not parked off-screen: the browser only
	// paints layout near the viewport, and drawElementImage draws from that
	// cached paint — on a canvas at left:-100000px (or below the fold) it
	// throws "no cached paint record" and every HTML paint captures blank.
	// Only the canvas's origin has to intersect the viewport, not its whole
	// box: a `layoutsubtree` child is paint-contained and records in full, so a
	// 4K canvas in a small window still captures its far corner.
	// `opacity:0` alone would not do — Blink skips painting a subtree under its
	// minimum visible opacity (0.0004) — but `will-change:opacity` keeps the
	// effect node composited, so the subtree is painted at opacity 0 all the
	// same and nothing shows through translucent UI above it. Canvas opacity is
	// not baked into what drawElementImage yields.
	const canvas = document.createElement('canvas');
	canvas.width = 2;
	canvas.height = 2;
	canvas.style.cssText = 'position:fixed;left:0;top:0;z-index:-9999;opacity:0;will-change:opacity;pointer-events:none;';
	document.body.appendChild(canvas);

	// Shares the source's assets — a `src` names the same file in both — and
	// its fonts, which are loaded into the document
	// already, so copying the list only tracks them as loaded rather than
	// having this world add them again.
	const world = createRuntimeWorld(source.get(Project)?.id ?? '');
	world.set(Mode, { value: mode });
	world.set(Library, source.get(Library) ?? null);
	world.set(Fonts, { list: [...(source.get(Fonts)?.list ?? [])] });
	world.set(RenderSurface, { canvas, ctx: canvas.getContext('2d'), resolution: 1 });
	world.set(FrameRate, { value: frameRate });
	// The barrier offline capture awaits: the systems push decoder and source
	// readiness here and the encoder drains it before sampling a frame.
	world.set(FramePromises, { list: [] });

	const dispose = (mounted?: { dispose(): void }) => () => {
		mounted?.dispose();
		canvas.remove();
		// Release the decoder file handles and caches, then the world slot
		// itself: koota caps live worlds at 16, so a throwaway one has to be
		// destroyed rather than dropped.
		disposeDecoders(world, world.get(Root)!);
		world.destroy();
	};

	let mounted: { dispose(): void };
	try {
		// The frame rate is set above, so every authored time lands in this
		// world's frames as the document converts it — nothing to rescale.
		mounted = mount(code, world);
	} catch (error) {
		dispose()();
		throw error;
	}

	const rendered = world.query(Source).find((entity) => entity.get(Source)?.value === stamp);

	if (!rendered) {
		dispose(mounted)();
		throw new Error(`The project rendered nothing for "${stamp}"`);
	}

	// A node from inside a scene becomes the whole world, so it goes to the
	// top and whatever kept it from being seen in there no longer applies —
	// it is what was asked for. A scene is already a root and keeps both.
	if (getParentNode(rendered) !== null) {
		removeChild(world, rendered, getParentNode(rendered)!);
		rendered.remove(Hidden);
	}

	// Down to the one node. Destroying a root takes its subtree with it
	// (ChildOf is autoDestroy 'orphan'); what those nodes held outside the
	// world — an `<html>` root parked on the canvas, a `<surface>`'s own
	// canvas — is unreachable from here and goes when the canvas does.
	for (const root of world.query(ChildOf(world.get(Root)!))) {
		if (root !== rendered) root.destroy();
	}

	// The project may have spelled `<stage camera={…}>`, which is where the
	// editor was last looking — no part of the composition, and the view an
	// encode draws with is the plain one.
	resetCamera(world);

	return { world, node: rendered, dispose: dispose(mounted) };
}