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
Render transparent WebM and MOV for video editors (#13)
Vincent Schmalbached16325e32d9
diff --git a/AGENTS.md b/AGENTS.mdindex 10d3c9b..1d8fed1 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -670,11 +670,11 @@ when `ink` or `muted` has too little contrast against `bg`.| `init <dir>` | creates a project (`--theme`, `--size`, `--pace`, `--voice`, `--title`) || `voice [project]` | makes the narration and the word times, saved per scene so only changed scenes are made again || `preview [project]` | a live preview in the browser that reloads when you save |-| `still [project] [times]` | PNG pictures at `12.5`, `scene`, `[email protected]` or `scene@end` |+| `still [project] [times]` | PNG pictures at `12.5`, `scene`, `[email protected]` or `scene@end` (`--transparent` keeps alpha) || `sheet [project]` | one image with many frames of the video or of one scene (`--scene`, `--every`) || `check [project]` | finds layout, timing and pronunciation problems |-| `render [project]` | the MP4 plus subtitle files, chapters and a cover (`--format gif`, `--draft`, `--from`, `--to`, `--workers`, `--out`) |-| `verify [project]` | checks the finished file: loudness, black frames, silence, clear voice |+| `render [project]` | the video plus subtitle files, chapters and a cover (`--format mp4`, `gif`, `webm` or `mov`, `--transparent`, `--draft`, `--from`, `--to`, `--workers`, `--out`) |+| `verify [project]` | checks the finished MP4, WebM or MOV: loudness, black frames, silence, clear voice (`--file` picks another file) || `capture [project] <url>` | saves screenshots, wording, colors, fonts and logos from a live site (`--mobile`, `--json`) || `image [project] <name> "<prompt>"` | makes an illustration with OpenRouter || `images [project]` | lists the images and what they cost |@@ -690,6 +690,24 @@ With `--out`, the file ending must match the format. A render of part of thevideo (`--from`, `--to`) skips the chapters and the cover. A video withoutnarration gets no subtitle files.+### Transparent video for editors++To put a diagram or a lower third over camera footage, render with an alpha+channel: `render --transparent --format mov` for video editors (ProRes 4444)+or `--format webm` for the web (VP9). The look's background texture is left+out. Everything the scene paints stays, including `s.bg()` and+`s.ui.backdrop()`, and cards, captions and the watermark keep their own+backgrounds. Keep elements readable on footage: use cards or the `bg` option+of text.++The files are `out/video.mov` or `out/video.webm` (`draft.*` with+`--draft`), and the cover stays an opaque JPEG. `slide`, `wipe` and `brush`+transitions become `fade` in a transparent video. Check frames with+`still --transparent`, which keeps the alpha, and the file with+`verify --file out/video.mov`, which skips the black-frame check for+transparent video. Without `--transparent`, WebM and MOV are ordinary opaque+videos.+## Scene APIEach scene function draws one frame. explainroo calls it for every frame withdiff --git a/engine/frame.html b/engine/frame.htmlindex 5079e2e..27875e8 100644--- a/engine/frame.html+++ b/engine/frame.html@@ -12,7 +12,9 @@ import { boot, renderAudio } from '/engine/runtime.js';import { upload } from '/engine/upload.js';const canvas = document.getElementById('c');-const scale = Number(new URLSearchParams(location.search).get('scale') || 1);+const params = new URLSearchParams(location.search);+const scale = Number(params.get('scale') || 1);+const transparent = params.get('transparent') === '1';function describe(e) {const where = e.scene ? ` (scene "${e.scene}" at ${Number(e.sceneTime).toFixed(2)}s)` : '';@@ -20,7 +22,7 @@ function describe(e) {}window.explainrooReady = (async () => {- const { engine, audio, state } = await boot({ canvas, scale });+ const { engine, audio, state } = await boot({ canvas, scale, transparent });const fps = state.config.fps;window.explainroo = {info() {@@ -35,7 +37,7 @@ window.explainrooReady = (async () => {} catch (e) {throw new Error(describe(e));}- out.push(canvas.toDataURL('image/jpeg', quality).slice(23));+ out.push(transparent ? canvas.toDataURL('image/png').slice(22) : canvas.toDataURL('image/jpeg', quality).slice(23));}return out;},diff --git a/engine/runtime.js b/engine/runtime.jsindex 81045be..0a84f3b 100644--- a/engine/runtime.js+++ b/engine/runtime.js@@ -60,7 +60,7 @@ async function loadImages(assets) {}export class Engine {- constructor({ canvas, state, scenes, icons, images, clips = new Map(), scale = 1, sfxNames = [] }) {+ constructor({ canvas, state, scenes, icons, images, clips = new Map(), scale = 1, transparent = false, sfxNames = [] }) {const { config, timeline } = state;this.state = state;this.config = config;@@ -75,6 +75,7 @@ export class Engine {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;@@ -95,8 +96,8 @@ export class Engine {// 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: false });- this.background = makeBackground(this.theme, this.W, this.H, config.seed);+ 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');@@ -212,15 +213,20 @@ export class Engine {transitionFor(sc) {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';- ctx.drawImage(this.background, 0, 0, this.W, this.H);+ if (this.background) 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}`));@@ -249,9 +255,13 @@ export class Engine {if (i > 0 && sc.transition !== 'none' && trName !== 'cut' && t < trDur) {const prev = this.timeline.scenes[i - 1];const [a, b] = this.buffers;- this.drawScene(a.getContext('2d', { alpha: false }), i - 1, T - prev.start);- this.drawScene(b.getContext('2d', { alpha: false }), i, t);- drawTransition(trName, ctx, a, b, t / trDur, this.W, this.H, hashStr(sc.id));+ if (this.transparent) {+ ctx.setTransform(1, 0, 0, 1, 0, 0);+ ctx.clearRect(0, 0, ctx.canvas.width, ctx.canvas.height);+ }+ 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);}@@ -512,7 +522,7 @@ export class Engine {}// Boots the engine for render, check or studio pages.-export async function boot({ canvas, scale = 1, version = '' }) {+export async function boot({ canvas, scale = 1, transparent = false, version = '' }) {const state = await fetchState();const theme = getTheme(state.config.theme, state.config.look);const [icons, images, scenesMod, audio, iconTags, clips] = await Promise.all([@@ -530,7 +540,7 @@ export async function boot({ canvas, scale = 1, version = '' }) {]);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, sfxNames: Object.keys(audio.SFX) });+ const engine = new Engine({ canvas, state, scenes, icons, images, clips, scale, transparent, sfxNames: Object.keys(audio.SFX) });engine.iconTags = iconTags;await engine.loadMath();return { engine, audio, state };diff --git a/engine/transitions.js b/engine/transitions.jsindex 7ad9d48..0d1c3ca 100644--- a/engine/transitions.js+++ b/engine/transitions.js@@ -4,7 +4,7 @@ import { ease, mulberry32, hashStr } from './util.js';export const TRANSITION_NAMES = ['fade', 'slide', 'wipe', 'zoom', 'brush', 'cut'];-export function drawTransition(name, ctx, from, to, p, W, H, seed = 1) {+export function drawTransition(name, ctx, from, to, p, W, H, seed = 1, transparent = false) {const e = ease.inOut(p);ctx.save();ctx.setTransform(1, 0, 0, 1, 0, 0);@@ -12,7 +12,9 @@ export function drawTransition(name, ctx, from, to, p, W, H, seed = 1) {const ch = ctx.canvas.height;switch (name) {case 'fade':+ if (transparent) ctx.globalAlpha = 1 - e;ctx.drawImage(from, 0, 0);+ if (transparent) ctx.globalCompositeOperation = 'lighter';ctx.globalAlpha = e;ctx.drawImage(to, 0, 0);break;@@ -50,6 +52,7 @@ export function drawTransition(name, ctx, from, to, p, W, H, seed = 1) {ctx.drawImage(from, -cw / 2, -ch / 2);ctx.restore();ctx.save();+ if (transparent) ctx.globalCompositeOperation = 'lighter';ctx.globalAlpha = e;const s2 = 0.94 + 0.06 * e;ctx.translate(cw / 2, ch / 2);diff --git a/src/browser.js b/src/browser.jsindex da64157..5ecb2df 100644--- a/src/browser.js+++ b/src/browser.js@@ -85,14 +85,14 @@ export async function launch() {// Opens the render page and waits until the engine has loaded fonts, icons,// images and the scenes module. Throws with the page's error if boot fails.-export async function openEngine(browser, serverUrl, { scale = 1, onConsole } = {}) {+export async function openEngine(browser, serverUrl, { scale = 1, transparent = false, onConsole } = {}) {const page = await browser.newPage({ viewport: { width: 800, height: 600 }, deviceScaleFactor: 1 });const errors = [];page.on('pageerror', (e) => errors.push(e));page.on('console', (m) => {if (onConsole) onConsole(m.type(), m.text());});- await page.goto(`${serverUrl}/frame.html?scale=${scale}`, { waitUntil: 'load' });+ await page.goto(`${serverUrl}/frame.html?scale=${scale}${transparent ? '&transparent=1' : ''}`, { waitUntil: 'load' });const boot = await page.evaluate(async () => {try {await window.explainrooReady;diff --git a/src/cli.js b/src/cli.jsindex 402118f..4ae5102 100644--- a/src/cli.js+++ b/src/cli.js@@ -26,12 +26,12 @@ Make a videoinit <dir> create a project (--theme, --size, --pace, --voice, --title)voice [project] make the narration (Kokoro, ElevenLabs or a recording) and word timingspreview [project] live preview in your browser, reloads on save (--port)- still [project] [t…] PNG stills: "12.5", "scene", "[email protected]" (default: end of every scene)+ still [project] [t…] PNG stills: "12.5", "scene", "[email protected]" (--transparent, default: end of every scene)sheet [project] contact sheet of the whole video (--scene id, --every s)check [project] find layout, timing and pronunciation problems (--view-width pixels)- render [project] write the MP4 with subtitles, chapters and a cover (--format gif,- --draft, --from s, --to s, --workers n, --out file)- verify [project] check an MP4: loudness, black frames, narration+ render [project] write the video with subtitles, chapters and a cover (--format mp4|gif|webm|mov,+ --transparent, --draft, --from s, --to s, --workers n, --out file)+ verify [project] check the video: loudness, black frames, narration (--file)Product demoscapture [project] <url> save screenshots, wording, colors, fonts and logo of a live site (--mobile)@@ -67,7 +67,7 @@ function parseArgs(argv) {}return { pos, flags };}-const BOOL = new Set(['json', 'draft', 'force', 'fetch', 'help', 'version', 'quiet', 'open', 'no-style', 'elevenlabs', 'mobile']);+const BOOL = new Set(['json', 'draft', 'transparent', 'force', 'fetch', 'help', 'version', 'quiet', 'open', 'no-style', 'elevenlabs', 'mobile']);function num(v, name) {if (v === undefined) return undefined;@@ -130,7 +130,7 @@ export async function main(argv) {case 'still': {const isProject = pos[0] && fs.existsSync(path.join(pos[0], 'video.json'));const project = loadProject(isProject ? pos.shift() : undefined);- const list = await stills(project, pos, { log, scale: num(flags.scale, 'scale') ?? 1 });+ const list = await stills(project, pos, { log, scale: num(flags.scale, 'scale') ?? 1, transparent: !!flags.transparent });print(list.map((s) => `${s.label.padEnd(24)} ${s.file}`).join('\n'), { stills: list });return 0;}@@ -152,7 +152,7 @@ export async function main(argv) {}case 'render': {const project = loadProject(pos[0]);- const r = await render(project, { log, draft: !!flags.draft, from: num(flags.from, 'from'), to: num(flags.to, 'to'), workers: num(flags.workers, 'workers'), scale: num(flags.scale, 'scale'), out: textFlag(flags, 'out'), format: textFlag(flags, 'format') });+ const r = await render(project, { log, draft: !!flags.draft, transparent: !!flags.transparent, from: num(flags.from, 'from'), to: num(flags.to, 'to'), workers: num(flags.workers, 'workers'), scale: num(flags.scale, 'scale'), out: textFlag(flags, 'out'), format: textFlag(flags, 'format') });print([r.out, r.subtitles?.srt, r.subtitles?.vtt, r.chapters, r.cover].filter(Boolean).map((f) => path.relative(process.cwd(), f) || f).join('\n'), r);return 0;}diff --git a/src/ffmpeg.js b/src/ffmpeg.jsindex 418515d..860bb2d 100644--- a/src/ffmpeg.js+++ b/src/ffmpeg.js@@ -36,13 +36,17 @@ export function ffmpeg(args, opts) {return run(ffmpegPath(), ['-hide_banner', '-y', ...args], opts);}-// A long-running encoder fed with JPEG frames on stdin.-export function frameEncoder({ fps, out, draft }) {+// A long-running encoder fed with JPEG or PNG frames on stdin.+export function frameEncoder({ fps, out, draft, format = 'mp4', transparent = false }) {+ const codec = format === 'webm'+ ? ['-c:v', 'libvpx-vp9', '-crf', draft ? '32' : '24', '-b:v', '0', '-deadline', 'good', '-cpu-used', draft ? '4' : '2', '-auto-alt-ref', '0', '-pix_fmt', transparent ? 'yuva420p' : 'yuv420p', '-r', String(fps), '-g', String(fps * 2)]+ : format === 'mov'+ ? ['-c:v', 'prores_ks', '-profile:v', '4', '-pix_fmt', transparent ? 'yuva444p10le' : 'yuv444p10le', '-r', String(fps)]+ : ['-c:v', 'libx264', '-preset', draft ? 'veryfast' : 'medium', '-crf', draft ? '24' : '17', '-tune', 'animation', '-pix_fmt', 'yuv420p', '-r', String(fps), '-g', String(fps * 2)];const args = ['-hide_banner', '-y', '-loglevel', 'error',- '-f', 'image2pipe', '-framerate', String(fps), '-c:v', 'mjpeg', '-i', '-',- '-c:v', 'libx264', '-preset', draft ? 'veryfast' : 'medium', '-crf', draft ? '24' : '17',- '-tune', 'animation', '-pix_fmt', 'yuv420p', '-r', String(fps), '-g', String(fps * 2),+ '-f', 'image2pipe', '-framerate', String(fps), '-c:v', transparent ? 'png' : 'mjpeg', '-i', '-',+ ...codec,out,];const p = spawn(ffmpegPath(), args, { stdio: ['pipe', 'ignore', 'pipe'] });diff --git a/src/pipeline.js b/src/pipeline.jsindex 7a8d44f..97583c4 100644--- a/src/pipeline.js+++ b/src/pipeline.js@@ -39,7 +39,7 @@ export function makeState(project, timeline) {}// Runs fn(page, ctx) with the engine loaded at `scale`, then cleans up.-export async function withEngine(project, timeline, { scale = 1, pages = 1, log = () => {} } = {}, fn) {+export async function withEngine(project, timeline, { scale = 1, pages = 1, transparent = false, log = () => {} } = {}, fn) {const state = makeState(project, timeline);const server = await startServer({ projectDir: project.dir, getState: () => state });let browser = null;@@ -47,7 +47,7 @@ export async function withEngine(project, timeline, { scale = 1, pages = 1, logbrowser = await launch();const list = [];for (let i = 0; i < pages; i++) {- list.push(await openEngine(browser, server.url, { scale, onConsole: (type, text) => { if (type === 'error') log(`page: ${text}`); } }));+ list.push(await openEngine(browser, server.url, { scale, transparent, onConsole: (type, text) => { if (type === 'error') log(`page: ${text}`); } }));}return await fn(pages === 1 ? list[0] : list, { server, state });} finally {diff --git a/src/qa.js b/src/qa.jsindex 29aa331..3bee7ef 100644--- a/src/qa.js+++ b/src/qa.js@@ -1,5 +1,5 @@// Quality tools for the agent: layout checks, stills, contact sheets and a-// verification pass over the rendered MP4.+// verification pass over the rendered video.import fs from 'node:fs';import path from 'node:path';import { prepare, withEngine } from './pipeline.js';@@ -51,10 +51,10 @@ export function resolveTimes(timeline, specs) {});}-export async function stills(project, specs, { log = () => {}, scale = 1 } = {}) {+export async function stills(project, specs, { log = () => {}, scale = 1, transparent = false } = {}) {const { timeline } = await prepare(project, { log });const list = resolveTimes(timeline, specs).map((x) => ({ ...x, path: `out/stills/${x.label.replace(/[^\[email protected]]/g, '_')}.png` }));- await withEngine(project, timeline, { scale, log }, (page) => page.evaluate((l) => window.explainroo.stills(l), list));+ await withEngine(project, timeline, { scale, transparent, log }, (page) => page.evaluate((l) => window.explainroo.stills(l), list));return list.map((x) => ({ time: Math.round(x.T * 100) / 100, label: x.label, file: path.join(project.dir, x.path) }));}@@ -90,7 +90,7 @@ export async function sheet(project, { scene = null, every = null, cols = null,export async function verify(project, { file = null, log = () => {} } = {}) {const video = path.resolve(file || path.join(project.paths.out, 'video.mp4'));- if (path.extname(video).toLowerCase() === '.gif') throw new Error('verify checks MP4 files. Pass an MP4 with --file.');+ if (path.extname(video).toLowerCase() === '.gif') throw new Error('verify checks MP4, WebM and MOV files. Pass a video with --file.');if (!fs.existsSync(video)) throw new Error(`${video} does not exist. Run "explainroo render" first.`);const issues = [];const info = await probe(video);@@ -105,8 +105,13 @@ export async function verify(project, { file = null, log = () => {} } = {}) {}if (loud && loud.truePeak !== null && loud.truePeak > -0.5) issues.push({ level: 'warn', message: `true peak ${loud.truePeak} dBFS is close to clipping` });- const { stderr: bd } = await ffmpeg(['-nostats', '-i', video, '-vf', 'blackdetect=d=0.4:pix_th=0.08', '-an', '-f', 'null', '-']);- const blacks = [...bd.matchAll(/black_start:([\d.]+) black_end:([\d.]+)/g)].map((m) => [Number(m[1]), Number(m[2])]);+ const alpha = v && (String(v.tags?.alpha_mode ?? v.tags?.ALPHA_MODE) === '1' || /^(yuva|rgba|bgra|gbrap|argb|abgr)/.test(v.pix_fmt || ''));+ let blacks = [];+ if (alpha) issues.push({ level: 'hint', message: 'black-frame detection is skipped because the video has alpha' });+ else if (v) {+ const { stderr: bd } = await ffmpeg(['-nostats', '-i', video, '-vf', 'blackdetect=d=0.4:pix_th=0.08', '-an', '-f', 'null', '-']);+ blacks = [...bd.matchAll(/black_start:([\d.]+) black_end:([\d.]+)/g)].map((m) => [Number(m[1]), Number(m[2])]);+ }for (const [s, e] of blacks) issues.push({ level: 'warn', message: `black frames from ${s.toFixed(2)}s to ${e.toFixed(2)}s` });let silences = [];diff --git a/src/render.js b/src/render.jsindex 2fdaadb..51c039e 100644--- a/src/render.js+++ b/src/render.js@@ -1,4 +1,4 @@-// Renders MP4 or GIF: frames in parallel pages, encode, mux and extra files.+// Renders video or GIF: frames in parallel pages, encode, mux and extra files.import fs from 'node:fs';import os from 'node:os';import path from 'node:path';@@ -8,18 +8,26 @@ import { subtitleCues, toSrt, toVtt } from './subtitles.js';import { buildChapters, toChaptersText, toChapterMetadata } from './chapters.js';import { resolveTimes } from './qa.js';-export function renderFormat({ format = 'mp4', out } = {}) {- if (!['mp4', 'gif'].includes(format)) throw new Error('--format must be mp4 or gif');+export function renderFormat({ format = 'mp4', out, transparent = false } = {}) {+ if (!['mp4', 'gif', 'webm', 'mov'].includes(format)) throw new Error('--format must be mp4, gif, webm or mov');+ if (transparent && !['webm', 'mov'].includes(format)) throw new Error('--transparent needs --format webm or --format mov');if (out && path.extname(out).toLowerCase() !== `.${format}`) throw new Error(`--out must end in .${format} for --format ${format}`);return format;}+export function renderOutput(outDir, opts = {}) {+ const format = renderFormat(opts);+ return path.resolve(opts.out || path.join(outDir, `${opts.draft ? 'draft' : 'video'}.${format}`));+}+export async function render(project, opts = {}) {const log = opts.log || (() => {});const format = renderFormat(opts);const t0 = Date.now();const { timeline } = await prepare(project, { log });const draft = !!opts.draft;+ const transparent = !!opts.transparent;+ const segmentFormat = format === 'gif' ? 'mp4' : format;const scale = opts.scale ?? (draft ? 0.5 : 1);const fps = project.config.fps;const total = timeline.frames;@@ -27,7 +35,7 @@ export async function render(project, opts = {}) {const to = Math.min(total, opts.to !== undefined ? Math.ceil(opts.to * fps) : total);if (to <= from) throw new Error('nothing to render: --from must be before --to');const partial = from > 0 || to < total;- const out = path.resolve(opts.out || path.join(project.paths.out, `${draft ? 'draft' : 'video'}.${format}`));+ const out = renderOutput(project.paths.out, opts);const base = out.slice(0, -path.extname(out).length);const cues = subtitleCues(timeline, { from: from / fps, to: to / fps });const chapters = partial ? [] : buildChapters(timeline, project.script.title || project.config.title);@@ -44,10 +52,10 @@ export async function render(project, opts = {}) {const mixNorm = path.join(project.paths.build, 'mix-norm.wav');const encoders = [];try {- await withEngine(project, timeline, { scale, pages: workers, log }, async (pages) => {+ await withEngine(project, timeline, { scale, pages: workers, transparent, log }, async (pages) => {const list = Array.isArray(pages) ? pages : [pages];let norm;- if (format === 'mp4') {+ if (format !== 'gif') {const ta = Date.now();const sound = await list[0].evaluate((p) => window.explainroo.soundtrack(p), 'build/mix.wav');log(`soundtrack: ${sound.cues} sound cues, mixed in ${((Date.now() - ta) / 1000).toFixed(1)}s`);@@ -63,7 +71,7 @@ export async function render(project, opts = {}) {const a = from + k * per;const b = Math.min(to, a + per);if (a >= b) return;- const enc = frameEncoder({ fps, out: path.join(segDir, `seg-${String(k).padStart(2, '0')}.mp4`), draft });+ const enc = frameEncoder({ fps, out: path.join(segDir, `seg-${String(k).padStart(2, '0')}.${segmentFormat}`), draft, format: segmentFormat, transparent });encoders.push(enc);const batch = 6;for (let f = a; f < b; f += batch) {@@ -88,7 +96,7 @@ export async function render(project, opts = {}) {throw e;}- const segs = fs.readdirSync(segDir).filter((f) => f.endsWith('.mp4')).sort();+ const segs = fs.readdirSync(segDir).filter((f) => f.endsWith(`.${segmentFormat}`)).sort();const listFile = path.join(segDir, 'list.txt');fs.writeFileSync(listFile, segs.map((s) => `file '${path.join(segDir, s).replace(/'/g, "'\\''")}'`).join('\n') + '\n');const audioArgs = partial ? ['-ss', String(from / fps), '-t', String((to - from) / fps), '-i', mixNorm] : ['-i', mixNorm];@@ -113,7 +121,10 @@ export async function render(project, opts = {}) {fs.rmSync(palette, { force: true });}} else {- await ffmpeg(['-loglevel', 'error', '-f', 'concat', '-safe', '0', '-i', listFile, ...audioArgs, ...metadataArgs, '-map', '0:v', '-map', '1:a', '-c:v', 'copy', '-c:a', 'aac', '-b:a', '192k', '-movflags', '+faststart', '-shortest', out]);+ const audioCodec = format === 'webm' ? ['-c:a', 'libopus', '-b:a', '192k']+ : format === 'mov' ? ['-c:a', 'pcm_s16le'] : ['-c:a', 'aac', '-b:a', '192k'];+ const containerArgs = format === 'webm' ? [] : ['-movflags', '+faststart'];+ await ffmpeg(['-loglevel', 'error', '-f', 'concat', '-safe', '0', '-i', listFile, ...audioArgs, ...metadataArgs, '-map', '0:v', '-map', '1:a', '-c:v', 'copy', ...audioCodec, ...containerArgs, '-shortest', out]);}fs.rmSync(segDir, { recursive: true, force: true });const files = { subtitles: null, chapters: null, cover: null };diff --git a/test/cli.test.js b/test/cli.test.jsindex a1f1d69..a2809f1 100644--- a/test/cli.test.js+++ b/test/cli.test.js@@ -76,7 +76,11 @@ test('render rejects bad formats, mismatched extensions and missing text flags bfs.writeFileSync(path.join(dir, 'script.md'), '## intro\n');fs.writeFileSync(path.join(dir, 'scenes.js'), 'export default { intro(s) {} };');for (const [flags, message] of [- [['--format', 'webm'], /mp4 or gif/],+ [['--format', 'avi'], /mp4, gif, webm or mov/],+ [['--transparent'], /--format webm or --format mov/],+ [['--transparent', '--format', 'gif'], /--format webm or --format mov/],+ [['--format', 'webm', '--out', 'file.mp4'], /must end in .webm/],+ [['--format', 'mov', '--out', 'file.webm'], /must end in .mov/],[['--out', 'file.gif'], /must end in .mp4/],[['--format', 'gif', '--out', 'file.mp4'], /must end in .gif/],[['--format'], /--format needs a value/],diff --git a/test/render-options.test.js b/test/render-options.test.jsindex 46c55e4..b4a5044 100644--- a/test/render-options.test.js+++ b/test/render-options.test.js@@ -1,20 +1,41 @@import test from 'node:test';import assert from 'node:assert/strict';-import { renderFormat } from '../src/render.js';+import path from 'node:path';+import { renderFormat, renderOutput } from '../src/render.js';import { normalizeConfig } from '../src/project.js';import { resolveTimes, verify } from '../src/qa.js';-test('render accepts only mp4 and gif with matching output extensions', () => {+test('render accepts mp4, gif, webm and mov with matching output extensions', () => {assert.equal(renderFormat(), 'mp4');assert.equal(renderFormat({ out: 'x/y.mp4' }), 'mp4');assert.equal(renderFormat({ format: 'gif', out: 'x/y.gif' }), 'gif');assert.equal(renderFormat({ format: 'mp4', out: 'x/y.MP4' }), 'mp4');- assert.throws(() => renderFormat({ format: 'webm' }), /mp4 or gif/);+ for (const format of ['webm', 'mov']) {+ assert.equal(renderFormat({ format, out: `x/y.${format}` }), format);+ assert.equal(renderFormat({ format, transparent: true }), format);+ assert.throws(() => renderFormat({ format, out: 'x/y.mp4' }), new RegExp(`\\.${format}`));+ }+ assert.throws(() => renderFormat({ format: 'avi' }), /mp4, gif, webm or mov/);assert.throws(() => renderFormat({ out: 'x/y.gif' }), /\.mp4/);assert.throws(() => renderFormat({ format: 'gif', out: 'x/y.mp4' }), /\.gif/);assert.throws(() => renderFormat({ out: 'x/y' }), /\.mp4/);});+test('transparent export needs an alpha format', () => {+ for (const format of [undefined, 'mp4', 'gif']) {+ assert.throws(() => renderFormat({ format, transparent: true }), /--format webm or --format mov/);+ }+});++test('render output names follow format, draft and --out', () => {+ for (const format of ['mp4', 'gif', 'webm', 'mov']) {+ assert.equal(renderOutput('/tmp/out', { format }), path.resolve(`/tmp/out/video.${format}`));+ assert.equal(renderOutput('/tmp/out', { format, draft: true }), path.resolve(`/tmp/out/draft.${format}`));+ assert.equal(renderOutput('/tmp/out', { format, draft: true, out: `/tmp/custom.${format}` }), path.resolve(`/tmp/custom.${format}`));+ }+ assert.equal(renderOutput('/tmp/out'), path.resolve('/tmp/out/video.mp4'));+});+test('cover validates its type and syntax while allowing still specs', () => {assert.equal(normalizeConfig({}).cover, 'auto');for (const cover of [0, 12.5, '12.5', 'intro', '[email protected]', 'intro@end', 'intro@start']) assert.equal(normalizeConfig({ cover }).cover, cover);@@ -27,5 +48,5 @@ test('cover validates its type and syntax while allowing still specs', () => {});test('verify explains that GIF is unsupported', async () => {- await assert.rejects(verify({ paths: { out: '/tmp' } }, { file: '/tmp/video.gif' }), /verify checks MP4 files/);+ await assert.rejects(verify({ paths: { out: '/tmp' } }, { file: '/tmp/video.gif' }), /verify checks MP4, WebM and MOV files/);});diff --git a/test/transparent-browser.test.js b/test/transparent-browser.test.jsnew file mode 100644index 0000000..ac0c6e1--- /dev/null+++ b/test/transparent-browser.test.js@@ -0,0 +1,123 @@+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 { spawnSync } from 'node:child_process';+import { findChrome } from '../src/browser.js';+import { loadProject } from '../src/project.js';+import { withEngine } from '../src/pipeline.js';+import { render } from '../src/render.js';+import { stills, verify } from '../src/qa.js';+import { ffmpegPath, ffmpegVersion, probe } from '../src/ffmpeg.js';++let chrome;+try { chrome = findChrome(); } catch {}+const skip = !chrome || !ffmpegVersion();++function pixels(file, decoder = []) {+ const r = spawnSync(ffmpegPath(), ['-v', 'error', ...decoder, '-i', file, '-frames:v', '1', '-f', 'rawvideo', '-pix_fmt', 'rgba', '-threads', '1', '-'], { maxBuffer: 1024 * 1024 });+ assert.equal(r.status, 0, r.stderr.toString());+ return r.stdout;+}+const alphaAt = (data, x, y, w = 320) => data[(y * w + x) * 4 + 3];++function projectFiles(dir) {+ fs.writeFileSync(path.join(dir, 'video.json'), JSON.stringify({ theme: 'clean', size: '320x180', fps: 24, captions: false, watermark: false, music: false, sfx: false, end: 0 }));+ fs.writeFileSync(path.join(dir, 'script.md'), '## box {min=2 chapter="Box"}\n');+ fs.writeFileSync(path.join(dir, 'scenes.js'), `export default { box(s) {+ s.box('', { x: 160, y: 90, w: 80, h: 60, fill: '#245cff', border: false, at: 0, enter: 'none' });+ } };`);+ return loadProject(dir);+}++test('transparent WebM and MOV retain alpha, audio, chapters and opaque covers', { skip }, async () => {+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'explainroo-alpha-'));+ try {+ const project = projectFiles(dir);+ for (const format of ['webm', 'mov']) {+ const r = await render(project, { format, transparent: true, workers: 2 });+ assert.equal(r.out, path.join(dir, `out/video.${format}`));+ assert.equal(r.duration, 2);+ assert.equal(r.chapters, path.join(dir, 'out/video.chapters.txt'));+ assert.equal(r.cover, path.join(dir, 'out/video.cover.jpg'));+ const info = await probe(r.out);+ const video = info.streams.find((s) => s.codec_type === 'video');+ const audio = info.streams.find((s) => s.codec_type === 'audio');+ assert.equal(audio.codec_name, format === 'webm' ? 'opus' : 'pcm_s16le');+ // ffprobe's native VP9 decoder hides the alpha plane. libvpx exposes it.+ if (format === 'webm') {+ assert.equal(video.codec_name, 'vp9');+ assert.equal(video.tags.alpha_mode ?? video.tags.ALPHA_MODE, '1');+ const decoded = spawnSync(ffmpegPath(), ['-c:v', 'libvpx-vp9', '-i', r.out, '-frames:v', '1', '-f', 'null', '-'], { encoding: 'utf8' });+ assert.equal(decoded.status, 0, decoded.stderr);+ assert.match(decoded.stderr, /yuva420p/);+ } else {+ assert.equal(video.codec_name, 'prores');+ assert.equal(video.codec_tag_string, 'ap4h');+ assert.match(video.pix_fmt, /^yuva444p/);+ }+ const chapters = spawnSync(process.env.EXPLAINROO_FFPROBE || 'ffprobe', ['-v', 'error', '-show_chapters', '-of', 'json', r.out], { encoding: 'utf8' });+ assert.equal(chapters.status, 0, chapters.stderr);+ assert.equal(JSON.parse(chapters.stdout).chapters[0].tags.title, 'Box');+ const data = pixels(r.out, format === 'webm' ? ['-c:v', 'libvpx-vp9'] : []);+ assert.equal(alphaAt(data, 0, 0), 0);+ assert.equal(alphaAt(data, 160, 90), 255);+ assert.equal(alphaAt(pixels(r.cover), 0, 0), 255);+ const report = await verify(project, { file: r.out });+ assert.deepEqual(report.blackSegments, []);+ assert.ok(report.issues.some((i) => /skipped because the video has alpha/.test(i.message)));+ assert.ok(!report.issues.some((i) => i.level === 'error'));+ }+ const [still] = await stills(project, ['box@1'], { transparent: true });+ const data = pixels(still.file);+ assert.equal(alphaAt(data, 0, 0), 0);+ assert.equal(alphaAt(data, 160, 90), 255);+ for (const format of ['webm', 'mov']) {+ const r = await render(project, { format, draft: true, workers: 1 });+ assert.equal(r.out, path.join(dir, `out/draft.${format}`));+ assert.equal(alphaAt(pixels(r.out), 0, 0, 160), 255);+ }+ } finally { fs.rmSync(dir, { recursive: true, force: true }); }+});++test('every transparent transition keeps empty pixels clear and clears old frames', { skip: !chrome }, async () => {+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'explainroo-transitions-'));+ try {+ const project = projectFiles(dir);+ const names = ['fade', 'slide', 'wipe', 'zoom', 'brush', 'cut'];+ const timeline = { duration: 14, frames: 336, fps: 24, width: 320, height: 180, transitionSeconds: 0.7,+ scenes: ['none', ...names].map((transition, index) => ({ id: 'box', index, start: index * 2, dur: 2, words: [], marks: {}, voice: null, transition })) };+ await withEngine(project, timeline, { transparent: true }, async (page) => {+ const results = await page.evaluate(async () => {+ const { boot } = await import('/engine/runtime.js');+ const { engine } = await boot({ canvas: document.createElement('canvas'), transparent: true });+ engine.scenesModule.box = (s) => {+ s.ctx.fillStyle = '#245cff';+ s.ctx.fillRect(s.scene.index % 2 ? 160 : 80, 60, 80, 60);+ };+ const sample = (T) => {+ engine.renderFrame(T);+ const ctx = engine.ctx;+ return [0, 100, 180].map((x) => ctx.getImageData(x, x ? 90 : 0, 1, 1).data[3]);+ };+ return engine.timeline.scenes.slice(1).map((sc) => ({+ name: sc.transition, middle: sample(sc.start + 0.35), end: sample(sc.start + 0.8), repeat: sample(sc.start + 0.35),+ }));+ });+ for (const [i, r] of results.entries()) {+ assert.equal(r.middle[0], 0, r.name);+ assert.equal(r.end[0], 0, r.name);+ assert.deepEqual(r.repeat, r.middle, r.name);+ const outgoing = i % 2 ? 2 : 1;+ const incoming = i % 2 ? 1 : 2;+ assert.equal(r.end[outgoing], 0, r.name);+ assert.equal(r.end[incoming], 255, r.name);+ if (r.name !== 'cut') {+ assert.ok(Math.abs(r.middle[outgoing] - 128) <= 1, JSON.stringify(r));+ assert.ok(Math.abs(r.middle[incoming] - 128) <= 1, JSON.stringify(r));+ }+ }+ });+ } finally { fs.rmSync(dir, { recursive: true, force: true }); }+});