API reference
The complete Python SDK call surface: facades, methods, arguments, and returns.
The complete Scrambo Python SDK call surface in one place. This is a lookup table, not a tutorial. For the learning path from installation to first edit, see Start here.
from scrambo import editor, planner, source, timeline, validation
from scrambo import Artifact, ValidationReport
from scrambo.tools import transcribe, detect_events, detect_beats, masking
from scrambo.tools.genAI import img2video, voiceoverCalls are synchronous. Most agent calls return an Artifact; planner.ask
returns a plain string. 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. |
session.view_edit_snapshot(...) | edit_id=None | Returns a detached PublicEditorView; call .wait() to wait for hydration. Defaults to the current edit. |
session.create_render_handoff(...) | edit_id=None, request_id=None | Waits for capture and returns the selected edit's renderer-neutral scrambo.render-ir.v1 JSON as a dict. Defaults to the current edit. |
editor.close_session() | — | Cancels remaining work, destroys the active session, and releases server capacity. Optional — Scrambo auto-closes on program exit. |
editor.close() | — | Compatibility alias for editor.close_session(). |
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.work(prompt, ...) | tools=(), name="source-work" | Artifact — the run's sole SourceBrief v2 in result["brief"], plus atomically rendered derivatives with stable IDs and paths in result["results"]. |
source.generate_agent.create(prompt, ...) | tools=[generation_tool, ...] (required); optional masking; budget_usd=5.0, max_calls=4, name="generated-assets" (1–80 chars) | Artifact — SourceBrief v2 over generated assets in result["brief"]. |
See Source agents.
Generation deployment ceilings are configurable and default to $15 and 15
outputs per specialist turn. Requests above the active ceiling fail with
generation_limit_exceeded.
planner — read-only analysis and grounded planning
| Call | Accepts | Returns |
|---|---|---|
planner.ask(prompt, ...) | prompt, name="planner-answer" | Plain str; cached automatically against current source/timeline state. |
planner.compile(prompt, ...) | current SourceBrief; tools=(), name="plan" | Artifact — grounded plan in result["plan"]. |
planner.compile(answer, prompt, ...) | answer str, prompt; tools=(), name="plan" | Artifact — answer is optional planning context. |
planner.ask has read tools only and accepts no capabilities. planner.compile
accepts transcribe, detect_events, and masking.
See Planning.
validation — artifact quality checks
| Call | Accepts | Returns |
|---|---|---|
validation.check(target, policy="all", ...) | source, planner, or timeline Artifact; validator selection or ValidationPolicy; name= | ValidationReport. all runs every validator applicable to the target. |
validation.applicable_to(target) | one Artifact | Validator names that can inspect that artifact. |
validation.applicability() | — | Mapping of every validator name to its supported artifact categories. |
A focused selection with no validator that can inspect the target raises; broader mixed groups are narrowed to applicable checks. Source artifacts currently have no public validators; narration semantic continuity is plan-only; the remaining public validators inspect timeline artifacts.
timeline — author, refine, validate
| Call | Accepts | Returns / effect |
|---|---|---|
timeline.author_agent.edit() | current plan; tools=(), name= | Artifact; builds the planned edit from scratch as a new root revision. |
timeline.author_agent.edit(request, ...) | str | plan Artifact | ValidationReport; tools=(), name= | Artifact; promotes a new current revision. Structural editing. |
timeline.graphics_agent.edit(request, ...) | str | ValidationReport; tools=(), name= | Artifact; shapes, panels, backings, accents. |
timeline.sound_agent.edit(request, ...) | str | ValidationReport; tools=(), name= | Artifact; music, bundled SFX, balance, ducking. |
timeline.titles_agent.edit(request, ...) | str | ValidationReport; tools=(), name= | Artifact; titles, cards, lower thirds, typography. |
timeline.captions_agent.edit(request, ...) | str | ValidationReport; tools=(), 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. Source Work, Planner Compile, and Author accept
tools=[transcribe] or tools=[detect_events]; tools=[detect_beats] is
accepted by Source Work only. tools=[masking] is accepted by Source Work,
Generate, Planner Compile, Author, and every refinement specialist; Generate still
requires at least one generation tool.
See Two ways to create the first timeline · Planning · Timeline agents · Validation and repair · Choose the right workflow.
Tools (opt-in, scrambo.tools)
| Tool | Grant / call | Notes |
|---|---|---|
transcribe | tools=[transcribe] on Source Work/Planner Compile/author; transcribe.set_config(provider, model, language, diarize) | Per-call, fail-closed grant; does not persist. Calling transcribe(...) directly raises. Default ElevenLabs Scribe v2. |
detect_events | tools=[detect_events] on Source Work/Planner Compile/author; detect_events.set_config(sample_density, max_frames) | Per-call, fail-closed grant. Defaults: dense sampling, max_frames=900 (1–2400). Calling directly raises. |
detect_beats | tools=[detect_beats] on Source Work only | Per-call, fail-closed grant with no config. Runs cached beat/onset analysis. Calling directly raises. |
masking | tools=[masking] on Source Work/generate/Planner Compile/author/graphics/sound/titles/captions | Paid, per-call, fail-closed grant with no caller configuration. Plain agents may precompute a matte; timeline agents may place one. Calling directly raises. |
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. The opt-in
capabilities (transcribe, detect_events, detect_beats, masking) are agent-only —
you grant them, the specialist decides how to use them. 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 compatibility reference for APIs that explicitly accept an artifact. |
ValidationReport (returned by validation.check or 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. |
Source Work, Planner Compile, and plan-backed Author hand off the current source brief and plan automatically. Keep their returned artifacts only when your own program needs to inspect or validate the result. See Artifacts.
Validator selection spec
validation.check(target, policy) and timeline.validate(policy) take 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 (Planner Compile 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: each SFX's transient lands on its trigger time, and each plan instruction fires its expected number of triggers. | Only when the plan declares sound. | Names the misaligned transient or the instruction's expected-vs-actual trigger count. |
edit_contract.mask_matches_plan | Every live mask has grounded generated-mask provenance, exact source/timeline mapping, and a valid layer stack. | On every timeline mutation; absence passes only when no mask is live. | Names orphaned media, mapping drift, or invalid compositor ordering. |
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.narration.semantic_continuity | A provider scores whether outgoing and incoming planned narration phrases sound natural when joined. Tunable minimum_score, warning_score, context_words, and include_timeline_edges. | On a planner artifact whose ordered direct section clips resolve to word-timed transcripts. All seams are judged in one batch before Author runs. | Extend or trim the planned source windows to complete phrases, or choose a semantically continuous neighboring excerpt. |
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. |