ffmpeg-skill 3.8.12 → 3.8.13

package/scripts/scenes.py

@@ -110,6 +110,48 @@ def speech_music_ratio(samples: "List[float]", rate: int, step_s: float = SPEECH
     return [{"time": round(i * step_s, 2), "speech_music_ratio": round(z / med, 3)} for i, z in enumerate(zcrs)]
 
 
+# A --sheet picks one frame a scene with select. One expression summing a term a scene was refused
+# by FFmpeg 7.1 and later at 3,000 scenes ("Error while parsing expression", ENOMEM) and taken by
+# 6.1. No expression here grows with the scene count: the scenes are dealt round-robin to branches
+# of at most SHEET_SELECT_TERMS terms, each summed as a balanced tree (at most
+# ceil(log2(SHEET_SELECT_TERMS)) = 6 nested parentheses), and the branches' frames are merged back in
+# time order by interleave. Round-robin keeps the branches level, so interleave holds about one
+# thumbnail a branch.
+SHEET_SELECT_TERMS = 64
+
+
+def _first_at(t: float) -> str:
+    """The select term for the first frame at or after `t`. The starts are presentation times, so
+    the frame is chosen by its time, not by start x fps as a frame number -- on a
+    variable-frame-rate source that number is another frame (#411)."""
+    a = f"{max(0.0, t - 0.0006):.4f}"
+    return f"gte(t\\,{a})*(isnan(prev_t)+lt(prev_t\\,{a}))"
+
+
+def _balanced_sum(terms: List[str]) -> str:
+    if len(terms) == 1:
+        return terms[0]
+    mid = len(terms) // 2
+    return f"({_balanced_sum(terms[:mid])}+{_balanced_sum(terms[mid:])})"
+
+
+def sheet_graph(starts: List[float], src: str, thumb: str, tile: str) -> str:
+    """The --sheet filter graph: exactly one frame a scene (the first at or after its start), each
+    made a thumbnail by `thumb`, laid out by `tile`, out as [sheet]."""
+    # no scene (a dry run whose input an earlier step has yet to write, a clip of under one scene):
+    # the sheet is its one tile, the first frame, as the 1x1 layout the caller sized for it
+    starts = starts or [0.0]
+    k = max(1, math.ceil(len(starts) / SHEET_SELECT_TERMS))
+    if k == 1:
+        return f"{src}select='{_balanced_sum([_first_at(t) for t in starts])}',{thumb},{tile}[sheet]"
+    parts = [f"{src}split={k}" + "".join(f"[s{j}]" for j in range(k))]
+    for j in range(k):
+        expr = _balanced_sum([_first_at(t) for t in starts[j::k]])
+        parts.append(f"[s{j}]select='{expr}',{thumb}[t{j}]")
+    parts.append("".join(f"[t{j}]" for j in range(k)) + f"interleave=nb_inputs={k},{tile}[sheet]")
+    return ";".join(parts)
+
+
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("input")
@@ -305,6 +347,7 @@ def main() -> int:
             rank_key = lambda sc: (-sc["audio_rms"], sc["start"])
         ranked = sorted(scenes, key=rank_key)[: args.highlights]
         picks: List[Tuple[float, float]] = []
+        empty: List[Tuple[float, float]] = []
         budget = args.target if args.target else None
         per = (budget / max(1, len(ranked))) if budget else args.max_scene
         for sc in ranked:
@@ -314,36 +357,44 @@ def main() -> int:
             if env and length < sc["duration"]:
                 best, best_s = -1.0, sc["start"]
                 win = max(1, int(length / step_s))
-                lo, hi = int(sc["start"] / step_s), max(int(sc["start"] / step_s) + 1, int(sc["end"] / step_s) - win)
-                for i in range(lo, hi + 1):
+                # A139: a window starts at the scene's start or on the step grid after it, and
+                # ends inside the scene. The grid point at or before the start (floor) was a
+                # candidate, so a pick opened up to one step (0.5 s) early, on the previous shot
+                latest = sc["end"] - length
+                starts = [sc["start"]] + [i * step_s for i in range(math.ceil(sc["start"] / step_s - 1e-9),
+                                                                      math.floor(latest / step_s + 1e-9) + 1)
+                                          if sc["start"] < i * step_s <= latest]
+                for t in starts:
+                    i = int(t / step_s + 1e-9)
                     val = sum(env[i:i + win])
                     if val > best:
-                        best, best_s = val, i * step_s
-            picks.append((round(best_s, 2), round(min(sc["end"], best_s + length), 2)))
+                        best, best_s = val, t
+            # to the hundredth the result and the EDL are written in, inward: a start of 3.333
+            # written as 3.33 opened on the frame before the cut
+            pick_s = math.ceil(best_s * 100 - 1e-6) / 100
+            pick_e = math.floor(min(sc["end"], pick_s + length) * 100 + 1e-6) / 100
+            if pick_e <= pick_s:
+                # no hundredth fits inside it: written as 0.00-0.00 it was a range cut.py refuses
+                empty.append((sc["start"], sc["end"]))
+                continue
+            picks.append((pick_s, pick_e))
+        if empty and not picks:
+            die(f"--highlights found no range of at least 0.01 s, the precision the ranges are written in "
+                f"(each pick is at most {min(per, args.max_scene):g} s, or its scene is shorter)",
+                kind="input", hint="raise --target (or drop it), or lower --highlights")
+        for s, e in empty:
+            note(f"--highlights: the scene {s:.3f}-{e:.3f}s holds no range of at least 0.01 s and has no pick")
         picks.sort()
         result["highlights"] = [{"start": s, "end": e, "duration": round(e - s, 2)} for s, e in picks]
         result["highlights_total"] = round(sum(e - s for s, e in picks), 2)
         result["highlights_rank_by"] = args.rank_by
         info(f"proposed {len(picks)} highlight ranges totalling {result['highlights_total']:.1f}s")
-        if args.edl:
-            if not STATE.dry_run:  # the contract says --edl is not written under --dry-run
-                with open(args.edl, "w", encoding="utf-8") as fh:
-                    for s, e in picks:
-                        fh.write(f"{s:.2f}-{e:.2f}\n")
-            info(f"wrote {args.edl}")
 
     if args.sheet:
         n = len(scenes)
         cols = min(4, max(1, n))
         rows = max(1, math.ceil(n / cols))
         tile_w = 1280 // cols // 2 * 2
-        # exactly one frame per scene: the first frame at or after the scene start. The starts are
-        # presentation times, so the frame is chosen by its time, not by start x fps as a frame
-        # number -- on a variable-frame-rate source that number is another frame (#411)
-        def first_at(t: float) -> str:
-            a = f"{max(0.0, t - 0.0006):.4f}"
-            return f"gte(t\\,{a})*(isnan(prev_t)+lt(prev_t\\,{a}))"
-        expr = "+".join(first_at(sc["start"]) for sc in scenes)
         stamp = ""
         if not args.no_timecode and ffmpeg_filters() and "drawtext" not in ffmpeg_filters():
             # as look.py (#394): the sheet needs drawtext only for its stamps
@@ -360,13 +411,23 @@ def main() -> int:
         # a non-square-pixel source is squared at its display aspect (#411)
         lab = bt709_label_filter(meta)
         square = square_pixels(meta["video"])
-        vf = (f"select='{expr}'," + (lab + "," if lab else "") + (square + "," if square else "")
-              + f"scale={tile_w}:-2{stamp},"
-              f"tile={cols}x{rows}:padding=2:margin=2:color=0x202020")
-        run(ffmpeg_base() + ["-i", args.input, "-map", f"0:{PROBED_VIDEO}", "-an", "-vf", vf, "-frames:v", "1", "-fps_mode", "vfr", "-update", "1", args.sheet])
+        thumb = (lab + "," if lab else "") + (square + "," if square else "") + f"scale={tile_w}:-2{stamp}"
+        graph = sheet_graph([sc["start"] for sc in scenes], f"[0:{PROBED_VIDEO}]", thumb,
+                            f"tile={cols}x{rows}:padding=2:margin=2:color=0x202020")
+        run(ffmpeg_base() + ["-i", args.input, "-filter_complex", graph, "-map", "[sheet]", "-an",
+                             "-frames:v", "1", "-fps_mode", "vfr", "-update", "1", args.sheet])
         info(f"wrote {args.sheet}")
         result["sheet"] = args.sheet
 
+    # after the sheet, as silence.py writes its EDL after the cut (#462 A41): a --sheet refused as an
+    # existing file, or failed, left the EDL behind, and the corrected retry was then refused for it
+    if args.highlights and args.edl:
+        if not STATE.dry_run:  # the contract says --edl is not written under --dry-run
+            with open(args.edl, "w", encoding="utf-8") as fh:
+                for s, e in picks:
+                    fh.write(f"{s:.2f}-{e:.2f}\n")
+        info(f"wrote {args.edl}")
+
     if STATE.json:  # --json-brief too: emit() is what adds the diagnostics (scenes_sheet_no_drawtext)
         emit(None, **result)
     else:

package/scripts/silence.py

@@ -33,7 +33,7 @@ from _common.runner import parse_json, replace_checked
 from _common import guard_sidecar, refuse_existing_outputs, refuse_output_is_input, _check_output_path
 from _common.emit import refuse
 from _common import detect_silences as detect, STATE, add_common, apply_common, default_output, die, emit, info, is_audio_output, print_json, probe, X264_PRESETS, measured_level_dbfs, fmt_secs
-from _common.decision import frame_rate, stream_starts
+from _common.decision import frame_rate, grid_at_or_after, stream_starts
 from _common.probe import PROBED_AUDIO
 from _common.emit import input_length
 
@@ -163,21 +163,47 @@ def speech_aware_silences(path: str, threshold: float, min_silence: float) -> "T
     return boundaries, breaths
 
 
+# how close to the start or the end of the sound a silence's edge may sit and still be where the sound
+# starts or ends: silencedetect closes a silence that runs to the end at its last decoded block (7.509
+# for a sound probed as 7.500), and an AAC stream's stated start sits a priming frame off its samples
+SOUND_EDGE = 0.05
+
+
+def sound_span(meta: Dict[str, Any], duration: float) -> Tuple[float, float]:
+    """Where the sound starts and ends on the clock silencedetect reports on (the file's), for
+    inside_margin(): its start, and its own end (the file's length when that is not stated). The
+    end is stream_end()'s: a Matroska DURATION tag is already where the sound ends, and adding the
+    start to it put the end of a sound from 1 s to 6 s at 7 s."""
+    from _common.emit import file_origin, stream_end
+    a0 = stream_starts(meta)[1]
+    end = stream_end(meta, "audio")
+    return a0, (end - file_origin(meta)) if end is not None else duration
+
+
 def inside_margin(silences: List[Tuple[float, float]], duration: float, margin: float,
-                  lead: Optional[float] = None) -> List[Tuple[float, float]]:
+                  lead: Optional[float] = None,
+                  sound: Optional[Tuple[float, float]] = None) -> List[Tuple[float, float]]:
     """Each silence with a margin kept on both sides: the stretch actually removed. `margin` is
     kept after the speech that ends where the silence starts (--margin-tail), `lead` before the
     speech that starts where it ends (--margin-lead; the same as `margin` when not given). A
     silence too short to hold both removes nothing (it is dropped, never turned inside out).
 
+    A silence with no speech on one side keeps no margin on that side (#462 A40): one that starts
+    where the sound does (`sound`, from sound_span()) is removed from the file's start, and one
+    that runs to where the sound ends (or that silencedetect never closed, `inf`) to the file's end.
+    A margin there kept dead air as a piece of its own, with a jump cut after it; FFmpeg 6.1 closes
+    a silence at the end of the file, so the `inf` end alone never caught the last one.
+
     The margin is applied to the silences alone, before they are merged with filler spans (#414):
     a filler word's span is the word itself plus --filler-pad, and taking a 0.2 s margin off each
     side of it turned every word narrower than 2 x --margin inside out -- kept, and still counted
     as removed."""
     out: List[Tuple[float, float]] = []
     for s, e in silences:
