Skip to content

Code-first video & image, rendered natively on WebGPU.

11.9 KB
Raw Blame
/**
 * Relay, a 25-second product film: a client asks "Can we ship the homepage
 * update Friday?", and one pointer turns the message into an assigned,
 * scheduled task that lands on the project board.
 *
 *   0–3 s   the request, under "From request to ready."; it flies into the inbox
 *   3–8 s   select the message, Create task: the task modal opens
 *   8–14 s  Maya, Friday, a checklist: "An owner. A deadline. A clear next step."
 *  14–20 s  back out to the board: the modal shrinks into its card in Ready
 *  20–25 s  the card becomes the mark: Relay. Keep client work moving.
 *
 * AppFrame is the window, MousePointer the hand, FocusZoom the camera (added
 * with `framefields add app-frame mouse-pointer focus-zoom`). The UI reacts
 * to the pointer's cues, so moving a beat re-times everything after it, the
 * narration included. Voice, music and click are generated (audio.ts).
 */
import { Composition, FontManager, Layer, LayerAnimation } from "framefields";
import {
	CLICK_PATH,
	LINE_IDS,
	type LineId,
	MUSIC_PATH,
	readManifest,
	voicePath,
} from "./audio.js";
import { backdrop } from "./backdrop.js";
import { AppFrame } from "./components/app-frame/index.js";
import { FocusZoom } from "./components/focus-zoom/index.js";
import {
	MousePointer,
	type Waypoint,
} from "./components/mouse-pointer/index.js";
import { SFX, type SfxName, sfxPath } from "./sfx.js";
import {
	ACCENT,
	APP,
	FONTS,
	FPS,
	FRAME,
	H,
	SANS,
	SHADOW,
	sec,
	W,
	WALL,
} from "./theme.js";
import { captions, endCard, handover, opening } from "./titles.js";
import { relayApp } from "./ui/app.js";
import { DUE_OPTIONS, FRIDAY, TEAM } from "./ui/data.js";
import { CARD_RADIUS } from "./ui/handoffs.js";
import { centre, type Rect } from "./ui/kit.js";
import {
	ADD_CHECKLIST,
	ASSIGNEE_FIELD,
	COLUMN_W,
	CREATE_BUTTON,
	cardSlot,
	columnX,
	DUE_FIELD,
	inModal,
	LIST_TOP,
	LIST_X,
	MODAL,
	menuUnder,
	optionIn,
	PANE_W,
	PANE_X,
	READY,
	REQUEST_ROW,
	SAVE_BUTTON,
} from "./ui/layout.js";
import {
	type Click,
	cardLands,
	checklistItemAt,
	modalIn,
	type Timeline,
} from "./ui/timeline.js";

/** The storyboard's fixed marks. */
const WINDOW_IN = sec(2.1);
const FLY = sec(2.6);
const LANDED = sec(3.45);
const POINTER_IN = sec(3.2);
const END_CARD = sec(20);
/** The card leaves the board for the end card. */
const SCENE_OUT = END_CARD - sec(0.8);
const END = sec(25);

/**
 * MousePointer's click, at 30 fps: it settles 4 frames after arriving,
 * presses for 3 (the click lands) and is fully released 7 frames later.
 */
const CLICK_LANDS = 7;
const RELEASED = 14;

interface Beat {
	to: [number, number];
	/** Composition frame the click lands (or the pointer arrives, for a rest). */
	at: number;
	/** Frames on the way from the previous beat (the first comes in from the edge). */
	travel?: number;
	click?: boolean;
	/** Frames to rest after the last beat. */
	rest?: number;
}

/** Waypoints that leave each beat in time to make the next one. */
function perform(enter: number, beats: Beat[]): Waypoint[] {
	const arrival = (b: Beat) => b.at - (b.click ? CLICK_LANDS : 0);
	return beats.map((b, i) => {
		const next = beats[i + 1];
		const free = arrival(b) + (b.click ? RELEASED - CLICK_LANDS : 0);
		const dwell = next
			? arrival(next) - (next.travel ?? 0) - free
			: (b.rest ?? 0);
		if (dwell < 0)
			throw new Error(
				`Beat ${i + 1} cannot leave in time for beat ${i + 2}: ${-dwell} frames short.`,
			);
		return {
			to: b.to,
			at: arrival(b) - enter,
			dwell,
			...(b.click && { click: true }),
		};
	});
}

const clickAt = (
	cues: {
		presses: ReadonlyArray<{ frame: number }>;
		clicks: ReadonlyArray<{ frame: number }>;
		releases: ReadonlyArray<{ frame: number }>;
	},
	i: number,
): Click => ({
	down: cues.presses[i]?.frame ?? 0,
	at: cues.clicks[i]?.frame ?? 0,
	up: cues.releases[i]?.frame ?? 0,
});

function sound(file: string, frame: number, seconds: number, volume: number) {
	return Layer.audio(file, {
		startFrame: frame,
		durationFrames: Math.ceil(seconds * FPS) + 2,
		volume,
	});
}

const cue = (name: SfxName, frame: number, volume: number) =>
	sound(sfxPath(name), frame, SFX[name].seconds, volume);

