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
Write subtitle files, chapters and a cover with every render, and GIFs (#6)
Vincent Schmalbachfc9d21139634
diff --git a/AGENTS.md b/AGENTS.mdindex bc5ece7..888c921 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -133,12 +133,17 @@ When you ask, put everything you need in one message. Typical reasons to ask:node bin/explainroo.js verify videos/<name>```- `render` makes the video. `verify` measures the loudness and looks for+ `render` also writes subtitle files (`.srt` and `.vtt`) and a cover+ image (`.cover.jpg`) next to the video. When scenes name chapters, it+ writes `.chapters.txt` for the YouTube description and adds the chapters+ to the MP4. `--format gif` makes a silent GIF instead, for a README or a+ post. `verify` checks the MP4. It measures the loudness and looks forblack frames and silence. It also runs the speech check on the finishedsound to make sure the voice is still clear over the music.-11. **Tell the user** where `out/video.mp4` is, how long it is, what verify- said, and what you could not check.+11. **Tell the user** where the video and its subtitle files, chapters and+ cover are, how long the video is, what verify said, and what you could+ not check.## How to write the narration@@ -192,6 +197,11 @@ Narration for this scene. [#marker] A marker names a moment you can animate on.be, in seconds), `lead` (seconds before the voice, default 0.35) and`transition` (`fade`, `slide`, `wipe`, `zoom`, `brush`, `cut`).- A scene without narration lasts `min` seconds (default 3).+- `chapter="How the resolver finds it"` in a scene's braces starts a+ chapter at that scene. It lasts until the next chapter. Titles have 1 to+ 60 characters. If the first scene names no chapter, the first chapter is+ the video title. YouTube shows chapters only when there are at least 3+ and each lasts 10 seconds or more.## What makes the pictures good@@ -405,6 +415,9 @@ Set `size` to the place the video goes. `explainroo formats` lists the sizes.`9:16`, `4:5` and `WIDTHxHEIGHT` also work.+YouTube and LinkedIn take the `.srt` file as captions when you upload the+video.+Shorts, TikTok and Reels put their own buttons, the account name and the posttext on top of the video. With `shorts`, `tiktok`, `reels` and `vertical`,explainroo keeps your content away from those spots. `s.safe` is the part the@@ -481,6 +494,7 @@ videos/<name>/| `music` | `true` | `true` (the look's style), `warm`, `upbeat`, `calm`, `tech`, `playful`, `{ "style", "volume" }` or `false` || `sfx` | `true` | sound effects: `true`, `"minimal"` or `false` || `captions` | `"auto"` | text of the narration at the bottom; auto turns it on for vertical and square videos |+| `cover` | `"auto"` | full-size JPEG at the end of the first scene, or a still spec: `12.5`, `"intro"`, `"[email protected]"`, `"intro@end"` || `transition` | `"auto"` | the look's default, or `fade`, `slide`, `wipe`, `zoom`, `brush`, `cut` || `lead`, `hold`, `end` | 0.35, 0.7, 1.4 | seconds before the voice, after it, and extra at the very end || `sentenceGap`, `paragraphGap` | 0.3, 0.55 | pauses in the narration |@@ -556,7 +570,7 @@ when `ink` or `muted` has too little contrast against `bg`.| `still [project] [times]` | PNG pictures at `12.5`, `scene`, `[email protected]` or `scene@end` || `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 (`--draft`, `--from`, `--to`, `--workers`, `--out`) |+| `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 || `image [project] <name> "<prompt>"` | makes an illustration with OpenRouter || `images [project]` | lists the images and what they cost |@@ -564,6 +578,13 @@ when `ink` or `muted` has too little contrast against `bg`.| `themes`, `formats`, `icons <word>` | lists the looks and the sizes, searches the 1,854 icons || `doctor` | checks the setup (`--fetch` downloads the speech models) |+The extra files share the video's name, also with `--out`: `video.srt`,+`video.vtt`, `video.cover.jpg` and `video.chapters.txt`. A GIF has no sound,+runs at 15 frames per second and is at most 960 pixels on its long side.+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.+## Scene APIEach scene function draws one frame. explainroo calls it for every frame withdiff --git a/engine/frame.html b/engine/frame.htmlindex 2698aea..6b8968a 100644--- a/engine/frame.html+++ b/engine/frame.html@@ -38,14 +38,14 @@ window.explainrooReady = (async () => {}return out;},- async stills(list) {+ async stills(list, { type = 'image/png', quality } = {}) {for (const { T, path } of list) {try {engine.renderFrame(T);} catch (e) {throw new Error(describe(e));}- const blob = await new Promise((r) => canvas.toBlob(r, 'image/png'));+ const blob = await new Promise((r) => canvas.toBlob(r, type, quality));await upload(path, blob);}return list.length;diff --git a/src/chapters.js b/src/chapters.jsnew file mode 100644index 0000000..4ed2540--- /dev/null+++ b/src/chapters.js@@ -0,0 +1,32 @@+// Chapters share the scene boundaries used by the video.+export function buildChapters(timeline, title) {+ const named = timeline.scenes.filter((s) => s.attrs?.chapter !== undefined);+ if (!named.length) return [];+ if (named[0] !== timeline.scenes[0]) named.unshift({ ...timeline.scenes[0], attrs: { chapter: title } });+ return named.map((s, i) => ({ title: s.attrs.chapter, start: s.start, end: named[i + 1]?.start ?? timeline.duration, scene: s.id }));+}++export function chapterHints(chapters) {+ if (!chapters.length) return [];+ const issues = [];+ if (chapters.length < 3) issues.push({ level: 'hint', scene: null, t: null, message: `the video has ${chapters.length} chapter${chapters.length === 1 ? '' : 's'}, and YouTube shows chapters only when there are at least 3 chapters. Name chapters in more scenes, or leave them out.` });+ for (const c of chapters) {+ if (c.end - c.start < 10) issues.push({ level: 'hint', scene: c.scene, t: null, message: `chapter "${c.title}" lasts ${(c.end - c.start).toFixed(1)}s, and YouTube shows chapters only when each lasts at least 10 seconds. Start it at another scene or join it with the next one.` });+ }+ return issues;+}++export function toChaptersText(chapters) {+ return chapters.map((c) => {+ const seconds = Math.floor(c.start);+ const minutes = Math.floor(seconds / 60);+ const pad = (n) => String(n).padStart(2, '0');+ const time = seconds >= 3600 ? `${Math.floor(minutes / 60)}:${pad(minutes % 60)}:${pad(seconds % 60)}` : `${minutes}:${pad(seconds % 60)}`;+ return `${time} ${c.title}\n`;+ }).join('');+}++export function toChapterMetadata(chapters) {+ const escape = (text) => String(text).replace(/[\\=;#\n]/g, '\\$&');+ return ';FFMETADATA1\n' + chapters.map((c) => `[CHAPTER]\nTIMEBASE=1/1000\nSTART=${Math.round(c.start * 1000)}\nEND=${Math.round(c.end * 1000)}\ntitle=${escape(c.title)}\n`).join('');+}diff --git a/src/cli.js b/src/cli.jsindex 0701192..17cf500 100644--- a/src/cli.js+++ b/src/cli.js@@ -27,8 +27,9 @@ Make a videostill [project] [t…] PNG stills: "12.5", "scene", "[email protected]" (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 out/video.mp4 (--draft, --from s, --to s, --workers n, --out file)- verify [project] check the rendered file: loudness, black frames, narration+ render [project] write MP4, subtitles, chapters and a cover (--format gif for GIF)+ (--draft, --from s, --to s, --workers n, --out file)+ verify [project] check an MP4: loudness, black frames, narrationImages (optional, needs an OpenRouter API key)image [project] <name> "<what to draw>" save an illustration as assets/<name>.png@@ -128,8 +129,8 @@ 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: flags.out });- print(r.out, r);+ 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') });+ 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;}case 'verify': {diff --git a/src/project.js b/src/project.jsindex c25b5e8..3b64a9b 100644--- a/src/project.js+++ b/src/project.js@@ -42,6 +42,7 @@ export const DEFAULTS = {music: true,sfx: true,captions: 'auto',+ cover: 'auto',transition: 'auto',lead: 0.35,hold: 0.7,@@ -169,6 +170,14 @@ export function normalizeConfig(raw, dir = '.') {if (!TRANSITIONS.includes(cfg.transition)) fail(`transition must be one of ${TRANSITIONS.join(', ')}`);if (![true, false, 'minimal'].includes(cfg.sfx)) fail('sfx must be true, false or "minimal"');if (![true, false, 'auto'].includes(cfg.captions)) fail('captions must be true, false or "auto"');+ const cover = cfg.cover;+ const [scene, at, extra] = typeof cover === 'string' ? cover.split('@') : [];+ const coverTime = typeof cover === 'number' && Number.isFinite(cover) && cover >= 0;+ const coverSpec = typeof cover === 'string' && (/^\d+(\.\d+)?$/.test(cover) || (+ /^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(scene) && extra === undefined &&+ (at === undefined || at === '' || at === 'end' || at === 'start' || Number.isFinite(Number(at)))+ ));+ if (!coverTime && !coverSpec) fail('cover must be "auto", seconds like 12.5, or a still spec like "intro@end"');for (const k of ['lead', 'hold', 'end', 'sentenceGap', 'paragraphGap']) {if (!(typeof cfg[k] === 'number' && cfg[k] >= 0 && cfg[k] <= 10)) fail(`${k} must be a number of seconds between 0 and 10`);}diff --git a/src/qa.js b/src/qa.jsindex 2635bf7..79dd873 100644--- a/src/qa.js+++ b/src/qa.js@@ -7,11 +7,12 @@ import { probe, loudness, ffmpeg } from './ffmpeg.js';import { transcribeWords } from './models.js';import { readWav } from './wav.js';import { alignWords } from './align.js';+import { buildChapters, chapterHints } from './chapters.js';export async function check(project, { log = () => {}, step = 0.25, viewWidth = null } = {}) {if (viewWidth !== null && (!Number.isFinite(viewWidth) || viewWidth <= 0)) throw new Error("--view-width must be a positive number");const { voices, timeline } = await prepare(project, { log });- const issues = [];+ const issues = chapterHints(buildChapters(timeline, project.script.title || project.config.title));for (const sc of project.script.scenes) {const v = voices[sc.id];const suspicious = v ? v.unmatched.filter((w) => w.replace(/[^\p{L}\p{N}]/gu, '').length > 3) : [];@@ -34,7 +35,7 @@ export function resolveTimes(timeline, specs) {const endOf = (sc) => sc.start + Math.max(0, sc.dur - 0.3);if (!specs.length) return timeline.scenes.map((sc) => ({ T: endOf(sc), label: `${sc.id}@end` }));return specs.map((spec) => {- if (/^\d+(\.\d+)?$/.test(spec)) {+ if (typeof spec === 'number' || /^\d+(\.\d+)?$/.test(spec)) {const T = Math.min(Number(spec), timeline.duration - 1 / timeline.fps);return { T, label: `t${T.toFixed(2)}` };}@@ -89,6 +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 (!fs.existsSync(video)) throw new Error(`${video} does not exist. Run "explainroo render" first.`);const issues = [];const info = await probe(video);diff --git a/src/render.js b/src/render.jsindex b2c6d77..2fdaadb 100644--- a/src/render.js+++ b/src/render.js@@ -1,12 +1,22 @@-// Renders the finished MP4: soundtrack, frames in parallel pages, encode, mux.+// Renders MP4 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';import { prepare, withEngine } from './pipeline.js';import { frameEncoder, ffmpeg, normalizeLoudness } from './ffmpeg.js';+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');+ if (out && path.extname(out).toLowerCase() !== `.${format}`) throw new Error(`--out must end in .${format} for --format ${format}`);+ return 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;@@ -17,7 +27,11 @@ 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.mp4' : 'video.mp4'));+ const out = path.resolve(opts.out || path.join(project.paths.out, `${draft ? 'draft' : 'video'}.${format}`));+ 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);+ const coverTime = partial ? null : resolveTimes(timeline, [project.config.cover === 'auto' ? `${timeline.scenes[0].id}@end` : project.config.cover])[0];const workers = Math.max(1, Math.min(opts.workers ?? Math.min(8, Math.max(1, Math.floor(os.cpus().length / 2))), to - from));const quality = draft ? 0.82 : 0.93;const segDir = path.join(project.paths.build, 'segments');@@ -32,11 +46,14 @@ export async function render(project, opts = {}) {try {await withEngine(project, timeline, { scale, pages: workers, log }, async (pages) => {const list = Array.isArray(pages) ? pages : [pages];- 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`);- const norm = normalizeLoudness(mix, mixNorm, project.config.loudness);- norm.catch(() => {});+ let norm;+ if (format === 'mp4') {+ 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`);+ norm = normalizeLoudness(mix, mixNorm, project.config.loudness);+ norm.catch(() => {});+ }const per = Math.ceil((to - from) / list.length);let done = 0;@@ -75,9 +92,51 @@ export async function render(project, opts = {}) {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];- await ffmpeg(['-loglevel', 'error', '-f', 'concat', '-safe', '0', '-i', listFile, ...audioArgs, '-map', '0:v', '-map', '1:a', '-c:v', 'copy', '-c:a', 'aac', '-b:a', '192k', '-movflags', '+faststart', '-shortest', out]);+ const metadata = path.join(project.paths.build, 'chapters.ffmeta');+ if (chapters.length) fs.writeFileSync(metadata, toChapterMetadata(chapters));+ const metadataArgs = chapters.length ? ['-f', 'ffmetadata', '-i', metadata, '-map_metadata', '2', '-map_chapters', '2'] : [];+ let width = 2 * Math.round(project.config.width * scale / 2);+ let height = 2 * Math.round(project.config.height * scale / 2);+ if (format === 'gif') {+ const temp = path.join(project.paths.build, 'gif.mp4');+ const palette = path.join(project.paths.build, 'gif-palette.png');+ const ratio = Math.min(1, 960 / Math.max(width, height));+ width = Math.max(2, 2 * Math.floor(width * ratio / 2));+ height = Math.max(2, 2 * Math.floor(height * ratio / 2));+ const filter = `fps=15,scale=${width}:${height}:flags=lanczos`;+ try {+ await ffmpeg(['-loglevel', 'error', '-f', 'concat', '-safe', '0', '-i', listFile, '-map', '0:v', '-c:v', 'copy', '-an', temp]);+ await ffmpeg(['-loglevel', 'error', '-i', temp, '-vf', `${filter},palettegen=stats_mode=diff`, '-frames:v', '1', '-threads', '1', palette]);+ await ffmpeg(['-loglevel', 'error', '-i', temp, '-i', palette, '-lavfi', `${filter}[v];[v][1:v]paletteuse=dither=sierra2_4a`, '-an', out]);+ } finally {+ fs.rmSync(temp, { force: true });+ 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]);+ }fs.rmSync(segDir, { recursive: true, force: true });+ const files = { subtitles: null, chapters: null, cover: null };+ if (timeline.scenes.some((s) => s.words.length)) {+ files.subtitles = { srt: `${base}.srt`, vtt: `${base}.vtt` };+ fs.writeFileSync(files.subtitles.srt, toSrt(cues));+ fs.writeFileSync(files.subtitles.vtt, toVtt(cues));+ } else {+ for (const ext of ['srt', 'vtt']) fs.rmSync(`${base}.${ext}`, { force: true });+ }+ if (chapters.length) {+ files.chapters = `${base}.chapters.txt`;+ fs.writeFileSync(files.chapters, toChaptersText(chapters));+ } else fs.rmSync(`${base}.chapters.txt`, { force: true });+ if (coverTime) {+ const temp = path.join(project.paths.build, 'cover.jpg');+ try {+ await withEngine(project, timeline, { scale: 1, log }, (page) => page.evaluate((T) => window.explainroo.stills([{ T, path: 'build/cover.jpg' }], { type: 'image/jpeg', quality: 0.9 }), coverTime.T));+ files.cover = `${base}.cover.jpg`;+ fs.copyFileSync(temp, files.cover);+ } finally { fs.rmSync(temp, { force: true }); }+ } else fs.rmSync(`${base}.cover.jpg`, { force: true });const secs = (Date.now() - t0) / 1000;log(`wrote ${path.relative(process.cwd(), out) || out} in ${secs.toFixed(1)}s`);- return { out, duration: (to - from) / fps, frames: to - from, seconds: secs, width: Math.round(project.config.width * scale), height: Math.round(project.config.height * scale) };+ return { out, ...files, duration: (to - from) / fps, frames: to - from, seconds: secs, width, height };}diff --git a/src/script.js b/src/script.jsindex a640953..ff067f8 100644--- a/src/script.js+++ b/src/script.js@@ -29,11 +29,18 @@ export function normWord(w) {function parseAttrs(src, line) {const attrs = {};if (!src) return attrs;- for (const part of src.trim().split(/[\s,]+/).filter(Boolean)) {+ const token = /[^\s,=:]+[=:](?:"[^"]*"|'[^']*'|[^\s,]+)|[^\s,]+/y;+ let i = 0;+ while (i < src.length) {+ if (/[\s,]/.test(src[i])) { i++; continue; }+ token.lastIndex = i;+ const part = token.exec(src)?.[0];+ i = token.lastIndex;const m = /^([a-zA-Z][\w-]*)\s*[=:]\s*(.+)$/.exec(part);if (!m) throw new ScriptError(`cannot read scene attribute "${part}" (use key=value)`, line);const [, key, raw] = m;const value = raw.replace(/^["']|["']$/g, '');+ if (key === 'chapter' && (!value.trim() || value.length > 60)) throw new ScriptError('chapter title must be 1 to 60 characters', line);if (ATTR_NUMBERS.has(key)) {const n = Number(value);if (!Number.isFinite(n) || n < 0) throw new ScriptError(`attribute ${key} must be a number >= 0`, line);diff --git a/src/subtitles.js b/src/subtitles.jsnew file mode 100644index 0000000..cfdc881--- /dev/null+++ b/src/subtitles.js@@ -0,0 +1,63 @@+// Subtitle cues use the shown words and their times from the voice timeline.+const sentenceEnd = /[.!?…]["'’”)\]]*$/;+const punctuation = /[,;:.!?…]["'’”)\]]*$/;++function lines(words) {+ const text = words.map((w) => w.text).join(' ');+ if (text.length <= 42) return text;+ let best = null;+ for (let i = 1; i < words.length; i++) {+ const a = words.slice(0, i).map((w) => w.text).join(' ');+ const b = words.slice(i).map((w) => w.text).join(' ');+ if (a.length > 42 || b.length > 42) continue;+ // Break after punctuation, unless that leaves a word or two alone on a line.+ const atPunctuation = punctuation.test(words[i - 1].text) && Math.min(a.length, b.length) >= 12;+ const score = (atPunctuation ? 30 : 0) - Math.abs(a.length - b.length);+ if (!best || score > best.score) best = { score, text: `${a}\n${b}` };+ }+ return best?.text ?? null;+}++export function subtitleCues(timeline, { from = 0, to = Infinity } = {}) {+ const cues = [];+ for (const scene of timeline.scenes) {+ const words = scene.words || [];+ let i = 0;+ while (i < words.length) {+ if (words[i].text.length > 42) throw new Error(`subtitle word "${words[i].text}" is longer than 42 characters. Shorten its shown text in script.md.`);+ let j = i + 1;+ while (j < words.length) {+ if (sentenceEnd.test(words[j - 1].text) || words[j].start - words[j - 1].end > 0.6 + 1e-9) break;+ if (words[j].end + 0.25 - words[i].start > 6 || lines(words.slice(i, j + 1)) === null) {+ for (let k = j - 1; k > i; k--) {+ if (punctuation.test(words[k - 1].text)) { j = k; break; }+ }+ break;+ }+ j++;+ }+ const start = scene.start + words[i].start;+ const end = Math.min(scene.start + words[j - 1].end + 0.25, start + 6, scene.start + (scene.dur ?? Infinity));+ cues.push({ start, end, text: lines(words.slice(i, j)) });+ i = j;+ }+ }+ for (let i = 0; i < cues.length - 1; i++) cues[i].end = Math.min(cues[i].end, cues[i + 1].start);+ return cues.filter((c) => c.end > from && c.start < to).map((c) => ({+ ...c, start: Math.max(c.start, from) - from, end: Math.min(c.end, to) - from,+ }));+}++function timestamp(seconds, separator) {+ const ms = Math.max(0, Math.round(seconds * 1000));+ const pad = (n, width = 2) => String(n).padStart(width, '0');+ return `${pad(Math.floor(ms / 3600000))}:${pad(Math.floor(ms / 60000) % 60)}:${pad(Math.floor(ms / 1000) % 60)}${separator}${pad(ms % 1000, 3)}`;+}++export function toSrt(cues) {+ return cues.map((c, i) => `${i + 1}\n${timestamp(c.start, ',')} --> ${timestamp(c.end, ',')}\n${c.text}\n\n`).join('');+}++export function toVtt(cues) {+ return 'WEBVTT\n\n' + cues.map((c) => `${timestamp(c.start, '.')} --> ${timestamp(c.end, '.')}\n${c.text.replace(/&/g, '&').replace(/</g, '<').replace(/>/g, '>')}\n\n`).join('');+}diff --git a/test/chapters.test.js b/test/chapters.test.jsnew file mode 100644index 0000000..ba064c9--- /dev/null+++ b/test/chapters.test.js@@ -0,0 +1,41 @@+import test from 'node:test';+import assert from 'node:assert/strict';+import { buildChapters, chapterHints, toChaptersText, toChapterMetadata } from '../src/chapters.js';++const timeline = { duration: 40, scenes: [+ { id: 'intro', start: 0, attrs: {} },+ { id: 'first', start: 12, attrs: { chapter: 'First chapter' } },+ { id: 'second', start: 26, attrs: { chapter: 'Second chapter' } },+] };++test('chapters start on named scenes and fill the opening with the video title', () => {+ assert.deepEqual(buildChapters(timeline, 'Video title'), [+ { title: 'Video title', scene: 'intro', start: 0, end: 12 },+ { title: 'First chapter', scene: 'first', start: 12, end: 26 },+ { title: 'Second chapter', scene: 'second', start: 26, end: 40 },+ ]);+ assert.equal(timeline.scenes[0].attrs.chapter, undefined);+ const namedIntro = { ...timeline, scenes: [{ ...timeline.scenes[0], attrs: { chapter: 'Opening' } }, ...timeline.scenes.slice(1)] };+ assert.equal(buildChapters(namedIntro, 'Video title')[0].title, 'Opening');+ assert.deepEqual(buildChapters({ scenes: [{ start: 0, attrs: {} }] }, 'Title'), []);+});++test('YouTube hints explain ignored chapters without warnings', () => {+ const chapters = buildChapters(timeline, 'Title');+ assert.deepEqual(chapterHints(chapters), []);+ assert.deepEqual(chapterHints([]), []);+ const hints = chapterHints([{ title: 'Short', scene: 'a', start: 0, end: 9.99 }]);+ assert.equal(hints.length, 2);+ assert.ok(hints.every((h) => h.level === 'hint' && /YouTube shows chapters only when/.test(h.message)));+ assert.match(hints[0].message, /3 chapters/);+ assert.match(hints[1].message, /10 seconds/);+ assert.equal(chapterHints([{ start: 0, end: 10 }]).length, 1);+});++test('chapter text uses m:ss below an hour and h:mm:ss from an hour', () => {+ assert.equal(toChaptersText([{ start: 0, title: 'Opening' }, { start: 65.9, title: 'Next' }, { start: 3599, title: 'Later' }, { start: 3600, title: 'Hour' }, { start: 7325, title: 'End' }]), '0:00 Opening\n1:05 Next\n59:59 Later\n1:00:00 Hour\n2:02:05 End\n');+});++test('ffmetadata keeps millisecond boundaries and escapes special title characters', () => {+ assert.equal(toChapterMetadata([{ start: 0, end: 12.345, title: 'A=B; #C\\D' }]), ';FFMETADATA1\n[CHAPTER]\nTIMEBASE=1/1000\nSTART=0\nEND=12345\ntitle=A\\=B\\; \\#C\\\\D\n');+});diff --git a/test/cli.test.js b/test/cli.test.jsindex d2852b4..a1f1d69 100644--- a/test/cli.test.js+++ b/test/cli.test.js@@ -68,3 +68,24 @@ test('init with valid settings writes video.json and the starter files', async (assert.ok(fs.existsSync(path.join(target, 'assets')));assert.ok(fs.existsSync(path.join(target, 'script.md')));});++test('render rejects bad formats, mismatched extensions and missing text flags before building', async () => {+ const dir = tempDir();+ try {+ fs.writeFileSync(path.join(dir, 'video.json'), '{}');+ 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/],+ [['--out', 'file.gif'], /must end in .mp4/],+ [['--format', 'gif', '--out', 'file.mp4'], /must end in .gif/],+ [['--format'], /--format needs a value/],+ [['--out'], /--out needs a value/],+ ]) {+ const r = await run(['render', dir, ...flags]);+ assert.equal(r.code, 1);+ assert.match(r.err, message);+ assert.equal(fs.existsSync(path.join(dir, 'build')), false);+ }+ } finally { fs.rmSync(dir, { recursive: true, force: true }); }+});diff --git a/test/render-options.test.js b/test/render-options.test.jsnew file mode 100644index 0000000..46c55e4--- /dev/null+++ b/test/render-options.test.js@@ -0,0 +1,31 @@+import test from 'node:test';+import assert from 'node:assert/strict';+import { renderFormat } 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', () => {+ 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/);+ 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('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);+ for (const cover of [false, null, -1, Infinity, {}, '', 'intro@bad', 'intro@2@3']) assert.throws(() => normalizeConfig({ cover }), /cover must be/);+ const timeline = { duration: 8, fps: 30, scenes: [{ id: 'intro', start: 0, dur: 3 }, { id: 'next', start: 3, dur: 5 }] };+ assert.equal(resolveTimes(timeline, ['intro@end'])[0].T, 2.7);+ assert.equal(resolveTimes(timeline, ['[email protected]'])[0].T, 5.4);+ assert.equal(resolveTimes(timeline, [1e21])[0].T, 8 - 1 / 30);+ assert.throws(() => resolveTimes(timeline, ['missing']), /no scene "missing".*intro, next/);+});++test('verify explains that GIF is unsupported', async () => {+ await assert.rejects(verify({ paths: { out: '/tmp' } }, { file: '/tmp/video.gif' }), /verify checks MP4 files/);+});diff --git a/test/script.test.js b/test/script.test.jsindex 822dccc..8a6aa9b 100644--- a/test/script.test.js+++ b/test/script.test.js@@ -10,6 +10,19 @@ test('parses title, scenes, attributes and narration', () => {assert.equal(r.scenes[0].text, 'Hello there.');});+test('quoted attributes keep spaces and commas with either kind of quote', () => {+ const r = parseScript('## a {hold="1.5", chapter="How the resolver finds it" transition=cut}\nHi.\n## b {chapter=\'More, with spaces\' min:3}\nBye.');+ assert.deepEqual(r.scenes[0].attrs, { hold: 1.5, chapter: 'How the resolver finds it', transition: 'cut' });+ assert.deepEqual(r.scenes[1].attrs, { chapter: 'More, with spaces', min: 3 });+ assert.deepEqual(parseScript('## old {hold=1.5,min:3 lead=0 transition=fade}\nHi.').scenes[0].attrs, { hold: 1.5, min: 3, lead: 0, transition: 'fade' });+ assert.equal(parseScript("## old {note=don't}\nHi.").scenes[0].attrs.note, "don't");+});++test('chapter titles must have 1 to 60 characters', () => {+ for (const title of ['', ' ', 'x'.repeat(61)]) assert.throws(() => parseScript(`## a {chapter="${title}"}\nHi.`), /chapter title must be 1 to 60 characters/);+ assert.equal(parseScript(`## a {chapter="${'x'.repeat(60)}"}\nHi.`).scenes[0].attrs.chapter.length, 60);+});+test('markers, pauses and pronunciation overrides', () => {const units = tokenizeNarration('The {DNS|D N S} lookup, [pause 0.4] takes [#fast] {20ms|twenty milliseconds}.');const words = units.filter((u) => u.type === 'word');diff --git a/test/stills-browser.test.js b/test/stills-browser.test.jsnew file mode 100644index 0000000..ab0e97e--- /dev/null+++ b/test/stills-browser.test.js@@ -0,0 +1,35 @@+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 { findChrome } from '../src/browser.js';+import { loadProject } from '../src/project.js';+import { withEngine } from '../src/pipeline.js';++let chrome;+try { chrome = findChrome(); } catch {}+test('stills preserve PNG by default and support JPEG covers', { skip: !chrome }, async () => {+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'explainroo-stills-'));+ try {+ fs.writeFileSync(path.join(dir, 'video.json'), JSON.stringify({ theme: 'clean', size: '320x180', captions: false }));+ fs.writeFileSync(path.join(dir, 'script.md'), '## intro\n');+ fs.writeFileSync(path.join(dir, 'scenes.js'), 'export default { intro(s) { s.bg("#245cff"); } };');+ const project = loadProject(dir);+ const timeline = { duration: 1, frames: 30, fps: 30, width: 320, height: 180, transitionSeconds: 0,+ scenes: [{ id: 'intro', index: 0, start: 0, dur: 1, words: [], marks: {}, voice: null, transition: 'none' }] };+ await withEngine(project, timeline, {}, async (page) => {+ await page.evaluate(() => window.explainroo.stills([{ T: 0.5, path: 'out/still.png' }]));+ await page.evaluate(() => window.explainroo.stills([{ T: 0.5, path: 'build/cover.jpg' }], { type: 'image/jpeg', quality: 0.9 }));+ const dimensions = await page.evaluate(async () => {+ const img = new Image();+ img.src = '/project/build/cover.jpg';+ await img.decode();+ return [img.naturalWidth, img.naturalHeight];+ });+ assert.deepEqual(dimensions, [320, 180]);+ });+ assert.equal(fs.readFileSync(path.join(dir, 'out/still.png')).subarray(1, 4).toString(), 'PNG');+ assert.deepEqual([...fs.readFileSync(path.join(dir, 'build/cover.jpg')).subarray(0, 3)], [0xff, 0xd8, 0xff]);+ } finally { fs.rmSync(dir, { recursive: true, force: true }); }+});diff --git a/test/subtitles.test.js b/test/subtitles.test.jsnew file mode 100644index 0000000..6eeb6ab--- /dev/null+++ b/test/subtitles.test.js@@ -0,0 +1,83 @@+import test from 'node:test';+import assert from 'node:assert/strict';+import { subtitleCues, toSrt, toVtt } from '../src/subtitles.js';+import { parseScript } from '../src/script.js';+import { buildTimeline } from '../src/timeline.js';+import { normalizeConfig } from '../src/project.js';++function scene(text, { start = 0, step = 0.3, dur = 100 } = {}) {+ return { start, dur, words: text.split(' ').map((text, i) => ({ text, start: i * step, end: i * step + 0.2 })) };+}++test('cues keep every word inside two 42-character lines and six seconds', () => {+ for (const step of [0.15, 0.7]) {+ const sc = scene('This longer explanation contains several ordinary words and keeps going until both lines fill up with enough text to need another cue before the sentence ends.', { step });+ const cues = subtitleCues({ scenes: [sc] });+ assert.ok(cues.length > 1);+ assert.equal(cues.map((c) => c.text.replaceAll('\n', ' ')).join(' '), sc.words.map((w) => w.text).join(' '));+ for (const c of cues) {+ assert.ok(c.end - c.start <= 6);+ assert.ok(c.text.split('\n').length <= 2);+ assert.ok(c.text.split('\n').every((line) => line.length <= 42));+ }+ }+});++test('sentence endings start new cues and padding stops at the next cue', () => {+ const cues = subtitleCues({ scenes: [scene('Hello there. Another sentence! Last one?')] });+ assert.deepEqual(cues.map((c) => c.text), ['Hello there.', 'Another sentence!', 'Last one?']);+ assert.equal(cues[0].end, cues[1].start);+ assert.equal(cues[2].end, 1.95);+});++test('line and cue breaks prefer commas and other punctuation', () => {+ const line = subtitleCues({ scenes: [scene('Here is a useful clause, followed by more words for the second line')] });+ assert.equal(line[0].text, 'Here is a useful clause,\nfollowed by more words for the second line');+ const cues = subtitleCues({ scenes: [scene('Here is a useful clause, followed by several words that keep going until the subtitle has no room left for more words')] });+ assert.equal(cues[0].text, 'Here is a useful clause,');+ const orphan = subtitleCues({ scenes: [scene("Computers don't find each other by name, though.")] });+ assert.equal(orphan[0].text, "Computers don't find each\nother by name, though.");+});++test('pauses over 0.6 seconds and scene boundaries start new cues', () => {+ const sc = { start: 2, dur: 4, words: [+ { text: 'One', start: 0, end: 0.2 },+ { text: 'two', start: 0.8, end: 1 },+ { text: 'three', start: 1.61, end: 1.9 },+ ] };+ const cues = subtitleCues({ scenes: [sc, scene('Next', { start: 6, dur: 0.3 })] });+ assert.deepEqual(cues.map((c) => c.text), ['One two', 'three', 'Next']);+ assert.equal(cues[0].start, 2);+ assert.equal(cues[0].end, 3.25);+ assert.equal(cues.at(-1).end, 6.3);+});++test('partial ranges keep overlapping cues, clip times and start at clip zero', () => {+ const timeline = { scenes: [scene('First. Second. Third.', { step: 1 })] };+ assert.deepEqual(subtitleCues(timeline, { from: 0.2, to: 1.2 }), [+ { start: 0, end: 0.25, text: 'First.' },+ { start: 0.8, end: 1, text: 'Second.' },+ ]);+ assert.deepEqual(subtitleCues(timeline, { from: 3 }), []);+ assert.deepEqual(subtitleCues({ scenes: [{ start: 0, words: [] }] }), []);+});++test('subtitles use the shown form from pronunciation overrides', () => {+ const script = parseScript('## intro\nThe {DNS|D N S} answer.');+ const words = script.scenes[0].units.map((u, i) => ({ text: u.display, start: i * 0.3, end: i * 0.3 + 0.2 }));+ const timeline = buildTimeline({ script, config: normalizeConfig({}) }, { intro: { duration: 1, words } });+ assert.equal(subtitleCues(timeline)[0].text, 'The DNS answer.');+});++test('an indivisible word over 42 characters gives a useful error', () => {+ assert.throws(() => subtitleCues({ scenes: [scene('x'.repeat(43))] }), /Shorten its shown text/);+});++test('SRT and VTT have millisecond timestamps, UTF-8 text and LF endings', () => {+ const cues = [{ start: 1.234, end: 3.5, text: 'Café\nline two' }, { start: 3661.9996, end: 3663, text: 'End.' }];+ assert.equal(toSrt(cues), '1\n00:00:01,234 --> 00:00:03,500\nCafé\nline two\n\n2\n01:01:02,000 --> 01:01:03,000\nEnd.\n\n');+ assert.equal(toVtt(cues), 'WEBVTT\n\n00:00:01.234 --> 00:00:03.500\nCafé\nline two\n\n01:01:02.000 --> 01:01:03.000\nEnd.\n\n');+ assert.equal(toSrt([]), '');+ assert.equal(toVtt([]), 'WEBVTT\n\n');+ assert.match(toVtt([{ start: 0, end: 1, text: '<tag> & text' }]), /<tag> & text/);+});