-        a = s + margin
-        b = duration if e == float("inf") else min(duration, e - (margin if lead is None else lead))
+        opens = sound is not None and s <= sound[0] + SOUND_EDGE
+        closes = e == float("inf") or (sound is not None and e >= sound[1] - SOUND_EDGE)
+        a = 0.0 if opens else s + margin
+        b = duration if closes else min(duration, e - (margin if lead is None else lead))
         if b > a:
             out.append((a, b))
     return out
@@ -215,7 +241,10 @@ def rendered_ranges(keeps: List[Tuple[float, float]], meta: Dict[str, Any], dura
     v0 = stream_starts(meta)[0]
 
     def snap(t: float) -> float:
-        return min(v0 + round((t - v0) * rate) / rate, duration)
+        # a video that starts after the sound puts frame times before 0 on its grid's extension: a
+        # bound there moves to the first one at or after 0, which is where the re-cut starts (#462 A43)
+        t = v0 + round((t - v0) * rate) / rate
+        return min(t if t >= 0 else grid_at_or_after(0.0, v0, rate), duration)
     return [(a, b) for a, b in ((snap(s), snap(e)) for s, e in keeps) if b > a]
 
 
@@ -307,8 +336,10 @@ def cut_levels(path: str, tm: Dict[str, Any], duration: float,
     out = []
     with tempfile.TemporaryDirectory(prefix="silence-levels-") as tmp:
         raw = os.path.join(tmp, "pcm.s16le")
+        # padded from the file's start, as decode_pcm_mono() pads it: the windows are read at
+        # t x rate, so a sound that starts late was read that far after each cut (#462 A42)
         proc = run_analysis([require_tool("ffmpeg"), "-hide_banner", "-loglevel", "error", "-nostdin", "-i", path,
-                             "-map", f"0:{PROBED_AUDIO}", "-vn",
+                             "-map", f"0:{PROBED_AUDIO}", "-vn", "-af", "aresample=async=1:first_pts=0",
                              "-ac", str(channels), "-ar", str(CUT_LEVEL_RATE), "-f", "s16le", "-y", raw],
                             check=False, text=False)
         if proc.returncode != 0 or not os.path.isfile(raw) or not os.path.getsize(raw):
@@ -624,8 +655,9 @@ def main() -> int:
     fil.add_argument("--filler-list", action="store_true",
                      help="report what --filler would remove and write nothing")
     fil.add_argument("--max-cuts", type=int, default=400,
-                     help="refuse above this many removal ranges: the filter graph grows with them "
-                          "(default 400)")
+                     help="refuse to render above this many removal ranges (default 400): that many cuts usually "
+                          "means --threshold, --min-silence or the filler list is catching speech. --list and "
+                          "--filler-list report them without the limit")
     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)
     add_common(ap)
