demo-script

Writing the script

Narration that works

You are writing for a voice, not a page.

• Short sentences. One idea each. The TTS will honour a comma; it will not rescue a subordinate clause.
• Say what the viewer is watching, half a beat before they see it. "You start by creating a project" lands as the cursor moves toward the button.
• Benefit, then mechanism. "Ship in one click" beats "click the deploy button".
• No feature lists. Three things well beats nine things fast.
• Write the hook last. It is easier once you know what the demo actually shows.
• Spell out anything you want pronounced. "S3" not "S₃"; "dot dev" if it must be said aloud.

Roughly 2.5 words per second. A 60-second video is ~150 words total. That is much less than it sounds — cut accordingly.

Shape of a 60-second demo

Beat	Time	Job
Hook	0–8s	The problem, felt. Not the product name.
Core action	8–24s	The single best thing it does
Context beat	24–30s	B-roll, breathing room, credibility
Payoff	30–50s	The result, and why it matters
Close	50–60s	One clear next step

Presenter lines vs voiceover lines

Both use the same voice, but they read differently. A presenter line is addressed to camera ("Let me show you what changed"). A voiceover line describes what is on screen ("Projects appear the moment they're created"). Do not write voiceover for a presenter shot; it sounds like someone reading a manual at you.

The manifest

demo/<slug>/demo.json is the single source of truth — each video keeps its own project folder under demo/ (e.g. demo/project-overview/), and every script reads and writes the manifest inside it. Anything that exists only in your context is lost on the next run.

{
  "version": 1,
  "slug": "acme-dashboard",
  "product": { "name": "Acme", "tagline": "...", "audience": "...", "valueProps": ["..."] },
  "brand":   { "colors": { "primary": "#5B8DEF", "bg": "#0B0D12", "text": "#FFFFFF" },
               "logo": "assets/logo.png", "font": "Inter" },
  "format":  { "width": 1920, "height": 1080, "fps": 30 },
  // Default: a fal.ai stock voice. `provider` may be omitted (means "fal").
  "voice":   { "provider": "fal", "model": "fal-ai/elevenlabs/tts/eleven-v3",
               "voice": "Rachel", "stability": 0.4 },
  // OR a designed character voice (needs ELEVENLABS_API_KEY; written for you by
  // gen/voice-design.mjs — do not invent a voiceId by hand):
  // "voice": { "provider": "elevenlabs", "model": "eleven_v3",
  //            "voiceId": "abc123...", "voiceName": "Captain",
  //            "designPrompt": "weathered lobster-boat captain...", "stability": 0.4 },
  "presenter": { "mode": "hybrid", "description": "a woman in her 30s, smart casual, warm and direct",
                 "characterImage": "assets/presenter.png", "engine": "fal-ai/infinitalk" },
  // In mode "always" (the tutorial style) every plain demo scene gets a
  // lip-synced corner bubble; "pip" configures its look. All fields optional:
  // shape "circle" (default) | "square", position any corner (default
  // bottom-left), sizePct 10-40 (% of frame width, default 22).
  // "presenter": { "mode": "always", "pip": { "shape": "circle", "position": "bottom-left", "sizePct": 22 }, ... },
  // presenter.continuousPip: true (seeded by --style tutorial) makes
  // gen/presenter.mjs --all produce ONE continuous bubble take instead of
  // per-scene clips; it writes presenter.pipTake — segments laid on the
  // absolute timeline ([{ video, audio, fromSec, durationSec, overlapSec,
  // scenes }], one chunk per scene, named after its first scene) that the
  // renderer plays straight through underneath the cuts, cross-dissolving
  // each seam over the previous chunk's overlapSec silent tail. Re-voicing a
  // scene regenerates only its chunk.
  // "zoomToClick": false at the top level turns the click push-in off for every
  // demo scene (tutorial default); a scene's own zoomToClick wins.
  // Dynamic style (--style dynamic): the same continuous take, RE-FRAMED along
  // the beats' `layout` (see beats below). presenter.takeAspect "16:9" shoots
  // the take wide (assets/presenter-16x9.png) so face beats fill the frame;
  // presenter.frame.morphMs (default 300) is how long a move between layouts
  // takes — 0 for hard cuts; pace "lively" (a move every 4-6s) | "calm" (one
  // layout per step); faceFit "auto" letterboxes a square/9:16 take for
  // full-frame layouts | "cover" crops | "contain"; panelZoom 1-1.6 (default 1,
  // the side panel is a plain cover-fit). No pip block; transitions must be empty.
  // "presenter": { "mode": "always", "continuousPip": true, "takeAspect": "16:9",
  //                "frame": { "morphMs": 300, "pace": "lively", "faceFit": "auto" }, ... },
  "music": { "enabled": false, "bed": "assets/bed.mp3", "duckDb": -14 },
  // Optional sound-effect pack (needs ELEVENLABS_API_KEY): named cues fired on
  // events — insert, stamp, face, bullet, coverExit, transition, card,
  // sceneStart. Any beat/transition/scene/bullet overrides with
  // "sfx": "pop" | false | { "cue", "gain", "offsetSec" }. See demo-assembly § Audio.
  // "sfx": { "enabled": true, "gain": 0.7, "duckDb": -6,
  //          "cues": { "whoosh": { "prompt": "short fast air whoosh, dry", "durationSec": 0.6, "file": null } },
  //          "auto": { "insert": "whoosh", "stamp": "pop", "face": "hit", "transition": "whoosh" } },
  // style: "clean" (pill near the bottom edge), "shorts" (big centered
  // karaoke for vertical cuts — see the demo-shorts skill), "boxed" (1-3 word
  // phrase cards, listicle), or "buildup" (dynamic style: bottom phrase box
  // whose words appear as spoken, one auto-picked word in an accent box —
  // "autoEmphasis": false turns the pick off; captionEmphasis overrides it)
  "captions": { "enabled": true, "style": "clean" },
  // Optional persistent channel-handle watermark (text and/or a small PNG).
  // position: top-left (default) | top-center | top-right | bottom-left | bottom-right
  // — the insets already avoid the zones platform UI covers on vertical video.
  // Opt a scene out with "watermark": false on the scene (e.g. the CTA card).
  // "watermark": { "text": "@handle", "position": "top-left", "opacity": 0.55 },
  // Vertical (and the 16:9 dynamic style, kind "overlay" only — frame 0 is the
  // poster of a README embed): the hook card that IS frame 0 — the thumbnail every platform
  // shows — held ~0.5s then wiped away over the first scene. See demo-shorts §2b.
  // layout: stack | band | corner | stripe   exit: wipe-up | wipe-down | dissolve | slide-left
  // (a landscape overlay defaults to the lower third and wipe-down, clear of the face)
  // "cover": { "hook": "You use AI for all your coding.", "kicker": "AI tech stack",
  //            "layout": "band", "accent": "#8B5CF6", "portrait": "assets/cover-mark.png" },
  // — or a frozen frame of the video itself instead of a card (no hook text):
  // "cover": { "kind": "frame", "scene": "s-r2", "atSec": 2.6, "holdSec": 0.45, "captions": false },
  "timeline": [ /* scenes */ ],
  "transitions": [ { "after": "hook", "type": "fade", "ms": 400 } ]
}