ffmpeg-skill 2.2.1 → 2.2.3

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.2.1`) | any release |
+| `skill.version` | the npm / package.json version (`2.2.3`) | 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.2.1", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "2.2.3", "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"},
@@ -492,6 +492,12 @@ Per-tool keys added in 1.18.0, all additive:
 | `sources` | `sync.py` | `[{path, offset_s, confidence, drift_ppm}]`, one entry per SOURCE. Present for every run, including the original single-SOURCE shape (where it mirrors the top-level `second`/`offset_seconds`/`confidence` additively). With 2+ SOURCEs it is the *only* per-source shape: there is no top-level `second`/`offset_seconds` because there is no single pair to put there |
 | `switch_mode`, `min_shot` | `multicam.py --switch energy` | `"energy"` and the `--min-shot` value used (default 1.5s), alongside the existing `cuts` (`[[start, end, camera], ...]`) which already carries the camera index for `--edl`'s companion cut list |
 
+Per-tool keys added after 2.2.2, all additive:
+
+| key | tool | what it holds |
+|---|---|---|
+| `sdr_path`, `notes` | `color.py --to-sdr` | `sdr_path` is `"tonemap"` for PQ / HLG / Dolby Vision input (and `--force` on an untagged file) or `"gamut"` for BT.2020 primaries on an SDR transfer, which is converted to BT.709 without a tone map (`--tonemap`/`--peak`/`--desat` do not apply); `notes` says which path was taken and why |
+
 `check.py` also gains an informational `subtitles` row on **every** platform:
 `PASS` when every soft subtitle stream carries a language tag, `WARN` when one
 does not (or when there are none). Like `channels` and `chapters` it is never

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "2.2.1",
+  "version": "2.2.3",
   "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/scripts.md

@@ -563,11 +563,21 @@ before anything runs: missing, empty (0 bytes) or unreadable as media. By defaul
 are named in one refusal (`kind: input`, `problems: [{index, path, reason}]`, nothing encoded);
 `--on-missing skip` joins the usable ones and reports the rest under `skipped` (always present,
 `[]` when nothing was). A list with no entries is refused as such, and a skip that leaves fewer
-than two inputs is refused rather than "joining" one file.
+than two inputs is refused rather than "joining" one file. Under `--dry-run` an input that does
+not exist yet is an earlier step's output, with either `--on-missing`: it stays in the plan and
+is named under `pending: [{index, path}]` and in `notes` (never `skipped`). Its extension stands
+in for its streams (any audio extension the skill reads, `.aiff` and `.caf` included: no
+picture), so a pending `.mp4` next to measured audio is refused as the mix a real run would
+refuse; `expected_duration` is null while any input is pending, and `notes` names the planned
+frame, rate or xfade offsets that rest on a pending input's unmeasured placeholder.
 Normalises every clip to one frame size, fps, `yuv420p`, 48 kHz and one
 channel layout (the widest clip's -- a 5.1 clip keeps 5.1 -- or `--channels`;
 silent track generated for clips without audio), then chains `xfade` +
-`acrossfade`. Output length = sum of clips − transition × (n−1). Clips must be
+`acrossfade`. With a transition each clip has one length for picture and sound
+-- the video stream's, or the audio's when it runs more than a frame longer --
+and the shorter stream is padded (silence / last frame held), so every clip's
+sound stays with its picture. Output length = sum of clip lengths −
+transition × (n−1); `verified` checks the output's video-stream length against it. Clips must be
 longer than 2 × the transition. Use `--transition none` for a plain cut.
 A subtitle/data track in the source is not carried into the retimed/concatenated
 output; the result says so with `dropped_non_av_streams: true`.
@@ -586,13 +596,20 @@ Premiere, Resolve, Avid) or `.otio` (OpenTimelineIO JSON: Resolve natively, othe
 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.
+track; inline `chapters` are markers. Times take the render's own grammar (`"0:05"`,
+`hh:mm:ss:ff` at the source's fps), and the sequence is the project's `frame` sized by
+fit.py's rule (`{aspect 16:9, width 1920}` is 1920x1080; an aspect alone takes the export
+preset's size when the preset has that aspect; an aspect fit.py refuses, such as `16/9`, is
+refused unless the project's own `fit.aspect` replaces it in the render). A clip of another
+aspect gets its spatial conform in FCPXML (`adjust-conform`: `fill` for `frame.fit: crop`,
+`fit` for pad); EDL and OTIO cannot state one. Everything else in the project -- captions,
+graphics, overlays, the silence cut, fit, a reframe the format cannot state (and `blur`'s
+background), 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/__init__.py

@@ -69,10 +69,10 @@ from _common.emit import (
 from _common.probe import (
     analyze_levels, _aspect_string, _bit_depth, decode_pcm_mono, detect_scenes, detect_silences, fingerprint,
     _fraction, keyframes_near, SCORE_RE, SIL_RE, decode_gray_frames,
-    measured_level_dbfs, MEDIA_EXT, _output_failed, probe, rms_envelope, _to_float, _to_int, verify_output
+    measured_level_dbfs, AUDIO_MEDIA_EXT, MEDIA_EXT, _output_failed, probe, rms_envelope, _to_float, _to_int, verify_output
 )
 from _common.decision import (
-    aac_args, add_pad_fill_args, audio_codec_for, AUDIO_CODECS, brand_caption_style, BRAND_DEFAULTS,
+    aac_args, add_pad_fill_args, aspect_ratio, audio_codec_for, AUDIO_CODECS, brand_caption_style, BRAND_DEFAULTS,
     description_block, _evidence_rank, fmt_chapter_time, propose_chapters,
     frame_flow, label_shot_flow, MOTION_GRID, MOTION_SEARCH, MOTION_STATIC_PX, MOTION_PAN_SPREAD,
     filler_spans, FILLER_WORDS, FILLER_AMBIGUOUS, FILLER_DISCOURSE_MARKERS, FILLER_MAX_WORD,
@@ -82,7 +82,7 @@ from _common.decision import (
     BEAT_Z_FLOOR, BEAT_Z_SPAN,
     _onset_strength, _pick_onsets, _autocorrelation_peak, _grid_score,
     brand_states_font, cfr_args, concat_list_line, db_to_linear, default_output, encoder_args, escape_filter_path,
-    fmt_secs, fmt_smpte_time, fmt_srt_time, is_audio_output, load_brand, MissingFpsError, pad_filters, parse_time,
+    fmt_secs, fmt_smpte_time, fmt_srt_time, frame_size, is_audio_output, load_brand, MissingFpsError, pad_filters, parse_time,
     signed_time_arg, SVT_PRESET, time_arg, video_args, x264_args, _x264_raw
 )
 from _common.asr import (
@@ -201,7 +201,7 @@ __all__ = [
     "fonts_dir_covers_script", "_fraction", "has_emoji", "info", "INSTALL_HINTS", "install_signal_handlers",
     "is_audio_output", "_is_emoji_base", "_is_emoji_char", "_is_ffmpeg", "_is_mark", "_KEYCAP", "_KEYCAP_BASES",
     "keyframes_near", "LANGUAGE_NAMES", "LATIN_EM", "LEADING_VOWELS", "_libass_color_probe", "_limit_for",
-    "load_brand", "measured_level_dbfs", "MEDIA_EXT", "MissingFpsError", "needs_shaping", "NO_SPACE_SCRIPTS",
+    "load_brand", "measured_level_dbfs", "AUDIO_MEDIA_EXT", "MEDIA_EXT", "MissingFpsError", "needs_shaping", "NO_SPACE_SCRIPTS",
     "_odd_dimension_retry", "_on_signal", "_output_failed", "_OutputLock", "pad_filters", "parse_time", "_pid_dead",
     "place_output", "_plan_at_exit", "_plan_inputs", "_PLAN_STRIP", "PLAN_VERSION", "PREFERRED_FAMILIES",
     "print_json", "probe", "PROBE_TIMEOUT", "_progress_line", "read_text_or_die", "refuse_output_is_input",

package/scripts/_common/decision.py

@@ -9,9 +9,11 @@ from __future__ import annotations
 import json
 import math
 import os
+import re
 import argparse
+from fractions import Fraction
 from pathlib import Path
-from typing import Any, Dict, List, Optional, Sequence
+from typing import Any, Dict, List, Optional, Sequence, Tuple
 from _common.color import bt709_tag_args, _sdr_bt709
 from _common.emit import die
 from _common.runner import CODECS, STATE, ffmpeg_encoders
@@ -47,6 +49,60 @@ def add_pad_fill_args(parser: "argparse.ArgumentParser") -> None:
     parser.add_argument("--pad-blur", type=int, default=20, help="blur radius in pixels for --pad-fill blur (default 20)")
 
 
+def aspect_ratio(value: Any) -> Optional[Fraction]:
+    """An aspect written W:H as an exact ratio, or None. fit.py --aspect and --export-timeline's
+    sequence frame read an aspect through this one function, so the export refuses `16/9` and
+    `2.39:1` where the render hands them to fit.py, which refuses them too (the timeline once
+    took them and wrote a sequence for a project whose render then failed in fit.py). Each side
+    is read with int(), as fit.py read it in 2.2.1, so a patch release refuses nothing fit.py
+    took: `+16:9` and `1_6:9` still parse, and `0:9` is a zero ratio, which frame_size() treats
+    as no aspect (2.2.1 kept the source frame). render.py's frame_from_preset() keeps 2.2.1's
+    looser match: it only picks the export preset's size."""
+    parts = str(value).split(":")
+    if len(parts) != 2:
+        return None
+    try:
+        return Fraction(int(parts[0]), int(parts[1]))
+    except (ValueError, ZeroDivisionError):
+        return None
+
+
+def _even(n: float) -> int:
+    v = int(round(n))
+    return v if v % 2 == 0 else v + 1
+
+
+def frame_size(ratio: Optional[Fraction], width: Optional[int], height: Optional[int],
+               src_w: int, src_h: int) -> Tuple[int, int]:
+    """The frame fit.py sizes for --aspect `ratio` (None: the source's own) and --width/--height,
+    from a src_w x src_h picture -- and so the sequence frame render.py --export-timeline writes
+    for the same project frame. Both sides given are used directly; one side takes the other from
+    the aspect. With neither, the canvas takes the new aspect without exceeding the source's
+    resolution in either dimension: a narrower/taller target than the source (e.g. 9:16 from a
+    16:9 source) must be bounded by the source's HEIGHT, not its width -- bounding by width there
+    multiplies the height by src_ratio/ratio (a 1920x1080 source asked for 9:16 used to come out
+    1920x3414, a ~3.16x upscale in both fit=pad and fit=crop, entirely unrequested). Every side is
+    rounded to even."""
+    src_ratio = Fraction(src_w, src_h) if src_h else None
+    if ratio is None:
+        ratio = src_ratio
+    if width and height:
+        return _even(width), _even(height)
+    if width:
+        out_w = _even(width)
+        return out_w, (_even(out_w / ratio) if ratio else width)
+    if height:
+        out_h = _even(height)
+        return (_even(out_h * ratio) if ratio else height), out_h
+    if ratio and src_ratio:
+        if ratio <= src_ratio:
+            out_h = _even(src_h)
+            return _even(out_h * ratio), out_h
+        out_w = _even(src_w)
+        return out_w, _even(out_w / ratio)
+    return _even(src_w), _even(src_h)
+
+
 # x264 preset names mapped onto SVT-AV1's 0-13 speed scale (lower = slower / better)
 SVT_PRESET = {"ultrafast": 12, "superfast": 11, "veryfast": 10, "faster": 9, "fast": 8, "medium": 6, "slow": 4, "slower": 3, "veryslow": 2, "placebo": 1}
 

package/scripts/_common/probe.py

@@ -73,8 +73,11 @@ def rms_envelope(samples: Sequence[float], step: int, *, full_blocks_only: bool
     return env
 
 
+# the audio members of MEDIA_EXT: every audio file this skill reads, a wider set than the audio
+# outputs it writes (AUDIO_CODECS / is_audio_output() -- no .aif, .aiff, .caf or .wma there)
+AUDIO_MEDIA_EXT = {".wav", ".flac", ".mp3", ".m4a", ".aac", ".ogg", ".opus", ".aif", ".aiff", ".caf", ".wma"}
 MEDIA_EXT = {".mp4", ".mov", ".mkv", ".webm", ".m4v", ".avi", ".ts", ".mts", ".m2ts", ".mxf", ".3gp", ".wmv", ".gif",
-             ".wav", ".flac", ".mp3", ".m4a", ".aac", ".ogg", ".opus", ".aif", ".aiff", ".caf", ".wma", ".png", ".jpg", ".jpeg", ".webp"}
+             ".png", ".jpg", ".jpeg", ".webp"} | AUDIO_MEDIA_EXT
 
 
 def decode_gray_frames(path: str, fps: float, width: int, height: int, *, start: float = 0.0,
@@ -280,6 +283,8 @@ def probe(path: str, role: str = "input") -> Dict[str, Any]:
             "color_range": video.get("color_range"),
             "rotation": rotation,
             "nb_frames": _to_int(video.get("nb_frames")),
+            # the stream's own length (a container's also counts audio priming and a longer track)
+            "duration": _to_float(video.get("duration")),
             "bitrate": _to_int(video.get("bit_rate")),
         }
     if audio:
@@ -289,6 +294,7 @@ def probe(path: str, role: str = "input") -> Dict[str, Any]:
             "channel_layout": audio.get("channel_layout"),
             "sample_rate": _to_int(audio.get("sample_rate")),
             "bitrate": _to_int(audio.get("bit_rate")),
+            "duration": _to_float(audio.get("duration")),
         }
         # every audio stream in file order: index n here is `-map 0:a:n` (audio.py --audio-stream n)
         out["audio_streams"] = [{

package/scripts/_common/timeline.py

@@ -13,18 +13,23 @@ either side of the new cut: the same frames blend over the same span, and the to
 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.
+transition between them, a music bed on its own audio track, and chapters as markers, on a
+sequence of the project's frame (sized by the rule fit.py renders it with). FCPXML also states
+how a clip of another aspect fills that frame (`adjust-conform`); EDL and OTIO cannot.
+Everything else in the project -- captions, graphics, overlays, the silence cut, fit/crop, a
+reframe the format cannot state, audio processing, loudness, the export preset -- is listed
+under `not_exported`, never silently dropped.
 """
 import json
+import math
 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
 
+from _common.decision import MissingFpsError, aspect_ratio, frame_size, parse_time
+
 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),
@@ -43,6 +48,9 @@ _NOT_EXPORTED = {
     "brand": "brand styles",
     "snap": "beat snapping (the timeline uses the project's in/out as written, before any snap)",
 }
+# frame.fit -> the FCPXML adjust-conform type that fills the sequence the same way. blur has no
+# conform of its own: the picture is fitted whole, and its blurred background is not exported.
+_CONFORM = {"pad": "fit", "crop": "fill", "blur": "fit"}
 _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",
@@ -63,6 +71,43 @@ def exact_rate(fps: float) -> Fraction:
     return frac
 
 
+def _number(value: Any, what: str) -> float:
+    """A numeric project value (a rate, a size, a speed, a transition length) as a float, or a
+    TimelineError naming it -- never float()'s traceback."""
+    try:
+        number = float(value)
+    except (TypeError, ValueError):
+        number = math.nan
+    if not math.isfinite(number):
+        raise TimelineError(f"{what}: {value!r} is not a number")
+    return number
+
+
+def _seconds(value: Any, what: str, fps: Optional[float]) -> float:
+    """A project time read with the grammar render.py's own stages read it (time_arg()): seconds,
+    mm:ss, hh:mm:ss.ms, or hh:mm:ss:ff at `fps` or its own @fps. A value it refuses is a
+    TimelineError, so `--json` gets a `kind: input` document, not a traceback and empty stdout."""
+    try:
+        seconds = parse_time(str(value), fps)
+    except MissingFpsError as exc:
+        raise TimelineError(f"{what}: {exc}")
+    except ValueError as exc:
+        raise TimelineError(f"{what}: {exc} (use seconds, mm:ss, hh:mm:ss.ms, or hh:mm:ss:ff at the "
+                            "source's fps or with an explicit @fps suffix)")
+    if not math.isfinite(seconds):
+        raise TimelineError(f"{what}: {value!r} is not a time")
+    return seconds
+
+
+def _picture(meta: Dict[str, Any]) -> Optional[Tuple[int, int]]:
+    """A source's displayed width x height (rotation metadata swaps them, as fit.py reads it)."""
+    video = meta.get("video") or {}
+    w, h = int(video.get("width") or 0), int(video.get("height") or 0)
+    if not (w and h):
+        return None
+    return (h, w) if video.get("rotation") in (90, -90, 270, -270) else (w, h)
+
+
 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`.
 
