ffmpeg-skill 3.1.4 → 3.1.6

package/scripts/_common/probe.py

@@ -13,7 +13,7 @@ import statistics
 from fractions import Fraction
 from typing import Any, Dict, List, Optional, Sequence, Tuple
 from _common.emit import die, warn
-from _common.runner import STATE, dry_run_input_pending, require_tool, run, run_analysis
+from _common.runner import STATE, dry_run_input_pending, require_tool, run, run_analysis, still_input_args
 
 
 def fingerprint(path: str) -> Dict[str, Any]:
@@ -38,7 +38,8 @@ def decode_pcm_mono(path: str, sample_rate: int, seconds: Optional[float] = None
                     *, check: bool = True) -> List[float]:
     """Decode (part of) a file's audio to mono float samples in [-1, 1) at `sample_rate` via a
     single ffmpeg pass under --timeout. Shared by scenes.py (audio envelope for cut scoring) and
-    sync.py (cross-correlation); an undecodable input is kind ffmpeg when check=True, else []."""
+    sync.py (cross-correlation); an undecodable input is kind ffmpeg when check=True, else [].
+    The samples are on the file's clock: a sound that starts late is padded at its head."""
     ffmpeg = require_tool("ffmpeg")
     cmd = [ffmpeg, "-hide_banner", "-loglevel", "error", "-nostdin"]
     if start:
