feat: timeline.export() for NLE project bundles

[videodb-kal]

timeline.export() — NLE project bundles

A timeline can already be rendered to a video. This adds the other thing you might want from it: an editable project.

job = timeline.export()          # returns immediately
job.wait()                       # or poll job.refresh()
url = job.download_url()         # short-lived link to a .zip

The zip holds an FCP7 XML project, an OTIO copy, an EDL, an SRT and the media the sequence references — importable with media already relinked, rather than a flat video.

+521 lines, 0 deletions. One new module, one method, one export from the package root.

---

The shape

sequenceDiagram
    participant U as Your code
    participant T as Timeline
    participant J as ExportJob
    participant A as VideoDB

    U->>T: timeline.export()
    T->>A: POST (the same payload generate_stream sends)
    A-->>T: job id + status
    T-->>U: ExportJob
    U->>J: wait()
    loop until terminal
        J->>A: GET status
    end
    U->>J: download_url()
    J->>A: GET artifact
    A-->>J: a short-lived URL

Loading

Submit returns straight away because the work is minutes of downloading and encoding. Nothing is held open.

Timeline.export()

def export(
    self,
    format: str = "nle",
    name: str = None,
    client_ref: str = None,
    timeline_id: str = None,
) -> ExportJob

Parameter	Why it exists
format	Named rather than assumed, so a second format is additive
name	The sequence name in the NLE's project panel. Falls back to the timeline id — an unnamed sequence is a worse import than an ugly one
client_ref	Your own identifier, echoed back on the job, so you never have to hold ours to correlate
timeline_id	Your identifier for this timeline; assigned for you when omitted

The payload is the same shape generate_stream sends, including the fallback that uploads the timeline JSON when it exceeds MAX_PAYLOAD_SIZE — a long timeline posted inline can exceed the request body limit.

ExportJob — videodb/export.py

Member	Notes
refresh()	One read; returns self so it chains
wait(timeout=..., poll_interval=...)	Blocks to a terminal state
done / failed / terminal	Properties, not string comparisons at the call site
download_url()	Minted per call and short-lived by construction — never stored, so a link cannot quietly expire in your database
fidelity	What the bundle carried, approximated and dropped

ExportJob is exported at the package root, so from videodb import ExportJob works for type annotations without reaching into a submodule.

---

Design decisions, each with a test

A job is read back under the timeline that produced it. The read path is scoped by timeline, not global — a bare job id is not a lookup key.

download_url() returns str, and now actually does. It was annotated str while returning the response dict on one branch.

Absent and null are different. name, client_ref and timeline_id are omitted from the payload when unset rather than sent as null — absent means "fall back to the timeline id", null means "there is no name", and those are not the same request.

The docstrings describe the SDK's behaviour, not the service behind it. An earlier draft explained infrastructure this package has no business knowing about.

Compatibility

Purely additive: one new module, one new method, one new package-level export. No existing signature, return type or behaviour changes. Nothing is deprecated.

Requires

A VideoDB deployment where the export feature is enabled. Against one where it is not, timeline.export() raises the same error any unavailable endpoint does.

This PR is not a prerequisite for the feature working — it is a typed convenience over an endpoint that can also be called directly. It can merge before, after, or independently of the rest.

---

Verification

tests/test_export.py — 255 lines, no network. Covers the payload shape including the large-timeline upload fallback, the omitted-versus-null distinction, terminal-state handling, wait() timeout behaviour, and download_url()'s return type.

Known follow-up

fidelity is exposed on ExportJob but the status response does not currently populate it, so it reads as empty even for an export that dropped content. The field is right; the plumbing behind it is not finished.

🤖 Generated with Claude Code