@@ -686,6 +718,7 @@ def main() -> int:
     if not meta.get("audio"):
         die("input has no audio stream to analyse")
     duration = input_length(meta)
+    sound = sound_span(meta, duration)
     breaths: List[Tuple[float, float]] = []
     if args.speech_aware:
         silences, breaths = speech_aware_silences(args.input, args.threshold, args.min_silence)
@@ -717,10 +750,10 @@ def main() -> int:
     def margined(spans: List[Tuple[float, float]]) -> List[Tuple[float, float]]:
         """The stretch of each silence that is removed: its own tail for one after a sentence end."""
         if not by_sentence:
-            return inside_margin(spans, duration, tail, lead)
+            return inside_margin(spans, duration, tail, lead, sound)
         out: List[Tuple[float, float]] = []
         for span, pos in zip(spans, positions):
-            out += inside_margin([span], duration, sentence_tail if pos == "sentence_end" else tail, lead)
+            out += inside_margin([span], duration, sentence_tail if pos == "sentence_end" else tail, lead, sound)
         return out
     # One sorted, merged removal list through the graph the tool already has: filler removal IS
     # time-range removal, so it reuses keep_ranges() and the same select chain.
@@ -730,7 +763,9 @@ def main() -> int:
     keeps = keep_ranges(removals, duration, 0.0, args.min_keep)
     # what the render holds (on a picture, each bound on its nearest frame): the report, the EDL
     # and the time map all describe these, so a re-cut or a sum of `keep` is the rendered edit
