Skip to content

Local video editor for coding agents: 42 FFmpeg tools with a machine-readable contract and an MCP server, for Claude Code, Cursor and Codex. Cut, captions, reframe, loudness, platform exports. No cloud, no API keys.

feat: 2.1.0 — render.py --export-timeline (FCPXML / EDL / OTIO) (#285)

Shogo Kajiyama3550c4f51750
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index 8bea5a1..e22c20a 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "ffmpeg-skill",
"description": "Local FFmpeg video/audio editing for coding agents: 42 tools with a machine-readable contract, capability detection, probe-first / verify-last workflow. No cloud, no API keys.",
- "version": "2.0.0",
+ "version": "2.1.0",
"author": {
"name": "kajisho5",
"url": "https://github.com/kajisho5"
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 289f510..b43308f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,30 @@
(nothing yet)
+## 2.1.0
+
+### Added
+
+- `render.py project.json --export-timeline edit.fcpxml|edit.edl|edit.otio` writes the project's
+ cut as an editor timeline instead of rendering it -- FCPXML 1.10 (Final Cut Pro, DaVinci
+ Resolve), CMX 3600 EDL (Premiere, Resolve, Avid) or OpenTimelineIO JSON. Clips keep their
+ in/out and speed, `transition` becomes a cross dissolve centred on each cut (trimmed so the
+ timeline is exactly `join.py`'s rendered length), `audio.music` is its own track and inline
+ `chapters` are markers. Nothing is encoded. Everything else the project asks for (captions,
+ graphics, overlays, the silence cut, fit, audio processing, loudness, export) is listed in the
+ new `timeline` result block's `not_exported` and on stderr, never dropped silently; a file that
+ exists is refused without `--overwrite`, like every output. Verified: the three formats read
+ back at the right length through the reference `opentimelineio` library and its FCPXML and
+ CMX 3600 adapters. Not verified here: Final Cut, Resolve or Premiere opening them (#143).
+
+### Fixed
+
+- `export.py`'s colour warning called a BT.2020 SDR source "HDR (BT.2020 SDR)" -- 1.x wording
+ that 2.0's `hdr` contradicts. It now says "wide-gamut SDR, not HDR" for that case, and still
+ points at `color.py --to-sdr` (found by eval 24 h1).
+- `docs/demos.md` still printed `proxy.py --crf 34`, a flag 2.0 removed; the gallery is
+ regenerated.
+
## 2.0.0
What 1.10.0 announced for 2.0 (`contract --json`'s `deprecated` list): four changes made, one
diff --git a/README.md b/README.md
index a943f64..7e265d9 100644
--- a/README.md
+++ b/README.md
@@ -257,7 +257,7 @@ These are the rules the skill file gives the agent and the code enforces.
| Tool | What it does |
|---|---|
-| `render.py` | Render a whole edit from a declarative `project.json` (clips, transitions, captions, overlays including the social sticker/hook/meme graphics, music and stem levels, loudness, export, chapter markers, check); `--init`, `--dry-run`, `--stop-after`, `--cache DIR`/`--from STAGE` (reuse the stages that did not change); the captions block takes the fit-size policy (`fit_size`, `min_size`, `fit_size_scope`) and the run reports the caption stage's counts as `caption`; `--template NAME INPUT` renders a shipped delivery template (`--template all` writes the whole social pack plus its table) |
+| `render.py` | Render a whole edit from a declarative `project.json` (clips, transitions, captions, overlays including the social sticker/hook/meme graphics, music and stem levels, loudness, export, chapter markers, check); `--init`, `--dry-run`, `--stop-after`, `--cache DIR`/`--from STAGE` (reuse the stages that did not change); the captions block takes the fit-size policy (`fit_size`, `min_size`, `fit_size_scope`) and the run reports the caption stage's counts as `caption`; `--template NAME INPUT` renders a shipped delivery template (`--template all` writes the whole social pack plus its table); `--export-timeline edit.fcpxml\|.edl\|.otio` (2.1) writes the cut as an editor timeline for Final Cut, DaVinci Resolve or Premiere instead of rendering it — clips, speed, dissolves, the music bed and chapter markers carry over, and `not_exported` names what stays behind |
| `batch.py` | Apply a step recipe or a project to a folder with a content-hash cache; `--watch`; `--jobs N` processes several files at once under one shared `--timeout` |
| `multicam.py` | Align any number of cameras and recorders by audio (with drift correction) and cut between them from a switch list; `--switch energy` auto-cuts to whichever camera is loudest/talking instead of a hand-built list, with `--min-shot` (minimum shot length) and `--edl` (write the cut list) |
| `verify.py` | Run the toolchain on real device files and report PASS / FAIL per step |
diff --git a/SKILL.md b/SKILL.md
index 8ca4132..d228f05 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -117,8 +117,8 @@ Timestamp flags (`--start`, `--end`, `--at`, `--from`, `--duration`, `--offset`,
| "pull the audio out", "give me the sound as WAV" | `audio.py input.mp4 -o input.wav` (an audio extension drops the picture; `--audio-stream 1` picks a track) |
| "compress the voice", "limit the peaks", "gate the room noise" | `audio.py input.mp4 --compress --comp-threshold -20 --comp-ratio 4` / `--limit --limit-ceiling -1` / `--gate --gate-threshold -45` |
| "the audio drifts out of sync over the hour" | `sync.py camera.mp4 recorder.wav --fix-drift --replace-audio` |
-| "turn this podcast into a video", "audiogram" | `render.py --template audiogram ep.m4a --image cover.png` — waveform over a still or colour plate; give an image or colour, nothing is fetched |
-| "make this a TikTok / Reel / Short / YouTube / X / LinkedIn / podcast" | `render.py --template tiktok\|reels\|shorts\|youtube-shorts\|youtube\|x\|linkedin\|facebook\|podcast input.mp4 [--cues cues.txt] [--title "..."]` — frame, captions, loudness, export and check in one command (`--list-templates`, `--write-project` to edit first) |
+| "turn this podcast into a video", "audiogram" | `render.py --template audiogram ep.m4a --image cover.png` — waveform over a still or colour plate; nothing is fetched |
+| "make this a TikTok / Reel / Short / YouTube / X / LinkedIn / podcast" | `render.py --template tiktok\|reels\|shorts\|youtube-shorts\|youtube\|x\|linkedin\|facebook\|podcast input.mp4 [--cues cues.txt] [--title "..."]` — frame, captions, loudness, export, check in one command (`--list-templates`; `--write-project` to edit first) |
| "post it everywhere", "one edit for every platform" | `render.py --template all input.mp4 --cues cues.txt` (or a comma list) → one file per destination plus `<name>_pack.md` (`report.py --pack` renders the HTML) |
| "export for YouTube / Reels / X", "a ProRes master" | `export.py input.mp4 --preset youtube\|reels\|tiktok\|shorts\|linkedin\|facebook\|x\|prores\|h265` (`--normalize` hits the loudness spec in the same call; `youtube-hdr` keeps HDR, `youtube-av1` writes AV1) |
| "make a GIF preview" | `export.py input.mp4 --preset gif` |
@@ -133,12 +133,13 @@ Timestamp flags (`--start`, `--end`, `--at`, `--from`, `--duration`, `--offset`,
| "waveform/spectrum video for this track" | `waveform.py podcast.wav -o waveform.mp4` |
| "add black at the start" | `pad.py clip.mp4 --start 1.5` |
| "cut to the product shot 0:12-0:16", "B-roll over this bit" | `broll.py talk.mp4 --insert product.mp4 --at 12 --end 16` (repeat `--insert/--at`; `--audio b\|mix`) |
-| "add chapters", "chapter markers for YouTube" | `metadata.py episode.mp4 --chapters chapters.txt` (`TIME TITLE` per line; streams copied; a `render.py` project spells it `"chapters"`). `--auto-chapters` proposes them from measured pauses/scene cuts, titled `Chapter N`, renameable |
+| "add chapters", "chapter markers for YouTube" | `metadata.py episode.mp4 --chapters chapters.txt` (`TIME TITLE` per line; streams copied; in a project: `"chapters"`). `--auto-chapters` proposes them from measured pauses/scene cuts (`Chapter N`) |
| "set the title / artist / comment" | `metadata.py episode.mp4 --title "Episode 12" --artist "Studio"` |
| "put these videos in a 4x2 grid" | `grid.py t1.mp4 ... t8.mp4 --cols 4 --rows 2` |
| "stitch these clips", "add a crossfade" | `join.py a.mp4 b.mp4 c.mp4 --transition fade --duration 0.5` |
-| "several changes to the same edit", 3+ steps | `render.py --init project.json`, edit, `render.py project.json` |
-| "I changed one stage, don't redo the rest" | `render.py project.json --cache DIR` — identical stages come from the cache (`--from STAGE` starts there) |
+| "several changes to one edit", 3+ steps | `render.py --init project.json`, edit, `render.py project.json` |
+| "I changed one stage, don't redo the rest" | `render.py project.json --cache DIR` — identical stages reused (`--from STAGE` starts there) |
+| "open it in Premiere / Resolve / Final Cut" | `render.py project.json --export-timeline edit.fcpxml\|.edl\|.otio` — the cut as a timeline, nothing rendered; read `not_exported` |
| "do this to every file in the folder", "use all the cores" | `batch.py FOLDER --recipe batch.json --jobs auto` (steps or a render project; cached) |
| "three cameras, cut between them" | `multicam.py camA.mp4 camB.mp4 camC.mp4 --switch "0-20:0,20-40:1,40-60:2"` (manual) or `--switch energy` (auto-cuts to the loudest camera, `--min-shot`, `--edl`) |
| "what's in this file", "how long is it" | `probe.py input.mp4` |
diff --git a/demos/build.py b/demos/build.py
index 942d1da..cb76158 100644
--- a/demos/build.py
+++ b/demos/build.py
@@ -761,6 +761,13 @@ def demo_render_project(ctx):
ctx.script("render.py", FIX / "project.json", "--fast")
if not after.exists():
raise BuildError("render.py did not write %s" % after)
+ # 2.1: the same project as an editor timeline (nothing rendered), so every demo build runs
+ # --export-timeline end to end and the gallery shows the command next to the render
+ timeline = ctx.path("timeline.otio")
+ ctx.script("render.py", FIX / "project.json", "--export-timeline", timeline)
+ if not timeline.exists():
+ raise BuildError("render.py --export-timeline did not write %s" % timeline)
+ ctx.note("the same project also opens in an editor: --export-timeline writes .otio / .fcpxml / .edl")
return before, after
diff --git a/docs/contract.md b/docs/contract.md
index dcaac83..0d05113 100644
--- a/docs/contract.md
+++ b/docs/contract.md
@@ -21,7 +21,7 @@ The contract is derived from the code that runs, not maintained beside it:
| Field | Meaning | Changes when |
|---|---|---|
| `contract_version` | shape of this document (`1.0`) | a key is renamed, removed or changes meaning |
-| `skill.version` | the npm / package.json version (`2.0.0`) | any release |
+| `skill.version` | the npm / package.json version (`2.1.0`) | any release |
A release that adds a tool or a flag keeps `contract_version`; a breaking change to the
ToolSpec shape bumps it. Consumers pin on `contract_version` and read `skill.version`
@@ -119,7 +119,7 @@ JSON would have been rewritten for that. The flat keys, typed per tool in `outpu
"contract_version": "1.0",
"deprecated": [],
"removed": [{"what": "...", "since": "1.10.0", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | behaviour"}],
- "skill": {"id": "ffmpeg-skill", "version": "2.0.0", "execution_mode": "local", "kind": "execution",
+ "skill": {"id": "ffmpeg-skill", "version": "2.1.0", "execution_mode": "local", "kind": "execution",
"entrypoints": {"cli": "...", "mcp": "...", "contract": "...", "doctor": "..."},
"not_provided": ["AI reasoning", "decisions", "production plans", "project IR", "approvals", "network access", "transcription engine"]},
"requirements": {"python": ">=3.9 (standard library only)", "ffmpeg": ">=5.0", "ffprobe": ">=5.0"},
@@ -469,6 +469,7 @@ Per-tool keys added in 1.17, all additive:
| `snap` | `cut.py --snap beats`, `render.py` | `{mode, tolerance, confidence, tempo_bpm, grid, grid_points, moved, snapped, unchanged, source}`. `grid` is `"supported"`: points are moved only onto grid points a measured onset marks, never onto the regular grid's continuation through a silent passage. `moved` has exactly one row per in/out point given (`from`, `to`, `delta`, `snapped`, `beat_index`) — a point is never added or dropped, and `to` is always either a measured beat or the caller's own value |
| `filler`, `removed_seconds_total` | `silence.py --filler` | `{lang, source, engine, words, removed, removed_count, removed_seconds, removed_words, word_timings, list, warnings}`. The existing `removed_seconds` is unchanged in name and meaning — the seconds of *silence* removed, which is what it has always held — and `removed_seconds_total` is the additive sibling covering silence plus filler |
| `jobs`, `jobs_requested`, `wall_seconds`, `item_seconds_total`, `timed_out` | `batch.py` | the parallelism actually applied and the number asked for, the batch's wall clock, the sum of the per-item times (so the speed-up can be quoted), and whether the shared timeout budget ran out. A timed-out item carries `"skipped": "timeout"` in its result row |
+| `timeline` | `render.py --export-timeline FILE` | `{format, rate, duration, frames, clips, transition, transition_frames, music, markers, notes, not_exported}`: the written timeline's own numbers (`rate` is exact, `"30000/1001"` for 29.97) and what the project asked for that an editor timeline cannot carry. Nothing is encoded (`commands: []`); `verified` means the file was written and reads back as its format (`verification` step `parse`) -- not that an editor opened it |
| `cache` | `render.py --cache` | `{dir, ffmpeg, hits, misses, saved_seconds, entries}`, plus `would_hit` under `--dry-run`. The ffmpeg build banner, the skill version, the contract version, the forwarded flags (`--fast`, `--codec`, …) and the output's extension are all part of every key, so a cache is never reused across any of them — a `--fast` draft is never served to a run that did not ask for one |
Per-tool keys added in 1.17.1, all additive:
diff --git a/docs/demos.md b/docs/demos.md
index 6542c5b..8086763 100644
--- a/docs/demos.md
+++ b/docs/demos.md
@@ -616,7 +616,7 @@ python3 scripts/render.py demos/out/fixtures/motion.mp4 --template tiktok --cues
![Proxy vs. master, shown at the same size](demos/proxy.gif)
```bash
-python3 scripts/proxy.py demos/out/fixtures/mandel.mp4 --width 320 --crf 34 --fps 12 -o demos/out/proxy_after.mp4
+python3 scripts/proxy.py demos/out/fixtures/mandel.mp4 --width 320 --quality 34 --fps 12 -o demos/out/proxy_after.mp4
```
**Look for:** Both halves are scaled to the same cell, which is the honest comparison: the proxy is smaller on disk and cheaper to decode, not smaller on screen. The softness is the point of it.
@@ -630,6 +630,7 @@ python3 scripts/proxy.py demos/out/fixtures/mandel.mp4 --width 320 --crf 34 --fp
```bash
python3 scripts/render.py demos/out/fixtures/project.json --fast
+python3 scripts/render.py demos/out/fixtures/project.json --export-timeline demos/out/render_project_timeline.otio
```
**Look for:** Clips, a transition, captions and a title card described as JSON and rendered in one pass.
diff --git a/docs/design-decisions.md b/docs/design-decisions.md
index c7fa4e6..0225004 100644
--- a/docs/design-decisions.md
+++ b/docs/design-decisions.md
@@ -560,3 +560,33 @@ plain `cut.py --segments` file (`START-END` per line) rather than a `render.py`
because the camera index a project's clips need is already sitting in the JSON `cuts` field
(`[[start, end, camera], ...]`) — turning that into `clips[]` is a few lines in the calling agent,
not a new file format this tool would have to maintain.
+
+## 2.1.0 — handing the cut to an editor
+
+- **`--export-timeline` is an option on `render.py`, not a 43rd tool.** The input is a
+ project file and the translation is render.py's own reading of it (paths resolved the same
+ way, the same validation); a separate tool would re-implement both. Code:
+ `render.export_timeline()`, `_common/timeline.py`.
+- **The timeline matches the project's numbers, not a render's.** A dissolve is centred on
+ each cut and trimmed `trim_head`/`trim_tail` frames either side, so the total is the sum of the
+ clip lengths minus one transition per join -- what `join.py`'s xfade renders by design. A real
+ render can come out a few frames longer, because `join.py` offsets each crossfade by the
+ part's *container* duration (audio priming included); that is render's drift, recorded as a
+ follow-up, and copying it into the timeline would hand an editor a cut nobody asked for.
+ Test: `test_build_centres_each_dissolve_and_keeps_the_rendered_length`.
+- **What a timeline cannot carry is reported, never dropped.** Captions, graphics, overlays,
+ the silence cut, fit, audio processing, loudness and the export preset go to
+ `timeline.not_exported` and stderr. A caption track or a title in FCPXML would be a second
+ implementation of `caption.py`/`graphics.py` whose output no one here can see.
+ Test: `test_build_refuses_what_a_timeline_cannot_hold`.
+- **OTIO's `source_range` is timeline length, with the speed in a `LinearTimeWarp`.** Core
+ OTIO does not rescale a clip's duration by its effects; the first version stored the
+ speed-scaled source length and the reference `opentimelineio` library (0.18) measured the
+ track at 253 frames for a 225-frame cut. Test:
+ `test_otio_track_lengths_add_up_without_counting_transitions`.
+- **Verified here: structure and arithmetic; not verified here: an editor opening the file.**
+ All three formats were read back by the reference OTIO library and its FCPXML / CMX 3600
+ adapters at the right length, but none of Final Cut, Resolve or Premiere is available in this
+ environment, and OTIO's own FCPXML adapter ignores dissolves, markers and retiming, so those
+ parts of the FCPXML are checked only against Apple's schema by hand. The editor round trip is
+ on #143's real-hands checklist.
diff --git a/docs/roadmap.md b/docs/roadmap.md
index b16628b..c02bcd2 100644
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -17,33 +17,11 @@ minor and `fix` PRs into a patch, so each block below is one or two `feat` PRs p
- **planned** — not released. Nothing below a *planned* heading exists in any published version;
the feature lines are the intent, not a description of the code.
-The released version today is **2.0.0** — the five changes 1.10.0 announced: `--crf` removed in
-favour of `--quality`, an existing output refused without `--overwrite`, `probe`'s `hdr` narrowed
-to a real PQ/HLG/Dolby Vision signal (`bt2020_or_hdr` keeps the 1.x meaning, and the tools route
-on it), `json` / `progress` out of the MCP `inputSchema`, and the `result_v2` preview withdrawn
-rather than promoted (the flat keys are the 2.0 shape). No new feature; tool count still 42.
-`docs/contract.md` "What 2.0 changed" is the migration table, and `contract --json` lists the same
-under `removed`. 2.0.0 waived the 90-day half of the deprecation window (stated there).
-that closes the remaining mp4 stream-copy paths — `audio.py`, `caption.py --mode mux`, `sync.py`
-and `cut.py` — over to `+faststart` too (#279); `metadata.py`'s own `-c copy` tag/chapter write is
-left alone, since its documented guarantee is the container's metadata only. No script API
-change, tool count still 42.
-1.19.0 (the `--write-project` feature) is a `feat:` release, hence the minor bump; it does not
-start the "1.19.0: observability, portability" theme further down this document, which remains
-planned. 1.19.2 is docs-only (SKILL.md's overlong-word and MCP core-12 rows, this same truth-up).
-1.19.3 extends 1.18.4's column-edge slice to `graphics.py`'s own `wrapped()` helper (lower-third,
-title, sticker, hook and meme labels), so an unbreakable overlong word no longer clips off-frame
-on those templates either. 1.20.0 is `look.py --ink` (#261), a `feat:` release, hence the minor
-bump — not the start of a new theme. 1.21.0 is `contract --json` gaining per-tool `examples`,
-parsed from SKILL.md's own "User says" / "Do" table (#267), also a `feat:` release and not the
-start of the "1.21.0: the 2.0 freeze" heading further down this document, which remains planned.
-1.22.0 is `batch.py` rolling up `cut.py`'s per-call `reencoded` across a recipe's whole run into
-one `cut_stream_copy` summary (`{calls, stream_copy, reencoded, stream_copy_rate}`, #269), a
-`feat:` release, hence the minor bump -- not the start of a new theme. 1.23.0 moves the MCP
-structured-arguments note out of every one of the 42 `tools/list` descriptions into `initialize`'s
-`instructions` field once (#271), also a `feat:` release, hence the minor bump. 1.24.0 adds the
-"1.20.0" theme's last big item, a `prompts` capability with the five workflow recipes (`reel`,
-`podcast`, `multicam`, `delivery_check`, `hdr`, #272), also a `feat:` release, hence the minor bump.
+The released version today is **2.1.0** — `render.py --export-timeline` hands the cut to an
+editor as FCPXML, CMX 3600 EDL or OpenTimelineIO (clips, speed, dissolves, music bed, chapter
+markers; everything else listed as `not_exported`), plus the eval-24 follow-up that stops
+`export.py` calling a BT.2020 SDR source HDR. 2.0.0 made the five changes 1.10.0 announced
+(docs/contract.md "What 2.0 changed"). Tool count still 42.
| version | state | evidence |
|---|---|---|
diff --git a/package.json b/package.json
index ca4631f..8bb18eb 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "ffmpeg-skill",
- "version": "2.0.0",
+ "version": "2.1.0",
"description": "Agent Skill that gives coding agents (Claude Code, Cursor, Codex) a local video editor: 42 FFmpeg tools with a machine-readable contract, contract-derived MCP server, FFmpeg capability detection, probe-first / verify-last workflow. Cut, join, silence removal, fit, captions and karaoke, overlays, motion graphics, HDR to SDR, LUTs, audio clean-up and typed dynamics, sync with drift correction, multicam, loudness, delivery checks, project rendering, batch. No API keys, no cloud, no dependencies.",
"keywords": [
"ffmpeg",
diff --git a/references/scripts.md b/references/scripts.md
index 92cb80a..1a83b1c 100644
--- a/references/scripts.md
+++ b/references/scripts.md
@@ -569,7 +569,21 @@ render.py --init project.json # starter file
render.py project.json [--fast] [--dry-run] [--stop-after STAGE] [--work DIR --keep]
render.py project.json --cache DIR [--from STAGE] # reuse identical stages from a previous run
render.py plan.json # execute a plan written by <tool> --plan plan.json
-```
+render.py project.json --export-timeline edit.fcpxml|edit.edl|edit.otio # the cut for an editor, nothing rendered
+```
+`--export-timeline FILE` (2.1) writes the project's cut as an editor timeline instead of
+rendering it: `.fcpxml` (FCPXML 1.10: Final Cut Pro, DaVinci Resolve), `.edl` (CMX 3600:
+Premiere, Resolve, Avid) or `.otio` (OpenTimelineIO JSON: Resolve natively, others through
+OTIO's adapters). Clips keep their in/out and speed (an M2 line, a `timeMap`, a
+`LinearTimeWarp`); `transition` becomes a cross dissolve centred on each cut, trimmed so the
+timeline is exactly as long as `join.py`'s crossfade would render it; `audio.music` is its own
+track; inline `chapters` are markers. Everything else in the project -- captions, graphics,
+overlays, the silence cut, fit, audio processing, loudness, export -- is listed in the result's
+`timeline.not_exported` and on stderr, never dropped silently. Media paths are absolute file
+URLs to the sources, nothing is copied or encoded, and the existing-output rule applies
+(`--overwrite` to replace). The timeline follows the project's numbers exactly; a render of
+the same project can come out a few frames longer, because `join.py` offsets its crossfades
+by each part's container duration, audio included.
A plan is a single tool's dry run as an artifact: `cut.py in.mp4 --start 2 --end 8
--plan cut.json` writes `{plan_version, tool, argv, inputs (path, size, sha256 of
head+tail), commands, output, verify}` and runs nothing. `render.py cut.json`
diff --git a/scripts/_common/timeline.py b/scripts/_common/timeline.py
new file mode 100644
index 0000000..5c49103
--- /dev/null
+++ b/scripts/_common/timeline.py
@@ -0,0 +1,379 @@
+"""render.py project -> an editor's timeline (EDL, FCPXML, OTIO).
+
+`render.py project.json --export-timeline edit.fcpxml|.edl|.otio` hands a rough cut to a person
+who finishes it in Premiere, DaVinci Resolve or Final Cut. It is a translation, not a render:
+nothing is encoded, and every decision in the file is one the project already made.
+
+The timeline has to match what render.py itself would deliver, or the editor opens a different
+cut than the agent showed. join.py's crossfade overlaps neighbouring clips by the transition
+duration `d` (xfade: the last `d` s of A blend with the first `d` s of B, so the whole is `d`
+shorter). Editors model a dissolve centred on a cut, using media beyond each clip's visible
+range ("handles"), so each side of a dissolve is trimmed by `d/2` and the dissolve spans `d/2`
+either side of the new cut: the same frames blend over the same span, and the total length is
+the rendered one.
+
+Only what an editor timeline can carry is exported: clips (with in/out and speed), the
+transition between them, a music bed on its own audio track, and chapters as markers.
+Everything else in the project -- captions, graphics, overlays, the silence cut, fit/crop,
+audio processing, loudness, the export preset -- is listed under `not_exported`, never silently
+dropped.
+"""
+import json
+import os
+from fractions import Fraction
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+from xml.sax.saxutils import escape as _xml_escape
+
+FORMATS = {".edl": "edl", ".fcpxml": "fcpxml", ".otio": "otio"}
+# Common NTSC rates are stored as the exact ratio an editor expects, not as 29.97.
+_NTSC = {23.976: Fraction(24000, 1001), 29.97: Fraction(30000, 1001), 59.94: Fraction(60000, 1001),
+ 47.952: Fraction(48000, 1001), 119.88: Fraction(120000, 1001)}
+# project keys an editor timeline cannot carry, with what the caller should know about each
+_NOT_EXPORTED = {
+ "silence": "the silence cut (render.py measures it at render time; the timeline keeps the clips whole)",
+ "captions": "captions (burn them with render.py, or import the .srt into the editor)",
+ "graphics": "graphics (titles, lower thirds, social templates)",
+ "overlays": "overlays (logos and text)",
+ "fit": "fit / reframe to the delivery aspect (set the sequence frame in the editor)",
+ "audiogram": "the audiogram picture",
+ "loudness": "loudness normalisation",
+ "export": "the export preset (the editor's own export decides the delivery)",
+ "check": "the platform check",
+ "brand": "brand styles",
+ "snap": "beat snapping (the timeline uses the project's in/out as written, before any snap)",
+}
+_AUDIO_NOT_EXPORTED = ("replace", "voice", "denoise", "duck", "duck_amount", "duck_threshold", "duck_attack",
+ "duck_release", "gain", "stereo", "mono", "downmix", "stereo_widen", "effects",
+ "effects_volume", "stems", "music_volume", "fade_in", "fade_out", "music_fade_out",
+ "music_loop")
+
+
+class TimelineError(ValueError):
+ """A project that cannot be expressed as a timeline (a caller-facing `kind: input`)."""
+
+
+def exact_rate(fps: float) -> Fraction:
+ for approx, exact in _NTSC.items():
+ if abs(fps - approx) < 0.01:
+ return exact
+ frac = Fraction(fps).limit_denominator(1001)
+ if frac <= 0:
+ raise TimelineError(f"frame rate {fps!r} is not usable for a timeline")
+ return frac
+
+
+def build(proj: Dict[str, Any], probes: Dict[str, Dict[str, Any]], rel) -> Dict[str, Any]:
+ """The editor-neutral timeline: every time in frames at `rate`.
+
+ `probes` maps each resolved clip/music path to its probe(); `rel` resolves a project path
+ the way render.py does. Raises TimelineError for what an editor timeline cannot represent."""
+ clips_in = proj.get("clips") or []
+ if not clips_in:
+ raise TimelineError("project.clips is empty")
+ frame = proj.get("frame") or {}
+ first = probes[rel(clips_in[0]["src"])]
+ fps = frame.get("fps") or (first.get("video") or {}).get("fps")
+ if not fps:
+ raise TimelineError("no frame rate: the first clip has no video stream and project.frame.fps is not set")
+ rate = exact_rate(float(fps))
+ width = int(frame.get("width") or (first.get("video") or {}).get("width") or 1920)
+ height = int(frame.get("height") or (first.get("video") or {}).get("height") or 1080)
+
+ def fr(seconds: float) -> int:
+ return int(round(Fraction(seconds).limit_denominator(1000000) * rate))
+
+ trans = proj.get("transition") or {}
+ t_type = str(trans.get("type", "fade")) if len(clips_in) > 1 else "none"
+ d_frames = 0 if t_type == "none" else fr(float(trans.get("duration", 0.5)))
+ notes: List[str] = []
+ if d_frames and t_type != "fade":
+ notes.append(f'transition "{t_type}" is exported as a cross dissolve: editors do not share xfade\'s other patterns')
+
+ clips: List[Dict[str, Any]] = []
+ for i, c in enumerate(clips_in):
+ src = rel(c["src"])
+ meta = probes[src]
+ dur = float(meta.get("duration") or 0.0)
+ start = float(c.get("in") or 0.0)
+ end = float(c["out"]) if c.get("out") is not None else dur
+ if end <= start:
+ raise TimelineError(f"clip {i}: out ({end:g}) is not after in ({start:g})")
+ speed = float(c.get("speed") or 1.0)
+ if not speed > 0:
+ raise TimelineError(f"clip {i}: speed must be positive, got {c.get('speed')!r}")
+ src_in, src_out = fr(start), fr(end)
+ clips.append({"index": i, "src": os.path.abspath(src), "name": os.path.basename(src),
+ "src_in": src_in, "src_out": src_out, "speed": speed,
+ "length": int(round((src_out - src_in) / speed)),
+ "media_frames": fr(dur), "has_video": bool(meta.get("video")),
+ "has_audio": bool(meta.get("audio")),
+ "width": (meta.get("video") or {}).get("width"), "height": (meta.get("video") or {}).get("height")})
+
+ # Centre each dissolve on the cut: trim d/2 off the outgoing tail and d/2 off the incoming head.
+ half_a, half_b = d_frames // 2, d_frames - d_frames // 2
+ for i, c in enumerate(clips):
+ c["trim_head"] = half_b if (i > 0 and d_frames) else 0
+ c["trim_tail"] = half_a if (i < len(clips) - 1 and d_frames) else 0
+ visible = c["length"] - c["trim_head"] - c["trim_tail"]
+ if visible <= 0:
+ raise TimelineError(f"clip {c['index']} ({c['name']}) is shorter than its transitions")
+ c["visible"] = visible
+ pos = 0
+ for c in clips:
+ c["record_in"] = pos
+ pos += c["visible"]
+ total = pos
+
+ music = None
+ audio = proj.get("audio") or {}
+ if audio.get("music"):
+ msrc = rel(audio["music"])
+ mmeta = probes[msrc]
+ mlen = min(fr(float(mmeta.get("duration") or 0.0)), total)
+ if mlen > 0:
+ music = {"src": os.path.abspath(msrc), "name": os.path.basename(msrc), "length": mlen,
+ "media_frames": fr(float(mmeta.get("duration") or 0.0))}
+ if audio.get("music_loop"):
+ notes.append("music_loop is not exported: the bed plays once, up to the timeline's length")
+
+ markers: List[Dict[str, Any]] = []
+ chapters = proj.get("chapters")
+ if isinstance(chapters, list):
+ for ch in chapters:
+ at = fr(float(ch.get("at", 0)))
+ if 0 <= at < total:
+ markers.append({"at": at, "title": str(ch.get("title") or "")})
+ elif chapters:
+ notes.append("chapters given as a file are not exported as markers; write them inline as [{at, title}]")
+
+ not_exported = [text for key, text in _NOT_EXPORTED.items() if proj.get(key)]
+ dropped_audio = sorted(k for k in _AUDIO_NOT_EXPORTED if audio.get(k) not in (None, False, "", 0) and k != "music")
+ if dropped_audio:
+ not_exported.append("audio processing: " + ", ".join(dropped_audio))
+ return {"name": Path(str(proj.get("output") or "timeline")).stem, "rate": rate, "width": width, "height": height,
+ "clips": clips, "transition": t_type if d_frames else "none", "transition_frames": d_frames,
+ "music": music, "markers": markers, "total": total, "notes": notes, "not_exported": not_exported}
+
+
+# ---------------------------------------------------------------------------------------- EDL
+def _tc(frames: int, fps_int: int) -> str:
+ h, rem = divmod(frames, fps_int * 3600)
+ m, rem = divmod(rem, fps_int * 60)
+ s, f = divmod(rem, fps_int)
+ return f"{h:02d}:{m:02d}:{s:02d}:{f:02d}"
+
+
+def to_edl(tl: Dict[str, Any]) -> str:
+ """CMX 3600, non-drop timecode at the nominal integer rate, record starting at 01:00:00:00.
+ Every event is reel AX (the convention for file-based media) with the file named in
+ FROM CLIP NAME / SOURCE FILE comments, which Premiere and Resolve both relink from. A speed
+ change is an M2 line. A dissolve is the standard pair: a zero-length cut on the outgoing
+ source where its event ended, then a D event that brings the incoming clip in over `d`
+ frames starting at the incoming clip's own in point -- so each event's record range runs
+ from where the previous one stopped to where the next dissolve begins."""
+ fps_int = int(round(float(tl["rate"])))
+ hour = fps_int * 3600
+ clips = tl["clips"]
+ d = tl["transition_frames"]
+ # record range of each event: starts `trim_head` before its visible start (the dissolve
+ # window), ends where the next event starts
+ starts = [c["record_in"] - c["trim_head"] for c in clips]
+ ends = starts[1:] + [tl["total"]]
+ lines = [f"TITLE: {tl['name']}", "FCM: NON-DROP FRAME", ""]
+ n = 0
+ prev_src_end = 0
+ for i, c in enumerate(clips):
+ n += 1
+ chan = "B" if c["has_audio"] and c["has_video"] else ("V" if c["has_video"] else "A")
+ rec_in, rec_out = hour + starts[i], hour + ends[i]
+ s_in = c["src_in"]
+ s_out = s_in + int(round((ends[i] - starts[i]) * c["speed"]))
+ if i > 0 and d:
+ lines.append(f"{n:03d} AX {chan:<5} C {_tc(prev_src_end, fps_int)} {_tc(prev_src_end, fps_int)} "
+ f"{_tc(rec_in, fps_int)} {_tc(rec_in, fps_int)}")
+ lines.append(f"{n:03d} AX {chan:<5} D {d:03d} {_tc(s_in, fps_int)} {_tc(s_out, fps_int)} "
+ f"{_tc(rec_in, fps_int)} {_tc(rec_out, fps_int)}")
+ lines.append(f"* FROM CLIP NAME: {clips[i - 1]['name']}")
+ lines.append(f"* TO CLIP NAME: {c['name']}")
+ else:
+ lines.append(f"{n:03d} AX {chan:<5} C {_tc(s_in, fps_int)} {_tc(s_out, fps_int)} "
+ f"{_tc(rec_in, fps_int)} {_tc(rec_out, fps_int)}")
+ lines.append(f"* FROM CLIP NAME: {c['name']}")
+ lines.append(f"* SOURCE FILE: {c['src']}")
+ if abs(c["speed"] - 1.0) > 1e-6:
+ lines.append(f"M2 AX {fps_int * c['speed']:05.1f} {_tc(s_in, fps_int)}")
+ lines.append("")
+ prev_src_end = s_out
+ if tl["music"]:
+ n += 1
+ m = tl["music"]
+ lines.append(f"{n:03d} AX A2 C {_tc(0, fps_int)} {_tc(m['length'], fps_int)} "
+ f"{_tc(hour, fps_int)} {_tc(hour + m['length'], fps_int)}")
+ lines.append(f"* FROM CLIP NAME: {m['name']}")
+ lines.append(f"* SOURCE FILE: {m['src']}")
+ lines.append("")
+ for mk in tl["markers"]:
+ lines.append(f"* LOC: {_tc(hour + mk['at'], fps_int)} WHITE {mk['title']}")
+ return "\n".join(lines).rstrip("\n") + "\n"
+
+
+# ---------------------------------------------------------------------------------------- FCPXML
+def _t(frames: int, rate: Fraction) -> str:
+ """A rational FCPXML time: frames at `rate`, as `N/Ds` (or `Ns` when whole)."""
+ value = Fraction(frames) / rate
+ return f"{value.numerator}s" if value.denominator == 1 else f"{value.numerator}/{value.denominator}s"
+
+
+def _url(path: str) -> str:
+ # pathlib builds the percent-encoded file:// URL itself (and the drive-letter form on
+ # Windows): no network-library import in scripts/, not even for quoting (see the no-fetch test)
+ return Path(os.path.abspath(path)).as_uri()
+
+
+def to_fcpxml(tl: Dict[str, Any]) -> str:
+ """FCPXML 1.10 (Final Cut Pro 10.6+, DaVinci Resolve): one library/event/project, a spine of
+ asset-clips with cross dissolves between them, the music bed as a connected clip on lane -1
+ of the first clip, chapters as chapter-markers. Speed is a linear timeMap on the clip."""
+ rate = tl["rate"]
+ q = lambda s: _xml_escape(str(s), {'"': "&quot;"}) # noqa: E731
+ fd = _t(1, rate)
+ res = [f' <format id="r1" name="FFVideoFormat{tl["height"]}p" frameDuration="{fd}" width="{tl["width"]}" height="{tl["height"]}"/>']
+ ids: Dict[str, str] = {}
+
+ def asset(path: str, name: str, frames: int, has_video: bool, has_audio: bool) -> str:
+ if path in ids:
+ return ids[path]
+ rid = f"r{len(ids) + 2}"
+ ids[path] = rid
+ res.append(f' <asset id="{rid}" name="{q(name)}" start="0s" duration="{_t(frames, rate)}" '
+ f'hasVideo="{int(has_video)}" hasAudio="{int(has_audio)}"'
+ + (' format="r1"' if has_video else "") + ' audioSources="1" audioChannels="2">\n'
+ f' <media-rep kind="original-media" src="{q(_url(path))}"/>\n </asset>')
+ return rid
+
+ spine: List[str] = []
+ d = tl["transition_frames"]
+ markers = list(tl["markers"])
+ for i, c in enumerate(tl["clips"]):
+ rid = asset(c["src"], c["name"], c["media_frames"], c["has_video"], c["has_audio"])
+ if i > 0 and d:
+ spine.append(f' <transition name="Cross Dissolve" offset="{_t(c["record_in"] - c["trim_head"], rate)}" '
+ f'duration="{_t(d, rate)}"/>')
+ src_start = c["src_in"] + int(round(c["trim_head"] * c["speed"]))
+ inner: List[str] = []
+ if abs(c["speed"] - 1.0) > 1e-6:
+ # timeMap maps clip-local time to source time; two linear points give a constant speed
+ inner.append(" <timeMap>")
+ inner.append(f' <timept time="0s" value="{_t(src_start, rate)}" interp="linear"/>')
+ inner.append(f' <timept time="{_t(c["visible"], rate)}" '
+ f'value="{_t(src_start + int(round(c["visible"] * c["speed"])), rate)}" interp="linear"/>')
+ inner.append(" </timeMap>")
+ start_attr = "0s"
+ else:
+ start_attr = _t(src_start, rate)
+ local0 = src_start if abs(c["speed"] - 1.0) <= 1e-6 else 0
+ for mk in [m for m in markers if c["record_in"] <= m["at"] < c["record_in"] + c["visible"]]:
+ inner.append(f' <chapter-marker start="{_t(local0 + mk["at"] - c["record_in"], rate)}" '
+ f'duration="{fd}" value="{q(mk["title"])}"/>')
+ if i == 0 and tl["music"]:
+ m = tl["music"]
+ mid = asset(m["src"], m["name"], m["media_frames"], False, True)
+ inner.append(f' <asset-clip ref="{mid}" lane="-1" offset="{_t(local0, rate)}" name="{q(m["name"])}" '
+ f'start="0s" duration="{_t(m["length"], rate)}" audioRole="music"/>')
+ head = (f' <asset-clip ref="{rid}" offset="{_t(c["record_in"], rate)}" name="{q(c["name"])}" '
+ f'start="{start_attr}" duration="{_t(c["visible"], rate)}" format="r1" tcFormat="NDF"')
+ spine.append(head + (">\n" + "\n".join(inner) + "\n </asset-clip>" if inner else "/>"))
+ out = ['<?xml version="1.0" encoding="UTF-8"?>', "<!DOCTYPE fcpxml>", '<fcpxml version="1.10">',
+ " <resources>", *res, " </resources>", " <library>", f' <event name="{q(tl["name"])}">',
+ f' <project name="{q(tl["name"])}">',
+ f' <sequence format="r1" duration="{_t(tl["total"], rate)}" tcStart="0s" tcFormat="NDF">',
+ " <spine>", *spine, " </spine>", " </sequence>", " </project>", " </event>",
+ " </library>", "</fcpxml>"]
+ return "\n".join(out) + "\n"
+
+
+# ---------------------------------------------------------------------------------------- OTIO
+def _rt(frames: int, rate: Fraction) -> Dict[str, Any]:
+ return {"OTIO_SCHEMA": "RationalTime.1", "rate": float(rate), "value": float(frames)}
+
+
+def _range(start: int, dur: int, rate: Fraction) -> Dict[str, Any]:
+ return {"OTIO_SCHEMA": "TimeRange.1", "start_time": _rt(start, rate), "duration": _rt(dur, rate)}
+
+
+def to_otio(tl: Dict[str, Any]) -> str:
+ """OpenTimelineIO JSON (Resolve imports it natively; Premiere/Avid through OTIO's adapters):
+ a video track of clips and SMPTE dissolves, a music track, markers on the stack. Times are in
+ timeline frames; a speed change is a LinearTimeWarp effect over the clip's source range."""
+ rate = tl["rate"]
+ d = tl["transition_frames"]
+ video: List[Dict[str, Any]] = []
+ for i, c in enumerate(tl["clips"]):
+ if i > 0 and d:
+ video.append({"OTIO_SCHEMA": "Transition.1", "name": "Cross Dissolve", "metadata": {},
+ "transition_type": "SMPTE_Dissolve",
+ # OTIO: in_offset is the part before the cut, out_offset the part after
+ "in_offset": _rt(c["trim_head"], rate), "out_offset": _rt(tl["clips"][i - 1]["trim_tail"], rate)})
+ src_start = c["src_in"] + int(round(c["trim_head"] * c["speed"]))
+ clip = {"OTIO_SCHEMA": "Clip.2", "name": c["name"], "metadata": {}, "enabled": True,
+ # OTIO's own convention: source_range starts at the media's in point and lasts the
+ # clip's length on the timeline; a LinearTimeWarp says how fast the media runs
+ # through it (core OTIO does not rescale durations by effects).
+ "source_range": _range(src_start, c["visible"], rate),
+ "effects": [], "markers": [],
+ "media_references": {"DEFAULT_MEDIA": {
+ "OTIO_SCHEMA": "ExternalReference.1", "name": c["name"], "metadata": {},
+ "target_url": _url(c["src"]), "available_range": _range(0, c["media_frames"], rate),
+ "available_image_bounds": None}},
+ "active_media_reference_key": "DEFAULT_MEDIA"}
+ if abs(c["speed"] - 1.0) > 1e-6:
+ clip["effects"].append({"OTIO_SCHEMA": "LinearTimeWarp.1", "name": "speed", "metadata": {},
+ "effect_name": "LinearTimeWarp", "time_scalar": c["speed"]})
+ video.append(clip)
+ tracks = [{"OTIO_SCHEMA": "Track.1", "name": "V1", "kind": "Video", "metadata": {}, "enabled": True,
+ "source_range": None, "effects": [], "markers": [], "children": video}]
+ if tl["music"]:
+ m = tl["music"]
+ tracks.append({"OTIO_SCHEMA": "Track.1", "name": "Music", "kind": "Audio", "metadata": {}, "enabled": True,
+ "source_range": None, "effects": [], "markers": [], "children": [{
+ "OTIO_SCHEMA": "Clip.2", "name": m["name"], "metadata": {}, "enabled": True,
+ "source_range": _range(0, m["length"], rate), "effects": [], "markers": [],
+ "media_references": {"DEFAULT_MEDIA": {
+ "OTIO_SCHEMA": "ExternalReference.1", "name": m["name"], "metadata": {},
+ "target_url": _url(m["src"]), "available_range": _range(0, m["media_frames"], rate),
+ "available_image_bounds": None}},
+ "active_media_reference_key": "DEFAULT_MEDIA"}]})
+ markers = [{"OTIO_SCHEMA": "Marker.2", "name": mk["title"], "metadata": {}, "color": "RED", "comment": "",
+ "marked_range": _range(mk["at"], 0, rate)} for mk in tl["markers"]]
+ doc = {"OTIO_SCHEMA": "Timeline.1", "name": tl["name"], "metadata": {}, "global_start_time": _rt(0, rate),
+ "tracks": {"OTIO_SCHEMA": "Stack.1", "name": "tracks", "metadata": {}, "enabled": True,
+ "source_range": None, "effects": [], "markers": markers, "children": tracks}}
+ return json.dumps(doc, indent=2, ensure_ascii=False) + "\n"
+
+
+WRITERS = {"edl": to_edl, "fcpxml": to_fcpxml, "otio": to_otio}
+
+
+def parses(path: str, fmt: str) -> bool:
+ """The verification step: the written file reads back as what it claims to be."""
+ try:
+ text = Path(path).read_text(encoding="utf-8")
+ if fmt == "fcpxml":
+ import xml.etree.ElementTree as ET
+ return ET.fromstring(text.encode("utf-8")).tag == "fcpxml"
+ if fmt == "otio":
+ return json.loads(text).get("OTIO_SCHEMA") == "Timeline.1"
+ return text.startswith("TITLE:") and any(line[:3].isdigit() for line in text.splitlines())
+ except (OSError, ValueError, SyntaxError):
+ return False
+
+
+def summary(tl: Dict[str, Any], fmt: str) -> Dict[str, Any]:
+ """The part of the timeline a caller reads back in render.py's --json document."""
+ rate = tl["rate"]
+ return {"format": fmt, "rate": f"{rate.numerator}/{rate.denominator}" if rate.denominator != 1 else str(rate.numerator),
+ "duration": round(float(Fraction(tl["total"]) / rate), 3), "frames": tl["total"],
+ "clips": len(tl["clips"]), "transition": tl["transition"],
+ "transition_frames": tl["transition_frames"], "music": bool(tl["music"]),
+ "markers": len(tl["markers"]), "notes": tl["notes"], "not_exported": tl["not_exported"]}
diff --git a/scripts/_contract.py b/scripts/_contract.py
index 41d1199..fa81aee 100644
--- a/scripts/_contract.py
+++ b/scripts/_contract.py
@@ -206,7 +206,7 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
required=FF + ["filter:tile"], optional=[{"capability": "filter:drawtext", "when": "timecode stamps (default; --no-timecode to skip)"},
{"capability": "filter:drawbox", "when": "--safe NAME (the platform's occluded zones)"}, {"capability": "filter:zscale", "when": "HDR source"}, {"capability": "filter:tonemap", "when": "HDR source"}],
video_required=True, audio_only=False, visual=False, verify=[], produces_artifact=True, idempotency="bit_exact", deterministic=True),
- "render": dict(role="execution", inputs=["project.json (clips, transitions, captions, overlays, audio, loudness, export, check)", "media asset plus --template NAME (a shipped delivery template)"], outputs=["final video artifact", "one artifact per destination plus a pack table (--template all)", "work directory of stage outputs (--keep / --work)"],
+ "render": dict(role="execution", inputs=["project.json (clips, transitions, captions, overlays, audio, loudness, export, check)", "media asset plus --template NAME (a shipped delivery template)"], outputs=["final video artifact", "one artifact per destination plus a pack table (--template all)", "work directory of stage outputs (--keep / --work)", "editor timeline (.fcpxml / .edl / .otio) instead of a render (--export-timeline)"],
required=FF, optional=[{"capability": "delegated", "when": "each stage (and each destination of --template) runs cut / join / fit / caption / graphics / overlay / audio / loudness / export / check with their capabilities"}],
video_required=True, audio_only=False, visual=True, verify=["probe", "check", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
"batch": dict(role="execution", inputs=["folder of media", "batch.json recipe (steps or a render project)"], outputs=["one artifact per input file in the recipe's output_dir", "content-hash cache"],
@@ -426,7 +426,10 @@ def output_schema(name: str, meta: Dict[str, Any]) -> Dict[str, Any]:
extra = {"stages": {"type": "array", "items": {"type": "string"}}, "check": {"type": ["object", "null"]},
"plan": {"type": "string", "description": "when the argument was a plan.json (written by <tool> --plan): its path"},
"tool": {"type": "string", "description": "plan execution: the tool the plan ran"},
- "tool_result": {"type": "object", "description": "plan execution: the tool's own --json document"}}
+ "tool_result": {"type": "object", "description": "plan execution: the tool's own --json document"},
+ "timeline": {"type": "object", "description": "--export-timeline: format, rate, duration, frames, clips, transition, "
+ "transition_frames, music, markers, notes, and not_exported (what the project asks for that an "
+ "editor timeline cannot carry)"}}
elif name == "verify":
extra = {"report": {"type": ["string", "null"]}, "files": {"type": "array"}, "failed": {"type": "integer"}, "total": {"type": "integer"}}
elif name == "batch":
diff --git a/scripts/export.py b/scripts/export.py
index c81a680..86b5935 100755
--- a/scripts/export.py
+++ b/scripts/export.py
@@ -148,7 +148,10 @@ def main() -> int:
f"{meta['video'].get('color_transfer') or 'untagged'})",
hint="use --preset youtube for an SDR delivery; there is no way to invent HDR range from an SDR master")
if meta["video"].get("bt2020_or_hdr") and args.preset not in ("prores", "copy", "youtube-hdr"):
- notes.append("source is HDR (%s). This preset outputs SDR BT.709 tags without tone mapping; run color.py --to-sdr first for correct colours." % meta["video"].get("hdr_format"))
+ # 2.0: `hdr` is a real PQ/HLG/DV signal; bt2020_or_hdr also covers BT.2020 SDR, which is
+ # not HDR but still needs converting before BT.709 tags describe it (eval 24 h1)
+ kind = "HDR" if meta["video"].get("hdr") else "wide-gamut SDR, not HDR"
+ notes.append("source is %s (%s). This preset outputs SDR BT.709 tags without converting it; run color.py --to-sdr first for correct colours." % (kind, meta["video"].get("hdr_format")))
info("warning: " + notes[-1])
has_audio = bool(meta.get("audio"))
output = args.output or default_output(args.input, args.preset, p["ext"])
diff --git a/scripts/render.py b/scripts/render.py
index 65b5d2e..a01fcb9 100755
--- a/scripts/render.py
+++ b/scripts/render.py
@@ -64,7 +64,7 @@ from typing import Any, Dict, List, Optional, Sequence
from export import PRESETS, PLATFORM_OF
from _platforms import PLATFORMS, caption_defaults, resolve as resolve_platform
-from _common import STATE, add_common, brand_caption_style, load_brand, apply_common, child_args, die, emit, info, probe, run_tool, place_output, refuse_output_is_input, _check_existing_output, fingerprint, PLAN_VERSION, ffmpeg_version
+from _common import STATE, add_common, brand_caption_style, load_brand, apply_common, child_args, die, emit, info, probe, run_tool, place_output, refuse_output_is_input, _check_existing_output, _check_output_path, fingerprint, PLAN_VERSION, ffmpeg_version
import subprocess
from _contract import CONTRACT_VERSION
from batch import file_key
@@ -718,6 +718,44 @@ def frame_from_preset(frame: Dict[str, Any], export: Dict[str, Any]) -> None:
info(f"frame: {preset['w']}x{preset['h']} from the {export['preset']} export preset (captions and overlays are sized for delivery)")
+def export_timeline(proj: Dict[str, Any], rel, dest: str) -> int:
+ """--export-timeline: the project's cut as an editor timeline, nothing rendered (_common.timeline)."""
+ from _common import timeline as tlmod
+ fmt = tlmod.FORMATS.get(Path(dest).suffix.lower())
+ if not fmt:
+ die(f"--export-timeline {dest}: unknown timeline format", kind="input",
+ hint="name the file .fcpxml, .edl or .otio")
+ paths = [rel(c["src"]) for c in proj.get("clips") or [] if c.get("src")]
+ if (proj.get("audio") or {}).get("music"):
+ paths.append(rel(proj["audio"]["music"]))
+ probes: Dict[str, Dict[str, Any]] = {}
+ for path in paths:
+ if not os.path.exists(path):
+ die(f"timeline source not found: {path}")
+ probes[path] = probe(path) # a timeline needs real durations and rates, dry run or not
+ try:
+ tl = tlmod.build(proj, probes, rel)
+ except tlmod.TimelineError as exc:
+ die(f"--export-timeline: {exc}", kind="input")
+ text = tlmod.WRITERS[fmt](tl)
+ report = tlmod.summary(tl, fmt)
+ _check_output_path(["ffmpeg", dest])
+ _check_existing_output(["ffmpeg", dest])
+ verification: List[Dict[str, Any]] = []
+ if not STATE.dry_run:
+ try:
+ Path(dest).write_text(text, encoding="utf-8")
+ except OSError as exc:
+ die(f"cannot write {dest}: {exc}", kind="output")
+ verification.append({"step": "parse", "ok": tlmod.parses(dest, fmt)})
+ for line in report["not_exported"]:
+ info(f"not exported: {line}")
+ info(("[dry-run] would write " if STATE.dry_run else "wrote ") +
+ f"{dest} ({fmt}, {report['clips']} clips, {report['duration']}s at {report['rate']} fps)")
+ emit(dest, timeline=report, verification=verification)
+ return 0
+
+
def main() -> int:
ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
ap.add_argument("project", nargs="?", help="project.json, or a plan.json written by <tool> --plan")
@@ -732,6 +770,10 @@ def main() -> int:
choices=list(STAGE_ORDER),
help="start at this stage, taking every earlier one from --cache; refuses if "
"one of them is not there")
+ ap.add_argument("--export-timeline", metavar="FILE",
+ help="write the project's cut as an editor timeline instead of rendering it: .fcpxml (Final Cut, "
+ "Resolve), .edl (CMX 3600: Premiere, Resolve, Avid) or .otio (OpenTimelineIO); clips, speed, "
+ "transitions, the music bed and chapter markers carry over, everything else is listed as not exported")
ap.add_argument("--stop-after", choices=["clips", "join", "silence", "fit", "captions", "graphics", "overlays", "audio", "loudness", "export"], help="stop after this stage (for iterating)")
tpl = ap.add_argument_group("delivery templates (one command per destination)")
tpl.add_argument("--template", metavar="NAME", help="render INPUT with a shipped template: " + ", ".join(template_names())
@@ -810,6 +852,9 @@ def main() -> int:
if isinstance(proj.get("chapters"), str) and not os.path.exists(rel(proj["chapters"])):
die(f"chapters file not found: {rel(proj['chapters'])}")
+ if args.export_timeline:
+ return export_timeline(proj, rel, args.export_timeline)
+
clips = proj.get("clips") or []
if not clips:
die("project.clips is empty")
diff --git a/tests/fixtures/mcp_tools.json b/tests/fixtures/mcp_tools.json
index 20777a8..13877b3 100644
--- a/tests/fixtures/mcp_tools.json
+++ b/tests/fixtures/mcp_tools.json
@@ -849,6 +849,7 @@
"chapters",
"cues",
"dry_run",
+ "export_timeline",
"fast",
"fit",
"from_stage",
diff --git a/tests/test_delivery.py b/tests/test_delivery.py
index bbb4523..8faf377 100644
--- a/tests/test_delivery.py
+++ b/tests/test_delivery.py
@@ -77,6 +77,23 @@ class DeliveryTests(MediaFixtures):
self.assertTrue(m["video"]["hdr"], "the source's real HDR tags must survive a stream copy")
self.assertNotEqual(m["video"]["color_space"], "bt709", "copy must never relabel HDR content as bt709")
+ def test_export_warning_names_bt2020_sdr_as_not_hdr(self):
+ """Eval 24 h1: after 2.0 narrowed `hdr` to a real PQ/HLG/DV signal, export.py still warned
+ "source is HDR (BT.2020 SDR)" for a wide-gamut SDR file -- the 1.x wording, contradicting
+ probe. The warning now says which case it is, and still points at color.py --to-sdr."""
+ wide = OUT / "export_bt2020_sdr.mp4"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "testsrc2=size=320x240:rate=30",
+ "-t", "1", "-vf", "format=yuv420p10le", "-c:v", "libx265", "-preset", "ultrafast",
+ "-x265-params", "colorprim=bt2020:transfer=bt709:colormatrix=bt2020nc:log-level=error", "-tag:v", "hvc1", wide)
+ doc = json.loads(script("export.py", wide, "--preset", "youtube", "--fast", "--json",
+ "-o", OUT / "export_bt2020_sdr_yt.mp4").stdout)
+ note = " ".join(doc.get("notes") or [])
+ self.assertIn("wide-gamut SDR, not HDR", note)
+ self.assertIn("color.py --to-sdr", note)
+ doc = json.loads(script("export.py", self.hdr, "--preset", "youtube", "--fast", "--json",
+ "-o", OUT / "export_hdr_yt_note.mp4").stdout)
+ self.assertIn("source is HDR (HDR10/PQ)", " ".join(doc.get("notes") or []))
+
def test_proxy_default_width_and_crf_keeps_audio(self):
out = OUT / "proxy_default.mp4"
script("proxy.py", self.src, "-o", out)
diff --git a/tests/test_orchestration.py b/tests/test_orchestration.py
index 5b034aa..6f5190f 100644
--- a/tests/test_orchestration.py
+++ b/tests/test_orchestration.py
@@ -1623,3 +1623,166 @@ class CommonFacadeTests(unittest.TestCase):
importlib.reload(_common)
self.assertEqual(runner.__file__, before)
self.assertTrue(callable(_common.emit) and callable(_common.probe))
+
+
+class TimelineExportTests(unittest.TestCase):
+ """2.1: render.py --export-timeline writes the project's cut as an editor timeline (EDL,
+ FCPXML, OTIO) instead of rendering it. The arithmetic is the contract: every format must put
+ the same frames on the same timeline positions render.py's own join would, dissolves included,
+ and whatever an editor timeline cannot carry is named in `not_exported`, never dropped."""
+
+ RATE = 30
+
+ @staticmethod
+ def _tl():
+ from _common import timeline
+ return timeline
+
+ def _probes(self, **durations):
+ return {f"/m/{name}": {"duration": dur, "video": {"fps": 30.0, "width": 1280, "height": 720},
+ "audio": {"channels": 2}} for name, dur in durations.items()}
+
+ def test_build_centres_each_dissolve_and_keeps_the_rendered_length(self):
+ """Three clips, a 0.5 s (15-frame, odd) dissolve, one clip at 1.25x: the total is the sum of
+ the clip lengths minus one dissolve per join -- what join.py's xfade renders -- and each
+ dissolve's window starts `trim_head` frames before the cut and ends `trim_tail` after it."""
+ tl_mod = self._tl()
+ proj = {"clips": [{"src": "a.mp4", "in": 1, "out": 5}, {"src": "b.mp4", "in": 2, "out": 7, "speed": 1.25},
+ {"src": "c.mp4"}], "transition": {"type": "fade", "duration": 0.5}}
+ tl = tl_mod.build(proj, self._probes(**{"a.mp4": 8, "b.mp4": 8, "c.mp4": 3}), lambda p: f"/m/{p}")
+ lengths = [c["length"] for c in tl["clips"]]
+ self.assertEqual(lengths, [120, 120, 90])
+ self.assertEqual(tl["transition_frames"], 15)
+ self.assertEqual(tl["total"], sum(lengths) - 15 * 2)
+ a, b, c = tl["clips"]
+ self.assertEqual((a["trim_head"], a["trim_tail"], b["trim_head"], b["trim_tail"], c["trim_head"]), (0, 7, 8, 7, 8))
+ self.assertEqual(b["record_in"], a["visible"])
+ self.assertEqual(c["record_in"], a["visible"] + b["visible"])
+ # b's window: from its visible start minus trim_head, for 15 frames; a's media covers it
+ self.assertEqual(a["visible"] + a["trim_tail"], a["length"])
+
+ def test_build_refuses_what_a_timeline_cannot_hold(self):
+ tl_mod = self._tl()
+ probes = self._probes(**{"a.mp4": 8, "b.mp4": 8})
+ rel = lambda p: f"/m/{p}" # noqa: E731
+ with self.assertRaises(tl_mod.TimelineError):
+ tl_mod.build({"clips": [{"src": "a.mp4", "in": 5, "out": 5}]}, probes, rel)
+ with self.assertRaises(tl_mod.TimelineError): # 0.2 s clip, 0.5 s dissolves on both sides
+ tl_mod.build({"clips": [{"src": "a.mp4"}, {"src": "b.mp4", "in": 0, "out": 0.2}, {"src": "a.mp4"}],
+ "transition": {"duration": 0.5}}, probes, rel)
+ tl = tl_mod.build({"clips": [{"src": "a.mp4"}], "captions": {"text": "c.txt"}, "silence": {},
+ "audio": {"voice": "light"}, "export": {"preset": "reels"}}, probes, rel)
+ joined = " | ".join(tl["not_exported"])
+ for word in ("captions", "export preset", "voice"):
+ self.assertIn(word, joined)
+ self.assertNotIn("silence", joined, "an empty silence block asked for nothing")
+
+ def test_ntsc_rates_are_exact(self):
+ tl_mod = self._tl()
+ from fractions import Fraction
+ self.assertEqual(tl_mod.exact_rate(29.97), Fraction(30000, 1001))
+ self.assertEqual(tl_mod.exact_rate(23.976), Fraction(24000, 1001))
+ self.assertEqual(tl_mod.exact_rate(25.0), Fraction(25))
+
+ @classmethod
+ def setUpClass(cls):
+ if not shutil.which("ffmpeg"):
+ if os.environ.get("CI"):
+ raise AssertionError("ffmpeg not on PATH -- in CI this is a broken install step")
+ raise unittest.SkipTest("ffmpeg not on PATH")
+ d = OUT / "timeline"
+ d.mkdir(parents=True, exist_ok=True)
+ cls.dir = d
+ for name, src, freq in (("a.mp4", "testsrc2", 440), ("b.mp4", "testsrc", 660)):
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", f"{src}=size=640x360:rate=30",
+ "-f", "lavfi", "-i", f"sine=frequency={freq}:sample_rate=48000", "-t", "8", "-c:v", "libx264",
+ "-preset", "ultrafast", "-pix_fmt", "yuv420p", "-c:a", "aac", d / name)
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "sine=frequency=220:sample_rate=48000",
+ "-t", "30", "-c:a", "aac", d / "bed.m4a")
+ cls.project = d / "p.json"
+ cls.project.write_text(json.dumps({
+ "output": "final.mp4",
+ "clips": [{"src": "a.mp4", "in": 1, "out": 5}, {"src": "b.mp4", "in": 2, "out": 7, "speed": 1.25}],
+ "transition": {"type": "fade", "duration": 0.5}, "audio": {"music": "bed.m4a"},
+ "chapters": [{"at": 0, "title": "Intro"}, {"at": 3.5, "title": "Part B"}],
+ "captions": {"text": "cues.txt"}}), encoding="utf-8")
+
+ def _export(self, name, *extra):
+ out = self.dir / name
+ if out.exists():
+ out.unlink()
+ doc = json.loads(script("render.py", self.project, "--export-timeline", out, "--json", *extra).stdout)
+ return out, doc
+
+ def test_every_format_reports_the_same_cut_and_what_it_left_out(self):
+ for name in ("e.edl", "e.fcpxml", "e.otio"):
+ with self.subTest(fmt=name):
+ out, doc = self._export(name)
+ self.assertEqual((doc["status"], doc["verified"]), ("completed", True))
+ self.assertEqual(doc["verification"], [{"step": "exists", "ok": True}, {"step": "parse", "ok": True}])
+ t = doc["timeline"]
+ # a: 4 s = 120 frames; b: 5 s at 1.25x = 120 frames; one 15-frame dissolve
+ self.assertEqual((t["frames"], t["duration"], t["rate"]), (225, 7.5, "30"))
+ self.assertEqual((t["clips"], t["transition_frames"], t["music"], t["markers"]), (2, 15, True, 2))
+ self.assertTrue(any("captions" in x for x in t["not_exported"]))
+ self.assertEqual(doc["commands"], [], "a timeline is written, nothing is encoded")
+
+ def test_edl_events_line_up_with_the_dissolve(self):
+ out, _ = self._export("golden.edl")
+ events = [ln for ln in out.read_text(encoding="utf-8").splitlines() if ln[:3].isdigit()]
+ self.assertEqual(events, [
+ "001 AX B C 00:00:01:00 00:00:04:15 01:00:00:00 01:00:03:15",
+ "002 AX B C 00:00:04:15 00:00:04:15 01:00:03:15 01:00:03:15",
+ "002 AX B D 015 00:00:02:00 00:00:07:00 01:00:03:15 01:00:07:15",
+ "003 AX A2 C 00:00:00:00 00:00:07:15 01:00:00:00 01:00:07:15"])
+ text = out.read_text(encoding="utf-8")
+ self.assertIn("M2 AX 037.5", text, "1.25x at 30 fps is an M2 of 37.5")
+ self.assertIn("* LOC: 01:00:03:15 WHITE Part B", text)
+
+ def test_otio_track_lengths_add_up_without_counting_transitions(self):
+ """OTIO: a track's length is the sum of its clips' source_range durations; transitions
+ overlap them and add nothing. The first version put the speed-scaled source length there
+ and the track came out 253 frames for a 225-frame cut (caught with the reference
+ opentimelineio library, 0.18)."""
+ out, _ = self._export("e2.otio")
+ doc = json.loads(out.read_text(encoding="utf-8"))
+ video, music = doc["tracks"]["children"]
+ clips = [c for c in video["children"] if c["OTIO_SCHEMA"] == "Clip.2"]
+ trans = [c for c in video["children"] if c["OTIO_SCHEMA"] == "Transition.1"]
+ self.assertEqual(sum(c["source_range"]["duration"]["value"] for c in clips), 225)
+ self.assertEqual([(t["in_offset"]["value"], t["out_offset"]["value"]) for t in trans], [(8, 7)])
+ self.assertEqual(clips[1]["effects"][0]["time_scalar"], 1.25)
+ self.assertEqual(music["children"][0]["source_range"]["duration"]["value"], 225)
+ self.assertEqual([m["name"] for m in doc["tracks"]["markers"]], ["Intro", "Part B"])
+
+ def test_fcpxml_spine_matches_the_cut(self):
+ import xml.etree.ElementTree as ET
+ out, _ = self._export("e2.fcpxml")
+ root = ET.fromstring(out.read_bytes())
+ self.assertEqual(root.get("version"), "1.10")
+ seq = root.find("./library/event/project/sequence")
+ self.assertEqual(seq.get("duration"), "15/2s")
+ spine = list(seq.find("spine"))
+ self.assertEqual([e.tag for e in spine], ["asset-clip", "transition", "asset-clip"])
+ self.assertEqual((spine[1].get("offset"), spine[1].get("duration")), ("7/2s", "1/2s"))
+ self.assertEqual(spine[2].get("offset"), "113/30s")
+ self.assertIsNotNone(spine[2].find("timeMap"), "the 1.25x clip is retimed")
+ self.assertEqual(len(spine[0].findall("chapter-marker")), 2)
+ self.assertEqual(spine[0].find("asset-clip").get("lane"), "-1", "the music bed is a connected clip below")
+ for asset in root.findall("./resources/asset"):
+ self.assertTrue(asset.find("media-rep").get("src").startswith("file://"))
+
+ def test_existing_file_dry_run_and_unknown_format(self):
+ out, _ = self._export("guard.edl")
+ before = out.read_bytes()
+ proc = sh(sys.executable, SCRIPTS / "render.py", self.project, "--export-timeline", out, "--json", expect_fail=True)
+ self.assertEqual(json.loads(proc.stdout)["error"]["kind"], "input", "2.0: an existing file is refused")
+ self.assertEqual(out.read_bytes(), before)
+ dry = self.dir / "dry.otio"
+ if dry.exists():
+ dry.unlink()
+ doc = json.loads(script("render.py", self.project, "--export-timeline", dry, "--dry-run", "--json").stdout)
+ self.assertEqual((doc["dry_run"], doc["verified"]), (True, False))
+ self.assertFalse(dry.exists(), "a dry run writes nothing")
+ proc = sh(sys.executable, SCRIPTS / "render.py", self.project, "--export-timeline", self.dir / "x.aaf", "--json", expect_fail=True)
+ self.assertEqual(json.loads(proc.stdout)["error"]["kind"], "input")