ffmpeg-skill 2.23.1 → 2.24.1

package/scripts/export.py

@@ -31,12 +31,14 @@ Examples:
 import argparse
 import json
 import math
+import re
 import os
 import sys
+import tempfile
 from pathlib import Path
 from typing import Dict, List
 
-from _common import STATE, add_common, apply_common, 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 import STATE, run_analysis, add_common, apply_common, 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.emit import note, record_fallback, record_skip, warn
 from check import SPECS as PLATFORMS, measure_loudness
@@ -239,6 +241,64 @@ def _non_av_report(subs: List[Dict], sub_codecs: List[str], data: List[Dict], dr
     return {"kept": kept, "dropped": gone}
 
 
+# --repair (2.24): regenerate missing timestamps, drop packets flagged corrupt, keep demuxing past errors
+REPAIR_INPUT_ARGS = ["-fflags", "+genpts+discardcorrupt", "-err_detect", "ignore_err"]
+_TIMESTAMP_WARNING = re.compile(r"(?i)\b(dts|pts)\b|timestamp")
+
+
+def media_damage(path: str) -> Dict[str, int]:
+    """One full decode of `path` at -v warning: lines about timestamps (non-monotonic DTS, invalid
+    PTS) and every other error line, counted. What --repair is measured by, before and after."""
+    # repeat+: every occurrence on its own line, not "Last message repeated N times", which hid
+    # N timestamp warnings and was itself counted as a decode error
+    proc = run_analysis([require_tool("ffmpeg"), "-hide_banner", "-nostdin", "-v", "repeat+warning", "-i", path, "-f", "null", "-"],
+                        check=False, record=True)
+    lines = [ln for ln in (proc.stderr or "").splitlines() if ln.strip()]
+    # "Packet corrupt (stream = 0, dts = ...)" names a dts but is damage, not a timestamp problem
+    stamps = sum(1 for ln in lines if _TIMESTAMP_WARNING.search(ln) and "corrupt" not in ln.lower())
+    return {"timestamp_warnings": stamps, "decode_errors": len(lines) - stamps}
+
+
+MIB = 1024 * 1024
+SIZE_HEADROOM = 0.97        # of the byte budget given to the streams; the rest is container overhead
+SIZE_MIN_VIDEO_KBPS = 100   # below this the picture is not worth delivering; refused instead
+SIZE_MAX_VIDEO_KBPS = 400_000  # 400 Mb/s: above any delivery line, and libx264 refuses far larger values
+
+
+def size_video_args(args, video: List[str], p: Dict, meta: Dict, has_audio: bool) -> List[str]:
+    """--max-mb: the preset's x264 line with its CRF replaced by the bitrate that fits the size,
+    for a two-pass encode. Refused where that cannot be done honestly: another codec, --crf, --hw,
+    a source with no duration, or a size too small for a watchable picture."""
+    if args.crf is not None:
+        die("--max-mb sets the bitrate from the size, --crf sets a quality: give one of them")
+    if "-c:v" not in video or video[video.index("-c:v") + 1] != "libx264" or "-crf" not in video:
+        die(f"--max-mb runs a two-pass x264 encode; --preset {args.preset} does not encode with x264"
+            + (" (--hw puts it on VideoToolbox, which has no two-pass mode)" if STATE.hw else ""))
+    if not math.isfinite(args.max_mb) or args.max_mb <= 0:
+        die(f"--max-mb must be a positive number of MiB, got {args.max_mb:g}")
+    dur = float(meta.get("duration") or 0.0)
+    if p["max"] and not args.allow_long:
+        dur = min(dur, float(p["max"]))
+    if dur <= 0:
+        die("--max-mb needs the source's duration, which it does not report")
+    audio_kbps = 0.0
+    if has_audio and "-b:a" in p["audio"]:
+        audio_kbps = float(p["audio"][p["audio"].index("-b:a") + 1].rstrip("k"))
+    video_kbps = args.max_mb * MIB * 8 * SIZE_HEADROOM / dur / 1000 - audio_kbps
+    if video_kbps > SIZE_MAX_VIDEO_KBPS:
+        die(f"--max-mb {args.max_mb:g} allows {video_kbps / 1000:.0f} Mb/s over {dur:.1f}s, beyond any delivery bitrate; "
+            "a limit that large constrains nothing", hint="drop --max-mb (the preset's quality setting applies)")
+    if video_kbps < SIZE_MIN_VIDEO_KBPS:
+        die(f"--max-mb {args.max_mb:g} leaves {max(video_kbps, 0):.0f} kb/s for the picture over {dur:.1f}s "
+            f"(after {audio_kbps:.0f} kb/s of audio); under {SIZE_MIN_VIDEO_KBPS} kb/s it is not watchable",
+            hint="raise --max-mb, or cut the video shorter first")
+    out = list(video)
+    i = out.index("-crf")
+    out[i:i + 2] = ["-b:v", f"{video_kbps:.0f}k"]
+    info(f"--max-mb {args.max_mb:g}: {video_kbps:.0f} kb/s video + {audio_kbps:.0f} kb/s audio over {dur:.1f}s, two-pass")
+    return out
+
+
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("input", nargs="?")
@@ -250,6 +310,13 @@ def main() -> int:
     ap.add_argument("--no-scale", action="store_true", help="keep source resolution even for platform presets")
     ap.add_argument("--allow-long", action="store_true", help="do not trim to the platform's max duration")
     ap.add_argument("--crf", type=int, help="override CRF")
+    ap.add_argument("--repair", action="store_true",
+                    help="--preset copy only: remux a damaged file -- timestamps regenerated, corrupt packets dropped, "
+                         "negative timestamps shifted to zero -- and count the decode errors and timestamp warnings "
+                         "before and after; the input is never touched")
+    ap.add_argument("--max-mb", type=float, metavar="MB",
+                    help="fit the file under MB megabytes (MiB): a two-pass x264 encode at the video bitrate the "
+                         "running time leaves after the audio, measured afterwards (H.264 presets; not with --crf or --hw)")
     ap.add_argument("--normalize", action="store_true", help="youtube/youtube4k/reels/x: when the written file misses the platform's loudness spec, run loudness.py on it (audio re-encoded, video copied) so one export delivers")
     ap.add_argument("--list", action="store_true", help="list presets and exit")
     add_common(ap, codec=False)  # the preset decides the codec; --codec would only be refused
@@ -303,7 +370,12 @@ def main() -> int:
             vf.append("setsar=1")
         else:
             vf.append(f"scale={p['w']}:-2")
-    cmd = ffmpeg_base() + ["-i", args.input]
+    if args.repair and args.preset != "copy":
+        die("--repair is a remux: use it with --preset copy (a re-encoding preset already rebuilds every frame)")
+    if args.max_mb is not None and args.preset == "gif":
+        # the GIF branch below returns before the size is ever applied or measured
+        die("--max-mb runs a two-pass x264 encode; --preset gif does not encode with x264 (shorten or shrink the GIF instead)")
+    cmd = ffmpeg_base() + (REPAIR_INPUT_ARGS if args.repair else []) + ["-i", args.input]
     # Subtitle and data streams (a soft-subtitle track muxed upstream, a camera's timecode) are
     # kept where the container can hold them: ffmpeg's default stream selection takes one video
     # and one audio stream only, and through 2.22.1 every preset dropped the rest without a word.
@@ -354,6 +426,8 @@ def main() -> int:
         # A build without libx264/libx265 has no other encoder, so it goes there without --hw too
         # (hw_preset_video returns the line untouched in every other case)
         video = hw_preset_video(video, meta, bt709=tag_bt709)
+    if args.max_mb is not None:
+        video = size_video_args(args, video, p, meta, has_audio)
     cmd += video
     if args.preset != "copy":
         # a stream copy can't be frame-rate-conformed or retagged without decoding it — that would
@@ -369,6 +443,8 @@ def main() -> int:
             cmd += bt709_matrix_args(meta)
     if out_ext == "mp4":
         cmd += ["-movflags", "+faststart"]
+    if args.repair:
+        cmd += ["-avoid_negative_ts", "make_zero"]
     cmd += (p["audio"] if has_audio else ["-an"])
     trimmed = None
     if p["max"] and not args.allow_long and (meta.get("duration") or 0) > p["max"]:
@@ -379,9 +455,16 @@ def main() -> int:
         note(f"trimmed from {trimmed['from']:.3f}s to the {args.preset} maximum of {p['max']:.0f}s "
              "(use --allow-long to keep full length)")
         cmd += ["-t", f"{p['max']:.3f}"]
-    dropped = _run_keeping_non_av(cmd, output, sub_codecs, len(data)) if (subs or data) else []
-    if not (subs or data):
-        run(cmd + [output])
+    damage_before = media_damage(args.input) if args.repair and not STATE.dry_run else None
+    with tempfile.TemporaryDirectory(prefix="ffskill_2pass_") as passdir:
+        if args.max_mb is not None:
+            # pass 1 only writes x264's statistics; pass 2 encodes against them
+            log = os.path.join(passdir, "x264")
+            run(cmd + ["-pass", "1", "-passlogfile", log, "-an", "-sn", "-dn", "-f", "null", "-"])
+            cmd += ["-pass", "2", "-passlogfile", log]
+        dropped = _run_keeping_non_av(cmd, output, sub_codecs, len(data)) if (subs or data) else []
+        if not (subs or data):
+            run(cmd + [output])
     result = probe(output, role="output")
     v = result["video"]
     info(f"wrote {output} ({fmt_secs(result['duration'])}, {v['width']}x{v['height']}, {v['codec']})")
@@ -463,6 +546,31 @@ def main() -> int:
             step = {"step": "duration", "property": "duration", "ok": False, "expected": {"max": p["max"]},
                     "reason": "not_measured: the written file reports no duration"}
         extra.setdefault("verification", []).append(step)
+    if damage_before is not None:
+        after = media_damage(output)
+        extra["repair"] = {"before": damage_before, "after": after}
+        # judged on timestamp warnings, the part a remux rewrites: decode errors are counted in log
+        # lines, and the same damaged frame logs a different number of them demuxed from another
+        # container, so their before/after is reported, not compared
+        stamps = after["timestamp_warnings"]
+        extra.setdefault("verification", []).append(
+            {"step": "repair", "property": "timestamp_warnings", "ok": stamps <= damage_before["timestamp_warnings"],
+             "expected": {"max": damage_before["timestamp_warnings"]}, "measured": stamps,
+             "provenance": "input_premeasurement"})
+        if after["decode_errors"]:
+            notes.append(f"--repair: {after['decode_errors']} decode error(s) remain: a remux drops corrupt packets and "
+                         "rewrites timestamps but cannot rebuild a damaged frame; a re-encoding preset decodes past them")
+            warn(notes[-1], "repair_incomplete", **after)
+    if args.max_mb is not None and not STATE.dry_run:
+        limit = int(args.max_mb * MIB)
+        size = os.path.getsize(output)
+        extra.setdefault("verification", []).append(
+            {"step": "file_size", "property": "size_bytes", "ok": size <= limit, "expected": {"max": limit},
+             "measured": size, "delta": size - limit, "tolerance": 0, "provenance": "user_specified"})
+        if size > limit:
+            notes.append(f"--max-mb {args.max_mb:g}: the file is {size / MIB:.2f} MiB, over the limit; the encoder overshot "
+                         f"its target bitrate on this content: export again with a lower --max-mb")
+            warn(notes[-1], "size_over_limit", size=size, limit=limit)
     # read back after --normalize, which rewrote the file
     non_av = _non_av_report(subs, sub_codecs, data, dropped, output, "write_failed")
     if non_av["dropped"]:

package/scripts/join.py

@@ -35,12 +35,14 @@ fail refuses it with the other input problems; skip drops it into `skipped`. A c
 audio stream is never silent.
 """
 import argparse
+import json
 import os
+import tempfile
 import sys
 from typing import Any, Dict, List, Optional, Tuple
 
-from _common.probe import SILENT_PEAK_DBFS
-from _common import STATE, AUDIO_MEDIA_EXT, draws_chroma, drawn_chain, label_chain, matrix_chain, video_args, aac_args, add_common, apply_common, audio_codec_for, default_output, die, dry_run_input_pending, emit, ffmpeg_base, info, measured_level_dbfs, is_audio_output, probe, require_tool, run, validate_color, X264_PRESETS, fmt_secs
+from _common.probe import SILENT_PEAK_DBFS, signatures_match, stream_signature
+from _common import STATE, AUDIO_MEDIA_EXT, concat_list_line, guard_sidecar, place_output, refuse, sibling_temp, draws_chroma, drawn_chain, label_chain, matrix_chain, video_args, aac_args, add_common, apply_common, audio_codec_for, default_output, die, dry_run_input_pending, emit, ffmpeg_base, info, measured_level_dbfs, is_audio_output, probe, require_tool, run, validate_color, X264_PRESETS, fmt_secs
 from _common.emit import warn
 
 TRANSITIONS = ["fade", "dissolve", "wipeleft", "wiperight", "wipeup", "wipedown", "slideleft", "slideright",
@@ -305,6 +307,204 @@ def parse_allow_silent(value: Optional[str], n: int) -> List[int]:
     return out
 
 
+# join.py --copy (2.24). The concat demuxer starts each clip where the previous one's container
+# ends, so a stream that ends early leaves a gap at the join: a held frame for the picture, a hole
+# for the sound. A clip whose picture and sound end further apart than this is refused.
+COPY_AV_GAP = 0.05
+COPY_PREROLL_PACKETS = 300   # packets read per clip to find an edit list's hidden pre-roll
+
+
+def _copy_doc(path: str) -> "Optional[Dict[str, Any]]":
+    """ffprobe's first video and first audio stream of `path`, with extradata hashes, as the doc
+    stream_signature() reads; None when it cannot be read."""
+    proc = run([require_tool("ffprobe"), "-v", "error", "-show_data_hash", "sha256", "-show_streams", "-show_format",
+                "-of", "json", path], quiet=True, check=False)
+    try:
+        doc = json.loads(proc.stdout or "") if proc.returncode == 0 else None
+    except ValueError:
+        return None
+    if not isinstance(doc, dict):
+        return None
+    # attached pictures (cover art) are not the picture being joined, as V:0 skips them
+    every = doc.get("streams") or []
+    streams = [st for st in every if not (st.get("disposition") or {}).get("attached_pic")]
+    keep = [next((st for st in streams if st.get("codec_type") == kind), None) for kind in ("video", "audio")]
+    doc["streams"] = [st for st in keep if st]
+    # the concat demuxer maps every clip's packets by stream index, laid out as the first clip's
+    doc["layout"] = {"streams": len(every), "indices": [st.get("index") for st in doc["streams"]]}
+    return doc
+
+
+def _video_packets(path: str, limit: "Optional[int]" = None) -> "List[str]":
+    """The flags of the first video stream's packets (all of them, or the first `limit`); cover art
+    is not that stream."""
+    cmd = [require_tool("ffprobe"), "-v", "error", "-select_streams", "V:0", "-show_entries", "packet=flags", "-of", "csv=p=0"]
+    if limit:
+        cmd += ["-read_intervals", f"%+#{limit}"]
+    proc = run(cmd + [path], quiet=True, check=False)
+    return (proc.stdout or "").split() if proc.returncode == 0 else []
+
+
+SPAN_HEAD_PACKETS = 64     # enough to see the earliest presentation time past B-frame reordering
+SPAN_TAIL_SECONDS = 10.0   # read from this far before the end, so a seek that lands early still reaches it
+
+
+def _stream_span(path: str, kind: str, duration: float = 0.0, start: float = 0.0) -> "Optional[Tuple[float, float]]":
+    """First packet's time and last packet's time plus its duration for the first `kind` stream
+    (V or a): measured, because Matroska/WebM state no stream length and MPEG-TS only an estimate.
+    None when the packets cannot be read or one has no time: a partial span would invent a gap."""
+    # JSON, not csv: older ffprobe builds (5.1) print side-data rows between the packet rows in csv.
+    # A long clip is read at its head and its tail only: every packet of a two-hour file is
+    # hundreds of thousands of entries for two numbers
+    cmd = [require_tool("ffprobe"), "-v", "error", "-select_streams", f"{kind}:0", "-show_entries",
+           "packet=pts_time,dts_time,duration_time", "-of", "json"]
+    if duration > 3 * SPAN_TAIL_SECONDS:
+        # read_intervals takes timestamps, so the tail starts from the file's own start time
+        # (an MPEG-TS clock can start hours in; an edit list can start it below zero)
+        cmd += ["-read_intervals", f"%+#{SPAN_HEAD_PACKETS},{start + duration - SPAN_TAIL_SECONDS:.3f}%"]
+    proc = run(cmd + [path], quiet=True, check=False)
+    try:
+        packets = json.loads(proc.stdout or "{}").get("packets") or [] if proc.returncode == 0 else []
+    except ValueError:
+        return None
+    times = []
+    for pkt in packets:
+        try:
+            # a packet ffprobe gives no pts (some muxers leave it on B-frames) still has its dts
+            t = float(pkt.get("pts_time", pkt.get("dts_time")))
+        except (TypeError, ValueError):
+            return None
+        try:
+            d = float(pkt.get("duration_time") or 0.0)
+        except (TypeError, ValueError):
+            d = 0.0
+        times.append((t, t + d))
+    if not times:
+        return None
+    return min(t for t, _ in times), max(e for _, e in times)
+
+
+def join_copy(args, metas: List[Dict[str, Any]]) -> int:
+    """--copy: the concat demuxer with -c copy, after checking that the clips can be joined that
+    way, and measured afterwards (video packet count and length against the clips')."""
+    if args.transition != "none":
+        die("--copy joins without a transition: pass --transition none (a transition re-encodes the frames it blends)")
+    if args.width or args.height or args.fps:
+        die("--copy keeps every clip's own frame and rate: --width, --height and --fps need a re-encode, so drop --copy")
+    if args.sample_rate or args.channels:
+        die("--copy keeps every clip's own sound: --sample-rate and --channels need a re-encode, so drop --copy")
+    encoder = [f for f, on in (("--codec", STATE.codec), ("--hw", STATE.hw and STATE.hw_source == "flag"),
+                               ("--quality", getattr(args, "quality_given", False)))
+               if on]
+    if encoder:
+        die(f"--copy keeps every clip's own encoding: {', '.join(encoder)} choose(s) an encode, so drop --copy")
+    output = args.output or default_output(args.inputs[0], "joined", os.path.splitext(args.inputs[0])[1].lstrip(".") or "mp4")
+    guard_sidecar(output, *args.inputs)
+    ext = os.path.splitext(output)[1].lower()
+    n = len(args.inputs)
+    pending = any(m.get("dry_run") for m in metas)
+    if pending:
+        STATE_NOTES.append("--copy: an input does not exist yet, so whether the clips match is checked when a real run has them")
+    else:
+        docs = [_copy_doc(p) for p in args.inputs]
+        unreadable = [p for p, d in zip(args.inputs, docs) if d is None]
+        if unreadable:
+            die(f"--copy: could not read the streams of {', '.join(unreadable)}")
+        moved = [{"index": i, "path": p, "differs": {"stream_layout": [docs[0]["layout"], d["layout"]]}}
+                 for i, (p, d) in enumerate(zip(args.inputs, docs)) if i and d["layout"] != docs[0]["layout"]]
+        if moved:
+            refuse("input", "join_copy_mismatch",
+                   f"--copy: {', '.join(m['path'] for m in moved)} lay(s) out their streams differently from "
+                   f"{args.inputs[0]} (count or order, cover art included); the concat demuxer maps streams by position",
+                   hint="drop --copy to re-encode them to one layout", clips=moved)
+        sigs = [stream_signature(d) for d in docs]
+        mismatched = [{"index": i, "path": p, "differs": {k: [a.get(k), b.get(k)] for a, b in zip(sigs[0], sig)
+                                                           for k in a if k != "extradata_hash" and a.get(k) != b.get(k)}
+                       if len(sig) == len(sigs[0]) else {"streams": [len(sigs[0]), len(sig)]}}
+                      for i, (p, sig) in enumerate(zip(args.inputs, sigs)) if i and not signatures_match([sigs[0], sig], ext)]
+        if mismatched:
+            listing = "; ".join(f"#{m['index'] + 1} {m['path']}: " + (", ".join(f"{k} {v[1]} (not {v[0]})" for k, v in m["differs"].items())
+                                                                        or "codec configuration (extradata) differs")
+                                for m in mismatched)
+            refuse("input", "join_copy_mismatch", f"--copy: {len(mismatched)} clip(s) do not match the first one: {listing}",
+                   hint="drop --copy to re-encode them to one format", clips=mismatched)
+        hidden = [p for p in args.inputs if "D" in "".join(_video_packets(p, COPY_PREROLL_PACKETS))]
+        if hidden:
+            refuse("input", "join_copy_mismatch",
+                   f"--copy: {', '.join(hidden)} hide(s) frames before their start (an edit list), which a copy join would show",
+                   hint="drop --copy, or re-cut those clips with cut.py --accurate", clips=[{"path": p, "differs": {"edit_list": True}} for p in hidden])
+        gaps = []
+        for p, m in zip(args.inputs, metas):
+            # each stream's span from its packets: Matroska/WebM state no stream length and an
+            # MPEG-TS stream length is an estimate, so a stated duration missed or invented gaps
+            if not (m.get("video") and m.get("audio")):
+                continue
+            length, origin = float(m.get("duration") or 0.0), float(m.get("start_time") or 0.0)
+            v_span, a_span = _stream_span(p, "V", length, origin), _stream_span(p, "a", length, origin)
+            if v_span is None or a_span is None:
+                refuse("input", "join_copy_mismatch",
+                       f"--copy: could not measure where picture and sound start and end in {p} (a packet without a "
+                       "time), so a gap at the join could not be ruled out", hint="drop --copy to re-encode the join",
+                       clips=[{"path": p, "differs": {"av_span": "unmeasured"}}])
+            (vb, ve), (ab, ae) = v_span, a_span
+            if abs(vb - ab) > COPY_AV_GAP or abs(ve - ae) > COPY_AV_GAP:
+                gaps.append({"path": p, "video": [round(vb, 3), None if ve is None else round(ve, 3)],
+                             "audio": [round(ab, 3), None if ae is None else round(ae, 3)]})
+        if gaps:
+            def span(x):
+                return f"{x[0]:.3f}-" + ("?" if x[1] is None else f"{x[1]:.3f}") + "s"
+            listing = "; ".join(f"{g['path']} (video {span(g['video'])}, audio {span(g['audio'])})" for g in gaps)
+            refuse("input", "join_copy_mismatch",
+                   f"--copy: picture and sound start or end more than {COPY_AV_GAP * 1000:.0f} ms apart in {listing}; a copy join "
+                   "would leave that gap at the next clip", hint="drop --copy, which trims both streams to one length",
+                   clips=[{"path": g["path"], "differs": {"video_span": g["video"], "audio_span": g["audio"]}} for g in gaps])
+    fps = (metas[0].get("video") or {}).get("fps") or 30.0
+    note_short_segments(args.inputs, metas, MIN_SEGMENT_FRAMES / fps, f"{MIN_SEGMENT_FRAMES} frames at {fps:g} fps")
+    place_silent([m.get("duration") or 0.0 for m in metas], 0.0)
+    with tempfile.TemporaryDirectory(prefix="ffskill_join_") as tmp:
+        listfile = os.path.join(tmp, "list.txt")
+        with open(listfile, "w", encoding="utf-8") as fh:
+            for p in args.inputs:
+                fh.write(concat_list_line(os.path.abspath(p)) + "\n")
+        joined = sibling_temp(output, "join") if not STATE.dry_run else output
+        cmd = ffmpeg_base() + ["-f", "concat", "-safe", "0", "-i", listfile, "-map", "0:V:0", "-map", "0:a:0?", "-c", "copy"]
+        if ext in (".mp4", ".mov", ".m4v"):
+            cmd += ["-movflags", "+faststart"]
+        try:
+            run(cmd + [joined])
+            verification: List[Dict[str, Any]] = []
+            if not STATE.dry_run:
+                want = sum(len(_video_packets(p)) for p in args.inputs)
+                got = len(_video_packets(joined))
+                # nothing counted on either side is a failed read, not a match
+                verification.append({"step": "join", "property": "video_packets", "ok": got == want and want > 0,
+                                     "measured": got, "expected": want, "provenance": "input_premeasurement"})
+                r = probe(joined, role="output")
+                measured = (r.get("video") or {}).get("duration") or r.get("duration")
+                expected = round(sum(m.get("duration") or 0.0 for m in metas), 3)
+                tol = round(n * COPY_AV_GAP + 1.0 / fps, 3)
+                verification.append({"step": "join", "property": "video_duration",
+                                     "ok": measured is not None and abs(measured - expected) <= tol,
+                                     "measured": None if measured is None else round(measured, 3), "expected": expected,
+                                     "tolerance": tol, "provenance": "input_premeasurement"})
+                bad = [v for v in verification if not v["ok"]]
+                if bad:
+                    die("--copy: the joined file does not hold the clips it was given: "
+                        + "; ".join(f"{v['property']} {v['measured']} (expected {v['expected']})" for v in bad),
+                        kind="verification", hint="drop --copy to re-encode the join", verification=verification)
+                place_output(joined, output, move=True)
+        finally:
+            if joined != output and os.path.exists(joined):
+                os.remove(joined)
+    r = probe(output, role="output")
+    info(f"wrote {output} ({fmt_secs(r.get('duration'))}, {n} clips, stream copy)")
+    emit(output, mode="copy", **reported(), clips=n, transition="none", reencoded=False,
+         verification=verification, expect_streams={"video": 1, "audio": 1 if all(m.get("audio") for m in metas) else 0},
+         stream_reference=metas,
+         dropped_non_av_streams=any(m.get("subtitle_streams") or m.get("data_streams") for m in metas))
+    return 0
+
+
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("inputs", nargs="*", help="two or more clips in order (or --list FILE)")
@@ -329,6 +529,10 @@ def main() -> int:
     ap.add_argument("--height", type=int, help="output height (default: first clip)")
     ap.add_argument("--fps", type=float, help="output frame rate (default: first clip)")
     ap.add_argument("--fit", choices=["pad", "crop"], default="pad", help="how clips of another aspect reach the frame (default pad)")
+    ap.add_argument("--copy", action="store_true",
+                    help="join by stream copy, no re-encode (needs --transition none): every clip must carry the same "
+                         "video and audio parameters (codec, size, rate, pixel format, sample rate, channels); a clip "
+                         "that does not is refused, by name, with what differs")
     ap.add_argument("--pad-color", default="black")
     ap.set_defaults(crf=18)  # --quality's default (the --crf alias was removed in 2.0)
     ap.add_argument("--preset", default="medium", choices=X264_PRESETS)
@@ -337,6 +541,8 @@ def main() -> int:
     aud.add_argument("--channels", type=int, choices=[1, 2, 6, 8], help="output channel count (default: the widest clip)")
     add_common(ap)
     args = ap.parse_args()
+    # given at all, not only different from the default: --quality 18 asks for an encode as much as 23 does
+    args.quality_given = any(a == "--quality" or a.startswith("--quality=") for a in sys.argv[1:])
     apply_common(args)
     if args.fps is not None and args.fps <= 0:
         die(f"--fps must be positive, got {args.fps:g}")
@@ -433,6 +639,8 @@ def main() -> int:
         for p, m in zip(args.inputs, metas):
             if not m.get("audio"):
                 die(f"{p} has neither a video nor an audio stream")
+        if args.copy:
+            die("--copy joins video clips; an audio-only join resamples every clip to one format, which a copy cannot do")
         return join_audio(args, metas)
     for p, m, pic in zip(args.inputs, metas, pictured):
         if not pic:
@@ -444,6 +652,8 @@ def main() -> int:
             die((f"{p} does not exist yet, and its audio extension says it will have no video stream" if m.get("dry_run")
                  else f"{p} has no video stream")
                 + (f" while {other}; join audio with audio or give every clip a picture" if other else ""))
+    if args.copy:
+        return join_copy(args, metas)
     first = metas[0]["video"]
     fw, fh = first["width"], first["height"]
     if first.get("rotation") in (90, -90, 270, -270):

package/scripts/render.py

@@ -1192,7 +1192,12 @@ def main() -> int:
         work.mkdir(parents=True, exist_ok=True)
     except OSError as e:
         die(f"cannot create the work directory {work}: {e}")
-    if not args.keep and not args.work:
+    # --stop-after before the export reports a stage file inside the work directory as its output:
+    # removing the directory at exit deleted the file the result named (and its output_identity)
+    previewing = bool(args.stop_after) and args.stop_after != "export" and not STATE.dry_run
+    if previewing and not args.keep and not args.work:
+        info(f"--stop-after {args.stop_after}: keeping the work directory {work}, since the result's output is in it")
+    if not args.keep and not args.work and not previewing:
         # a failed or dry run used to leave <output>_work_<pid>/ behind (sweep F15): the
         # auto-named directory is ours alone, so remove it on every exit path
         import atexit