ffmpeg-skill 0.9.0 → 0.12.0

package/scripts/color.py

@@ -1,7 +1,8 @@
 #!/usr/bin/env python3
 """Colour management: convert HDR (HDR10/PQ, HLG, BT.2020) to SDR BT.709 with
-real tone mapping, apply a .cube LUT (Log footage, creative grades), or fix
-wrong colour tags without re-encoding.
+real tone mapping, apply a .cube LUT (Log footage, creative grades), fix wrong
+colour tags without re-encoding, or apply typed primary colour correction
+(exposure, contrast, saturation, white balance).
 
 Examples:
   python3 color.py iphone_hdr.mov --to-sdr                       # PQ/HLG -> BT.709 SDR, hable tonemap
@@ -11,16 +12,61 @@ Examples:
   python3 color.py wrongly_tagged.mp4 --retag bt709                # metadata only, stream copy
   python3 color.py iphone_dv.mov --strip-dovi                       # drop Dolby Vision RPU, keep HLG base layer
   python3 color.py iphone_dv.mov --to-sdr                           # DV 8.4 = HLG base layer -> tone-mapped SDR
+  python3 color.py flat.mp4 --correct --exposure 0.3 --contrast 1.1 --saturation 1.05 --temperature 5600 --tint -0.05
 """
 import argparse
 import os
 import sys
 from typing import List
 
-from _common import add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, info, probe, run, x264_args
+from _common import add_common, analyze_levels, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, info, probe, run, x264_args
 
 TONEMAPS = ["hable", "mobius", "reinhard", "bt2390", "clip", "linear", "gamma"]
 
+# Typed primary correction: each flag is one option of one real, always-available libavfilter filter
+# (never a caller-supplied filter string). Range is this script's own safe subset of what the filter
+# documents (`ffmpeg -h filter=<name>`), not the filter's full technical range. default is each filter's
+# own documented no-op value, so every stage below is always emitted and the chain never depends on
+# which flags were actually given.
+CORRECTION = {
+    #      flag           default  lo      hi       unit
+    "exposure":    (0.0,   -3.0,    3.0,   "stops"),   # exposure filter's own full range (linear-domain stops)
+    "contrast":    (1.0,    0.0,    2.0,   "x"),       # eq filter; 0=flat grey, 1=unchanged, 2=double contrast
+    "saturation":  (1.0,    0.0,    2.0,   "x"),       # eq filter; 0=grayscale, 1=unchanged, 2=double saturation
+    "temperature": (6500.0, 2000.0, 12000.0, "K"),     # colortemperature filter; 6500=unchanged (its own default)
+    "tint":        (0.0,   -1.0,    1.0,   "x"),       # mapped to colorbalance midtones, see correction_chain()
+}
+
+
+def _checked(args: argparse.Namespace, flag: str) -> float:
+    _, lo, hi, unit = CORRECTION[flag]
+    value = getattr(args, flag)
+    if not (lo <= value <= hi):
+        die(f"--{flag} {value:g} is outside {lo:g}..{hi:g} {unit} (the safe range this tool guarantees)")
+    return value
+
+
+def correction_chain(args: argparse.Namespace) -> str:
+    """Four always-present filter stages, in a fixed order chosen so each stage sees a picture already
+    corrected by the previous one: exposure (linear light level) -> white balance (temperature/tint, so
+    contrast/saturation act on colour-balanced footage) -> contrast -> saturation (the most creative-
+    adjacent stage, applied last). `tint` (-1 green .. +1 magenta) is not a single ffmpeg option: it is
+    expressed as colorbalance's three midtone channels (gm=-tint, rm=bm=tint/2) so a positive tint shifts
+    midtones toward magenta and a negative one toward green without changing overall midtone lightness,
+    the same balanced-axis convention colour tools use for a one-dial tint control."""
+    exposure = _checked(args, "exposure")
+    contrast = _checked(args, "contrast")
+    saturation = _checked(args, "saturation")
+    temperature = _checked(args, "temperature")
+    tint = _checked(args, "tint")
+    gm, rm, bm = -tint, tint / 2.0, tint / 2.0
+    return ",".join([
+        f"exposure=exposure={exposure:g}",
+        f"colortemperature=temperature={temperature:g}",
+        f"colorbalance=rm={rm:g}:gm={gm:g}:bm={bm:g}",
+        f"eq=contrast={contrast:g}:saturation={saturation:g}",
+    ])
+
 
 def hdr_to_sdr_chain(meta: dict, tonemap: str, peak: float, desat: float) -> str:
     v = meta["video"]
