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.

Add three examples for code steps, math and Spanish narration (#22)

Vincent Schmalbachfd9b8727b811
diff --git a/examples/callbacks-to-async-await/.gitignore b/examples/callbacks-to-async-await/.gitignore
new file mode 100644
index 0000000..3c0160d
--- /dev/null
+++ b/examples/callbacks-to-async-await/.gitignore
@@ -0,0 +1,2 @@
+build/
+out/
diff --git a/examples/callbacks-to-async-await/code-versions.js b/examples/callbacks-to-async-await/code-versions.js
new file mode 100644
index 0000000..dace21c
--- /dev/null
+++ b/examples/callbacks-to-async-await/code-versions.js
@@ -0,0 +1,34 @@
+// getUser and getOrders are application helpers, not the native fetch API.
+// The callback version shows the success path. The promise versions add errors.
+export const callback = `getUser(7, user => {
+ getOrders(user.id, orders => {
+ showOrders(orders);
+ });
+});`;
+
+export const promise = `getUser(7)
+ .then(user => {
+ return getOrders(user.id);
+ })
+ .then(orders => showOrders(orders));`;
+
+export const promiseErrors = `getUser(7)
+ .then(user => {
+ return getOrders(user.id);
+ })
+ .then(orders => showOrders(orders))
+ .catch(err => showError(err));`;
+
+export const awaited = `async function loadOrders() {
+ const user = await getUser(7);
+ const orders = await getOrders(user.id);
+ showOrders(orders);
+}`;
+
+export const awaitedErrors = `async function loadOrders() {
+ try {
+ const user = await getUser(7);
+ const orders = await getOrders(user.id);
+ showOrders(orders);
+ } catch (err) { showError(err); }
+}`;
diff --git a/examples/callbacks-to-async-await/scenes.js b/examples/callbacks-to-async-await/scenes.js
new file mode 100644
index 0000000..6c435cb
--- /dev/null
+++ b/examples/callbacks-to-async-await/scenes.js
@@ -0,0 +1,106 @@
+import { callback, promise, promiseErrors, awaited, awaitedErrors } from './code-versions.js';
+
+// Every state is declared on every frame; markers drive both morphs and labels.
+const quiet = { sfx: false };
+function heading(s, title, section) {
+ s.text(section, { x: 192, y: 94, align: 'left', size: 32, font: 'mono', color: 'muted', at: -1, ...quiet });
+ s.text(title, { x: 192, y: 172, align: 'left', size: 88, font: 'display', bold: true, at: -1, ...quiet });
+}
+function editor(s, steps) {
+ s.code(steps, { x: 960, y: 570, w: 1550, size: 48, title: 'user-orders.js', lang: 'js', reveal: 'none', enter: 'none', morphDur: 0.8, ...quiet });
+}
+function notes(s, states) {
+ states.forEach(([text, at, color = 'ink'], i) => {
+ s.text(text, { x: 960, y: 956, size: 44, color, at,
+ out: states[i + 1]?.[1], enter: 'fade', dur: 0.18, exit: 'none', ...quiet });
+ });
+}
+function flow(s, times, y = 625) {
+ s.box('User 7', { id: 'user', x: 480, y, w: 310, h: 148, size: 52, color: 'blue', at: times[0], ...quiet });
+ s.box('Orders', { id: 'orders', x: 960, y, w: 310, h: 148, size: 52, color: 'purple', at: times[1], ...quiet });
+ s.box('Display', { id: 'display', x: 1440, y, w: 310, h: 148, size: 52, color: 'green', at: times[2], ...quiet });
+ s.arrow('user', 'orders', { at: times[1], color: 'blue', width: 4, ...quiet });
+ s.arrow('orders', 'display', { at: times[2], color: 'purple', width: 4, ...quiet });
+}
+export default {
+ intro(s) {
+ heading(s, 'Callbacks to async/await', 'JAVASCRIPT / ASYNCHRONOUS CODE');
+ s.text('Two requests, one dependency', { id: 'dependency', y: 350, size: 56, at: '#question', ...quiet });
+ s.annotate('dependency', { type: 'underline', color: 'accent', at: '#depends', ...quiet });
+ flow(s, ['#user', '#orders', '#display']);
+ s.text('user.id', { x: 720, y: 762, font: 'mono', size: 40, color: 'blue', at: '#orders', ...quiet });
+ },
+ callbacks(s) {
+ heading(s, 'Callbacks', '01 / FUNCTIONS THAT RUN LATER');
+ editor(s, [
+ { code: callback, at: -1, highlight: [] },
+ { code: callback, at: '#callback', highlight: [1] },
+ { code: callback, at: '#later', highlight: [1] },
+ { code: callback, at: '#nested', highlight: [2] },
+ { code: callback, at: '#display', highlight: [3] },
+ ]);
+ notes(s, [['Success path', -1, 'muted'], ['Pass a function', '#callback'], ['Run it when data arrives', '#later'], ['Start orders inside the callback', '#nested'], ['Display inside the next callback', '#display']]);
+ },
+ promises(s) {
+ heading(s, 'Promises', '02 / HELPERS NOW RETURN PROMISES');
+ editor(s, [
+ { code: callback, at: -1, highlight: [] },
+ { code: promise, at: '#promise', highlight: [1] },
+ { code: promise, at: '#future', highlight: [1] },
+ { code: promise, at: '#then', highlight: [2] },
+ { code: promise, at: '#return', highlight: [3] },
+ ]);
+ notes(s, [['A promise represents a future result', '#promise'], ['Result arrives later', '#future'], ['then receives the user', '#then'], ['Return the orders promise', '#return', 'accent']]);
+ s.sfx('whoosh', '#promise', { gain: 0.12 });
+ },
+ chain(s) {
+ heading(s, 'Connect the results', '02 / A SINGLE PROMISE CHAIN');
+ editor(s, [
+ { code: promise, at: -1, highlight: [3] },
+ { code: promise, at: '#wait', highlight: [3] },
+ { code: promise, at: '#orders', highlight: [5] },
+ { code: promiseErrors, at: '#catch', highlight: [6] },
+ { code: promiseErrors, at: '#either', highlight: [1, 3, 6] },
+ ]);
+ notes(s, [['Return connects the two requests', '#wait'], ['The next then receives the orders', '#orders'], ['catch handles rejection', '#catch'], ['Failures from either request', '#either']]);
+ s.sfx('click', '#catch', { gain: 0.1 });
+ },
+ asyncVersion(s) {
+ heading(s, 'async / await', '03 / THE SAME REQUEST ORDER');
+ editor(s, [
+ { code: promiseErrors, at: -1, highlight: [] },
+ { code: awaited, at: '#async', highlight: [1] },
+ { code: awaited, at: '#syntax', highlight: [2, 3] },
+ { code: awaited, at: '#first', highlight: [2] },
+ { code: awaited, at: '#second', highlight: [3] },
+ ]);
+ notes(s, [['async enables await', '#async'], ['Success path', '#syntax', 'muted'], ['The user result becomes a variable', '#first'], ['Then fetch orders with user.id', '#second']]);
+ s.sfx('whoosh', '#async', { gain: 0.12 });
+ },
+ waiting(s) {
+ heading(s, 'What await does', '03 / WAITING AND FAILURE');
+ editor(s, [
+ { code: awaited, at: -1, highlight: [2] },
+ { code: awaited, at: '#pause', highlight: [2] },
+ { code: awaited, at: '#other', highlight: [2] },
+ { code: awaited, at: '#throws', highlight: [2, 3] },
+ { code: awaitedErrors, at: '#try', highlight: [2, 6] },
+ ]);
+ notes(s, [['This function pauses at await', '#pause'], ['Other JavaScript can run', '#other', 'accent'], ['Rejection throws at await', '#throws'], ['try / catch handles the failure', '#try']]);
+ s.sfx('click', '#try', { gain: 0.1 });
+ },
+ summary(s) {
+ heading(s, 'One sequence, three styles', 'JAVASCRIPT / CALLBACKS TO ASYNC/AWAIT');
+ const styles = [
+ ['Callbacks', 'Nested functions', 480, '#callbacks', 'blue'],
+ ['Promises', 'Returned promises', 960, '#promises', 'purple'],
+ ['async / await', 'Awaited results', 1440, '#await', 'accent'],
+ ];
+ styles.forEach(([title, detail, x, at, color]) => {
+ s.text(title, { x, y: 404, size: 54, bold: true, color, at, ...quiet });
+ s.text(detail, { x, y: 482, size: 36, color: 'muted', at, ...quiet });
+ });
+ flow(s, [-1, -1, -1], 715);
+ s.text('Fetch user, then orders, then display', { y: 935, size: 48, at: '#read', ...quiet });
+ },
+};
diff --git a/examples/callbacks-to-async-await/script.md b/examples/callbacks-to-async-await/script.md
new file mode 100644
index 0000000..a9b0813
--- /dev/null
+++ b/examples/callbacks-to-async-await/script.md
@@ -0,0 +1,22 @@
+# JavaScript: callbacks to async/await
+
+## intro {chapter="Callbacks"}
+[#question] How does JavaScript handle two requests that [#depends] depend on each other? Our helper functions [#user] fetch a user, then [#orders] that user's orders, and [#display] display them.
+
+## callbacks {transition=cut}
+[#callback] Here, a callback is a function that [#later] runs after a result arrives. [#nested] When the user arrives, its callback starts fetching orders. [#display] Another callback displays them.
+
+## promises {chapter="Promises" transition=cut}
+[#promise] Now use helpers that return promises, which represent [#future] future results. A then handler [#then] receives the user, and [#return] returns the promise for their orders.
+
+## chain {transition=cut}
+[#wait] Returning that promise makes the next handler [#orders] wait for the orders. A [#catch] catch handler handles failures from [#either] either request.
+
+## asyncVersion {chapter="Async and await" transition=cut}
+[#async] The {async|a sink} keyword lets a function use [#syntax] {await|a wait} expressions. Each [#first] {await|a wait} gives us the result when its [#second] promise succeeds.
+
+## waiting {transition=cut}
+[#pause] While this function is waiting, [#other] other JavaScript can keep running. A rejected promise [#throws] makes this function throw, so [#try] try and catch handle failures.
+
+## summary {hold=1.1 transition=fade}
+[#callbacks] Callbacks nest the steps, and [#promises] promises connect them through handlers. [#await] The {async|a sink} and {await|a wait} keywords make promise based code [#read] easier to read.
diff --git a/examples/callbacks-to-async-await/video.json b/examples/callbacks-to-async-await/video.json
new file mode 100644
index 0000000..90a5396
--- /dev/null
+++ b/examples/callbacks-to-async-await/video.json
@@ -0,0 +1,16 @@
+{
+ "title": "JavaScript: callbacks to async/await",
+ "theme": "midnight",
+ "size": "youtube",
+ "voice": "af_heart",
+ "music": {
+ "style": "tech",
+ "volume": 0.12
+ },
+ "captions": false,
+ "speed": 0.95,
+ "sfx": "minimal",
+ "transition": "fade",
+ "cover": "intro@end",
+ "end": 1.0
+}
diff --git a/examples/circle-area/.gitignore b/examples/circle-area/.gitignore
new file mode 100644
index 0000000..3c0160d
--- /dev/null
+++ b/examples/circle-area/.gitignore
@@ -0,0 +1,2 @@
+build/
+out/
diff --git a/examples/circle-area/scenes.js b/examples/circle-area/scenes.js
new file mode 100644
index 0000000..f3a5f66
--- /dev/null
+++ b/examples/circle-area/scenes.js
@@ -0,0 +1,228 @@
+// Geometry is in canvas pixels; every sector remains a circular sector.
+// For n even: half-angle d=pi/n, projected half-chord a=R sin(d),
+// distance between the alternating tips h=R cos(d).
+// The n/2 arcs on EACH long edge have total length pi R.
+const TAU = Math.PI * 2;
+const R = 255;
+const CX = 960;
+const CY = 550;
+
+function heading(s, text, at = -1) {
+ s.text(text, { x: 960, y: 155, size: 88, font: 'display', at, enter: at < 0 ? 'none' : 'write', sfx: false });
+}
+function label(s, text, x, y, at, extra = {}) {
+ s.text(text, { x, y, size: 48, at, sfx: false, ...extra });
+}
+function stroke(ctx, pts, color, width = 4) {
+ ctx.strokeStyle = color;
+ ctx.lineWidth = width;
+ ctx.lineCap = 'round';
+ ctx.lineJoin = 'round';
+ ctx.beginPath();
+ pts.forEach(([x, y], i) => i ? ctx.lineTo(x, y) : ctx.moveTo(x, y));
+ ctx.stroke();
+}
+function sector(ctx, radius, delta, color, ink, alpha = 1, inner = 1) {
+ ctx.save();
+ ctx.globalAlpha *= alpha;
+ ctx.beginPath();
+ ctx.moveTo(0, 0);
+ ctx.arc(0, 0, radius, -Math.PI / 2 - delta, -Math.PI / 2 + delta);
+ ctx.closePath();
+ ctx.fillStyle = color;
+ ctx.globalAlpha *= 0.12;
+ ctx.fill();
+ ctx.globalAlpha /= 0.12;
+ const a = radius * Math.sin(delta), h = radius * Math.cos(delta);
+ ctx.save();
+ ctx.globalAlpha *= inner;
+ stroke(ctx, [[-a, -h], [0, 0], [a, -h]], ink, 2.4);
+ ctx.restore();
+ ctx.beginPath();
+ ctx.arc(0, 0, radius, -Math.PI / 2 - delta, -Math.PI / 2 + delta);
+ ctx.strokeStyle = color;
+ ctx.lineWidth = 5;
+ ctx.stroke();
+ ctx.restore();
+}
+function row(ctx, s, n, radius = R, x = CX, y = CY, alpha = 1) {
+ const d = Math.PI / n, a = radius * Math.sin(d), h = radius * Math.cos(d);
+ for (let j = 0; j < n; j++) {
+ ctx.save();
+ ctx.translate(x + (j - (n - 1) / 2) * a, y + (j % 2 ? -h / 2 : h / 2));
+ ctx.rotate(j % 2 ? Math.PI : 0);
+ sector(ctx, radius, d, s.color(j % 2 ? 'blue' : 'yellow'), s.color('ink'), alpha, n >= 64 ? 0.2 : n >= 32 ? 0.35 : 0.65);
+ ctx.restore();
+ }
+}
+function circle(s, { x = 560, y = 550, r = 235, at = -1, out } = {}) {
+ // Exact circular geometry makes the radius endpoint land on the boundary.
+ // The chalk look's rough s.circle outline can wander outside its nominal r.
+ s.draw({ at, out, enter: at < 0 ? 'none' : 'fade' }, (ctx) => {
+ ctx.beginPath();
+ ctx.arc(x, y, r, 0, TAU);
+ ctx.save();
+ ctx.globalAlpha *= 0.12;
+ ctx.fillStyle = s.color('yellow'); ctx.fill();
+ ctx.restore();
+ ctx.strokeStyle = s.color('ink'); ctx.lineWidth = 5; ctx.stroke();
+ });
+}
+function cutCircle(s, { at = -1, coloredAt = -1, cutAt = -1 } = {}) {
+ s.draw({ at, enter: 'none' }, (ctx) => {
+ const colorP = coloredAt < 0 ? 1 : s.p(coloredAt, 1.4);
+ const cutP = cutAt < 0 ? 1 : s.p(cutAt, 2.6, 'linear');
+ for (let i = 0; i < 8; i++) {
+ ctx.save();
+ ctx.translate(CX, CY);
+ ctx.rotate((i + 0.5) * TAU / 8);
+ const c = s.color(i < 4 ? 'yellow' : 'blue');
+ sector(ctx, R, Math.PI / 8, colorP > 0 ? c : s.color('ink'), s.color('ink'), 1, Math.min(1, Math.max(0, cutP * 8 - i)));
+ ctx.restore();
+ }
+ });
+}
+function rectangle(s, at = -1, { x = CX, y = CY, r = R, opacity = 1 } = {}) {
+ const w = Math.PI * r;
+ s.draw({ at, enter: at < 0 ? 'none' : 'fade', dur: 1.1, opacity }, (ctx) => {
+ ctx.save();
+ ctx.globalAlpha *= 0.1;
+ ctx.fillStyle = s.color('yellow');
+ ctx.fillRect(x - w / 2, y - r / 2, w, r);
+ ctx.restore();
+ stroke(ctx, [[x - w / 2, y - r / 2], [x + w / 2, y - r / 2]], s.color('yellow'), 6);
+ stroke(ctx, [[x - w / 2, y + r / 2], [x + w / 2, y + r / 2]], s.color('blue'), 6);
+ stroke(ctx, [[x - w / 2, y - r / 2], [x - w / 2, y + r / 2]], s.color('ink'), 4);
+ stroke(ctx, [[x + w / 2, y - r / 2], [x + w / 2, y + r / 2]], s.color('ink'), 4);
+ });
+}
+function horizontalMeasure(s, x1, x2, y, at, color = 'yellow') {
+ s.line([[x1, y - 12], [x1, y + 12], [x1, y], [x2, y], [x2, y - 12], [x2, y + 12]], { color, at, width: 3, sfx: false });
+}
+function verticalMeasure(s, x, y1, y2, at) {
+ s.line([[x - 12, y1], [x + 12, y1], [x, y1], [x, y2], [x - 12, y2], [x + 12, y2]], { color: 'ink', at, width: 3, sfx: false });
+}
+
+export default {
+ intro(s) {
+ heading(s, 'Why this circle formula?');
+ circle(s, { at: -1 });
+ s.math(String.raw`A = \pi r^2`, { x: 1280, y: 520, size: 118, at: '#question', color: 'yellow', sfx: false });
+ s.line([[560, 550], [795, 550]], { at: '#idea', color: 'yellow', sfx: false });
+ s.math('r', { x: 685, y: 495, size: 64, at: '#idea', color: 'yellow', sfx: false });
+ label(s, 'Cut it. Rearrange it.', 1280, 690, '#idea', { size: 56 });
+ },
+ measure(s) {
+ heading(s, 'Start with the radius');
+ circle(s);
+ s.line([[560, 550], [795, 550]], { at: '#radius', color: 'yellow', sfx: false });
+ s.math('r', { x: 685, y: 495, size: 64, at: '#radius', color: 'yellow', sfx: false });
+ label(s, 'Center to edge', 1280, 390, '#radius', { size: 56 });
+ s.draw({ at: '#around' }, (ctx) => {
+ ctx.beginPath();
+ ctx.arc(560, 550, 247, -Math.PI / 2, -Math.PI / 2 + TAU * s.p('#around', 2.7, 'linear'));
+ ctx.strokeStyle = s.color('blue'); ctx.lineWidth = 6; ctx.stroke();
+ });
+ label(s, 'Around the circle', 1280, 580, '#around');
+ s.math(String.raw`C = 2\pi r`, { x: 1280, y: 700, size: 86, color: 'blue', at: '#around', sfx: false });
+ },
+ slices(s) {
+ heading(s, 'Cut into equal slices', '#cut');
+ cutCircle(s, { at: '#cut', cutAt: '#cut', coloredAt: '#halves' });
+ label(s, '8 equal slices', CX, 865, '#cut');
+ // A trace of each semicircle links the two colors to the circumference.
+ s.draw({ at: '#halves' }, (ctx) => {
+ for (let i = 0; i < 2; i++) {
+ ctx.beginPath();
+ ctx.arc(CX, CY, R + 12, -Math.PI / 2 + i * Math.PI, -Math.PI / 2 + i * Math.PI + Math.PI * s.p('#halves', 1.7, 'linear'));
+ ctx.strokeStyle = s.color(i ? 'blue' : 'yellow'); ctx.lineWidth = 4; ctx.stroke();
+ }
+ });
+ },
+ arrange(s) {
+ heading(s, 'Alternate the directions');
+ s.draw({ at: -1 }, (ctx) => {
+ const n = 8, d = Math.PI / n, a = R * Math.sin(d), h = R * Math.cos(d);
+ // Draw unmoved sectors first, then traveling sectors, to keep motion legible.
+ const pieces = Array.from({ length: n }, (_, i) => {
+ const j = i < 4 ? i * 2 : (i - 4) * 2 + 1;
+ return { i, j, p: s.p(s.time('#move') + j * 0.24, 1.65) };
+ }).sort((a, b) => a.p - b.p);
+ for (const { i, j, p } of pieces) {
+ const targetX = (j - (n - 1) / 2) * a;
+ const targetY = j % 2 ? -h / 2 : h / 2;
+ const startAngle = (i + 0.5) * TAU / n;
+ const endAngle = j % 2 ? Math.PI : 0;
+ const turn = ((endAngle - startAngle + 3 * Math.PI) % TAU) - Math.PI;
+ ctx.save();
+ ctx.translate(CX + targetX * p, CY + targetY * p + Math.sin(p * Math.PI) * (j % 2 ? 115 : -115));
+ ctx.rotate(startAngle + turn * p);
+ sector(ctx, R, d, s.color(i < 4 ? 'yellow' : 'blue'), s.color('ink'));
+ ctx.restore();
+ }
+ });
+ label(s, 'Same pieces, same area', CX, 865, '#same', { size: 56 });
+ s.sfx('whoosh', '#move', { gain: 0.17, dur: 0.6 });
+ },
+ refine(s) {
+ heading(s, 'Thinner slices, flatter edges');
+ const stages = [
+ { n: 8, at: -1, out: '#more' },
+ { n: 16, at: '#more', out: 'flatter' },
+ { n: 32, at: 'flatter', out: '#limit' },
+ { n: 64, at: '#limit', out: 'rectangle' },
+ ];
+ for (const st of stages) {
+ s.draw({ at: st.at, out: st.out, enter: st.at < 0 ? 'none' : 'fade', dur: 0.6 }, (ctx) => row(ctx, s, st.n));
+ }
+ label(s, '8 slices', CX, 865, -1, { out: '#more', exit: 'none' });
+ label(s, '16 slices', CX, 865, '#more', { out: 'flatter', exit: 'none' });
+ label(s, '32 slices', CX, 865, 'flatter', { out: '#limit', exit: 'none' });
+ label(s, '64 slices', CX, 865, '#limit', { out: 'rectangle', exit: 'none' });
+ rectangle(s, 'rectangle');
+ label(s, 'The limiting rectangle', CX, 865, 'rectangle', { size: 56 });
+ },
+ edges(s) {
+ heading(s, 'Half the circumference on each side');
+ s.draw({ at: -1 }, (ctx) => row(ctx, s, 64));
+ horizontalMeasure(s, 558, 1362, 355, '#top');
+ s.math(String.raw`\pi r`, { x: CX, y: 300, size: 68, color: 'yellow', at: '#top', sfx: false });
+ horizontalMeasure(s, 558, 1362, 748, 'bottom', 'blue');
+ s.math(String.raw`\pi r`, { x: CX, y: 800, size: 68, color: 'blue', at: 'bottom', sfx: false });
+ s.math(String.raw`\frac{1}{2}(2\pi r) = \pi r`, { x: CX, y: 915, size: 76, at: '#width', color: 'yellow', sfx: false });
+ },
+ height(s) {
+ heading(s, 'The height approaches the radius');
+ s.draw({ at: -1, out: '#height' }, (ctx) => row(ctx, s, 64));
+ const d = Math.PI / 64, a = R * Math.sin(d), h = R * Math.cos(d);
+ // This is an actual sector radius, not a finite-slice vertical height.
+ s.line([[CX + a / 2, CY + h / 2], [CX + a * 1.5, CY - h / 2]], { at: '#radius', out: '#height', color: 'yellow', width: 7, sfx: false });
+ s.math('r', { x: 1050, y: CY, size: 70, color: 'yellow', at: '#radius', out: '#height', sfx: false });
+ rectangle(s, '#height');
+ verticalMeasure(s, 1485, CY - R / 2, CY + R / 2, '#height');
+ s.math('r', { x: 1560, y: CY, size: 76, at: '#height', sfx: false });
+ label(s, 'In the limit', CX, 865, '#height', { size: 56 });
+ },
+ example(s) {
+ heading(s, 'Try a radius of two', '#two');
+ rectangle(s, '#two');
+ horizontalMeasure(s, 558, 1362, 355, '#two');
+ s.math(String.raw`2\pi`, { x: CX, y: 295, size: 76, color: 'yellow', at: '#two', sfx: false });
+ verticalMeasure(s, 1485, CY - R / 2, CY + R / 2, '#multiply');
+ s.math('2', { x: 1560, y: CY, size: 76, at: '#multiply', sfx: false });
+ s.math(String.raw`2\pi \times 2 = 4\pi`, { x: CX, y: 850, size: 88, color: 'yellow', at: '#multiply', sfx: false });
+ label(s, 'square units', CX, 950, 'square');
+ },
+ conclusion(s) {
+ heading(s, 'The area of a circle');
+ rectangle(s, -1, { y: 490, r: 220 });
+ horizontalMeasure(s, 614, 1306, 325, '#product');
+ s.math(String.raw`\pi r`, { x: CX, y: 270, size: 72, color: 'yellow', at: '#product', sfx: false });
+ verticalMeasure(s, 1420, 380, 600, '#product');
+ s.math('r', { x: 1500, y: 490, size: 78, at: '#product', sfx: false });
+ s.math(String.raw`A = \pi r \times r`, { x: CX, y: 785, size: 100, at: '#product', out: '#answer', exit: 'none', sfx: false });
+ s.math(String.raw`A = \pi r^2`, { id: 'answer', x: CX, y: 785, size: 128, at: '#answer', color: 'yellow', sfx: false });
+ s.annotate('answer', { type: 'box', padding: 26, color: 'yellow', at: s.time('#answer') + 0.9, dur: 1, sfx: false });
+ s.sfx('chime', '#answer', { gain: 0.15 });
+ },
+};
diff --git a/examples/circle-area/script.md b/examples/circle-area/script.md
new file mode 100644
index 0000000..d1fafdd
--- /dev/null
+++ b/examples/circle-area/script.md
@@ -0,0 +1,37 @@
+# Why a circle has area pi r squared
+
+## intro {chapter="Cut and rearrange"}
+[#question] Why does a circle's area equal {πr²|pi times r squared}?
+[#idea] Cutting it into slices helps us see where the formula comes from.
+
+## measure {transition=fade}
+[#radius] The radius, called {r|R}, measures from the center to the edge.
+[#around] The circumference is the distance around, equal to {2πr|two times pi times R}.
+
+## slices {transition=fade}
+[#cut] Cut the circle into equal slices, each meeting at the center.
+[#halves] Color half the slices yellow, and the other half blue.
+
+## arrange {transition=cut}
+[#move] Lay the slices side by side, alternating their directions.
+[#same] Moving these pieces keeps their total area the same.
+
+## refine {chapter="Approach a rectangle" transition=fade}
+[#more] With more, thinner slices, the curved edges become flatter.
+[#limit] As the slices get arbitrarily thin, the shape approaches a rectangle.
+
+## edges {transition=fade}
+[#top] Half the circle's circumference runs along the top, and half along the bottom.
+[#width] Each long side approaches {πr|pi times R}, half of {2πr|two times pi times R}.
+
+## height {transition=fade}
+[#radius] Each slice has straight sides of length {r|R}, the circle's radius.
+[#height] As the slices narrow, the rectangle's height approaches {r|R}.
+
+## example {chapter="Multiply the two sides"}
+[#two] For a radius of two, the rectangle's width is {2π|two times pi}.
+[#multiply] Its height is two, giving an area of {4π|four times pi} square units.
+
+## conclusion {hold=1.8}
+[#product] A rectangle's area is its width times its height.
+[#answer] So the circle's area is {πr²|pi times r squared}.
diff --git a/examples/circle-area/video.json b/examples/circle-area/video.json
new file mode 100644
index 0000000..db7118a
--- /dev/null
+++ b/examples/circle-area/video.json
@@ -0,0 +1,14 @@
+{
+ "title": "Why a circle has area pi r squared",
+ "theme": "chalk",
+ "size": "youtube",
+ "fps": 30,
+ "voice": "af_heart",
+ "speed": 0.96,
+ "music": { "style": "calm", "volume": 0.12 },
+ "sfx": "minimal",
+ "captions": false,
+ "cover": "intro@end",
+ "transition": "fade",
+ "end": 1.4
+}
diff --git a/examples/why-is-the-sky-blue-es/.gitignore b/examples/why-is-the-sky-blue-es/.gitignore
new file mode 100644
index 0000000..3c0160d
--- /dev/null
+++ b/examples/why-is-the-sky-blue-es/.gitignore
@@ -0,0 +1,2 @@
+build/
+out/
diff --git a/examples/why-is-the-sky-blue-es/scenes.js b/examples/why-is-the-sky-blue-es/scenes.js
new file mode 100644
index 0000000..b72f33b
--- /dev/null
+++ b/examples/why-is-the-sky-blue-es/scenes.js
@@ -0,0 +1,160 @@
+// The same colors carry the same meaning throughout: blue scattering,
+// gold sunlight, warm red/orange light after the longer sunset path.
+const C = { blue: '#3c6fa8', red: '#a14332', orange: '#c46728', gold: '#d69b27', air: '#e4edf3', soft: '#645e54' };
+const quiet = { sfx: false };
+
+function heading(s, n, category, title, at, first = false) {
+ s.text(`${n} / ${category}`, { x: 180, y: 115, align: 'left', size: 36, color: C.soft, at: first ? -1 : at, enter: first ? 'none' : 'fade', ...quiet });
+ s.text(title, { x: 180, y: 220, align: 'left', size: 88, font: 'display', at: first ? -1 : at, enter: first ? 'none' : 'write', ...quiet });
+ s.line([[180, 286], [1740, 286]], { at: first ? -1 : at, color: C.blue, opacity: 0.3, width: 2, ...quiet });
+}
+function label(s, text, x, y, at, o = {}) {
+ return s.text(text, { x, y, size: 48, at, ...quiet, ...o });
+}
+function sun(s, x, y, at, size = 140, o = {}) {
+ s.circle({ x, y, r: size * 0.30, fill: '#f4d17a', color: C.gold, at, ...quiet, ...o });
+ s.icon('sun', { x, y, size, color: C.gold, at, ...quiet, ...o });
+}
+function molecule(s, x, y, at, o = {}) {
+ s.line([[x - 10, y], [x + 10, y]], { at, color: C.soft, width: 4, ...quiet, ...o });
+ s.circle({ x: x - 12, y, r: 13, at, color: C.soft, fill: '#f7f3ea', width: 2.5, ...quiet, ...o });
+ s.circle({ x: x + 12, y, r: 13, at, color: C.soft, fill: '#f7f3ea', width: 2.5, ...quiet, ...o });
+}
+function ray(s, from, to, at, color = C.blue, o = {}) {
+ s.arrow(from, to, { at, color, width: 7, headSize: 21, gap: 8, ...quiet, ...o });
+}
+function horizon(s, x, y, w, at, color = '#7a8d70') {
+ s.path(`M ${x} ${y} Q ${x+w/2} ${y-95} ${x+w} ${y}`, { at, color, width: 5, ...quiet });
+}
+function wave(s, x, y, w, wavelength, color, at) {
+ let d = `M ${x} ${y}`;
+ for (let i = 1; i <= 200; i++) {
+ const dx = w*i/200;
+ d += ` L ${x+dx} ${y-40*Math.sin(dx*2*Math.PI/wavelength)}`;
+ }
+ s.path(d, { at, color, width: 6, single: true, ...quiet });
+}
+// A pulse follows a ray, keeping a diagram alive between spoken cues.
+// This uses local scene time, so rendering remains deterministic.
+function pulse(s, from, to, at, color, offset = 0) {
+ s.draw({ at, ...quiet }, (ctx, life) => {
+ const p = ((life.local + offset) % 2.8) / 2.8;
+ ctx.globalAlpha *= Math.sin(Math.PI*p) * 0.8;
+ ctx.fillStyle = color;
+ ctx.beginPath();
+ ctx.arc(from[0]+(to[0]-from[0])*p, from[1]+(to[1]-from[1])*p, 7, 0, 2*Math.PI);
+ ctx.fill();
+ });
+}
+
+export default {
+ pregunta(s) {
+ heading(s, '01', 'UNA PREGUNTA COTIDIANA', '¿Por qué el cielo es azul?', '#pregunta', true);
+ s.path('M 520 750 C 490 240 1430 240 1400 750 Z', { at: '#pregunta', color: C.blue, fill: C.air, width: 3, ...quiet });
+ horizon(s, 460, 775, 1000, '#pregunta');
+ sun(s, 760, 470, 'día', 150);
+ label(s, 'Luz del Sol', 460, 530, '#respuesta');
+ ray(s, [585, 550], [715, 493], '#respuesta', C.gold);
+ label(s, 'Aire', 1420, 530, 'aire', { color: C.blue });
+ ray(s, [1325, 540], [1180, 540], 'aire');
+ s.annotate({ x: 1060, y: 500, w: 180, h: 120 }, { type: 'circle', at: 'aire', color: C.blue, ...quiet });
+ },
+
+ colores(s) {
+ heading(s, '02', 'LA LUZ DEL SOL', 'Una mezcla de colores', '#sol');
+ sun(s, 350, 575, '#sol', 185);
+ label(s, 'Sol', 350, 780, '#sol');
+ const colors = ['#b55743', '#d98835', '#ddb544', '#6d985c', '#3c6fa8', '#6563a6', '#895b9f'];
+ colors.forEach((color, i) => {
+ const y = 440+i*44;
+ s.path(`M 475 575 Q 770 ${y} 1100 ${y} Q 1300 ${y} 1450 575`, { at: 'colores', color, width: 10, ...quiet });
+ });
+ label(s, 'Colores visibles', 910, 355, 'colores');
+ s.circle({ x: 1500, y: 575, r: 83, color: '#9c9486', fill: '#fffdf8', width: 3, at: '#juntos', ...quiet });
+ label(s, 'Luz blanca', 1500, 780, 'blanca');
+ s.annotate({ x: 1498, y: 575, w: 192, h: 192 }, { type: 'circle', at: 'mezcla', color: C.gold, ...quiet });
+ pulse(s, [1170, 575], [1420, 575], '#juntos', C.gold);
+ },
+
+ moleculas(s) {
+ heading(s, '03', 'EL PAPEL DEL AIRE', 'La luz cambia de dirección', '#aire');
+ s.circle({ x: 960, y: 575, r: 185, color: C.blue, fill: C.air, width: 3, at: '#aire', ...quiet });
+ [[850,490],[1060,480],[960,575],[850,660],[1070,660]].forEach(([x,y],i) => molecule(s,x,y,i===2 ? 'moléculas' : 'partículas'));
+ label(s, 'Moléculas del aire', 960, 360, 'moléculas');
+ ray(s, [360,575], [920,575], 'luz', C.gold);
+ label(s, 'Luz solar', 485, 670, 'luz');
+ ray(s, [992,555], [1400,410], '#desvio');
+ ray(s, [995,595], [1370,730], 'direcciones');
+ pulse(s, [992,555], [1400,410], '#desvio', C.blue);
+ pulse(s, [995,595], [1370,730], 'direcciones', C.blue, 1.2);
+ label(s, 'Dispersión', 960, 788, '#nombre', { size: 58, color: C.blue, font: 'display' });
+ },
+
+ ondas(s) {
+ heading(s, '04', 'EL PAPEL DEL AIRE', 'El azul se dispersa más', '#ondas');
+ label(s, 'Azul', 275, 455, '#ondas', { color: C.blue, size: 56 });
+ label(s, 'Rojo', 275, 685, '#ondas', { color: C.red, size: 56 });
+ wave(s, 440,455,920,120,C.blue,'#ondas');
+ wave(s, 440,685,920,300,C.red,'#ondas');
+ s.arrow([470,359], [590,359], { at: 'distancia', head: 'both', color: C.blue, width: 3, headSize: 14, gap: 0, ...quiet });
+ s.line([[470,367],[470,405]], { at: 'crestas', color: C.blue, dashed: true, width: 2, ...quiet });
+ s.line([[590,367],[590,405]], { at: 'crestas', color: C.blue, dashed: true, width: 2, ...quiet });
+ label(s, 'Onda corta', 965, 355, '#azul', { color: C.blue });
+ label(s, 'Más\ndispersión', 1550, 455, 'dispersan', { color: C.blue, size: 44 });
+ label(s, 'Onda larga', 965, 790, '#rojo', { color: C.red });
+ label(s, 'Menos\ndispersión', 1550, 685, '#rojo', { color: C.red, size: 44 });
+ s.annotate({ x: 830, y: 455, w: 300, h: 110 }, { at: 'cortas', type: 'highlight', color: C.blue, ...quiet });
+ },
+
+ ojos(s) {
+ heading(s, '05', 'EL AZUL QUE VEMOS', 'Desde todo el cielo', '#cielo');
+ s.path('M 430 680 C 380 255 1540 255 1490 680', { at: '#cielo', color: C.blue, width: 4, ...quiet });
+ sun(s, 390, 435, '#cielo', 120);
+ s.icon('eye', { x: 960, y: 690, size: 145, at: 'ojos', color: 'ink', ...quiet });
+ label(s, 'Nuestros ojos', 960, 795, 'ojos');
+ const rays = [[[590,475],[895,665]], [[960,375],[960,627]], [[1330,475],[1025,665]]];
+ rays.forEach(([from,to],i) => {
+ const at = i===0 ? 'azul' : i===1 ? 'ojos' : 'direcciones';
+ s.circle({ x: from[0], y: from[1], r: 19, color: C.blue, fill: C.air, at, ...quiet });
+ ray(s,from,to,at);
+ pulse(s,from,to,at,C.blue,i*.7);
+ });
+ s.annotate({ x: 1330, y: 475, w: 110, h: 110 }, { at: '#mirada', type: 'circle', color: C.blue, ...quiet });
+ label(s, 'Lejos del Sol', 1470, 785, 'lejos', { size: 46, color: C.blue });
+ },
+
+ ocaso(s) {
+ heading(s, '06', 'AL ATARDECER', 'Un recorrido más largo', '#bajo');
+ s.path('M 450 770 C 510 295 1370 295 1480 770 Z', { at: '#bajo', color: C.blue, fill: C.air, width: 2.5, ...quiet });
+ horizon(s, 200, 790, 1510, '#bajo');
+ sun(s, 280, 650, 'bajo', 130);
+ [[630,600],[780,700],[930,590],[1080,705],[1230,600],[1370,700]].forEach(([x,y]) => molecule(s,x,y,'aire'));
+ s.icon('eye', { x: 1570, y: 650, size: 125, at: 'luz', color: 'ink', ...quiet });
+ ray(s,[365,650],[1495,650],'luz',C.gold);
+ label(s, 'Más aire', 960, 370, 'aire', { size: 52, color: C.blue });
+ ray(s,[715,638],[790,465],'#fuera');
+ ray(s,[970,638],[1090,465],'azul');
+ pulse(s,[715,638],[790,465],'#fuera',C.blue);
+ pulse(s,[970,638],[1090,465],'azul',C.blue,1);
+ label(s, 'Azul dispersado', 580, 405, 'dispersa', { size: 42, color: C.blue });
+ ray(s,[1130,650],[1495,650],'#calidos',C.orange,{width:11});
+ label(s, 'Rojos y naranjas', 1330, 798, 'rojos', { size: 46, color: C.red });
+ },
+
+ cierre(s) {
+ heading(s, '07', 'LA IDEA PRINCIPAL', 'El aire cambia lo que vemos', '#dia');
+ label(s, 'De día', 540, 360, '#dia', { size: 60, font: 'display', color: C.blue });
+ s.path('M 285 695 C 285 330 795 330 795 695', { at: '#dia', color: C.blue, fill: C.air, width: 3, ...quiet });
+ s.icon('eye', { x: 540, y: 700, size: 105, at: 'vemos', ...quiet });
+ [[390,540],[540,470],[690,540]].forEach((p,i)=>ray(s,p,[540+(i-1)*36,647], 'dispersado'));
+ label(s, 'Azul dispersado', 540, 795, 'aire', { color: C.blue });
+ label(s, 'Al atardecer', 1380, 360, '#tarde', { size: 60, font: 'display', color: C.red });
+ horizon(s, 1110, 715, 580, '#tarde');
+ sun(s, 1160, 620, '#tarde', 110);
+ s.icon('eye', { x: 1630, y: 620, size: 105, at: '#tarde', ...quiet });
+ ray(s,[1220,620],[1565,620], 'recorrido', C.orange, {width:9});
+ ray(s,[1350,605],[1395,470], 'largo');
+ label(s, 'Tonos cálidos', 1380, 795, 'tonos', { color: C.red });
+ s.line([[960,365],[960,830]], { at: '#tarde', color: C.blue, opacity:0.2, width:2, ...quiet });
+ },
+};
diff --git a/examples/why-is-the-sky-blue-es/script.md b/examples/why-is-the-sky-blue-es/script.md
new file mode 100644
index 0000000..5b9d52d
--- /dev/null
+++ b/examples/why-is-the-sky-blue-es/script.md
@@ -0,0 +1,22 @@
+# ¿Por qué el cielo es azul?
+
+## pregunta {chapter="La luz del Sol"}
+[#pregunta] ¿Por qué vemos el cielo azul durante el día? [#respuesta] La respuesta está en la luz del Sol y en el aire.
+
+## colores
+[#sol] La luz del Sol contiene todos los colores que podemos ver. [#juntos] Cuando llegan juntos a nuestros ojos, esa mezcla nos parece blanca.
+
+## moleculas {chapter="El papel del aire"}
+[#aire] El aire está formado por moléculas, partículas diminutas que interactúan con la luz. [#desvio] Al hacerlo, desvían parte de esa luz hacia otras direcciones. [#nombre] Eso se llama dispersión.
+
+## ondas
+[#ondas] Cada color tiene una longitud de onda, la distancia entre dos crestas de la luz. [#azul] Las moléculas dispersan mucho más las ondas cortas, como el azul, [#rojo] que las largas, como el rojo.
+
+## ojos
+[#cielo] Esa luz azul dispersada llega a nuestros ojos desde todas las direcciones del cielo. [#mirada] Por eso vemos azul incluso cuando miramos lejos del Sol.
+
+## ocaso {chapter="El cielo al atardecer"}
+[#bajo] Al atardecer, el Sol está bajo y su luz atraviesa más aire. [#fuera] En ese recorrido, más azul se dispersa fuera del camino. [#calidos] La luz que llega conserva más rojos y naranjas.
+
+## cierre {hold=1.5}
+[#dia] De día vemos el azul dispersado por el aire. [#tarde] Al atardecer, el recorrido más largo favorece los tonos cálidos.
diff --git a/examples/why-is-the-sky-blue-es/video.json b/examples/why-is-the-sky-blue-es/video.json
new file mode 100644
index 0000000..bafd1bf
--- /dev/null
+++ b/examples/why-is-the-sky-blue-es/video.json
@@ -0,0 +1,15 @@
+{
+ "title": "¿Por qué el cielo es azul?",
+ "theme": "paper",
+ "size": "youtube",
+ "voice": "ef_dora",
+ "music": {
+ "style": "warm",
+ "volume": 0.1
+ },
+ "captions": true,
+ "language": "es",
+ "sfx": "minimal",
+ "transition": "fade",
+ "cover": "pregunta@end"
+}