ffmpeg-skill 3.8.10 → 3.8.12

package/scripts/overlay.py

@@ -38,7 +38,7 @@ from _common import still_input_args  # noqa: E402
 from _common import STATE, script_font_for_text, drawtext_clean, drawtext_line_metrics, drawtext_text_opts, drawtext_draws_newline_glyph, is_multiline, needs_shaping, LANGUAGE_NAMES, has_emoji, detect_script, emoji_clusters, load_brand, drawn_chain, label_chain, layer_base_chain, matrix_chain, overlay_format, range_chain, rgb_chain_to_bt709, video_args, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_drawtext, ffmpeg_base, info, parse_time, probe, run, run_keeping_subtitles, validate_color, x264_args, X264_PRESETS, time_arg, fmt_secs
 from _common.emit import note, warn
 from _common.color import is_rgb
-from _common.decision import length_output_t
+from _common.decision import length_output_t, window_expr, windowed_overlay_x
 from _common.alpha import (add_alpha_args, audio_line, check_alpha_args, decoder_args_for, default_ext, finish_chain,
                            has_alpha_plane, report as alpha_report, source_alpha, source_format, tag_args, video_line)
 from _common.probe import display_size, refuse_not_a_still, square_pixels, square_pixels_note
@@ -128,13 +128,12 @@ def _wrap_to_frame(args, frame_w: int, margins: Optional[dict], frame_h: int = 0
     return wrapped
 
 
-def enable_expr(start: Optional[float], end: Optional[float]) -> str:
+def enable_expr(start: Optional[float], end: Optional[float], meta: Optional[dict] = None) -> str:
+    """True on the main picture's frames from --start to --end, both inclusive (window_expr):
+    the bounds sit half a frame from the frames they select, not on a frame's own time."""
     if start is None and end is None:
         return ""
-    s = f"{start:.3f}" if start is not None else "0"
-    if end is None:
-        return f"gte(t,{s})"
-    return f"between(t,{s},{end:.3f})"
+    return window_expr(start, end, meta)
 
 
 def alpha_expr(opacity: float, start: Optional[float], end: Optional[float], fade: float) -> str:
@@ -440,7 +439,7 @@ def main() -> int:
             "from --start to --end without a fade", hint="drop --fade for the video layer")
 
     output = args.output or default_output(args.input, "overlay", default_ext(alpha_codec) if alpha_codec else None)
-    enable = enable_expr(start, end)
+    enable = enable_expr(start, end, meta)
     cmd = ffmpeg_base() + ["-i", args.input]
 
     if args.image:
@@ -464,9 +463,9 @@ def main() -> int:
         x, y = position_exprs(args.position, args.margin, text_mode=False, margins=safe_margins)
         # a 10-bit main on a 10-bit line is composited at 10 bits in YUV: format=auto with an RGBA
         # still took the whole picture through 8-bit RGB (overlay_format)
-        ov = f"overlay={x}:{y}" + (overlay_format(meta) or ":format=auto")
-        if enable:
-            ov += f":enable='{enable}'"
+        # a --start/--end window is in the layer's position, which is evaluated on the main
+        # picture's frames; overlay's enable is evaluated on the layer's frames too
+        ov = f"overlay={windowed_overlay_x(x, enable) if enable else x}:{y}" + (overlay_format(meta) or ":format=auto")
         # -loop 1 turns the still into a timed stream so fade/enable expressions see real timestamps
         cmd = ffmpeg_base() + ["-i", args.input, "-loop", "1", *still_input_args(args.image), "-i", args.image]
         # the RGBA still is converted to the BT.709 the output is tagged with (overlay's own
@@ -545,9 +544,9 @@ def main() -> int:
             # which came back BT.601 under the BT.709 tag (#333's defect, on this path)
             chain.append(f"lut=y=val:u=val:v=val:a=val*{args.opacity:g}")
         x, y = position_exprs(args.position, args.margin, text_mode=False, margins=safe_margins)