@@ -48,11 +94,23 @@ def main() -> int:
     mode.add_argument("--lut", help=".cube LUT to apply (3D)")
     mode.add_argument("--retag", choices=["bt709", "bt2020-pq", "bt2020-hlg", "bt601"], help="rewrite colour tags only (no re-encode)")
     mode.add_argument("--strip-dovi", action="store_true", help="remove the Dolby Vision RPU (profile 8.4 iPhone clips) so players use the plain HLG/HDR10 base layer; stream copy")
+    mode.add_argument("--correct", action="store_true", help="typed primary colour correction: --exposure/--contrast/--saturation/--temperature/--tint")
     ap.add_argument("--tonemap", choices=TONEMAPS, default="hable", help="tone-mapping curve (default hable)")
     ap.add_argument("--peak", type=float, default=1000.0, help="source peak brightness in nits used for PQ (default 1000)")
     ap.add_argument("--desat", type=float, default=0.0, help="tonemap desaturation strength (default 0)")
     ap.add_argument("--lut-strength", type=float, default=1.0, help="blend LUT result with the original, 0..1 (default 1)")
     ap.add_argument("--force", action="store_true", help="run --to-sdr even if the file is not tagged as HDR (treat as PQ)")
+    ap.add_argument("--exposure", type=float, default=CORRECTION["exposure"][0], help="--correct: exposure in stops, -3..3 (default 0)")
+    ap.add_argument("--contrast", type=float, default=CORRECTION["contrast"][0], help="--correct: contrast, 0..2, 1=unchanged (default 1)")
+    ap.add_argument("--saturation", type=float, default=CORRECTION["saturation"][0], help="--correct: saturation, 0..2, 1=unchanged (default 1)")
+    ap.add_argument("--temperature", type=float, default=CORRECTION["temperature"][0], help="--correct: white-balance temperature in Kelvin, 2000..12000, 6500=unchanged (default 6500)")
+    ap.add_argument("--tint", type=float, default=CORRECTION["tint"][0], help="--correct: green(-1)/magenta(+1) tint, 0=unchanged (default 0)")
+    ap.add_argument("--audio-stream", type=int, default=0,
+                     help="which audio stream of the input to keep, 0-based in file order (probe.py lists them under "
+                          "audio_streams) -- matters on a multi-track input (dubbed languages, M&E stems); default 0, "
+                          "the first track, same as leaving it unset always did. Only affects modes that re-encode "
+                          "audio (--to-sdr, --lut, --correct, and --retag's re-encode fallback) -- --strip-dovi and "
+                          "a successful --retag stream-copy all streams untouched, so the flag has nothing to select there.")
     ap.add_argument("--crf", type=int, default=18)
     ap.add_argument("--preset", default="medium")
     add_common(ap)
@@ -64,6 +122,11 @@ def main() -> int:
         die("input has no video stream")
     v = meta["video"]
     has_audio = bool(meta.get("audio"))
+    audio_streams = meta.get("audio_streams") or []
+    if audio_streams and not (0 <= args.audio_stream < len(audio_streams)):
+        die(f"--audio-stream {args.audio_stream}: input has {len(audio_streams)} audio stream(s), 0..{len(audio_streams) - 1}")
+    if args.audio_stream and not audio_streams:
+        die("--audio-stream needs an input with audio streams")
 
     if args.strip_dovi:
         output = args.output or default_output(args.input, "nodv")