@@ -71,44 +116,76 @@ def build(proj: Dict[str, Any], probes: Dict[str, Dict[str, Any]], rel) -> Dict[
     clips_in = proj.get("clips") or []
     if not clips_in:
         raise TimelineError("project.clips is empty")
+    for i, c in enumerate(clips_in):
+        if not isinstance(c, dict) or not c.get("src"):
+            raise TimelineError(f"clips[{i}]: no src")
     frame = proj.get("frame") or {}
     first = probes[rel(clips_in[0]["src"])]
-    fps = frame.get("fps") or (first.get("video") or {}).get("fps")
+    frame_fps = _number(frame["fps"], "frame.fps") if frame.get("fps") else None
+    fps = frame_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)
+    # The sequence is the project's frame sized by fit.py's rule (render.py has already filled an
+    # aspect-only frame from the export preset), so {aspect 16:9, width 1920} is 1920x1080
+    # whatever the source's height -- the size the render's fit stage delivers. No frame at all
+    # is the first clip's own picture, which is what the render keeps.
+    aspect = frame.get("aspect")
+    ratio = aspect_ratio(aspect) if aspect else None
+    if aspect and ratio is None:
+        raise TimelineError(f"frame.aspect {aspect!r}: use W:H with whole numbers, like 16:9 (fit.py refuses it too)")
+    want_w, want_h = (int(_number(frame[k], f"frame.{k}")) if frame.get(k) else None for k in ("width", "height"))
+    if (want_w or 0) < 0 or (want_h or 0) < 0:
+        raise TimelineError(f"frame width/height must be positive, got {frame.get('width')!r} x {frame.get('height')!r}")
+    src_w, src_h = _picture(first) or (1920, 1080)
+    if ratio is None and not want_w and not want_h:
+        width, height = src_w, src_h
+    else:
+        width, height = frame_size(ratio, want_w, want_h, src_w, src_h)
+    fit_mode = str(frame.get("fit") or "pad")
+    if fit_mode not in _CONFORM:
+        raise TimelineError(f"frame.fit {frame.get('fit')!r}: use pad, crop or blur (fit.py's --fit)")
 
     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)))