-        ov = f"overlay={x}:{y}" + (overlay_format(meta) or ":format=auto")
-        if enable:
-            ov += f":enable='{enable}'"
+        # a --start/--end window is in the layer's position, which is evaluated on the main
+        # picture's frames; overlay's enable is evaluated on the layer's frames too
+        ov = f"overlay={windowed_overlay_x(x, enable) if enable else x}:{y}" + (overlay_format(meta) or ":format=auto")
         # a VP9 layer stored with an alpha layer is decoded with libvpx-vp9: FFmpeg's own decoder
         # drops the alpha, and the layer covered the picture as an opaque rectangle
         cmd = ffmpeg_base() + ["-i", args.input] + decoder_args_for(pip_meta, args.video) + ["-i", args.video]

package/scripts/pad.py

@@ -16,8 +16,8 @@ Examples:
 import argparse
 import sys
 
-from _common.emit import record_fallback
-from _common.decision import silence_filter
+from _common.emit import note, record_fallback
+from _common.decision import silence_filter, tpad_length
 from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, drawn_chain, emit, EVEN_SCALE, ffmpeg_base, info, probe, run_keeping_subtitles, validate_color, video_args, X264_PRESETS, time_arg, fmt_secs, run
 
 
@@ -65,8 +65,16 @@ def main() -> int:
             # front (one -filter_complex), so the record is made here, as broll and stabilize do
             record_fallback(f"{args.input} is {v.get('width')}x{v.get('height')}: scaled to even dimensions first",
                             "odd_dimensions_scaled_even", output=output, scale=EVEN_SCALE)
-        # the silence is counted in samples when --start/--end is not a whole millisecond
-        af = silence_filter(meta["audio"].get("sample_rate"), args.start, args.end)
+        # The sound is delayed by what the picture is: tpad puts whole frames ahead of the clip
+        # (--start 0.23425 at 25 fps: 6 frames, 0.240 s), and a delay of --start itself moved the
+        # sound 5.75 ms ahead of its picture (tpad_length). The silence after the clip moves
+        # nothing and is --end as asked. Either is counted in samples when it is not a whole
+        # millisecond (silence_filter).
+        lead = tpad_length(args.start, meta)
+        if abs(lead - args.start) > 1e-9:
+            note(f"--start {args.start:g}: the picture can only be padded by whole frames, {lead:.6f} s here; "
+                 f"the sound is delayed by the same {lead:.6f} s so the clip keeps its sync")
+        af = silence_filter(meta["audio"].get("sample_rate"), lead, args.end)
         cmd += ["-filter_complex", f"[0:v:0]{even}{vf}[v];[0:a:0]{af}[a]", "-map", "[v]", "-map", "[a]"]
     else:
         cmd += ["-vf", vf, "-map", "0:v:0"]

package/scripts/redact.py

@@ -101,7 +101,14 @@ def main() -> int:
                                (square + "," if square else "") + f"delogo=x={args.x}:y={args.y}:w={args.width}:h={args.height}",
                                "-map", "0:v:0"]
     else:
-        crop = f"crop={args.width}:{args.height}:{args.x}:{args.y}"
+        # exact=1: crop rounds an odd x/y down to the chroma grid of a 4:2:0 frame otherwise, and
+        # overlay always does, so an odd rectangle was taken from and put back one pixel up and
+        # left (its last column and row left as they were, one outside it changed: A170). The
+        # patch is taken exactly, given a transparent first column/row where x/y is odd, and put
+        # at the even position before it: the luma inside the rectangle is replaced, the luma
+        # outside is not (the chroma pair on an odd edge is shared, so it is half mixed)
+        crop = f"crop={args.width}:{args.height}:{args.x}:{args.y}:exact=1"
+        ox, oy = args.x % 2, args.y % 2
         if args.mode == "blur":
             # boxblur refuses a radius above half the plane: the chroma planes of 4:2:0 are half-size,
             # so they get their own (halved) radius; a 30 px region with the default 20 used to fail
