ffmpeg-skill 3.8.15 → 3.8.17

package/scripts/_common/wrap.py

@@ -282,16 +282,32 @@ def _slice_atom(atom: str, max_em: float) -> "List[str]":
     No dictionary, no hyphenation library: an existing hyphen is preferred as the cut (the same
     break R1 already allows), then whatever is left is cut again at exactly the widest prefix
     that still measures within `max_em`, one character at a time. The characters themselves are
-    never rewritten -- every piece concatenates back to the original atom exactly."""
-    if text_width_em(atom) <= max_em:
-        return [atom]
-    for i in range(len(atom) - 2, 0, -1):
-        # latest hyphen whose left side still fits -- keeps the left half as large as possible
-        if atom[i] in _HYPHENS and text_width_em(atom[:i + 1]) <= max_em:
-            return [atom[:i + 1]] + _slice_atom(atom[i + 1:], max_em)
+    never rewritten -- every piece concatenates back to the original atom exactly.
+
+    Iterative, and each piece measures only the prefixes up to the first that is too wide (a
+    prefix is never narrower than a shorter one): the recursive form measured every prefix of the
+    remaining atom for each piece it cut, so a 1 KB hyphenated cue took seconds and 4 KB minutes
+    (A11, #465), in caption.py's own process, which --timeout (a limit on each ffmpeg call) does
+    not bound. The pieces are the ones the recursive form cut."""
     pieces: "List[str]" = []
+    rest = atom
+    while True:
+        # latest hyphen whose left side still fits -- keeps the left half as large as possible;
+        # a rest whose every prefix fits, itself included, is the last piece
+        cut = 0
+        for end in range(1, len(rest) + 1):
+            if text_width_em(rest[:end]) > max_em:
+                break
+            if 1 <= end - 1 <= len(rest) - 2 and rest[end - 1] in _HYPHENS:
+                cut = end
+        else:
+            return pieces + [rest]
+        if not cut:
+            break
+        pieces.append(rest[:cut])
+        rest = rest[cut:]
     cur = ""
-    for ch in atom:
+    for ch in rest:
         candidate = cur + ch
         if cur and text_width_em(candidate) > max_em:
             pieces.append(cur)

package/scripts/_contract.py

@@ -436,6 +436,7 @@ ERROR_REASONS = {
     "output_is_directory": "the output path is a directory; details: {output}",
     "media_path_is_playlist": "an input is a playlist that ffmpeg would follow to the files or URLs it names: HLS .m3u8/.m3u or an ffconcat list (by name or by its first bytes), a DASH manifest or an IMF composition playlist (by name or by the content ffmpeg's own probe looks for, whatever the file is called); the skill takes media files only; details: {path}",
     "media_path_has_line_break": "a path written into a concat list (loop.py, join.py --copy, sequence.py, multi-part cuts) contains a line break, which the concat format cannot hold: each line is a directive, so the name would add entries to the list; details: {path}",
+    "still_unreadable": "an input read by an image demuxer (a .png, .jpg, ... name) has a picture stream with no frame size: the file is not an image ffmpeg can decode (a text file named .png); details: {path, format, codec}",
     "media_path_not_a_file": "an input exists but is not a regular file (a FIFO or a device), which ffmpeg would block on or read as a stream; details: {path}",
     "join_copy_mismatch": "join.py --copy: a clip's streams do not match the first clip's, it hides pre-roll frames with an edit list, or its picture and sound end more than 50 ms apart; details: {clips: [{index?, path, differs}]}",
     "output_path_taken": "two files one run writes (a side file and the output, or two side files) resolve to the same path, so the second would replace the first; details: {output, other}",
@@ -446,7 +447,7 @@ ERROR_REASONS = {
     "output_dir_not_writable": "the output's directory is not writable; details: {output, directory}",
     "output_container_codecs": "a .webm output whose command encodes video or sound WebM cannot hold (H.264/HEVC, AAC; WebM takes VP8/VP9/AV1 and Opus/Vorbis), refused before ffmpeg runs; details: {output, container, encoders}",
     "timemap_path_taken": "silence.py --timemap names the same file as -o, --edl or --plan; details: {timemap, flag, path}",
-    "output_locked": "another run holds the output's lock; details: {lock, output, pid, pid_alive, deadline, why}",
+    "output_locked": "another run holds the output's lock, or is taking a stale one over (why: takeover_in_progress), or a stale lock cannot be taken over safely because the filesystem gives no OS file lock (why: takeover_unavailable: delete it by hand); details: {lock, output, pid, pid_alive, deadline, why}",
     "plan_inputs_changed": "render.py PLAN: a fingerprinted input is missing or changed; details: {plan, plan_sha256, checked_at, "
                            "inputs: [{path, status: unchanged|changed|missing, expected: {size, sha256_head_tail}, actual: {size, "
                            "sha256_head_tail} | \"missing\"}], unbound_inputs, audit_log}",
@@ -1943,6 +1944,11 @@ MCP_PROMPTS: List[Dict[str, Any]] = [
                      "to keep HDR and only drop the Dolby Vision layer, when strip_dovi is asked for). A flat, washed-out "
                      "look after a re-encode usually means HDR metadata was lost upstream; `probe` shows `hdr: true` "
                      "only for a real PQ/HLG/Dolby Vision signal, and `bt2020_or_hdr: true` also for BT.2020 SDR."),
+        # A23 (#465): strip_dovi was taken and changed nothing; true now asks for the other recipe
+        "flags": {"strip_dovi": (
+            "Keep {input} HDR and drop only its Dolby Vision layer: `color.py {input} --strip-dovi`, a stream copy "
+            "(HEVC only) that removes the Dolby Vision RPU so players use the HLG/HDR10 base layer. A source with no "
+            "Dolby Vision metadata gets a `dovi_not_detected` warning.")},
     },
 ]
 