@@ -46,7 +47,10 @@ def decode_pcm_mono(path: str, sample_rate: int, seconds: Optional[float] = None
     cmd += ["-i", path]
     if seconds is not None:
         cmd += ["-t", f"{seconds:.3f}"]
-    cmd += ["-vn", "-ac", "1", "-ar", str(sample_rate), "-f", "s16le", "-"]
+    # first_pts=0 pads a sound that starts after the file's start (or after `start`) with silence,
+    # so sample i is at start + i / sample_rate on the file's clock: sync.py measured a track that
+    # starts 0.3 s late 0.279 s off, and --replace-audio placed it that far late (#409)
+    cmd += ["-vn", "-af", "aresample=async=1:first_pts=0", "-ac", "1", "-ar", str(sample_rate), "-f", "s16le", "-"]
     proc = run_analysis(cmd, check=False, text=False)
     if proc.returncode != 0 or not proc.stdout:
         if check:
@@ -187,7 +191,8 @@ def probe(path: str, role: str = "input") -> Dict[str, Any]:
         die(f"input not found: {path}")
     ffprobe = require_tool("ffprobe")
     proc = run(
-        [ffprobe, "-v", "error", "-print_format", "json", "-show_format", "-show_streams", "-show_chapters", path],
+        [ffprobe, "-v", "error", *still_input_args(path),
+         "-print_format", "json", "-show_format", "-show_streams", "-show_chapters", path],
         quiet=True,
         check=False,
     )
@@ -283,6 +288,12 @@ def probe(path: str, role: str = "input") -> Dict[str, Any]:
                 rotation = int(video["tags"]["rotate"])
             except ValueError:
                 pass
+        if not rotation and _is_still(fmt, video):
+            # an EXIF Orientation reaches ffmpeg as the decoded frame's display matrix, not as
+            # stream side data, so -show_streams has no rotation for a phone's portrait JPEG;
+            # ffmpeg still turns the picture upright on decode, and every tool that sizes the
+            # frame has to know it did (#411)
+            rotation = _still_rotation(path)
         pix = video.get("pix_fmt") or ""
         trc = video.get("color_transfer") or ""
         prim = video.get("color_primaries") or ""
@@ -300,6 +311,10 @@ def probe(path: str, role: str = "input") -> Dict[str, Any]:
             "width": w,
             "height": h,
             "display_aspect": video.get("display_aspect_ratio") or _aspect_string(w, h),
+            # the stored pixel's shape (DV, HDV 1440x1080, DVD and XDCAM store non-square pixels);
+            # every tool that sizes or draws on the picture works on square pixels at the display
+            # aspect (square_pixels() / display_size() below)
+            "sample_aspect_ratio": _sar_string(video.get("sample_aspect_ratio")),
             "fps": round(fps, 3) if fps else None,
             "r_frame_rate": video.get("r_frame_rate"),
             "avg_frame_rate": video.get("avg_frame_rate"),
@@ -368,6 +383,8 @@ def probe(path: str, role: str = "input") -> Dict[str, Any]:
     if role == "input" and getattr(STATE, "first_input", None) is None:
         STATE.first_input = (path, len(out.get("audio_streams") or []),
                              (out.get("video") or {}).get("hdr10_static"))
+    if role == "input" and out["timecode"].get("value") and getattr(STATE, "source_timecode", None) is None:
+        STATE.source_timecode = (out["timecode"]["value"], duration)
     return out
 
 
@@ -657,6 +674,83 @@ def _fraction(v: Optional[str]) -> Optional[Fraction]:
         return None
 
 
+def _sar_string(v: Optional[str]) -> str:
+    """ffprobe's sample_aspect_ratio as "N:D", "1:1" when unset (0:1, N/A, missing)."""
+    f = _fraction((v or "").replace(":", "/"))
+    return f"{f.numerator}:{f.denominator}" if f else "1:1"
+
+
+def pixel_aspect(video: Optional[Dict[str, Any]]) -> Fraction:
+    """The stored pixel's width over its height (the SAR); 1 when the stream does not say."""
+    return _fraction(str((video or {}).get("sample_aspect_ratio") or "").replace(":", "/")) or Fraction(1)
+
+
+def _square_size(video: Optional[Dict[str, Any]]) -> "Tuple[int, int, Fraction]":
+    """(width, height, SAR) of the frame the filter graph receives: rotation applied (ffmpeg
+    autorotates on decode, and its transpose turns the SAR over too), pixels not yet squared."""
+    video = video or {}
+    w, h = int(video.get("width") or 0), int(video.get("height") or 0)
+    sar = pixel_aspect(video)
+    if video.get("rotation") in (90, -90, 270, -270):
+        w, h, sar = h, w, 1 / sar
+    return w, h, sar
+
+
+def display_size(video: Optional[Dict[str, Any]]) -> "Tuple[int, int]":
+    """The displayed frame in square pixels: rotation applied, and a non-square-pixel picture
+    widened or narrowed to its display aspect at its own height (1440x1080 at 4:3 is 1920x1080,
+    720x480 at 8:9 is 640x480). It is the frame square_pixels() hands the rest of a graph, so a
+    tool sizes, places and draws in it. 0x0 when unknown (a dry run's pending input)."""
+    w, h, sar = _square_size(video)
+    if w and h and sar != 1:
+        w = max(2, int(round(w * sar / 2)) * 2)
+    return w, h
+
+
+def square_pixels(video: Optional[Dict[str, Any]]) -> str:
+    """The filter that makes a non-square-pixel picture square at its display aspect
+    ("scale=640:360,setsar=1"), or "" when the pixels are square already. A tool that scales,
+    crops, places or draws starts its video chain with it, so every such tool agrees on one
+    frame (display_size()) and nothing is squashed or drawn stretched (#411). Tools that only
+    re-encode keep the stored size and its SAR, which the encoder writes through."""
+    w, h, sar = _square_size(video)
+    if not (w and h) or sar == 1:
+        return ""
+    dw, dh = display_size(video)
+    return f"scale={dw}:{dh},setsar=1"
+
+
+def square_pixels_note(video: Optional[Dict[str, Any]], what: str = "the input") -> Optional[str]:
+    """The notes line for a square_pixels() scale, or None when there is none."""
+    if not square_pixels(video):
+        return None
+    w, h, _ = _square_size(video)
+    dw, dh = display_size(video)
+    return (f"{what} stores non-square pixels (SAR {(video or {}).get('sample_aspect_ratio')}): "
+            f"its {w}x{h} picture was scaled to {dw}x{dh} square pixels, its display aspect")
+
+
+def _is_still(fmt: Dict[str, Any], video: Dict[str, Any]) -> bool:
+    """A single picture read by an image demuxer (image2, jpeg_pipe, png_pipe, ...)."""
+    name = fmt.get("format_name") or ""
+    return name == "image2" or name.endswith("_pipe")
+
+
+def _still_rotation(path: str) -> int:
+    """The display rotation of a still's first decoded frame (an EXIF Orientation), 0 if none."""
+    proc = run([require_tool("ffprobe"), "-v", "error", *still_input_args(path), "-select_streams", "v:0",
+                "-read_intervals", "%+#1", "-show_entries", "frame_side_data=rotation", "-of", "json", path],
+               quiet=True, check=False)
+    try:
+        frames = json.loads(proc.stdout or "{}").get("frames") or []
+        for sd in (frames[0].get("side_data_list") or []) if frames else []:
+            if "rotation" in sd:
+                return int(round(float(sd["rotation"])))
+    except (ValueError, TypeError, AttributeError):
+        pass
+    return 0
+
+
 def _aspect_string(w: Optional[int], h: Optional[int]) -> Optional[str]:
     if not w or not h:
         return None

package/scripts/_common/runner.py

@@ -324,7 +324,8 @@ class Context:
 
     __slots__ = ("dry_run", "json", "json_brief", "progress", "fast", "duration_hint", "commands", "timeout", "overwrite", "written", "preexisting", "plan", "plan_written", "plan_inputs", "codec",
                  "hw", "hw_source", "hw_notes", "hw_swaps", "hw_fallback", "hw_env_ignored", "hw_stages", "hw_auto",
-                 "notes", "warnings", "fallbacks", "skipped", "audit_log", "stage_verification", "first_input", "audio_inputs", "video_inputs")
+                 "notes", "warnings", "fallbacks", "skipped", "audit_log", "stage_verification", "first_input", "audio_inputs", "video_inputs",
+                 "source_timecode", "smpte_hint")
 
     def __init__(self) -> None:
         self.reset()
@@ -334,6 +335,8 @@ class Context:
         self.json = False         # emit() prints a JSON document instead of the output path
         self.first_input = None   # (path, audio track count) of the first input probed: emit() reports tracks the output left out
         self.video_inputs = set()  # real paths of the inputs probed that have a picture: with two or more, which one the output shows is the tool's choice (sync --trim-second, a join)
+        self.source_timecode = None  # (start timecode, duration) of the first input probed that carries one (time_arg's SMPTE hint)
+        self.smpte_hint = None    # what die() says when an hh:mm:ss:ff flag read past the end looks like a source timecode (#411)
         self.audio_inputs = set()  # real paths of the inputs probed that have sound: with two or more, whose tracks an output should keep is the tool's choice (grid --audio-from, a mix)
         self.json_brief = False   # --json-brief: the same document trimmed to the fields a caller acts on
         self.progress = False     # run() streams percent / ETA to stderr for ffmpeg