@@ -110,7 +117,12 @@ def main() -> int:
             region = f"{crop},boxblur={radius}:{radius}:{chroma}:{radius}"
         else:
             region = f"{crop},scale={max(1, args.width // args.block_size)}:{max(1, args.height // args.block_size)}:flags=neighbor,scale={args.width}:{args.height}:flags=neighbor"
-        fc = f"[0:v]{square + ',' if square else ''}split=2[base][region];[region]{region}[patched];[base][patched]overlay={args.x}:{args.y}{overlay_format(meta)}[out]"
+        if ox or oy:
+            deep = overlay_format(meta)
+            region += (f",format=yuva444p{'10le' if deep else ''},"
+                       f"pad={args.width + 2 * ox}:{args.height + 2 * oy}:{ox}:{oy}:color=black@0")
+        fc = (f"[0:v]{square + ',' if square else ''}split=2[base][region];[region]{region}[patched];"
+              f"[base][patched]overlay={args.x - ox}:{args.y - oy}{overlay_format(meta)}[out]")
         cmd = ffmpeg_base() + ["-i", args.input, "-filter_complex", fc, "-map", "[out]"]
     if has_audio:
         cmd += ["-map", f"0:a:{args.audio_stream}?"]

package/scripts/render.py

@@ -74,7 +74,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 guard_sidecar, STATE, add_common, aspect_ratio, brand_caption_style, load_brand, apply_common, child_args, die, emit, info, option_args, probe, require_tool, run, run_tool, place_output, refuse_output_is_input, _check_existing_output, _check_output_path, fingerprint, PLAN_VERSION, ffmpeg_version, X264_PRESETS
+from _common import guard_sidecar, STATE, add_common, aspect_ratio, brand_caption_style, load_brand, apply_common, child_args, die, emit as _emit, info, option_args, probe, require_tool, run, run_tool, place_output, refuse_output_is_input, _check_existing_output, _check_output_path, fingerprint, PLAN_VERSION, ffmpeg_version, X264_PRESETS
 from _common.runner import HW_ENV, HW_FORCED_ENV, add_hw_orchestrator_args, child_exit_code, found_exe, kept_clause, kept_deliverables, mark_delivered, owned_identity, read_json, remember_written
 from _common.emit import absorb_stage, audit, record_fallback, record_skip, refuse, warn
 from _common.decision import rebase_project_paths
@@ -691,6 +691,59 @@ def check_snap_to(snap: Any, label: str) -> None:
 
 _LAST_DOC: Dict[str, Any] = {}   # the JSON document the most recent sh() child printed
 