@@ -1968,7 +1974,17 @@ def mcp_prompt_get(name: str, arguments: Dict[str, Any]) -> Dict[str, Any]:
     fields: Dict[str, str] = {a["name"]: str((arguments or {}).get(a["name"]) or a.get("default", "")) for a in prompt["arguments"]}
     for opt_name, clause in prompt["optional"].items():
         fields[opt_name] = clause.format(**fields) if fields.get(opt_name) else ""
-    text = prompt["template"].format(**fields)
+    template = prompt["template"]
+    for flag, flag_template in (prompt.get("flags") or {}).items():
+        # a yes/no argument picks the recipe; every prompt argument arrives as a string, so
+        # "false" is no, and a value that is neither is a caller mistake (ValueError, as above)
+        value = (arguments or {}).get(flag)
+        word = str(value).strip().lower() if value is not None else ""
+        if word in ("true", "1", "yes"):
+            template = flag_template
+        elif word not in ("", "false", "0", "no"):
+            raise ValueError(f"prompt {name!r}: {flag} must be true or false, got {value!r}")
+    text = template.format(**fields)
     return {"description": prompt["description"], "messages": [{"role": "user", "content": {"type": "text", "text": text}}]}
 
 

package/scripts/batch.py

@@ -699,10 +699,15 @@ def main() -> int:
     created = [d for d in (outdir, work) if not d.exists()]
     outdir.mkdir(parents=True, exist_ok=True)
     work.mkdir(parents=True, exist_ok=True)
-    if STATE.dry_run and created:
+    # a real run that is refused before any item starts (--jobs, an output collision, a final path
+    # that is an input) leaves nothing behind either (A187, #465: it left out/ and out/.work)
+    item_started = {"item": False}
+    if created:
         import atexit
 
         def _remove_empty_dirs() -> None:
+            if not STATE.dry_run and item_started["item"]:
+                return
             for d in sorted(created, key=lambda p: len(str(p)), reverse=True):
                 try:
                     if not any(d.iterdir()):
@@ -850,6 +855,7 @@ def main() -> int:
         def run_item(i: int, src: Path) -> Dict[str, Any]:
             """process() in the item's own work directory, which goes when it ends, however it ends."""
             import shutil
+            item_started["item"] = True
             iw = item_work(i, src)
             try:
                 return process(src, recipe, outdir, iw, deadline)

package/scripts/broll.py

@@ -24,7 +24,7 @@ from typing import Any, Dict, List
 
 from _common.decision import (av_trim, conform_output_t, conform_to_length, frame_durations, frame_rate, frame_window,
                               grid_at_or_after, silence_filter, stream_starts, window_expr, windowed_overlay_x)
-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, overlay_format, range_chain, probe, run, validate_color, video_args, X264_PRESETS, fmt_secs
+from _common import STATE, add_common, aac_args, apply_common, cfr_args, cfr_at_input, as_limited, default_output, die, draws_chroma, drawn_chain, emit, ffmpeg_base, info, time_arg, label_chain, matrix_chain, overlay_format, 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
 from _common.emit import input_length
@@ -242,7 +242,10 @@ def main() -> int:
             parts.append(f"{''.join(layers)}amix=inputs={len(layers)}:normalize=0:dropout_transition=0,{tail}[aout]")
             aout = "[aout]"
 
-    cmd += ["-filter_complex", ";".join(parts), "-map", vout]
+    # a VFR A-roll is conformed by the fps filter as it is decoded, at the rate cfr_args() delivers:
+    # -fps_mode cfr alone let a frame run up to two frames late against the sound (#512)
+    graph = cfr_at_input(";".join(parts), meta_a)
+    cmd += ["-filter_complex", graph, "-map", vout]
     if aout:
         cmd += ["-map", aout]
     cmd += video_args(meta_a, args.crf, args.preset, convert_matrix=False) + cfr_args(meta_a, None)

package/scripts/caption.py

@@ -46,7 +46,7 @@ from _ass_overlay import (EMOJI_SENTINEL, emoji_placeholder, ass_escape_markup,
                           strip_srt_markup, reinsert_srt_markup, carry_srt_markup, srt_alignment)
 from _common.emit import refuse  # noqa: E402
 from _common.emoji import emoji_missing_asset_note, emoji_mono_on_colour_note
-from _common import require_filter, emoji_filter_chain, EMOJI_ASSET_HINT, emoji_asset_for, emoji_codepoint_name, emoji_support, resolve_emoji_assets, NO_SPACE_SCRIPTS, 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, layer_base_chain, load_brand, overlay_format, rgb_chain_to_bt709, video_args, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, fmt_smpte_time, info, MissingFpsError, parse_time, probe, run, X264_PRESETS, read_text_or_die, fmt_secs, refuse_existing_outputs, guard_sidecar
+from _common import require_filter, emoji_filter_chain, EMOJI_ASSET_HINT, emoji_asset_for, emoji_codepoint_name, emoji_support, resolve_emoji_assets, NO_SPACE_SCRIPTS, 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, layer_base_chain, load_brand, overlay_format, rgb_chain_to_bt709, video_args, add_common, apply_common, emit, aac_args, cfr_args, cfr_at_input, with_cfr, default_output, die, escape_filter_path, ffmpeg_base, fmt_smpte_time, info, MissingFpsError, parse_time, probe, run, 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
@@ -55,7 +55,7 @@ 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.runner import carried_stream_maps, subtitle_codec_for, subtitle_container_holds
+from _common.runner import carried_stream_maps, refuse_output_is_input, same_file, subtitle_codec_for, subtitle_container_holds
 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)
