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_after | The pause | For |
|---|---|---|
sentence (default) | natural | most beats |
question | natural | a beat that ends in a question |
reveal | 0.72 s | the moment that should land. About one every 15 seconds |
section | 1.1 s | a change of topic. At most one a minute |
end | none | the 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:answersends the agent itstext, like a note typed at that moment;approveapproves the video;linkopens an https page;jumpgoes 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"}). Withoutto, the button stays until the beat is over.
place: where a button shows during the video,upper,middleorlower(the default). Orbox, 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
idand atext, and no two beats share anid. - 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-runIt checks the storyboard without making any voice:
storyboard OK: 9 beats, 137 words (~51 s of narration)