+    d_frames = 0 if t_type == "none" else fr(_number(trans.get("duration", 0.5), "transition.duration"))
     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]] = []
+    reframed: List[str] = []
     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
+        # in/out are on the source's own clock, as cut.py reads them: hh:mm:ss:ff at the
+        # source's fps, never frame.fps. A clip with no picture has no fps, and cut.py takes no
+        # other, so its hh:mm:ss:ff needs an @fps suffix here as in the render.
+        clip_fps = (meta.get("video") or {}).get("fps")
+        start = _seconds(c["in"], f"clips[{i}].in", clip_fps) if c.get("in") is not None else 0.0
+        if start < 0:
+            raise TimelineError(f"clips[{i}].in must not be negative, got {c['in']!r}")
+        end = _seconds(c["out"], f"clips[{i}].out", clip_fps) 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)
+        speed = _number(c.get("speed") or 1.0, f"clips[{i}].speed")
         if not speed > 0:
             raise TimelineError(f"clip {i}: speed must be positive, got {c.get('speed')!r}")
+        picture = _picture(meta)
+        reframe = bool(picture and abs(Fraction(*picture) - Fraction(width, height)) > Fraction(1, 100))
+        if reframe:
+            reframed.append(os.path.basename(src))
         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")})
+                      "picture": picture, "fps": clip_fps, "reframed": reframe})
 
     # 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
@@ -140,22 +217,44 @@ def build(proj: Dict[str, Any], probes: Dict[str, Dict[str, Any]], rel) -> Dict[
     markers: List[Dict[str, Any]] = []
     chapters = proj.get("chapters")
     if isinstance(chapters, list):
-        for ch in chapters:
-            at = fr(float(ch.get("at", 0)))
+        for j, ch in enumerate(chapters):
+            # read as render.py's chapters stage reads it (metadata.py): a chapter list carries
+            # no fps, so hh:mm:ss:ff needs its @fps there and here alike
+            at = fr(_seconds(ch.get("at", 0), f"chapters[{j}].at", None))
             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}]")
 
+    # A clip of another aspect than the sequence is a reframe: whether the file can state it
+    # depends on the format, so summary() adds it to not_exported per format (_reframe_note).
     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,
+            "fit": fit_mode, "reframed": list(dict.fromkeys(reframed)),
             "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}
 
 
+def _reframe_note(tl: Dict[str, Any], fmt: str) -> List[str]:
+    """What `not_exported` says about the clips whose picture has another aspect than the
+    sequence. FCPXML states each one's spatial conform (adjust-conform: fit for frame.fit pad,
+    fill for crop), so there only blur's blurred background is missing; EDL and OTIO have no
+    field for a conform at all, so the editor's own default decides and the caller is told."""
+    if not tl["reframed"]:
+        return []
+    names = ", ".join(tl["reframed"])
+    if fmt == "fcpxml":
+        if tl["fit"] != "blur":
+            return []
+        return [f"frame.fit blur's blurred background behind {names}: the FCPXML fits the picture into "
+                f"{tl['width']}x{tl['height']} (adjust-conform fit), leaving bars where the render blurs"]
+    return [f"the reframe to {tl['width']}x{tl['height']} (frame.fit {tl['fit']}) of {names}: "
+            "set the clips' spatial conform in the editor (fit = pad, fill = crop)"]
+
+
 # ---------------------------------------------------------------------------------------- EDL
 def _tc(frames: int, fps_int: int) -> str:
     h, rem = divmod(frames, fps_int * 3600)
@@ -234,21 +333,40 @@ def _url(path: str) -> str:
 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."""
+    of the first clip, chapters as chapter-markers. Speed is a linear timeMap on the clip. The
+    sequence has its own format (r1); each video asset has its source's, and a clip of another
+    aspect states its spatial conform (adjust-conform) for frame.fit."""
     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:
+    res: List[str] = []
+    ids: Dict[Any, str] = {}  # a format's (width, height, frameDuration) or an asset's path -> its id
+
+    def fmt(width: int, height: int, frame_duration: str) -> str:
+        key = (width, height, frame_duration)
+        if key not in ids:
+            ids[key] = f"r{len(ids) + 1}"
+            res.append(f'    <format id="{ids[key]}" name="FFVideoFormat{height}p" frameDuration="{frame_duration}" '
+                       f'width="{width}" height="{height}"/>')
+        return ids[key]
+
+    seq_fmt = fmt(tl["width"], tl["height"], fd)  # r1: the sequence's frame
+
+    def clip_fmt(c: Dict[str, Any]) -> str:
+        # An asset describes its own media, not the sequence: with every asset on r1, a 320x180
+        # file under a 1080x1920 frame claimed to be 1080x1920, and its conform had nothing to do.
+        if not (c["has_video"] and c["picture"]):
+            return seq_fmt
+        return fmt(c["picture"][0], c["picture"][1], _t(1, exact_rate(float(c["fps"]))) if c["fps"] else fd)
+
+    def asset(path: str, name: str, frames: int, has_video: bool, has_audio: bool, format_id: str = "") -> str:
         if path in ids:
             return ids[path]
-        rid = f"r{len(ids) + 2}"
+        rid = f"r{len(ids) + 1}"
         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' format="{format_id}"' if has_video else "") + ' audioSources="1" audioChannels="2">\n'
                    f'      <media-rep kind="original-media" src="{q(_url(path))}"/>\n    </asset>')
         return rid
 
@@ -256,7 +374,8 @@ def to_fcpxml(tl: Dict[str, Any]) -> 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"])
+        cid = clip_fmt(c)
+        rid = asset(c["src"], c["name"], c["media_frames"], c["has_video"], c["has_audio"], cid)
         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)}"/>')
@@ -273,21 +392,28 @@ def to_fcpxml(tl: Dict[str, Any]) -> str:
         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"])}"/>')
+        # the FCPXML 1.10 DTD's order inside an asset-clip: timeMap, then the adjust-* elements
+        # (adjust-conform), then anchored items (the music bed), then markers. Anything out of
+        # that order does not validate, and Final Cut validates what it imports against that DTD.
+        if c["reframed"]:
+            # the DTD reads a missing adjust-conform as fit, so crop has to say fill; fit is
+            # written too, so the file states the project's choice rather than a default
+            inner.append(f'          <adjust-conform type="{_CONFORM[tl["fit"]]}"/>')
         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"/>')
