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.
Python agent-skillsai-agentsaudio-processingcaptionsclaude-codecodexcoding-agentcursorffmpegloudness-normalizationmcpmcp-servermodel-context-protocolpythonsubtitlestranscodingvideovideo-editingvideo-processingwhisper
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.jsonindex 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.mdindex 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.0What 1.10.0 announced for 2.0 (`contract --json`'s `deprecated` list): four changes made, onediff --git a/README.md b/README.mdindex 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.mdindex 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.pyindex 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, afterdiff --git a/docs/contract.md b/docs/contract.mdindex 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 theToolSpec 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.mdindex 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```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```bashpython3 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.mdindex 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.mdindex 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.jsonindex 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.mdindex 92cb80a..1a83b1c 100644--- a/references/scripts.md+++ b/references/scripts.md@@ -569,7 +569,21 @@ render.py --init project.json # starter filerender.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 runrender.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 ofhead+tail), commands, output, verify}` and runs nothing. `render.py cut.json`diff --git a/scripts/_common/timeline.py b/scripts/_common/timeline.pynew file mode 100644index 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), {'"': """}) # 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.pyindex 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.pyindex 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.pyindex 65b5d2e..a01fcb9 100755--- a/scripts/render.py+++ b/scripts/render.py@@ -64,7 +64,7 @@ from typing import Any, Dict, List, Optional, Sequencefrom export import PRESETS, PLATFORM_OFfrom _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_versionimport subprocessfrom _contract import CONTRACT_VERSIONfrom 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.jsonindex 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.pyindex 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.pyindex 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")