ffmpeg-skill 2.0.0 → 2.1.0

package/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 |

package/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` |

package/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:

package/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",

package/references/gotchas.md

@@ -16,7 +16,10 @@ flattened. Decide with the user: keep HDR (fine for YouTube/phones) or run
 deliverables. Since 2.0 `hdr: true` (and its 1.9 twin `hdr_signal`) is the narrow
 fact — a real PQ / HLG / Dolby Vision transfer; `bt2020_or_hdr` also counts a
 wide-gamut SDR file (1.x's `hdr`), and `hdr_format` names that in-between case
-(`BT.2020 SDR`). `export.py` platform presets are SDR and warn on HDR input.
+(`BT.2020 SDR`). "Not HDR" is not "ready for a BT.709 deliverable": a BT.2020 SDR file
+still carries wide-gamut primaries, so an SDR-only client or platform expecting BT.709 needs
+`color.py --to-sdr` first -- `export.py` only retags BT.709, it does not convert (eval 24 h1).
+`export.py` platform presets are SDR and warn on HDR input.
 iPhone `.mov` files also carry timecode/metadata tracks; scripts map only the
 first audio track, so extra tracks are dropped on re-encode. Keep ProRes masters
 at source colour: `export.py --preset prores` does not retag.

package/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`

package/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"]}

package/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":

package/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"])

package/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")