@@ -1586,9 +1586,12 @@ def main() -> int:
             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", "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, "video"))
+        # -o naming the input (the same name, a hard link, another case on a case-insensitive
+        # volume) is refused here, before any sidecar or transcript is written: run()'s own guard
+        # came after the .srt was already beside it (review of #530)
+        if same_file(planned_out, args.input):
+            refuse_output_is_input(planned_out, args.input, why="the captioned video would replace the source")
+        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
@@ -2082,10 +2085,11 @@ def main() -> int:
             asset = spec[-1]
             if asset not in STATE.plan_inputs:
                 STATE.plan_inputs.append(asset)
-        graph = ";".join([f"[0:v]{vf}[vsub]"] + chains)
+        # the conform of a VFR source is the fps filter at the end of the chain (#512)
+        graph = cfr_at_input(";".join([f"[0:v]{vf}[vsub]"] + chains), meta)
         cmd += ["-filter_complex", graph, "-map", "[vout]"]
     else:
-        cmd += ["-map", "0:v:0", "-vf", vf]
+        cmd += ["-map", "0:v:0", "-vf", with_cfr(vf, meta)]
     if meta.get("audio"):
         cmd += ["-map", f"0:a:{args.audio_stream}"]
     cmd += video_args(meta, args.crf, args.preset) + cfr_args(meta)

package/scripts/color.py

@@ -33,7 +33,7 @@ import sys
 from typing import List, Optional
 
 from _common.runner import carried_stream_maps, fail_if_classified
