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
import test from 'node:test';
import assert from 'node:assert/strict';
import { planCamera, cameraAt, cameraMoving, compose, continues, frameRect, viewRect } from '../engine/director.js';
const frame = { W: 1920, H: 1080 };
const view = { x: 134, y: 76, w: 1652, h: 928 };
const el = (kind, x, y, w, h, at, out = Infinity) => ({ kind, at, out, box: { x: x + w / 2, y: y + h / 2, w, h } });
// Every card or label is fully inside the frame or fully outside it.
function cuts(shot, elements, margin = 1) {
const r = frameRect(shot, view, frame);
return elements.filter((e) => {
if (e.kind === 'arrow' || e.kind === 'line') return false;
const b = { x0: e.box.x - e.box.w / 2, x1: e.box.x + e.box.w / 2, y0: e.box.y - e.box.h / 2, y1: e.box.y + e.box.h / 2 };
const outside = b.x1 <= r.x0 + margin || b.x0 >= r.x1 - margin || b.y1 <= r.y0 + margin || b.y0 >= r.y1 - margin;
const inside = b.x0 >= r.x0 - margin && b.x1 <= r.x1 + margin && b.y0 >= r.y0 - margin && b.y1 <= r.y1 + margin;
return !inside && !outside;
});
}
const diagram = [
el('text', 760, 90, 400, 90, 0.1),
el('shape', 200, 450, 260, 140, 1.5),
el('arrow', 470, 500, 300, 40, 2.6),
el('shape', 780, 450, 260, 140, 2.8),
el('arrow', 1050, 500, 300, 40, 4.4),
el('shape', 1360, 450, 260, 140, 4.6),
el('text', 1360, 640, 260, 40, 6.2),
];
test('no elements means no camera', () => {
assert.equal(planCamera([], { dur: 5, view, frame }), null);
assert.equal(planCamera([el('shape', 0, 0, 1920, 1080, 0)], { dur: 5, view, frame }), null);
});
// Zoom direction changes (in after out, or out after in) less than `gap`
// seconds apart.
function reversals(plan, gap = 5) {
let prev = null;
let n = 0;
for (const m of plan.moves) {
const dz = Math.log(m.to.z / m.from.z);
if (Math.abs(dz) < 0.1) continue;
if (prev && Math.sign(dz) !== prev.sign && m.start - prev.start < gap) n++;
prev = { sign: Math.sign(dz), start: m.start };
}
return n;
}
test('a scene that starts small starts close and widens as the picture grows', () => {
const row = [0, 1, 2, 3].map((i) => el('shape', 260 + i * 380, 470, 220, 140, 0.5 + i * 3));
const plan = planCamera(row, { dur: 14, view, frame });
assert.ok(plan.start.z > 1.3, 'the first shot is close');
for (const m of plan.moves) assert.ok(m.to.z <= m.from.z + 1e-9, `no zooming in again at ${m.start}`);
const end = frameRect(cameraAt(plan, 13.9), view, frame);
for (const e of row) assert.ok(e.box.x - e.box.w / 2 >= end.x0 && e.box.x + e.box.w / 2 <= end.x1, 'the end shows everything');
});
test('something new that already fits the shot needs no move', () => {
// A large chart, then a line and a label drawn inside it.
const chart = [
el('shape', 260, 160, 1400, 760, 0.2),
el('line', 560, 540, 800, 0, 3),
el('text', 900, 600, 160, 40, 6.5),
];
const plan = planCamera(chart, { dur: 11, view, frame });
assert.equal(plan.moves.length, 0);
});
test('the camera pushes in on something small when there is time, not again right after, and pulls back at the end', () => {
const scene = [
el('shape', 200, 200, 600, 300, 0.2),
el('shape', 1100, 200, 600, 300, 0.2),
el('text', 1250, 700, 300, 50, 3),
el('text', 300, 700, 300, 50, 6.5),
];
const plan = planCamera(scene, { dur: 13, view, frame, voiceEnd: 11 });
const pushes = plan.moves.filter((m) => m.to.z > m.from.z * 1.1);
assert.equal(pushes.length, 1, 'one push in');
assert.ok(Math.abs(pushes[0].start - 2.7) < 1e-6, 'on the first note');
const end = frameRect(cameraAt(plan, 12.9), view, frame);
for (const e of scene) assert.ok(e.box.x - e.box.w / 2 >= end.x0 - 0.5 && e.box.x + e.box.w / 2 <= end.x1 + 0.5, 'the end shows everything');
});
test('the camera does not keep zooming in and out', () => {
// New things every two seconds, far apart from each other.
const spots = [[200, 200], [1500, 800], [300, 820], [1450, 180], [860, 500], [200, 500], [1500, 500]];
const scene = spots.map(([x, y], i) => el('shape', x - 90, y - 50, 180, 100, 0.2 + i * 2));
const plan = planCamera(scene, { dur: 16, view, frame, voiceEnd: 14 });
for (let i = 1; i < plan.moves.length; i++) assert.ok(plan.moves[i].start - plan.moves[i - 1].start >= 2.2 - 1e-9, 'moves are spaced out');
assert.ok(reversals(plan) <= 1, `reversals: ${reversals(plan)}`);
assert.ok(plan.moves.length <= 5, `moves: ${plan.moves.length}`);
});
test('no shot cuts a card or label in half while it holds, drift included', () => {
const plan = planCamera(diagram, { dur: 12, view, frame, voiceEnd: 9 });
const holds = [0.05, ...plan.moves.map((m) => m.start + m.dur + 0.01), 11.9];
for (const t of holds) {
const shot = cameraAt(plan, t);
const visible = diagram.filter((e) => e.at <= t && e.out > t);
assert.deepEqual(cuts(shot, visible).map((e) => e.kind), [], `t=${t}`);
}
});
test('the camera is continuous and only reports real moves as moving', () => {
const plan = planCamera(diagram, { dur: 12, view, frame, voiceEnd: 9 });
let prev = cameraAt(plan, 0);
for (let t = 0.01; t < 12; t += 0.01) {
const c = cameraAt(plan, t);
assert.ok(Math.abs(c.x - prev.x) < 25 && Math.abs(c.y - prev.y) < 25 && Math.abs(Math.log(c.z / prev.z)) < 0.03, `jump at ${t.toFixed(2)}`);
prev = c;
}
const m = plan.moves[0];
assert.equal(cameraMoving(plan, m.start + m.dur / 2), true);
assert.equal(cameraMoving(plan, m.start - 0.01), false);
});
test('a close-up leaves a neighbour out entirely or takes it in, and falls back to the full frame', () => {
const row = [0, 1, 2, 3, 4].map((i) => el('shape', 805 + i * 205, 335, 190, 130, 3 + i * 0.2));
const music = el('icon', 1050, 700, 120, 120, 6.7);
const shot = compose([music], [...row, music], view, frame);
assert.ok(shot.z > 1.2);
assert.deepEqual(cuts(shot, row), []);
// A neighbour hugging the subject on every side cannot be avoided.
const subject = el('shape', 900, 500, 120, 80, 1);
const ring = [el('text', 700, 380, 600, 60, 0), el('text', 700, 640, 600, 60, 0), el('text', 560, 380, 60, 320, 0), el('text', 1300, 380, 60, 320, 0)];
const tight = compose([subject], [subject, ...ring], view, frame);
assert.deepEqual(cuts(tight, ring), []);
const v = viewRect(tight, view);
assert.ok(subject.box.x - subject.box.w / 2 >= v.x0 && subject.box.x + subject.box.w / 2 <= v.x1);
});
test('a scene continues the one before it when its first frame is that scene\'s last picture', () => {
const a = [el('shape', 200, 450, 260, 140, 0), el('shape', 780, 450, 260, 140, 1), el('text', 780, 640, 260, 40, 2)];
const b = [el('shape', 200, 450, 260, 140, -1), el('shape', 780, 450, 260, 140, -1), el('text', 780, 640, 260, 40, -1), el('shape', 1360, 450, 260, 140, 2)];
const everything = { x0: 0, y0: 0, x1: 1920, y1: 1080 };
assert.equal(continues(a, b, everything), true);
// Not when A ends on something B leaves out.
assert.equal(continues(a, b.filter((e) => e.kind !== 'text'), everything), false);
// Not when A's last close-up shows little of what B carries.
const closeUp = { x0: 760, y0: 620, x1: 1060, y1: 700 };
assert.equal(continues(a, b, closeUp), false);
// Not when B draws its own picture.
assert.equal(continues(a, [el('shape', 100, 100, 200, 100, -1), el('shape', 400, 100, 200, 100, -1)], everything), false);
});
test('a continued scene starts where the last camera stopped and holds through the dissolve', () => {
const from = { x: 700, y: 520, z: 1.4 };
const plan = planCamera(diagram, { dur: 12, view, frame, from, still: 0.6 });
assert.deepEqual(plan.start, from);
assert.ok(plan.moves.every((m) => m.start >= 0.6));
const c = cameraAt(plan, 0);
assert.ok(Math.abs(c.x - from.x) < 1e-9 && Math.abs(c.z - from.z) < 1e-9);
});
test('pace makes the camera quicker', () => {
const slow = planCamera(diagram, { dur: 12, view, frame, pace: 1 });
const fast = planCamera(diagram, { dur: 12, view, frame, pace: 1.5 });
assert.ok(slow.moves.length && fast.moves.length);
assert.ok(fast.moves[0].dur < slow.moves[0].dur);
});
test('the opening shot cuts nothing that is on screen before the first move', () => {
// Two opening cards leave at 1s; the close-up on the card at 2s would cut them.
const opening = [el('shape', 160, 150, 1600, 100, 0, 1), el('shape', 700, 440, 400, 200, 0, 1), el('shape', 1300, 465, 200, 150, 2)];
const plan = planCamera(opening, { dur: 8, view, frame });
for (const t of [0.05, 0.5, 0.9]) {
const visible = opening.filter((e) => e.at <= t && e.out > t);
assert.deepEqual(cuts(cameraAt(plan, t), visible).map((e) => e.box.x), [], `t=${t}`);
}
});
test('every move ends before its scene does', () => {
const late = [el('shape', 200, 450, 260, 140, 0), el('shape', 1500, 700, 200, 120, 7.5)];
const plan = planCamera(late, { dur: 8, view, frame });
for (const m of plan.moves) assert.ok(m.start + m.dur <= 8 + 1e-9, `move ${m.start}+${m.dur}`);
});
test('a full-frame shot does not drift what fits the free part of the frame into the app overlays', () => {
const tall = { W: 1080, H: 1920 };
const safe = { x: 119, y: 240, w: 745, h: 1027 };
const usable = { x0: 119, y0: 240, x1: 864, y1: 1267 };
const cards = [el('shape', 119, 703, 200, 100, 0), el('shape', 664, 703, 200, 100, 0.2)];
const plan = planCamera(cards, { dur: 8, view: safe, frame: tall, usable });
for (const t of [0.5, 4, 7.9]) {
const cam = cameraAt(plan, t);
const cx = safe.x + safe.w / 2;
for (const e of cards) {
const x0 = cx + (e.box.x - e.box.w / 2 - cam.x) * cam.z;
const x1 = cx + (e.box.x + e.box.w / 2 - cam.x) * cam.z;
assert.ok(x0 >= usable.x0 - 0.5 && x1 <= usable.x1 + 0.5, `t=${t}: ${x0.toFixed(1)}..${x1.toFixed(1)}`);
}
}
});
// Boxes given by their center, as the engine measures them.
const centered = (kind, x, y, w, h, at, out = Infinity, extra = {}) => ({ kind, box: { x, y, w, h }, at, out, ...extra });
const whole = (shot, e, v = view) => {
const r = frameRect(shot, v, frame);
return e.box.x - e.box.w / 2 >= r.x0 - 0.5 && e.box.x + e.box.w / 2 <= r.x1 + 0.5 && e.box.y - e.box.h / 2 >= r.y0 - 0.5 && e.box.y + e.box.h / 2 <= r.y1 + 0.5;
};
test('a move that keeps something new whole is made however small it is', () => {
const wide = { x: 76, y: 76, w: 1768, h: 928 };
const items = [centered('shape', 1525, 650, 500, 100, 0), centered('shape', 1000, 450, 550, 300, 3), centered('shape', 900, 300, 400, 100, 4.5), centered('shape', 1200, 900, 500, 200, 6)];
const plan = planCamera(items, { dur: 14, view: wide, frame, voiceEnd: 12 });
for (let t = 6.2; t < 13.9; t += 0.1) if (!cameraMoving(plan, t)) assert.ok(whole(cameraAt(plan, t), items[3], wide), `t=${t.toFixed(1)}`);
});
test('a focus region is framed whole, and an arrow that fits does not cancel it', () => {
const pan = [centered('code', 960, 540, 1600, 700, 0), centered('focus', 600, 540, 200, 80, 0, 3.9, { explicit: true }), centered('focus', 1050, 540, 200, 80, 4, Infinity, { explicit: true })];
const p1 = planCamera(pan, { dur: 14, view, frame, voiceEnd: 12 });
assert.ok(whole(cameraAt(p1, 6), pan[2]));
const arrow = [centered('shape', 960, 540, 1400, 700, 0), centered('focus', 960, 540, 200, 80, 3, Infinity, { explicit: true }), centered('arrow', 960, 700, 500, 20, 3.9)];
const p2 = planCamera(arrow, { dur: 14, view, frame, voiceEnd: 12 });
assert.ok(cameraAt(p2, 6).z > 1.5, 'the close-up happens');
});
test('a push in is held for a while before the camera pulls back', () => {
const items = [centered('shape', 500, 350, 600, 300, 0), centered('shape', 1400, 350, 600, 300, 0), centered('text', 1400, 725, 300, 50, 8.5)];
const plan = planCamera(items, { dur: 12, view, frame, voiceEnd: 10 });
for (let i = 0; i < plan.moves.length; i++) {
const m = plan.moves[i];
if (m.to.z <= m.from.z * 1.1) continue;
const next = plan.moves[i + 1]?.start ?? 12;
assert.ok(next - (m.start + m.dur) >= 1.5 - 1e-9, `held ${(next - m.start - m.dur).toFixed(2)}s`);
}
});
test('a large chart is the picture, and a label inside it gets no close-up', () => {
const items = [centered('chart', 960, 540, 1600, 800, 0), centered('line', 960, 540, 1400, 0, 3), centered('text', 960, 700, 160, 40, 6.5)];
const plan = planCamera(items, { dur: 12, view, frame, voiceEnd: 10 });
for (let t = 0.1; t < 11.9; t += 0.5) assert.ok(whole(cameraAt(plan, t), items[0]), `t=${t.toFixed(1)}`);
});
test('a push in makes way for a focus point that comes soon after', () => {
const items = [centered('shape', 500, 350, 600, 300, 0), centered('shape', 1400, 350, 600, 300, 0), centered('text', 500, 725, 300, 50, 3), centered('focus', 1400, 350, 200, 80, 5.5, Infinity, { explicit: true })];
const plan = planCamera(items, { dur: 12, view, frame, voiceEnd: 10 });
for (let i = 0; i < plan.moves.length; i++) {
const m = plan.moves[i];
const next = plan.moves[i + 1]?.start ?? 12;
if (m.to.z > m.from.z * 1.1) assert.ok(next - (m.start + m.dur) >= 1.5 - 1e-9, `held ${(next - m.start - m.dur).toFixed(2)}s`);
}
assert.ok(whole(cameraAt(plan, 8), items[3]) && cameraAt(plan, 8).z > 1.5, 'the focus gets its close-up');
});
test('a scene too short for the pull-back still ends on the whole picture', () => {
// Three steps in a row; the last one comes a second before the scene ends.
// They stay until the end, also when they leave right at the end.
for (const out of [Infinity, 5.6]) {
const steps = [0, 1, 2].map((i) => el('shape', 300 + i * 520, 470, 260, 140, [0.3, 2.4, 4.4][i], out));
const plan = planCamera(steps, { dur: 5.6, view, frame, voiceEnd: 5 });
const end = cameraAt(plan, 5.55);
for (const e of steps) assert.ok(whole(end, e), `step at ${e.at}, out ${out}`);
}
});
test('a last move in that becomes a wide shot keeps later things whole', () => {
const boxes = [[1383, 438, 382, 227, 0], [1632, 306, 119, 209, 0.89], [622, 541, 303, 71, 1.38], [737, 839, 113, 70, 2.19], [252, 632, 252, 163, 3.06]];
const items = boxes.map(([x, y, w, h, at]) => centered('shape', x, y, w, h, at));
const plan = planCamera(items, { dur: 5.7, view, frame, pace: 1 });
const settled = Math.max(3.06, ...plan.moves.map((m) => m.start + m.dur));
for (let t = settled + 0.05; t < 5.7; t += 0.1) assert.ok(whole(cameraAt(plan, t), items[4]), `t=${t.toFixed(2)}`);
});
test('a continued scene also ends on the whole picture', () => {
const items = [centered('shape', 350, 540, 260, 140, 0), centered('shape', 850, 540, 260, 140, 0), centered('shape', 1450, 540, 260, 140, 3.5)];
const plan = planCamera(items, { dur: 4.8, view, frame, from: { x: 600, y: 540, z: 1.7 }, still: 0.7 });
const end = cameraAt(plan, 4.75);
for (const e of items) assert.ok(whole(end, e), `box at ${e.box.x}`);
});
test("an arrow's label is kept whole, and a labelled arrow gets no close-up", () => {
const els = [
el('shape', 300, 420, 300, 160, 0.3),
el('shape', 1100, 420, 300, 160, 0.3),
el('arrow', 600, 480, 500, 40, 4),
el('label', 700, 380, 300, 40, 4),
el('shape', 1300, 760, 300, 120, 9),
];
const plan = planCamera(els, { dur: 14, view, frame });
assert.ok(!plan.moves.some((m) => m.start > 3 && m.start < 5.5), JSON.stringify(plan.moves.map((m) => m.start)));
for (let t = 0; t < 14; t += 0.05) {
if (cameraMoving(plan, t)) continue;
const shown = els.filter((e) => e.at <= t && e.out > t);
assert.deepEqual(cuts(cameraAt(plan, t), shown), [], `t=${t.toFixed(2)}`);
}
// A close-up next to an arrow leaves its label out or takes it in.
const label = el('label', 520, 300, 360, 50, 0);
const shot = compose([el('shape', 860, 360, 200, 120, 0)], [label, el('arrow', 400, 360, 460, 30, 0)], view, frame);
assert.ok(shot.z > 1.2, `z ${shot.z}`);
assert.deepEqual(cuts(shot, [label]), []);
});
test('an icon or shape without words gets no close-up of its own', () => {
// The picture fills the frame from the start, so the icon fits the shot.
const picture = [el('text', 560, 120, 800, 120, 0.2), el('shape', 150, 400, 300, 300, 0.2), el('shape', 1470, 400, 300, 300, 0.2)];
const plan = (icon) => planCamera([...picture, icon], { dur: 12, view, frame, voiceEnd: 11 });
const icon = el('icon', 900, 600, 120, 120, 3);
const bare = plan({ ...icon, bare: true });
assert.ok(!bare.moves.some((m) => m.start > 2 && m.start < 4 && m.to.z > m.from.z * 1.2), JSON.stringify(bare.moves));
const labelled = plan({ ...icon, box: { ...icon.box, h: 190 } });
assert.ok(labelled.moves.some((m) => m.start > 2 && m.start < 4 && m.to.z > m.from.z * 1.2), JSON.stringify(labelled.moves));
});
test("an arrow's label does not count on its own when a scene continues the one before", () => {
const card = (x) => el('shape', x, 450, 260, 140, 0.5);
const arrow = (x) => el('arrow', x, 500, 300, 40, 1);
const label = (x) => el('label', x + 60, 440, 180, 40, 1);
const a = [card(200), card(780), arrow(470), label(470), card(1360), arrow(1050), label(1050)];
const b = [card(200), card(780), card(1360), arrow(470), label(470)].map((e) => ({ ...e, at: -1 }));
assert.equal(continues(a, b, { x0: 0, y0: 0, x1: 1920, y1: 1080 }), continues(a.filter((e) => e.kind !== 'label'), b.filter((e) => e.kind !== 'label'), { x0: 0, y0: 0, x1: 1920, y1: 1080 }));
const two = [card(200), card(780), arrow(470), label(470), arrow(1050), label(1050)];
const one = [card(200), card(780), arrow(470)].map((e) => ({ ...e, at: -1 }));
assert.ok(continues(two, one, { x0: 0, y0: 0, x1: 1920, y1: 1080 }));
});