+# source_carry for a render (A255): the one picture/sound source of a project with one, and what
+# each stage that ran said about the start timecode ("kept", "dropped", None: a stage that compared
+# nothing, "unknown": a cache hit whose entry did not keep it). main() resets both.
+PROJECT_SOURCE: Dict[str, Any] = {"src": None, "timecode": []}
+
+
+def _timecode_verdict(doc: Any) -> Optional[str]:
+    """What a stage's document says about the start timecode: "kept", "dropped", or None when its
+    source_carry compared none."""
+    carry = doc.get("source_carry") if isinstance(doc, dict) else None
+    if not isinstance(carry, dict):
+        return None
+    return "dropped" if "timecode" in (carry.get("dropped") or []) else "kept" if "timecode" in (carry.get("kept") or []) else None
+
+
+def project_source(proj: Dict[str, Any], rel) -> Optional[str]:
+    """The project's single picture/sound source -- its clips all one file, and no music,
+    replacement or effects track, no video layer and no audiogram picture beside it -- or None,
+    when the output mixes several (source_carry is then not compared, as for any tool with two
+    sources)."""
+    srcs = {os.path.realpath(rel(c["src"])) for c in proj.get("clips") or [] if isinstance(c, dict) and isinstance(c.get("src"), str)}
+    audio = proj.get("audio") if isinstance(proj.get("audio"), dict) else {}
+    others = [audio.get(k) for k in ("music", "replace", "effects") if audio.get(k)]
+    overlays = proj.get("overlays") if isinstance(proj.get("overlays"), list) else []
+    others += [ov.get("video") for ov in overlays if isinstance(ov, dict) and ov.get("video")]
+    if proj.get("audiogram"):
+        others.append("audiogram")  # the picture is the waveform over an image, not the clip's
+    return next(iter(srcs)) if len(srcs) == 1 and not others else None
+
+
+def emit(output: Optional[str], **extra: Any) -> None:
+    """emit(), with render.py's source_carry: the stages run as children, so this process never
+    probed the project's source as an input and its result carried no source_carry at all, even
+    for a one-clip render that lost the source's subtitle track (A255). The source is probed here
+    (after the stages' intermediates, which are not sources), so emit() compares it with the
+    delivered file. A stage that moves the picture's start writes the label of the frame it starts
+    on, which is not the source's: the timecode counts as kept when every stage that compared it
+    kept it, as dropped when one dropped it, and is compared with the source's own label when no
+    stage said (nothing ran, or a cache entry written before stages' source_carry was kept)."""
+    src = PROJECT_SOURCE.get("src")
+    if src and output and not STATE.dry_run and os.path.isfile(src) and os.path.isfile(output) \
+            and os.path.realpath(src) != os.path.realpath(output) and "source_carry" not in extra:
+        STATE.first_input, STATE.video_inputs, STATE.audio_inputs = None, set(), set()
+        probe(src)
+        said = PROJECT_SOURCE["timecode"]
+        if "dropped" in said:
+            STATE.expected_timecode = ""
+        elif "kept" in said and "unknown" not in said:
+            STATE.expected_timecode = (probe(output, role="output").get("timecode") or {}).get("value") or ""
+        else:
+            STATE.expected_timecode = None
+    _emit(output, **extra)
+
 
 def _refuse_uncached_earlier_stage(stage: str) -> None:
     """--from STAGE promises the earlier stages come from the cache. When one does not, say so
@@ -783,6 +836,7 @@ def sh(script: str, *argv: Any, extra: List[str] = None, stage: str = None) -> s
             code=int(doc.get("exit_code") or 1), kind=err.get("kind") or "input", stage=script, error_extra=error_extra, **extra_fields)
     _LAST_DOC.clear()
     _LAST_DOC.update(doc if isinstance(doc, dict) else {})
+    PROJECT_SOURCE["timecode"].append(_timecode_verdict(doc))
     absorb_stage(Path(script).stem, doc)  # a stage's GPU facts (ran on VideoToolbox, fell back and why) and its diagnostics reach this result
     out_path = str(doc.get("output") or "")
     if not STATE.dry_run:
@@ -981,6 +1035,10 @@ def cache_lookup(stage: str, key: str, dest: str, tool: Optional[str] = None) ->
         shutil.copy2(art, dest)     # ... and a copy where it does not. Never a move: the cache
     CACHE["saved_seconds"] += float(meta.get("seconds") or 0.0)
     result = meta.get("result")
+    # what the stage said about the start timecode, for render's source_carry; an entry written
+    # before its source_carry was kept does not say
+    PROJECT_SOURCE["timecode"].append(_timecode_verdict(result) if isinstance(result, dict) and "source_carry" in result
+                                      else "unknown")
     if isinstance(result, dict):
         absorb_stage(tool or stage, dict(result, status="completed", dry_run=False))  # tagged as the stage's tool, as a live run is
     else:
@@ -994,7 +1052,9 @@ def _stage_result(doc: Any) -> Dict[str, Any]:
     """What a cache entry keeps of the stage's own --json document, replayed on a hit."""
     if not isinstance(doc, dict):
         return {}