@@ -76,7 +139,7 @@ def main() -> int:
             cmd += ["-movflags", "+faststart"]
         cmd.append(output)
         run(cmd)
-        r = probe(output)
+        r = probe(output, role="output")
         info(f"wrote {output} (dolby_vision={r['video'].get('dolby_vision')})")
         emit(output)
         return 0
@@ -96,22 +159,46 @@ def main() -> int:
             cmd += ["-movflags", "+faststart"]
         cmd.append(output)
         proc = run(cmd, check=False)
+        dropped_streams = False
         if proc.returncode != 0:
-            # some codecs cannot carry retagged colour info without a bitstream filter; fall back to re-encode
-            info("stream copy could not rewrite tags, re-encoding")
-            cmd = ffmpeg_base() + ["-i", args.input, "-map", "0:v:0", "-map", "0:a:0?"] + x264_args(args.crf, args.preset, keep_bt709=False)
-            cmd += ["-colorspace", tags[0], "-color_primaries", tags[1], "-color_trc", tags[2]] + (aac_args() if has_audio else []) + [output]
-            run(cmd)
+            # Some codecs cannot carry retagged colour info without a bitstream filter, so the
+            # stream copy above fails and we fall back to re-encoding video+audio. The copy path
+            # (-map 0 -c copy) keeps every stream -- extra audio tracks, subtitles, chapters,
+            # attached pictures -- byte-for-byte; -c:s/-c:d copy here keeps that same guarantee
+            # for subtitle/data streams even though video/audio must be re-encoded. Only if THAT
+            # also fails (e.g. a subtitle codec genuinely incompatible with the target container)
+            # do we drop to video+selected-audio-only, and even then we say so explicitly rather
+            # than silently reporting "completed" with streams missing.
+            info("stream copy could not rewrite tags, re-encoding video/audio (subtitles/data streams kept)")
+            cmd = ffmpeg_base() + ["-i", args.input, "-map", "0:v:0", "-map", f"0:a:{args.audio_stream}?",
+                                    "-map", "0:s?", "-map", "0:d?"] + x264_args(args.crf, args.preset, keep_bt709=False)
+            cmd += ["-colorspace", tags[0], "-color_primaries", tags[1], "-color_trc", tags[2]]
+            cmd += (aac_args() if has_audio else []) + ["-c:s", "copy", "-c:d", "copy"] + [output]
+            proc2 = run(cmd, check=False)
+            if proc2.returncode != 0:
+                info("re-encode with subtitles/data streams kept also failed; dropping them")
+                dropped_streams = True
+                cmd = ffmpeg_base() + ["-i", args.input, "-map", "0:v:0", "-map", f"0:a:{args.audio_stream}?"] + x264_args(args.crf, args.preset, keep_bt709=False)
+                cmd += ["-colorspace", tags[0], "-color_primaries", tags[1], "-color_trc", tags[2]] + (aac_args() if has_audio else []) + [output]
+                run(cmd)
         info(f"wrote {output} (tags -> {args.retag})")
-        emit(output)
+        emit(output, reencoded=proc.returncode != 0, dropped_non_av_streams=dropped_streams)
         return 0
 
+    measurements = None
     if args.to_sdr:
         if not v.get("hdr") and not args.force:
             die(f"{args.input} is not tagged as HDR (transfer={v.get('color_transfer')}, primaries={v.get('color_primaries')}). Use --force to tone-map anyway.")
         vf = hdr_to_sdr_chain(meta, args.tonemap, args.peak, args.desat)
         output = args.output or default_output(args.input, "sdr")
         tag = "sdr"
