ffmpeg-skill 3.8.11 → 3.8.13

package/scripts/_contract.py

@@ -170,7 +170,7 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
                      required=FF + [X264, AAC], optional=[HDR_X265],
                      video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "audio": dict(role="execution", inputs=["video or audio asset", "music bed (--music) or replacement track (--replace)", "effects/atmos track (--effects)"], outputs=["artifact with the processed audio (video stream-copied, or dropped when -o has an audio extension)"],
-                  required=FF, optional=[{"capability": "filter:afftdn", "when": "--denoise / --voice"}, {"capability": "filter:sidechaincompress", "when": "--duck"},
+                  required=FF, optional=[{"capability": "filter:afftdn", "when": "--denoise / --voice"}, {"capability": "filter:sidechaingate", "when": "--duck"}, {"capability": "filter:dcshift", "when": "--duck"},
                                         {"capability": "filter:acompressor", "when": "--compress / --voice"}, {"capability": "filter:alimiter", "when": "--limit / --voice strong"}, {"capability": "filter:agate", "when": "--gate"},
                                         {"capability": "filter:deesser", "when": "--voice medium (the default) / --voice strong"},
                                         {"capability": "filter:extrastereo", "when": "--stereo-widen"},
@@ -872,7 +872,7 @@ def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str
                  "silent": {"type": "array", "description": "--on-silent warn (default), only when a track was silent: [{flag, path, peak_db}] for each --music/--replace/--effects file, or under --duck the voice (flag \"input\"), whose whole-file peak is at or below --silence-threshold (default -50 dBFS); it was mixed anyway. --on-silent fail refuses instead, reason \"silent (peak X dBFS)\" in problems"},
                  "notes": {"type": "array", "items": {"type": "string"}, "description": "present with `silent`: which tracks were silent and how to refuse them"},
                  "timing": {"type": "object", "description": "#486: {tempo, atempo, length_samples, sample_rate}: the --tempo factor (null without it), the atempo stages (each 0.5..2.0, [] at tempo 1) whose product it is, --length-samples (null without it) and the sample rate that count is in (null when not measured yet); with --length-samples a length_samples verification step counts the written track's decoded samples (exact for PCM/FLAC/ALAC, within tolerance_samples, one codec frame, for a lossy codec)"},
-                 "audio": {"type": "object", "description": "what the mix was built from: voice (null | light | medium | strong), stereo_widen, channel (--channel N, the 0-based channel kept, else null), sample_rate (--sample-rate, else null; both are read back from the output as the channels / sample_rate verification steps), effects/effects_volume, and with --music the music_volume plus duck (null when --duck was not given, else the threshold in dB and linear, ratio, attack_ms, release_ms, amount_db actually used)"}}
+                 "audio": {"type": "object", "description": "what the mix was built from: voice (null | light | medium | strong), stereo_widen, channel (--channel N, the 0-based channel kept, else null), sample_rate (--sample-rate, else null; both are read back from the output as the channels / sample_rate verification steps), effects/effects_volume, and with --music the music_volume plus duck (null when --duck was not given, else the threshold in dB and linear, the sidechain gate's ratio, attack_ms, release_ms, and amount_db, the depth in dB the bed is lowered under speech)"}}
     for key, prop in EMITTED_KEYS.get(name, {}).items():
         extra.setdefault(key, prop)
     if name in ("overlay", "graphics", "caption", "grid"):

package/scripts/_smartcut.py

@@ -110,6 +110,21 @@ def ineligible(params: Optional[Dict[str, Any]], meta: Dict[str, Any], ext: str)
     return None
 
 
+# Matroska stores every timestamp in milliseconds (its default TimestampScale), whatever the source's
+# time base: an .mkv output's stream reads 1/1000 however it is written
+MATROSKA_TIME_BASE = "1/1000"
+
+
+def expected_time_base(params: Dict[str, Any], ext: str) -> Optional[str]:
+    """The time base the joined output's video should read: the source's for MP4/MOV, whose time
+    scale execute() sets from it (-video_track_timescale), and Matroska's own for .mkv. Comparing a
+    .mkv against an MP4 source's 1/15360 failed every such cut, and only after the whole smart cut had
+    been built and checked (#462 A45)."""
+    if ext.lower() == ".mkv":
+        return MATROSKA_TIME_BASE
+    return params.get("time_base")
+
+
 def _rate(params: Dict[str, Any]) -> Optional[Fraction]:
     try:
         q = Fraction(str(params.get("r_frame_rate") or ""))
@@ -165,8 +180,10 @@ def plan_segment(packets: List[Tuple[Any, Any, bool]], s: float, e: float, vend:
         raise SmartFallback(f"the keyframe at {packets[k1][0]:.3f}s opens its GOP (frames decoded after it are shown "
                             "before it), so a copy cannot start there", "open_gop")
     k1_pts = packets[k1][0]
-    # where the copy stops: the last keyframe presented at or before the end bound, decoded after K1
-    stops = [i for i in keyidx if packets[i][1] > packets[k1][1] + 1e-9
+    # where the copy stops: the last keyframe presented at or before the end bound, decoded after K1.
+    # A segment that runs to the end of the video has no end bound to stop before: its copy runs
+    # to the end, and the last GOP is whole, so it is copied, not re-encoded as a tail (#462 A44)
+    stops = [i for i in keyidx if not to_end and packets[i][1] > packets[k1][1] + 1e-9
              and (end_bound is None or packets[i][0] <= end_bound + 1e-6)]
     k2 = stops[-1] if stops else None
     if k2 is not None and gop_is_open(packets, k2):
@@ -422,9 +439,10 @@ def verify(src: str, dst: str, parts: List[Dict[str, Any]], params: Dict[str, An
         decoded += g
         offset += n
     out_params = stream_params(dst) or {}
-    if out_params.get("time_base") != params.get("time_base"):
-        raise SmartFallback(f"the output's time base is {out_params.get('time_base')}, the source's "
-                            f"{params.get('time_base')}", "time_base")
+    want_tb = expected_time_base(params, os.path.splitext(dst)[1])
+    if out_params.get("time_base") != want_tb:
+        raise SmartFallback(f"the output's time base is {out_params.get('time_base')}, where "
+                            f"{want_tb} was expected (the source's is {params.get('time_base')})", "time_base")
     diff = mismatches(params, out_params)
     if diff:
         raise SmartFallback("the output's stream does not match the source: " + ", ".join(diff), "params_mismatch")

package/scripts/audio.py

@@ -29,8 +29,8 @@ from typing import Any, Dict, List
 
 from _common.probe import SILENT_PEAK_DBFS
 from _common import STATE, add_common, dry_run_input_pending, require_tool, apply_common, audio_codec_for, db_to_linear, default_output, die, emit, ffmpeg_base, info, is_audio_output, measured_level_dbfs, probe, run, run_keeping_subtitles, fmt_secs
-from _common.emit import warn
-from _common.decision import conform_filter, conform_to_length
+from _common.emit import file_origin, stream_end, warn
+from _common.decision import LOSSLESS_AUDIO_EXT, conform_filter, conform_to_length
 
 # --downmix: ITU-R BS.775 fold-down, renormalised by pan's '<' (see main()).
 DOWNMIX_PAN = "pan=stereo|FL<FL+0.707*FC+0.707*BL+0.707*SL|FR<FR+0.707*FC+0.707*BR+0.707*SR"
@@ -43,10 +43,11 @@ VOICE_CHAIN = f"highpass=f=80,deesser=i=0.4,{VOICE_DENOISE},acompressor=threshol
 # which is what a good room recording needs; "strong" is for phone/laptop audio: a harder
 # de-esser, a second compression stage and a soft limiter at -1 dBFS so the peaks stop there
 # instead of at whatever the make-up gain produced.
+VOICE_LIMITER = "alimiter=limit=0.891251:level=disabled:latency=1"  # --voice strong's -1 dBFS ceiling
 VOICE_LEVELS = {
     "light": "highpass=f=80,acompressor=threshold=-18dB:ratio=2:attack=5:release=80:makeup=1",
     "medium": VOICE_CHAIN,
-    "strong": VOICE_CHAIN + ",deesser=i=0.6,acompressor=threshold=-24dB:ratio=4:attack=5:release=120:makeup=3,alimiter=limit=0.891251:level=disabled:latency=1",
+    "strong": VOICE_CHAIN + ",deesser=i=0.6,acompressor=threshold=-24dB:ratio=4:attack=5:release=120:makeup=3," + VOICE_LIMITER,
 }
 
 
@@ -66,11 +67,40 @@ def voice_chain(level: str, denoise_strength: "float | None") -> str:
     return chain.replace("highpass=f=80,", f"highpass=f=80,{stage},", 1)
 
 
-# The sidechain threshold the music bed has used since 1.4 is the linear 0.05 that ffmpeg's
-# sidechaincompress takes; -26.0206 dBFS is that same number in the unit the flag speaks, so the
-# default command line is unchanged to the byte while the value is now sayable.
+# The sidechain threshold the music bed has used since 1.4 is the linear 0.05 the filter takes;
+# -26.0206 dBFS is that same number in the unit the flag speaks.
 DUCK_THRESHOLD_DB = -26.0206
 
+# the knee the filters take is a linear 1..8 (default 2.82843): in the dB the flag speaks that is
+# 0..18.06 dB, default 9.03 dB. The flag used to accept 1..8 *dB* (linear 1.12..2.51), so no knee
+# from 2.51 up to ffmpeg's own default could be asked for, and the help gave the default as 2.83 dB
+KNEE_MAX_DB = 18.06  # 20*log10(8) = 18.0618, rounded down so the linear value stays inside 1..8
+
+# --duck (A134): the bed is lowered by exactly --duck-amount dB while the speech is above the
+# threshold. A sidechain gate keyed by the speech passes the bed where there is speech and nothing
+# elsewhere; that part, scaled by -(1 - 10^(-amount/20)), is added back to the bed, which leaves
+# 10^(-amount/20) of it under speech and all of it in the pauses. The sidechain compressor used
+# through 3.8.8 took the amount as ratio = max(2, amount/3), and a compressor's depth is how far
+# the speech rises over its threshold: on the test's speech 0 and 3 ducked the same 9.7 dB, 60 ducked 18.
+# The key gets a DC offset far below any threshold (-120 dBFS) because agate's detector leaves the
+# gate open on a key that is exact zeros from its first sample. The knee is hard (knee=1): agate's
+# default soft knee (2.82843) opened the gate only about 2 dB over the threshold, so a key just
+# over it left the bed at its level (measured: a sine 1.5 dB over -7.5 dBFS ducked 0 dB of 12).
+DUCK_GATE_RATIO = 9000.0  # agate's largest: closed below the threshold
+DUCK_KEY_DC = "dcshift=shift=0.000001"
+
+
+def duck_graph(threshold_db: float, amount_db: float, attack: float, release: float) -> List[str]:
+    """The filter-graph lines that turn `[music]` and the speech key `[sc]` into `[ducked]`."""
+    cut = 1.0 - 10 ** (-amount_db / 20.0)
+    return ["[music]asplit=2[mdry][mwet]",
+            f"[sc]{DUCK_KEY_DC}[key]",
+            f"[mwet][key]sidechaingate=threshold={db_to_linear(threshold_db):.6g}:ratio={DUCK_GATE_RATIO:g}:range=0:knee=1"
+            f":attack={attack:g}:release={release:g}[mspeech]",
+            f"[mspeech]volume={-cut:.6g}[mcut]",
+            "[mdry][mcut]amix=inputs=2:normalize=0[ducked]"]
+
+
 # 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.
@@ -81,7 +111,7 @@ DYNAMICS = {
         "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),
+        "comp_knee": ("knee", "dB", 0.0, KNEE_MAX_DB),         # 1..8 linear (A135: was 1..8 dB, linear 1.12..2.51)
     },
     "alimiter": {
         "limit_ceiling": ("limit", "dB", -24.0, 0.0),             # 0.0625..1 linear
@@ -94,7 +124,7 @@ DYNAMICS = {
         "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),
+        "gate_knee": ("knee", "dB", 0.0, KNEE_MAX_DB),         # 1..8 linear
     },
 }
 
@@ -289,8 +319,8 @@ def main() -> int:
     music = ap.add_argument_group("music")
     music.add_argument("--music", help="music file to mix underneath")
     music.add_argument("--music-volume", type=float, default=-14.0, help="music level in dB relative to full scale (default -14)")
-    music.add_argument("--duck", action="store_true", help="auto-duck the music when the main track has speech (sidechain compressor)")
-    music.add_argument("--duck-amount", type=float, default=12.0, help="how many dB to duck (default 12)")
+    music.add_argument("--duck", action="store_true", help="auto-duck the music by --duck-amount dB while the main track has speech (a sidechain gate keyed by it)")
+    music.add_argument("--duck-amount", type=float, default=12.0, help="how many dB the music is lowered under speech, 0..60 (default 12)")
     music.add_argument("--duck-threshold", type=float, default=DUCK_THRESHOLD_DB,
                        help="sidechain threshold in dBFS: the main track is heard as speech above this (default -26.02, the 0.05 linear used since 1.4)")
     music.add_argument("--duck-attack", type=float, default=20.0, help="ms the bed takes to duck once speech starts (default 20)")
@@ -326,25 +356,27 @@ def main() -> int:
                              "(an audio output only: beside a picture the sound is conformed to the picture)")
     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-threshold", type=float, help="dBFS above which gain is reduced, -60..0 (ffmpeg default -18.06, its linear 0.125)")
     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("--comp-knee", type=float, help="knee width dB 0..18.06 (ffmpeg's linear 1..8; default 9.03, its 2.82843)")
     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-threshold", type=float, help="dBFS below which the gate closes, -60..0 (default -18.06, ffmpeg's linear 0.125)")
     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)")
+    dyn.add_argument("--gate-range", type=float, help="attenuation when closed, dB -90..0 (default -24.26, ffmpeg's linear 0.06125)")
+    dyn.add_argument("--gate-knee", type=float, help="knee width dB 0..18.06 (ffmpeg's linear 1..8; default 9.03, its 2.82843)")
     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")
+    ap.add_argument("--bitrate", default=None,
+                    help="audio bitrate: AAC's beside a picture (default 192k), and the codec's of a lossy audio output "
+                         "(.m4a/.aac default 256k, .mp3 -q:a 0, .ogg -q:a 6, .opus 128k); refused for .wav/.flac")
     ap.add_argument("--on-silent", choices=["warn", "fail"], default="warn",
                     help="a --music/--replace/--effects file (or, under --duck, the voice) whose peak is at or below "
                          "--silence-threshold: warn (default: mix it, report it under `silent`) or fail (refuse before ffmpeg runs)")
@@ -391,7 +423,7 @@ def main() -> int:
                                 ("--duck-attack", args.duck_attack, 0.01, 2000.0),
                                 ("--duck-release", args.duck_release, 0.01, 9000.0)):
         if not (lo <= value <= hi):
-            die(f"{flag} {value:g} is outside {lo:g}..{hi:g} (the range ffmpeg's sidechaincompress accepts)")
+            die(f"{flag} {value:g} is outside {lo:g}..{hi:g}")
     if args.stereo_widen is not None and not (0.0 <= args.stereo_widen <= 1.0):
         die(f"--stereo-widen must be 0..1 (0 = untouched, 1 = maximum), got {args.stereo_widen:g}")
 
@@ -421,6 +453,9 @@ def main() -> int:
         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)
+    if args.bitrate is not None and Path(output).suffix.lower() in LOSSLESS_AUDIO_EXT:
+        # A143: the rate used to be dropped without a word for every audio extension
+        die(f"--bitrate has no effect on a lossless {Path(output).suffix.lower()} output; drop it, or write a lossy one (.m4a, .mp3, ...)")
     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}")
@@ -486,8 +521,17 @@ def main() -> int:
         # 7.1), so in-phase channels at full scale cannot clip; '=' summed 2.7x and clipped a loud
         # 5.1 while the run said verified.
         fx.append(DOWNMIX_PAN)
+    # A129: a limiter is the ceiling of what is delivered, so with a bed mixed in it runs after the
+    # mix: on the voice alone, the music and effects added on top of it peaked over the ceiling
+    # (--limit-ceiling -6 delivered 0 dBFS, --voice strong's -1 dBFS -0.2)
+    limit_after_mix = bool(args.music or args.effects)
+    post_limit: List[str] = []
     if args.voice:
-        fx.append(voice_chain(args.voice, args.denoise_strength if args.denoise else None))
+        chain = voice_chain(args.voice, args.denoise_strength if args.denoise else None)
+        if limit_after_mix and chain.endswith("," + VOICE_LIMITER):
+            chain = chain[: -len("," + VOICE_LIMITER)]
+            post_limit.append(VOICE_LIMITER)
+        fx.append(chain)
     elif args.denoise:
         fx.append(f"afftdn=nf=-{args.denoise_strength:g}:tn=1")
     if args.gain:
@@ -497,7 +541,7 @@ def main() -> int:
     if args.compress:
         fx.append(dynamics_filter("acompressor", args))
     if args.limit:
-        fx.append(dynamics_filter("alimiter", args))
+        (post_limit if limit_after_mix else fx).append(dynamics_filter("alimiter", args))
     if args.mono:
         # after --downmix the track is the stereo fold-down, whatever the source had
         in_ch = 2 if args.downmix else (in_channels or 2)
@@ -542,15 +586,28 @@ def main() -> int:
         m = f"{idx}:a:0"
         idx += 1
         mfx = [f"volume={args.music_volume:g}dB", f"atrim=0:{main_dur:.6f}" if main_dur else "anull"]
-        if args.music_fade_out and end_dur:
-            mfx.append(f"afade=t=out:st={max(0.0, end_dur - args.music_fade_out):.3f}:d={args.music_fade_out:g}")
+        # A142: a bed shorter than the output (and not looped) stops at its own end, so its fade
+        # ends there: timed on the output's end it started after the bed had stopped at full level
+        # ... and at the main track's end when the output runs past it (--length-samples): the
+        # atrim above has cut the bed there. All three are timestamps, which is what afade reads:
+        # a bed whose sound starts late in its file (2 to 5 s) keeps those, so its fade ends at 5,
+        # not at its 3 s length (that fade ran over the bed's first second)
+        ends = [t for t in (end_dur, main_dur) if t]
+        if args.music_fade_out and not args.music_loop and not dry_run_input_pending(args.music):
+            bed_meta = probe(args.music)
+            bed_stop = stream_end(bed_meta, "audio")
+            if bed_stop is not None and bed_stop - file_origin(bed_meta) > 0:
+                ends.append(bed_stop - file_origin(bed_meta))
+        bed_end = min(ends) if ends else None
+        if args.music_fade_out and bed_end:
+            # a fade longer than the bed is cut to it, so the bed still ends silent (a 5 s fade on
+            # a 2 s bed started at 0 and stopped at 60% gain)
+            m_fade = min(args.music_fade_out, bed_end)
+            mfx.append(f"afade=t=out:st={bed_end - m_fade:.3f}:d={m_fade:g}")
         graph.append(f"[{m}]{','.join(mfx)}[music]")
         if args.duck:
             graph.append("[main]asplit=2[mainA][sc]")
-            graph.append(
-                f"[music][sc]sidechaincompress=threshold={db_to_linear(args.duck_threshold):.6g}"
-                f":ratio={max(2.0, args.duck_amount / 3):.1f}:attack={args.duck_attack:g}:release={args.duck_release:g}:makeup=1[ducked]"
-            )
+            graph += duck_graph(args.duck_threshold, args.duck_amount, args.duck_attack, args.duck_release)
             graph.append("[mainA][ducked]amix=inputs=2:duration=first:dropout_transition=2:normalize=0[mix]")
         else:
             graph.append("[main][music]amix=inputs=2:duration=first:dropout_transition=2:normalize=0[mix]")
@@ -567,11 +624,12 @@ def main() -> int:
         graph.append(f"[{last}][effects]amix=inputs=2:duration=first:dropout_transition=2:normalize=0[mixfx]")
         last = "mixfx"
 
-    post: List[str] = []
+    post: List[str] = list(post_limit)
     if args.fade_in:
         post.append(f"afade=t=in:st=0:d={args.fade_in:g}")
     if args.fade_out and end_dur:
-        post.append(f"afade=t=out:st={max(0.0, end_dur - args.fade_out):.3f}:d={args.fade_out:g}")
+        fade_out = min(args.fade_out, end_dur)  # cut to the output, so it still ends silent
+        post.append(f"afade=t=out:st={end_dur - fade_out:.3f}:d={fade_out:g}")
     # The audio track is conformed to the source duration whenever it is known: padded with
     # silence if the graph came out short, trimmed if long. A mixed track can come out a few
     # hundredths short (amix's dropout_transition, a looped bed's atrim boundary), and with
@@ -628,7 +686,7 @@ def main() -> int:
         audio_block["music_volume"] = args.music_volume
         audio_block["duck"] = ({"amount_db": args.duck_amount, "threshold_db": round(args.duck_threshold, 4),
                                 "threshold_linear": float(f"{db_to_linear(args.duck_threshold):.6g}"),
-                                "ratio": round(max(2.0, args.duck_amount / 3), 1),
+                                "ratio": DUCK_GATE_RATIO,
                                 "attack_ms": args.duck_attack, "release_ms": args.duck_release}
                                if args.duck else None)
     verification: List[Dict[str, Any]] = []

package/scripts/broll.py

@@ -18,10 +18,12 @@ Examples:
   python3 broll.py talk.mp4 --insert demo.mp4 --at 30 --duration 8 --audio mix
 """
 import argparse
+import math
 import sys
 from typing import Any, Dict, List
 
-from _common.decision import av_trim, conform_output_t, conform_to_length, frame_rate, grid_at_or_after, silence_filter, stream_starts
+from _common.decision import (av_trim, conform_output_t, conform_to_length, frame_durations, frame_rate, frame_window,
+                              grid_at_or_after, silence_filter, stream_starts, window_expr, windowed_overlay_x)
 from _common import STATE, add_common, aac_args, apply_common, cfr_args, as_limited, default_output, die, draws_chroma, drawn_chain, emit, ffmpeg_base, info, time_arg, label_chain, matrix_chain, overlay_format, range_chain, probe, run, validate_color, video_args, X264_PRESETS, fmt_secs
 from _common.emit import note, record_fallback
 from _common.probe import display_size, square_pixels, square_pixels_note
@@ -77,6 +79,11 @@ def main() -> int:
         a_chain = (a_chain + "," if a_chain else "") + f"scale={ew}:{eh},setsar=1"
         w, h = ew, eh
     fps = meta_a["video"].get("fps") or 30.0
+    # the A-roll's frame grid, when it has one (frame_window): its exact rate and where it starts
+    grid = frame_window(0.0, None, meta_a) is not None
+    rate_a, v0a = frame_rate(meta_a), stream_starts(meta_a)[0]
+    fps_filter = frame_durations(meta_a, rate_a)  # fps=30000/1001; a whole rate reads as it did (fps=25)
+    fps_filter = fps_filter[:-2] if fps_filter.endswith("/1") else fps_filter
     has_audio_a = bool(meta_a.get("audio"))
 
     def per(values: List[str], i: int, default: str) -> str:
@@ -105,7 +112,19 @@ def main() -> int:
         dur_b = input_length(meta_b)
         if dur_b and start_b + length > dur_b + 0.01 and not STATE.dry_run:
             die(f"cutaway {i + 1}: {path} has only {dur_b - start_b:.3f}s from {start_b:g}s, {length:g}s asked for")
-        cutaways.append({"path": path, "at": at, "length": length, "from": start_b, "has_audio": bool(meta_b.get("audio")), "meta": meta_b})
+        # the cutaway in whole frames: `first` is B's first frame at or after --from, `on` the
+        # A-roll's first frame at or after --at, and `span` runs to its first at or after the end
+        v0b, rate_b = stream_starts(meta_b)[0], frame_rate(meta_b)
+        first = max(v0b, grid_at_or_after(start_b, v0b, rate_b))
+        on = span = None
+        if grid:
+            on = grid_at_or_after(at, v0a, rate_a)
+            span = grid_at_or_after(at + length, v0a, rate_a) - on
+            if round(span * rate_a) < 1:
+                die(f"cutaway {i + 1}: no frame of the A-roll starts between {at:g}s and {at + length:g}s "
+                    f"(its frames are {1 / rate_a:.4f}s apart): nothing would be shown")
+        cutaways.append({"path": path, "at": at, "length": length, "from": start_b, "has_audio": bool(meta_b.get("audio")), "meta": meta_b,
+                         "first": first, "rate": rate_b, "on": on, "span": span})
     # overlap is a property of the windows in time, not of the order they were given in: compared
     # against the one given before it, a later window listed first was called overlapping (A179)
     order = sorted(range(len(cutaways)), key=lambda k: cutaways[k]["at"])
@@ -123,7 +142,7 @@ def main() -> int:
         cmd += ["-i", c["path"]]
 
     # Picture: each B window is trimmed, normalised to A's frame and fps, shifted to start at its
-    # --at time, and overlaid on A; before its first frame and after its last (eof_action=pass)
+    # --at time, and overlaid on A; outside the window the overlay is placed off the picture and
     # A shows through unchanged, so A's timeline is never touched.
     parts: List[str] = []
     cur = "[0:v]"
@@ -144,9 +163,32 @@ def main() -> int:
                + drawn_chain(pad + args.pad_color, as_limited(c["meta"]), [args.pad_color], pad + "black", line_meta=meta_a,
                              tag=f"pad{i}", labelled=True))
         b_sq = (square_pixels(c["meta"]["video"]) + ",") if square_pixels(c["meta"]["video"]) else ""
-        parts.append(f"[{i + 1}:v]trim=start={c['from']:.3f}:duration={c['length']:.3f},setpts=PTS-STARTPTS+{c['at']:.3f}/TB,"
-                     f"{convert[i + 1]}{b_sq}{geo},setsar=1,fps={fps:g},format={'yuv420p10le' if (meta_a.get('video') or {}).get('bt2020_or_hdr') else 'yuv420p'}[b{i}]")
-        parts.append(f"{cur}[b{i}]overlay=0:0{overlay_format(meta_a)}:eof_action=pass:enable='between(t,{c['at']:.3f},{c['at'] + c['length']:.3f})'[v{i}]")
+        pix = 'yuv420p10le' if (meta_a.get('video') or {}).get('bt2020_or_hdr') else 'yuv420p'
+        if c["on"] is None:
+            # no grid to count the A-roll's frames on (a dry run's pending A-roll, a variable
+            # rate): the window as it was written before, to the millisecond
+            parts.append(f"[{i + 1}:v]trim=start={c['from']:.3f}:duration={c['length']:.3f},setpts=PTS-STARTPTS+{c['at']:.3f}/TB,"
+                         f"{convert[i + 1]}{b_sq}{geo},setsar=1,fps={fps:g},format={pix}[b{i}]")
+            window = window_expr(c["at"], c["at"] + c["length"], None)
+        else:
+            # The window is whole frames of the A-roll: from its first frame at or after --at to
+            # the frame before its first at or after the end. B is cut half a frame of its own
+            # before its first frame at or after --from, for as long as the window lasts, and
+            # that frame is put on the tick of the `fps` grid at or before the window's first
+            # frame, at the A-roll's exact rate (30000/1001, not probe()'s 29.97: frame 37
+            # counted at 29.97 comes 1.2 microseconds after the A-roll's and was shown a frame on)
+            # The cut never ends before B's first frame: a window shorter than half a frame of B
+            # (one 60 fps frame of the A-roll under a 24 fps cutaway) cut that frame off too
+            half_b = 0.5 / c["rate"] if c["rate"] else 0.0
+            parts.append(f"[{i + 1}:v]trim=start={max(0.0, c['first'] - half_b):.6f}:end={max(c['first'] + c['span'], c['first'] + 2 * half_b) - half_b:.6f},"
+                         f"setpts=PTS-STARTPTS+{math.floor(c['on'] * rate_a + 1e-6) / rate_a:.6f}/TB,"
+                         f"{convert[i + 1]}{b_sq}{geo},setsar=1,{fps_filter},format={pix}[b{i}]")
+            window = window_expr(c["on"], c["on"] + c["span"], meta_a, half_open=True)
+        # The window is in the cutaway's position: overlay's enable is evaluated on B's frames
+        # too. B's last frame is held when B ends (eof_action=repeat) and the position takes it
+        # off the picture: with eof_action=pass the window's last frame depended on where B's
+        # end fell against it, and an A-roll whose picture starts 13 ms late lost that frame.
+        parts.append(f"{cur}[b{i}]overlay={windowed_overlay_x(0, window)}:0{overlay_format(meta_a)}:eof_action=repeat[v{i}]")
         cur = f"[v{i}]"
     vout = cur
 
@@ -158,24 +200,40 @@ def main() -> int:
             aout = "0:a:0" if has_audio_a else None
         else:
             layers: List[str] = []
+            # the cutaway's sound follows its picture: it starts with the window's first frame and
+            # lasts as long as the window, counted in samples of the mix (without a frame grid:
+            # --at and the length asked)
+            for c in cutaways:
+                c["s0"] = round((c["at"] if c["on"] is None else c["on"]) * MIX_RATE)
+                c["sn"] = round((c["length"] if c["on"] is None else c["span"]) * MIX_RATE)
             if has_audio_a:
-                gate = "".join(f",volume=0:enable='between(t,{c['at']:.3f},{c['at'] + c['length']:.3f})'" for c in cutaways) if args.audio == "b" else ""
+                # `b` mutes the A-roll over exactly the samples B's sound takes, on the A-roll's
+                # own clock: aeval's `t` is each sample's time, and the bounds sit half a sample
+                # outside the first and the last. `volume=0:enable='between(t,...)'` is evaluated
+                # once per audio frame and muted 48128-96255 where 48000-95999 was asked
+                # (1024-sample frames; FFmpeg 6.1.1)
+                gate = ""
+                if args.audio == "b":
+                    gate = ",aeval='val(ch)*not(" + "+".join(
+                        f"between(t,{(c['s0'] - 0.5) / MIX_RATE:.9f},{(c['s0'] + c['sn'] - 0.5) / MIX_RATE:.9f})" for c in cutaways) + ")':c=same"
                 parts.append(f"[0:a:0]aformat=sample_rates=48000:channel_layouts=stereo{gate}[a0]")
                 layers.append("[a0]")
             for i, c in enumerate(cutaways):
                 # B's sound is shifted by the same constant as its picture, whose first frame (the
-                # first at or after --from) lands on --at; rebasing the sound to its own first
-                # sample moved a track that starts 0.3 s late 0.279 s early (#409)
-                v0b = stream_starts(c["meta"])[0]
-                first = max(v0b, grid_at_or_after(c["from"], v0b, frame_rate(c["meta"])))
-                # the delay is --at to the sample of the mix's rate: `int(at * 1000)` cut 1.001 to
+                # first at or after --from) lands on the window's first frame; rebasing the sound
+                # to its own first sample moved a track that starts 0.3 s late 0.279 s early (#409)
+                first, length = c["first"], c["length"] if c["on"] is None else c["span"]
+                # the delay is to the sample of the mix's rate: `int(at * 1000)` cut 1.001 to
                 # 1000 ms and wrote 1.2346 s as 1234 ms, the cutaway's sound 48 and 29 samples
                 # early. A whole millisecond keeps the text it had, rounded (silence_filter)
-                delay = silence_filter(MIX_RATE, lead=c["at"])
+                lead = c["s0"] / MIX_RATE
+                delay = silence_filter(MIX_RATE, lead=lead)
                 if "S:" not in delay:
-                    delay = f"adelay={round(c['at'] * 1000)}|{round(c['at'] * 1000)}"
-                parts.append(f"[{i + 1}:a:0]{av_trim(first, first + c['length'])[1]},"
-                             f"aformat=sample_rates=48000:channel_layouts=stereo,{delay}[ab{i}]")
+                    delay = f"adelay={round(lead * 1000)}|{round(lead * 1000)}"
+                # under `b` the layer is as many samples as the gate mutes, padded or cut
+                exact = f"apad=whole_len={c['sn']},atrim=end_sample={c['sn']}," if args.audio == "b" else ""
+                parts.append(f"[{i + 1}:a:0]{av_trim(first, first + length)[1]},"
+                             f"aformat=sample_rates=48000:channel_layouts=stereo,{exact}{delay}[ab{i}]")
                 layers.append(f"[ab{i}]")
             # the mix ends with the A-roll, to the sample (#493): every layer is 48 kHz, so the count
             # is in that rate. `atrim=duration={:.3f}` and `-t {:.3f}` cut it to the millisecond. A

package/scripts/check.py

@@ -50,7 +50,7 @@ from typing import Any, Dict, List, Optional, Tuple
 from _platforms import PLATFORMS, PLATFORM_CHOICES, TP_TOLERANCE_DB, spec_of, upload_limit_note, resolve as resolve_platform
 from _common.probe import (CHANGE_FLOOR, CHANGE_GRID, change_mask_tiles, change_tiles, LEGAL_RANGE_CHOICES, measure_signal_range, COMPARE_SSIM_WARN, CONTENT_FLAT_STD, SILENT_PEAK_DBFS, compare_pictures, detect_content,
                            detect_flashes, first_frame_stats, presentation_times, measured_level_dbfs)
-from _common.emit import file_identity
+from _common.emit import file_identity, own_length
 from _common.probe import PROBED_AUDIO
 from _common.probe import display_size as shown_size, shorter_than_a_loudness_block
 from _common import STATE, add_common, apply_common, die, emit, info, probe, require_tool, run, run_analysis, dry_run_input_pending
@@ -618,7 +618,7 @@ def main() -> int:
                 row("true peak", "WARN", "could not measure", f"<= {spec['tp']:g} dBTP", "re-run check.py, or verify true peak manually",
                     reason="ffmpeg's loudness measurement didn't produce a readable result -- this was not actually checked")
             elif (lm and lm["lufs"] == float("-inf") and lm["tp"] > SILENT_PEAK_DBFS
-                  and shorter_than_a_loudness_block(a.get("duration") or a.get("tagged_duration") or dur_read)):
+                  and shorter_than_a_loudness_block(own_length(a) or dur_read)):
                 # A257: shorter than one 400 ms gating block: a true peak but no integrated
                 # loudness. Not silence, and not a -inf LUFS that FAILs the target. Decided on
                 # the sound's length: a longer track whose every block is under the gate reads

package/scripts/cut.py

@@ -56,7 +56,7 @@ import os
 import sys
 import tempfile
 import zlib
-from typing import List, Tuple
+from typing import List, Optional, Tuple
 
 from _common.runner import ffmpeg_failure_extra, JsonTooDeep, fail_if_classified, read_json
 from _common import (beat_grid, snap_points, decode_pcm_mono, rms_envelope, BEAT_MIN_CONFIDENCE)
@@ -81,12 +81,27 @@ def _t(value: str, fps, flag: str = "--segments") -> float:
     return time_arg(value, flag, fps)
 
 
-def keep_ranges_after_removing(removed: List[Tuple[float, float]], total: float, fps=None) -> List[Tuple[float, float]]:
+def keep_ranges_after_removing(removed: List[Tuple[float, float]], total: float, fps=None,
+                               picture: Optional[Tuple[float, float]] = None,
+                               dropped: Optional[List[Tuple[float, float]]] = None) -> List[Tuple[float, float]]:
     """--remove: what is left of [0, total] once `removed` is dropped (merged where they overlap,
     clamped to the file). A leftover shorter than one frame (10 ms without a frame rate) is not a
-    piece anyone asked to keep. Refuses a removal that would leave nothing."""
+    piece anyone asked to keep. With `picture` (where the video starts and ends, for a video
+    output), neither is a leftover that holds less than one frame of it: sound before the first
+    frame or after the last (a track that outlasts its picture) has no picture to cut, and was
+    kept and then refused as a segment the caller never gave (#462 A51). Such leftovers are added
+    to `dropped`. Refuses a removal that would leave nothing."""
     least = 1.0 / fps if fps else 0.01
     keep, cursor = [], 0.0
+
+    def add(a: float, b: float) -> None:
+        if b - a < least:
+            return
+        if picture is not None and min(b, picture[1]) - max(a, picture[0]) < least - 1e-6:
+            if dropped is not None:
+                dropped.append((a, b))
+            return
+        keep.append((a, b))
     outside = [(s, e) for s, e in removed if min(total, e) <= min(total, max(0.0, s))]
     if outside:
         die("--remove " + ", ".join(f"{s:g}-{e:g}" for s, e in outside) + f" lies outside the file (0-{total:.3f}s), "
@@ -94,12 +109,14 @@ def keep_ranges_after_removing(removed: List[Tuple[float, float]], total: float,
     for s, e in sorted((min(total, max(0.0, s)), min(total, e)) for s, e in removed):
         if e <= cursor:
             continue
-        if s - cursor >= least:
-            keep.append((cursor, s))
+        add(cursor, s)
         cursor = max(cursor, e)
-    if total - cursor >= least:
-        keep.append((cursor, total))
+    add(cursor, total)
     if not keep:
+        if dropped:
+            die(f"--remove leaves only sound with no picture ({', '.join(f'{a:.3f}-{b:.3f}s' for a, b in dropped)}, "
+                f"outside the video's {picture[0]:.3f}-{picture[1]:.3f}s); nothing with a picture would be left to keep. "
+                "Write the sound out with an audio -o (e.g. -o part.wav) instead", kind="input")
         die(f"--remove drops the whole file ({total:.3f}s); nothing would be left to keep")
     return keep
 
@@ -277,11 +294,12 @@ def source_skew(src: str, meta: dict, t: float) -> float:
 
 def video_end(src: str, meta: dict):
     """Where the video stream ends on the cut's clock (seconds from the file's start), or None when
-    the stream's length is unknown."""
-    v = meta.get("video") or {}
-    if not v.get("duration"):
-        return None
-    return (v.get("start_time") or 0.0) + v["duration"] - file_origin(src)
+    the stream's length is unknown. A Matroska/WebM stream states no duration, only its DURATION
+    tag, which is already that end (own_end()); read from `duration` alone, a .mkv had no picture
+    end and --remove kept a sound-only leftover past it."""
+    from _common.emit import own_end
+    end = own_end(meta.get("video"))
+    return None if end is None else end - file_origin(src)
 
 
 _SEEK_SHIFTS: dict = {}
@@ -893,9 +911,12 @@ def cut_one(src: str, start: float, end: float, dst: str, reencode: bool, crf: i
         if is_audio_output(dst) or not meta.get("video"):
             # -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.
+            # resolution. The input seek counts from the file's start, so a sound that starts after
+            # it (late against its picture) arrives at its offset from `start`; it is padded with
+            # silence from 0, as the --segments re-cut pads it (av_trim), not rebased to its own
+            # first sample, which moved it earlier and made the cut shorter than asked (#462 A46)
             cmd = ffmpeg_base() + ["-ss", f"{start:.6f}", "-i", src, "-t", f"{dur:.6f}"] + stream_maps(meta, dst, copy=False)
-            cmd += ["-af", f"atrim=end={dur:.6f},asetpts=PTS-STARTPTS"]
+            cmd += ["-af", f"atrim=end={dur:.6f},aresample=async=1:first_pts=0"]
         else:
             # Seek SEEK_MARGIN early, then drop the margin on the output side, which decodes and
             # discards it from both streams alike. An input seek straight to `start` can land (the
@@ -1515,6 +1536,7 @@ def main() -> int:
         forced.append("codec")
 
     fps = (meta.get("video") or {}).get("fps")
+    remove_notes: List[str] = []
     if args.remove:
         if args.segments or args.end or args.duration or args.start is not None:
             die("--remove names what to drop from the whole file: it does not combine with --segments, --start, --end or --duration")
@@ -1525,7 +1547,18 @@ def main() -> int:
         if not total:
             die(f"--remove needs the input's duration, which {args.input} does not report"
                 + (" yet (it is an earlier step's output)" if dry_run_input_pending(args.input) else ""))
-        args.segments = ",".join(f"{s:.6f}-{e:.6f}" for s, e in keep_ranges_after_removing(parse_segments(args.remove, fps, clamp=True), total, fps))
+        picture = None
+        if (meta.get("video") or {}).get("fps") and not is_audio_output(args.output or "") and not dry_run_input_pending(args.input):
+            vend = video_end(args.input, meta)
+            if vend is not None:
+                picture = ((meta["video"].get("start_time") or 0.0) - file_origin(args.input), vend)
+        sound_only: List[Tuple[float, float]] = []
+        args.segments = ",".join(f"{s:.6f}-{e:.6f}" for s, e in keep_ranges_after_removing(
+            parse_segments(args.remove, fps, clamp=True), total, fps, picture, sound_only))
+        for a, b in sound_only:
+            remove_notes.append(f"--remove left {a:.3f}-{b:.3f}s, which holds sound but no frame of the picture "
+                                f"(the video runs {picture[0]:.3f}-{picture[1]:.3f}s); it is not kept")
+            info(remove_notes[-1])
     elif args.segments and (args.end or args.duration or args.start is not None):
         # A50: the single-range flags were accepted beside --segments and not read, where --remove
         # refuses the same combination
@@ -1588,7 +1621,7 @@ def main() -> int:
     # clean copy). clip_length's rule, as join.py uses it: less than a frame past -> end the
     # segment with its picture; more -> hold the last frame for the sound, which only a re-cut
     # can do. The last segment is left as the source had it: nothing is placed after it.
-    join_notes: List[str] = []
+    join_notes: List[str] = list(remove_notes)
     hold_needed = False
     vend = (video_end(args.input, meta) if len(segments) > 1 and video.get("fps") and not is_audio_output(output)
             and not dry_run_input_pending(args.input) else None)