+        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"])}"/>')
         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"')
+                f'start="{start_attr}" duration="{_t(c["visible"], rate)}" format="{cid}" 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">',
+           f'        <sequence format="{seq_fmt}" duration="{_t(tl["total"], rate)}" tcStart="0s" tcFormat="NDF">',
            "      <spine>", *spine, "      </spine>", "        </sequence>", "      </project>", "    </event>",
            "  </library>", "</fcpxml>"]
     return "\n".join(out) + "\n"
@@ -376,4 +502,5 @@ def summary(tl: Dict[str, Any], fmt: str) -> Dict[str, Any]:
             "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"]}
+            "markers": len(tl["markers"]), "notes": tl["notes"],
+            "not_exported": tl["not_exported"] + _reframe_note(tl, fmt)}

package/scripts/_contract.py

@@ -443,6 +443,11 @@ def output_schema(name: str, meta: Dict[str, Any]) -> Dict[str, Any]:
         extra = {"measured": {"type": "object", "description": "the loudnorm measurement of the input (input_i, input_tp, input_lra, input_thresh, target_offset); with --measure-only it is the whole result"},
                  "targets": {"type": "object", "description": "the requested lufs / tp / lra"},
                  "result": {"type": "object", "description": "the written file measured again (input_i, input_tp, input_lra, ...), plus tp_ceiling_used, audio_bitrate_used and encodes"}}
+    elif name == "color":
+        extra = {"dropped_non_av_streams": {"type": "boolean"},
+                 "sdr_path": {"enum": ["tonemap", "gamut"], "description": "--to-sdr only: tonemap for PQ / HLG / Dolby Vision (and --force on an untagged file); gamut for BT.2020 primaries on an SDR transfer, converted to BT.709 without a tone map"},
+                 "notes": {"type": "array", "items": {"type": "string"}, "description": "--to-sdr only: which path was taken and why"},
+                 "measurements": {"type": "object", "description": "--correct only: signalstats levels of input and output"}}
     elif name == "cut":
         extra = {"expected_duration": {"type": "number", "description": "seconds requested"},
                  "duration_error_ms": {"type": ["number", "null"], "description": "written minus requested, measured by ffprobe (null under --dry-run)"},
@@ -451,10 +456,13 @@ def output_schema(name: str, meta: Dict[str, Any]) -> Dict[str, Any]:
                  "reencoded": {"type": "boolean"},
                  "lossless_alternative": {"type": ["string", "null"], "description": "when a lossless cut re-encoded because of the keyframe snap: the --start that would stream-copy instead, and how far it is from the request"}}
     elif name == "join":
