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.

Check text at playback size and add a readable SQLite demo (v0.1.1)

Vincent Schmalbach53479053ffd6
diff --git a/AGENTS.md b/AGENTS.md
index e01f38d..60bdabb 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -117,6 +117,14 @@ When you ask, put everything you need in one message. Typical reasons to ask:
empty? Does the sheet show something new every few seconds? Fix what is
wrong and look again.
+ For Reddit and other feeds, also run `check videos/<name> --view-width
+ 854`. It warns when visible text shrinks below 16px in that player.
+ This is a size check, not a guarantee about platform compression. Show
+ only the current query or result, use bigger type, and zoom into details.
+ Review a still at `--scale 0.4448` too (about 480p for a 1080p video).
+ Never upload `draft.mp4`. After uploading, check the platform's lower
+ quality copy as well as its full-size copy.
+
10. **Make the video and check the file.**
```bash
diff --git a/README.md b/README.md
index 6b8c7d6..90045b0 100644
--- a/README.md
+++ b/README.md
@@ -67,7 +67,8 @@ explainroo does the rest:
An agent can't watch a video, so explainroo gives it other ways to check its
work. It saves stills of the scenes and a sheet of small frames for the whole
video. A layout check finds text that is cut off or overlaps, and a speech
-check finds words the voice got wrong.
+check finds words the voice got wrong. For a feed-sized player,
+`explainroo check videos/<name> --view-width 854` also flags small text.
None of this leaves your computer, and it costs nothing. Your coding agent is
a separate service with its own terms and prices. If you want, the agent can
diff --git a/engine/frame.html b/engine/frame.html
index 4237ef9..c3cfc0a 100644
--- a/engine/frame.html
+++ b/engine/frame.html
@@ -83,8 +83,8 @@ window.explainrooReady = (async () => {
await upload(path, blob);
return { width: sheet.width, height: sheet.height };
},
- check(step) {
- return engine.check(step);
+ check(step, viewWidth) {
+ return engine.check(step, viewWidth);
},
async soundtrack(path) {
const { buffer, cues, errors } = await renderAudio(engine, audio);
diff --git a/engine/readability.js b/engine/readability.js
new file mode 100644
index 0000000..aa1ba83
--- /dev/null
+++ b/engine/readability.js
@@ -0,0 +1,9 @@
+// Text size after the player shrinks the video. Sizes already include the
+// camera/group transform and are in design pixels, independent of QA scale.
+export function playbackTextIssue(text, width, height, viewWidth) {
+ if (!Number.isFinite(viewWidth) || viewWidth <= 0) throw new Error('view width must be a positive number');
+ if (text.alpha <= 0.95 || text.x1 <= 0 || text.y1 <= 0 || text.x0 >= width || text.y0 >= height) return null;
+ const size = text.size * Math.min(1, viewWidth / width);
+ if (size >= 16) return null;
+ return `"${text.text.slice(0, 40)}" is ${size.toFixed(1)}px at a ${viewWidth}px player width; enlarge important text or zoom in (aim for at least 16px)`;
+}
diff --git a/engine/runtime.js b/engine/runtime.js
index 725cd54..22df162 100644
--- a/engine/runtime.js
+++ b/engine/runtime.js
@@ -9,6 +9,7 @@ import { buildPhrases, drawCaptions } from './captions.js';
import { hashStr, mulberry32, suggest, contrast, opaque, withAlpha } from './util.js';
import { layoutAreas } from './layout.js';
import { UI } from './ui.js';
+import { playbackTextIssue } from './readability.js';
Stage.UI = UI;
@@ -285,7 +286,7 @@ export class Engine {
}
// Samples every scene and reports layout problems.
- check(step = 0.25) {
+ check(step = 0.25, viewWidth = null) {
const issues = [];
const add = (level, scene, t, message) => issues.push({ level, scene, t: t === null ? null : Math.round(t * 100) / 100, message });
for (const id of this.extraScenes) add('warn', id, null, `scenes.js has a function "${id}" but script.md has no scene with that id, so it is never shown`);
@@ -320,6 +321,10 @@ export class Engine {
for (const pr of this.textLog.filter((x) => x.problem)) once(`problem:${sc.id}:${pr.problem}`, () => add('error', sc.id, t, pr.problem));
const texts = this.textLog.filter((x) => !x.problem && x.alpha > 0.5);
for (const tx of texts) {
+ if (viewWidth !== null) {
+ const message = playbackTextIssue(tx, W, H, viewWidth);
+ if (message) once(`playback:${sc.id}:${tx.text}`, () => add('warn', sc.id, t, message));
+ }
const label = tx.text.length > 40 ? tx.text.slice(0, 37) + '...' : tx.text;
// UI kit text (s.ui) may leave the frame on purpose while the
// camera zooms or pans; app screens use smaller text than slides.
diff --git a/examples/sqlite-demo/README.md b/examples/sqlite-demo/README.md
new file mode 100644
index 0000000..3b3c81b
--- /dev/null
+++ b/examples/sqlite-demo/README.md
@@ -0,0 +1,19 @@
+# SQLite demo
+
+An unofficial SQLite 3.53.4 demo using example bakery orders. The SQL and
+results were captured with the official Linux CLI on October 3, 2026.
+The video shows excerpts, with the long STRICT statement and error wrapped
+at spaces. The first orders view is a summary of the example data.
+
+This revision uses 40px terminal text and omits earlier terminal history.
+The original 24px text was sharp in 1080p but too small in Reddit's 480p copy.
+
+```bash
+node bin/explainroo.js check examples/sqlite-demo --view-width 854
+node bin/explainroo.js still examples/sqlite-demo --scale 0.4448
+node bin/explainroo.js render examples/sqlite-demo
+node bin/explainroo.js verify examples/sqlite-demo
+```
+
+Review the small stills and the platform's actual upload before sharing it.
+The size check is a heuristic; it cannot control streaming quality or codecs.
diff --git a/examples/sqlite-demo/scenes.js b/examples/sqlite-demo/scenes.js
new file mode 100644
index 0000000..392e8a4
--- /dev/null
+++ b/examples/sqlite-demo/scenes.js
@@ -0,0 +1,423 @@
+// Feed revision: show only the current command/result in 40px type.
+// SQL is unchanged; the STRICT statement and error wrap at spaces.
+// Earlier terminal history is deliberately omitted.
+// An unofficial SQLite demo, drawn with the UI kit (s.ui) on a dark teal
+// stage. No logo: the name is plain text. Every line in the terminal comes
+// from a real interactive run of the official sqlite3 3.53.4 for Linux in a
+// 76 column terminal on 2026-10-03: the banner, the continuation prompts
+// ("(x1...>" inside the parentheses), the STRICT error, the box tables and
+// the backup. The CLI prints no colors, so the terminal text has one color;
+// the bands, rings and cards are part of the video. Only the "$ " shell
+// prompt is not printed by SQLite. The bakery, its orders, the names and the
+// pickup times are example data written for this video.
+
+const K = {
+ win: '#081a22',
+ bar: '#06141b',
+ line: '#1b3a48',
+ text: '#dce9ef',
+ dim: '#86a1ae',
+ faint: '#2a4756',
+ blue: '#56b9ea',
+ red: '#ff7d70',
+ green: '#5ed68f',
+ white: '#eef6fa',
+ ink: '#0a2531',
+ soft: '#4d6875',
+ acc: '#0f6f9e',
+ err: '#c23b2e',
+ ok: '#16794a',
+};
+const MONO = 'JetBrains Mono';
+const SIZE = 40;
+const ROW = 48;
+const TRACK = 0.01;
+
+const clamp = (v, a = 0, b = 1) => Math.max(a, Math.min(b, v));
+const lerp = (a, b, p) => a + (b - a) * p;
+
+function rr(s, x, y, w, h, r, fill, stroke, lw = 1.5) {
+ const c = s.ctx;
+ c.beginPath();
+ c.roundRect(x, y, w, h, r);
+ if (fill) {
+ c.fillStyle = fill;
+ c.fill();
+ }
+ if (stroke) {
+ c.strokeStyle = stroke;
+ c.lineWidth = lw;
+ c.stroke();
+ }
+}
+
+// Draws fn with an extra alpha, moved down by dy.
+function alpha(s, a, fn, dy = 0) {
+ if (a <= 0.002) return;
+ s.ctx.save();
+ s.ctx.globalAlpha *= clamp(a);
+ s.ctx.translate(0, dy);
+ fn();
+ s.ctx.restore();
+}
+
+let CW = 0;
+const cw = (u) => CW || (CW = u.measure('MMMMMMMMMM', SIZE, 400, MONO, false, TRACK) / 10);
+
+// The stage: dark teal with a soft blue light from the top, and the headline.
+function stage(s, title, o = {}) {
+ const u = s.ui;
+ u.backdrop();
+ const c = s.ctx;
+ c.save();
+ c.setTransform(s.engine.scale, 0, 0, s.engine.scale, 0, 0);
+ const glow = c.createRadialGradient(960, -300, 100, 960, -300, 1450);
+ glow.addColorStop(0, 'rgba(86, 185, 234, 0.18)');
+ glow.addColorStop(1, 'rgba(86, 185, 234, 0)');
+ c.fillStyle = glow;
+ c.fillRect(0, 0, 1920, 1080);
+ c.restore();
+ if (title) u.headline(title, s.W / 2, 150, { size: 70, at: o.at ?? 0.15, out: o.out });
+ return u;
+}
+
+const ry = (gr, r) => gr.top + r * ROW + ROW / 2;
+const cx = (u, gr, col) => gr.left + col * cw(u);
+
+// Box drawing characters, drawn as lines so they join like in a terminal:
+// [left, right, up, down, round]; 2 is a double line.
+const BOXCH = {
+ '─': [1, 1, 0, 0], '═': [2, 2, 0, 0], '│': [0, 0, 1, 1],
+ '╭': [0, 1, 0, 1, 1], '╮': [1, 0, 0, 1, 1], '╰': [0, 1, 1, 0, 1], '╯': [1, 0, 1, 0, 1],
+ '┬': [1, 1, 0, 1], '┴': [1, 1, 1, 0], '┼': [1, 1, 1, 1],
+ '╞': [0, 2, 1, 1], '╡': [2, 0, 1, 1], '╪': [2, 2, 1, 1],
+};
+
+function boxChar(s, ch, x, y, w, color) {
+ const [l, r, up, dn, round] = BOXCH[ch];
+ const c = s.ctx;
+ const xm = x + w / 2;
+ const y0 = y - ROW / 2;
+ const y1 = y + ROW / 2;
+ c.save();
+ c.strokeStyle = color;
+ c.lineWidth = 1.8;
+ c.lineCap = 'butt';
+ c.beginPath();
+ if (round) {
+ const hx = l ? x : x + w;
+ const vy = up ? y0 : y1;
+ c.moveTo(hx, y);
+ c.arcTo(xm, y, xm, vy, w * 0.45);
+ c.lineTo(xm, vy);
+ } else {
+ if (up || dn) {
+ c.moveTo(xm, up ? y0 : y);
+ c.lineTo(xm, dn ? y1 : y);
+ }
+ const h = (dy, a, b) => {
+ c.moveTo(a, y + dy);
+ c.lineTo(b, y + dy);
+ };
+ if (l === 1) h(0, x, xm);
+ if (r === 1) h(0, xm, x + w);
+ if (l === 2) {
+ h(-3, x, xm);
+ h(3, x, xm);
+ }
+ if (r === 2) {
+ h(-3, xm, x + w);
+ h(3, xm, x + w);
+ }
+ }
+ c.stroke();
+ c.restore();
+}
+
+// One terminal line: text runs in the monospace font, box characters as lines.
+function line(s, u, gr, t, i, color = K.text) {
+ const y = ry(gr, i);
+ let run = '';
+ let start = 0;
+ const flush = () => {
+ // A little letter spacing keeps the font from joining -> and >> into one sign.
+ if (run.trim()) u.text(run, cx(u, gr, start), y + 1, { size: SIZE, font: MONO, color, tracking: TRACK });
+ run = '';
+ };
+ [...t].forEach((ch, k) => {
+ if (BOXCH[ch]) {
+ flush();
+ boxChar(s, ch, cx(u, gr, k), y, cw(u), color);
+ } else {
+ if (!run) start = k;
+ run += ch;
+ }
+ });
+ flush();
+}
+
+// A white document with a folded corner.
+function doc(s, u, x, y, w, h, o = {}) {
+ const c = s.ctx;
+ const r = 18;
+ const f = o.fold ?? 38;
+ const path = () => {
+ c.beginPath();
+ c.moveTo(x + r, y);
+ c.lineTo(x + w - f, y);
+ c.lineTo(x + w, y + f);
+ c.lineTo(x + w, y + h - r);
+ c.arcTo(x + w, y + h, x + w - r, y + h, r);
+ c.lineTo(x + r, y + h);
+ c.arcTo(x, y + h, x, y + h - r, r);
+ c.lineTo(x, y + r);
+ c.arcTo(x, y, x + r, y, r);
+ c.closePath();
+ };
+ c.save();
+ c.shadowColor = 'rgba(0, 0, 0, 0.35)';
+ c.shadowBlur = 50 * u.k;
+ c.shadowOffsetY = 18 * u.k;
+ path();
+ c.fillStyle = '#ffffff';
+ c.fill();
+ c.restore();
+ c.beginPath();
+ c.moveTo(x + w - f, y);
+ c.lineTo(x + w - f, y + f - 6);
+ c.arcTo(x + w - f, y + f, x + w - f + 6, y + f, 6);
+ c.lineTo(x + w, y + f);
+ c.closePath();
+ c.fillStyle = '#cfe2eb';
+ c.fill();
+}
+
+const P = 'sqlite> ';
+const C = ' ...> ';
+const IN = '(x1...> ';
+const join = (lines) => lines.map(([p, t]) => p + t);
+const flat = (rows) => rows.map((r) => (typeof r === 'string' ? r : r.t));
+const BANNER = ['SQLite version 3.53.4 2026-07-24 19:02:57', 'Enter ".help" for usage hints.'];
+const CREATE = [
+ [P, 'CREATE TABLE orders('],
+ [IN, ' id INTEGER PRIMARY KEY,'],
+ [IN, ' item TEXT,'],
+ [IN, ' qty INTEGER,'],
+ [IN, ' info TEXT'],
+ [IN, ') STRICT;'],
+];
+const SELECT1 = [[P, 'SELECT id, item, qty FROM orders;']];
+const TABLE1 = [
+ '╭────┬───────────┬─────╮',
+ '│ id │ item │ qty │',
+ '╞════╪═══════════╪═════╡',
+ { t: '│ 1 │ Bread │ 2 │', id: 't1' },
+ { t: '│ 2 │ Croissant │ 6 │', id: 't1' },
+ { t: '│ 3 │ Bagel │ 4 │', id: 't1' },
+ { t: '│ 4 │ Bread │ 1 │', id: 't1' },
+ '╰────┴───────────┴─────╯',
+];
+const SELECT2 = [
+ [P, "SELECT item, info ->> 'name' AS name FROM orders"],
+ [C, "WHERE info ->> 'pickup' = '08:00';"],
+];
+const TABLE2 = [
+ '╭───────┬──────╮',
+ '│ item │ name │',
+ '╞═══════╪══════╡',
+ { t: '│ Bread │ Ana │', id: 't2' },
+ { t: '│ Bagel │ Cleo │', id: 't2' },
+ '╰───────┴──────╯',
+];
+const SELECT3 = [
+ [P, 'SELECT id, item, qty,'],
+ [C, ' sum(qty) OVER (ORDER BY id) AS running'],
+ [C, 'FROM orders;'],
+];
+const TABLE3 = [
+ '╭────┬───────────┬─────┬─────────╮',
+ '│ id │ item │ qty │ running │',
+ '╞════╪═══════════╪═════╪═════════╡',
+ { t: '│ 1 │ Bread │ 2 │ 2 │', id: 't3' },
+ { t: '│ 2 │ Croissant │ 6 │ 8 │', id: 't3' },
+ { t: '│ 3 │ Bagel │ 4 │ 12 │', id: 't3' },
+ { t: '│ 4 │ Bread │ 1 │ 13 │', id: 't3' },
+ '╰────┴───────────┴─────┴─────────╯',
+];
+const TABLE4 = ['╭──────────╮', '│ count(*) │', '╞══════════╡', { t: '│ 4 │', id: 't4' }, '╰──────────╯'];
+
+
+// Feed-sized shots: only the current command and result, in 40px type.
+// SQL and output are unchanged; long lines wrap at their existing spaces.
+function focused(s, title, lines, highlight = []) {
+ const u = stage(s, title);
+ u.card(90, 250, 1740, 690, { r: 20, fill: K.win, border: false, lift: 0 });
+ lines.forEach((text, i) => {
+ const y = 302 + i * 48;
+ if (highlight.includes(i)) rr(s, 116, y - 24, 1688, 48, 8, '#163b4c');
+ line(s, u, { left: 130, top: 278 }, text, i, text.startsWith('Error') || text.startsWith('INTEGER column') ? K.red : K.text);
+ });
+ return u;
+}
+
+export default {
+ hook(s) {
+ const fl = s.time('#file');
+ const sv = s.time('#server');
+ const up = s.p(fl - 0.55, 0.65, 'inOut');
+ const u = stage(s, null);
+ // The name as plain text from the first frame (the cover).
+ u.eyebrow('Unofficial demo', 960, lerp(330, 152, up), { align: 'center', size: 36 });
+ u.text('SQLite', 960, lerp(452, 236, up), { size: lerp(170, 110, up), weight: 700, color: K.white, align: 'center', tracking: lerp(-4, -2, up) });
+ u.headline('An embedded *SQL database engine*', 960, lerp(612, 352, up), { size: lerp(66, 50, up), at: s.time('#name') + 0.4 });
+ // One file holds it all.
+ const FX = 430;
+ const FY = 430;
+ const FW = 620;
+ const FH = 400;
+ u.pop(fl - 0.1, FX + FW / 2, FY + FH / 2, () => {
+ doc(s, u, FX, FY, FW, FH);
+ u.icon('database', FX + 62, FY + 66, 38, K.acc, 2.2);
+ u.text('bakery.db', FX + 102, FY + 67, { size: 44, font: MONO, color: K.ink, tracking: TRACK });
+ s.ctx.fillStyle = '#e1ecf1';
+ s.ctx.fillRect(FX + 36, FY + 120, FW - 72, 2);
+ }, { sfx: 'pop' });
+ [
+ ['table', 'tables', s.cue('Tables') + 0.25],
+ ['list-ordered', 'indexes', s.cue('indexes')],
+ ['eye', 'views', s.cue('views')],
+ ].forEach(([icon, label, at], i) => {
+ const yy = FY + 182 + i * 72;
+ u.pop(at, FX + 170, yy, () => {
+ u.icon(icon, FX + 74, yy, 32, K.acc, 2.2);
+ u.text(label, FX + 116, yy + 1, { size: 44, weight: 600, color: K.ink });
+ }, { sfx: 'tick' });
+ });
+ // No server next to it.
+ const SX = 1150;
+ const SY = 430;
+ const SW = 340;
+ const SH = 400;
+ u.pop(sv - 0.1, SX + SW / 2, SY + SH / 2, () => {
+ const c = s.ctx;
+ c.save();
+ c.setLineDash([12, 10]);
+ rr(s, SX, SY, SW, SH, 22, 'rgba(255, 255, 255, 0.04)', K.dim, 2);
+ c.restore();
+ u.icon('server', SX + SW / 2, SY + 165, 120, '#9fb7c3', 2);
+ u.text('no server process', SX + SW / 2, SY + 330, { size: 44, weight: 600, color: K.white, align: 'center' });
+ }, { sfx: 'pop' });
+ const strike = s.p(sv + 0.45, 0.35, 'out');
+ if (strike > 0) {
+ const c = s.ctx;
+ c.save();
+ c.strokeStyle = K.red;
+ c.lineWidth = 9;
+ c.lineCap = 'round';
+ c.beginPath();
+ c.moveTo(SX + 80, SY + 255);
+ c.lineTo(SX + 80 + (SW - 160) * strike, SY + 255 - 180 * strike);
+ c.stroke();
+ c.restore();
+ }
+ s.sfx('thud', sv + 0.45, { gain: 0.3 });
+ },
+
+ open(s) {
+ const u = focused(s, 'Open a *database file*', [
+ '$ sqlite3 bakery.db', '', ...BANNER, '', 'sqlite> ',
+ ], [0]);
+ if (s.t >= s.time('#new')) u.text('New file: bakery.db', 130, 830, { size: 44, color: K.blue });
+ },
+
+ strict(s) {
+ const error = s.t >= s.time('#error');
+ const lines = error ? [
+ 'sqlite> INSERT INTO orders(item, qty)',
+ " ...> VALUES ('Bread', 'a dozen');", '',
+ 'Error near line 7: cannot store TEXT value in',
+ 'INTEGER column orders.qty',
+ ] : [...join(CREATE)];
+ focused(s, '*STRICT* tables', lines, error ? [3, 4] : [5]);
+ },
+
+ box(s) {
+ const selected = s.t >= s.time('#select');
+ const lines = selected ? [
+ ...join(SELECT1), '', ...flat(TABLE1),
+ ] : [
+ 'Four example orders', '',
+ 'id item qty',
+ ' 1 Bread 2',
+ ' 2 Croissant 6',
+ ' 3 Bagel 4',
+ ' 4 Bread 1',
+ ];
+ focused(s, 'Results in a *box*', lines, selected && s.t >= s.time('#right') ? [5, 6, 7, 8] : []);
+ },
+
+ json(s) {
+ const query = s.t >= s.time('#arrow');
+ const lines = query ? [
+ ...join(SELECT2), '', ...flat(TABLE2),
+ ] : [
+ 'info TEXT', '',
+ '{"name":"Ana","pickup":"08:00"}', '',
+ '{"name":"Cleo","pickup":"08:00"}',
+ ];
+ focused(s, '*JSON* as text', lines, query ? [0, 1] : [2, 4]);
+ },
+
+ window(s) {
+ focused(s, 'A *running total*', [
+ ...join(SELECT3), '', ...flat(TABLE3),
+ ], [1]);
+ },
+
+ backup(s) {
+ const copied = s.t >= s.time('#copy');
+ focused(s, 'Copy it with *.backup*', [
+ 'sqlite> .backup bakery-copy.db', '',
+ ...(copied ? [
+ 'sqlite> .open bakery-copy.db',
+ 'sqlite> SELECT count(*) FROM orders;', '', ...flat(TABLE4),
+ ] : ['bakery.db → bakery-copy.db']),
+ ], [0]);
+ },
+
+ outro(s) {
+ const also = s.time('#also');
+ const point = s.time('#point');
+ const made = s.time('#made');
+ const end = made - 0.3;
+ const u = stage(s, 'Make a video like *this one*', { out: end, at: also - 0.1 });
+ const lines = [
+ 'Make a short video about [your topic].',
+ 'Use explainroo:',
+ 'https://github.com/vincentsch/explainroo',
+ 'Read AGENTS.md and follow the steps.',
+ ];
+ const typed = u.typed(lines.join(' '), point + 0.2, 80, { gain: 0.16 });
+ u.pop(also + 0.4, 960, 560, () => {
+ rr(s, 90, 300, 1740, 440, 18, K.win, K.line);
+ u.text('your coding agent', 130, 352, { size: 40, weight: 600, color: K.dim });
+ let used = 0;
+ lines.forEach((l, i) => {
+ const n = clamp(typed.length - used, 0, l.length);
+ if (n > 0) u.text(l.slice(0, n), 130, 440 + i * 72, { size: 40, font: MONO, color: K.text, tracking: TRACK });
+ used += l.length + 1;
+ });
+ }, { sfx: 'pop' });
+ s.sfx('chime', made, { gain: 0.5 });
+ const p = u.wipe(end, { color: K.white });
+ if (p > 0) {
+ u.over(() =>
+ alpha(s, s.p(end + 0.35, 0.5, 'out'), () => {
+ u.text('SQLite', 960, 430, { size: 120, weight: 700, color: '#05222e', align: 'center', tracking: -2 });
+ u.text('Unofficial demo made with explainroo', 960, 560, { size: 40, weight: 600, color: '#05222e', align: 'center' });
+ u.text('Not affiliated with SQLite', 960, 612, { size: 40, color: '#4d6875', align: 'center' });
+ }),
+ );
+ }
+ },
+};
diff --git a/examples/sqlite-demo/script.md b/examples/sqlite-demo/script.md
new file mode 100644
index 0000000..cc24fa0
--- /dev/null
+++ b/examples/sqlite-demo/script.md
@@ -0,0 +1,35 @@
+# SQLite
+
+> Unofficial demo. Facts come from the SQLite docs on sqlite.org (About
+> SQLite, Command Line Shell For SQLite, CLI output modes, STRICT Tables, JSON
+> Functions And Operators, Window Functions and the 3.53.0 release log),
+> checked on 2026-10-03 with SQLite 3.53.4 (2026-07-24). The terminal output
+> was captured on 2026-10-03 from a real interactive run of the official
+> precompiled sqlite3 3.53.4 for Linux (sqlite-tools-linux-x64-3530400) in a
+> 76 column terminal: the banner, the continuation prompts, the STRICT error,
+> the box tables and the backup. The bakery, its orders, the names and the
+> pickup times are example data written for this video.
+
+## hook {hold=0.7}
+[#name] This is SQLite. [#file] Tables, indexes and views all sit in one file on disk, [#server] and there is no server process.
+
+## open {hold=0.8}
+[#open] Type {sqlite3|SQLite three} and a file name. [#new] If the file is not there yet, the shell makes a new one.
+
+## strict {hold=0.9}
+[#flex] By default, SQLite is flexible about column types. [#strict] Add STRICT to the table, [#error] and "a dozen" in an integer column is an error.
+
+## box {hold=0.9}
+[#insert] Add four orders. [#select] In a terminal, results now come in a box, [#right] and numbers line up on the right.
+
+## json {hold=0.9}
+[#json] JSON is stored as ordinary text. [#arrow] The double arrow pulls out one field, [#where] here to find the eight o'clock orders.
+
+## window {hold=1.0}
+[#window] A window function adds a running total, [#rows] and the query still returns every row.
+
+## backup {hold=1.0}
+[#backup] {.backup|Dot backup} copies the whole database into a new file. [#copy] Open the copy, and all four orders are there.
+
+## outro {hold=0.8}
+[#also] explainroo works with any coding agent. [#point] Point yours at the repo and ask for a video. [pause 1.0] [#made] This unofficial demo was made with explainroo.
diff --git a/examples/sqlite-demo/video.json b/examples/sqlite-demo/video.json
new file mode 100644
index 0000000..1090106
--- /dev/null
+++ b/examples/sqlite-demo/video.json
@@ -0,0 +1,17 @@
+{
+ "title": "SQLite",
+ "theme": "clean",
+ "size": "youtube",
+ "voice": "af_heart",
+ "music": true,
+ "captions": "auto",
+ "transition": "fade",
+ "pace": 1.1,
+ "brand": {
+ "accent": "#56b9ea",
+ "background": "#05222e",
+ "ink": "#eef6fa",
+ "font": "Inter",
+ "headline": "Instrument Serif"
+ }
+}
diff --git a/package-lock.json b/package-lock.json
index 75ba4c2..cc8d395 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "explainroo",
- "version": "0.1.0",
+ "version": "0.1.1",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "explainroo",
- "version": "0.1.0",
+ "version": "0.1.1",
"license": "MIT",
"dependencies": {
"@huggingface/transformers": "3.8.1",
diff --git a/package.json b/package.json
index 3029717..8a367ee 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "explainroo",
- "version": "0.1.0",
+ "version": "0.1.1",
"description": "Narrated explainer videos made by your coding agent. Pure JavaScript, local voice, no API keys.",
"keywords": [
"video",
diff --git a/src/cli.js b/src/cli.js
index 1d95e56..e0b4d19 100644
--- a/src/cli.js
+++ b/src/cli.js
@@ -26,7 +26,7 @@ Make a video
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)
sheet [project] contact sheet of the whole video (--scene id, --every s)
- check [project] find layout, timing and pronunciation problems
+ 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
@@ -117,7 +117,7 @@ export async function main(argv) {
}
case 'check': {
const project = loadProject(pos[0]);
- const r = await check(project, { log, step: num(flags.step, 'step') ?? 0.25 });
+ const r = await check(project, { log, step: num(flags.step, 'step') ?? 0.25, viewWidth: num(flags['view-width'], 'view-width') ?? null });
const errors = r.issues.filter((i) => i.level === 'error').length;
const human = r.issues.length
? r.issues.map((i) => `${i.level.toUpperCase().padEnd(5)} ${i.scene ?? ''}${i.t !== null && i.t !== undefined ? ' @' + i.t + 's' : ''}: ${i.message}`).join('\n') + `\n${errors} error(s), ${r.issues.length - errors} other finding(s) in ${r.scenes} scenes (${r.duration.toFixed(1)}s)`
diff --git a/src/qa.js b/src/qa.js
index 9ee5465..2635bf7 100644
--- a/src/qa.js
+++ b/src/qa.js
@@ -8,7 +8,8 @@ import { transcribeWords } from './models.js';
import { readWav } from './wav.js';
import { alignWords } from './align.js';
-export async function check(project, { log = () => {}, step = 0.25 } = {}) {
+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 = [];
for (const sc of project.script.scenes) {
@@ -19,7 +20,7 @@ export async function check(project, { log = () => {}, step = 0.25 } = {}) {
}
if (v && v.duration > 40) issues.push({ level: 'hint', scene: sc.id, t: null, message: `the narration runs ${v.duration.toFixed(0)}s; long scenes are easier to follow when split` });
}
- const pageIssues = await withEngine(project, timeline, { scale: 0.5, log }, (page) => page.evaluate((s) => window.explainroo.check(s), step));
+ const pageIssues = await withEngine(project, timeline, { scale: 0.5, log }, (page) => page.evaluate(([s, w]) => window.explainroo.check(s, w), [step, viewWidth]));
issues.push(...pageIssues);
const order = { error: 0, warn: 1, hint: 2 };
issues.sort((a, b) => order[a.level] - order[b.level]);
diff --git a/test/readability-browser.test.js b/test/readability-browser.test.js
new file mode 100644
index 0000000..296e651
--- /dev/null
+++ b/test/readability-browser.test.js
@@ -0,0 +1,36 @@
+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('playback check uses camera zoom and ignores the half-size QA canvas', { skip: !chrome }, async () => {
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'explainroo-readability-'));
+ try {
+ fs.writeFileSync(path.join(dir, 'video.json'), JSON.stringify({ theme: 'clean', captions: false, music: false, sfx: false }));
+ fs.writeFileSync(path.join(dir, 'script.md'), '## demo\nA query.');
+ fs.writeFileSync(path.join(dir, 'scenes.js'), `export default { demo(s) {
+ s.camera([{ at: 1, x: 960, y: 540, zoom: 2, dur: 0.1 }]);
+ s.ui.text('SELECT item FROM orders;', 800, 500, {size:24});
+ } };`);
+ const project = loadProject(dir);
+ const timeline = { pace: 1, duration: 2, frames: 60, fps: 30, width: 1920, height: 1080, transitionSeconds: 0,
+ scenes: [{ id: 'demo', index: 0, start: 0, dur: 2, words: [], marks: {}, voice: null, lead: 0, transition: 'none' }] };
+ for (const scale of [0.5, 1]) {
+ await withEngine(project, timeline, { scale }, async page => {
+ const issues = await page.evaluate(() => window.explainroo.check(0.25, 854));
+ const warnings = issues.filter(i => i.message.includes('player width'));
+ assert.equal(warnings.length, 1);
+ assert.equal(warnings[0].t, 0);
+ assert.match(warnings[0].message, /10.7px/);
+ const normal = await page.evaluate(() => window.explainroo.check(0.25));
+ assert.equal(normal.some(i => i.message.includes('player width')), false);
+ });
+ }
+ } finally { fs.rmSync(dir, { recursive: true, force: true }); }
+});
diff --git a/test/readability.test.js b/test/readability.test.js
new file mode 100644
index 0000000..94c59c7
--- /dev/null
+++ b/test/readability.test.js
@@ -0,0 +1,20 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { playbackTextIssue } from '../engine/readability.js';
+
+const text = { text: 'SELECT item FROM orders;', size: 24, alpha: 1, x0: 100, y0: 200, x1: 800, y1: 230 };
+test('full-HD terminal text needs enlarging for a 480p player', () => {
+ assert.equal(playbackTextIssue(text, 1920, 1080, 1920), null);
+ assert.match(playbackTextIssue(text, 1920, 1080, 854), /10.7px/);
+ assert.equal(playbackTextIssue({ ...text, size: 40 }, 1920, 1080, 854), null);
+ assert.equal(playbackTextIssue({ ...text, size: 24 * 2 }, 1920, 1080, 854), null);
+});
+test('fades and text outside the shot do not trigger playback warnings', () => {
+ assert.equal(playbackTextIssue({ ...text, alpha: 0.5 }, 1920, 1080, 854), null);
+ assert.equal(playbackTextIssue({ ...text, x0: 2000, x1: 2500 }, 1920, 1080, 854), null);
+ assert.match(playbackTextIssue({ ...text, x0: -100 }, 1920, 1080, 854), /enlarge/);
+});
+test('upscaling a player does not make small source text readable', () => {
+ assert.match(playbackTextIssue({ ...text, size: 12 }, 1920, 1080, 3840), /12.0px/);
+ for (const w of [0, -1, Infinity, NaN]) assert.throws(() => playbackTextIssue(text, 1920, 1080, w), /positive/);
+});