The session lifecycle

A typical program follows this arc:

1. editor.open(...) creates or resumes a project session.
2. editor.start() connects the program to the browser editor.
3. Source agents inspect or prepare the media, if needed.
4. Timeline agents create and refine the edit.
5. timeline.validate(...) checks the current revision.
6. Optionally open a detached editor snapshot or create renderer-neutral JSON.
7. 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_session(). Call editor.close_session() only when you want to destroy the session and release its server capacity 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",
)

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, plan, roughcut, and final-check.

editor.start() and editor.close_session()

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_session(). Scrambo destroys the active session automatically when your program exits, whether it finishes normally or stops on an uncaught error. Call editor.close_session() yourself to cancel any remaining operation and release server capacity before the program ends. After the call returns, the same owner or another user can start a new session. The finished edit remains available for preview and export in the browser editor.

editor.close() remains available as a compatibility alias.

View an edit snapshot

After a timeline edit, session.view_edit_snapshot() opens a detached browser view of the current durable revision. Pass edit_id=authored.edit_id to select a specific revision. Open view.view_url, then call view.wait() to wait for the editor to finish hydrating.

authored = timeline.author_agent.edit("Create a concise caption reel")
view = session.view_edit_snapshot(edit_id=authored.edit_id)
print(view.view_url)
view.wait()

The view is independent of the private agent editor. Manual changes in it do not become durable Scrambo revisions.

Create a render handoff

Call session.create_render_handoff() after authoring a timeline to capture the current durable edit as renderer-neutral scrambo.render-ir.v1 JSON. The call waits for capture and downloads the complete manifest as a Python dictionary.

authored = timeline.author_agent.edit("Create a concise caption reel")
handoff = session.create_render_handoff(edit_id=authored.edit_id)

Omit edit_id to use the current edit. Pass a stable request_id only when you need idempotent retries of the same capture request.

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.