-        extra = {"mode": {"enum": ["video", "audio"]}, "clips": {"type": "integer"}, "transition": {"type": "string"}, "expected_duration": {"type": "number"},
+        extra = {"mode": {"enum": ["video", "audio"]}, "clips": {"type": "integer"}, "transition": {"type": "string"},
+                 "expected_duration": {"type": ["number", "null"], "description": "clip lengths minus the transitions; null under --dry-run while an input is pending (its length is unknown)"},
                  "sample_rate": {"type": "integer", "description": "audio mode only"}, "channels": {"type": "integer", "description": "audio mode only"},
                  "video": {"type": "boolean", "description": "false in audio mode: the output has no video stream"},
-                 "skipped": {"type": "array", "description": "inputs --on-missing skip left out: [{index, path, reason}] ([] when none were)"}}
+                 "skipped": {"type": "array", "description": "inputs --on-missing skip left out: [{index, path, reason}] ([] when none were)"},
+                 "pending": {"type": "array", "description": "--dry-run: inputs that do not exist yet, planned on as an earlier step's output and never also under skipped: [{index, path}] ([] otherwise)"},
+                 "notes": {"type": "array", "items": {"type": "string"}, "description": "--dry-run with pending inputs: which ones, what a real run does if one is still missing (including a skip that leaves fewer than two inputs), whether the mode came from the extensions, and which planned numbers are the unmeasured stub's placeholders (a pending first clip's frame and rate, xfade offsets after a pending clip)"}}
     elif name == "audio":
         extra = {"video": {"type": "boolean", "description": "true when the input's video stream was copied; false for an audio output extension (extraction)"},
                  "audio_stream": {"type": "integer", "description": "which input audio stream was processed (--audio-stream)"},

package/scripts/color.py

@@ -169,12 +169,36 @@ def hdr_to_sdr_chain(meta: dict, tonemap: str, peak: float, desat: float) -> str
     return ",".join(chain)
 
 
+def bt2020_sdr_to_bt709_chain(meta: dict) -> str:
+    """Gamut conversion only, for BT.2020 primaries on an SDR transfer (probe: `bt2020_or_hdr`
+    true, `hdr_signal` false). Such a file is already display-referred SDR: linearising it with
+    its own transfer, mapping the primaries to BT.709 and re-applying the BT.709 transfer keeps
+    white at white and grey at grey. The tone map the HDR chain adds would treat 100 % SDR white
+    as a fraction of a 1000-nit peak and darken the picture (white Y 235 -> 151, grey 126 -> 90)."""
+    v = meta["video"]
+    trc = v.get("color_transfer") or "bt709"
+    space = v.get("color_space") or "bt2020nc"
+    return ",".join([
+        f"zscale=tin={trc}:pin=bt2020:min={space}:rin={v.get('color_range') or 'tv'}:t=linear",
+        "format=gbrpf32le",
+        "zscale=p=bt709",
+        "zscale=t=bt709:m=bt709:r=tv",
+        "format=yuv420p",
+    ])
+
+
+def is_bt2020_sdr(v: dict) -> bool:
+    """BT.2020 primaries on a non-HDR transfer and no Dolby Vision: gamut-only --to-sdr."""
+    return bool(v.get("bt2020_or_hdr")) and not v.get("hdr_signal") and not v.get("dolby_vision") \
+        and v.get("color_transfer") not in ("smpte2084", "arib-std-b67")
+
+
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("input")
     ap.add_argument("-o", "--output", help="output file (default: <name>_sdr / _lut / _retag)")
     mode = ap.add_mutually_exclusive_group(required=True)
-    mode.add_argument("--to-sdr", action="store_true", help="tone-map HDR (PQ/HLG/BT.2020) to SDR BT.709")
+    mode.add_argument("--to-sdr", action="store_true", help="convert to SDR BT.709: tone-map HDR (PQ/HLG/Dolby Vision); BT.2020 primaries on an SDR transfer get a gamut conversion only, no tone map")
     mode.add_argument("--lut", help=".cube LUT to apply (3D)")
     mode.add_argument("--retag", choices=["bt709", "bt2020-pq", "bt2020-hlg", "bt601"], help="rewrite colour tags only (no re-encode)")
     mode.add_argument("--strip-dovi", action="store_true", help="remove the Dolby Vision RPU (profile 8.4 iPhone clips) so players use the plain HLG/HDR10 base layer; stream copy")
@@ -183,7 +207,7 @@ def main() -> int:
     ap.add_argument("--peak", type=float, default=1000.0, help="source peak brightness in nits used for PQ (default 1000)")
     ap.add_argument("--desat", type=float, default=0.0, help="tonemap desaturation strength (default 0)")
     ap.add_argument("--lut-strength", type=float, default=1.0, help="blend LUT result with the original, 0..1 (default 1)")
-    ap.add_argument("--force", action="store_true", help="run --to-sdr even if the file is not tagged as HDR (treat as PQ)")
+    ap.add_argument("--force", action="store_true", help="run --to-sdr even if the file is tagged neither HDR nor BT.2020 (tone-mapped as PQ; a BT.2020 SDR file never needs it)")
     ap.add_argument("--exposure", type=float, default=CORRECTION["exposure"][0], help="--correct: exposure in stops, -3..3 (default 0)")
     ap.add_argument("--contrast", type=float, default=CORRECTION["contrast"][0], help="--correct: contrast, 0..2, 1=unchanged (default 1)")
     ap.add_argument("--saturation", type=float, default=CORRECTION["saturation"][0], help="--correct: saturation, 0..2, 1=unchanged (default 1)")
@@ -278,10 +302,21 @@ def main() -> int:
         return 0
 
     measurements = None
+    sdr_extra: dict = {}
     if args.to_sdr:
         if not v.get("bt2020_or_hdr") and not args.force:
             die(f"{args.input} is not tagged as HDR (transfer={v.get('color_transfer')}, primaries={v.get('color_primaries')}). Use --force to tone-map anyway.")
-        vf = hdr_to_sdr_chain(meta, args.tonemap, args.peak, args.desat)
+        if is_bt2020_sdr(v):
+            vf = bt2020_sdr_to_bt709_chain(meta)
+            sdr_path = "gamut"
+            note = (f"BT.2020 primaries on an SDR transfer ({v.get('color_transfer')}): converted the gamut to BT.709 "
+                    f"without a tone map (--tonemap/--peak/--desat do not apply)")
+        else:
+            vf = hdr_to_sdr_chain(meta, args.tonemap, args.peak, args.desat)
+            sdr_path = "tonemap"
+            note = f"tone-mapped {v.get('hdr_format') or 'untagged input as PQ (--force)'} to SDR BT.709 with {args.tonemap}"
+        info(f"note: {note}")
+        sdr_extra = {"sdr_path": sdr_path, "notes": [note]}
         output = args.output or default_output(args.input, "sdr")
         tag = "sdr"
     elif args.correct:
@@ -323,7 +358,7 @@ def main() -> int:
     r = probe(output, role="output")
     info(f"wrote {output} ({fmt_secs(r['duration'])}, {r['video']['width']}x{r['video']['height']}, "
          f"{r['video']['color_transfer']}/{r['video']['color_primaries']}, {tag})")
-    extra = {"dropped_non_av_streams": dropped_streams}
+    extra = {"dropped_non_av_streams": dropped_streams, **sdr_extra}
     if measurements is not None:
         measurements["output"] = analyze_levels(output)
         extra["measurements"] = measurements

package/scripts/fit.py

@@ -39,20 +39,16 @@ import sys
 from fractions import Fraction
 from typing import List
 
-from _common import video_args, STATE, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, ffmpeg_base, info, parse_time, probe, run, run_keeping_subtitles, validate_color, x264_args, pad_filters, add_pad_fill_args, X264_PRESETS, time_arg, fmt_secs
+from _common import video_args, STATE, add_common, apply_common, emit, aac_args, aspect_ratio, cfr_args, default_output, die, ffmpeg_base, info, parse_time, probe, run, run_keeping_subtitles, validate_color, x264_args, pad_filters, add_pad_fill_args, X264_PRESETS, time_arg, fmt_secs, frame_size
 BLUR_DARKEN = 0.15  # how much --fit blur dims the blurred background copy (eq brightness)
-ASPECT_PRESETS = {"16:9": Fraction(16, 9), "9:16": Fraction(9, 16), "1:1": Fraction(1, 1), "4:5": Fraction(4, 5), "4:3": Fraction(4, 3), "21:9": Fraction(21, 9)}
 
 
 def parse_aspect(value: str) -> Fraction:
-    if value in ASPECT_PRESETS:
-        return ASPECT_PRESETS[value]
-    try:
-        w, h = value.split(":")
-        return Fraction(int(w), int(h))
-    except (ValueError, ZeroDivisionError):
+    # the one aspect grammar, shared with render.py's frame and --export-timeline's sequence
+    ratio = aspect_ratio(value)
+    if ratio is None:
         die(f"bad aspect '{value}', use W:H like 16:9")
-    return Fraction(1)  # unreachable
+    return ratio
 
 
 def atempo_chain(factor: float) -> str:
@@ -69,11 +65,6 @@ def atempo_chain(factor: float) -> str:
     return ",".join(parts)
 
 
-def even(n: float) -> int:
-    v = int(round(n))
-    return v if v % 2 == 0 else v + 1
-
-
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("input")
@@ -192,31 +183,8 @@ def main() -> int:
 
     # ---- aspect / size
     if args.aspect or args.width or args.height:
-        src_ratio = Fraction(sw, sh) if sh else None
-        ratio = parse_aspect(args.aspect) if args.aspect else src_ratio
-        if args.width and args.height:
-            out_w, out_h = even(args.width), even(args.height)
-        elif args.width:
-            out_w = even(args.width)
-            out_h = even(out_w / ratio) if ratio else args.width
-        elif args.height:
-            out_h = even(args.height)
-            out_w = even(out_h * ratio) if ratio else args.height
-        elif ratio and src_ratio:
-            # No explicit --width/--height: size the canvas to the new aspect without exceeding
-            # the source's own resolution in either dimension. A narrower/taller target than the
-            # source (e.g. 9:16 from a 16:9 source) must be bounded by the source's HEIGHT, not
-            # its width -- bounding by width there multiplies the height by src_ratio/ratio (a
-            # 1920x1080 source asked for 9:16 used to come out 1920x3414, a ~3.16x upscale in
-            # both fit=pad and fit=crop, entirely unrequested).
-            if ratio <= src_ratio:
-                out_h = even(sh)
-                out_w = even(out_h * ratio)
-            else:
-                out_w = even(sw)
-                out_h = even(out_w / ratio)
-        else:
-            out_w, out_h = even(sw), even(sh)
+        # the one sizing rule, shared with render.py --export-timeline's sequence frame
+        out_w, out_h = frame_size(parse_aspect(args.aspect) if args.aspect else None, args.width, args.height, sw, sh)
         if args.fit == "crop":
             vf.append(f"scale={out_w}:{out_h}:force_original_aspect_ratio=increase")
             vf.append(f"crop={out_w}:{out_h}:(in_w-out_w)*{args.crop_x:g}:(in_h-out_h)*{args.crop_y:g}")

package/scripts/join.py

@@ -24,19 +24,62 @@ Examples:
 Every input is checked before anything is joined: a missing, empty or unreadable segment is
 refused with every problem named at once (kind input), never discovered one run at a time.
 --on-missing skip joins the usable segments instead and lists the others under `skipped`.
+Under --dry-run a segment that does not exist yet is an earlier step's output: it is planned
+on and named under `pending` (never `skipped`), whichever --on-missing was given, and its
+extension stands in for what it will hold (an audio extension: no picture).
 """
 import argparse
 import os
 import sys
-from typing import Any, Dict, List
+from typing import Any, Dict, List, Optional, Tuple
 
-from _common import STATE, video_args, aac_args, add_common, apply_common, audio_codec_for, default_output, die, emit, ffmpeg_base, info, is_audio_output, probe, require_tool, run, validate_color, X264_PRESETS, fmt_secs
+from _common import STATE, AUDIO_MEDIA_EXT, video_args, aac_args, add_common, apply_common, audio_codec_for, default_output, die, dry_run_input_pending, emit, ffmpeg_base, info, is_audio_output, probe, require_tool, run, validate_color, X264_PRESETS, fmt_secs
 
 TRANSITIONS = ["fade", "dissolve", "wipeleft", "wiperight", "wipeup", "wipedown", "slideleft", "slideright",
                "circleopen", "circleclose", "fadeblack", "fadewhite", "smoothleft", "smoothright", "radial", "none"]
 LAYOUTS = {1: "mono", 2: "stereo", 6: "5.1", 8: "7.1"}
 # inputs --on-missing skip dropped, reported in the success document (empty when nothing was)
 STATE_SKIPPED: List[Dict[str, Any]] = []
+# --dry-run: inputs that do not exist yet, planned on as an earlier step's output
+STATE_PENDING: List[Dict[str, Any]] = []
+STATE_NOTES: List[str] = []
+
+
+def reported() -> Dict[str, Any]:
+    """The input bookkeeping both success documents carry: `skipped` is what the join left out,
+    `pending` what a dry run planned on without it existing; `notes` says the same in words."""
+    extra: Dict[str, Any] = {"skipped": list(STATE_SKIPPED), "pending": list(STATE_PENDING)}
+    if STATE_NOTES:
+        extra["notes"] = list(STATE_NOTES)
+    return extra
+
+
+def unpending_length(durs: List[float], d: float) -> Optional[float]:
+    """The joined length the clip durations add up to, or None while an input is pending: its
+    dry-run stub says 0 s, which would count the clip as nothing and still subtract a transition
+    for it (a negative length when nothing exists yet)."""
+    if STATE_PENDING:
+        return None
+    return round(sum(durs) - d * (len(durs) - 1), 3)
+
+
+def clip_length(meta: Dict[str, Any], fps: float) -> float:
+    """The one length a clip holds in a crossfaded join, for its picture and its sound alike: the
+    video stream's, or the audio stream's when the sound runs more than a frame past the picture
+    (narration is never cut; an AAC tail adds no frame). The container duration (audio priming,
+    a longer track) is only the fallback when a stream length is unknown (a pending input)."""
+    v = (meta.get("video") or {}).get("duration")
+    a = (meta.get("audio") or {}).get("duration")
+    if not v:
+        return meta.get("duration") or 0.0
+    if a and fps and a > v + 1.0 / fps:
+        return a
+    return v
+
+
+def expected_text(expected: Optional[float]) -> str:
+    """unpending_length() as the stderr summary line puts it."""
+    return f"expected ~{expected:.3f}s" if expected is not None else "expected length unknown until the pending inputs exist"
 
 
 def join_audio(args: argparse.Namespace, metas: List[dict]) -> int:
@@ -47,8 +90,11 @@ def join_audio(args: argparse.Namespace, metas: List[dict]) -> int:
     for p, dur in zip(args.inputs, durs):
         if d and dur <= d * 2 and not STATE.dry_run:
             die(f"{p} is only {dur:.2f}s, too short for a {d:.2f}s crossfade; shorten --duration")
-    rates = [m["audio"].get("sample_rate") or 48000 for m in metas]
-    chans = [m["audio"].get("channels") or 2 for m in metas]
+    # a pending input's probe is the dry-run stub (rate and layout unmeasured): plan from the
+    # clips that exist, and fall back to 48 kHz stereo only when none does
+    known = [m for m in metas if not m.get("dry_run")] or metas
+    rates = [m["audio"].get("sample_rate") or 48000 for m in known]
+    chans = [m["audio"].get("channels") or 2 for m in known]
     rate = args.sample_rate or rates[0]
     channels = args.channels or max(chans)
     layout = LAYOUTS.get(channels)
@@ -76,7 +122,7 @@ def join_audio(args: argparse.Namespace, metas: List[dict]) -> int:
             prev = out
     cmd += ["-filter_complex", ";".join(parts), "-map", "[aout]", "-vn"] + audio_codec_for(output) + [output]
     run(cmd)
-    expected = sum(durs) - d * (n - 1)
+    expected = unpending_length(durs, d)
     r = probe(output, role="output")
     a = r.get("audio") or {}
     if not STATE.dry_run:
@@ -84,9 +130,9 @@ def join_audio(args: argparse.Namespace, metas: List[dict]) -> int:
             die(f"{output} unexpectedly contains a video stream")
         if a.get("sample_rate") != rate or a.get("channels") != channels:
             die(f"{output} is {a.get('sample_rate')} Hz {a.get('channels')} ch, expected {rate} Hz {channels} ch")
-    info(f"wrote {output} ({fmt_secs(r['duration'])}, expected ~{expected:.3f}s, audio {a.get('codec')} {channels}ch {rate}Hz, {n} clips, "
+    info(f"wrote {output} ({fmt_secs(r['duration'])}, {expected_text(expected)}, audio {a.get('codec')} {channels}ch {rate}Hz, {n} clips, "
          + ("crossfade" if d else "butt join") + ")")
-    emit(output, mode="audio", skipped=list(STATE_SKIPPED), clips=n, transition=args.transition if d else "none", expected_duration=round(expected, 3),
+    emit(output, mode="audio", **reported(), clips=n, transition=args.transition if d else "none", expected_duration=expected,
          sample_rate=rate, channels=channels, video=False)
     return 0
 
@@ -118,17 +164,20 @@ def read_list(path: str) -> List[str]:
     return entries
 
 
-def preflight(paths: List[str]) -> List[Dict[str, Any]]:
+def preflight(paths: List[str]) -> Tuple[List[Dict[str, Any]], List[Dict[str, Any]]]:
     """Every problem with every input, found before anything runs: missing, empty (0 bytes,
     the usual trace of a TTS or download step that failed after creating its file), or not
     readable as media. One ffprobe per file; nothing is decoded. Under --dry-run a file that
-    does not exist yet is not a problem: in a planned pipeline it is an earlier step's output."""
+    does not exist yet is not a problem but pending (the second list, with a note): in a
+    planned pipeline it is an earlier step's output, and the plan keeps it."""
     ffprobe = require_tool("ffprobe")
     problems: List[Dict[str, Any]] = []
+    pending: List[Dict[str, Any]] = []
     for i, p in enumerate(paths):
+        if dry_run_input_pending(p):
+            pending.append({"index": i, "path": p})
+            continue
         if not os.path.exists(p):
-            if STATE.dry_run:
-                continue  # a dry-run pipeline plans on outputs earlier steps have not written yet
             problems.append({"index": i, "path": p, "reason": "missing"})
             continue
         if os.path.isdir(p):
@@ -143,7 +192,7 @@ def preflight(paths: List[str]) -> List[Dict[str, Any]]:
         if proc.returncode != 0 or not kinds & {"audio", "video"}:
             first = ((proc.stderr or "").strip().splitlines() or ["no audio or video stream"])[-1]
             problems.append({"index": i, "path": p, "reason": f"unreadable: {first}"})
-    return problems
+    return problems, pending
 
 
 def main() -> int:
@@ -180,7 +229,7 @@ def main() -> int:
     if not args.inputs:
         die("give at least two clips (or --list FILE)")
     skipped: List[Dict[str, Any]] = []
-    problems = preflight(args.inputs)
+    problems, pending = preflight(args.inputs)
     if problems and args.on_missing == "fail":
         listing = "; ".join(f"#{p['index'] + 1} {p['path']}: {p['reason']}" for p in problems)
         die(f"{len(problems)} of {len(args.inputs)} inputs cannot be joined: {listing}",
@@ -192,21 +241,53 @@ def main() -> int:
         for p in problems:
             info(f"skipping #{p['index'] + 1} {p['path']}: {p['reason']}")
     STATE_SKIPPED[:] = skipped
+    STATE_PENDING[:] = pending
+    if pending:
+        # a dry run cannot know whether the file will be there: it plans on it, and says what a
+        # real run does if it still is not (the same --on-missing rule as any missing input --
+        # including the refusal when skipping would leave fewer than two inputs)
+        left = len(args.inputs) - len(pending)
+        if args.on_missing == "fail":
+            then = "refuses the join if one is still missing"
+        elif left >= 2:
+            then = "skips one that is still missing"
+        else:
+            then = (f"skips one that is still missing and refuses the join if that leaves fewer than two inputs "
+                    f"(only {left} exist{'s' if left == 1 else ''} now)")
+        STATE_NOTES.append(f"{len(pending)} of {len(args.inputs) + len(skipped)} inputs do not exist yet and were planned on "
+                           "as an earlier step's output: " + ", ".join(f"#{p['index'] + 1} {p['path']}" for p in pending)
+                           + f"; a real run {then}")
     if len(args.inputs) < 2:
         die("give at least two clips" if not skipped else
             f"only {len(args.inputs)} usable input(s) left after skipping {len(skipped)}; nothing to join",
             skipped=skipped)
     validate_color(args.pad_color, "--pad-color")
     metas = [probe(p) for p in args.inputs]
-    if all(not m.get("video") for m in metas):
+    # A pending input's probe is the dry-run stub, whose (0x0) video stream says nothing about the
+    # file an earlier step will write. Its extension stands in: a step names its output for what
+    # it holds, so an audio extension (.wav, .m4a, .aiff, ... -- every audio file this skill
+    # reads, not only the ones it writes) is taken for a file without a picture and any other for
+    # one with a picture. Measured and pending inputs then meet the same rules a real run
+    # applies: all without a picture is an audio join, a mix is refused.
+    pictured = [(os.path.splitext(p)[1].lower() not in AUDIO_MEDIA_EXT) if m.get("dry_run") else bool(m.get("video"))
+                for p, m in zip(args.inputs, metas)]
+    if all(m.get("dry_run") for m in metas):
+        STATE_NOTES.append(f"no input exists yet: {'a video' if any(pictured) else 'an audio'} join was planned from the file extensions")
+    if not any(pictured):
         for p, m in zip(args.inputs, metas):
             if not m.get("audio"):
                 die(f"{p} has neither a video nor an audio stream")
         return join_audio(args, metas)
-    for p, m in zip(args.inputs, metas):
-        if not m.get("video"):
-            others = [q for q, mm in zip(args.inputs, metas) if mm.get("video")]
-            die(f"{p} has no video stream" + (f" while {others[0]} has one; join audio with audio or give every clip a picture" if others else ""))
+    for p, m, pic in zip(args.inputs, metas, pictured):
+        if not pic:
+            # name an input measured to have a picture first; a pending one only as expected to
+            measured = [q for q, mm in zip(args.inputs, metas) if mm.get("video") and not mm.get("dry_run")]
+            planned = [q for q, mm, pc in zip(args.inputs, metas, pictured) if pc and mm.get("dry_run")]
+            other = (f"{measured[0]} has one" if measured else
+                     f"{planned[0]}, which does not exist yet, is expected to have one (its extension is not an audio one)" if planned else "")
+            die((f"{p} does not exist yet, and its audio extension says it will have no video stream" if m.get("dry_run")
+                 else f"{p} has no video stream")
+                + (f" while {other}; join audio with audio or give every clip a picture" if other else ""))
     first = metas[0]["video"]
     fw, fh = first["width"], first["height"]
     if first.get("rotation") in (90, -90, 270, -270):
@@ -226,7 +307,10 @@ def main() -> int:
     w, h = w - (w % 2), h - (h % 2)
     durs = [m.get("duration") or 0.0 for m in metas]
     d = args.duration if args.transition != "none" else 0.0
-    for p, dur in zip(args.inputs, durs):
+    # a crossfaded join gives each clip one length for both streams, so the offsets that place
+    # every picture also place its sound; the plain cut (concat) keeps the streams paired itself
+    lens = [clip_length(m, fps) for m in metas] if d else durs
+    for p, dur in zip(args.inputs, lens):
         if d and dur <= d * 2 and not STATE.dry_run:
             die(f"{p} is only {dur:.2f}s, too short for a {d:.2f}s transition; shorten --duration")
 
@@ -263,8 +347,9 @@ def main() -> int:
     hdr_meta = next((m for m in metas if (m.get("video") or {}).get("bt2020_or_hdr")), None)
     pixfmt = "yuv420p10le" if hdr_meta else "yuv420p"
     # the audio-only join keeps the widest layout; the video join used to force stereo and
-    # silently dropped the centre/LFE of 5.1 material
-    chans = [(m.get("audio") or {}).get("channels") or 2 for m in metas]
+    # silently dropped the centre/LFE of 5.1 material. A pending input's stub has no measured
+    # layout: plan from the inputs that exist, as join_audio() does.
+    chans = [(m.get("audio") or {}).get("channels") or 2 for m in ([m for m in metas if not m.get("dry_run")] or metas)]
     channels = args.channels or max(chans)
     layout = LAYOUTS.get(channels)
     if layout is None:
@@ -279,24 +364,54 @@ def main() -> int:
         chain = "".join(f"[v{i}][a{i}]" for i in range(n))
         parts.append(f"{chain}concat=n={n}:v=1:a=1[vout][aout]")
     else:
-        vprev, aprev = "v0", "a0"
+        # pad the shorter stream to the clip's length: the audio with silence, the picture by
+        # holding its last frame, then cut both there -- each xfade and acrossfade then starts
+        # at the same clip boundary instead of the audio chain drifting by every clip's gap
+        for i in range(n):
+            vlen = (metas[i].get("video") or {}).get("duration") or lens[i]
+            hold = f"tpad=stop_mode=clone:stop_duration={lens[i] - vlen:.3f}," if lens[i] > vlen else ""
+            parts.append(f"[v{i}]{hold}trim=duration={lens[i]:.3f}[vp{i}]")
+            parts.append(f"[a{i}]apad=whole_dur={lens[i]:.3f},atrim=duration={lens[i]:.3f}[ap{i}]")
+        vprev, aprev = "vp0", "ap0"
         offset = 0.0
         for i in range(1, n):
-            offset += durs[i - 1] - d
+            offset += lens[i - 1] - d
             vout = f"vx{i}" if i < n - 1 else "vout"
             aout = f"ax{i}" if i < n - 1 else "aout"
-            parts.append(f"[{vprev}][v{i}]xfade=transition={args.transition}:duration={d:g}:offset={offset:.3f}[{vout}]")
-            parts.append(f"[{aprev}][a{i}]acrossfade=d={d:g}:c1=tri:c2=tri[{aout}]")
+            parts.append(f"[{vprev}][vp{i}]xfade=transition={args.transition}:duration={d:g}:offset={offset:.3f}[{vout}]")
+            parts.append(f"[{aprev}][ap{i}]acrossfade=d={d:g}:c1=tri:c2=tri[{aout}]")
             vprev, aprev = vout, aout
 
+    # A pending input's stub is unmeasured (0x0, 0 fps, 0 s -- #77 keeps it honest rather than
+    # plausible), and the planned command is built on it: say which numbers are placeholders.
+    if metas[0].get("dry_run") and not (args.width and args.height and args.fps):
+        STATE_NOTES.append(f"the first input is pending, so the planned frame and rate ({w}x{h} @ {fps:g}fps) are "
+                           "placeholders: a real run takes them from that file")
+    if d and any(m.get("dry_run") for m in metas[:-1]):
+        STATE_NOTES.append("the planned xfade offsets count each pending input as 0 s long: a real run offsets "
+                           "by its measured length")
     output = args.output or default_output(args.inputs[0], "joined", "mp4")
     cmd += ["-filter_complex", ";".join(parts), "-map", "[vout]", "-map", "[aout]"]
+    if d:
+        # the fps filter already made the picture constant-rate and xfade places every frame: FFmpeg
+        # 5.1's default cfr output mode still duplicated the last one to meet the AAC tail (a 51-frame
+        # dissolve came out 52), which newer builds no longer do -- pass the frames through as built
+        cmd += ["-fps_mode", "passthrough"]
     cmd += video_args(hdr_meta or metas[0], args.crf, args.preset) + aac_args() + [output]
     run(cmd)
-    expected = sum(durs) - d * (n - 1)
+    expected = unpending_length(lens, d)
     r = probe(output, role="output")
-    info(f"wrote {output} ({fmt_secs(r['duration'])}, expected ~{expected:.3f}s, {w}x{h} @ {fps:g}fps, {n} clips, {args.transition})")
-    emit(output, mode="video", skipped=list(STATE_SKIPPED), clips=n, transition=args.transition, expected_duration=round(expected, 3),
+    # the picture is what the offsets place: measure the video stream, not the container (whose
+    # length also counts the AAC tail), against the length the clips add up to
+    measured = (r.get("video") or {}).get("duration") or r.get("duration")
+    verification = []
+    if expected is not None and measured is not None and not STATE.dry_run:
+        tol = max(1.5 / fps, 0.05)
+        verification.append({"step": "duration", "ok": abs(measured - expected) <= tol,
+                             "measured": round(measured, 3), "expected": expected, "tolerance": round(tol, 3)})
+    info(f"wrote {output} ({fmt_secs(measured)}, {expected_text(expected)}, {w}x{h} @ {fps:g}fps, {n} clips, {args.transition})")
+    emit(output, mode="video", **reported(), clips=n, transition=args.transition, expected_duration=expected,
+         verification=verification,
          dropped_non_av_streams=any(m.get("subtitle_streams") or m.get("data_streams") for m in metas))
     return 0
 

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, _check_output_path, fingerprint, PLAN_VERSION, ffmpeg_version
+from _common import STATE, add_common, aspect_ratio, 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
@@ -394,7 +394,8 @@ def render_pack(names: List[str], args) -> int:
 
 
 def check_keys(obj: Any, schema: str, label: str) -> None:
-    """Refuse an unrecognised key, naming the object, the key and the nearest valid one."""
+    """Refuse an unrecognised key, naming the object, the key and the nearest valid one. A value
+    that is not an object is require_object()'s to refuse, and only where the run reads it."""
     if not isinstance(obj, dict):
         return
     valid = OBJECT_KEYS[schema]
@@ -406,25 +407,76 @@ def check_keys(obj: Any, schema: str, label: str) -> None:
             else f" (valid keys: {', '.join(sorted(valid))})"))
 
 
-def validate_project(proj: Dict[str, Any]) -> None:
+def require_object(obj: Any, label: str) -> None:
+    """Refuse a value that is not an object where the run reads it with .get(): "export": "reels"
+    in a render, a string frame, a clip written as a bare path. 2.2.1 died there with a traceback
+    and nothing on stdout under --json. null, false and {} still ask for nothing."""
+    if obj and not isinstance(obj, dict):
+        die(f"{label}: must be an object {{...}}, got {type(obj).__name__} {obj!r:.60}")
+
+
+# the stage that first reads each section; --stop-after before it means the run never reads it
+READ_AT = {"transition": "join", "silence": "silence", "fit": "fit", "captions": "captions",
+           "graphics": "graphics", "overlays": "overlays", "loudness": "loudness", "export": "export",
+           "check": "check"}
+_READ_ORDER = ["clips", "join", "silence", "fit", "captions", "graphics", "overlays", "audio", "loudness", "export", "check"]
+
+
+def _reaches(stage: str, stop_after: Optional[str]) -> bool:
+    return not stop_after or _READ_ORDER.index(stage) <= _READ_ORDER.index(stop_after)
+
+
+def validate_project(proj: Dict[str, Any], timeline: bool = False, stop_after: Optional[str] = None) -> None:
+    """Every project error the run would hit, before the first ffmpeg call. A value that is not
+    an object is refused only where this run reads it (require_object()): a full render reads
+    every stage's section, a transition only between two or more clips and a clip's snap only
+    on a clip it cuts; --export-timeline (`timeline`) reads the clips, frame, audio and a
+    transition between clips, and only names the other sections in not_exported. 2.2.1 rendered
+    a single clip with "transition": "none" and exported "captions": "subs.srt", reading neither,
+    and a patch release does not refuse them."""
     check_keys(proj, "project", "project")
+    clips = proj.get("clips")
+    # the join (or the timeline's dissolves) reads the transition; an audiogram render joins nothing
+    several = isinstance(clips, list) and len(clips) > 1 and (timeline or not proj.get("audiogram"))
+    read = {"frame", "audio"} | ({"transition"} if several else set())
+    if not timeline:
+        read |= {"silence", "audiogram", "captions", "loudness", "fit", "export", "check", "snap"}
+        # --stop-after ends the run before later stages read their sections: 2.2.1 completed a
+        # `--stop-after fit` preview of a project with "captions": "subs.srt", never reading it
+        read = {n for n in read if n not in READ_AT or _reaches(READ_AT[n], stop_after)}
     for name in ("frame", "transition", "silence", "audiogram", "captions", "audio", "loudness", "fit", "export", "check", "snap"):
+        if name in read:
+            require_object(proj.get(name), name)
         check_keys(proj.get(name), name, name)
     check_keys((proj.get("audio") or {}).get("stems"), "audio.stems", "audio.stems")
     if isinstance(proj.get("chapters"), list):
         # Every other project error is raised here, before the first ffmpeg call; a chapter typo
         # found inside the last stage costs a whole render and leaves an unchaptered file behind.
         for i, item in enumerate(proj["chapters"]):
-            check_keys(item, "chapters[]", f"chapters[{i}]")
+            if isinstance(item, dict):
+                check_keys(item, "chapters[]", f"chapters[{i}]")
             if not isinstance(item, dict) or item.get("at") is None or not str(item.get("title") or "").strip():
                 die(f'chapters[{i}]: needs {{"at": TIME, "title": STR}}')
     for name in ("clips", "graphics", "overlays"):
         items = proj.get(name)
-        if isinstance(items, list):
-            for i, item in enumerate(items):
-                check_keys(item, f"{name}[]", f"{name}[{i}]")
-                if name == "clips" and isinstance(item, dict) and item.get("snap") is not None:
-                    check_keys(item["snap"], "snap", f"clips[{i}].snap")
+        if name == "clips" or (not timeline and _reaches(READ_AT[name], stop_after)):  # the export reads only the clips
+            if items and not isinstance(items, list):
+                die(f"{name}: must be a list of objects [{{...}}], got {type(items).__name__} {items!r:.60}")
+            for i, item in enumerate(items or []):
+                if not isinstance(item, dict):
+                    die(f"{name}[{i}]: must be an object {{...}}, got {type(item).__name__} {item!r:.60}")
+        for i, item in enumerate(items if isinstance(items, list) else []):
+            check_keys(item, f"{name}[]", f"{name}[{i}]")
+            if name != "clips":
+                continue
+            # every clip stage starts from rel(c["src"]): without one it was a KeyError traceback
+            if not item.get("src"):
+                die(f"clips[{i}]: no src")
+            if item.get("snap") is not None:
+                # the render reads a clip's snap only on a clip it cuts (in/out), the export never
+                if not timeline and (item.get("in") is not None or item.get("out") is not None):
+                    require_object(item["snap"], f"clips[{i}].snap")
+                check_keys(item["snap"], "snap", f"clips[{i}].snap")
 
 
 _LAST_DOC: Dict[str, Any] = {}   # the JSON document the most recent sh() child printed
@@ -703,7 +755,11 @@ def frame_from_preset(frame: Dict[str, Any], export: Dict[str, Any]) -> None:
     """Fill frame.width/height from the export preset when the project gave only an aspect.
     Eval 7 (j08 twice, e01 by hand): "frame": {"aspect": "9:16"} with a reels export fitted a
     1280x720 source to 406x720, captions were burned at that size, and export.py upscaled them
-    soft. A preset that names a delivery frame of the same aspect is that frame."""
+    soft. A preset that names a delivery frame of the same aspect is that frame.
+    The match is 2.2.1's, looser than aspect_ratio(): `16/9` and `1.78:1` still take a 16:9
+    preset's size. A render that hands such a frame.aspect to fit.py fails there, as in 2.2.1;
+    one whose own fit.aspect replaces it, or that stops before fit, is sized by this match, and
+    a patch release does not change a render 2.2.1 completed."""
     if not frame.get("aspect") or frame.get("width") or frame.get("height"):
         return
     preset = PRESETS.get(str(export.get("preset") or ""), {})
@@ -733,8 +789,20 @@ def export_timeline(proj: Dict[str, Any], rel, dest: str) -> int:
         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
+    # the sequence frame is the one the render would deliver: an aspect-only frame takes its size
+    # from the export preset exactly as the render's own frame does. An export that is not an
+    # object names no preset here: 2.2.1's export never read it, and validate_project() refuses
+    # it only in the render, which reads it.
+    frame = dict(proj.get("frame") or {})
+    export = proj.get("export")
+    frame_from_preset(frame, export if isinstance(export, dict) else {})
+    fit = proj.get("fit")
+    if isinstance(fit, dict) and fit.get("aspect") and frame.get("aspect") and aspect_ratio(frame["aspect"]) is None:
+        # the render hands fit.py the fit object's own aspect, never this one (only the preset
+        # match above reads it), and completes: the sequence is the frame's size without it
+        del frame["aspect"]
     try:
-        tl = tlmod.build(proj, probes, rel)
+        tl = tlmod.build(dict(proj, frame=frame), probes, rel)
     except tlmod.TimelineError as exc:
         die(f"--export-timeline: {exc}", kind="input")
     text = tlmod.WRITERS[fmt](tl)
@@ -834,7 +902,7 @@ def main() -> int:
         if "plan_version" in proj:
             return execute_plan(proj, os.path.abspath(args.project))
         base = Path(args.project).resolve().parent
-    validate_project(proj)
+    validate_project(proj, timeline=bool(args.export_timeline), stop_after=args.stop_after)
     if args.write_project:
         # Only the filled project: the point is to edit it before rendering, so nothing runs.
         try:
@@ -1059,9 +1127,21 @@ def main() -> int:
         fit.setdefault("aspect", frame["aspect"])
     if frame.get("fit"):
         fit.setdefault("fit", frame["fit"])
-    if frame.get("width") and len(parts) == 1:
+    # Several clips were joined by join.py: into frame.width x frame.height when the frame gives
+    # both, else at the FIRST clip's aspect. A frame of an aspect and ONE side then reached fit.py
+    # as the aspect alone, which fit.py bounds by the joined picture: {aspect 9:16, width 1080}
+    # over two 16:9 clips rendered 342x608, where one clip (and --export-timeline's sequence) is
+    # 1080x1920. Only that case gets the frame's side. A frame with both sides is already the
+    # join's size, and a project fit object with its own width, height or another aspect renders
+    # as 2.2.1 rendered it: filling the frame's sides in there overrode the fit object's aspect
+    # (fit {width 540} under a 1080x1920 frame came out 540x1920).
+    own = proj.get("fit") or {}
+    one_side = bool(frame.get("width")) != bool(frame.get("height"))
+    sized = len(parts) == 1 or bool(frame.get("aspect") and one_side and not own.get("width") and not own.get("height")
+                                    and own.get("aspect") in (None, frame.get("aspect")))
+    if frame.get("width") and sized:
         fit.setdefault("width", frame["width"])
-    if frame.get("height") and len(parts) == 1:
+    if frame.get("height") and sized:
         fit.setdefault("height", frame["height"])
     if frame.get("fps") and len(parts) == 1:
         fit.setdefault("fps", frame["fps"])