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 fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import http from 'node:http';
import { findChrome, launch } from '../src/browser.js';
import { loadProject } from '../src/project.js';
import { exportPlayer } from '../src/export.js';
import { withEngine } from '../src/pipeline.js';
import { ffmpeg, probe } from '../src/ffmpeg.js';
import { ROOT } from '../src/server.js';
let chrome;
try { chrome = findChrome(); } catch {}
async function servePlayer(dir, ranges = true) {
const types = { '.html': 'text/html', '.js': 'text/javascript', '.mjs': 'text/javascript', '.json': 'application/json', '.vtt': 'text/vtt', '.m4a': 'audio/mp4', '.mp4': 'video/mp4', '.svg': 'image/svg+xml', '.woff2': 'font/woff2' };
const server = http.createServer((req, res) => {
const url = new URL(req.url, 'http://localhost');
const rel = decodeURIComponent(url.pathname).replace(/^\/docs\/video\//, '');
const file = path.resolve(dir, rel);
if (!url.pathname.startsWith('/docs/video/') || !file.startsWith(dir + path.sep) || !fs.existsSync(file) || !fs.statSync(file).isFile()) { res.writeHead(404); res.end(); return; }
const size = fs.statSync(file).size;
const range = ranges && /^bytes=(\d+)-(\d*)$/.exec(req.headers.range || '');
const start = range ? Number(range[1]) : 0;
const end = range?.[2] ? Math.min(size - 1, Number(range[2])) : size - 1;
res.writeHead(range ? 206 : 200, { 'Content-Type': types[path.extname(file)] || 'application/octet-stream', 'Content-Length': end - start + 1, ...(ranges ? { 'Accept-Ranges': 'bytes' } : {}), ...(range ? { 'Content-Range': `bytes ${start}-${end}/${size}` } : {}) });
fs.createReadStream(file, { start, end }).pipe(res);
});
await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
return { url: `http://127.0.0.1:${server.address().port}/docs/video/`, close: () => new Promise(resolve => { server.closeAllConnections(); server.close(resolve); }) };
}
test('exported player runs at a sub-path with matching frames, clips and accessible controls', { skip: !chrome }, async t => {
const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'explainroo-player-browser-'));
t.after(() => fs.rmSync(dir, { recursive: true, force: true }));
fs.mkdirSync(path.join(dir, 'assets'));
fs.writeFileSync(path.join(dir, 'assets/used.svg'), '<svg xmlns="http://www.w3.org/2000/svg" width="100" height="100"><circle cx="50" cy="50" r="40" fill="#245cff"/></svg>');
fs.writeFileSync(path.join(dir, 'assets/unused.svg'), '<svg xmlns="http://www.w3.org/2000/svg" width="100" height="100"/>');
fs.writeFileSync(path.join(dir, 'assets/secret.json'), '{"key":"SECRET"}');
fs.writeFileSync(path.join(dir, '.env'), 'SECRET');
fs.copyFileSync(path.join(ROOT, 'fonts/Inter-400-latin.woff2'), path.join(dir, 'assets/unused.woff2'));
await ffmpeg(['-loglevel', 'error', '-f', 'lavfi', '-i', 'color=red:s=160x90:r=30:d=1', '-f', 'lavfi', '-i', 'color=lime:s=160x90:r=30:d=1', '-filter_complex', '[0:v][1:v]concat=n=2:v=1:a=0[v]', '-map', '[v]', '-c:v', 'libx264', '-threads', '1', path.join(dir, 'assets/clip.mp4')]);
fs.writeFileSync(path.join(dir, 'video.json'), JSON.stringify({ theme: 'clean', music: false, sfx: false, end: 0, fonts: [{ family: 'Unused', src: 'assets/unused.woff2' }] }));
fs.writeFileSync(path.join(dir, 'script.md'), '# Player fixture\n## intro {min=12}\n');
fs.writeFileSync(path.join(dir, 'helper.mjs'), "export const label = 'Player fixture';");
fs.writeFileSync(path.join(dir, 'scenes.js'), `const modulePath = './helper.mjs';
const { label } = await import(modulePath);
export default { intro(s) {
s.title(label, { y: 220, enter: 'none' });
s.math('E=mc^2', { y: 440, enter: 'none' });
s.image('assets/used.svg', { x: 1600, y: 440, w: 160, enter: 'none' });
s.clip('assets/clip.mp4', { y: 760, w: 480, at: 2, out: 4, enter: 'none', shadow: false, radius: 0 });
} };`);
const project = loadProject(dir);
const output = await exportPlayer(project);
assert.equal(output.out, path.join(dir, 'out/player'));
for (const name of ['audio.m4a', 'poster.jpg', 'subtitles.vtt']) assert.ok(fs.existsSync(path.join(output.out, name)));
assert.ok(!fs.existsSync(path.join(output.out, 'project/build')));
assert.ok(fs.existsSync(path.join(output.out, 'project/helper.mjs')));
assert.deepEqual(fs.readdirSync(path.join(output.out, 'project/assets')).sort(), ['clip.mp4', 'used.svg']);
const exportedState = JSON.parse(fs.readFileSync(path.join(output.out, 'state.json'), 'utf8'));
assert.deepEqual(exportedState.config.fonts, []);
const audioInfo = await probe(path.join(output.out, 'audio.m4a'));
assert.equal(audioInfo.streams[0].codec_name, 'aac');
assert.ok(Math.abs(Number(audioInfo.format.duration) - 12) < 0.1);
// A cue exercises the browser's native TextTrack parsing and the HTML overlay.
fs.writeFileSync(path.join(output.out, 'subtitles.vtt'), 'WEBVTT\n\n00:00:00.000 --> 00:00:10.000\nReadable & accessible\n');
const timeline = JSON.parse(fs.readFileSync(path.join(project.paths.build, 'timeline.json'), 'utf8'));
let reference;
await withEngine(project, timeline, {}, async page => {
await page.evaluate(() => window.explainroo.stills([{ T: 0, path: 'out/reference.png' }]));
reference = fs.readFileSync(path.join(project.paths.out, 'reference.png')).toString('base64');
});
const server = await servePlayer(output.out);
t.after(() => server.close());
const browser = await launch();
t.after(() => browser.close());
const context = await browser.newContext({ viewport: { width: 1920, height: 1080 } });
const page = await context.newPage();
const errors = [];
const requests = [];
page.on('pageerror', e => errors.push(e.message));
page.on('request', req => requests.push(req.url()));
await page.goto(server.url + 'index.html?muted=1');
await page.evaluate(() => window.explainrooReady);
assert.equal(await page.locator('#poster').isVisible(), true);
assert.equal(await page.locator('#audio').evaluate(a => a.paused), true);
assert.ok(!requests.some(url => url.endsWith('/audio.m4a')));
assert.equal(await page.locator('#cc').getAttribute('aria-pressed'), 'false');
assert.equal(await page.getByRole('button', { name: 'Play', exact: true }).count(), 1);
assert.equal(await page.locator('#controls').isVisible(), false);
assert.equal(await page.locator('#start').isVisible(), true);
for (const [id, label] of [['mute', 'Unmute'], ['cc', 'Show captions'], ['fullscreen', 'Enter fullscreen']]) assert.equal(await page.locator(`#${id}`).getAttribute('aria-label'), label);
assert.equal(await page.locator('#seek').getAttribute('aria-label'), 'Seek');
const icons = JSON.parse(fs.readFileSync(path.join(ROOT, 'engine/icons/lucide.json'), 'utf8')).icons;
for (const [id, name] of [['play', 'play'], ['mute', 'volume-x'], ['cc', 'closed-caption'], ['fullscreen', 'maximize']]) {
assert.deepEqual(await page.locator(`#${id} path`).evaluateAll(paths => paths.map(path => path.getAttribute('d'))), icons[name]);
assert.equal(await page.locator(`#${id}`).getAttribute('title'), await page.locator(`#${id}`).getAttribute('aria-label'));
}
await page.locator('#poster').click({ position: { x: 40, y: 40 } });
await page.waitForFunction(() => Number(document.querySelector('#seek').value) > 0.15);
assert.ok(await page.locator('#audio').evaluate(a => a.currentTime > 0.1 && !a.paused));
await page.keyboard.press('k');
assert.equal(await page.getByRole('button', { name: 'Play', exact: true }).count(), 1);
assert.equal(await page.locator('#poster').isVisible(), false);
assert.equal(await page.locator('#start').isVisible(), false);
assert.equal(await page.locator('#controls').isVisible(), true);
for (const label of ['Play', 'Unmute', 'Show captions', 'Enter fullscreen']) assert.equal(await page.getByRole('button', { name: label, exact: true }).count(), 1);
assert.equal(await page.getByRole('slider', { name: 'Seek' }).count(), 1);
await page.locator('#seek').evaluate(input => { input.value = 0; input.dispatchEvent(new Event('input')); });
const difference = await page.evaluate(async base64 => {
const image = new Image(); image.src = 'data:image/png;base64,' + base64; await image.decode();
const canvas = document.querySelector('#c');
const other = document.createElement('canvas'); other.width = canvas.width; other.height = canvas.height;
const ctx = other.getContext('2d'); ctx.drawImage(image, 0, 0);
const a = canvas.getContext('2d').getImageData(0, 0, canvas.width, canvas.height).data;
const b = ctx.getImageData(0, 0, canvas.width, canvas.height).data;
let error = 0; for (let i = 0; i < a.length; i++) error += Math.abs(a[i] - b[i]);
return error / a.length;
}, reference);
assert.ok(difference < 0.2, `mean pixel error ${difference}`);
await page.locator('#player').focus();
await page.keyboard.press('ArrowRight');
assert.equal(Number(await page.locator('#seek').inputValue()), 5);
await page.keyboard.press('ArrowLeft');
assert.equal(Number(await page.locator('#seek').inputValue()), 0);
await page.keyboard.press('m');
assert.equal(await page.locator('#audio').evaluate(a => a.muted), false);
assert.equal(await page.locator('#mute').getAttribute('title'), 'Mute');
assert.equal(await page.locator('#mute').getAttribute('data-icon'), 'volume-2');
await page.keyboard.press('m');
await page.keyboard.press('Space');
await page.waitForFunction(() => document.querySelector('#play').getAttribute('aria-label') === 'Pause');
assert.equal(await page.locator('#play').getAttribute('title'), 'Pause');
assert.equal(await page.locator('#play').getAttribute('data-icon'), 'pause');
await page.waitForFunction(() => getComputedStyle(document.querySelector('#controls')).opacity === '0');
await page.mouse.move(20, 20);
await page.waitForFunction(() => getComputedStyle(document.querySelector('#controls')).opacity === '1');
await page.locator('#play').focus();
await page.waitForTimeout(2200);
assert.equal(await page.locator('#controls').evaluate(el => getComputedStyle(el).opacity), '1');
assert.equal(await page.locator('#play').evaluate(el => getComputedStyle(el).outlineStyle), 'solid');
await page.locator('#player').focus();
await page.keyboard.press('Space');
await page.locator('#cc').click();
await page.waitForFunction(() => document.querySelector('#captions').textContent === 'Readable & accessible');
assert.equal(await page.locator('#cc').getAttribute('aria-pressed'), 'true');
assert.equal(await page.locator('#cc').getAttribute('title'), 'Hide captions');
assert.notEqual(await page.locator('#cc').evaluate(el => getComputedStyle(el, '::after').backgroundColor), 'rgba(0, 0, 0, 0)');
await page.locator('#seek').evaluate(input => { input.value = 3.5; input.dispatchEvent(new Event('input')); });
await page.waitForFunction(() => {
const c = document.querySelector('#c'); const p = c.getContext('2d').getImageData(c.width / 2, c.height * 760 / 1080, 1, 1).data;
return p[1] > 240 && p[0] < 15;
});
await page.locator('#seek').evaluate(input => { input.value = 2.5; input.dispatchEvent(new Event('input')); });
await page.waitForFunction(() => {
const c = document.querySelector('#c'); const p = c.getContext('2d').getImageData(c.width / 2, c.height * 760 / 1080, 1, 1).data;
return p[0] > 240 && p[1] < 15;
});
await page.locator('#player').focus();
await page.keyboard.press('f');
await page.waitForFunction(() => !!document.fullscreenElement);
// The label follows the fullscreenchange event, a moment after the element changes.
await page.waitForFunction(() => document.querySelector('#fullscreen').getAttribute('aria-label') === 'Exit fullscreen');
assert.equal(await page.getByRole('button', { name: 'Exit fullscreen' }).count(), 1);
assert.equal(await page.locator('#fullscreen').getAttribute('title'), 'Exit fullscreen');
assert.equal(await page.locator('#fullscreen').getAttribute('data-icon'), 'minimize');
await page.keyboard.press('k');
await page.waitForFunction(() => getComputedStyle(document.querySelector('#controls')).opacity === '0');
assert.equal(await page.locator('#player').evaluate(el => getComputedStyle(el).cursor), 'none');
await page.locator('#player').dispatchEvent('pointerdown', { pointerType: 'touch' });
await page.waitForFunction(() => getComputedStyle(document.querySelector('#controls')).opacity === '1');
assert.notEqual(await page.locator('#player').evaluate(el => getComputedStyle(el).cursor), 'none');
await page.keyboard.press('k');
await page.keyboard.press('f');
await page.waitForFunction(() => !document.fullscreenElement);
await page.setViewportSize({ width: 480, height: 320 });
await page.waitForFunction(() => document.querySelector('#c').width === 480);
assert.equal(await page.locator('#player').evaluate(el => Math.round(el.getBoundingClientRect().height)), 270);
await page.setViewportSize({ width: 320, height: 240 });
const layout = await page.locator('#controls').evaluate(el => {
const bounds = el.getBoundingClientRect();
return [...el.querySelectorAll('button,input,#time')].map(child => {
const box = child.getBoundingClientRect();
return { inside: box.left >= bounds.left && box.right <= bounds.right, target: child.tagName === 'SPAN' || (box.width >= 40 && box.height >= 40) };
});
});
assert.ok(layout.every(el => el.inside && el.target));
await page.emulateMedia({ reducedMotion: 'reduce' });
assert.equal(await page.locator('#controls').evaluate(el => getComputedStyle(el).transitionDuration), '0s');
await page.reload();
await page.evaluate(() => window.explainrooReady);
assert.equal(await page.locator('#cc').getAttribute('aria-pressed'), 'true');
assert.equal(await page.locator('#poster').isVisible(), true);
await page.keyboard.press('k');
await page.waitForFunction(() => document.querySelector('#play').getAttribute('aria-label') === 'Pause');
await page.keyboard.press('k');
await page.goto(server.url + 'index.html?autoplay=1&muted=1&t=6.5');
await page.evaluate(() => window.explainrooReady);
await page.waitForFunction(() => Number(document.querySelector('#seek').value) > 6.6);
assert.equal(await page.locator('#audio').evaluate(a => a.muted), true);
assert.deepEqual(errors, []);
assert.ok(requests.every(url => url.startsWith(server.url)), requests.join('\n'));
assert.ok(!requests.some(url => /__math|__clip|__state|__upload|build\/clips/.test(url)));
await page.route('**/audio.m4a', route => route.abort());
await page.goto(server.url + 'index.html?autoplay=1&muted=1&t=6.5');
await page.evaluate(() => window.explainrooReady);
await page.waitForFunction(() => Number(document.querySelector('#seek').value) > 6.7);
assert.ok(await page.locator('#audio').evaluate(a => !!a.error));
await page.unroute('**/audio.m4a');
const basic = await servePlayer(output.out, false);
t.after(() => basic.close());
await page.goto(basic.url + 'index.html?muted=1&t=3.5');
await page.evaluate(() => window.explainrooReady);
assert.ok(await page.locator('video').evaluate(v => v.src.startsWith('blob:')));
await page.locator('#start').click();
await page.waitForFunction(() => document.querySelector('#audio').src.startsWith('blob:') && document.querySelector('#audio').currentTime > 3.5);
await page.keyboard.press('k');
await page.locator('#seek').evaluate(input => { input.value = 2.5; input.dispatchEvent(new Event('input')); });
await page.waitForFunction(() => Math.abs(document.querySelector('video').currentTime - 0.5) < 0.05);
await page.waitForFunction(() => Math.abs(document.querySelector('#audio').currentTime - 2.5) < 0.05);
});