/** Where each line of narration starts: on the beat it describes. */
function lineStarts(t: Timeline): Record<LineId, number> {
	return {
		ask: sec(0.5),
		inbox: LANDED - 2,
		owner: t.maya.at + 2,
		deadline: t.friday.at + 2,
		step: checklistItemAt(t, 0),
		board: cardLands(t) + 4,
		close: END_CARD + sec(0.7),
	};
}

export interface Line {
	id: LineId;
	start: number;
	end: number;
}

/** Music level between lines, and under them. */
const BED = 0.5;
const DUCKED = 0.22;
/** Lines closer than this keep the music down between them. */
const BRIDGE = 18;

/** The music's volume: down under every line, and out by the end. */
function ducking(lines: Line[]): Array<[number, number, string?]> {
	const keys: Array<[number, number, string?]> = [
		[0, 0],
		[6, BED, "power2.out"],
	];
	let i = 0;
	while (i < lines.length) {
		const start = lines[i]?.start ?? 0;
		let end = lines[i]?.end ?? 0;
		while (i + 1 < lines.length && (lines[i + 1]?.start ?? 0) - end < BRIDGE)
			end = lines[++i]?.end ?? end;
		keys.push(
			[start - 6, BED, "hold"],
			[start, DUCKED, "power2.out"],
			[end, DUCKED, "hold"],
			[end + 12, BED, "power2.inOut"],
		);
		i++;
	}
	keys.push([END - sec(1.6), BED, "hold"], [END, 0, "power2.in"]);
	return keys;
}

export interface Relay {
	film: Composition;
	timeline: Timeline;
	/** The camera, for asking where it looks at a frame. */
	camera: ReturnType<typeof FocusZoom>;
	/** Every click, in composition frames. */
	clicks: number[];
	/** The narration, in composition frames. */
	lines: Line[];
}

