Complete examples

import os
from pathlib import Path

from scrambo import editor, source, timeline
from scrambo.tools import transcribe

editor.open(project="reel-with-captions", input="...", canvas=(1080, 1920))
editor.start()

timeline.author_agent.edit(
    "Make a polished 15-second vertical house tour reel from these clips, transcribe voiceover.mp3 as the narrative spine.",
    tools=[transcribe]
)
timeline.captions_agent.edit("Create word-reveal captions from voiceover.mp3 transcript, use fade-in animation.",)

import os
from pathlib import Path

from scrambo import editor, source, timeline
from scrambo.tools.genAI import img2video, voiceover
from scrambo.tools import transcribe


# Listing stills for 13430 Patriot Wy SE, Renton, WA. Override with
INPUT = Path("...")

editor.open(
    project="renton-home-listing-tour",
    input=str(Path(INPUT)),
    canvas=(1920, 1080),  # 16:9 tour
    provider="codex",
    model="gpt-5.6-luna", # or gpt-5.6-terra
)

img2video.set_config(
    model="veo-3.1-lite-generate-preview",
    resolution="720p",
    duration_seconds=6.0,
)
voiceover.set_config(model="eleven_multilingual_v2")

editor.start()

# Use GenAI to generate assets, then create editorial brief.
# The brief describes and label assets for downstream edit 
brief = source.generate_agent.create(
    "Create a narrated 16:9 tour from the listing photos of this Renton custom home. Turn the strongest stills into slow, low-motion 6-second push-ins (24mm interiors, 28mm exteriors) that preserve the exact architecture, and write a warm, concise narration that walks a buyer from the front exterior through the kitchen and great room out to the deck and backyard. Use listing_description.txt and realestate_prompting_guide.md as references.",
    tools=[img2video, voiceover],
    budget_usd=5.0,
    max_calls=10,
    name="listing-tour-generated",
)

# Plan the edit from the generated brief. 
plan = timeline.storyboard_agent.plan(
    brief,
    "Plan a real-estate listing reel that matches the exact length of the voiceover audio file, which is the narrative spine throughout. Import or compute the voiceover transcript so section timing follows the narration's phrase boundaries. Cut on narration phrase boundaries with clean hard cuts, no dialogue other than the voiceover. If background_music is used, keep it as a very low bed under the narration.",
    tools=[transcribe],
    name="listing-storyboard",
)

# Edit on the timeline
timeline.author_agent.edit(plan, name="listing-roughcut")

# caption
timeline.captions_agent.edit(
    "Add transcript-aligned captions for the voiceover narration only, styled as a premium real-estate reel. Reveal one word at a time in sync with speech, and fade each word in as it appears -- no pop, bounce, or scale-in animation on any word, only a clean fade. Group words into short, sentence-aware phrases of at most three to four words per line, at most two lines on screen at once, centered horizontally in the lower third with generous side margins and tight, even line spacing so the block reads as one clean, compact unit -- not spread across the frame. Use a clean modern sans-serif, strong legibility with a subtle stroke or shadow so text stays readable over bright interiors and exteriors alike. Most words are clean white; pick out a few key words per sentence -- room names, standout features, and descriptive highlights such as 'open-concept', 'primary', or 'backyard' -- and render just those in bold with a warm, saturated accent color so they pop against the plain white words without ever feeling busy. Keep captions clear of the very top and bottom safe margins and do not caption background_music.",
    name="listing-captions",
)

# sound design
timeline.sound_agent.edit(
    "If background_music.mp3 is present in the timeline, keep it as a very low, unobtrusive bed -- the voiceover narration must stay clearly dominant at all times. Duck the music further under every spoken phrase, add a short fade-in at the open and fade-out at the close, and avoid any sound effects or transition stingers.",
    name="listing-sound",
)

from scrambo import editor, source, timeline
from scrambo.tools import transcribe

editor.open(
    project="founder-profile",
    input="./founder_media",
    canvas=(1080, 1920),
)

editor.start()

brief = source.scout_agent.brief(
    "Transcribe founder_interview.mov. Find one concise origin-story line, "
    "one concrete customer benefit, and a warm invitation. Find stable "
    "workshop, product-detail, and customer B-roll that directly supports "
    "those statements. Exclude setup footage and repeated takes.",
    tools=[transcribe],
    name="profile-source-brief",
)

plan = timeline.storyboard_agent.plan(
    brief,
    "Create a 35-second vertical founder profile. Open with a 2-second visual "
    "hook, then origin, product proof, customer benefit, and invitation. Keep "
    "the interview audio continuous where possible and cover edits with B-roll. "
    "Reserve the final 3 seconds for a clean end card.",
    name="profile-storyboard",
)

timeline.author_agent.edit(plan, name="profile-roughcut")

timeline.titles_agent.edit(
    "Add a lower third with 'NIA CHEN — FOUNDER' on her first clear appearance, "
    "then an end card reading 'MADE FOR THE EVERYDAY'. Use clean sans-serif "
    "type and generous safe margins.",
    name="profile-titles",
)

timeline.captions_agent.edit(
    "Add transcript-aligned captions for Nia's speech only. Use at most two "
    "lines, sentence-aware groups, and a subtle current-word highlight. Keep "
    "captions clear of the lower third and faces.",
    name="profile-captions",
)

timeline.sound_agent.edit(
    "Use a warm, understated music bed. Keep speech clearly dominant, add only "
    "subtle workshop texture between spoken sections, and let the end card land "
    "without a loud effect.",
    name="profile-sound",
)

selection = "edit_contract,edit_quality.caption,edit_quality.typography,edit_quality.sfx.levels"
report = timeline.validate(selection, name="profile-final-check")
if not report.passed:
    timeline.author_agent.edit(report, name="profile-final-repair")
    report = timeline.validate(selection, name="profile-recheck")
report.require_passed()