ffmpeg-skill 3.1.8 → 3.2.0

package/scripts/loop.py

@@ -4,11 +4,15 @@
 For a background loop, an ambient bed, or filling a fixed slot length with
 a short clip. --times repeats the whole clip that many times back to back;
 --duration instead loops (and, on the last repeat, trims) to hit an exact
-target length. Audio loops along with the video when present. This tool
-does not smooth the loop point (no crossfade at the seam) -- a clip that
-doesn't already loop cleanly will show a visible cut/pop at each repeat;
-that's a judgement call about the source material, not something a --times
-or --duration flag can fix. --boomerang is the exception: it plays the clip
+target length. Audio loops along with the video when present. Without
+--crossfade the loop point is not smoothed: a clip that doesn't already loop
+cleanly shows a visible cut/pop at each repeat. --crossfade S makes the clip
+loop first: its last S seconds fade into its first S (picture and sound), so
+one repeat is S shorter than the clip and every seam continues the motion;
+--times 1 then writes a single seamless loop file. Every run measures its
+seam (the picture step and the sound level step where a repeat meets the
+next) and reports it next to the steady frame-to-frame step, so a caller can
+see whether the seam still jumps. --boomerang is the other way: it plays the clip
 forward, then backward, so every repeat meets frames that match. Each
 turnaround frame is shown once (frames 0..N-1, then N-2..1), so the motion
 does not stall at either end. A boomerang is silent, because reversed sound
@@ -19,6 +23,7 @@ Examples:
   python3 loop.py bg_loop.mp4 --times 3
   python3 loop.py texture.mp4 --duration 30
   python3 loop.py wave.mp4 --boomerang --times 4