@@ -441,6 +444,13 @@ def apply_common(args: "argparse.Namespace") -> None:
     STATE.progress = bool(getattr(args, "progress", False))
     STATE.fast = bool(getattr(args, "fast", False))
     STATE.overwrite = bool(getattr(args, "overwrite", False))
+    if STATE.plan:
+        # the plan is a file this run writes itself: the side-file guards apply (#408), so it
+        # never replaces an input, the output or an existing file without --overwrite
+        named = [getattr(args, k, None) for k in ("input", "inputs", "reference", "compare")]
+        inputs = [p for v in named for p in (v if isinstance(v, (list, tuple)) else [v]) if isinstance(p, str)]
+        out = getattr(args, "output", None)
+        guard_sidecar(STATE.plan, *inputs, siblings=(out,) if isinstance(out, str) else ())
     if getattr(args, "timeout", None) is not None:
         STATE.timeout = max(0.0, float(args.timeout))
     else:
@@ -683,11 +693,15 @@ def video_encoder_of(cmd: Sequence[str]) -> Optional[str]:
 # while every guard here reads it as a path. Two or more letters, so a Windows
 # drive letter (`C:\x.mp4`) is a path; `pipe:` is the skill's own stdout/stdin and stays allowed.
 _URL_SCHEME = re.compile(r"^[A-Za-z][A-Za-z0-9+.-]+:")
+# Off Windows there are no drive letters, and ffmpeg reads a one-letter `x:y.mp4` as protocol `x`
+# too (#408: it then failed as "Protocol not found", with no hint that ./x:y.mp4 works)
+_URL_SCHEME_POSIX = re.compile(r"^[A-Za-z][A-Za-z0-9+.-]*:")
 
 
 def looks_like_url(value: str) -> bool:
     """True for a value ffmpeg would open through a protocol rather than as a local file."""
-    return bool(_URL_SCHEME.match(value)) and not value.startswith("pipe:")
+    scheme = _URL_SCHEME if os.name == "nt" else _URL_SCHEME_POSIX
+    return bool(scheme.match(value)) and not value.startswith("pipe:")
 
 
 _PLAYLIST_SUFFIXES = (".m3u8", ".m3u", ".ffconcat")
@@ -1705,13 +1719,34 @@ def place_output(src: str, dst: str, move: bool = False) -> None:
     _remember_output(cmd)
 
 
+# extensions ffmpeg opens through the image2 demuxer, the only one that expands `%d` in a name
+# and the only one that has a `pattern_type` option (gif, avif, mp4... reject it: "Option
+# pattern_type not found")
+_IMAGE2_EXT = (".png", ".jpg", ".jpeg", ".webp", ".bmp", ".tif", ".tiff", ".dpx", ".exr", ".tga",
+               ".ppm", ".pgm", ".pbm", ".pam", ".sgi", ".jp2", ".j2k", ".xbm", ".xpm", ".pcx", ".qoi")
+
+
+def still_input_args(path: str) -> List[str]:
+    """`-pattern_type none` for a still read through image2 whose path has a `%` in it (#408):
+    image2 otherwise reads `logo%d.png` as a numbered sequence and opens `logo1.png`, a file the
+    run's guards and fingerprints never looked at. Empty for every other path, a video or a GIF
+    with a `%` in its name included: their demuxers never expand it and reject the option."""
+    p = str(path)
+    return ["-pattern_type", "none"] if "%" in p and os.path.splitext(p)[1].lower() in _IMAGE2_EXT else []
+
+
 def sibling_temp(dst: str, tag: str) -> str:
     """A hidden path next to `dst`, with its extension (the muxer is chosen by it), for a file
     place_output(..., move=True) renames into place: same directory, so the rename never
     crosses a filesystem."""
     d, base = os.path.split(dst)
     stem, ext = os.path.splitext(base)
-    return os.path.join(d, f".{stem}.ffskill-{tag}-{os.getpid()}{ext}")
+    path = os.path.join(d, f".{stem}.ffskill-{tag}-{os.getpid()}{ext}")
+    n = 1
+    while os.path.lexists(path):  # a leftover of an earlier run with this pid: not ours to replace
+        n += 1
+        path = os.path.join(d, f".{stem}.ffskill-{tag}-{os.getpid()}-{n}{ext}")
+    return path
 
 
 _DRAWTEXT_TMPDIR: "Optional[str]" = None

package/scripts/_common/timeline.py

@@ -30,6 +30,7 @@ from xml.sax.saxutils import escape as _xml_escape
 
 from _common.decision import MissingFpsError, aspect_ratio, frame_size, parse_time
 from _common.emit import warn
+from _common.probe import display_size
 
 FORMATS = {".edl": "edl", ".fcpxml": "fcpxml", ".otio": "otio"}
 # Common NTSC rates are stored as the exact ratio an editor expects, not as 29.97.
@@ -101,12 +102,12 @@ def _seconds(value: Any, what: str, fps: Optional[float]) -> float:
 
 
 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)
+    """A source's displayed width x height, as fit.py reads it: rotation metadata swaps them, and
+    non-square pixels are squared at the display aspect (probe.display_size(), #411)."""
+    w, h = display_size(meta.get("video") or {})
     if not (w and h):
         return None
-    return (h, w) if video.get("rotation") in (90, -90, 270, -270) else (w, h)
+    return (w, h)
 
 
 def build(proj: Dict[str, Any], probes: Dict[str, Dict[str, Any]], rel) -> Dict[str, Any]:

package/scripts/_contract.py

