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.

s.ui: brand.colors, textarea, stream, overlay layers; still names keep the time as written; product demo tips from three agent runs

Vincent Schmalbach617181381cb8
diff --git a/AGENTS.md b/AGENTS.md
index 92b4ee5..999b7ef 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -320,8 +320,21 @@ hook(s) {
```
Draw the headline after `s.camera()`, or the zoomed screens slide under it.
+When the camera zooms in, either keep the headline fully in view (zoom up to
+about 1.1) or zoom far enough that it leaves the frame (about 1.3 and more).
+In between it gets cut in half.
+
Time every click to a `[#mark]` in the script, so it happens when the voice
-says it. Move the cursor about 0.7 seconds before the click.
+says it. A cursor move starts at its `at` and arrives `dur` seconds later
+(0.7 by default), so start the move a little more than `dur` before the
+click. The first 0.7 seconds of a scene are covered by the transition from
+the scene before, so put no clicks there.
+
+The watermark sits in the bottom right corner. When the camera zooms in, it
+can cover what is there, so keep important text out of that corner.
+
+Use the product's name as plain text in the first frame. The first frame is
+also the video's cover.
**`s.ui` reference.** Positions are in the frame (1920 wide for 16:9). Times
take seconds, spoken words or `"#marks"`, like everywhere else.
@@ -332,12 +345,12 @@ take seconds, spoken words or `"#marks"`, like everywhere else.
| `u.panel(x, y, w, h, { at, out, from, rise, sfx, fill, border, lift }, fn)` | a card that pops in at `at`; `fn(x, y, w, h)` draws inside it |
| `u.card(x, y, w, h, o)` | a card without an entrance |
| `u.browser(x, y, w, h, { url, at }, fn)` | a panel with a browser bar; `fn` gets the page area |
-| `u.modal(x, y, w, h, { at, out }, fn)` | a dialog over a dimmed frame |
+| `u.modal(x, y, w, h, { at, out }, fn)`, `u.over(fn)` | a dialog over a dimmed frame, and a layer for your own menus or popups; `check` does not report text in one layer as overlapping text in another |
| `u.toast(text, { at, out, icon, tone })` | a message that slides up, with a chime |
-| `u.headline(text, x, y, { size, at, out, align, weight, italic })` | big text that blurs in word by word; `*stars*` mark words in the accent color |
-| `u.text(text, x, y, { size, weight, color, align, font, maxW })`, `u.para(text, x, y, maxW, o)`, `u.eyebrow(text, x, y)` | text, wrapped text, and a small uppercase label |
+| `u.headline(text, x, y, { size, at, out, align, weight, italic, color, accent, tracking })` | big text that blurs in word by word; `*stars*` mark words in the `accent` color |
+| `u.text(text, x, y, { size, weight, color, align, base, font, italic, tracking, alpha, maxW, check })`, `u.para(text, x, y, maxW, o)`, `u.eyebrow(text, x, y)` | text, wrapped text (`\n` starts a new line), and a small uppercase label; `font` is `'ui'`, `'headline'` or a family; `check: false` hides text from `check`; `u.measure(text, size, weight)` gives the width |
| `u.button(label, x, y, w, h, { variant, press, icon, loading, color, caps })` | `primary`, `secondary` or `ghost` |
-| `u.input(x, y, w, h, { label, value, placeholder, focus, caret, icon })` | a text field |
+| `u.input(x, y, w, h, { label, value, placeholder, focus, caret, icon })`, `u.textarea(x, y, w, h, o)` | a text field, and a taller one where the text wraps |
| `u.select(x, y, w, h, { label, value, open, options, hover, selected })` | a dropdown; returns the y of each option row |
| `u.toggle(x, y, on)`, `u.checkbox(x, y, on)`, `u.radio(x, y, on)` | `on` goes from 0 to 1, so it can animate |
| `u.chip(label, x, y, { selected })`, `u.chipWidth(label, o, selected)` | option chips; a selected chip grows by its check mark, so leave room |
@@ -345,9 +358,9 @@ take seconds, spoken words or `"#marks"`, like everywhere else.
| `u.spinner(x, y, r)`, `u.progress(x, y, w, p)`, `u.avatar(x, y, r, initials, { image })`, `u.icon(name, x, y, size, color)`, `u.lines(x, y, w, n)`, `u.logo(x, y, w)` | small parts; `lines` draws grey bars in place of body text |
| `u.pop(at, cx, cy, fn, { sfx })` | pops anything in around a point |
| `u.wipe(at, { color })` | the accent color spreads out until it fills the frame |
-| `u.cursor(keys, { out })` | the mouse; each key `{ at, x, y }` moves it, `{ at, click: true }` clicks with a sound |
-| `u.press(at)`, `u.typed(text, at, cps, { gain, sfx })`, `u.count(to, at, dur)` | a button press (0 to 1 and back), text typed so far with typing sounds, a number counting up |
-| `u.colors` | `accent`, `accentDark`, `accentTint`, `background`, `ink`, `text`, `muted`, `faint`, `line`, `surface` |
+| `u.cursor(keys, { out })` | the mouse; a key `{ at, x, y, dur, arc }` moves it (`arc` bends the path, 0 is straight), `{ at, click: true }` clicks with a sound |
+| `u.press(at)`, `u.typed(text, at, cps, { gain, sfx })`, `u.stream(text, at, wps)`, `u.count(to, at, dur)` | a button press (0 to 1 and back), text typed so far with typing sounds, text appearing word by word like an AI reply, a number counting up |
+| `u.colors` | `accent`, `accentDark`, `accentTint`, `background`, `ink`, `text`, `soft`, `muted`, `faint`, `line`, `field`, `surface`, `panel`; `brand.colors` in `video.json` replaces the grays, for example `{ "text": "#141413", "line": "#e8e6dc" }` for a warm brand |
`check` sees the text of `s.ui` too. It reports text that runs off the frame
(not while the camera zooms in), text that is too small and text that
@@ -355,6 +368,11 @@ overlaps. A dropdown or dialog may cover what is under it. Look at stills at
the moments the camera is zoomed in, and check the cursor does not hide the
word it points at.
+Panels and headlines from `s.ui` make no sound unless you pass `sfx`.
+`check` does not see clipping: text you hide by clipping still counts, so
+do not draw text that should not show. Try a product name with its plain
+spelling first; only respell it when the speech check mishears it.
+
Many sounds under the voice make it hard to follow, and `verify` then
understands less of it. Keep long typing quiet (`u.typed(text, at, cps, {
gain: 0.25 })`) and give each moment one sound, not three.
diff --git a/engine/ui.js b/engine/ui.js
index bf1d6ea..590e980 100644
--- a/engine/ui.js
+++ b/engine/ui.js
@@ -71,8 +71,11 @@ export class UI {
field: '#d0d5dd',
surface: '#ffffff',
panel: '#f5f7fb',
+ // brand.colors overrides any of these, for example warm grays.
+ ...(b.colors || {}),
};
this._layer = 0;
+ this._layers = 0;
}
// Scale of the current transform. Canvas shadows and blur filters work in
@@ -258,7 +261,7 @@ export class UI {
c.fillStyle = '#ffffff';
c.fill();
c.restore();
- if (o.url) this.text(o.url, x + 128, y + bar / 2 + 1, { size: 16, color: this.colors.muted, maxW: w - 170 });
+ if (o.url) this.text(o.url, x + 128, y + bar / 2 + 1, { size: o.urlSize ?? 17, color: this.colors.muted, maxW: w - 170 });
if (fn) fn(x, y + bar, w, h - bar);
});
}
@@ -346,12 +349,15 @@ export class UI {
}
// Draws fn as a layer on top of what is already there (menus, dialogs).
+ // Each call is its own layer, so `check` does not report text in one
+ // layer as overlapping text in another.
over(fn) {
- this._layer++;
+ const prev = this._layer;
+ this._layer = ++this._layers;
try {
return fn();
} finally {
- this._layer--;
+ this._layer = prev;
}
}
@@ -402,16 +408,7 @@ export class UI {
para(str, x, y, maxW, o = {}) {
const size = o.size ?? 22;
const lh = o.lh ?? size * 1.45;
- const lines = [];
- let cur = '';
- for (const w of String(str).split(/\s+/)) {
- const next = cur ? cur + ' ' + w : w;
- if (cur && this.measure(next, size, o.weight ?? 400, o.font) > maxW) {
- lines.push(cur);
- cur = w;
- } else cur = next;
- }
- if (cur) lines.push(cur);
+ const lines = this._wrap(str, maxW, size, o.weight ?? 400, o.font).filter((l, i, a) => l || i < a.length - 1);
lines.forEach((l, i) => this.text(l, x, y + i * lh, { ...o, base: 'top' }));
return lines.length * lh;
}
@@ -610,6 +607,60 @@ export class UI {
c.restore();
}
+ // A multi-line field: the value wraps inside it, with a caret at the end.
+ textarea(x, y, w, h, o = {}) {
+ const size = o.size ?? 21;
+ const lh = o.lh ?? size * 1.45;
+ this.input(x, y, w, h, { label: o.label, focus: o.focus, alpha: o.alpha, size });
+ const pad = 18;
+ const value = o.value ?? '';
+ if (!value && o.placeholder) {
+ this.para(o.placeholder, x + pad, y + pad, w - pad * 2, { size, lh, color: this.colors.faint });
+ return;
+ }
+ const lines = this._wrap(value, w - pad * 2, size, o.weight ?? 400);
+ lines.forEach((l, i) => this.text(l, x + pad, y + pad + i * lh, { size, base: 'top' }));
+ if (o.caret && (o.focus ?? 0) > 0.5 && Math.floor(this.s.t * 2.2) % 2 === 0) {
+ const last = lines[lines.length - 1] ?? '';
+ const c = this.c;
+ c.fillStyle = this.colors.text;
+ c.fillRect(x + pad + this.measure(last, size) + 2, y + pad + (lines.length - 1) * lh + (lh - size * 1.2) / 2, 2, size * 1.2);
+ }
+ }
+
+ _wrap(str, maxW, size, weight = 400, font) {
+ const lines = [];
+ for (const para of String(str).split('\n')) {
+ let cur = '';
+ for (const w of para.split(/\s+/).filter(Boolean)) {
+ const next = cur ? cur + ' ' + w : w;
+ if (cur && this.measure(next, size, weight, font) > maxW) {
+ lines.push(cur);
+ cur = w;
+ } else cur = next;
+ }
+ lines.push(cur);
+ }
+ return lines;
+ }
+
+ // The part of `str` shown by now when it appears word by word from `at`,
+ // like an AI reply streaming in (wps: words per second).
+ stream(str, at, wps = 9) {
+ const words = String(str).split(/(\s+)/);
+ const n = Math.floor(Math.max(0, this.s.t - this.at(at)) * wps * this.s.pace);
+ let shown = 0;
+ let out = '';
+ for (const part of words) {
+ if (/\S/.test(part)) {
+ if (shown >= n) break;
+ shown++;
+ }
+ out += part;
+ }
+ return out.trimEnd();
+ }
+
// A dropdown. open 0..1 shows the menu below it, hover is the index of the
// highlighted option, selected gets a check. Returns each option row's
// center y, for pointing the cursor at it.
@@ -799,7 +850,7 @@ export class UI {
c.drawImage(img, (img.naturalWidth - side) / 2, (img.naturalHeight - side) / 2, side, side, x - r, y - r, r * 2, r * 2);
}
c.restore();
- if (initials && !o.image) this.text(initials, x, y + 1, { size: r * 0.8, weight: 600, color: o.color ?? this.colors.accent, align: 'center' });
+ if (initials && !o.image) this.text(initials, x, y + 1, { size: Math.max(17, r * 0.8), weight: 600, color: o.color ?? this.colors.accent, align: 'center' });
}
icon(name, x, y, size, color = this.colors.text, weight = 2) {
diff --git a/src/project.js b/src/project.js
index ab8a8ce..701b890 100644
--- a/src/project.js
+++ b/src/project.js
@@ -56,7 +56,9 @@ export const DEFAULTS = {
};
// Settings for the UI kit (s.ui), for product demos in a brand's own look.
-export const BRAND_KEYS = ['accent', 'background', 'ink', 'font', 'headline', 'logo'];
+export const BRAND_KEYS = ['accent', 'background', 'ink', 'font', 'headline', 'logo', 'colors'];
+// The UI kit's neutral colors that brand.colors can replace.
+export const BRAND_COLORS = ['text', 'soft', 'muted', 'faint', 'line', 'field', 'surface', 'panel'];
const FONT_FILE = /\.(woff2?|ttf|otf)$/i;
const HEX = /^#[0-9a-f]{6}$/i;
@@ -114,6 +116,14 @@ export function normalizeConfig(raw) {
for (const k of ['font', 'headline']) {
if (cfg.brand[k] !== undefined && !(typeof cfg.brand[k] === 'string' && cfg.brand[k].trim())) fail(`brand.${k} must be a font family name, like "Inter"`);
}
+ if (cfg.brand.colors !== undefined) {
+ const c = cfg.brand.colors;
+ if (!c || typeof c !== 'object' || Array.isArray(c)) fail(`brand.colors must be an object like { "text": "#141413", "line": "#e8e6dc" }`);
+ for (const [k, v] of Object.entries(c)) {
+ if (!BRAND_COLORS.includes(k)) fail(`brand.colors has an unknown color "${k}". Known: ${BRAND_COLORS.join(', ')}`);
+ if (!HEX.test(v)) fail(`brand.colors.${k} must be a color like "#141413", not ${JSON.stringify(v)}`);
+ }
+ }
if (cfg.brand.logo !== undefined && !(typeof cfg.brand.logo === 'string' && /^assets\/.+\.(svg|png|webp|jpe?g)$/i.test(cfg.brand.logo))) {
fail('brand.logo must be an image in the assets/ folder, like "assets/logo.svg"');
}
diff --git a/src/qa.js b/src/qa.js
index 5a10067..9ee5465 100644
--- a/src/qa.js
+++ b/src/qa.js
@@ -44,7 +44,8 @@ export function resolveTimes(timeline, specs) {
if (at === 'start') return { T: sc.start, label: `${id}@start` };
const local = Number(at);
if (!Number.isFinite(local)) throw new Error(`"${spec}": use scene@seconds, for example ${id}@1.5`);
- return { T: sc.start + Math.min(local, sc.dur - 0.01), label: `${id}@${local}` };
+ // Keep the time as written, so "[email protected]" saves as [email protected].
+ return { T: sc.start + Math.min(local, sc.dur - 0.01), label: `${id}@${at}` };
});
}
diff --git a/test/brand.test.js b/test/brand.test.js
index a79affe..6478bd4 100644
--- a/test/brand.test.js
+++ b/test/brand.test.js
@@ -13,6 +13,9 @@ test('brand settings for the UI kit are checked', () => {
assert.throws(() => normalizeConfig({ brand: { accent: 'blue' } }), /brand.accent must be a color/);
assert.throws(() => normalizeConfig({ brand: { logo: '../logo.svg' } }), /assets\/ folder/);
assert.throws(() => normalizeConfig({ brand: [] }), ProjectError);
+ assert.deepEqual(normalizeConfig({ brand: { colors: { text: '#141413', line: '#e8e6dc' } } }).brand.colors, { text: '#141413', line: '#e8e6dc' });
+ assert.throws(() => normalizeConfig({ brand: { colors: { ink2: '#000000' } } }), /unknown color "ink2"/);
+ assert.throws(() => normalizeConfig({ brand: { colors: { text: 'black' } } }), /brand.colors.text must be a color/);
});
test('a video can bring its own fonts', () => {