+    elif args.correct:
+        vf = correction_chain(args)
+        output = args.output or default_output(args.input, "correct")
+        tag = "correct"
+        # OBSERVED technical measurements (signalstats: luma / saturation distribution), never a
+        # "looks better" judgement -- the same primitive probe.py --analyze uses for Log detection.
+        measurements = {"input": analyze_levels(args.input)}
     else:
         if not os.path.exists(args.lut):
             die(f"LUT not found: {args.lut}")
@@ -124,13 +211,17 @@ def main() -> int:
         output = args.output or default_output(args.input, "lut")
         tag = "lut"
 
-    cmd = ffmpeg_base() + ["-i", args.input, "-vf", vf, "-map", "0:v:0", "-map", "0:a:0?"]
+    cmd = ffmpeg_base() + ["-i", args.input, "-vf", vf, "-map", "0:v:0", "-map", f"0:a:{args.audio_stream}?"]
     cmd += x264_args(args.crf, args.preset) + cfr_args(meta) + (aac_args() if has_audio else []) + [output]
     run(cmd)
-    r = probe(output)
+    r = probe(output, role="output")
     info(f"wrote {output} ({r['duration']:.3f}s, {r['video']['width']}x{r['video']['height']}, "
          f"{r['video']['color_transfer']}/{r['video']['color_primaries']}, {tag})")
-    emit(output)
+    if measurements is not None:
+        measurements["output"] = analyze_levels(output)
+        emit(output, measurements=measurements)
+    else:
+        emit(output)
     return 0
 
 

package/scripts/crop.py

@@ -0,0 +1,79 @@
+#!/usr/bin/env python3
+"""Crop a video to an exact pixel rectangle.
+
+{x, y, width, height} are literal pixel offsets and dimensions in the SOURCE
+frame, not aspect-ratio-relative -- for cropping to a target aspect ratio
+(e.g. 16:9 -> 9:16) use fit.py --fit crop instead, which computes the
+rectangle for you and lets you steer it with --crop-x/--crop-y. This tool is
+for when the caller already knows the exact rectangle (a face-detection box,
+a saved crop from a previous edit, a hand-picked region).
+
+The rectangle must lie entirely inside the source frame after accounting for
+any display rotation, and --width/--height must be even (required for 4:2:0
+chroma subsampling, the pixel format every encoder here uses) -- given values
+are validated and refused, never silently rounded, since a caller-specified
+rectangle should do exactly what was asked or fail loudly.
+
+Examples:
+  python3 crop.py input.mp4 --x 100 --y 0 --width 1080 --height 1920
+  python3 crop.py input.mp4 --x 0 --y 140 --width 1920 --height 800 -o cropped.mp4
+"""
+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
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("input")
+    ap.add_argument("-o", "--output", help="output file (default: <name>_crop.<ext>)")
+    ap.add_argument("--x", type=int, required=True, help="left edge of the crop rectangle, in source pixels")
+    ap.add_argument("--y", type=int, required=True, help="top edge of the crop rectangle, in source pixels")
+    ap.add_argument("--width", type=int, required=True, help="crop width in px (must be even)")
+    ap.add_argument("--height", type=int, required=True, help="crop height in px (must be even)")
+    ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
+    ap.add_argument("--preset", default="medium", help="x264 preset")
+    ap.add_argument("--fps", type=float, help="force a constant output frame rate (recommended for VFR sources)")
+    add_common(ap)
+    args = ap.parse_args()
+    apply_common(args)
+
+    if args.x < 0 or args.y < 0:
+        die(f"--x/--y must be >= 0, got x={args.x} y={args.y}")
+    if args.width <= 0 or args.height <= 0:
+        die(f"--width/--height must be > 0, got width={args.width} height={args.height}")
+    if args.width % 2 or args.height % 2:
+        die(f"--width/--height must be even (4:2:0 chroma), got width={args.width} height={args.height}")
+
+    meta = probe(args.input)
+    if not meta.get("video"):
+        die("input has no video stream")
+    sw, sh = meta["video"]["width"], meta["video"]["height"]
+    if meta["video"].get("rotation") in (90, -90, 270, -270):
+        sw, sh = sh, sw
+    if args.x + args.width > sw or args.y + args.height > sh:
+        die(f"crop rectangle ({args.x},{args.y},{args.width}x{args.height}) exceeds the source frame ({sw}x{sh})")
+    has_audio = bool(meta.get("audio"))
+
+    output = args.output or default_output(args.input, "crop")
+    vf = [f"crop={args.width}:{args.height}:{args.x}:{args.y}", "setsar=1"]
+    cmd = ffmpeg_base() + ["-i", args.input, "-vf", ",".join(vf)]
+    cmd += video_args(meta, args.crf, args.preset)
+    cmd += cfr_args(meta, args.fps)
+    if has_audio:
+        cmd += aac_args()
+    else:
+        cmd += ["-an"]
+    cmd.append(output)
+    run(cmd)
+
+    result = probe(output, role="output")
+    v = result["video"]
+    info(f"wrote {output} ({result['duration']:.3f}s, {v['width']}x{v['height']})")
+    emit(output)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/cut.py

