API reference
The whole call surface on one page: facades, methods, arguments, and returns.
The complete Scrambo call surface in one place. This is a lookup table, not a tutorial — each row links to the narrative page with the judgment calls (when to use it, how to prompt it). For the arc from install to first edit, see Start here.
from scrambo import editor, source, timeline
from scrambo import Artifact, ValidationReport
from scrambo.tools import transcribe
from scrambo.tools.genAI import img2video, voiceoverEvery agent call takes a name= stage label and returns an Artifact. Calls
are synchronous; timeline agents edit the current revision in call order.
editor — session and browser editor
| Call | Key arguments | Returns / effect |
|---|---|---|
editor.open(...) | project, input (required), canvas=(w, h), provider, model, thinking | Creates or resumes the project session. |
editor.start() | — | Connects to the browser editor; call before any timeline op. Keep the tab open. |
editor.close() | — | Releases the session. Optional — Scrambo auto-closes on program exit. |
editor.export(path) | — | Not supported on the cloud SDK (raises ScramboError). Export from the editor's Export control. |
See The session lifecycle · Supplying media and creative constraints.
source — media before or alongside the timeline
These agents do not change the live timeline.
| Call | Key arguments | Returns |
|---|---|---|
source.scout_agent.brief(prompt, ...) | tools=(), name= | Artifact — SourceBrief v2 in result["brief"]. |
source.prepare_agent.prepare(prompt, ...) | name= | Artifact — registered mechanical derivatives (transcode, trim, concat, mux, extract). |
source.generate_agent.create(prompt, ...) | tools=[...] (required, non-empty), budget_usd=5.0, max_calls=4, name= | Artifact — SourceBrief v2 over generated assets in result["brief"]. |
See Source agents.
timeline — plan, author, refine, validate
| Call | Accepts | Returns / effect |
|---|---|---|
timeline.storyboard_agent.plan([brief,] prompt, ...) | optional brief Artifact, prompt; tools=(), name= | Artifact — ordered, timed plan in result["plan"]. |
timeline.author_agent.edit(request, ...) | str | storyboard Artifact | ValidationReport; tools=(), name= | Artifact; promotes a new current revision. Structural editing. |
timeline.graphics_agent.edit(request, ...) | str | ValidationReport; name= | Artifact; shapes, panels, backings, accents. |
timeline.sound_agent.edit(request, ...) | str | ValidationReport; name= | Artifact; music, SFX, balance, ducking. |
timeline.titles_agent.edit(request, ...) | str | ValidationReport; name= | Artifact; titles, cards, lower thirds, typography. |
timeline.captions_agent.edit(request, ...) | str | ValidationReport; name= | Artifact; transcript-aligned captions. |
timeline.validate(policy, ...) | validator selection spec or ValidationPolicy (not a prompt); name= | ValidationReport. |
timeline.ensure(policy, repair_with=, ...) | selection/ValidationPolicy; repair_with= one specialist; repairs=, name=, require_passed= | ValidationReport; validates, routes failures to repair_with, re-checks. |
Refinement specialists (graphics/sound/titles/captions) require an
existing timeline. Only author_agent and the three source/storyboard
callables accept tools=[transcribe].
See Two ways to create the first timeline · Storyboarding · Timeline agents · Validation and repair · Choose the right workflow.
Tools (opt-in, scrambo.tools)
| Tool | Grant / call | Notes |
|---|---|---|
transcribe | tools=[transcribe] on scout/storyboard/author; transcribe.set_config(provider, model, language, diarize) | Per-call, fail-closed grant; does not persist. Calling transcribe(...) directly raises. Default ElevenLabs Scribe v2. |
img2video(shots, ...) | duration, vendor, resolution, aspect_ratio, name, budget_usd=5.0 | shots: one dict, a list, or a prompts.json path. Each shot needs a first frame; optional last_frame interpolates. Returns Artifact. |
voiceover(text_or_path, ...) | voice (required), vendor, name, budget_usd=5.0 | Literal script text or a .txt/.md path. Returns Artifact. |
Deterministic generation tools write media into source/, register it in the
manifest, and reuse content-addressed outputs for free on a rerun. See
Source agents.
Result types
Artifact (returned by every agent call):
| Field / method | Meaning |
|---|---|
name | Stage name your program supplied. |
kind | Kind of agent task that produced it. |
execution_id | Unique accepted execution of that task. |
result | Structured data, e.g. result["brief"], result["plan"], media records. |
llm_invoked | Whether a model call was required. |
cached | Whether Scrambo reused prior work. |
input_ref() | Compact handoff reference (usually created for you when you pass an artifact onward). |
ValidationReport (returned by timeline.validate) adds:
| Field / method | Meaning |
|---|---|
passed | True when all selected validators passed. |
findings | Structured findings for logging or custom routing. |
md | Readable Markdown report. |
require_passed() | Raises ScramboValidationError if the report failed. |
Pass Artifacts onward directly — never copy .result into the next call. See
Artifacts.
Validator selection spec
timeline.validate(policy) takes a comma-separated list of exact validator
names or dotted group prefixes — all, none, a prefix like
edit_quality.caption, and a leading - to exclude (e.g.
"all,-edit_quality.sfx"). An unknown token raises and lists valid names. Pass a
ValidationPolicy to bundle a selection with per-validator quality settings.
How a check reports
Every validator returns structured findings. Each finding carries a severity
(fail or warn), a plain-language message, and usually a target — the
exact clip, caption group, or plan section it points at — plus a suggested fix.
report.passed is False only if some selected check produced a fail; a warn
is advisory and does not fail the report. report.findings is the structured
list for custom routing; report.md is the same content rolled up as readable
Markdown with fixes ordered by priority. Many checks no-op to a pass when the
layer they judge doesn't exist (no captions authored, no plan, no sound), so
selecting a group your edit didn't touch is harmless.
edit_contract.* — hard invariants
These enforce that the edit is what was declared. Each is verified automatically when the owning specialist is promoted, so a caller usually selects them only as a final gate.
| Validator | What it checks | Runs when | On a violation (fail) |
|---|---|---|---|
edit_contract.canvas_matches | Timeline resolution equals the editor.open(canvas=…) you declared. | Always. | Reports the drifted dimensions. |
edit_contract.duration_matches | Final length is within tolerance of the declared target duration. | Only when a target duration was set (storyboard or author). Skipped silently otherwise. | Reports measured vs. target delta. |
edit_contract.video_has_no_gaps | The visible video track has no uncovered time from first to last shot. | Once a timeline exists. | Points at each uncovered interval. |
edit_contract.video_matches_plan | Video shots realize the plan's clip IDs, order, and section windows exactly. | Only with a plan.json. | Names the missing, extra, or misplaced shot. |
edit_contract.captions_match_plan | Captions realize the planned caption elements and timing. | Only when the plan declares captions. | Names the unrealized or drifted caption. |
edit_contract.titles_match_plan | Title/card elements match the plan's declared IDs and placements. | Only when the plan declares titles. | Names the missing or altered title. |
edit_contract.graphics_match_plan | Graphic elements match the plan's declared IDs and placements. | Only when the plan declares graphics. | Names the missing or altered graphic. |
edit_contract.sound_matches_plan | Music/SFX elements realize the planned sound layer. | Only when the plan declares sound. | Names the missing or misplaced audio. |
edit_contract.fonts_loaded | Every font family/weight/style used by text was actually loaded. | When text clips exist. | Names the unloaded face to client.load_font(...). |
edit_quality.* — editorial judgments
Opt-in taste checks. They never run automatically — acceptance is caller-owned —
and each accepts per-validator settings through ValidationPolicy (keyed by the
concrete validator name). Their severity scales with how far off the edit is, so
they emit warn for borderline cases and fail only for clear defects.
| Validator | What it checks | Runs when | Typical fix |
|---|---|---|---|
edit_quality.pacing.short_shots | Shots aren't shorter than a readable hold. | On the video track. | Lengthen, merge, or replace the flashed shot. |
edit_quality.pacing.parent_flashes | The return to the speaker between cutaways isn't a second jump cut. | When cutaways sit over a base shot. | Hold the return longer or extend the cutaway. |
edit_quality.coverage.broll | Planned cutaway/B-roll coverage is present and long enough to read. | Only with a plan. | Add or lengthen the missing cover shot. |
edit_quality.structure.plan | Section order and boundaries follow the planned structure. | Only with a plan. | Re-order or re-time sections to the plan. |
edit_quality.caption.cadence.minimum_duration | Each caption stays on screen long enough to read (tunable min_duration). | When captions exist. | Extend or merge the short caption item. |
edit_quality.caption.cadence.cut_clearance | Caption groups don't straddle a shot change. | When captions exist. | Nudge the group clear of the cut. |
edit_quality.caption.segmentation | Words in a planned group reveal and clear together as one unit. | When captions exist. | Regroup so the phrase enters and exits together. |
edit_quality.caption.layout.row_layout | Caption rows sit in tidy bands with sane line spacing and word gaps. | When captions exist. | Adjust line height / row banding. |
edit_quality.caption.layout.balance | Groups read as horizontally centered by measured width. | When captions exist. | Re-center the group on its true width. |
edit_quality.typography.minimum_size | No text falls below a legible minimum size. | When text clips exist. | Raise fontSize. |
edit_quality.typography.overlap | Text rows/clips don't unintentionally overlap. | When text clips exist. | Fewer words per row, or re-measure the layout. |
edit_quality.sfx.density | SFX trigger cadence is neither too sparse nor too busy. | When a sound plan exists. | Adjust trigger cadence. |
edit_quality.sfx.levels | Music/SFX gain sits in a sane mix under narration. | When a sound plan exists. | Adjust gain or ducking. |
program.safe and program.executable are internal transaction checks and are
never selectable through timeline.validate().