Explainer videos and product demos made by your AI agent. Free and open source: a local voice (Kokoro), word timing (Whisper) and a canvas renderer turn a script into a narrated MP4.
JavaScript ai-agentsanimationcanvasclaude-codecodexexplainer-videoffmpegjavascriptkokoroproduct-demotext-to-speechvideo-generationwhisper
// Boots the engine in a page: loads the project state, fonts, icons, images
// and scenes, then exposes frame rendering, checks and the soundtrack.
import rough from '../vendor/rough.js';
import { Stage, SceneError, boundsRecorder } from './stage.js';
import { getTheme, makeBackground, fontString, colorOf } from './themes.js';
import { Pen } from './pen.js';
import { drawTransition } from './transitions.js';
import { buildPhrases, drawCaptions } from './captions.js';
import { hashStr, mulberry32, suggest, suggestColor, contrast, opaque, withAlpha, parseColor, rgba } from './util.js';
import { layoutAreas } from './layout.js';
import { loadClips, ClipFrames } from './clips.js';
import { UI } from './ui.js';
import { playbackTextIssue } from './readability.js';
import { planCamera, cameraAt, cameraMoving, continues, frameRect, backgroundShot } from './director.js';
Stage.UI = UI;
export async function fetchState() {
const res = await fetch('/__state.json', { cache: 'no-store' });
if (!res.ok) throw new Error(`could not load project state: ${res.status} ${await res.text()}`);
return res.json();
}
async function loadFonts(theme, config, root = '/') {
const manifest = await (await fetch(root + 'fonts/fonts.json')).json();
const wanted = new Set(Object.values(theme.fonts).map((f) => f.family));
// The UI kit (s.ui) draws app screens in Inter and headlines in Instrument Serif.
wanted.add('Inter');
wanted.add('Instrument Serif');
wanted.add('Noto Sans Devanagari');
const faces = [];
const add = (family, url, o) => {
const face = new FontFace(family, `url(${url})`, { weight: String(o.weight ?? 400), style: o.style ?? 'normal', unicodeRange: o.unicodeRange, display: 'block' });
document.fonts.add(face);
faces.push(face.load().catch(() => {
throw new Error(`font "${family}" from ${url} could not be loaded`);
}));
};
for (const f of manifest) if (root === './' || wanted.has(f.family)) add(f.family, `${root}fonts/${f.file}`, f);
if (root !== './' && ['ja', 'zh'].includes(config.language)) {
const family = config.language === 'ja' ? 'Noto Sans JP' : 'Noto Sans SC';
for (const weight of [400, 700]) add(family, `/language-fonts/${config.language}-${weight}.otf`, { weight });
}
// A video's own fonts, from "fonts" in video.json.
for (const f of config.fonts || []) add(f.family, root + 'project/' + f.src.split('/').map(encodeURIComponent).join('/'), f);
await Promise.all(faces);
// Make sure every weight used by the theme is ready before the first frame.
await Promise.all(Object.values(theme.fonts).map((f) => document.fonts.load(`${f.weight} 40px "${f.family}"`)));
}
async function loadImages(assets, root = '/') {
const images = new Map();
await Promise.all(
assets
.filter((a) => /\.(png|jpe?g|webp|gif|svg)$/i.test(a))
.map(async (a) => {
const img = new Image();
img.src = root + 'project/' + a.split('/').map(encodeURIComponent).join('/');
await img.decode().catch(() => {
throw new Error(`image ${a} could not be decoded`);
});
images.set(a, img);
}),
);
return images;
}
export class Engine {
constructor({ canvas, state, scenes, icons, images, clips = new Map(), scale = 1, transparent = false, sfxNames = [] }) {
const { config, timeline } = state;
this.state = state;
this.config = config;
this.timeline = timeline;
this.scenesModule = scenes;
this.W = config.width;
this.H = config.height;
const areas = layoutAreas(config, this.W, this.H);
this.safeArea = areas.safe;
this.captionArea = areas.captions;
this.captionBand = areas.band;
this.appArea = areas.app;
this.fps = config.fps;
this.scale = scale;
this.transparent = transparent;
this.theme = getTheme(config.theme, config.look);
this.pen = new Pen({ rough, theme: this.theme });
this.icons = icons;
this.iconCache = new Map();
this.mathCache = new Map();
this.lateMath = new Map();
this.collectingMath = false;
this.images = images;
this.clips = clips;
this.clipFrames = new ClipFrames();
this.clipProbe = null;
this.sfxNames = sfxNames;
this.sfxMode = config.sfx;
this.recorder = null;
this.textLog = null;
this.errors = [];
this.canvas = canvas;
// H.264 needs even dimensions.
canvas.width = 2 * Math.round((this.W * scale) / 2);
canvas.height = 2 * Math.round((this.H * scale) / 2);
this.ctx = canvas.getContext('2d', { alpha: transparent });
this.background = transparent ? null : makeBackground(this.theme, this.W, this.H, config.seed);
this.phrases = config.captions ? buildPhrases(timeline, this.H > this.W ? 28 : 46) : [];
this.buffers = [0, 1].map(() => {
const c = document.createElement('canvas');
c.width = canvas.width;
c.height = canvas.height;
return c;
});
const ids = new Set(timeline.scenes.map((s) => s.id));
this.extraScenes = Object.keys(scenes).filter((k) => !ids.has(k));
for (const sc of timeline.scenes) {
if (typeof scenes[sc.id] !== 'function') {
const have = Object.keys(scenes);
throw new SceneError(`scenes.js has no function for scene "${sc.id}".${have.length ? ' Close names: ' + suggest(sc.id, have, 3).join(', ') : ''}`);
}
}
}
image(src) {
const key = src.replace(/^\.?\//, '');
const img = this.images.get(key) || this.images.get('assets/' + key);
if (!img) throw new SceneError(`image "${src}" not found. Put it in the project's assets/ folder. Available: ${[...this.images.keys()].join(', ') || 'none'}`);
return img;
}
clip(src) {
const key = src.replace(/^\.?\//, '');
const clip = this.clips.get(key) || this.clips.get('assets/' + key);
if (!clip) throw new SceneError(`clip "${src}" not found. Put an MP4, MOV, WebM or M4V in the project's assets/ folder. Available: ${[...this.clips.keys()].join(', ') || 'none'}`);
return clip;
}
clipImage(clip, frame) {
if (this.recorder) return null;
if (clip.video) {
const video = clip.video;
const time = Math.min(frame / clip.fps, Math.max(0, clip.duration - 0.04));
if (!video.seeking && Math.abs(video.currentTime - time) > 0.04) video.currentTime = time;
return video.readyState >= 2 ? video : null;
}
const key = this.clipFrames.key(clip, frame);
if (this.clipProbe) {
this.clipProbe.set(key, { clip, frame });
return null;
}
const img = this.clipFrames.get(clip, frame);
if (img) return img;
if (this.clipFrames.errors.has(key)) throw this.clipFrames.errors.get(key);
this.clipFrames.load(clip, frame).then(() => {
this.clipFrames.trim();
this.onClipFrame?.();
}).catch((e) => {
this.clipFrames.errors.set(key, e);
this.onClipFrame?.();
});
return this.clipFrames.nearest(clip, frame);
}
// Loads the clip frames that time T shows. It finds them by drawing the
// frame on `ctx`. Motion blur passes a spare canvas here, so the picture it
// is adding up on the main canvas stays as it is.
async prepareFrame(T, ctx = this.ctx) {
if (!this.clips.size) return;
const needed = new Map();
this.clipProbe = needed;
try { this.renderFrame(T, ctx); }
finally { this.clipProbe = null; }
await Promise.all([...needed.values()].map(({ clip, frame }) => this.clipFrames.load(clip, frame)));
this.clipFrames.trim(new Set(needed.keys()));
}
mathData(tex, display, scene, t) {
const key = JSON.stringify([tex, display]);
if (this.staticMath) return this.staticMath[key] || { error: 'formula missing from the player. Export the project again.' };
if (this.collectingMath) {
if (!this.mathCache.has(key)) this.mathCache.set(key, null);
return null;
}
if (!this.mathCache.has(key)) {
this.lateMath.set(key, { scene, t, tex });
// Late formulas still draw synchronously, including the frame that finds them.
const req = new XMLHttpRequest();
req.open('GET', this.mathURL(tex, display), false);
req.send();
this.mathCache.set(key, this.mathResponse(req.status, req.responseText));
}
return this.mathCache.get(key);
}
mathURL(tex, display) {
return `/__math?tex=${encodeURIComponent(tex)}&display=${display ? '1' : '0'}`;
}
mathResponse(status, body) {
if (status !== 200) {
try { return { error: JSON.parse(body).error || body }; } catch { return { error: body }; }
}
return JSON.parse(body);
}
async loadMath() {
this.collectingMath = true;
try {
for (const sc of this.timeline.scenes) {
// Scene errors belong to check or render, as they do without formulas.
try { this.drawScene(this.ctx, sc.index, 0); } catch {}
}
} finally {
this.collectingMath = false;
}
await Promise.all([...this.mathCache.keys()].map(async key => {
const [tex, display] = JSON.parse(key);
const res = await fetch(this.mathURL(tex, display));
this.mathCache.set(key, this.mathResponse(res.status, await res.text()));
}));
}
sceneAt(T) {
const list = this.timeline.scenes;
let i = list.length - 1;
while (i > 0 && T < list[i].start) i--;
return i;
}
transitionFor(sc) {
// A scene that goes on with the picture before it fades into it. A wipe
// or a slide would break that picture apart.
if (sc.transition === 'auto' && this.continued?.has(sc.index)) return 'fade';
const name = sc.transition === 'auto' ? this.theme.transition : sc.transition;
if (this.transparent && ['slide', 'wipe', 'brush'].includes(name)) return 'fade';
return name || 'fade';
}
drawScene(ctx, index, t) {
const sc = this.timeline.scenes[index];
if (this.transparent) {
ctx.setTransform(1, 0, 0, 1, 0, 0);
ctx.clearRect(0, 0, ctx.canvas.width, ctx.canvas.height);
}
ctx.setTransform(this.scale, 0, 0, this.scale, 0, 0);
ctx.globalAlpha = 1;
ctx.globalCompositeOperation = 'source-over';
const plan = !this.planning && !this.cameraOff ? this.cameraPlans?.get(index) : null;
// A scene drawn past its end, while the next one comes in, keeps the
// camera where it stopped, so a continued picture stays on top of itself.
const cam = plan ? cameraAt(plan, Math.min(t, plan.dur)) : null;
if (this.background) {
if (plan) {
// The background moves a third as much as the camera, so it looks
// further away.
const bg = backgroundShot(plan, cam);
const v = plan.view;
ctx.save();
ctx.translate(v.x + v.w / 2, v.y + v.h / 2);
ctx.scale(bg.z, bg.z);
ctx.translate(-bg.x, -bg.y);
ctx.drawImage(this.background, 0, 0, this.W, this.H);
ctx.restore();
} else ctx.drawImage(this.background, 0, 0, this.W, this.H);
}
if (this.config.boil > 0) this.pen.seedOffset = Math.floor((sc.start + t) * this.config.boil) % 997;
const saved = Math.random;
Math.random = mulberry32(hashStr(`random:${sc.id}`));
ctx.save();
// The automatic camera films the scene unless the scene moves its own.
if (plan) {
const v = plan.view;
ctx.translate(v.x + v.w / 2, v.y + v.h / 2);
ctx.scale(cam.z, cam.z);
ctx.translate(-cam.x, -cam.y);
if (cameraMoving(plan, t)) this.moving = true;
}
const s = new Stage(this, ctx, sc, t);
// While the camera is planned, anything a scene draws straight on s.ctx
// is measured as one block that the camera must not cut.
let raw = null;
let api = s;
if (this.planning && this.layoutLog) {
raw = boundsRecorder(ctx, this.scale, { W: this.W, H: this.H });
// The UI kit draws on the same recorder; its panels and headlines
// still report their own times.
let ui = null;
api = new Proxy(s, {
get: (target, prop) => {
if (prop === 'ctx') return raw.proxy;
if (prop === 'ui') return (ui ??= new Stage.UI(api));
const v = target[prop];
return typeof v === 'function' ? v.bind(target) : v;
},
});
}
try {
this.scenesModule[sc.id](api);
const ink = raw?.box();
if (ink) this.layoutLog.push({ kind: 'ink', at: 0, out: Infinity, box: ink });
} catch (e) {
const err = e instanceof Error ? e : new Error(String(e));
err.scene = sc.id;
err.sceneTime = t;
throw err;
} finally {
Math.random = saved;
ctx.restore();
}
return s;
}
// Measures every scene once and plans its camera. A scene that continues
// the picture of the scene before it starts where that camera stopped,
// and the two dissolve into each other. Scene errors are left to check
// and render, which report them with their time.
planCameras() {
this.cameraPlans = new Map();
this.continued = new Set();
if (this.config.camera === 'still') return;
const scratch = document.createElement('canvas');
scratch.width = 16;
scratch.height = 16;
const ctx = scratch.getContext('2d');
const view = this.safeArea;
const frame = { W: this.W, H: this.H };
// The part of the frame that captions and app overlays leave free.
const usable = { x0: 0, y0: 0, x1: this.W, y1: this.H };
if (this.appArea) Object.assign(usable, { x0: this.appArea.left, y0: this.appArea.top, x1: this.appArea.right, y1: this.appArea.bottom });
if (this.captionBand) usable.y1 = Math.min(usable.y1, this.captionBand.top);
const layouts = this.timeline.scenes.map((sc) => {
this.layoutLog = [];
this.planning = true;
this.manualCamera = false;
try {
this.drawScene(ctx, sc.index, Math.max(0, sc.dur - 0.01));
return this.manualCamera ? null : this.layoutLog.map((e) => ({ ...e, out: e.out ?? Infinity }));
} catch {
return null;
} finally {
this.layoutLog = null;
this.planning = false;
}
});
this.timeline.scenes.forEach((sc, i) => {
if (!layouts[i]) return;
const prev = i > 0 ? this.cameraPlans.get(i - 1) : null;
const linked = prev && layouts[i - 1] && sc.transition !== 'none' && continues(layouts[i - 1], layouts[i], frameRect(cameraAt(prev, prev.dur), view, frame));
const voiceEnd = sc.voice ? sc.lead + sc.voice.dur : null;
const still = linked ? Math.min(this.timeline.transitionSeconds, sc.dur * 0.5) : 0;
const plan = planCamera(layouts[i], { dur: sc.dur, view, frame, pace: this.timeline.pace || 1, voiceEnd, from: linked ? cameraAt(prev, prev.dur) : null, still, usable });
if (!plan) return;
this.cameraPlans.set(i, plan);
if (linked) this.continued.add(i);
});
}
renderFrame(T, ctx = this.ctx, { captions = true } = {}) {
const i = this.sceneAt(T);
const sc = this.timeline.scenes[i];
const t = T - sc.start;
const trName = this.transitionFor(sc);
const trDur = Math.min(this.timeline.transitionSeconds, sc.dur * 0.5);
if (i > 0 && sc.transition !== 'none' && trName !== 'cut' && t < trDur) {
const prev = this.timeline.scenes[i - 1];
const [a, b] = this.buffers;
if (this.transparent) {
ctx.setTransform(1, 0, 0, 1, 0, 0);
ctx.clearRect(0, 0, ctx.canvas.width, ctx.canvas.height);
}
this.moving = true;
this.drawScene(a.getContext('2d', { alpha: this.transparent }), i - 1, T - prev.start);
this.drawScene(b.getContext('2d', { alpha: this.transparent }), i, t);
drawTransition(trName, ctx, a, b, t / trDur, this.W, this.H, hashStr(sc.id), this.transparent);
} else {
this.drawScene(ctx, i, t);
}
if (captions && this.phrases.length) {
ctx.setTransform(this.scale, 0, 0, this.scale, 0, 0);
drawCaptions(ctx, this.phrases, T, this.theme, this.W, this.H, this.captionArea);
}
if (this.config.watermark) {
ctx.setTransform(this.scale, 0, 0, this.scale, 0, 0);
this.drawWatermark(ctx, this.config.watermark);
}
}
// Small text in the bottom right corner of every frame, on a soft backing
// so it stays readable over any scene. Platform formats cover that corner
// with the app's own buttons, so there it sits at the top right of the part
// of the frame the app leaves free.
drawWatermark(ctx, text) {
const th = this.theme;
const m = Math.min(this.W, this.H);
const size = Math.round(m * 0.028);
const margin = Math.round(m * 0.028);
ctx.save();
ctx.globalAlpha = 1;
ctx.globalCompositeOperation = 'source-over';
ctx.font = fontString(th, 'body', size, th.fonts.body.family === 'Inter' ? 600 : th.fonts.body.family === 'Kalam' ? 700 : undefined);
ctx.textAlign = 'right';
ctx.textBaseline = 'middle';
const w = ctx.measureText(text).width;
const padX = size * 0.6;
const h = size * 1.6;
const x = this.appArea ? this.appArea.right : this.W - margin;
const y = this.appArea ? this.appArea.top + h / 2 : this.H - margin - h / 2;
ctx.fillStyle = withAlpha(th.bg, 0.72);
ctx.beginPath();
ctx.roundRect(x - w - padX * 2, y - h / 2, w + padX * 2, h, h / 2);
ctx.fill();
ctx.fillStyle = withAlpha(th.ink, 0.82);
ctx.fillText(text, x - padX, y + size * 0.04);
ctx.restore();
}
// Runs every scene over its duration without keeping pixels, collecting the
// elements that enter (for sound effects) and any scene errors.
collectEvents(step = 0.1) {
const scratch = document.createElement('canvas');
const save = { scale: this.scale };
this.scale = 0.25;
scratch.width = Math.round(this.W * 0.25);
scratch.height = Math.round(this.H * 0.25);
const ctx = scratch.getContext('2d', { alpha: false });
const events = [];
const errors = [];
try {
for (const sc of this.timeline.scenes) {
const seen = new Map();
this.recorder = { push: (e) => { if (!seen.has(e.key)) seen.set(e.key, e); } };
const n = Math.ceil(sc.dur / step);
for (let k = 0; k <= n; k++) {
const t = Math.min(sc.dur, k * step);
try {
this.drawScene(ctx, sc.index, t);
} catch (e) {
errors.push({ scene: sc.id, t, message: e.message });
break;
}
}
for (const e of seen.values()) {
if (e.at > sc.dur + 0.001) continue;
events.push({ ...e, scene: sc.id, T: sc.start + e.at });
}
}
} finally {
this.recorder = null;
this.scale = save.scale;
}
return { events, errors };
}
// Sound cues for the soundtrack: element entrances, explicit s.sfx() calls
// and scene transitions, thinned so effects never pile up.
sfxCues() {
if (this.config.sfx === false && !this.clips.size) return { cues: [], clips: [], errors: [] };
const { events, errors } = this.collectEvents();
const clips = events.filter((e) => e.kind === 'clip' && e.volume > 0 && e.speed === 1 && e.hasAudio).map((e) => ({ ...e, start: e.T, end: e.T + e.end - e.at }));
if (this.config.sfx === false) return { cues: [], clips, errors };
const cues = [];
for (const e of events) {
if (!e.sfx) continue;
if (!this.sfxNames.includes(e.sfx)) continue;
const cue = { name: e.sfx, t: e.T, gain: e.gain ?? 1, explicit: !!e.explicit };
if (e.pitch !== undefined) cue.pitch = e.pitch;
if (['scribble', 'chalk', 'type', 'rise'].includes(e.sfx)) cue.dur = Math.max(0.15, Math.min(e.dur || 0.4, 3));
cues.push(cue);
}
for (const sc of this.timeline.scenes) {
if (sc.index === 0 || sc.transition === 'none') continue;
const name = this.transitionFor(sc);
if (name === 'cut') continue;
const s = this.theme.sfx.transition;
if (s) cues.push({ name: s, t: Math.max(0, sc.start - 0.05), gain: 0.8, explicit: true });
}
cues.sort((a, b) => a.t - b.t);
const out = [];
const last = new Map();
let windowStart = 0;
let inWindow = 0;
for (const c of cues) {
const prev = last.get(c.name);
if (!c.explicit && prev !== undefined && c.t - prev < (c.name === 'tick' ? 0.045 : 0.12)) continue;
if (c.t - windowStart > 0.5) {
windowStart = c.t;
inWindow = 0;
}
if (!c.explicit && inWindow >= 3 && c.name !== 'tick') continue;
inWindow++;
last.set(c.name, c.t);
out.push(c);
}
return { cues: out, clips, errors };
}
// Samples every scene and reports layout problems.
check(step = 0.25, viewWidth = null) {
// check looks at the layout as written. The automatic camera only ever
// moves in, which makes text larger, and it may leave the edges out of
// a close-up on purpose.
this.cameraOff = true;
try {
return this._check(step, viewWidth);
} finally {
this.cameraOff = false;
}
}
_check(step, viewWidth) {
const issues = [];
const add = (level, scene, t, message) => issues.push({ level, scene, t: t === null ? null : Math.round(t * 100) / 100, message });
if (this.config.look) {
for (const [key, min] of [['ink', 4.5], ['muted', 3]]) {
if (contrast(this.theme[key], this.theme.bg) < min) add('warn', null, null, `${this.config.theme}: ${key} has low contrast against bg; use colors with a contrast of at least ${min}`);
}
}
for (const id of this.extraScenes) add('warn', id, null, `scenes.js has a function "${id}" but script.md has no scene with that id, so it is never shown`);
const scratch = document.createElement('canvas');
scratch.width = this.canvas.width;
scratch.height = this.canvas.height;
const ctx = scratch.getContext('2d', { alpha: false });
const { W, H } = this;
const margin = Math.round(Math.min(W, H) * 0.035);
const minSize = Math.round(Math.min(W, H) * 0.022);
const uiMinSize = Math.round(Math.min(W, H) * 0.015);
const colors = Object.fromEntries(['ink', 'accent', ...Object.keys(this.theme.colors)].map(name => [name, colorOf(this.theme, name)]));
let colorCtx;
const cssColor = color => {
if (parseColor(color)) return color;
if (!colorCtx) {
const canvas = document.createElement('canvas');
canvas.width = canvas.height = 1;
colorCtx = canvas.getContext('2d');
}
colorCtx.clearRect(0, 0, 1, 1);
colorCtx.fillStyle = '#000000';
colorCtx.fillStyle = color;
colorCtx.fillRect(0, 0, 1, 1);
const [r, g, b, a] = colorCtx.getImageData(0, 0, 1, 1).data;
return rgba({ r, g, b, a: a / 255 });
};
const reported = new Set();
const once = (key, fn) => {
if (reported.has(key)) return;
reported.add(key);
fn();
};
this.cueNotes = [];
for (const sc of this.timeline.scenes) {
const entrances = [];
this.recorder = { push: (e) => entrances.push(e) };
const n = Math.ceil(sc.dur / step);
for (let k = 0; k <= n; k++) {
const t = Math.min(sc.dur - 0.001, k * step);
this.textLog = [];
try {
this.drawScene(ctx, sc.index, t);
} catch (e) {
once(`err:${sc.id}:${e.message}`, () => add('error', sc.id, t, e.message));
break;
}
for (const pr of this.textLog.filter((x) => x.problem)) once(`problem:${sc.id}:${pr.problem}`, () => add('error', sc.id, t, pr.problem));
const texts = this.textLog.filter((x) => !x.problem && x.alpha > 0.5);
for (const tx of texts) {
if (viewWidth !== null) {
const message = playbackTextIssue(tx, W, H, viewWidth);
if (message) once(`playback:${sc.id}:${tx.text}`, () => add('warn', sc.id, t, message));
}
const label = tx.text.length > 40 ? tx.text.slice(0, 37) + '...' : tx.text;
// UI kit text (s.ui) may leave the frame on purpose while the
// camera zooms or pans; app screens use smaller text than slides.
const framed = !(tx.ui && tx.zoomed);
if (tx.x0 < -1 || tx.y0 < -1 || tx.x1 > W + 1 || tx.y1 > H + 1) {
if (framed) once(`off:${sc.id}:${tx.text}`, () => add('error', sc.id, t, `"${label}" runs off the frame (${Math.round(tx.x0)},${Math.round(tx.y0)} to ${Math.round(tx.x1)},${Math.round(tx.y1)} in a ${W}x${H} frame)`));
} else if (this.appArea) {
const a = this.appArea;
if (framed && (tx.x0 < a.left - 2 || tx.y0 < a.top - 2 || tx.x1 > a.right + 2 || tx.y1 > a.bottom + 2)) {
once(`app:${sc.id}:${tx.text}`, () => add('warn', sc.id, t, `"${label}" is outside the ${this.config.format} safe area (${a.left},${a.top} to ${a.right},${a.bottom}), where the app's buttons, name or caption can cover it`));
}
} else if (framed && (tx.x0 < margin || tx.y0 < margin || tx.x1 > W - margin || tx.y1 > H - margin)) {
once(`edge:${sc.id}:${tx.text}`, () => add('warn', sc.id, t, `"${label}" sits closer than ${margin}px to the edge`));
}
const b = this.captionBand;
if (b && tx.y1 > b.top + 2 && tx.y0 < b.bottom - 2 && tx.x1 > b.left && tx.x0 < b.right) {
once(`cap:${sc.id}:${tx.text}`, () => add('warn', sc.id, t, `"${label}" is in the caption band (y ${Math.round(b.top)} to ${Math.round(b.bottom)}), where captions can cover it; keep content above s.safe.bottom (${Math.round(this.safeArea.bottom)})`));
}
const least = tx.ui ? uiMinSize : minSize;
if (!tx.block && Math.round(tx.size) < least) once(`small:${sc.id}:${tx.text}`, () => add('warn', sc.id, t, `"${label}" is ${Math.round(tx.size)}px, hard to read (use at least ${least}px)`));
const bg = opaque(tx.bg || this.theme.bg, this.theme.bg);
if (typeof tx.fg === 'string' && contrast(tx.fg, bg) < 3) once(`contrast:${sc.id}:${tx.text}`, () => {
const suggestion = suggestColor(cssColor(tx.fg), cssColor(bg), tx.size, Object.fromEntries(Object.entries(colors).map(([name, c]) => [name, cssColor(c)])));
add('warn', sc.id, t, `"${label}" has low contrast against its background (${contrast(tx.fg, bg).toFixed(1)}:1); use color: '${suggestion.color}' (${suggestion.ratio.toFixed(1)}:1)`);
});
}
// Overlaps only count when both are fully shown, not mid-fade.
const solid = texts.filter((x) => x.alpha > 0.95);
for (let a = 0; a < solid.length; a++) {
for (let b = a + 1; b < solid.length; b++) {
const A = solid[a];
const B = solid[b];
if (A.block && B.block) continue;
// A dropdown or dialog (s.ui) covers what is under it.
if ((A.ui || 1) !== (B.ui || 1)) continue;
const ix = Math.min(A.x1, B.x1) - Math.max(A.x0, B.x0);
const iy = Math.min(A.y1, B.y1) - Math.max(A.y0, B.y0);
if (ix <= 4 || iy <= 4) continue;
const small = Math.min((A.x1 - A.x0) * (A.y1 - A.y0), (B.x1 - B.x0) * (B.y1 - B.y0)) || 1;
if ((ix * iy) / small > 0.15) {
once(`overlap:${sc.id}:${A.text}:${B.text}`, () => add('error', sc.id, t, `"${A.text.slice(0, 30)}" overlaps "${B.text.slice(0, 30)}"`));
}
}
}
}
this.recorder = null;
this.textLog = null;
const times = [...new Set(entrances.map((e) => Math.round(e.at * 100) / 100))].sort((a, b) => a - b);
for (const e of entrances) {
if (e.kind === 'clip') {
if (e.volume > 0 && e.speed !== 1) once(`clip-sound:${sc.id}:${e.key}`, () => add('warn', sc.id, e.at, `clip "${e.src}" stays silent at speed ${e.speed}; use speed: 1 for its sound`));
if (!e.loop && e.out - e.end > 1) once(`clip-freeze:${sc.id}:${e.key}`, () => add('hint', sc.id, e.end, `clip "${e.src}" freezes on its last frame from ${e.end.toFixed(2)}s until ${e.out.toFixed(2)}s; use loop: true or an earlier out`));
}
if (e.at > sc.dur) once(`late:${sc.id}:${e.key}`, () => add('error', sc.id, e.at, `a ${e.kind} is set to appear at ${e.at.toFixed(2)}s but the scene ends at ${sc.dur.toFixed(2)}s`));
}
if (!times.length) {
add('warn', sc.id, null, 'nothing enters in this scene; add at least one element with an "at" time');
} else {
const marks = [0, ...times.filter((x) => x >= 0 && x <= sc.dur), sc.dur];
for (let i = 1; i < marks.length; i++) {
const gap = marks[i] - marks[i - 1];
if (gap > 6) add('hint', sc.id, marks[i - 1], `no new element for ${gap.toFixed(1)}s (from ${marks[i - 1].toFixed(1)}s); consider revealing something on a cue in that stretch`);
}
}
}
const repeated = new Map();
for (const c of this.cueNotes) repeated.set(`${c.scene}|${c.word.toLowerCase()}`, c);
for (const c of repeated.values()) {
add('hint', c.scene, null, `cue "${c.word}" means the first of the ${c.count} times it is spoken in this scene; if you meant a later one, use s.cue("${c.word}", 2) or a [#marker]`);
}
this.cueNotes = null;
for (const { scene, t, tex } of this.lateMath.values()) add('error', scene, t, `math "${tex}" was not collected at the start; keep TeX strings fixed and always call s.math with at and out for timing`);
return issues;
}
}
// Boots the engine for render, check or studio pages.
export async function boot({ canvas, scale = 1, transparent = false, version = '', player = false }) {
const root = player ? './' : '/';
const state = player ? await (await fetch('./state.json')).json() : await fetchState();
const theme = getTheme(state.config.theme, state.config.look);
const [icons, images, scenesMod, audio, iconTags, clips] = await Promise.all([
fetch(root + 'engine/icons/lucide.json').then((r) => r.json()).then((j) => {
// Old Lucide names keep working.
for (const [alias, target] of Object.entries(j.aliases || {})) if (!j.icons[alias]) j.icons[alias] = j.icons[target];
return j.icons;
}),
loadImages(state.assets, root),
import(player ? '../project/scenes.js' : `/project/scenes.js?v=${encodeURIComponent(version || state.version)}`),
player ? { SFX: {} } : import('./audio/soundtrack.js').catch((e) => ({ SFX: {}, loadError: e })),
player ? {} : fetch('/engine/icons/lucide-tags.json').then((r) => r.json()),
loadClips(state.assets, player ? state : null),
loadFonts(theme, state.config, root),
]);
const scenes = scenesMod.default;
if (!scenes || typeof scenes !== 'object') throw new Error('scenes.js must "export default { sceneId(s) { ... } }"');
const engine = new Engine({ canvas, state, scenes, icons, images, clips, scale, transparent, sfxNames: Object.keys(audio.SFX) });
engine.iconTags = iconTags;
if (player) engine.staticMath = await (await fetch('./math.json')).json();
else await engine.loadMath();
engine.planCameras();
return { engine, audio, state };
}
// Mixes narration, music and sound effects in an OfflineAudioContext.
export async function renderAudio(engine, audio, { sampleRate = 48000 } = {}) {
if (audio.loadError) throw new Error(`audio engine failed to load: ${audio.loadError.message}`);
const { timeline, config } = engine.state;
const { cues, clips, errors } = engine.sfxCues();
const buffer = await audio.renderSoundtrack({
duration: timeline.duration,
sampleRate,
voice: timeline.scenes.filter((s) => s.voice).map((s) => ({ url: '/project/' + s.voice.url + '?v=' + engine.state.version, start: s.voice.start })),
voiceSpans: timeline.voiceSpans,
music: config.music,
sfx: cues,
clips,
scenes: timeline.scenes.map((s) => ({ start: s.start, dur: s.dur })),
});
return { buffer, cues, errors };
}