@@ -5,10 +5,24 @@ Lossless stream copy (-c copy) is preferred. Cuts snap to keyframes in that
 mode, so if frame accuracy matters pass --accurate to re-encode. Multiple
 segments are cut individually and concatenated with the concat demuxer.
 
+Audio: a stream copy lands on a packet boundary (about 21 ms for AAC, one
+demuxer block for WAV); --accurate decodes and trims to the sample. The output
+extension picks the codec: -o out.wav writes PCM (never an AAC packet inside a
+WAV), -o out.m4a writes AAC; an audio extension on a video input drops the
+picture (mp4 -> wav extraction). The result reports `precision`
+(packet / sample / codec_frame / frame) and the measured duration error, plus
+`mode` (copy / accurate / hybrid -- "hybrid" means a lossless cut silently
+re-encoded because the keyframe snap exceeded --tolerance), `keyframe_snapped`,
+`requested_start`/`requested_end` (or `requested_segments` for --segments),
+`requested_duration`, `output_duration` and `duration_delta_seconds` -- so a
+caller never has to trust "it probably cut where I asked" on faith.
+
 Examples:
   python3 cut.py input.mp4 --start 00:00:10 --end 00:00:25
   python3 cut.py input.mp4 --segments 0:05-0:12,1:00-1:20 -o highlights.mp4
   python3 cut.py input.mp4 --start 3.5 --duration 10 --accurate
