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, fromSec, durationSec }]) that the renderer
  // plays straight through underneath the cuts.
  // "zoomToClick": false at the top level turns the click push-in off for every
  // demo scene (tutorial default); a scene's own zoomToClick wins.
  "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) or "shorts" (big centered
  // karaoke for vertical cuts — see the demo-shorts skill)
  "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 only: 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 | dissolve | slide-left
  // "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 } ]
}