-    video_out = bool(meta.get("video")) and not (media_out and is_audio_output(media_out))
+    # from the -o given, under --list and --filler-list too (which write no media): a list for an
+    # audio -o reported frame-snapped ranges that the audio run does not cut (#462 A48)
+    video_out = bool(meta.get("video")) and not is_audio_output(args.output or "")
     held = rendered_ranges(keeps, meta, duration, video_out)
     kept = sum(e - s for s, e in held)
     removed = max(0.0, duration - kept)
@@ -787,10 +822,6 @@ def main() -> int:
         # an English-only transcript made on an assumption (asr.assumed_english_note): the
         # bridge already logged the warning; the result document carries it at the top level
         summary["notes"] = list(args._asr_notes)
-    if len(keeps) > args.max_cuts:
-        die(f"{len(keeps)} keep ranges is above --max-cuts {args.max_cuts}: the filter graph grows "
-            "with every range and a graph this size is slow and fragile. Raise --max-cuts if you "
-            "mean it, or use --min-silence/--filler-pad to merge the short ones.", kind="input")
     filler_only = args.filler and not args.speech_aware and not by_sentence
     if filler_only:
         info(f"--filler only (no --speech-aware): skipping generic silence detection, "
@@ -812,6 +843,14 @@ def main() -> int:
         info("hint: " + summary["hint"])
 
     tm = time_map(held, duration)
+    cuts = len(tm["removed"])
+    if cuts > args.max_cuts and not (args.list or args.filler_list):
+        # the removal ranges, as --max-cuts says, not the kept ones; a list renders nothing and is
+        # how the caller sees what the limit is about (#462 A49)
+        die(f"{cuts} removal ranges is above --max-cuts {args.max_cuts}: that many cuts usually means "
+            "--threshold, --min-silence or the filler list is catching speech. Check them with --list, then "
+            "raise --max-cuts if you mean it, or use --min-silence/--filler-pad to merge the short ones.",
+            kind="input")
     points: Any = False  # False: not measured (a dry run over a pending input); None: the decode failed
     if not (STATE.dry_run and not os.path.exists(args.input)):
         points = cut_levels(args.input, tm, duration, list(filler_ranges))
@@ -841,7 +880,12 @@ def main() -> int:
             info(f"wrote {args.timemap}")
         summary["timemap"] = args.timemap
 
-    if args.edl:
+    def finish_edl() -> None:
+        """Written with the time map, once the cut exists (or under --list): an EDL left by a
+        refused run (an existing -o, -o the input, nothing kept) or a failed encode described
+        media never made, and then blocked the corrected retry as an existing file (#462 A41)."""
+        if not args.edl:
+            return
         if not STATE.dry_run:  # the EDL is an artifact like the cut itself: a plan writes nothing
             with open(args.edl, "w", encoding="utf-8") as fh:
                 on_frames = bool(video_out and frame_rate(meta))
@@ -852,6 +896,7 @@ def main() -> int:
         info(f"wrote {args.edl}")
 
     if args.list or args.filler_list:
+        finish_edl()
         finish_time_map()
         if args.json:
             emit(None, **summary)
@@ -883,6 +928,7 @@ def main() -> int:
         _cut.join_from_source(args.input, held, output, meta, args.crf, args.preset, tmp)
     r = probe(output, role="output")
     info(f"wrote {output} ({fmt_secs(r['duration'])}, expected ~{kept:.3f}s)")
+    finish_edl()
     finish_time_map()
     emit(output, **summary)
     return 0

package/scripts/sync.py

@@ -7,7 +7,9 @@ reduced to a loudness envelope, cross-correlated with an FFT implemented in
 Python (coarse, 20 ms), then refined by direct correlation at 1 ms.
 
 Offset semantics: a positive offset means the SECOND input starts LATER
-than the reference, i.e. `second` must be shifted earlier by that amount.
+than the reference (it began recording after it), so its sound is delayed by
+that amount (its head padded) to line up; a negative offset means it started
+earlier, and its first -offset seconds are dropped.
 
 This aligns two AUDIO tracks to each other; it does not check or guarantee
 lip sync (mouth movement matching the audio). It assumes each recording's
@@ -161,9 +163,14 @@ def cross_correlate(ref: List[float], other: List[float], max_lag: int):
 
         scores.append((val, lag))
         if val > best_val:
-            second = best_val
             best_val, best_lag = val, lag
-        elif val > second and abs(lag - best_lag) > 5:
+    # The runner-up is the best other PEAK more than 5 lags from the winner (A126). The running
+    # "previous best" this used to take was usually the winner's own neighbour, one lag away and
+    # on the same slope, so an exact match read 0.59 and could not be told from a tie (0.50).
+    by_lag = dict((lag, val) for val, lag in scores)
+    for val, lag in scores:
+        if abs(lag - best_lag) > 5 and val > second and \
+                val >= by_lag.get(lag - 1, -float("inf")) and val >= by_lag.get(lag + 1, -float("inf")):
             second = val
     # confidence: peak similarity, penalised when a distant runner-up is nearly as good
     conf = max(0.0, min(1.0, best_val))

package/scripts/waveform.py

@@ -43,6 +43,7 @@ from _common import (add_common, apply_common, aac_args, default_output, die, dr
                      fmt_secs, child_args, run_tool, measured_level_dbfs, sibling_temp)
 from _common.emit import absorb_stage_hw, note, warn
 from _common.decision import length_output_t
+from _common.probe import AUDIO_MEDIA_EXT
 
 WAVEFORM_MODES = ["point", "line", "p2p", "cline"]
 
@@ -50,7 +51,7 @@ WAVEFORM_MODES = ["point", "line", "p2p", "cline"]
 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>_waveform.<ext>)")
