The session lifecycle
editor.open, editor.start, editor.close, and how sessions and export work.
A typical program follows this arc:
editor.open(...)creates or resumes a project session.editor.start()connects the program to the browser editor.- Source agents inspect or prepare the media, if needed.
- Timeline agents create and refine the edit.
timeline.validate(...)checks the current revision.- The session closes automatically when the program ends.
Scrambo registers the session to close automatically when your program exits —
whether it finishes normally or stops on an uncaught error — so you do not need
a try/finally or an explicit editor.close(). Call editor.close() only
when you want to release the session before the program ends.
One Python process has one active Scrambo session. Facade calls use that active session implicitly; you do not pass a session object between agents and should not try to edit two projects concurrently in one process.
editor.open(...)
session = editor.open(
project="customer-story",
input="./media",
canvas=(1920, 1080),
provider="codex",
model=None,
thinking="high",
)| Argument | Meaning |
|---|---|
project | A stable project name. Reusing it lets Scrambo reuse matching work where the runtime supports resumable projects. |
input | Required. A media file, or a directory of top-level video, audio, and images plus optional transcript-candidate JSON. A cloud session needs at least one supported media file (video .mp4/.mov/.m4v/.mkv/.avi/.webm, audio .mp3/.wav/.m4a/.aac/.flac/.ogg, images .jpg/.jpeg/.png/.gif/.webp/.heic); JSON is ancillary only. Limits: at most 20 top-level files and 500 MB in total, with unique file names. Only top-level files are uploaded; nested directories are ignored. |
canvas | (width, height) in pixels. Common choices are (1080, 1920) for vertical, (1920, 1080) for landscape, and (1080, 1080) for square. |
provider | Optional agent provider. Omit it to use the environment's default. echo may be available as a deterministic test provider. |
model | Optional provider model identifier. Omit it unless the environment exposes a specific choice. |
thinking | Optional reasoning level supported by the selected provider. More reasoning can help with complex, evidence-heavy edits but usually takes longer. |
Pin canvas when format matters. If you omit it, planning and authoring agents
infer a format from your prompt and fall back to the source media when the
request is ambiguous.
The project name identifies work and cached artifacts; the name= on each
agent call identifies a particular stage inside that project. Use stable,
descriptive names such as source-brief, storyboard, roughcut, and
final-check.
editor.start() and editor.close()
editor.start() opens or attaches to the browser editor and waits until it is
ready. Call it before any operation that reads or changes the live timeline.
Keep the editor tab open while the program is running.
You normally do not call editor.close(). Scrambo closes the active session
automatically when your program exits, whether it finishes normally or stops on
an uncaught error. Call editor.close() yourself only to release the session
before the program ends; either way the finished edit remains available for
preview and export in the browser editor.
Export
Export the finished video with the browser editor's Export control.
Programmatic editor.export(path) is not supported by the cloud SDK — calling
it raises a ScramboError — so do not rely on it in a cloud program.