export async function buildRelay(): Promise<Relay> {
	await FontManager.register({ family: SANS, source: `${FONTS}Inter.ttf` });
	const theme = { color: { bg: WALL, accent: ACCENT, shadow: SHADOW } };

	const frame = AppFrame({
		id: "relay-window",
		kind: "window",
		...FRAME,
		appearance: "light",
		contentBackground: APP,
		elevation: 2,
		theme,
		enter: {
			preset: "rise",
			duration: sec(0.9),
			delay: WINDOW_IN,
			distance: 60,
		},
	});
	// Content rects → the stage the camera films.
	const stage = (r: Rect): Rect => {
		const [x, y] = frame.at(r.x, r.y);
		return { x, y, width: r.width, height: r.height };
	};
	const aim = (r: Rect) => frame.at(...centre(r));
	const assignees = menuUnder(ASSIGNEE_FIELD, TEAM.length);
	const dates = menuUnder(DUE_FIELD, DUE_OPTIONS.length);
	const maya = inModal(optionIn(assignees, 0));
	const friday = inModal(optionIn(dates, FRIDAY));
	const newCard = cardSlot(READY, 0);

	const targets = {
		request: stage(REQUEST_ROW),
		create: stage(CREATE_BUTTON),
		assignee: stage(inModal(ASSIGNEE_FIELD)),
		maya: stage(maya),
		due: stage(inModal(DUE_FIELD)),
		friday: stage(friday),
		checklist: stage(inModal(ADD_CHECKLIST)),
		save: stage(inModal(SAVE_BUTTON)),
		card: stage(newCard),
	};
	const pointer = MousePointer({
		id: "pointer",
		at: POINTER_IN,
		from: "bottom",
		to: "right",
		size: 32,
		accent: ACCENT,
		fps: FPS,
		hoverRegions: Object.values(targets).map((target) => ({
			target,
			style: "hand" as const,
		})),
		path: perform(POINTER_IN, [
			{
				to: frame.at(LIST_X + 300, LIST_TOP + 52),
				at: sec(4.25),
				click: true,
			},
			{ to: aim(CREATE_BUTTON), at: sec(6.2), travel: 22, click: true },
			{
				to: aim(inModal(ASSIGNEE_FIELD)),
				at: sec(8.25),
				travel: 20,
				click: true,
			},
			{ to: aim(maya), at: sec(9.2), travel: 12, click: true },
			{ to: aim(inModal(DUE_FIELD)), at: sec(10.45), travel: 14, click: true },
			{ to: aim(friday), at: sec(11.45), travel: 14, click: true },
			{
				to: aim(inModal(ADD_CHECKLIST)),
				at: sec(13.05),
				travel: 18,
				click: true,
			},
			{ to: aim(inModal(SAVE_BUTTON)), at: sec(14.3), travel: 16, click: true },
			{
				to: frame.at(newCard.x + 236, newCard.y + 30),
				at: sec(16.2),
				travel: 30,
				rest: SCENE_OUT - sec(16.2),
			},
		]),
	});

	const cues = pointer.cues;
	const t: Timeline = {
		windowIn: WINDOW_IN,
		landed: LANDED,
		select: clickAt(cues, 0),
		create: clickAt(cues, 1),
		assignee: clickAt(cues, 2),
		mayaHover: (cues.arrivals[3]?.frame ?? 0) - 3,
		maya: clickAt(cues, 3),
		due: clickAt(cues, 4),
		fridayHover: (cues.arrivals[5]?.frame ?? 0) - 3,
		friday: clickAt(cues, 5),
		checklist: clickAt(cues, 6),
		save: clickAt(cues, 7),
		sceneOut: SCENE_OUT,
	};
	frame.fill(...relayApp(t));

	// The camera: in on each control while it's used, and still from the press
	// until the control has sprung back. A move starts once the click settles.
	const settled = (c: Click) => c.up + sec(0.2);
	const camera = FocusZoom({
		id: "camera",
		content: [frame, pointer],
		bounds: FRAME,
		length: END_CARD,
		fps: FPS,
		// Long, soft moves, and a slow push while each shot holds: the picture
		// never stops moving.
		smoothing: 0.8,
		drift: 0.012,
		smear: "standard",
		shots: [
			{
				at: settled(t.select),
				target: stage({ x: PANE_X, y: 0, width: PANE_W, height: 420 }),
				zoom: 1.6,
			},
			{
				at: modalIn(t) + 8,
				target: stage(
					inModal({ x: 0, y: 28, width: MODAL.width, height: 560 }),
				),
				zoom: 1.7,
			},
			{
				at: settled(t.friday),
				target: stage(
					inModal({ x: 0, y: 300, width: MODAL.width, height: 340 }),
				),
				zoom: 1.7,
			},
			{ at: settled(t.save), target: "full" },
			{
				at: cardLands(t) + sec(0.8),
				target: stage({
					x: columnX(READY) - 40,
					y: 0,
					width: COLUMN_W + 80,
					height: 560,
				}),
				zoom: 1.6,
				// Held until the card has handed over to the end card.
				hold: END_CARD - (cardLands(t) + sec(0.8)),
			},
		],
	});
	const scene = Layer.box({
		position: "absolute",
		x: 0,
		y: 0,
		width: W,
		height: H,
		perspective: 2200,
		children: [camera],
	}).animate(
		LayerAnimation.keys("rotateX", [
			[0, 22],
			[WINDOW_IN, 22, "hold"],
			[LANDED - 2, 0, "expo.out"],
		]),
		LayerAnimation.keys("rotateY", [
			[0, -18],
			[WINDOW_IN, -18, "hold"],
			[LANDED - 2, 0, "expo.out"],
		]),
		LayerAnimation.keys("opacity", [
			[0, 1],
			[SCENE_OUT, 1, "hold"],
			[SCENE_OUT + sec(0.6), 0, "power2.inOut"],
		]),
	);
	// The new card, where the camera shows it as it leaves for the end card.
	const card = stage(newCard);
	const [left, top] = camera.toScreen([card.x, card.y], SCENE_OUT);
	const [right, bottom] = camera.toScreen(
		[card.x + card.width, card.y + card.height],
		SCENE_OUT,
	);
	const onScreen = {
		x: left,
		y: top,
		width: right - left,
		height: bottom - top,
	};
	const zoomed = camera.cameraAt(SCENE_OUT).zoom;

	const comp = new Composition({
		width: W,
		height: H,
		fps: FPS,
		durationMs: (END / FPS) * 1000,
		backgroundColor: WALL,
		fonts: [`${FONTS}Inter.ttf`],
	});
	comp.add([
		backdrop(),
		scene,
		...opening(FLY, LANDED, targets.request),
		captions(
			["An owner.", "A deadline.", "A clear next step."],
			[t.maya.at + 3, t.friday.at + 3, checklistItemAt(t, 0)],
			t.save.down,
		),
		...handover(onScreen, CARD_RADIUS * zoomed, SCENE_OUT, END_CARD),
		endCard(END_CARD, END - END_CARD),
	]);

	// Narration on its beats, music ducked under it, and sparse cues: a click
	// as each press lands, the modal opening, the card landing.
	const audio = readManifest();
	const starts = lineStarts(t);
	const lines = LINE_IDS.map((id) => ({
		id,
		start: starts[id],
		end: starts[id] + Math.round(audio.voice[id].seconds * FPS),
	}));
	for (const line of lines)
		comp.addAudio(
			sound(voicePath(line.id), line.start, audio.voice[line.id].seconds, 1),
		);
	comp.addAudio(
		Layer.audio(MUSIC_PATH, {
			startFrame: 0,
			durationFrames: END,
			volume: BED,
		}).animate(LayerAnimation.keys("volume", ducking(lines))),
	);
	for (const c of cues.clicks)
		comp.addAudio(sound(CLICK_PATH, c.frame, audio.click.seconds, 0.6));
	comp.addAudio(cue("panel", modalIn(t), 0.6));
	comp.addAudio(cue("complete", cardLands(t), 0.8));
	return {
		film: comp,
		timeline: t,
		camera,
		clicks: cues.clicks.map((c) => c.frame),
		lines,
	};
}

export async function buildFilm(): Promise<Composition> {
	return (await buildRelay()).film;
}