-    return {k: doc[k] for k in ("verified", "verification", "notes", "diagnostics") if k in doc}
+    kept = {k: doc[k] for k in ("verified", "verification", "notes", "diagnostics") if k in doc}
+    kept["source_carry"] = doc.get("source_carry")  # None too: the stage compared nothing (render's source_carry)
+    return kept
 
 
 def cache_store(stage: str, key: str, produced: str, seconds: float, doc: Any = None) -> None:
@@ -1472,6 +1532,7 @@ def main() -> int:
     add_hw_orchestrator_args(ap)
     args = ap.parse_args()
     apply_common(args)
+    PROJECT_SOURCE.update(src=None, timecode=[])
     STATE.audit_log = os.path.abspath(args.audit_log) if args.audit_log else None
 
     if args.list_templates:
@@ -1650,6 +1711,7 @@ def main() -> int:
     CACHE.clear()
     CACHE.update(_fresh_cache())
     CONTENT_KEYED.clear()
+    PROJECT_SOURCE.update(src=project_source(proj, rel), timecode=[])
     if args.cache:
         cdir = Path(args.cache)
         try:

package/scripts/reverse.py

@@ -17,7 +17,8 @@ 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.emit import warn
-from _common.decision import av_clip_length, av_trim, frame_durations, frame_rate, stream_starts
+from _common.decision import (HELD_FRAMES_WARN_BYTES, av_clip_length, av_trim, delivered_rate, frame_durations, frame_rate,
+                              held_frames_bytes, stream_starts)
 
 
 def main() -> int:
@@ -37,10 +38,16 @@ def main() -> int:
     has_audio = bool(meta.get("audio")) and not args.no_audio
 
     output = args.output or default_output(args.input, "reverse")
-    if (meta.get("duration") or 0) > 60:
-        warn(f"reverse buffers every decoded frame in memory; {meta['duration']:.0f}s of "
-             f"{meta['video']['width']}x{meta['video']['height']} can exhaust RAM -- cut the part to reverse first (cut.py)",
-             "memory_heavy", duration=meta["duration"])
+    # keyed on what is held (every decoded frame), not on the length alone (A174): the estimate
+    # loop.py --boomerang warns from, over the frames of the picture's length at its rate
+    v = meta["video"]
+    vdur = v.get("duration") or meta.get("duration") or 0.0
+    frames = v.get("nb_frames") or vdur * (frame_rate(meta) or v.get("fps") or 30.0)
+    held = held_frames_bytes(v, frames)
+    if held > HELD_FRAMES_WARN_BYTES:
+        warn(f"reverse holds about {held / 1024 ** 3:.1f} GiB of decoded frames in memory "
+             f"({vdur:.0f}s of {v['width']}x{v['height']}) -- cut the part to reverse first (cut.py) if RAM is tight",
+             "memory_heavy", duration=meta.get("duration"), bytes=held)
     cmd = ffmpeg_base() + ["-i", args.input]
     if has_audio:
         # Both streams are reversed about one end (#409); each reversed about its own end put a sound
@@ -55,14 +62,20 @@ def main() -> int:
         # setpts: from FFmpeg 7.0 setpts leaves its output's frame rate unknown and its frames'
         # durations 0, so a tpad after it clones nothing (the picture stayed 0.6 s short on 7.1);
         # the closing fps gives the frames their durations back (frame_durations).
