ffmpeg-skill 0.8.5 → 0.10.0

package/scripts/audio.py

@@ -1,6 +1,8 @@
 #!/usr/bin/env python3
-"""Audio post: denoise, voice clean-up, background music with auto-ducking,
-fades and stereo/mono handling. Video is stream-copied.
+"""Audio post: denoise, voice clean-up, typed dynamics (compressor, limiter,
+gate), background music with auto-ducking, fades and stereo/mono handling.
+Video is stream-copied; an audio output extension (.wav/.flac/.mp3/.m4a/...)
+drops the picture, so `audio.py talk.mp4 -o talk.wav` is an extraction.
 
 Examples:
   python3 audio.py interview.mp4 --denoise                      # FFT noise reduction
@@ -10,15 +12,65 @@ Examples:
   python3 audio.py clip.mp4 --fade-in 0.5 --fade-out 1 --stereo
   python3 audio.py surround.mov --downmix                       # 5.1 -> stereo with proper centre/LFE weights
   python3 audio.py clip.mp4 --replace narration.wav             # swap the audio track entirely
+  python3 audio.py interview.mp4 -o interview.wav               # extract the audio (no video in the output)
+  python3 audio.py multi.mkv --audio-stream 1 --voice -o lav.m4a # pick the second audio track, clean it, write M4A
+  python3 audio.py talk.wav --compress --comp-threshold -20 --comp-ratio 4 --limit --limit-ceiling -1 -o talk_dyn.wav
 """
 import argparse
 import sys
 from typing import List
 
-from _common import add_common, apply_common, emit, audio_codec_for, default_output, die, ffmpeg_base, info, probe, run
+from _common import STATE, add_common, apply_common, audio_codec_for, db_to_linear, default_output, die, emit, ffmpeg_base, info, is_audio_output, probe, run
 
 VOICE_CHAIN = "highpass=f=80,deesser=i=0.4,afftdn=nf=-25:tn=1,acompressor=threshold=-18dB:ratio=3:attack=5:release=80:makeup=2"
 
+# Typed dynamics: every flag maps to one real option of one ffmpeg filter, validated against the
+# range that filter documents (ffmpeg -h filter=acompressor / alimiter / agate). dB flags are
+# converted to the linear value the filter takes, so no string reaches the graph unchecked.
+DYNAMICS = {
+    "acompressor": {
+        "comp_threshold": ("threshold", "dB", -60.0, 0.0),        # 0.000976563..1 linear
+        "comp_ratio": ("ratio", "x", 1.0, 20.0),
+        "comp_attack": ("attack", "ms", 0.01, 2000.0),
+        "comp_release": ("release", "ms", 0.01, 9000.0),
+        "comp_makeup": ("makeup", "dB", 0.0, 36.0),               # 1..64 linear
+        "comp_knee": ("knee", "dB", 1.0, 8.0),
+    },
+    "alimiter": {
+        "limit_ceiling": ("limit", "dB", -24.0, 0.0),             # 0.0625..1 linear
+        "limit_attack": ("attack", "ms", 0.1, 80.0),
+        "limit_release": ("release", "ms", 1.0, 8000.0),
+    },
+    "agate": {
+        "gate_threshold": ("threshold", "dB", -60.0, 0.0),        # 0..1 linear
+        "gate_ratio": ("ratio", "x", 1.0, 9000.0),
+        "gate_attack": ("attack", "ms", 0.01, 9000.0),
+        "gate_release": ("release", "ms", 0.01, 9000.0),
+        "gate_range": ("range", "dB", -90.0, 0.0),                # 0..1 linear: how far the gate closes
+        "gate_knee": ("knee", "dB", 1.0, 8.0),
+    },
+}
+
+
+def dynamics_filter(name: str, args: argparse.Namespace) -> str:
+    """One validated `acompressor=...` / `alimiter=...` / `agate=...` filter string from typed flags."""
+    opts = []
+    for flag, (opt, unit, lo, hi) in DYNAMICS[name].items():
+        value = getattr(args, flag)
+        if value is None:
+            continue
+        if not (lo <= value <= hi):
+            die(f"--{flag.replace('_', '-')} {value:g} is outside {lo:g}..{hi:g} {unit if unit != 'x' else ''}".rstrip()
+                + f" (the range ffmpeg's {name} accepts)")
+        if unit == "dB":
+            # the filters take linear amplitude (agate range: -90 dB -> 0.00003 closed, 0 dB -> 1 open)
+            opts.append(f"{opt}={db_to_linear(value):.6g}")
+        else:
+            opts.append(f"{opt}={value:g}")
+    if name == "alimiter":
+        opts.append("level=disabled")  # keep the level: a limiter must not normalise the whole track upwards
+    return name + ("=" + ":".join(opts) if opts else "")
+
 
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
@@ -43,10 +95,33 @@ def main() -> int:
     fades.add_argument("--mono", action="store_true", help="force 1-channel output")
     fades.add_argument("--downmix", action="store_true", help="downmix 5.1/7.1 to stereo using standard weights")
     fades.add_argument("--replace", help="replace the audio with this file (trimmed/padded to the video)")
+    dyn = ap.add_argument_group("dynamics (typed; each flag is one option of ffmpeg's acompressor / alimiter / agate)")
+    dyn.add_argument("--compress", action="store_true", help="compressor (acompressor); order: gate -> compressor -> limiter")
+    dyn.add_argument("--comp-threshold", type=float, help="dBFS above which gain is reduced, -60..0 (ffmpeg default -12.4)")
+    dyn.add_argument("--comp-ratio", type=float, help="ratio 1..20 (default 2)")
+    dyn.add_argument("--comp-attack", type=float, help="ms 0.01..2000 (default 20)")
+    dyn.add_argument("--comp-release", type=float, help="ms 0.01..9000 (default 250)")
+    dyn.add_argument("--comp-makeup", type=float, help="make-up gain dB 0..36 (default 0)")
+    dyn.add_argument("--comp-knee", type=float, help="knee dB 1..8 (default 2.83)")
+    dyn.add_argument("--limit", action="store_true", help="look-ahead limiter (alimiter), level left as is")
+    dyn.add_argument("--limit-ceiling", type=float, help="ceiling dBFS -24..0 (default 0)")
+    dyn.add_argument("--limit-attack", type=float, help="ms 0.1..80 (default 5)")
+    dyn.add_argument("--limit-release", type=float, help="ms 1..8000 (default 50)")
+    dyn.add_argument("--gate", action="store_true", help="noise gate (agate)")
+    dyn.add_argument("--gate-threshold", type=float, help="dBFS below which the gate closes, -60..0 (default -18.1)")
+    dyn.add_argument("--gate-ratio", type=float, help="ratio 1..9000 (default 2)")
+    dyn.add_argument("--gate-attack", type=float, help="ms 0.01..9000 (default 20)")
+    dyn.add_argument("--gate-release", type=float, help="ms 0.01..9000 (default 250)")
+    dyn.add_argument("--gate-range", type=float, help="attenuation when closed, dB -90..0 (default -6.1)")
+    dyn.add_argument("--gate-knee", type=float, help="knee dB 1..8 (default 2.83)")
+    ap.add_argument("--audio-stream", type=int, default=0, help="which audio stream of the input to process, 0-based in file order (probe lists them under audio_streams)")
     ap.add_argument("--bitrate", default="192k")
     add_common(ap)
     args = ap.parse_args()
     apply_common(args)
+    for flag_group, switch in (("acompressor", "compress"), ("alimiter", "limit"), ("agate", "gate")):
+        if not getattr(args, switch) and any(getattr(args, f) is not None for f in DYNAMICS[flag_group]):
+            die(f"--{switch} is off but one of its parameters was given; add --{switch}")
 
     meta = probe(args.input)
     dur = meta.get("duration") or 0.0
@@ -54,9 +129,15 @@ def main() -> int:
     if not meta.get("audio") and not args.replace:
         die("input has no audio stream (use --replace to add one)")
     output = args.output or default_output(args.input, "audio")
+    audio_out = is_audio_output(output)
+    streams = meta.get("audio_streams") or []
+    if streams and not (0 <= args.audio_stream < len(streams)) and not STATE["dry_run"]:
+        die(f"--audio-stream {args.audio_stream}: input has {len(streams)} audio stream(s), 0..{len(streams) - 1}")
+    if args.audio_stream and not streams and not STATE["dry_run"]:
+        die("--audio-stream needs an input with audio streams")
 
     inputs: List[str] = ["-i", args.input]
-    main_src = "0:a:0"
+    main_src = f"0:a:{args.audio_stream}"
     idx = 1
     if args.replace:
         probe(args.replace)
@@ -73,6 +154,12 @@ def main() -> int:
         fx.append(f"afftdn=nf=-{args.denoise_strength:g}:tn=1")
     if args.gain:
         fx.append(f"volume={args.gain:g}dB")
+    if args.gate:
+        fx.append(dynamics_filter("agate", args))
+    if args.compress:
+        fx.append(dynamics_filter("acompressor", args))
+    if args.limit:
+        fx.append(dynamics_filter("alimiter", args))
     if args.mono:
         fx.append("pan=mono|c0=0.5*c0+0.5*c1")
     elif args.stereo:
@@ -116,14 +203,20 @@ def main() -> int:
         last = "out"
 
     cmd = ffmpeg_base() + inputs + ["-filter_complex", ";".join(graph), "-map", f"[{last}]"]
-    if has_video:
+    if has_video and not audio_out:
         cmd += ["-map", "0:v:0", "-c:v", "copy"]
+    elif has_video:
+        cmd += ["-vn"]  # audio extension: the picture is dropped, not copied into a container that cannot hold it
     cmd += audio_codec_for(output, args.bitrate) + ["-shortest", output]
     run(cmd)
     r = probe(output)
     a = r["audio"]
-    info(f"wrote {output} ({r['duration']:.3f}s, audio {a['codec']} {a['channels']}ch {a['sample_rate']}Hz)")
-    emit(output)
+    if r.get("video") and audio_out and not STATE["dry_run"]:
+        die(f"{output} unexpectedly contains a video stream")
+    info(f"wrote {output} ({r['duration']:.3f}s, audio {a['codec']} {a['channels']}ch {a['sample_rate']}Hz"
+         + (", video stream-copied" if has_video and not audio_out else ", video dropped" if has_video else "") + ")")
+    emit(output, video=bool(has_video and not audio_out), audio_stream=args.audio_stream,
+         dynamics=[f for f in (args.gate and "agate", args.compress and "acompressor", args.limit and "alimiter") if f])
     return 0
 
 

package/scripts/caption.py

@@ -4,6 +4,12 @@
 Styling (font, size, colour, outline, position) applies to SRT input via
 libass force_style. ASS files carry their own styles and are rendered as-is.
 
+This only burns subtitles into the picture. There is no soft-subtitle (mux a
+subtitle stream, toggleable by the player) path -- every call re-encodes the
+whole video and its audio (see contract --json: reencodes_video/reencodes_audio
+are both "always" for this tool), even for a source that only needed the
+subtitle track added.
+
 Text-to-SRT input format (one cue per line, blank lines ignored):
   0:00-0:03 Hello and welcome
   00:00:03.500 --> 00:00:06 Second line | with a manual line break
@@ -23,7 +29,7 @@ import sys
 from pathlib import Path
 from typing import List, Optional, Tuple
 
-from _common import color_hex, load_brand, video_args, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, fmt_srt_time, info, parse_time, probe, run, x264_args
+from _common import STATE, color_hex, load_brand, video_args, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, fmt_srt_time, info, parse_time, probe, run, x264_args
 
 ALIGN = {"bottom": 2, "top": 8, "center": 5, "bottom-left": 1, "bottom-right": 3, "top-left": 7, "top-right": 9}
 
@@ -352,7 +358,8 @@ def main() -> int:
             srt_path = os.path.splitext(out_guess)[0] + ".srt"
         else:
             srt_path = os.path.splitext(args.text)[0] + ".srt"
-        write_srt(cues, srt_path)
+        if not STATE.dry_run:
+            write_srt(cues, srt_path)
         info(f"wrote {srt_path} ({len(cues)} cues)")
         if not args.input:
             print(srt_path)
@@ -382,7 +389,7 @@ def main() -> int:
         if args.fonts_dir:
             vf += f":fontsdir={escape_filter_path(args.fonts_dir)}"
     else:
-        if not srt_path or not os.path.exists(srt_path):
+        if not srt_path or (not os.path.exists(srt_path) and not (STATE.dry_run and args.text)):
             die(f"SRT file not found: {srt_path}")
         style = [
             f"FontName={args.font}",

package/scripts/check.py

@@ -3,7 +3,12 @@
 
 Checks duration, frame size / aspect, fps, codec, pixel format, colour tags,
 file size, integrated loudness and true peak against the chosen platform
-and prints a PASS/WARN/FAIL table. Exit code 1 when anything FAILs.
+and prints a PASS/WARN/FAIL table. Exit code 1 when anything FAILs. Each
+row's `fix` is the command that resolves it; a few of the less obvious FAILs
+(video codec, pixel format, HDR colour, loudness) also carry a plain-language
+`reason` -- "QuickTime and iOS commonly reject video that isn't 8-bit 4:2:0",
+not a restatement of the spec value -- for a caller reporting this to someone
+who doesn't already know why the spec says what it says.
 
 Platforms: youtube, shorts, reels, tiktok, x, linkedin, broadcast (EBU R128), podcast, custom
 
@@ -88,10 +93,13 @@ def main() -> int:
 
     JUDGEMENT = {"duration", "aspect", "loudness", "fps", "resolution"}
 
-    def row(name: str, status: str, value: Any, expect: Any, fix: str = "") -> None:
+    def row(name: str, status: str, value: Any, expect: Any, fix: str = "", reason: str = "") -> None:
         # "format" rows are safe to fix mechanically; "judgement" rows change the content
-        # (what is cut, what is cropped, how loud ambience gets) and need a decision
+        # (what is cut, what is cropped, how loud ambience gets) and need a decision.
+        # "fix" is the command that resolves it; "reason" (only on the FAILs a non-technical
+        # person would ask "so what?" about) is why it matters in plain terms, not the spec clause.
         rows.append({"check": name, "status": status, "value": value, "expected": expect, "fix": fix,
+                     "reason": reason if status != "PASS" else "",
                      "kind": "judgement" if name in JUDGEMENT else "format"})
 
     dur = meta.get("duration") or 0.0
@@ -117,12 +125,15 @@ def main() -> int:
             row("fps", "PASS" if fps <= spec["fps_max"] + 0.01 else "FAIL", f"{fps:g}", f"<= {spec['fps_max']}", "fit.py --fps 30 (drops half the frames of 60 fps motion; fine for talking heads, visible on sports/gaming)")
         row("vfr", "PASS" if not v.get("variable_frame_rate_suspected") else "WARN", "variable" if v.get("variable_frame_rate_suspected") else "constant", "constant", "fit.py --fps N (any re-encode conforms it)")
         if spec["codecs"]:
-            row("video codec", "PASS" if v.get("codec") in spec["codecs"] else "FAIL", v.get("codec"), "/".join(spec["codecs"]), "export.py --preset " + args.platform.replace("shorts", "reels").replace("tiktok", "reels").replace("linkedin", "youtube"))
+            row("video codec", "PASS" if v.get("codec") in spec["codecs"] else "FAIL", v.get("codec"), "/".join(spec["codecs"]), "export.py --preset " + args.platform.replace("shorts", "reels").replace("tiktok", "reels").replace("linkedin", "youtube"),
+                reason="the platform's player may refuse to decode this codec at all, not just look worse")
         pf = v.get("pix_fmt") or ""
         if args.platform in ("reels", "tiktok", "x", "linkedin"):
-            row("pixel format", "PASS" if pf == "yuv420p" else "FAIL", pf, "yuv420p (8-bit 4:2:0)", "export.py preset re-encodes to yuv420p")
+            row("pixel format", "PASS" if pf == "yuv420p" else "FAIL", pf, "yuv420p (8-bit 4:2:0)", "export.py preset re-encodes to yuv420p",
+                reason="QuickTime and iOS commonly reject video that isn't 8-bit 4:2:0")
         if spec["sdr_only"] and v.get("hdr"):
-            row("colour", "FAIL", v.get("hdr_format"), "SDR BT.709", "color.py --to-sdr")
+            row("colour", "FAIL", v.get("hdr_format"), "SDR BT.709", "color.py --to-sdr",
+                reason="a platform or player without HDR support will show this washed-out, too dark, or with wrong colours -- not a rendering glitch, a colour space mismatch")
         else:
             tags = (v.get("color_primaries"), v.get("color_transfer"))
             untagged = not tags[0] and not tags[1]
@@ -148,7 +159,8 @@ def main() -> int:
             lm = measure_loudness(args.input)
             if lm:
                 diff = abs(lm["lufs"] - spec["lufs"])
-                row("loudness", "PASS" if diff <= spec["lufs_tol"] else "FAIL", f"{lm['lufs']:.1f} LUFS", f"{spec['lufs']:g} ± {spec['lufs_tol']:g} LUFS", f"loudness.py -I {spec['lufs']:g} for speech or music; leave ambience/near-silence (<= -40 LUFS) alone and say so")
+                row("loudness", "PASS" if diff <= spec["lufs_tol"] else "FAIL", f"{lm['lufs']:.1f} LUFS", f"{spec['lufs']:g} ± {spec['lufs_tol']:g} LUFS", f"loudness.py -I {spec['lufs']:g} for speech or music; leave ambience/near-silence (<= -40 LUFS) alone and say so",
+                    reason="the platform will auto-normalise it to its own target anyway, which can pump or duck the mix in ways you did not choose")
                 row("true peak", "PASS" if lm["tp"] <= spec["tp"] + 0.05 else "FAIL", f"{lm['tp']:.1f} dBTP", f"<= {spec['tp']:g} dBTP", f"loudness.py --tp {spec['tp']:g}")
     elif args.platform in ("podcast",):
         row("audio", "FAIL", "none", "audio stream", "audio.py --replace")
@@ -164,6 +176,8 @@ def main() -> int:
             line = f"  {r['status']:4s} {r['check']:{width}s}  {r['value']}  (expected {r['expected']})"
             if r["status"] != "PASS" and r["kind"] == "judgement":
                 line += "  [judgement]"
+            if r["status"] != "PASS" and r["reason"]:
+                line += f"  ({r['reason']})"
             if r["status"] != "PASS" and r["fix"]:
                 line += f"  -> {r['fix']}"
             print(line)

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,17 @@ 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("--crf", type=int, default=18)
     ap.add_argument("--preset", default="medium")
     add_common(ap)
@@ -106,12 +158,20 @@ def main() -> int:
         emit(output)
         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}")
@@ -130,7 +190,11 @@ def main() -> int:
     r = probe(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/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,15 +51,62 @@ 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:
@@ -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)
     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"]: