Skip to content

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.

Render transparent WebM and MOV for video editors (#13)

Vincent Schmalbached16325e32d9
diff --git a/AGENTS.md b/AGENTS.md
index 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 the
video (`--from`, `--to`) skips the chapters and the cover. A video without
narration 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 API
Each scene function draws one frame. explainroo calls it for every frame with
diff --git a/engine/frame.html b/engine/frame.html
index 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.js
index 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.js
index 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.js
index 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.js
index 402118f..4ae5102 100644
--- a/src/cli.js
+++ b/src/cli.js
@@ -26,12 +26,12 @@ Make a video
init <dir> create a project (--theme, --size, --pace, --voice, --title)
voice [project] make the narration (Kokoro, ElevenLabs or a recording) and word timings
preview [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 demos
capture [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.js
index 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.js
index 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, log
browser = 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.js
index 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.js
index 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.js
index 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 b
fs.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.js
index 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.js
new file mode 100644
index 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 }); }
+});