-        rate = frame_rate(meta) or meta["video"].get("fps") or 30.0
+        # the rate the encoder line delivers (cfr_args: a VFR source is conformed to its average
+        # rate), so the graph's closing fps and the output's -r are one grid: the graph closed on
+        # r_frame_rate and -r then resampled it, 51 frames for 49 that ran 81 ms past the sound (A234)
+        # The trim that drops the hold's spare clones stays on the source's own grid (half a frame
+        # of r_frame_rate before the end): half a delivered frame cut a real last frame that sits
+        # nearer the end than that, and reverse then opened on the one before it.
+        rate = delivered_rate(meta) or frame_rate(meta) or meta["video"].get("fps") or 30.0
         length = av_clip_length(meta, rate)
         vlen = meta["video"].get("duration") or length
         end = math.ceil(length * rate - 1e-6) / rate
         vtrim, atrim = av_trim(stream_starts(meta)[0], None)
         cmd += ["-filter_complex",
                 f"[0:v:0]tpad=stop_mode=clone:stop_duration={max(0.0, end - vlen) + 2 / rate:.6f},{vtrim},"
-                f"trim=end={end - 0.5 / rate:.6f},reverse,{frame_durations(meta, rate)}[v];"
+                f"trim=end={end - 0.5 / max(rate, frame_rate(meta) or rate):.6f},reverse,{frame_durations(meta, rate)}[v];"
                 f"[0:a:0]{atrim},apad=whole_dur={end:.6f},atrim=end={end:.6f},areverse,asetpts=N/SR/TB[a]",
                 "-map", "[v]", "-map", "[a]"]
     else:

package/scripts/straighten.py

@@ -80,9 +80,20 @@ def main() -> int:
         dw, dh = display_size(meta["video"])
         aspect = max(dw / dh, dh / dw) if dw and dh else 1.0
         s = abs(math.cos(radians)) + aspect * abs(math.sin(radians))
-        # crop dimensions must round down to even (4:2:0 chroma); trunc(.../2)*2 floors to the
-        # nearest even value instead of leaving an odd width/height that the encoder would refuse.
-        rotate = f"scale=iw*{s:.8f}:ih*{s:.8f},rotate={radians:.8f},crop=trunc(iw/{s:.8f}/2)*2:trunc(ih/{s:.8f}/2)*2"
+        # The window is the displayed frame's own size, to even (4:2:0 chroma), and the scaled frame
+        # is rounded UP to even so it still covers it. Scaling to iw*s and cropping back to
+        # trunc(iw/s/2)*2 lost to two roundings: 1920x1080 came out 1918x1078, and the scale's
+        # rounding left a non-square SAR such as 6112:6111 (A235).
+        cw, ch = (dw // 2 * 2, dh // 2 * 2) if dw and dh else (0, 0)
+        if cw and ch:
+            # the margin on each axis is a multiple of 4, so the centred crop's offset is even:
+            # crop floors an odd one to the chroma grid, which moved the window a pixel up and
+            # left and could bring the fill into the top-left corner
+            sw, sh = (c + math.ceil(max(0.0, c * s - c) / 4) * 4 for c in (cw, ch))
+            rotate = (f"scale={sw}:{sh},setsar=1,"
+                      f"rotate={radians:.8f},crop={cw}:{ch},setsar=1")
+        else:  # a dry run's pending input has no size yet: the old expression, planned only
+            rotate = f"scale=iw*{s:.8f}:ih*{s:.8f},rotate={radians:.8f},crop=trunc(iw/{s:.8f}/2)*2:trunc(ih/{s:.8f}/2)*2"
 
     # a rotation of non-square pixels is a shear on screen: the picture is squared at its
     # display aspect first (#411)

package/scripts/sync.py

@@ -441,8 +441,12 @@ def main() -> int:
                 # same command, and the seek stays next to the -i it drops the margin from
                 cmd += ["-i", args.second] + out_seek + default_selection_maps(second_meta, output)
                 af_parts = on_clock + drift_af
-                if delay_ms > 0:
-                    af_parts.append(f"adelay={delay_ms}:all=1")
+                # one sound is written here (the default selection, or the probed track of a file
+                # with several: default_selection_maps), the one sec_sr is the rate of, so the delay
+                # is counted in its samples as --replace-audio's is. A whole millisecond (the
+                # default --fine-ms 1 without --fix-drift) keeps `adelay=<ms>:all=1`
+                if offset > 0 and round(offset * sec_sr):
+                    af_parts.append(silence_filter(sec_sr, lead=offset))
                 if has_video:
                     vf = []
                     if delay_ms > 0: