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. Calling Author with no
request builds the current plan.json as a new root edit.
timeline.author_agent.edit(...)
The author accepts four request forms:
| Request | Effect |
|---|---|
No request — edit() | Builds the complete current plan.json from scratch. Call planner.compile(...) first. |
str | Creates a timeline directly, or revises the current timeline from a free-form instruction. |
Planner 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 four request forms accept tools=[transcribe], tools=[detect_events],
and tools=[masking].
Use transcribe for a direct-author workflow that must discover spoken content
or a repair that truly needs new transcript evidence, and detect_events when
the author must watch a clip and ground events itself; omit them when the
accepted brief/plan already contains what the author needs. Both grants are
fail-closed and per call — see
Agent-only capabilities.
masking grants paid matte generation/reuse for that turn. detect_beats is
Source Work-only and is not accepted here.
Refinement specialists
Refinement specialists require an existing timeline. Each exposes
.edit(request, *, tools=(), 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.
Every refinement specialist accepts tools=[masking] for an explicitly
requested cross-layer mask effect. The specialist may coordinate the layer
stack needed for that effect while preserving unrelated layers. Mask placement
is full-state and transactionally validated on every later timeline mutation,
even when that later call is not granted masking. Sound effects themselves stay
intrinsic to sound_agent; there is no public SFX tool or endpoint.
Order refinement passes intentionally. For example, lock the picture before caption timing and sound alignment, and make large structural repairs before fine typography adjustments.