+  python3 cut.py talk.wav --start 1.2345 --end 2.3456 --accurate -o part.wav   # sample-exact
+  python3 cut.py talk.mp4 --start 1:00 --end 2:00 -o part.wav                   # audio extraction
 """
 import argparse
 import os
@@ -16,7 +30,7 @@ import sys
 import tempfile
 from typing import List, Tuple
 
-from _common import video_args, STATE, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, ffmpeg_base, info, parse_time, probe, run, x264_args
+from _common import video_args, STATE, add_common, apply_common, audio_codec_for, emit, aac_args, cfr_args, default_output, die, ffmpeg_base, info, is_audio_output, parse_time, probe, run
 
 
 def parse_segments(spec: str) -> List[Tuple[float, float]]:
@@ -37,21 +51,68 @@ def parse_segments(spec: str) -> List[Tuple[float, float]]:
     return segs
 
 
+def encode_args(meta: dict, dst: str, crf: int, preset: str) -> List[str]:
+    """Codec arguments for a re-encoded cut: video + AAC into a video container, otherwise the codec
+    the audio extension names (PCM for .wav, FLAC, MP3, AAC...) with no video stream."""
+    if is_audio_output(dst) or not meta.get("video"):
+        return ["-vn"] + audio_codec_for(dst)
+    return video_args(meta, crf, preset) + cfr_args(meta) + aac_args()
+
+
+def copy_args(meta: dict, dst: str) -> List[str]:
+    """Stream-copy arguments: everything into a video container, audio only into an audio extension."""
+    if is_audio_output(dst) and meta.get("video"):
+        return ["-vn", "-c:a", "copy"]
+    return ["-c", "copy"]
+
+
+LOSSLESS_AUDIO = {"pcm_s16le", "pcm_s24le", "pcm_s32le", "pcm_f32le", "flac"}
+
+
+def precision_of(meta: dict, dst: str, reencoded: bool) -> str:
+    """How exact the cut is, measured on what was written:
+
+    packet      stream copy; the cut lands on a packet (audio) or keyframe (video) boundary
+    sample      decoded audio trimmed to the sample and written losslessly (PCM / FLAC)
+    codec_frame decoded audio trimmed to the sample, then framed by a lossy encoder (AAC 1024,
+                MP3 1152, Opus 960 samples) which also adds its priming delay to the reported length
+    frame       re-encoded video: the picture is frame-exact, the audio underneath is sample-trimmed
+    """
+    if not reencoded:
+        return "packet"
+    if is_audio_output(dst) or not meta.get("video"):
+        codec = audio_codec_for(dst)[1]
+        return "sample" if codec in LOSSLESS_AUDIO else "codec_frame"
+    return "frame"
+
+
 def cut_one(src: str, start: float, end: float, dst: str, reencode: bool, crf: int, preset: str, tolerance: float = 0.5, meta: dict = None) -> bool:
     """Cut one segment. Returns True if the result was re-encoded."""
     dur = end - start
     meta = meta or probe(src)
+    audio_only = is_audio_output(dst) or not meta.get("video")
+    if not reencode and audio_only and audio_codec_for(dst)[1].startswith("pcm") and not str((meta.get("audio") or {}).get("codec", "")).startswith("pcm"):
+        info(f"{(meta.get('audio') or {}).get('codec')} packets cannot be copied into a PCM container; decoding to PCM")
+        reencode = True
     if reencode:
-        cmd = ffmpeg_base() + ["-ss", f"{start:.3f}", "-i", src, "-t", f"{dur:.3f}"]
-        cmd += video_args(meta, crf, preset) + cfr_args(meta) + aac_args() + ["-avoid_negative_ts", "make_zero", dst]
+        # -ss before -i seeks, then decoding discards samples up to the exact start (accurate_seek);
+        # atrim bounds the decoded stream to the requested length at sample resolution.
+        cmd = ffmpeg_base() + ["-ss", f"{start:.6f}", "-i", src, "-t", f"{dur:.6f}"]
+        if is_audio_output(dst) or not meta.get("video"):
+            cmd += ["-af", f"atrim=end={dur:.6f},asetpts=PTS-STARTPTS"]
+        cmd += encode_args(meta, dst, crf, preset) + ["-avoid_negative_ts", "make_zero", dst]
+    elif audio_only:
+        # output-side seek: an input seek on a video file lands on the previous video keyframe and on
+        # FLAC/MP3 on a coarse index; reading from the start and dropping packets is exact to the packet
+        cmd = ffmpeg_base() + ["-i", src, "-ss", f"{start:.6f}", "-t", f"{dur:.6f}"] + copy_args(meta, dst) + ["-avoid_negative_ts", "make_zero", dst]
     else:
-        cmd = ffmpeg_base() + ["-ss", f"{start:.3f}", "-i", src, "-t", f"{dur:.3f}", "-c", "copy", "-avoid_negative_ts", "make_zero", dst]
+        cmd = ffmpeg_base() + ["-ss", f"{start:.3f}", "-i", src, "-t", f"{dur:.3f}"] + copy_args(meta, dst) + ["-avoid_negative_ts", "make_zero", dst]
     proc = run(cmd, check=False)
     if proc.returncode != 0:
         if not reencode:
             info("stream copy failed, falling back to re-encode")
             return cut_one(src, start, end, dst, True, crf, preset, tolerance, meta)
-        die(f"ffmpeg failed:\n{proc.stderr.strip()}")
+        die(f"ffmpeg failed:\n{proc.stderr.strip()}", kind="ffmpeg")
     if not reencode and tolerance >= 0 and not STATE["dry_run"]:
         got = probe(dst).get("duration") or 0.0
         if abs(got - dur) > tolerance:
@@ -70,7 +131,7 @@ def main() -> int:
     g.add_argument("--end", help="end time")
     g.add_argument("--duration", help="duration instead of --end")
     ap.add_argument("--segments", help="comma separated START-END list, e.g. '0:05-0:12,1:00-1:20' (joined in order)")
-    ap.add_argument("--accurate", action="store_true", help="always re-encode for frame-accurate cuts (default: lossless -c copy, re-encoding only when the keyframe snap exceeds --tolerance)")
+    ap.add_argument("--accurate", action="store_true", help="always re-encode for frame-accurate (video) / sample-accurate (audio) cuts (default: lossless -c copy, re-encoding only when the keyframe snap exceeds --tolerance)")
     ap.add_argument("--tolerance", type=float, default=0.5, help="max seconds a lossless cut may deviate before re-encoding kicks in (default 0.5, -1 = never)")
     ap.add_argument("--crf", type=int, default=18, help="x264 CRF when re-encoding (default 18)")
     ap.add_argument("--preset", default="medium", help="x264 preset when re-encoding")
@@ -126,14 +187,27 @@ def main() -> int:
             proc = run(cmd, check=False)
             if proc.returncode != 0:
                 info("concat with stream copy failed, re-encoding the join")
-                cmd = ffmpeg_base() + ["-f", "concat", "-safe", "0", "-i", listfile] + video_args(meta, args.crf, args.preset) + cfr_args(meta) + aac_args() + [output]
+                cmd = ffmpeg_base() + ["-f", "concat", "-safe", "0", "-i", listfile] + encode_args(meta, output, args.crf, args.preset) + [output]
                 run(cmd)
 
-    result = probe(output)
+    result = probe(output, role="output")
     expected = sum(e - s for s, e in segments)
-    info(f"wrote {output} ({result.get('duration'):.3f}s, expected ~{expected:.3f}s, "
-         + ("re-encoded" if reencoded else "lossless stream copy") + ")")
-    emit(output)
+    precision = precision_of(meta, output, reencoded)
+    got = result.get("duration")
+    error_ms = round((got - expected) * 1000, 3) if got is not None and not STATE["dry_run"] else None
+    # mode: "copy" (untouched lossless), "accurate" (--accurate was asked for), "hybrid" (asked for
+    # lossless but the keyframe snap exceeded --tolerance so this segment silently re-encoded instead)
+    mode = "copy" if not reencoded else ("accurate" if args.accurate else "hybrid")
+    keyframe_snapped = precision == "packet"
+    info(f"wrote {output} ({got:.3f}s, expected ~{expected:.3f}s, "
+         + ("re-encoded" if reencoded else "lossless stream copy") + f", {precision} precision)")
+    emit(output, expected_duration=round(expected, 6), duration_error_ms=error_ms, precision=precision, reencoded=reencoded,
+         requested_start=round(segments[0][0], 6) if len(segments) == 1 else None,
+         requested_end=round(segments[0][1], 6) if len(segments) == 1 else None,
+         requested_segments=[[round(s, 6), round(e, 6)] for s, e in segments] if len(segments) > 1 else None,
+         requested_duration=round(expected, 6), output_duration=round(got, 6) if got is not None else None,
+         duration_delta_seconds=round(error_ms / 1000, 6) if error_ms is not None else None,
+         mode=mode, keyframe_snapped=keyframe_snapped)
     return 0
 
 

package/scripts/export.py

@@ -11,15 +11,19 @@ Presets:
   prores    ProRes 422 HQ .mov, PCM 16-bit audio (editing master)
   h265      HEVC CRF 24 (libx265) with hvc1 tag for Apple compatibility
   gif       480px wide palette-optimised GIF at 12 fps (short previews)
+  copy      stream copy, no re-encode: same codecs, container and colour
+            tags as the source (a delivery target with nothing to change)
 
 Examples:
   python3 export.py final.mp4 --preset youtube
   python3 export.py final.mp4 --preset reels --fit crop
   python3 export.py final.mp4 --preset prores -o master.mov
+  python3 export.py final.mp4 --preset copy -o delivered.mp4
   python3 export.py --list
 """
 import argparse
 import sys