+    ap.add_argument("-o", "--output", help="output file, a video (default: <name>_waveform.<ext>, .mp4 for an audio input; an audio extension is refused)")
     ap.add_argument("--style", choices=["waveform", "spectrum"], default="waveform", help="waveform (default) or spectrum visualization")
     ap.add_argument("--width", type=int, default=1920, help="output width in px, must be even (default 1920)")
     ap.add_argument("--height", type=int, default=1080, help="output height in px, must be even (default 1080)")
@@ -170,7 +171,16 @@ def main() -> int:
                 die(f"{args.input} is silent (audio stream {args.audio_stream} peaks at {silent_peak:g} dBFS, at or below "
                     f"--silence-threshold {args.silence_threshold:g}): the visualisation would be a flat line",
                     kind="input", hint="check the audio, or pass --on-silent warn to render it anyway")
-    output = args.output or default_output(args.input, "waveform")
+    # A137: the output always holds a picture, so an audio input's extension is not the default:
+    # talk.wav made talk_waveform.wav, which the WAV muxer refused (kind ffmpeg), and talk.m4a an
+    # H.264 video named .m4a
+    in_ext = os.path.splitext(args.input)[1].lower()
+    output = args.output or default_output(args.input, "waveform", "mp4" if in_ext in AUDIO_MEDIA_EXT else None)
+    # every audio-only extension this skill reads, not only those it writes (is_audio_output():
+    # .aif, .aiff, .caf and .wma are not there, and passed this to fail in ffmpeg, or in a dry run not at all)
+    if os.path.splitext(output)[1].lower() in AUDIO_MEDIA_EXT:
+        die(f"{output}: waveform.py writes a video, and {os.path.splitext(output)[1].lower()} holds sound only; "
+            "name a video file (.mp4, .mov, .mkv)", kind="input")
 
     # The visualisation's own band. Without --image/--position it fills the frame, which is what
     # every 1.15 command line did, so the graph below is byte-identical when no new flag is given.