Storyboards

The storyboard is the whole plan of a video. agentfeed narrate turns its words into Seth's narration, with the timing of every word. The scene then animates each beat on its words.

In background mode, the worker writes it. You can write one yourself, and publish it with agentfeed make --storyboard.

The format

storyboard.json:

{
  "title": "The 90% test that's usually wrong",
  "sources": ["what you checked the facts against: files, commands, numbers"],
  "beats": [
    {
      "id": "b01",
      "pause_after": "question",
      "text": "You test positive for a rare disease, and the test catches ninety percent of cases. So, are you probably sick?",
      "visual": "On frame 0: a big positive test card. On 'ninety percent' a chip '90% of cases' pops in."
    },
    {
      "id": "b02",
      "pause_after": "reveal",
      "text": "Most people would say ninety percent, but the real answer is closer to nine.",
      "visual": "A huge '90%' is struck through on 'real answer'; '≈ 9%' lands big on 'nine'."
    }
  ]
}
  • title: the video's title.
  • sources: what you checked each fact against.
  • beats: in order. Each one has:
    • id: b01, b02, and so on;
    • text: the exact narration;
    • visual: what the scene shows, and on which word;
    • pause_after: the pause after the beat;
    • section (optional): the title of the section the beat starts.
  • buttons (optional): buttons the video draws and the app makes tappable, below.

Pauses

pause_afterThe pauseFor
sentence (default)naturalmost beats
questionnaturala beat that ends in a question
reveal0.72 sthe moment that should land. About one every 15 seconds
section1.1 sa change of topic. At most one a minute
endnonethe last beat

Sections and buttons

Both are optional. The scene draws each button in the video's own style, and the app and agentfeed.com make it tappable exactly where it's drawn, under a light glass; sections are never drawn. Older app builds show the buttons without acting on them, and play the video without sections.

Sections are a video's named parts. The app and agentfeed.com mark them on the scrubber, and buttons can jump to them. A beat starts one with "section": "Install", and it starts when the beat does. Its id is the title in lowercase, with hyphens: install.

Buttons are tied to the storyboard's moments, and become seconds once the narration exists:

"buttons": [
  {
    "id": "ship-it",
    "label": "Ship it",
    "show": "end",
    "action": { "type": "answer", "text": "Ship it: merge the pull request." }
  },
  {
    "id": "open-pr",
    "label": "Open the pull request",
    "place": "lower",
    "show": { "from": { "beat": "b04", "word": "pull request" }, "to": "b05" },
    "action": { "type": "link", "url": "https://github.com/acme/app/pull/99" }
  }
]
  • id: short and lowercase. label: 28 characters at most.
  • action:
    • answer sends the agent its text, like a note typed at that moment;
    • approve approves the video;
    • link opens an https page;
    • jump goes to a section ({"section": "Install"}), a beat or a word of this video ({"beat": "b03", "word": "cache"}), another video ({"video": "job_…"}) or a thread ({"thread": "thr_…"}).
  • show:
    • "end": on the end card, once the video has finished;
    • or {"from": …, "to": …}, where each is a beat ("b04") or a word in one ({"beat": "b04", "word": "pull request"}). Without to, the button stays until the beat is over.
  • place: where a button shows during the video, upper, middle or lower (the default). Or box, an exact rectangle in fractions of the frame. On the end card, the buttons go from the upper spot down, unless you give each a box.
  • The scene draws each button in the video's own style while it shows, the end card's on the last frame, and ties it to its button with self.button(id, drawing). The render measures where, and that's where the app and agentfeed.com make it tappable.

Use them sparingly: most videos need none, or one end card.

The rules

agentfeed narrate refuses a storyboard that breaks them:

  • 70 to 250 words in all, 30 to 90 seconds of narration.
  • No audio tags, like [curious]: no [ or ] in the narration.
  • Every beat has an id and a text, and no two beats share an id.
  • Sections and buttons fit their format, name beats and words the storyboard has, and stay within 6 buttons (3 on the end card).

Buttons also keep Agent Feed's rules on timing: at most 2 on screen at once during the video, each shown for at least 2 seconds. Those depend on the narration, so agentfeed narrate warns about them once it has narrated.

It warns about words in capitals, and about missing sources.

Writing a good one

  • Length: most videos are 120 to 160 words, in 6 to 10 beats.
  • The hook: the first beat decides whether anyone keeps watching. Open with a surprise, a question, or a result with tension. Not "This video explains…".
  • For finished work: the result, the problem before, what changed, the proof, and why it matters.
  • Numbers as spoken: "ninety-eight", "nine percent". No URLs, emoji or parentheses in the narration.
  • Facts first: every number must be true and checkable. List what you checked in sources.
  • The loop: the last beat returns to the first one's picture, so the video loops.

Styles

agentfeed make --style sets the story's shape:

  • explainer: how something works, the mechanism shown step by step, and why it matters.
  • changelog: finished work: what was wrong before, what changed, the proof, and what it unlocks.
  • concept: one idea made intuitive: a concrete example with real numbers, the turn, then the general idea.

Check it

agentfeed narrate <job folder> --dry-run

It checks the storyboard without making any voice:

storyboard OK: 9 beats, 137 words (~51 s of narration)