+from pathlib import Path
 from typing import Dict, List
 
 from _common import STATE, add_common, apply_common, emit, cfr_args, default_output, die, ffmpeg_base, info, probe, run
@@ -32,6 +36,7 @@ PRESETS: Dict[str, Dict] = {
     "prores": {"w": None, "h": None, "ext": "mov", "video": ["-c:v", "prores_ks", "-profile:v", "3", "-vendor", "apl0", "-pix_fmt", "yuv422p10le"], "audio": ["-c:a", "pcm_s16le"], "max": None, "desc": "ProRes 422 HQ master, PCM audio, source resolution"},
     "h265": {"w": None, "h": None, "ext": "mp4", "video": ["-c:v", "libx265", "-preset", "medium", "-crf", "24", "-pix_fmt", "yuv420p", "-tag:v", "hvc1"], "audio": ["-c:a", "aac", "-b:a", "160k"], "max": None, "desc": "HEVC CRF 24, hvc1 tag, source resolution"},
     "gif": {"w": 480, "h": None, "ext": "gif", "video": [], "audio": [], "max": None, "desc": "480px palette GIF, 12fps"},
+    "copy": {"w": None, "h": None, "ext": None, "video": ["-c:v", "copy"], "audio": ["-c:a", "copy"], "max": None, "desc": "stream copy, no re-encode (source codecs/container/colour tags unchanged)"},
 }
 
 BT709 = ["-colorspace", "bt709", "-color_primaries", "bt709", "-color_trc", "bt709"]
