Two ways to create the first timeline
Direct authoring versus the scout, storyboard, and author workflow.
1. Direct authoring
timeline.author_agent.edit(str) is the shortest path. On its first call it can
scout the supplied media automatically and build a complete timeline:
timeline.author_agent.edit(
"Make a 30-second 16:9 conference recap. Use keynote audio as the narrative "
"spine, cover jump cuts with audience and venue B-roll, and end with the "
"speaker's invitation to next year's event.",
name="conference-roughcut",
)Use this when the request is cohesive and you do not need to inspect or reuse a source brief or storyboard separately.
If a timeline already exists, the same string form edits the current revision:
timeline.author_agent.edit(
"Shorten the opening by two seconds, keep the speaker's full final sentence, "
"and replace the weakest audience cutaway.",
name="pacing-revision",
)2. Scout, storyboard, and author
The structured workflow splits editorial decisions into three stages:
from scrambo.tools import transcribe
brief = source.scout_agent.brief(
"Analyze the interviews and B-roll for a 45-second customer story. "
"Transcribe interview_maya.mov. Find a concise problem statement, one "
"specific outcome, a warm closing line, and B-roll that visibly supports "
"each claim.",
tools=[transcribe],
name="customer-source-brief",
)
plan = timeline.storyboard_agent.plan(
brief,
"Plan a 45-second landscape story: 0-4s visual hook, then problem, solution, "
"measurable outcome, and closing invitation. Preserve Maya's sentence "
"boundaries, use B-roll as cutaways over dialogue, and leave the final two "
"seconds visually clean for a logo.",
name="customer-storyboard",
)
timeline.author_agent.edit(plan, name="customer-roughcut")The responsibilities are deliberately different:
- The scout identifies grounded source windows and requests transcription or deeper visual analysis when the brief needs it and the program grants the corresponding capability.
- The storyboard turns accepted evidence into an ordered, timed narrative plan.
- The author translates the plan into the live editor timeline.
Pass the returned Artifact object directly. Do not copy brief.result or
plan.result into the next call; the artifact carries the identity Scrambo
uses to resolve and cache the handoff.