Timeline agents
The author and the graphics, sound, titles, and captions refinement specialists.
Every timeline agent returns an Artifact and promotes a new current revision.
Later timeline calls build on that current revision unless the author is given a
storyboard plan, which asks it to construct the complete planned edit.
timeline.author_agent.edit(...)
The author accepts three request types:
| Request | Effect |
|---|---|
str | Creates a timeline directly, or revises the current timeline from a free-form instruction. |
Storyboard Artifact | Builds the complete rough cut described by result["plan"]. |
ValidationReport | Repairs the report's timeline revision while preserving work that already passes. |
The author owns structural editing: selecting and trimming clips, arranging tracks, preserving or muting source audio, placing cutaways, creating montages, and making timeline-wide repairs.
All three request forms accept tools=[transcribe]. Use it for a direct-author
workflow that must discover spoken content or for an author repair that truly
needs new transcript evidence; omit it when the accepted brief/plan and working
transcript already contain what the author needs.
Refinement specialists
Refinement specialists require an existing timeline. Each exposes
.edit(request, *, name=None) and accepts either a string or a
ValidationReport.
| Agent | Best used for |
|---|---|
timeline.graphics_agent | Shapes, panels, backings, visual accents, and other graphic elements. |
timeline.sound_agent | Music treatment, sound effects, audio balance, and sound-design timing. |
timeline.titles_agent | Opening titles, section cards, lower thirds, end cards, and typography. |
timeline.captions_agent | Transcript-aligned spoken-word captions and caption styling. |
Example layered pass:
timeline.titles_agent.edit(
"Add a restrained opening title for 'Field Notes' and a two-line end card. "
"Use warm white type, generous margins, and no other text.",
name="titles",
)
timeline.captions_agent.edit(
"Caption only the interview speech. Use sentence-aware two-line groups, "
"highlight the current word, keep clear of faces, and do not caption music.",
name="captions",
)
timeline.sound_agent.edit(
"Add subtle transitions at the three section changes. Keep dialogue dominant, "
"duck music under speech, and avoid effects during the closing sentence.",
name="sound-design",
)Give each specialist only the work it owns. A caption request should not ask for a recut; a sound request should not redesign titles. If a refinement reveals a structural problem, send that change to the author first.
Order refinement passes intentionally. For example, lock the picture before caption timing and sound alignment, and make large structural repairs before fine typography adjustments.