Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

fix(demo): make re-shooting one chapter actually produce a usable chapter

nirholase01f5ce92963
diff --git a/.gitignore b/.gitignore
index 30246c991..dc8b57d1b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -523,8 +523,9 @@ marketing/*/.raw/
# The product demo film (scripts/make-product-demo.mjs, `npm run demo:video`).
# Every chapter is a 1080p screen recording of the live site and the set runs to
# hundreds of megabytes, which is not something a git history should carry
-# forever. demo-manifest.json IS committed, so the repo still records what was
-# filmed, when, from which origin, and which stops were skipped.
+# forever. three-ws-demo-manifest.json IS committed, so the repo still records
+# what was filmed, when, from which origin, and which stops were skipped. The
+# .smoke/ tree is where a --out=...smoke test run lands; .raw/ is covered above.
marketing/product-demo/*.mp4
marketing/product-demo/.smoke/
@@ -592,12 +593,6 @@ public/announce/img/activity-*
# `npm run announce:rank -- --write --probe`; delete this rule once approved.
data/announcements.json
-# Product-demo capture scratch. `scripts/make-product-demo.mjs --smoke` writes
-# ~70 MB of intermediate wavs, per-track silence padding and rendered mp4s here
-# on every run. The finished demo is published, not committed, so this tree is
-# pure regenerable output; ignoring it keeps a concurrent `git add -A` sweep
-# from putting the binaries in the history.
-marketing/product-demo/.smoke/
# The unanchored `demo/` rule above (NVIDIA TRELLIS local outputs) matches at any
# depth, so it also swallowed 578 files of runnable demos inside the vendored MIT
diff --git a/docs/product-demo.md b/docs/product-demo.md
index 0f6d791fd..6427da41c 100644
--- a/docs/product-demo.md
+++ b/docs/product-demo.md
@@ -38,7 +38,7 @@ curriculum the in-product [Feature Tour](../tour-sdk/README.md) walks, which
follow from that:
- **A page that ships tomorrow is in the film.** Add it to `data/pages.json`, run
- `npm run build:tour`, and the next recording visits it. Nothing here needs editing.
+ `node scripts/build-tour.mjs`, and the next recording visits it. Nothing here needs editing.
- **The narration is the page's own description.** The words spoken over each stop are the same
plain-language sentences that feed the sitemap, `llms.txt`, and the changelog, so the film cannot
drift into claiming something the platform does not do.
@@ -86,8 +86,9 @@ for the click ring.
**The voice is the platform's own.** Narration is synthesized through the site's own TTS lane, so
three.ws narrates three.ws. The default is `/api/tts/edge` (Microsoft Edge Neural voices, proxied
and cached in R2 by the platform), because it allows 20 lines a minute for a signed-in caller and a
-full film has close to three hundred of them. `--narrator=speak` switches to the free NVIDIA Magpie
-lane behind `/api/tts/speak`, which is better suited to a handful of lines: it allows 40 an hour.
+full film has close to three hundred of them. `--narrator=speak` switches to `/api/tts/speak`, which
+is better suited to a handful of lines: it allows 40 an hour, and its free NVIDIA Magpie lane falls
+through to a paid OpenAI backstop when Magpie errors, which on a few hundred lines is real spend.
Both lanes need the QA session, so `--authed` is not optional when there is a voice track.
Every line is synthesized **before** the camera rolls. Filming is real time, so a line fetched
@@ -122,6 +123,7 @@ stays sample accurate end to end.
| `--reuse` | Keep chapter mp4s that already exist, and film the rest |
| `--strict` | A failed stop fails the run |
| `--crf=<n>` | x264 quality, default 22; lower is bigger |
+| `--name=<basename>` | Output basename (default `three-ws-demo`, or `three-ws-demo-<route>`) |
| `--dry-run` | Print the route and exit |
## Before you film
diff --git a/scripts/lib/demo-stage.mjs b/scripts/lib/demo-stage.mjs
index b6d75553a..3a22e5ab0 100644
--- a/scripts/lib/demo-stage.mjs
+++ b/scripts/lib/demo-stage.mjs
@@ -14,8 +14,9 @@
* the same way a screen recorder draws the host cursor over a real session. It
* reports the interaction, it never stands in for one.
*
- * The narration is spoken by the platform's own TTS endpoint (/api/tts/speak),
- * so a demo of three.ws is narrated by three.ws.
+ * The narration is spoken by the platform's own TTS endpoints (/api/tts/edge by
+ * default, /api/tts/speak on request), so a demo of three.ws is narrated by
+ * three.ws.
*/
import { spawnSync } from 'node:child_process';
import { createHash } from 'node:crypto';
@@ -397,12 +398,6 @@ export class Presenter {
}
}
- async toTop({ ms = 900 } = {}) {
- const { y } = await this.scrollState();
- if (y < 8) return;
- await this.readDown(-y, { ms });
- }
-
/** Put an element in the comfortable middle band of the frame. */
async bringIntoView(selector, { top = 140, bottom = 260 } = {}) {
const el = this.locate(selector);
@@ -587,8 +582,13 @@ export class Narrator {
body: JSON.stringify(this.lane.body(text, this.voice)),
});
if (res.status === 429) {
+ /* The handler answers JSON, but a limiter in front of it (CDN, load
+ balancer) answers HTML, and parsing that would throw out of the
+ retry loop and kill a warm-up ten minutes in. */
const body = await res.text();
- const after = Number(res.headers.get('retry-after')) || JSON.parse(body || '{}').retry_after || 60;
+ let hinted = 0;
+ try { hinted = Number(JSON.parse(body || '{}').retry_after) || 0; } catch { hinted = 0; }
+ const after = Number(res.headers.get('retry-after')) || hinted || 60;
this.log(`narrator rate limited, waiting ${after}s`);
await sleep(Math.min(after, 300) * 1000 + 500);
continue;
@@ -718,6 +718,10 @@ export function concatParts(parts, out, work) {
export function mediaInfo(file) {
const r = spawnSync('ffprobe', ['-v', 'error', '-show_entries', 'format=duration,size',
'-of', 'default=noprint_wrappers=1', file], { encoding: 'utf8' });
+ /* This feeds the committed run manifest. A probe that quietly failed would
+ write a film of zero seconds into it, which reads as a bad recording
+ rather than as a broken measurement. */
+ if (r.status !== 0) throw new Error(`ffprobe failed on ${file}: ${r.stderr || r.status}`);
const map = Object.fromEntries(r.stdout.trim().split('\n').map((l) => l.split('=')));
return { seconds: Number(map.duration || 0), bytes: Number(map.size || 0) };
}
diff --git a/scripts/make-product-demo.mjs b/scripts/make-product-demo.mjs
index df09bdf60..1a6535d31 100644
--- a/scripts/make-product-demo.mjs
+++ b/scripts/make-product-demo.mjs
@@ -5,7 +5,8 @@
* The route is not hand-maintained: it is the same curriculum the in-product
* Feature Tour walks (public/tour/curriculum.json, generated from
* data/pages.json by scripts/build-tour.mjs), so a page that ships tomorrow is
- * one `npm run build:tour` away from being in the video, and the narration is
+ * one `node scripts/build-tour.mjs` away from being in the video, and the
+ * narration is
* the page's own plain-language description rather than marketing invented
* here. Chapters are the curriculum's sections.
*
@@ -268,7 +269,8 @@ const ACTS = {
'/pay': async (p, { beat }) => {
await beat('This is machine to machine payment. An API answers a request with a price instead of a refusal, and the agent pays it.');
- await p.clickIfPresent('button.chain-tab:has-text("BNB")', { after: 1300 });
+ /* Solana is the home chain, so the film opens this page on the Solana
+ tab and stays there rather than touring the secondary rails. */
await p.clickIfPresent('button.chain-tab:has-text("Solana")', { after: 1300 });
await p.type('#prompt', 'validate https://example.com', { cps: 16, settle: 700 });
await beat('Solana first, in USDC, settling in under a second and costing a fraction of a cent.');
@@ -353,14 +355,29 @@ const wantSections = args.sections
? String(args.sections).split(',').map((s) => s.trim()).filter(Boolean)
: null;
-const chapters = [];
+/*
+ * A chapter's number is its place in the WHOLE route, not in whatever slice of
+ * it this run happens to film. Re-shooting one chapter has to write the file the
+ * joined film will look for, open without the film's welcome, and end without
+ * its sign-off, or the re-shot chapter cannot be dropped back in.
+ */
+const allChapters = [];
for (const section of curriculum.sections) {
if (section.id === 'onboarding') continue;
- if (wantSections && !wantSections.includes(section.id)) continue;
- const stops = routeStops().filter((s) => s.section === section.id).slice(0, LIMIT);
- if (stops.length) chapters.push({ ...section, stops });
+ const stops = routeStops().filter((s) => s.section === section.id);
+ if (stops.length) allChapters.push({ ...section, no: allChapters.length + 1, stops });
}
+const lastChapterNo = allChapters.length;
+const chapters = allChapters
+ .filter((c) => !wantSections || wantSections.includes(c.id))
+ .map((c) => ({ ...c, stops: c.stops.slice(0, LIMIT) }))
+ .filter((c) => c.stops.length);
if (!chapters.length) throw new Error('the route selected no stops');
+/* A run that did not cover the whole route must not overwrite the full film or
+ the manifest that records it; its chapters stand alone until a --reuse pass
+ joins them back up. */
+const COMPLETE = chapters.length === allChapters.length
+ && chapters.every((c, i) => c.stops.length === allChapters[i].stops.length);
const totalStops = chapters.reduce((n, c) => n + c.stops.length, 0);
log(`route ${ROUTE}: ${totalStops} stops across ${chapters.length} chapters against ${ORIGIN}`);
@@ -400,17 +417,34 @@ const narrator = new Narrator({
* source, so the whole script can be collected up front.
*/
const BEAT_RE = /beat\(\s*'((?:[^'\\]|\\.)*)'\s*\)/g;
+/* A beat written with backticks or double quotes would be invisible here and
+ would then be synthesized mid-take, which is exactly the dead air the warm-up
+ exists to prevent. Counting the calls catches that at startup instead. */
+function beatsIn(act) {
+ const src = String(act);
+ const calls = (src.match(/\bbeat\(/g) || []).length;
+ const found = [...src.matchAll(BEAT_RE)].map((m) => m[1].replace(/\\'/g, "'"));
+ if (found.length !== calls) {
+ throw new Error(`an act has ${calls} beat() calls but ${found.length} readable literals; `
+ + 'write every beat as a single-quoted string so the warm-up can synthesize it');
+ }
+ return found;
+}
+
function scriptLines() {
const lines = [OPENING, CLOSING];
for (const chapter of chapters) {
lines.push(chapter.intro);
for (const stop of chapter.stops) lines.push(lineFor(stop));
}
- for (const act of Object.values(ACTS)) {
- for (const m of String(act).matchAll(BEAT_RE)) lines.push(m[1].replace(/\\'/g, "'"));
- }
+ for (const act of Object.values(ACTS)) lines.push(...beatsIn(act));
return lines;
}
+/* contextOptions carries the actionable message about minting a QA session, but
+ it is not reached until the first chapter, and the narration lane is
+ signed-in-only: without this the run dies seventeen minutes earlier on a bare
+ TTS 401. */
+if (args.authed) contextOptions({ authed: true });
await narrator.warm(scriptLines());
const skipped = [];
@@ -418,8 +452,8 @@ const parts = [];
const browser = await chromium.launch(launchOptions());
try {
- for (const [ci, chapter] of chapters.entries()) {
- const out = path.join(OUT, `${NAME}-${String(ci + 1).padStart(2, '0')}-${chapter.id}.mp4`);
+ for (const chapter of chapters) {
+ const out = path.join(OUT, `${NAME}-${String(chapter.no).padStart(2, '0')}-${chapter.id}.mp4`);
if (args.reuse && existsSync(out)) {
log(`chapter ${chapter.title}: reusing ${path.basename(out)}`);
parts.push(out);
@@ -438,17 +472,18 @@ try {
narrator.open(t0);
const p = new Presenter(page, { log });
- log(`chapter ${ci + 1}/${chapters.length}: ${chapter.title} (${chapter.stops.length} stops)`);
+ log(`chapter ${chapter.no}/${lastChapterNo}: ${chapter.title} (${chapter.stops.length} stops)`);
/* Open on the chapter's first page so the title card sits over the real
product rather than over a blank tab. The card carries the words while
they are spoken, so the caption bar stays out of its way. */
const first = chapter.stops[0];
- await page.goto(`${ORIGIN}${first.path}`, { waitUntil: 'domcontentloaded', timeout: 60_000 }).catch(() => {});
+ await page.goto(`${ORIGIN}${first.path}`, { waitUntil: 'domcontentloaded', timeout: 60_000 })
+ .catch((err) => log(` opening ${first.path} failed: ${String(err.message).split('\n')[0]}`));
/* The card goes up as soon as the document exists, so the chapter opens
on a title rather than on a page still streaming its 3D scene in. */
await p.showCursor(false);
- if (ci === 0) {
+ if (chapter.no === 1) {
/* The opening already welcomes the viewer, so chapter one does not
also read the guide's own welcome line back to them. */
await p.chapter('', 'three.ws', OPENING);
@@ -458,7 +493,7 @@ try {
await sleep(2600);
} else {
const intro = chapter.intro;
- await p.chapter(`Chapter ${ci + 1}`, chapter.title, intro);
+ await p.chapter(`Chapter ${chapter.no}`, chapter.title, intro);
const introUntil = await narrator.say(p, intro, { caption: false });
await narrator.settle(introUntil);
}
@@ -501,7 +536,7 @@ try {
}
}
- if (ci === chapters.length - 1) {
+ if (chapter.no === lastChapterNo) {
await p.caption('', '');
await p.badge('');
await p.showCursor(false);
@@ -526,14 +561,17 @@ try {
}
const full = path.join(OUT, `${NAME}.mp4`);
-if (parts.length > 1) {
+if (!COMPLETE) {
+ log(`partial run: ${parts.length} chapter file(s) written, none of them joined`);
+ log(`rejoin the whole film with: npm run demo:video -- --reuse${ROUTE === 'full' ? '' : ` --route=${ROUTE}`}`);
+} else if (parts.length > 1) {
concatParts(parts, full, WORK);
log(`wrote ${path.relative(ROOT, full)}`);
-} else if (parts.length === 1) {
+} else {
log(`single chapter: ${path.relative(ROOT, parts[0])}`);
}
-const film = existsSync(full) ? full : parts[0];
+const film = COMPLETE && existsSync(full) ? full : null;
const info = film ? mediaInfo(film) : { seconds: 0, bytes: 0 };
const manifest = {
generatedAt: new Date().toISOString(),
@@ -555,8 +593,13 @@ const manifest = {
})),
skipped,
};
-writeFileSync(path.join(OUT, `${NAME}-manifest.json`), `${JSON.stringify(manifest, null, '\t')}\n`);
+/* The full run's manifest is committed as the record of what the film covers,
+ so a one-chapter re-shoot writes its own beside it rather than replacing it
+ with a one-chapter record. */
+const manifestFile = path.join(OUT, COMPLETE ? `${NAME}-manifest.json` : `${NAME}-partial-manifest.json`);
+writeFileSync(manifestFile, `${JSON.stringify(manifest, null, '\t')}\n`);
log(`${manifest.recorded}/${totalStops} stops recorded, ${skipped.length} skipped`);
if (skipped.length) for (const s of skipped) log(` skipped ${s.path}: ${s.why}`);
-log(`film: ${manifest.film} (${Math.round(info.seconds / 60)}m ${Math.round(info.seconds % 60)}s, ${(info.bytes / 1e6).toFixed(0)} MB)`);
+if (film) log(`film: ${manifest.film} (${Math.round(info.seconds / 60)}m ${Math.round(info.seconds % 60)}s, ${(info.bytes / 1e6).toFixed(0)} MB)`);
+log(`manifest: ${path.relative(ROOT, manifestFile)}`);