@@ -63,10 +68,11 @@ def main() -> int:
     meta = probe(args.input)
     if not meta.get("video"):
         die("input has no video stream")
-    if meta["video"].get("hdr") and args.preset != "prores":
+    if meta["video"].get("hdr") and args.preset not in ("prores", "copy"):
         info("warning: source is HDR (%s). This preset outputs SDR BT.709 tags without tone mapping; run color.py --to-sdr first for correct colours." % meta["video"].get("hdr_format"))
     has_audio = bool(meta.get("audio"))
     output = args.output or default_output(args.input, args.preset, p["ext"])
+    out_ext = Path(output).suffix.lstrip(".").lower()
 
     vf: List[str] = []
     if p["w"] and not args.no_scale:
@@ -97,11 +103,14 @@ def main() -> int:
     if STATE["fast"] and "-preset" in video:
         video[video.index("-preset") + 1] = "veryfast"
     cmd += video
-    if "-r" not in video:
-        cmd += cfr_args(meta)
-    if args.preset not in ("prores",):
-        cmd += BT709
-    if p["ext"] == "mp4":
+    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
+        if "-r" not in video:
+            cmd += cfr_args(meta)
+        if args.preset not in ("prores",):
+            cmd += BT709
+    if out_ext == "mp4":
         cmd += ["-movflags", "+faststart"]
     cmd += (p["audio"] if has_audio else ["-an"])
     if p["max"] and not args.allow_long and (meta.get("duration") or 0) > p["max"]:
@@ -109,7 +118,7 @@ def main() -> int:
         cmd += ["-t", f"{p['max']:.3f}"]
     cmd.append(output)
     run(cmd)
-    result = probe(output)
+    result = probe(output, role="output")
     v = result["video"]
     info(f"wrote {output} ({result['duration']:.3f}s, {v['width']}x{v['height']}, {v['codec']})")
     emit(output)