-from _common import STATE, add_common, analyze_levels, LEGAL_RANGE_CHOICES, legal_limits, measure_signal_range, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, ffmpeg_bsfs, info, probe, require_tool, run, run_analysis, run_keeping_subtitles, x264_args, X264_PRESETS, fmt_secs
+from _common import STATE, add_common, analyze_levels, LEGAL_RANGE_CHOICES, legal_limits, measure_signal_range, apply_common, emit, aac_args, cfr_args, cfr_at_input, with_cfr, default_output, die, escape_filter_path, ffmpeg_base, ffmpeg_bsfs, info, probe, require_tool, run, run_analysis, run_keeping_subtitles, x264_args, X264_PRESETS, fmt_secs
 from _common.emit import note, warn
 from _common.color import is_rgb, rgb_to_bt709_filter
 from _common.alpha import (add_alpha_args, audio_line, check_alpha_args, decoder_args_for, default_ext, finish_chain,
@@ -648,13 +648,14 @@ def main() -> int:
         # converts the graded YUV in front of alphamerge, so the matrix is labelled there too
         fc = (f"[0:v]split[ka_c][ka_a];[ka_c]{vf}{matrix_label(meta)}[ka_g];[ka_a]alphaextract[ka_m];"
               f"[ka_g][ka_m]alphamerge,{finish_chain(alpha_codec, args.alpha_mode, meta)}[ka_v]")
+        fc = cfr_at_input(fc, meta)  # the conform of a VFR source: the fps filter (#512)
         cmd = ffmpeg_base() + decoder_args_for(meta, args.input) + ["-i", args.input, "-filter_complex", fc,
                                                                      "-map", "[ka_v]", "-map", f"0:a:{args.audio_stream}?"]
         cmd += video_line(alpha_codec) + tag_args(meta) + cfr_args(meta) + (audio_line(alpha_codec) if has_audio else [])
         if STATE.hw:
             note(f"--hw: --alpha-codec {alpha_codec} stays on the CPU (no VideoToolbox encoder writes it with its alpha)")
     else:
-        cmd = ffmpeg_base() + ["-i", args.input, "-vf", vf, "-map", "0:v:0", "-map", f"0:a:{args.audio_stream}?"]
+        cmd = ffmpeg_base() + ["-i", args.input, "-vf", with_cfr(vf, meta), "-map", "0:v:0", "-map", f"0:a:{args.audio_stream}?"]
         # --lut/--correct grade the source's own pixels, so a BT.601 source is converted to the BT.709
         # the line is tagged with; --to-sdr's zscale chain already writes BT.709 and converts nothing more
         cmd += x264_args(args.crf, args.preset, source=None if args.to_sdr else meta) + cfr_args(meta) + (aac_args() if has_audio else [])

package/scripts/crop.py

@@ -22,7 +22,7 @@ Examples:
 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 import add_common, apply_common, aac_args, cfr_args, with_cfr, 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.runner import default_selection_maps
 from _common.emit import note
@@ -70,7 +70,7 @@ def main() -> int:
         vf.insert(0, square_pixels(meta["video"]))
         note(square_pixels_note(meta["video"]))
     # the picture the rectangle was checked against, not the largest one default selection takes
-    cmd = ffmpeg_base() + ["-i", args.input] + default_selection_maps(meta, output) + ["-vf", ",".join(vf)]
+    cmd = ffmpeg_base() + ["-i", args.input] + default_selection_maps(meta, output) + ["-vf", with_cfr(",".join(vf), meta, args.fps)]
     cmd += video_args(meta, args.crf, args.preset)
     cmd += cfr_args(meta, args.fps)
     if has_audio:

package/scripts/cut.py

@@ -65,7 +65,7 @@ from _common.probe import PROBED_AUDIO, PROBED_VIDEO, TS_EXTS, probed_maps, seve
 from _common.runner import subtitle_codec_for, subtitle_container_holds
 from _common.decision import SEEK_MARGIN, delivered_rate, frame_rate, grid_at_or_after, stream_starts
 from _common.timeline import output_timecode_args
-from _common import warn, record_fallback, refuse_existing_outputs, sibling_temp, source_codec_video_args, STATE, add_common, apply_common, audio_codec_for, emit, aac_args, cfr_args, default_output, die, ffmpeg_base, info, is_audio_output, time_arg, probe, run, X264_PRESETS, keyframes_near, concat_list_line, place_output, refuse_output_is_input, fmt_secs, measure_frame_timing, dry_run_input_pending
+from _common import warn, record_fallback, refuse_existing_outputs, sibling_temp, source_codec_video_args, STATE, add_common, apply_common, audio_codec_for, emit, aac_args, cfr_args, cfr_filter, graph_with_cfr, default_output, die, ffmpeg_base, info, is_audio_output, time_arg, probe, run, X264_PRESETS, keyframes_near, concat_list_line, place_output, refuse_output_is_input, fmt_secs, measure_frame_timing, dry_run_input_pending
 
 # outputs whose re-encode dropped a subtitle/data stream (reported as dropped_non_av_streams)
 DROPPED_STREAMS: List[str] = []
@@ -925,6 +925,9 @@ def cut_one(src: str, start: float, end: float, dst: str, reencode: bool, crf: i
             m = min(SEEK_MARGIN, start)
             cmd = ffmpeg_base() + ["-ss", f"{start - m:.6f}", "-i", src, "-ss", f"{m:.6f}", "-t", f"{dur:.6f}"]
             cmd += stream_maps(meta, dst, copy=False)
+            # a VFR source is conformed by the fps filter at the rate cfr_args() delivers: the
+            # encoder line's -fps_mode cfr alone let a frame run up to two frames late (#512)
+            cmd += ["-vf", cfr_filter(meta)] if cfr_filter(meta) else []
         # ffmpeg's default stream selection also picks one subtitle stream; a re-encode cannot
         # trim it (the cues kept their timestamps and the container grew to 2 s for a 1 s cut,
         # sweep F2), so the re-encode carries video/audio only and the result says so
@@ -1162,8 +1165,11 @@ def _join_chunk(src: str, segments: List[Tuple[float, float]], dst: str, meta: d
             pads += f"[a{i}]"
     outs = ("[v]" if has_v else "") + ("[a]" if has_a else "")
     graph.append(f"{pads}concat=n={len(segments)}:v={int(has_v)}:a={int(has_a)}{outs}")
-    cmd += ["-filter_complex", ";".join(graph)]
-    for pad in ("[v]" if has_v else None, "[a]" if has_a else None):
+    # a VFR source is conformed by the fps filter after the concat, at the rate cfr_args() delivers
+    # (#512); a constant-rate source's graph is unchanged
+    fc, vpad = graph_with_cfr(";".join(graph), "[v]", meta) if has_v else (";".join(graph), None)
+    cmd += ["-filter_complex", fc]
+    for pad in (vpad, "[a]" if has_a else None):
         if pad:
             cmd += ["-map", pad]
     if intermediate:

package/scripts/deinterlace.py

@@ -22,7 +22,7 @@ Examples:
 import argparse
 import sys
 
-from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run_keeping_subtitles, video_args, X264_PRESETS, fmt_secs
+from _common import add_common, apply_common, aac_args, cfr_args, with_cfr, default_output, die, emit, ffmpeg_base, info, probe, run_keeping_subtitles, video_args, X264_PRESETS, fmt_secs
 
 MODES = {"frame": 0, "field": 1}
 PARITIES = {"auto": -1, "tff": 0, "bff": 1}
@@ -58,16 +58,21 @@ def main() -> int:
     output = args.output or default_output(args.input, "deint")
 
     vf = f"yadif=mode={MODES[args.mode]}:parity={PARITIES[args.parity]}:deint={1 if args.only_interlaced else 0}"
-    cmd = ffmpeg_base() + ["-i", args.input, "-vf", vf, "-map", "0:v:0"]
-    if has_audio:
-        cmd += ["-map", f"0:a:{args.audio_stream}?"]
-    cmd += video_args(meta, args.crf, args.preset)
+    # the conform is the fps filter at the end of the chain, the rate the encoder line delivers:
+    # its -fps_mode cfr alone let a frame run up to two frames late (#512)
     if args.mode == "field":
         v = meta["video"]
         src_fps = v.get("fps") or 30.0
-        cmd += ["-fps_mode", "cfr", "-r", f"{src_fps * 2:g}"]
+        rate_args = ["-fps_mode", "cfr", "-r", f"{src_fps * 2:g}"]
+        vf += f",fps={src_fps * 2:g}"
     else:
-        cmd += cfr_args(meta)
+        rate_args = cfr_args(meta)
+        vf = with_cfr(vf, meta)
+    cmd = ffmpeg_base() + ["-i", args.input, "-vf", vf, "-map", "0:v:0"]
+    if has_audio:
+        cmd += ["-map", f"0:a:{args.audio_stream}?"]
+    cmd += video_args(meta, args.crf, args.preset)
+    cmd += rate_args
     if has_audio:
         cmd += aac_args()
     else:

package/scripts/denoise.py

@@ -18,7 +18,7 @@ Examples:
 import argparse
 import sys
 
-from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run_keeping_subtitles, video_args, X264_PRESETS, fmt_secs
+from _common import add_common, apply_common, aac_args, cfr_args, with_cfr, default_output, die, emit, ffmpeg_base, info, probe, run_keeping_subtitles, video_args, X264_PRESETS, fmt_secs
 
 # hqdn3d's own AVOptions default to 0 (off); these tested presets are the light/medium/heavy
 # starting points its own documentation and common usage recommend (spatial then temporal,
@@ -72,7 +72,7 @@ def main() -> int:
     output = args.output or default_output(args.input, "denoise")
 
     vf = f"hqdn3d={ls:g}:{cs:g}:{lt:g}:{ct:g}"
-    cmd = ffmpeg_base() + ["-i", args.input, "-vf", vf, "-map", "0:v:0"]
+    cmd = ffmpeg_base() + ["-i", args.input, "-vf", with_cfr(vf, meta, args.fps), "-map", "0:v:0"]
     if has_audio:
         cmd += ["-map", f"0:a:{args.audio_stream}?"]
     cmd += video_args(meta, args.crf, args.preset)

package/scripts/export.py

@@ -48,8 +48,8 @@ from pathlib import Path
 from typing import Dict, List, Optional
 
 from _common.runner import carried_stream_maps, child_exit_code, fail_if_classified, kept_clause, mark_delivered
-from _common import STATE, run_analysis, add_common, apply_common, bt709_label_filter, bt709_matrix_args, bt709_tag_args, child_args, emit, cfr_args, default_output, die, encoder_args, ffmpeg_base, info, probe, require_tool, run, run_tool, validate_color, pad_filters, add_pad_fill_args, fmt_secs
-from _common.decision import hw_preset_video, restate_last_swap
+from _common import STATE, run_analysis, add_common, apply_common, bt709_label_filter, bt709_matrix_args, bt709_tag_args, child_args, emit, cfr_args, cfr_filter, default_output, die, encoder_args, ffmpeg_base, info, probe, require_tool, run, run_tool, validate_color, pad_filters, add_pad_fill_args, fmt_secs
+from _common.decision import chain_with_rate, hw_preset_video, restate_last_swap
 from _common.emit import note, record_fallback, record_skip, warn
 from _common.probe import PROBED_AUDIO, PROBED_VIDEO, probed_maps, square_pixels, square_pixels_note
 from _common.runner import ffmpeg_encoders, guard_sidecar, remember_written, replace_checked, replace_checked_together, reserve_sibling, subtitle_codec_for
@@ -207,7 +207,11 @@ def _key_fill(args, p: Dict, meta: Dict, output: str, cmd: List[str], vf: List[s
     key_chain = ",".join(vf + ["alphaextract", "scale=in_range=pc:out_range=tv", "format=yuv422p10le"])
     tc = ((meta.get("timecode") or {}).get("value"))
     tc_args = ["-timecode", tc] if tc else []
-    cmd = cmd + ["-filter_complex", f"[0:{PROBED_VIDEO}]split[f][k];[f]{fill_chain}[fill];[k]{key_chain}[key]"]
+    # a VFR source is conformed by the fps filter, once, ahead of the split: both files hold the same
+    # frames, and -fps_mode cfr alone let a frame run up to two frames late against the sound (#512)
+    conform = cfr_filter(meta)
+    cmd = cmd + ["-filter_complex", f"[0:{PROBED_VIDEO}]{conform + ',' if conform else ''}split[f][k];"
+                                    f"[f]{fill_chain}[fill];[k]{key_chain}[key]"]
     cmd += ["-map", "[fill]"] + probed_maps(meta, video=False, audio=has_audio) + p["video"] + tc_args + cfr_args(meta)
     # the fill is always written to a hidden sibling and moved into place only after the encode
     # succeeds: run() stages and cleans up only ffmpeg's last output (the key), so a failed encode
@@ -696,8 +700,23 @@ def main() -> int:
     if args.preset != "copy":
         # a stream copy can't be frame-rate-conformed or retagged without decoding it — that would
         # no longer be a copy, and would silently mislabel colour the agent never actually looked at
+        rate_args: List[str] = []
         if "-r" not in video:
-            cmd += _platform_rate_args(args.preset, meta) or cfr_args(meta)
+            rate_args = _platform_rate_args(args.preset, meta) or cfr_args(meta)
+            cmd += rate_args
+        # the rate the line delivers (a preset's own -r, a platform's divided rate, or a VFR
+        # source's average) is reached by the fps filter, the nearest frame for each slot: the
+        # encoder line's -r alone let a frame run up to two frames late against the sound before
+        # it dropped one (#512)
+        rate_f = (f"fps={video[video.index('-r') + 1]}" if "-r" in video
+                  else f"fps={rate_args[rate_args.index('-r') + 1]}" if "-r" in rate_args else "")
+        # it is placed as with_cfr() places it: first in a -vf that is a graph (a blur pad's
+        # split/overlay, a drawn pad's maskedmerge), whose last frame an fps filter after it lost
+        # on FFmpeg 6.1 (reels --pad-fill blur: 119 frames of a 4 s 30 fps picture)
+        if rate_f and "-vf" in cmd:
+            cmd[cmd.index("-vf") + 1] = chain_with_rate(cmd[cmd.index("-vf") + 1], rate_f)
+        elif rate_f:
+            cmd += ["-vf", rate_f]
         if tag_bt709 and not video[video.index("-c:v") + 1].endswith("_videotoolbox"):
             cmd += bt709_tag_args(video[video.index("-c:v") + 1])
         if not p.get("intermediate"):

package/scripts/fit.py

@@ -38,9 +38,9 @@ import sys
 from fractions import Fraction
 from typing import List
 
-from _common.decision import SEEK_MARGIN, delivered_rate, frame_rate, grid_at_or_after, length_output_t, stream_starts
+from _common.decision import SEEK_MARGIN, delivered_rate, frame_durations, frame_rate, grid_at_or_after, length_output_t, stream_starts
 from _common.timeline import exact_rate, output_timecode_args
-from _common import video_args, STATE, add_common, apply_common, emit, aac_args, aspect_ratio, cfr_args, default_output, die, ffmpeg_base, info, probe, run, run_keeping_subtitles, validate_color, pad_filters, add_pad_fill_args, X264_PRESETS, time_arg, fmt_secs, frame_size, display_size, square_pixels, square_pixels_note, note
+from _common import video_args, STATE, add_common, apply_common, emit, aac_args, aspect_ratio, cfr_args, cfr_filter, default_output, die, ffmpeg_base, info, probe, run, run_keeping_subtitles, validate_color, pad_filters, add_pad_fill_args, X264_PRESETS, time_arg, fmt_secs, frame_size, display_size, square_pixels, square_pixels_note, note
 from _common.emit import input_length
 BLUR_DARKEN = 0.15  # how much --fit blur dims the blurred background copy (eq brightness)
 
@@ -162,6 +162,7 @@ def main() -> int:
     post: List[str] = []
     factor = 1.0
     tc_first = None  # seconds from the source's first frame to the output's, when a trim moves it
+    regridded = False  # a speed change already put the picture on the delivered grid
 
     # ---- rotate / flip
     if args.rotate == 90:
@@ -204,6 +205,15 @@ def main() -> int:
                 elif factor < 1.0 and args.smooth == "blend":
                     vf.append(f"fps={src_fps:g}")
                     vf.append("tblend=all_mode=average")
+                elif not args.fps:
+                    # the retimed frames are put back on the output's grid by the fps filter, the
+                    # nearest frame for each slot: left to the encoder line's rate, a 1.11x speed-up
+                    # showed every picture up to two frames late against its sound (#512's class).
+                    # A rate the caller names is that grid (the conform below): conformed here to
+                    # the source's 30 first, a 2x speed-up to --fps 60 dropped every other picture
+                    # and the second fps filter repeated the rest
+                    vf.append(frame_durations(meta, delivered_rate(meta) or frame_rate(meta) or src_fps))
+                    regridded = True
                 if has_audio:
                     af.append(atempo_chain(factor))
             # atempo's sound is not the input's length over the factor (it comes out some
@@ -243,11 +253,43 @@ def main() -> int:
             else:
                 info(f"source ({src_dur:.2f}s) is already shorter than {target:.2f}s; trim does nothing")
 
+    # ---- the output's rate: after any retiming, ahead of the frame's own filters. --fit blur and
+    # --pad-fill blur are a split/overlay graph, and FFmpeg 6.1's overlay ends its output at its
+    # last frame's start, so an fps filter after it lost the last frame (#512's placement).
+    # A speed change without --fps has already been put on the delivered grid above
+    if args.fps:
+        vf.append(f"fps={args.fps:g}")
+    elif meta["video"].get("variable_frame_rate_suspected") and not regridded:
+        info("source looks variable-frame-rate; conforming to constant fps automatically")
+        # the conform is the fps filter, as --fps is: -fps_mode cfr alone let a frame run up to
+        # two frames late against the sound (#512)
+        vf.append(cfr_filter(meta))
+
     # ---- aspect / size
     if args.aspect or args.width or args.height:
         # 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":
+        if args.fit == "crop" and sw and sh:
+            # The scaled frame's margin on each axis is a multiple of 4 and the offset is computed
+            # here, to even: crop floors an odd offset to the chroma grid of a 4:2:0 frame, so
+            # --crop-x 1 lost the source's last column and showed one column of the margin, and a
+            # centred crop sat a pixel left of / above the centre (#512). exact=1 would put the
+            # chroma half a sample off the luma instead. The size is the one
+            # force_original_aspect_ratio=increase gives (av_rescale rounds half away from zero),
+            # widened by at most 3 px on the cropped axis.
+            sc_w = max(out_w, (2 * out_h * sw + sh) // (2 * sh))
+            sc_h = max(out_h, (2 * out_w * sh + sw) // (2 * sw))
+            mx, my = (-(-(sc - o) // 4) * 4 for sc, o in ((sc_w, out_w), (sc_h, out_h)))
+            ox, oy = (int(m * f / 2 + 0.5) * 2 for m, f in ((mx, args.crop_x), (my, args.crop_y)))
+            for axis, m, f, got in (("x", mx, args.crop_x, ox), ("y", my, args.crop_y, oy)):
+                if abs(m * f - got) > 1e-9:
+                    # the offset is kept even (the chroma grid); a caller who asked for another one
+                    # is told which it got, as proxy.py says which width it wrote
+                    note(f"--crop-{axis} {f:g}: crop offset {got}px, not {m * f:g}px: the offset is kept even "
+                         f"(4:2:0 chroma), on a {m}px margin")
+            vf.append(f"scale={out_w + mx}:{out_h + my}")
+            vf.append(f"crop={out_w}:{out_h}:{ox}:{oy}")
+        elif args.fit == "crop":  # a dry run's pending input has no size: the expressions, planned only
             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}")
         elif args.fit == "blur":
@@ -272,10 +314,6 @@ def main() -> int:
             vf.insert(0, square_pixels(meta["video"]))
             note(square_pixels_note(meta["video"]))
 
-    if args.fps:
-        vf.append(f"fps={args.fps:g}")
-    elif meta["video"].get("variable_frame_rate_suspected"):
-        info("source looks variable-frame-rate; conforming to constant fps automatically")
     # the start timecode is counted at the rate the output is delivered at: a --fps that changes
     # the rate relabels it (01:00:00:12 at 25 fps is 01:00:00:24 at 50) even with no trim, which
     # is also how a render.py clip cut at its own rate reaches the project's frame.fps

package/scripts/freeze.py

@@ -19,8 +19,8 @@ Examples:
 import argparse
 import sys
 
-from _common.decision import av_trim, frame_durations, frame_rate, grid_at_or_after, silence_filter, stream_starts, tpad_length
-from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run_keeping_subtitles, video_args, X264_PRESETS, time_arg, fmt_secs, run
+from _common.decision import av_trim, delivered_rate, frame_durations, frame_rate, grid_at_or_after, silence_filter, stream_starts, tpad_length
+from _common import add_common, apply_common, aac_args, cfr_args, with_cfr, default_output, die, emit, ffmpeg_base, info, probe, run_keeping_subtitles, video_args, X264_PRESETS, time_arg, fmt_secs, run
 from _common.emit import input_length
 
 
@@ -71,7 +71,7 @@ def main() -> int:
     if holds_end:
         # tpad's stop_duration clones the last frame for the given duration; no PTS surgery
         # needed since it only ever appends past the real end.
-        vf = f"tpad=stop_mode=clone:stop_duration={args.hold:.3f}"
+        vf = with_cfr(f"tpad=stop_mode=clone:stop_duration={args.hold:.3f}", meta)
         cmd = ffmpeg_base() + ["-i", args.input, "-vf", vf, "-map", "0:v:0"]
         if has_audio:
             cmd += ["-map", "0:a:0?", "-af", silence_filter(meta["audio"].get("sample_rate"), tail=args.hold)]
@@ -80,7 +80,7 @@ def main() -> int:
         # split/trim/concat approach below needs a non-empty head, which trim=end=0 can't give
         # it -- ffmpeg fails filtering an empty stream). Symmetric to --mode extend at the other
         # end: tpad's start_duration clones the *first* frame backwards instead.
-        vf = f"tpad=start_mode=clone:start_duration={args.hold:.3f}"
+        vf = with_cfr(f"tpad=start_mode=clone:start_duration={args.hold:.3f}", meta)
         cmd = ffmpeg_base() + ["-i", args.input, "-vf", vf, "-map", "0:v:0"]
         if has_audio:
             # the sound waits as long as the picture is held: whole frames (tpad_length), as the
@@ -92,12 +92,12 @@ def main() -> int:
         # FIRST frame -- the frame shown at `at` -- for --hold seconds (a segment of its own, below).
         # Through 3.1.3 the head's last frame was held, the frame before `at`: at a cut, the last
         # frame of the previous shot (#411).
-        n = max(1, round(args.hold * fps))
+        n = max(1, round(args.hold * rate))
         # The video hold length is rounded to a whole number of frames (n / fps), but the audio
         # side used to pad by the raw --hold value -- up to half a frame duration off from what
         # the video actually holds for, a permanent A/V drift from this point on. Pad audio by
         # the same, frame-rounded duration the video actually gets.
-        actual_hold = n / fps
+        actual_hold = n / rate
         head_v, head_a = av_trim(v0, cut_at, rate)
         tail_v, tail_a = av_trim(cut_at, None, rate)
         # The hold is its own segment: the frame at cut_at, cut on the input's clock and cloned to
@@ -112,11 +112,13 @@ def main() -> int:
         # and 0.100, --at 0.06), and the hold was lost (#416 review). A second trim keeps that one
         # frame; on a constant rate it is the frame at cut_at, as before.
         half = 0.5 / rate
+        # the graph closes on the rate the encoder line delivers (a VFR source is conformed to its
+        # average): closed on r_frame_rate, -r then resampled it and the picture ran late (#512)
         hold_v = (f"trim=start={cut_at - half:.6f},trim=end_frame=1,"
                   f"tpad=stop_mode=clone:stop={n - 1},setpts=PTS-STARTPTS")
         vf = (f"[0:v]split=3[a][b][c];[a]{head_v}[head];"
               f"[b]{hold_v}[hold];[c]{tail_v}[tail];"
-              f"[head][hold][tail]concat=n=3:v=1:a=0,{frame_durations(meta, rate)}[outv]")
+              f"[head][hold][tail]concat=n=3:v=1:a=0,{frame_durations(meta, delivered_rate(meta) or rate)}[outv]")
         cmd = ffmpeg_base() + ["-i", args.input, "-filter_complex", vf, "-map", "[outv]"]
         if has_audio:
             af = (f"[0:a]asplit[aa][ab];[aa]{head_a}[ahead];"

package/scripts/graphics.py

@@ -36,7 +36,7 @@ from typing import List, Optional, Tuple
 from _platforms import PLATFORMS, PLATFORM_CHOICES, safe_margins_px, resolve as resolve_platform
 from _common.emoji import emoji_missing_asset_note, emoji_mono_on_colour_note
 from _common.drawtext import shaping_refusal
-from _common import (guard_sidecar, require_filter, aac_args, add_common, brand_caption_style, script_font_for_text, apply_common, cfr_args,
+from _common import (guard_sidecar, require_filter, aac_args, add_common, brand_caption_style, script_font_for_text, apply_common, cfr_args, cfr_at_input, with_cfr,
                      color_hex, default_output, die, draws_chroma, drawn_chain, emit, escape_drawtext, escape_filter_path,
                      ffmpeg_base, info, layer_base_chain, load_brand, overlay_format, probe, rgb_chain_to_bt709, run_keeping_subtitles, video_args,
                      drawtext_boxborderw, drawtext_center_align, X264_PRESETS, time_arg, fmt_secs, STATE, drawtext_text_opts,
@@ -837,14 +837,17 @@ def main(force_route: Optional[str] = None) -> int:
         if finish:
             chains.append(f"[{last}]{finish}[ka_v]")
             last = "ka_v"
-        cmd += ["-filter_complex", ";".join(chains), "-map", f"[{last}]",
+        # the conform of a VFR source is the fps filter on the picture as it is decoded (#512)
+        cmd += ["-filter_complex", cfr_at_input(";".join(chains), meta), "-map", f"[{last}]",
                 "-map", f"0:a:{args.audio_stream}?"]
     elif fc:
         if finish:
             fc.append(f"[vout]{finish}[ka_v]")
-        cmd += ["-filter_complex", ";".join(fc), "-map", "[ka_v]" if finish else "[vout]", "-map", f"0:a:{args.audio_stream}?"]
+        cmd += ["-filter_complex", cfr_at_input(";".join(fc), meta), "-map", "[ka_v]" if finish else "[vout]",
+                "-map", f"0:a:{args.audio_stream}?"]
     else:
-        cmd += ["-vf", ",".join(p for p in (square, text, finish) if p) if finish else (square + "," if square else "") + text,
+        vf = ",".join(p for p in (square, text, finish) if p) if finish else (square + "," if square else "") + text
+        cmd += ["-vf", with_cfr(vf, meta),
                 "-map", "0:v:0", "-map", f"0:a:{args.audio_stream}?"]
     if alpha_codec:
         cmd += video_line(alpha_codec) + tag_args(meta) + cfr_args(meta)

package/scripts/loop.py

@@ -32,7 +32,7 @@ import os
 import sys
 import tempfile
 
-from _common import STATE, concat_list_line, add_common, aac_args, apply_common, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, refuse_output_is_input, require_filter, require_tool, run, video_args, X264_PRESETS, time_arg, fmt_secs
+from _common import STATE, concat_list_line, add_common, aac_args, apply_common, cfr_args, with_cfr, default_output, die, emit, ffmpeg_base, info, probe, refuse_output_is_input, require_filter, require_tool, run, video_args, X264_PRESETS, time_arg, fmt_secs
 from _common.emit import warn
 from _common.decision import HELD_FRAMES_WARN_BYTES, av_trim, held_frames_bytes, length_output_t, stream_starts
 from _common.probe import decode_gray_frames, decode_pcm_mono
@@ -296,7 +296,9 @@ def main() -> int:
             die(f"--duration ({target:g}s) must be longer than one repeat ({unit:.3f}s) -- use cut.py to trim instead")
         stream_loop = math.ceil(target / unit) - 1
 
-    # a variable-rate source is conformed by the output's own -fps_mode cfr -r (cfr_args)
+    # a variable-rate source is conformed to the rate cfr_args() delivers, by the fps filter in the
+    # picture's chain (below) and the output's -fps_mode cfr -r; the fps stage for a sound that
+    # outlasts the picture is for a constant-rate clip only, so the two never meet
     forced_rate = cfr_args(meta, fps if fade_frames and v.get("variable_frame_rate_suspected") else None)
     if args.boomerang:
         cmd = ffmpeg_base() + ["-i", args.input, "-filter_complex", _boomerang_graph(meta, src_dur, args.times), "-map", "[v]"]
@@ -319,6 +321,9 @@ def main() -> int:
         with open(listfile, "w", encoding="utf-8") as fh:
             fh.write((concat_list_line(repeat) + "\n") * (stream_loop + 1))
         vtrim, atrim = av_trim(concat_first_frame(listfile), None, fill_gaps=True)
+        # the conform of a VFR source is the fps filter at the end of the picture's chain, at the
+        # rate cfr_args() below delivers (#512)
+        vtrim = with_cfr(vtrim, meta, fps if fade_frames and v.get("variable_frame_rate_suspected") else None)
         cmd = ffmpeg_base() + ["-f", "concat", "-safe", "0", "-i", listfile]
         v_end = stream_starts(meta)[0] + (v.get("duration") or 0.0)
         if has_audio and not forced_rate and not fade_frames and src_dur - v_end > 0.5 / fps:

package/scripts/metadata.py

@@ -219,8 +219,11 @@ def main() -> int:
     args = ap.parse_args()
     apply_common(args)
     if args.auto_chapters:  # the only mode that writes them
-        guard_sidecar(args.chapters_out, args.input, siblings=(args.description_out, args.output))
-        guard_sidecar(args.description_out, args.input, siblings=(args.output,))
+        # against the video this run writes, the default name too (A6, #465: --chapters-out at
+        # input_meta.mp4 wrote the chapter text over the video it had just written)
+        video_out = args.output or default_output(args.input, "meta", Path(args.input).suffix.lstrip(".") or "mp4")
+        guard_sidecar(args.chapters_out, args.input, siblings=(args.description_out, video_out))
+        guard_sidecar(args.description_out, args.input, siblings=(video_out,))
 
     if args.chapters and args.clear_chapters:
         die("--chapters and --clear-chapters exclude each other")