@@ -276,7 +276,7 @@ REENCODE_META: Dict[str, Dict[str, str]] = {
     "speedramp": dict(video="always", audio="always", note="setpts/atempo per segment always forces a re-encode of both streams"),
     "broll":    dict(video="always", audio="conditional", note="the overlay graph always re-encodes the video stream; A's audio is stream-copied under --audio a and re-encoded to AAC under --audio b/mix"),
     "metadata": dict(video="never", audio="never", note="-c copy on every stream; only the container's chapters and tags change -- --auto-chapters decodes to measure, but still writes with -c copy"),
-    "loop":     dict(video="always", audio="conditional", note="-stream_loop always re-encodes both streams; the audio codec is always AAC when present. --boomerang re-encodes the video through reverse/loop filters and drops the audio"),
+    "loop":     dict(video="always", audio="conditional", note="the repeats (the concat demuxer, the file listed once per repeat) always re-encode both streams; the audio codec is always AAC when present. --boomerang re-encodes the video through reverse/loop filters and drops the audio"),
     "insert":    dict(video="always", audio="never", note="always encodes a fresh silent clip from the still image; there is no audio stream to touch"),
     "background": dict(video="always", audio="never", note="always encodes a fresh generated clip; there is no input to copy from"),
     "reverse":   dict(video="always", audio="conditional", note="video always re-encodes (reverse buffers and re-emits every frame); audio re-encodes to AAC when present and not dropped by --no-audio"),
@@ -454,7 +454,7 @@ DIAGNOSTIC_CODES = {
     "audit_log_unwritable": ("warnings", "an audit record could not be appended; never fails the run; {path, event, error}"),
     "plan_unbound_inputs": ("warnings", "render.py PLAN: inputs that did not exist when the plan was made, so were not checked; {paths}"),
     # the runner
-    "odd_dimensions_scaled_even": ("fallbacks", "an encode that failed on odd dimensions was run again scaled to even ones (the frame loses a row or column); {output, scale}"),
+    "odd_dimensions_scaled_even": ("fallbacks", "an encode that failed on odd dimensions was run again scaled to even ones, or a graph the retry cannot reach (broll.py's filter_complex) was scaled to even ones up front (the frame loses a row or column); {output, scale}"),
     "measurement_input_pending": ("skipped", "--dry-run: a measurement skipped because its input is an earlier stage's output that does not exist yet; {path}"),
     "non_av_streams_dropped": ("fallbacks", "the subtitle/data streams could not be copied, so the encode ran again without them (dropped_non_av_streams: true); {output, returncode, error: the first attempt's last stderr lines}; export.py adds dropped: the stream types this retry leaves out (data alone first, then subtitle too)"),
     "ffmpeg_list_unreadable": ("warnings", "`ffmpeg -encoders` / `-bsfs` could not be read; what needs the list says so instead of 'the build lacks it'; {list, tool, error}"),

package/scripts/broll.py

@@ -21,7 +21,10 @@ import argparse
 import sys
 from typing import Any, Dict, List
 
-from _common import STATE, add_common, aac_args, apply_common, cfr_args, default_output, die, draws_chroma, drawn_chain, emit, ffmpeg_base, info, time_arg, label_chain, matrix_chain, probe, run, validate_color, video_args, X264_PRESETS, fmt_secs
+from _common.decision import av_trim, frame_rate, grid_at_or_after, stream_starts
+from _common import STATE, add_common, aac_args, apply_common, cfr_args, as_limited, default_output, die, draws_chroma, drawn_chain, emit, ffmpeg_base, info, time_arg, label_chain, matrix_chain, range_chain, probe, run, validate_color, video_args, X264_PRESETS, fmt_secs
+from _common.emit import note, record_fallback
+from _common.probe import display_size, square_pixels, square_pixels_note
 
 
 def main() -> int:
@@ -55,10 +58,20 @@ def main() -> int:
     if not meta_a.get("video"):
         die("A-roll has no video stream")
     dur_a = meta_a.get("duration") or 0.0
-    w, h = meta_a["video"]["width"], meta_a["video"]["height"]
-    # the cutaway is scaled onto the frame ffmpeg has already rotated, not the stored one
-    if meta_a["video"].get("rotation") in (90, -90, 270, -270):
-        w, h = h, w
+    # the cutaway is scaled onto the frame ffmpeg has already rotated, not the stored one, and
+    # onto a non-square-pixel A-roll squared at its display aspect (#411)
+    w, h = display_size(meta_a["video"])
+    a_chain = square_pixels(meta_a["video"])
+    if a_chain:
+        note(square_pixels_note(meta_a["video"], "the A-roll"))
+    if (w % 2 or h % 2) and w and h:
+        # an odd-sized A-roll cannot be encoded 4:2:0 at its own size, and the run-time even-scale
+        # retry does not reach a filter_complex: through 3.1.3 this failed as kind "ffmpeg" (#411)
+        ew, eh = max(2, w - w % 2), max(2, h - h % 2)  # never 0, which scale reads as "keep" (#416 review)
+        record_fallback(f"the A-roll is {w}x{h}, which 4:2:0 cannot hold: scaled to {ew}x{eh}",
+                        "odd_dimensions_scaled_even", output=args.output or default_output(args.input, "broll"), scale=f"scale={ew}:{eh}")
+        a_chain = (a_chain + "," if a_chain else "") + f"scale={ew}:{eh},setsar=1"
+        w, h = ew, eh
     fps = meta_a["video"].get("fps") or 30.0
     has_audio_a = bool(meta_a.get("audio"))
 
@@ -72,13 +85,13 @@ def main() -> int:
         meta_b = probe(path)
         if not meta_b.get("video"):
             die(f"{path} has no video stream")
-        at = time_arg(args.at[i], "--at", fps)
-        start_b = time_arg(per(args.from_, i, "0"), "--from", fps)
+        at = time_arg(args.at[i], "--at", fps, source=meta_a)
+        start_b = time_arg(per(args.from_, i, "0"), "--from", fps, source=meta_b)
         if args.end:
-            end = time_arg(per(args.end, i, "0"), "--end", fps)
+            end = time_arg(per(args.end, i, "0"), "--end", fps, source=meta_a)
             length = end - at
         else:
-            length = time_arg(per(args.duration, i, "4"), "--duration", fps)
+            length = time_arg(per(args.duration, i, "4"), "--duration", fps, source=meta_a)
         if length <= 0:
             die(f"cutaway {i + 1}: length must be > 0 (at {at:g}s, got {length:g}s)")
         if dur_a and at >= dur_a:
@@ -110,16 +123,19 @@ def main() -> int:
     convert = [matrix_chain(m, meta_a) for m in [meta_a] + [c["meta"] for c in cutaways]]
     if any(convert) or draws_chroma([args.pad_color], meta_a):
         convert = [cv or label_chain(m, meta_a) for cv, m in zip(convert, [meta_a] + [c["meta"] for c in cutaways])]
-    if convert[0]:
-        parts.append(f"[0:v]{convert[0]}null[a709]")
+    # overlay mixes samples: a full-range clip over or under a limited one is taken to limited range (#410)
+    convert = [cv + range_chain(m, meta_a) for cv, m in zip(convert, [meta_a] + [c["meta"] for c in cutaways])]
+    if convert[0] or a_chain:
+        parts.append(f"[0:v]{convert[0]}{a_chain or 'null'}[a709]")
         cur = "[a709]"
     pad = f"pad={w}:{h}:(ow-iw)/2:(oh-ih)/2:color="
     for i, c in enumerate(cutaways):
         geo = (f"scale={w}:{h}:force_original_aspect_ratio=decrease,"
-               + drawn_chain(pad + args.pad_color, c["meta"], [args.pad_color], pad + "black", line_meta=meta_a,
+               + drawn_chain(pad + args.pad_color, as_limited(c["meta"]), [args.pad_color], pad + "black", line_meta=meta_a,
                              tag=f"pad{i}", labelled=True))
+        b_sq = (square_pixels(c["meta"]["video"]) + ",") if square_pixels(c["meta"]["video"]) else ""
         parts.append(f"[{i + 1}:v]trim=start={c['from']:.3f}:duration={c['length']:.3f},setpts=PTS-STARTPTS+{c['at']:.3f}/TB,"
-                     f"{convert[i + 1]}{geo},setsar=1,fps={fps:g},format={'yuv420p10le' if (meta_a.get('video') or {}).get('bt2020_or_hdr') else 'yuv420p'}[b{i}]")
+                     f"{convert[i + 1]}{b_sq}{geo},setsar=1,fps={fps:g},format={'yuv420p10le' if (meta_a.get('video') or {}).get('bt2020_or_hdr') else 'yuv420p'}[b{i}]")
         parts.append(f"{cur}[b{i}]overlay=0:0:eof_action=pass:enable='between(t,{c['at']:.3f},{c['at'] + c['length']:.3f})'[v{i}]")
         cur = f"[v{i}]"
     vout = cur
@@ -137,7 +153,12 @@ def main() -> int:
                 parts.append(f"[0:a:0]aformat=sample_rates=48000:channel_layouts=stereo{gate}[a0]")
                 layers.append("[a0]")
             for i, c in enumerate(cutaways):
-                parts.append(f"[{i + 1}:a:0]atrim=start={c['from']:.3f}:duration={c['length']:.3f},asetpts=PTS-STARTPTS,"
+                # B's sound is shifted by the same constant as its picture, whose first frame (the
+                # first at or after --from) lands on --at; rebasing the sound to its own first
+                # sample moved a track that starts 0.3 s late 0.279 s early (#409)
+                v0b = stream_starts(c["meta"])[0]
+                first = max(v0b, grid_at_or_after(c["from"], v0b, frame_rate(c["meta"])))
+                parts.append(f"[{i + 1}:a:0]{av_trim(first, first + c['length'])[1]},"
                              f"aformat=sample_rates=48000:channel_layouts=stereo,adelay={int(c['at'] * 1000)}|{int(c['at'] * 1000)}[ab{i}]")
                 layers.append(f"[ab{i}]")
             parts.append(f"{''.join(layers)}amix=inputs={len(layers)}:normalize=0:dropout_transition=0,atrim=duration={dur_a:.3f}[aout]")

package/scripts/caption.py

@@ -44,7 +44,8 @@ from typing import Any, Dict, List, Optional, Tuple
 from _platforms import (PLATFORMS, PLATFORM_CHOICES, ASS_SCRIPT_HEIGHT, ass_units,
                         resolve as resolve_platform)
 from _ass_overlay import EMOJI_SENTINEL, emoji_placeholder, ass_escape
-from _common import require_filter, emoji_filter_chain, EMOJI_ASSET_HINT, emoji_asset_for, emoji_codepoint_name, emoji_support, resolve_emoji_assets, ADVANCE_EM, LATIN_EM, NO_SPACE_SCRIPTS, _char_em, char_script, text_width_em, emoji_clusters, has_emoji, detect_script, BIDI_SCRIPTS, STATE, brand_states_font, script_font_for_text, signed_time_arg, brand_caption_style, color_hex, drawn_chain, label_chain, load_brand, rgb_chain_to_bt709, video_args, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, fmt_srt_time, fmt_smpte_time, info, MissingFpsError, parse_time, probe, run, x264_args, X264_PRESETS, read_text_or_die, fmt_secs, refuse_existing_outputs
+from _common.emit import refuse  # noqa: E402
+from _common import require_filter, emoji_filter_chain, EMOJI_ASSET_HINT, emoji_asset_for, emoji_codepoint_name, emoji_support, resolve_emoji_assets, ADVANCE_EM, LATIN_EM, NO_SPACE_SCRIPTS, _char_em, char_script, text_width_em, emoji_clusters, has_emoji, detect_script, BIDI_SCRIPTS, STATE, brand_states_font, script_font_for_text, signed_time_arg, brand_caption_style, color_hex, drawn_chain, label_chain, layer_base_chain, load_brand, rgb_chain_to_bt709, video_args, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, fmt_srt_time, fmt_smpte_time, info, MissingFpsError, parse_time, probe, run, x264_args, X264_PRESETS, read_text_or_die, fmt_secs, refuse_existing_outputs, guard_sidecar
 # The line breaker, lifted into _common/text.py in 1.16.0 so graphics.py can use the same rules.
 # The ASR bridge and the SRT reader/writer live in _common.asr since 1.17 (silence.py --filler
 # shares them). They stay caption.py's public names -- every caller and test that reached for
@@ -52,6 +53,7 @@ from _common import require_filter, emoji_filter_chain, EMOJI_ASSET_HINT, emoji_
 from _common import asr as _asr
 from _common.asr import ENGINE_CHOICES
 from _common.emit import warn
+from _common.probe import display_size, square_pixels, square_pixels_note
 from _common.fonts import font_choice, record_font_choice
 from _common import (ASR_INSTALL_HINT, die_no_engine, parse_srt, transcribe, whisper_word_timings,
                      write_srt)
@@ -1138,9 +1140,9 @@ def main() -> int:
 
     play_w = play_h = None
     if meta and meta.get("video"):
-        play_w, play_h = meta["video"]["width"], meta["video"]["height"]
-        if meta["video"].get("rotation") in (90, -90, 270, -270):
-            play_w, play_h = play_h, play_w
+        # the displayed frame: rotation applied, non-square pixels squared (#411) -- the burn
+        # below draws on the square-pixel picture, so a cue is not stretched by the player's SAR
+        play_w, play_h = display_size(meta["video"])
     # A --plan or --dry-run written before the input exists has no geometry to fit against, and a
     # plan that describes a different FontSize from the run that executes it is not a plan. When
     # --platform names a destination, that destination's frame IS the geometry the real run will
@@ -1276,28 +1278,52 @@ def main() -> int:
     # next to the output was replaced on a re-run, even one ffmpeg's check then refused.
     # Side files whose existence depends on the cues (an _adjusted.srt, an emoji-forced ASS) are
     # checked again where they are written, still before that write.
-    claimed: set = set()
-
-    def claim(paths) -> None:
-        todo = [p for p in paths if p and os.path.realpath(p) not in claimed]
+    claimed: Dict[str, str] = {}  # real path -> which artifact of this run holds it
+
+    def claim(items) -> None:
+        """Reserve (path, artifact) pairs: the same artifact claiming its path again is a no-op,
+        another artifact of this run claiming it is refused (#413 review: --write-srt and
+        --write-ass naming one file, the SRT then replaced by the ASS)."""
+        todo = []
+        for path, owner in items:
+            if not path:
+                continue
+            real = os.path.realpath(path)
+            held = claimed.get(real)
+            if held is None and os.path.exists(real):
+                # a second name for the same file (a hard link) is the same path (#413 review)
+                held = next((o for r, o in claimed.items()
+                             if os.path.exists(r) and os.path.samefile(r, real)), None)
+            if held is None:
+                claimed[real] = owner
+                todo.append(path)
+            elif held != owner:
+                refuse("input", "output_path_taken",
+                       f"{path!r} is named for both the {held} and the {owner} this run writes; give each its own path",
+                       output=path, other=held)
         refuse_existing_outputs(todo)
-        claimed.update(os.path.realpath(p) for p in todo)
+        # and the rest of the side-file guards (#408): never an input, the video, a missing
+        # directory or an option-shaped name, even under --overwrite
+        side_inputs = [q for q in (args.input, getattr(args, "text", None), getattr(args, "ass", None),
+                                   getattr(args, "brand", None), *(t[0] for t in srt_tracks)) if isinstance(q, str)]
+        for path in todo:
+            guard_sidecar(path, *side_inputs)
 
     planned_out = args.output or (default_output(args.input, "captioned") if args.input else None)
-    up_front: List[str] = []
+    up_front: List[Tuple[str, str]] = []
     if args.transcribe:
-        up_front.append(args.write_srt or os.path.splitext(planned_out)[0] + ".srt")
+        up_front.append((args.write_srt or os.path.splitext(planned_out)[0] + ".srt", "SRT"))
     elif args.text:
-        up_front.append(args.write_srt or (os.path.splitext(planned_out)[0] + ".srt" if args.input
-                                           else os.path.splitext(args.text)[0] + ".srt"))
+        up_front.append((args.write_srt or (os.path.splitext(planned_out)[0] + ".srt" if args.input
+                                            else os.path.splitext(args.text)[0] + ".srt"), "SRT"))
     if args.input:
         if (args.animate != "none" or args.karaoke) and not args.ass:
-            up_front.append(args.write_ass or os.path.splitext(planned_out)[0] + ".ass")
+            up_front.append((args.write_ass or os.path.splitext(planned_out)[0] + ".ass", "ASS"))
         if args.ass and args.offset and os.path.exists(args.ass):
-            up_front.append(os.path.splitext(planned_out)[0] + "_offset.ass")
+            up_front.append((os.path.splitext(planned_out)[0] + "_offset.ass", "offset ASS"))
         # -o naming the input itself keeps its own, more specific refusal (_check_no_overwrite_input)
         if os.path.realpath(planned_out) != os.path.realpath(args.input):
-            up_front.append(planned_out)
+            up_front.append((planned_out, "video"))
     claim(up_front)
     if args.transcribe:
         # the sidecar goes next to the output like the --text one, not into the source folder
@@ -1358,7 +1384,7 @@ def main() -> int:
         adjusted, changed = lay_out(parse_srt(srt_path))
         if changed:
             new_srt = os.path.splitext(output)[0] + "_adjusted.srt"
-            claim([new_srt])
+            claim([(new_srt, "adjusted SRT")])
             if STATE.dry_run:
                 info(f"[dry-run] would write {new_srt} ({len(adjusted)} cues, adjusted from {os.path.basename(srt_path)})")
             else:
@@ -1563,10 +1589,8 @@ def main() -> int:
         if args.karaoke and not getattr(args, "_word_timings", None):
             args._word_timings = whisper_word_timings(srt_path)
         ass_path = args.write_ass or os.path.splitext(output)[0] + ".ass"
-        claim([ass_path])
-        w, h = meta["video"]["width"], meta["video"]["height"]
-        if meta["video"].get("rotation") in (90, -90, 270, -270):
-            w, h = h, w
+        claim([(ass_path, "ASS")])
+        w, h = display_size(meta["video"])
         if not STATE.dry_run:  # the generated ASS is an artifact of this run: a plan writes nothing
             write_ass(cues_for_ass, ass_path, args, w, h, video=args.input if meta.get("audio") else None)
         info(f"wrote {ass_path} ({len(cues_for_ass)} cues, animate={args.animate}, karaoke={args.karaoke})")
@@ -1656,9 +1680,12 @@ def main() -> int:
         vf = drawn_chain(vf, meta, [args.color, args.outline_color]
                          + ([args.highlight_color, args.upcoming_color] if args.karaoke else []))
 
+    if square_pixels((meta or {}).get("video")):
+        vf = square_pixels(meta["video"]) + "," + vf
+        side_notes.append(square_pixels_note(meta["video"]))
     cmd = ffmpeg_base() + ["-i", args.input]
     chains, emoji_inputs = (emoji_filter_chain(emoji_plan or {}, "vsub", "vout", to_yuv=rgb_chain_to_bt709(meta),
-                                               base_chain=label_chain(meta, meta) if rgb_chain_to_bt709(meta) else "")
+                                               base_chain=layer_base_chain(meta))
                             if emoji_plan else ([], []))
     if chains:
         for spec in emoji_inputs:

package/scripts/color.py

@@ -43,7 +43,7 @@ CORRECTION = {
     "exposure":    (0.0,   -3.0,    3.0,   "stops"),   # exposure filter's own full range (linear-domain stops)
     "contrast":    (1.0,    0.0,    2.0,   "x"),       # eq filter; 0=flat grey, 1=unchanged, 2=double contrast
     "saturation":  (1.0,    0.0,    2.0,   "x"),       # eq filter; 0=grayscale, 1=unchanged, 2=double saturation
-    "temperature": (6500.0, 2000.0, 12000.0, "K"),     # colortemperature filter; 6500=unchanged (its own default)
+    "temperature": (6500.0, 2000.0, 12000.0, "K"),     # colortemperature filter; 6500=unchanged (no term: the filter itself tints at 6500)
     "tint":        (0.0,   -1.0,    1.0,   "x"),       # mapped to colorbalance midtones, see correction_chain()
     "gamma":       (1.0,    0.1,   10.0,   "x"),       # eq filter's own gamma option; 1=unchanged (its own default)
     "lift":        (0.0,   -1.0,    1.0,   "x"),       # colorbalance shadows (rs=gs=bs); 0=unchanged
@@ -116,11 +116,13 @@ def correction_chain(args: argparse.Namespace) -> str:
         die(f"--levels-out-black {out_black} must be less than --levels-out-white {out_white}")
 
     gm, rm, bm = -tint, tint / 2.0, tint / 2.0
-    rgb = [
-        f"exposure=exposure={exposure:g}",
-        f"colortemperature=temperature={temperature:g}",
-        f"colorbalance=rs={lift:g}:gs={lift:g}:bs={lift:g}:rm={rm:g}:gm={gm:g}:bm={bm:g}:rh={gain:g}:gh={gain:g}:bh={gain:g}",
-    ]
+    rgb = [f"exposure=exposure={exposure:g}"]
+    if temperature != CORRECTION["temperature"][0]:
+        # colortemperature at 6500 K is not the identity it is documented as here: it multiplies by
+        # its own approximation of that white point, which tinted grey 808080 to 7E7E7B (#410), so
+        # "unchanged" adds no term at all
+        rgb.append(f"colortemperature=temperature={temperature:g}")
+    rgb.append(f"colorbalance=rs={lift:g}:gs={lift:g}:bs={lift:g}:rm={rm:g}:gm={gm:g}:bm={bm:g}:rh={gain:g}:gh={gain:g}:bh={gain:g}")
     terms = [_rgb_stage(rgb), f"eq=contrast={contrast:g}:saturation={saturation:g}:gamma={gamma:g}"]
     rgb2 = []
     if (in_black, in_white, out_black, out_white) != (0, 255, 0, 255):
@@ -156,6 +158,31 @@ def _rgb_stage(filters: list) -> str:
             + ",scale=out_color_matrix=bt601,format=yuv420p")
 
 
+# swscale's names for the non-BT.709 matrices a --codec prores re-encode keeps (it does not convert)
+_SWS_MATRIX = {"smpte170m": "bt601", "bt470bg": "bt601", "smpte240m": "smpte240m", "fcc": "fcc"}
+
+
+def lut_legs(meta=None) -> "tuple":
+    """(to RGB, back to YUV) around --lut's lut3d: explicit BT.709 conversions through float RGB,
+    the matrix the picture holds when it reaches them (an untagged or BT.709 source as it is, a
+    BT.601 or RGB one after x264_args(source=...)'s conversion), limited range on the way out.
+
+    lut3d takes RGB, and left to libavfilter the way in honoured the frame's BT.709 tag while the
+    way back used swscale's BT.601 default, so even an identity LUT shifted every colour (2FAE4E to
+    249A4B, #410); --correct had its legs pinned for the same reason in #159. A LUT maps the RGB the
+    picture really shows, so unlike --correct's working-space pair (bt601 both ways, see
+    _rgb_stage) these legs use the BT.709 the picture is: an identity LUT then returns every sample
+    as --lut-strength 0, which applies none, does (6.1, BT.709/BT.601/untagged, limited and full
+    range, 8- and 10-bit). The input range is read from the frames, as every scale here reads it."""
+    # --codec prores keeps a BT.601 (or other non-BT.709) source's matrix and tags instead of
+    # converting it (decision.video_args), so the legs use that matrix (#416 review)
+    matrix = "bt709"
+    if STATE.codec == "prores":
+        matrix = _SWS_MATRIX.get(((meta or {}).get("video") or {}).get("color_space"), "bt709")
+    return (f"scale=in_color_matrix={matrix},format=gbrpf32le",
+            f"scale=out_color_matrix={matrix}:out_range=tv,format=yuv420p")
+
+
 def hdr_to_sdr_chain(meta: dict, tonemap: str, peak: float, desat: float) -> str:
     v = meta["video"]
     trc = v.get("color_transfer") or "smpte2084"
@@ -442,6 +469,7 @@ def main() -> int:
         if not (0.0 <= args.lut_strength <= 1.0):
             die(f"--lut-strength {args.lut_strength:g} is outside 0..1")
         lut = f"lut3d=file={escape_filter_path(args.lut)}:interp=tetrahedral"
+        to_rgb, to_yuv = lut_legs(meta)
         if args.lut_strength == 0.0:
             # 0 means "no LUT at all" -- without this branch, 0 (falling outside the open interval
             # below) landed in the same "apply the LUT at full strength" fallback as an out-of-range
@@ -450,9 +478,10 @@ def main() -> int:
             vf = "format=yuv420p"
         elif args.lut_strength < 1.0:
             # blend graded and original
-            vf = f"split[o][g];[g]{lut}[g2];[o][g2]blend=all_mode=normal:all_opacity={args.lut_strength:g},format=yuv420p"
+            # blended in RGB, both pictures through the same two legs
+            vf = f"{to_rgb},split[o][g];[g]{lut}[g2];[o][g2]blend=all_mode=normal:all_opacity={args.lut_strength:g},{to_yuv}"
         else:
-            vf = f"{lut},format=yuv420p"
+            vf = f"{to_rgb},{lut},{to_yuv}"
         output = args.output or default_output(args.input, "lut")
         tag = "lut"
 

package/scripts/crop.py

@@ -22,6 +22,8 @@ import argparse
 import sys
 
 from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run, video_args, X264_PRESETS, fmt_secs
+from _common.probe import display_size, square_pixels, square_pixels_note
+from _common.emit import note
 
 
 def main() -> int:
@@ -51,15 +53,18 @@ def main() -> int:
     meta = probe(args.input)
     if not meta.get("video"):
         die("input has no video stream")
-    sw, sh = meta["video"]["width"], meta["video"]["height"]
-    if meta["video"].get("rotation") in (90, -90, 270, -270):
-        sw, sh = sh, sw
+    # the rectangle is in the displayed frame cropdetect.py reports: rotation applied, and a
+    # non-square-pixel source squared at its display aspect first (#411)
+    sw, sh = display_size(meta["video"])
     if args.x + args.width > sw or args.y + args.height > sh:
         die(f"crop rectangle ({args.x},{args.y},{args.width}x{args.height}) exceeds the source frame ({sw}x{sh})")
     has_audio = bool(meta.get("audio"))
 
     output = args.output or default_output(args.input, "crop")
     vf = [f"crop={args.width}:{args.height}:{args.x}:{args.y}", "setsar=1"]
+    if square_pixels(meta["video"]):
+        vf.insert(0, square_pixels(meta["video"]))
+        note(square_pixels_note(meta["video"]))
     cmd = ffmpeg_base() + ["-i", args.input, "-vf", ",".join(vf)]
     cmd += video_args(meta, args.crf, args.preset)
     cmd += cfr_args(meta, args.fps)