+  python3 loop.py smoke.mp4 --crossfade 1 --duration 60
 """
 import argparse
 import json
@@ -27,9 +32,10 @@ import os
 import sys
 import tempfile
 
-from _common import concat_list_line, add_common, aac_args, apply_common, cfr_args, default_output, die, emit, ffmpeg_base, info, parse_time, probe, refuse_output_is_input, require_tool, run, video_args, X264_PRESETS, time_arg, fmt_secs
+from _common import STATE, concat_list_line, add_common, aac_args, apply_common, cfr_args, default_output, die, emit, ffmpeg_base, info, parse_time, probe, refuse_output_is_input, require_filter, require_tool, run, video_args, X264_PRESETS, time_arg, fmt_secs
 from _common.emit import warn
 from _common.decision import av_trim
+from _common.probe import decode_gray_frames, decode_pcm_mono
 
 
 # The loop filter's size is capped at 32767 frames, so one boomerang cycle (2N-2 frames) must fit.
@@ -114,6 +120,113 @@ def concat_first_frame(listfile: str) -> float:
         return 0.0
 
 
+def _frame_count(v, rate: float, src_dur: float) -> int:
+    return int(v.get("nb_frames") or round((v.get("duration") or src_dur) * rate))
+
+
+def _conformed_frames(v, rate: float, src_dur: float) -> int:
+    """The frames the crossfade's graph sees: the picture after fps=RATE, which fills a gap in a
+    variable-rate stream and drops crowded frames, so its count follows the stream's length, not
+    the frames stored (299 stored frames over 10 s at 30 fps come out 300). The unit's trims and
+    its length are counted in these, or a repeat is a frame or more off the length planned."""
+    # the video stream's length, else Matroska's tag, else the container's (main() refuses a source
+    # without one): never the stored frame count, which is what fps= does not keep
+    d = v.get("duration") or v.get("tagged_duration") or src_dur
+    return int(round(float(d) * rate))
+
+
+def _seamless_unit_cmd(meta, src: str, unit: str, rate: str, frames: int, fade_frames: int, has_audio: bool) -> list:
+    """One repeat that loops on itself: the clip's last `fade_frames` fade into its first ones.
+
+    The tail (frames N-F..N-1) is laid over the head (frames 0..F-1) with xfade, so the repeat
+    starts on frame N-F, the frame the clip's own frame N-F-1 leads into: the repeat's end runs
+    straight on into its start. Frames F..N-F-1 follow unchanged; the repeat is N-F frames. The
+    sound does the same on the picture's clock (padded with silence to the picture's length
+    first, so a short or late sound cannot shorten the fade). Written lossless
+    (FFV1 + FLAC) to a temporary file the concat list then repeats, so the repeats cost one
+    lossy encode, as without --crossfade."""
+    fps = _fraction(rate) or 30.0
+    fade = fade_frames / fps
+    cut = (frames - fade_frames) / fps
+    length = frames / fps
+    # each branch re-states its rate after setpts: FFmpeg 7.x's setpts marks the frame rate
+    # unknown (1/0) and xfade refuses anything but a constant one (6.1 kept it)
+    graph = (f"[0:v:0]setpts=PTS-STARTPTS,fps={rate},split[vt][vb];"
+             f"[vt]trim=start_frame={frames - fade_frames}:end_frame={frames},setpts=PTS-STARTPTS,fps={rate}[t];"
+             f"[vb]trim=end_frame={frames - fade_frames},setpts=PTS-STARTPTS,fps={rate}[b];"
+             f"[t][b]xfade=transition=fade:duration={fade:.6f}:offset=0[v]")
+    maps = ["-map", "[v]"]
+    if has_audio:
+        # acrossfade writes nothing when its first input is exactly the fade long (FFmpeg 6.1 and
+        # 7.1, measured), so the fade is built by hand: tail faded out + head faded in, summed
+        graph += (f";[0:a:0]aresample=async=1:first_pts=0,apad,atrim=end={length:.6f},asplit=3[at][ah][ab];"
+                  f"[at]atrim=start={cut:.6f},asetpts=PTS-STARTPTS,afade=t=out:d={fade:.6f}:curve=tri[ta];"
+                  f"[ah]atrim=end={fade:.6f},asetpts=PTS-STARTPTS,afade=t=in:d={fade:.6f}:curve=tri[ha];"
+                  f"[ta][ha]amix=inputs=2:normalize=0:duration=longest[xa];"
+                  f"[ab]atrim=start={fade:.6f}:end={cut:.6f},asetpts=PTS-STARTPTS[ba];"
+                  f"[xa][ba]concat=n=2:v=0:a=1[a]")
+        maps += ["-map", "[a]", "-c:a", "flac"]
+    else:
+        maps += ["-an"]
+    return ffmpeg_base() + ["-i", src, "-filter_complex", graph] + maps + ["-c:v", "ffv1", "-fps_mode", "passthrough", unit]
+
+
+# Frames are compared at this size: enough to see a cut or a jump, a few KB per frame.
+SEAM_W, SEAM_H = 64, 36
+
+
+def _mean_step(a: bytes, b: bytes) -> float:
+    return sum(abs(x - y) for x, y in zip(a, b)) / max(1, len(a))
+
+
+def _rms_db(block) -> "float | None":
+    if not block:
+        return None
+    rms = math.sqrt(sum(x * x for x in block) / len(block))
+    return 20 * math.log10(rms) if rms > 1e-6 else -120.0
+
+
+def _measure_seam(output: str, unit: float, out_dur: float, fps: float, has_audio: bool) -> dict:
+    """The first seam of the written file, where repeat 1 meets repeat 2 (or, for a single repeat,
+    the file's last frame against its first, as a player looping it would show them).
+
+    video_step: the mean absolute luma difference (0-255, on a 64x36 grey copy) across the seam;
+    video_typical_step: the median of the same difference between the neighbouring frames, so a
+    caller can tell a seam that jumps (step far above typical) from a clip that is busy anyway.
+    audio_level_step_db: the RMS level 20 ms after the seam minus 20 ms before it."""
+    half = min(0.5, unit / 2)
+    if out_dur - unit > 1.5 / fps:
+        frames = decode_gray_frames(output, fps, SEAM_W, SEAM_H, start=unit - half, seconds=2 * half, check=False)
+        at = round(half * fps)
+        pair = (frames[at - 1], frames[at]) if 0 < at < len(frames) else None
+        where = "between_repeats"
+    else:
+        head = decode_gray_frames(output, fps, SEAM_W, SEAM_H, seconds=half, check=False)
+        tail = decode_gray_frames(output, fps, SEAM_W, SEAM_H, start=max(0.0, out_dur - half), check=False)
+        frames = tail + head
+        at = len(tail)
+        pair = (tail[-1], head[0]) if tail and head else None
+        where = "end_to_start"
+    seam = {"at": where, "time": round(unit, 3) if where == "between_repeats" else None}
+    if pair:
+        steps = [_mean_step(frames[i - 1], frames[i]) for i in range(1, len(frames)) if i != at]
+        seam["video_step"] = round(_mean_step(*pair), 2)
+        seam["video_typical_step"] = round(sorted(steps)[len(steps) // 2], 2) if steps else None
+    else:
+        seam["video_step"] = seam["video_typical_step"] = None
+    if has_audio:
+        rate, win = 48000, 0.02
+        if where == "between_repeats":
+            pcm = decode_pcm_mono(output, rate, seconds=2 * win, start=unit - win, check=False)
+            before, after = pcm[: int(rate * win)], pcm[int(rate * win):]
+        else:
+            after = decode_pcm_mono(output, rate, seconds=win, check=False)
+            before = decode_pcm_mono(output, rate, start=max(0.0, out_dur - win), check=False)
+        b, a = _rms_db(before), _rms_db(after)
+        seam["audio_level_step_db"] = round(a - b, 1) if a is not None and b is not None else None
+    return seam
+
+
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("input")
@@ -123,6 +236,9 @@ def main() -> int:
     group.add_argument("--duration", help="loop (and trim the last repeat) to hit exactly this target duration (seconds or mm:ss)")
     ap.add_argument("--boomerang", action="store_true",
                     help="play forward then backward (--times counts round trips; 1 is allowed); drops audio")
+    ap.add_argument("--crossfade", metavar="S",
+                    help="fade the clip's last S seconds into its first S (picture and sound) so every seam is smooth; "
+                         "one repeat is then S shorter than the clip, and --times 1 writes one seamless loop")
     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, help="x264 preset")
     add_common(ap)
@@ -141,17 +257,39 @@ def main() -> int:
     # the concat list is the only -i, so run() never sees the source next to -o (#416 review)
     refuse_output_is_input(output, args.input)
 
+    v = meta["video"]
+    rate = _nominal_rate(v)
+    fps = _fraction(rate) or 30.0
+    unit = src_dur  # the length one repeat adds
+    fade_frames = 0
+    if args.crossfade is not None:
+        if args.boomerang:
+            die("--crossfade and --boomerang cannot be combined: a boomerang's turnarounds already meet matching frames")
+        frames = _conformed_frames(v, fps, src_dur)
+        require_filter("xfade", "--crossfade")
+        fade = time_arg(args.crossfade, "--crossfade", v.get("fps"))
+        if not math.isfinite(fade):
+            die(f"--crossfade must be a finite number of seconds, got {args.crossfade!r}")
+        fade_frames = round(fade * fps)
+        if fade_frames < 1:
+            die(f"--crossfade {args.crossfade!r} is shorter than one frame ({1 / fps:.3f}s at {fps:g} fps)")
+        if 2 * fade_frames > frames:
+            die(f"--crossfade ({fade_frames / fps:.3f}s) must be at most half the clip ({frames / fps:.3f}s): "
+                f"the fade lays the clip's end over its start, and the two must not overlap")
+        unit = (frames - fade_frames) / fps
+
     if args.times is not None:
-        if args.times < (1 if args.boomerang else 2):
-            die(f"--times must be >= 1 with --boomerang, got {args.times}" if args.boomerang else
-                f"--times must be >= 2 (1 is just the original clip), got {args.times}")
+        least = 1 if (args.boomerang or fade_frames) else 2
+        if args.times < least:
+            die(f"--times must be >= 1, got {args.times}" if least == 1 else
+                f"--times must be >= 2 (1 is just the original clip; with --crossfade, 1 writes one seamless loop), got {args.times}")
         target = None
         stream_loop = args.times - 1
     else:
-        target = time_arg(args.duration, "--duration", meta["video"].get("fps") if meta.get("video") else None)
-        if target <= src_dur:
-            die(f"--duration ({target:g}s) must be longer than the source ({src_dur:.3f}s) -- use cut.py to trim instead")
-        stream_loop = math.ceil(target / src_dur) - 1
+        target = time_arg(args.duration, "--duration", v.get("fps"))
+        if target <= unit:
+            die(f"--duration ({target:g}s) must be longer than one repeat ({unit:.3f}s) -- use cut.py to trim instead")
+        stream_loop = math.ceil(target / unit) - 1
 
     if args.boomerang:
         cmd = ffmpeg_base() + ["-i", args.input, "-filter_complex", _boomerang_graph(meta, src_dur, args.times), "-map", "[v]"]
@@ -167,8 +305,12 @@ def main() -> int:
         # late sound leaves at each repeat's start is filled with silence, at any length.
         workdir = tempfile.TemporaryDirectory(prefix="ffskill_loop_")
         listfile = os.path.join(workdir.name, "loop.txt")
+        repeat = os.path.abspath(args.input)
+        if fade_frames:
+            repeat = os.path.join(workdir.name, "unit.mkv")
+            run(_seamless_unit_cmd(meta, args.input, repeat, rate, _conformed_frames(v, fps, src_dur), fade_frames, has_audio))
         with open(listfile, "w", encoding="utf-8") as fh:
-            fh.write((concat_list_line(os.path.abspath(args.input)) + "\n") * (stream_loop + 1))
+            fh.write((concat_list_line(repeat) + "\n") * (stream_loop + 1))
         vtrim, atrim = av_trim(concat_first_frame(listfile), None, fill_gaps=True)
         cmd = ffmpeg_base() + ["-f", "concat", "-safe", "0", "-i", listfile]
         if has_audio:
@@ -179,7 +321,9 @@ def main() -> int:
     if target is not None:
         cmd += ["-t", f"{target:.3f}"]
     cmd += video_args(meta, args.crf, args.preset)
-    cmd += ["-fps_mode", "passthrough"] if args.boomerang else cfr_args(meta)
+    # a crossfade's repeat is already constant at `rate` (its graph's fps=): the loop keeps that rate,
+    # not a variable-rate source's average, which re-timed every repeat by a frame or two
+    cmd += ["-fps_mode", "passthrough"] if args.boomerang else cfr_args(meta, fps if fade_frames and v.get("variable_frame_rate_suspected") else None)
     if has_audio:
         cmd += aac_args()
     else:
@@ -191,13 +335,33 @@ def main() -> int:
         if not args.boomerang:
             workdir.cleanup()
 
+    extra = {"boomerang": args.boomerang}
+    if fade_frames:
+        extra["crossfade"] = round(fade_frames / fps, 6)
+    requested = target if target is not None else (
+        args.times * (2 * _frame_count(v, fps, src_dur) - 2) / fps if args.boomerang else args.times * unit)
+    if STATE.dry_run:
+        emit(output, expected_duration=round(requested, 3), **extra, **({"notes": notes} if notes else {}))
+        return 0
     result = probe(output, role="output")
-    v = result["video"]
-    info(f"wrote {output} ({fmt_secs(result['duration'])}, {v['width']}x{v['height']}, source {src_dur:.3f}s "
+    rv = result["video"]
+    out_dur = result.get("duration") or 0.0
+    # the length asked for (repeats x one repeat, or --duration), against the file: within a frame
+    # and a half, the slack the last repeat's trim and the encoder's final frame leave
+    tolerance = 1.5 / fps
+    verification = [{"step": "duration", "requested": round(requested, 3), "measured": round(out_dur, 3),
+                     "tolerance": round(tolerance, 3), "ok": abs(out_dur - requested) <= tolerance}]
+    if not args.boomerang:
+        extra["seam"] = _measure_seam(output, unit, out_dur, fps, has_audio)
+    info(f"wrote {output} ({fmt_secs(result['duration'])}, {rv['width']}x{rv['height']}, source {src_dur:.3f}s "
          f"{'boomeranged' if args.boomerang else 'looped'})")
     for note in notes:
         info(note)
-    emit(output, boomerang=args.boomerang, **({"notes": notes} if notes else {}))
+    # the streams the run must have written: a crossfade unit whose sound came out empty once left
+    # a silent loop that still said verified: true
+    emit(output, expected_duration=round(requested, 3), verification=verification,
+         expect_streams={"video": 1, "audio": 1 if has_audio else 0}, **extra,
+         **({"notes": notes} if notes else {}))
     return 0
 
 

package/scripts/loudness.py

@@ -27,6 +27,40 @@ from _common import STATE, add_common, apply_common, emit, AUDIO_CODECS, audio_c
 
 
 
+# --versions' named targets: integrated loudness (LUFS) and true-peak ceiling (dBTP)
+VERSION_TARGETS = {
+    "streaming": (-14.0, -1.0),     # YouTube, Spotify and most streaming services
+    "ebu-r128": (-23.0, -1.0),      # EBU R128 broadcast
+    "broadcast-jp": (-24.0, -1.0),  # ARIB TR-B32 (Japanese broadcast, LKFS = LUFS)
+}
+
+
+def parse_versions(text: str) -> "list":
+    """[(label, lufs, tp)] from --versions; a refusal names the item that did not parse."""
+    out, seen = [], set()
+    for item in (x.strip() for x in text.split(",")):
+        if not item:
+            continue
+        if item in VERSION_TARGETS:
+            label, (lufs, tp) = item, VERSION_TARGETS[item]
+        else:
+            try:
+                lufs_s, tp_s = item.split("/")
+                lufs, tp = float(lufs_s), float(tp_s)
+            except ValueError:
+                die(f"--versions item {item!r} is neither a named target ({', '.join(VERSION_TARGETS)}) nor LUFS/TP such as -16/-1.5")
+            if not (-70 <= lufs <= -5 and -9 <= tp <= 0):
+                die(f"--versions item {item!r}: LUFS must be -70..-5 and TP -9..0 (loudnorm's ranges)")
+            label = f"{lufs:g}lufs{tp:g}tp".replace("-", "m").replace(".", "_")
+        if label in seen:
+            die(f"--versions names {label!r} twice")
+        seen.add(label)
+        out.append((label, lufs, tp))
+    if not out:
+        die("--versions is empty")
+    return out
+
+
 def measure(path: str, I: float, tp: float, lra: float) -> dict:
     if dry_run_input_pending(path):
         return {"input_i": "-20.0", "input_tp": "-3.0", "input_lra": "8.0", "input_thresh": "-30.0", "target_offset": "0.0", "silent": False, "placeholder": True}
@@ -47,46 +81,10 @@ def measure(path: str, I: float, tp: float, lra: float) -> dict:
     return data
 
 
-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>_loudnorm.<ext>)")
-    ap.add_argument("-I", "--lufs", type=float, default=-14.0, help="integrated loudness target in LUFS (default -14)")
-    ap.add_argument("--tp", type=float, default=-1.0, help="true peak ceiling in dBTP (default -1)")
-    ap.add_argument("--lra", type=float, default=11.0, help="loudness range target in LU (default 11)")
-    ap.add_argument("--measure-only", action="store_true", help="print the measured stats as JSON and exit")
-    ap.add_argument("--audio-bitrate", default=None, help="AAC bitrate when the container is video (default 192k; raised to 256k/320k only when the encoder overshoots the true-peak ceiling and you did not pin it)")
-    ap.add_argument("--sample-rate", type=int, help="output sample rate (default: 48000; loudnorm upsamples internally to 192k)")
-    add_common(ap)
-    args = ap.parse_args()
-    apply_common(args)
-
-    meta = probe(args.input)
-    if not meta.get("audio"):
-        die("input has no audio stream")
-
-    stats = measure(args.input, args.lufs, args.tp, args.lra)
-    if stats.get("silent"):
-        info("audio is silent (integrated loudness -inf); nothing to normalise")
-        if args.measure_only:
-            if STATE.json:
-                emit(None, measured={"silent": True, "input_i": "-inf"})
-            else:
-                print(json.dumps({"silent": True, "input_i": "-inf"}, indent=2))
-            return 0
-        die("input audio is silent; loudness normalisation is meaningless (use audio.py --replace to add a track)")
-    info(f"measured: {float(stats['input_i']):.1f} LUFS, TP {float(stats['input_tp']):.1f} dBTP, LRA {float(stats['input_lra']):.1f} LU")
-    if args.measure_only:
-        measured = {k: stats[k] for k in ("input_i", "input_tp", "input_lra", "input_thresh", "target_offset")}
-        if STATE.json:
-            emit(None, measured=measured)  # the contract's document shape (status, commands), not a bare dict
-        else:
-            print(json.dumps(measured, indent=2))
-        return 0
-
-    output = args.output or default_output(args.input, "loudnorm")
+def _normalize(args, meta: dict, stats: dict, lufs: float, tp_max: float, output: str) -> dict:
+    """One normalised file at `lufs` / `tp_max`, measured after: the keys emit() takes for it."""
     af = (
-        f"loudnorm=I={args.lufs}:TP={args.tp}:LRA={args.lra}"
+        f"loudnorm=I={lufs}:TP={tp_max}:LRA={args.lra}"
         f":measured_I={stats['input_i']}:measured_TP={stats['input_tp']}:measured_LRA={stats['input_lra']}"
         f":measured_thresh={stats['input_thresh']}:offset={stats['target_offset']}:linear=true:print_format=summary"
     )
@@ -106,7 +104,7 @@ def main() -> int:
     def encode(tp: float, bitrate: str) -> None:
         nonlocal dropped_streams
         af = (
-            f"loudnorm=I={args.lufs}:TP={tp}:LRA={args.lra}"
+            f"loudnorm=I={lufs}:TP={tp}:LRA={args.lra}"
             f":measured_I={stats['input_i']}:measured_TP={stats['input_tp']}:measured_LRA={stats['input_lra']}"
             f":measured_thresh={stats['input_thresh']}:offset={stats['target_offset']}:linear=true:print_format=summary"
         )
@@ -124,12 +122,11 @@ def main() -> int:
         cmd.append(output)
         run(cmd)
 
-    encode(args.tp, bitrate)
+    encode(tp_max, bitrate)
     if STATE.dry_run:
         # pass 1 measured the input for real; there is no output to measure
-        emit(output, measured={k: stats[k] for k in ("input_i", "input_tp", "input_lra", "input_thresh", "target_offset", "silent")})
-        return 0
-    after = measure(output, args.lufs, args.tp, args.lra)
+        return {"output": output, "measured": {k: stats[k] for k in ("input_i", "input_tp", "input_lra", "input_thresh", "target_offset", "silent")}}
+    after = measure(output, lufs, tp_max, args.lra)
     # loudnorm holds the ceiling on the float samples it outputs; the lossy encoder then adds
     # its own overshoot. ffmpeg's native AAC at 192k turned one transient of a 12-minute film
     # from -2.4 dBFS into +3.7 dBFS, so the file measured +1.2 dBTP after "--tp -1" and
@@ -138,43 +135,43 @@ def main() -> int:
     # loudness target is untouched) when the caller did not pin the bitrate; then a lower
     # loudnorm ceiling by the measured overshoot, which in linear mode also lowers the
     # integrated loudness -- reported, never hidden.
-    ceiling, rounds = args.tp, 0
+    ceiling, rounds = tp_max, 0
     steps = [] if bitrate_pinned or ext in AUDIO_CODECS and "aac" not in AUDIO_CODECS[ext] else [b for b in ("256k", "320k") if _kbps(b) > _kbps(bitrate)]
-    while not after.get("silent") and float(after["input_tp"]) > args.tp + TP_TOLERANCE_DB and rounds < 5:
+    while not after.get("silent") and float(after["input_tp"]) > tp_max + TP_TOLERANCE_DB and rounds < 5:
         rounds += 1
-        overshoot = float(after["input_tp"]) - args.tp
+        overshoot = float(after["input_tp"]) - tp_max
         if steps:
             bitrate = steps.pop(0)
-            info(f"true peak {float(after['input_tp']):.2f} dBTP exceeds the requested {args.tp:g} dBTP after encoding "
+            info(f"true peak {float(after['input_tp']):.2f} dBTP exceeds the requested {tp_max:g} dBTP after encoding "
                  f"(codec overshoot); re-encoding at {bitrate}")
         else:
             ceiling -= overshoot + 0.2
-            info(f"true peak {float(after['input_tp']):.2f} dBTP exceeds the requested {args.tp:g} dBTP after encoding "
+            info(f"true peak {float(after['input_tp']):.2f} dBTP exceeds the requested {tp_max:g} dBTP after encoding "
                  f"(codec overshoot); re-encoding with the loudnorm ceiling at {ceiling:.2f} dBTP")
         encode(ceiling, bitrate)
-        after = measure(output, args.lufs, args.tp, args.lra)
+        after = measure(output, lufs, tp_max, args.lra)
     if not after.get("silent"):
-        info(f"result:   {float(after['input_i']):.1f} LUFS, TP {float(after['input_tp']):.1f} dBTP (target {args.lufs} LUFS, TP <= {args.tp:g})")
+        info(f"result:   {float(after['input_i']):.1f} LUFS, TP {float(after['input_tp']):.1f} dBTP (target {lufs} LUFS, TP <= {tp_max:g})")
     result = {k: after[k] for k in ("input_i", "input_tp", "input_lra", "input_thresh", "target_offset", "silent")}
     result["tp_ceiling_used"] = round(ceiling, 2)
     if ext not in AUDIO_CODECS or "aac" in AUDIO_CODECS[ext]:
         result["audio_bitrate_used"] = bitrate
     result["encodes"] = rounds + 1
-    if not after.get("silent") and abs(float(after["input_i"]) - args.lufs) > LUFS_TOLERANCE:
-        result["note"] = (f"integrated loudness is {float(after['input_i']) - args.lufs:+.1f} LU from the target because the "
+    if not after.get("silent") and abs(float(after["input_i"]) - lufs) > LUFS_TOLERANCE:
+        result["note"] = (f"integrated loudness is {float(after['input_i']) - lufs:+.1f} LU from the target because the "
                           f"true-peak ceiling had to absorb the encoder's overshoot; a lossless delivery (wav/flac) or a pinned "
                           f"higher --audio-bitrate keeps both")
-    if not after.get("silent") and float(after["input_tp"]) > args.tp + TP_TOLERANCE_DB:
-        die(f"true peak is still {float(after['input_tp']):.2f} dBTP after {rounds + 1} encodes (requested <= {args.tp:g}); "
+    if not after.get("silent") and float(after["input_tp"]) > tp_max + TP_TOLERANCE_DB:
+        die(f"true peak is still {float(after['input_tp']):.2f} dBTP after {rounds + 1} encodes (requested <= {tp_max:g}); "
             f"the encoder overshoots more than the loudnorm ceiling can absorb at this bitrate",
             kind="verification", output=output, result=result,
             hint="raise --audio-bitrate (e.g. 256k) or deliver a lossless format (wav/flac) and let the platform encode")
     verification = [{"step": "loudness",
-                     "ok": bool(after.get("silent")) or (abs(float(after["input_i"]) - args.lufs) <= LUFS_TOLERANCE and float(after["input_tp"]) <= args.tp + TP_TOLERANCE_DB),
-                     "lufs": float(after["input_i"]), "tp": float(after["input_tp"]), "target_lufs": args.lufs, "target_tp": args.tp,
-                     "property": "loudness", "expected": {"lufs": args.lufs, "tp_max": args.tp},
+                     "ok": bool(after.get("silent")) or (abs(float(after["input_i"]) - lufs) <= LUFS_TOLERANCE and float(after["input_tp"]) <= tp_max + TP_TOLERANCE_DB),
+                     "lufs": float(after["input_i"]), "tp": float(after["input_tp"]), "target_lufs": lufs, "target_tp": tp_max,
+                     "property": "loudness", "expected": {"lufs": lufs, "tp_max": tp_max},
                      "measured": {"lufs": float(after["input_i"]), "tp": float(after["input_tp"])},
-                     "delta": {"lufs": round(float(after["input_i"]) - args.lufs, 2), "tp": round(float(after["input_tp"]) - args.tp, 2)},
+                     "delta": {"lufs": round(float(after["input_i"]) - lufs, 2), "tp": round(float(after["input_tp"]) - tp_max, 2)},
                      "tolerance": {"lufs": LUFS_TOLERANCE, "tp": TP_TOLERANCE_DB}, "provenance": "user_specified"}]
     written = probe(output, role="output")
     out_audio = audio_length(written)
@@ -189,9 +186,86 @@ def main() -> int:
         # a length that could not be read is not a length that matched
         verification.append({"step": "duration", "property": "audio_duration", "ok": False,
                              "reason": "not_measured: the " + ("input" if not in_audio else "output") + " reports no duration"})
-    emit(output, result=result, dropped_non_av_streams=dropped_streams,
-         measured={k: stats[k] for k in ("input_i", "input_tp", "input_lra", "input_thresh", "target_offset", "silent")},
-         targets={"lufs": args.lufs, "tp": args.tp, "lra": args.lra}, verification=verification)
+    return {"output": output, "result": result, "dropped_non_av_streams": dropped_streams,
+            "measured": {k: stats[k] for k in ("input_i", "input_tp", "input_lra", "input_thresh", "target_offset", "silent")},
+            "targets": {"lufs": lufs, "tp": tp_max, "lra": args.lra}, "verification": verification}
+
+
+def _versions(args, meta: dict, plan: list) -> int:
+    """--versions: one file per target from the one master, each a whole two-pass normalisation
+    (pass 1 is per target: loudnorm's target_offset depends on it) measured after. `verified` is
+    true only when every version met its own target."""
+    versions, steps, dropped = [], [], False
+    for label, lufs, tp in plan:
+        out = default_output(args.input, f"loudnorm_{label}")
+        stats = measure(args.input, lufs, tp, args.lra)
+        if stats.get("silent"):
+            die("input audio is silent; loudness normalisation is meaningless (use audio.py --replace to add a track)")
+        doc = _normalize(args, meta, stats, lufs, tp, out)
+        dropped = dropped or bool(doc.get("dropped_non_av_streams"))
+        versions.append({"target": label, "output": out, "targets": {"lufs": lufs, "tp": tp, "lra": args.lra},
+                         **({"result": doc["result"]} if "result" in doc else {})})
+        steps += [dict(st, version=label) for st in doc.get("verification") or []]
+    emit(None, versions=versions, outputs=[v["output"] for v in versions], dropped_non_av_streams=dropped,
+         **({"verification": steps} if steps else {}))
+    if not STATE.json and not STATE.plan:
+        print("\n".join(v["output"] for v in versions))  # one path per line, as a single run prints its one
+    return 0
+
+
+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>_loudnorm.<ext>)")
+    ap.add_argument("-I", "--lufs", type=float, default=-14.0, help="integrated loudness target in LUFS (default -14)")
+    ap.add_argument("--tp", type=float, default=-1.0, help="true peak ceiling in dBTP (default -1)")
+    ap.add_argument("--lra", type=float, default=11.0, help="loudness range target in LU (default 11)")
+    ap.add_argument("--measure-only", action="store_true", help="print the measured stats as JSON and exit")
+    ap.add_argument("--audio-bitrate", default=None, help="AAC bitrate when the container is video (default 192k; raised to 256k/320k only when the encoder overshoots the true-peak ceiling and you did not pin it)")
+    ap.add_argument("--versions", metavar="LIST",
+                    help="write one normalised file per target from this master, each measured after: a comma list of "
+                         + ", ".join(f"{n} ({i:g} LUFS / {t:g} dBTP)" for n, (i, t) in VERSION_TARGETS.items())
+                         + ", or LUFS/TP pairs such as -16/-1.5; files are <name>_loudnorm_<target>.<ext> (not with -o)")
+    ap.add_argument("--sample-rate", type=int, help="output sample rate (default: 48000; loudnorm upsamples internally to 192k)")
+    add_common(ap)
+    args = ap.parse_args()
+    apply_common(args)
+    # parsed before anything is measured, and an explicitly empty --versions ('' or ',') is refused
+    # by parse_versions rather than read as "not given", which wrote one default file instead
+    plan = parse_versions(args.versions) if args.versions is not None else None
+    if plan is not None and args.output:
+        die("--versions writes one file per target, named <name>_loudnorm_<target>.<ext>; it does not take -o")
+
+    meta = probe(args.input)
+    if not meta.get("audio"):
+        die("input has no audio stream")
+    if plan is not None and not args.measure_only:
+        # each version measures the master against its own target (loudnorm's offset depends on
+        # it): a pass against -I/--tp first would be one more full decode whose result is unused
+        return _versions(args, meta, plan)
+
+    stats = measure(args.input, args.lufs, args.tp, args.lra)
+    if stats.get("silent"):
+        info("audio is silent (integrated loudness -inf); nothing to normalise")
+        if args.measure_only:
+            if STATE.json:
+                emit(None, measured={"silent": True, "input_i": "-inf"})
+            else:
+                print(json.dumps({"silent": True, "input_i": "-inf"}, indent=2))
+            return 0
+        die("input audio is silent; loudness normalisation is meaningless (use audio.py --replace to add a track)")
+    info(f"measured: {float(stats['input_i']):.1f} LUFS, TP {float(stats['input_tp']):.1f} dBTP, LRA {float(stats['input_lra']):.1f} LU")
+    if args.measure_only:
+        measured = {k: stats[k] for k in ("input_i", "input_tp", "input_lra", "input_thresh", "target_offset")}
+        if STATE.json:
+            emit(None, measured=measured)  # the contract's document shape (status, commands), not a bare dict
+        else:
+            print(json.dumps(measured, indent=2))
+        return 0
+
+    output = args.output or default_output(args.input, "loudnorm")
+    doc = _normalize(args, meta, stats, args.lufs, args.tp, output)
+    emit(doc.pop("output"), **doc)
     return 0