ffmpeg-skill 1.15.1 → 1.16.0

package/scripts/check.py

@@ -173,6 +173,25 @@ def main() -> int:
         row("chapters", "PASS" if chapters else "WARN", f"{len(chapters)}" if chapters else "none", ">= 1 chapter marker",
             "metadata.py episode.m4a --chapters chapters.txt (`TIME TITLE` per line; streams copied)",
             reason="chapter markers are optional, but a podcast app shows them as the episode's seekable table of contents")
+    # Subtitles, informational and on every platform: a soft subtitle track that carries no
+    # language tag is the defect caption.py --mode mux's multi-track form exists to prevent -- a
+    # player lists it as "Track 2" and a viewer cannot tell which language it is. Never counted in
+    # `failed`: no platform refuses a delivery over it.
+    subs = meta.get("subtitle_stream_details") or []
+    if not subs:
+        row("subtitles", "WARN", "none", ">= 1 language-tagged subtitle track",
+            "caption.py video.mp4 --mode mux --srt subs.srt:en -o video_subs.mkv (streams are copied)",
+            reason="subtitles are optional, but they are the cheapest accessibility win a delivery has")
+    else:
+        untagged = [str(s["index"]) for s in subs if not s.get("language")]
+        listed = ", ".join((s.get("language") or "untagged") for s in subs)
+        row("subtitles", "WARN" if untagged else "PASS", f"{len(subs)} ({listed})",
+            "every track tagged with its language",
+            "caption.py video.mp4 --mode mux --srt subs.srt:en -o video_subs.mkv, or re-mux with `--srt file:lang` per track"
+            if untagged else "",
+            reason=("stream(s) " + ", ".join(untagged) + " carry no language tag: a player lists them "
+                    "by number and the viewer has to guess") if untagged else "")
+
     if a:
         if a.get("sample_rate") and a["sample_rate"] not in (44100, 48000):
             row("sample rate", "WARN", a["sample_rate"], "44100 or 48000", "loudness.py --sample-rate 48000")

package/scripts/graphics.py

@@ -38,7 +38,8 @@ from _common import (aac_args, add_common, brand_caption_style, script_font_for_
                      drawtext_boxborderw, X264_PRESETS, time_arg, fmt_secs, STATE, drawtext_text_opts,
                      LANGUAGE_NAMES, needs_shaping, detect_script, BIDI_SCRIPTS, font_family_of_file, font_family_for_script, has_emoji,
                      emoji_clusters, emoji_codepoint_name, char_script, emoji_filter_chain, emoji_asset_for, emoji_support, resolve_emoji_assets,
-                     EMOJI_ASSET_HINT, text_width_em, drawtext_shaping)
+                     EMOJI_ASSET_HINT, text_width_em, drawtext_shaping, wrap_text, WRAP_MODES,
+                     SAFE_WIDTH_FRACTION)
 from _ass_overlay import text_overlay_ass, EMOJI_SENTINEL
 
 TEMPLATES = ["lower-third", "title", "chapter", "progress", "countdown", "bug", "sticker", "hook", "meme"]
@@ -91,6 +92,12 @@ def main() -> int:
     ap.add_argument("--lang", help="language code of the text (e.g. ja, zh, ko): the hint that says whether Han-only "
                                    "text is Chinese, Japanese or Korean when a font is picked by script")
     ap.add_argument("--scale", type=float, default=1.0, help="size multiplier (default 1)")
+    ap.add_argument("--wrap", choices=list(WRAP_MODES), default="phrase",
+                    help="how a label too wide for the frame is broken into lines: 'phrase' (default, 1.16) never "
+                         "breaks inside a word or a hyphen's wrong side, never leaves a lone digit, kana or "
+                         "punctuation on its own line, prefers Japanese sentence ends and particles, and never ends "
+                         "a line on an article or preposition; 'measured' is 1.15's width-only wrap. A label that "
+                         "already fits one line is untouched either way")
     ap.add_argument("--text-render", choices=["auto", "ass", "drawtext"], default="auto",
                     help="which renderer draws the template's text: 'auto' (default) uses libass for "
                          "scripts drawtext cannot shape (Devanagari, Bengali, Tamil, Thai, Lao ...) and for "
@@ -247,6 +254,32 @@ def main() -> int:
             return os.path.dirname(os.path.abspath(script_file))
         return None
 
+    def chip_frac(left, right, pad):
+        """The fraction of the frame a boxed label may use: the span between the margins, less
+        drawtext's own box padding on each side."""
+        usable = W - left - right - 2 * pad
+        return max(0.1, min(SAFE_WIDTH_FRACTION, usable / float(W))) if W else SAFE_WIDTH_FRACTION
+
+    def wrapped(text, size_px, frac=SAFE_WIDTH_FRACTION):
+        """A label broken to the frame's safe width (1.16).
+
+        drawtext and libass both render a literal newline as a line break, and every template
+        below already passes its label through one of them -- so wrapping is a matter of putting
+        the breaks in, at the same measured width and by the same four phrase rules caption.py
+        uses. A label that already fits comes back unchanged, which is why this is additive: the
+        only text it touches is text that used to run off the edge of the frame.
+        """
+        text = str(text or "")
+        if not text or not size_px:
+            return text
+        max_em = (W * frac) / float(size_px)
+        if max_em <= 0:
+            return text
+        out = []
+        for para in text.split("\n"):
+            out.extend(wrap_text(para, max_em, mode=args.wrap, lang=args.lang) if para.strip() else [para])
+        return "\n".join(out)
+
     def add_text(text, drawtext, *, target=None, **el):
         """One line of template text: a drawtext filter on the old route, an ASS element on the
         new one. The geometry is computed identically either way."""
@@ -366,8 +399,11 @@ def main() -> int:
         align = (7 if "left" in pos else 9) if "top" in pos else (1 if "left" in pos else 3)
         y_rest = m_top if "top" in pos else H - m_bottom
         y_start = y_rest + rise if "top" in pos else y_rest + rise
-        add_text(args.text,
-                 f"drawtext={drawtext_text_opts(args.text)}:{fo}:fontsize={fs}:fontcolor={ff_color(bg)}:"
+        # the chip is a box between the two side margins, not the whole frame: wrapping to the
+        # frame width let a long --text run off the plate even though it "fitted"
+        sticker_text = wrapped(args.text, fs, chip_frac(m_left, m_right, padx))
+        add_text(sticker_text,
+                 f"drawtext={drawtext_text_opts(sticker_text)}:{fo}:fontsize={fs}:fontcolor={ff_color(bg)}:"
                  f"x={xe}:y='{ye}':box=1:boxcolor={ff_color(primary, 0.95)}:boxborderw={drawtext_boxborderw(pady, padx)}:"
                  f"alpha='{alpha}':{en}",
                  size=fs, color=bg, font=ass_font_family(), align=align,
@@ -391,8 +427,9 @@ def main() -> int:
         band_h = int(base * 0.30)
         y0 = (H - band_h) // 2
         filters.append(f"drawbox=x=0:y={y0}:w=iw:h={band_h}:color={ff_color(bg, 0.78)}:t=fill:{hen}")
-        add_text(args.title,
-                 f"drawtext={drawtext_text_opts(args.title)}:{fo}:fontsize={h1}:fontcolor={ff_color(text_c)}:"
+        hook_title = wrapped(args.title, h1)
+        add_text(hook_title,
+                 f"drawtext={drawtext_text_opts(hook_title)}:{fo}:fontsize={h1}:fontcolor={ff_color(text_c)}:"
                  f"x=(w-text_w)/2:y=(h-text_h)/2:{hen}",
                  size=h1, color=text_c, font=ass_font_family(), align=5, x=W / 2, y=H / 2,
                  outline=max(1.0, h1 / 20.0), outline_color="000000", start=s, end=he)
@@ -401,7 +438,8 @@ def main() -> int:
 
     elif args.template == "meme":
         # The classic layout: heavy white upper-case lines with a black outline, top and bottom,
-        # sized so a short line fills the frame's width without wrapping (drawtext never wraps).
+        # sized so a short line fills the frame's width; a longer one is broken by the same
+        # phrase-aware wrap caption.py uses (1.16 -- drawtext itself still never wraps).
         if not (args.top or args.bottom):
             die("meme needs --top and/or --bottom")
         fs = int(base * 0.09)
@@ -410,8 +448,9 @@ def main() -> int:
         for text, y in ((args.top, f"{m_top}"), (args.bottom, f"h-text_h-{m_bottom}")):
             if not text:
                 continue
-            add_text(text.upper(),
-                     f"drawtext={drawtext_text_opts(text.upper())}:{fo}:fontsize={fs}:fontcolor={white}:"
+            meme_line = wrapped(text.upper(), fs)
+            add_text(meme_line,
+                     f"drawtext={drawtext_text_opts(meme_line)}:{fo}:fontsize={fs}:fontcolor={white}:"
                      f"borderw={bw}:bordercolor={black}:x=(w-text_w)/2:y={y}:{en}",
                      size=fs, color="FFFFFF", font=ass_font_family(), bold=True,
                      align=(8 if y == f"{m_top}" else 2), x=W / 2,

package/scripts/metadata.py

@@ -30,7 +30,9 @@ import tempfile
 from pathlib import Path
 from typing import Any, Dict, List, Optional
 
-from _common import add_common, apply_common, default_output, die, emit, ffmpeg_base, info, time_arg, probe, run, STATE, read_text_or_die
+from _common import (add_common, apply_common, default_output, description_block, detect_scenes, detect_silences,
+                     die, emit, ffmpeg_base, fmt_chapter_time, info, propose_chapters, time_arg, probe, run,
+                     STATE, read_text_or_die)
 
 CHAPTER_CONTAINERS = {".mp4", ".m4v", ".m4a", ".mov", ".mkv", ".mka", ".webm"}
 TAG_KEYS = ("title", "artist", "album", "comment", "date", "genre")
@@ -82,12 +84,119 @@ def write_ffmetadata(chapters: List[Dict[str, Any]], path: str) -> None:
     Path(path).write_text("\n".join(lines) + "\n", encoding="utf-8")
 
 
+def propose(args, meta: Dict[str, Any], duration: float,
+            notes: List[str]) -> "tuple":
+    """--auto-chapters: measure the structure, then hand it to the pure proposer.
+
+    The detectors are the ones silence.py and scenes.py run (they live in _common/probe.py since
+    1.16 so that no tool has to import another tool); the decision is propose_chapters(), which
+    is pure and never looks at content.
+    """
+    source = args.detect_from
+    if not meta.get("audio") and source in ("silence", "both"):
+        if source == "silence":
+            die("--from silence needs an input with an audio stream; use --from scenes", kind="input")
+        source = "scenes"
+        notes.append("no audio stream: the markers come from scene changes alone (--from scenes)")
+    if not meta.get("video") and source in ("scenes", "both"):
+        if source == "scenes":
+            die("--from scenes needs an input with a video stream; use --from silence", kind="input")
+        source = "silence"
+        notes.append("no video stream: the markers come from the pauses alone (--from silence)")
+    silences = detect_silences(args.input, args.silence_threshold, args.silence_min) \
+        if source in ("silence", "both") else []
+    cuts = detect_scenes(args.input, args.scene_threshold, 1.0, duration) \
+        if source in ("scenes", "both") else []
+    if source == "both":
+        notes.append("measured in 2 passes (silencedetect and scdet each decode the file once); "
+                     "--from silence is the cheap path")
+    proposed = propose_chapters(duration, silences, cuts, min_chapter=args.min_chapter,
+                                max_chapters=args.max_chapters, source=source)
+    if len(proposed) == 1:
+        # every suggestion has to be a value the caller is not already using, or the hint reads
+        # "try --min-chapter 1" to someone who passed --min-chapter 1
+        tries = []
+        shorter_silence = round(args.silence_min / 2.0, 2)
+        if shorter_silence >= 0.1 and shorter_silence < args.silence_min:
+            tries.append(f"--silence-min {shorter_silence:g}")
+        shorter_chapter = max(1.0, round(args.min_chapter / 2.0, 2))
+        if shorter_chapter < args.min_chapter:
+            tries.append(f"--min-chapter {shorter_chapter:g}")
+        if args.detect_from != "both" and meta.get("audio") and meta.get("video"):
+            tries.append("--from both")
+        notes.append(f"no pause longer than {args.silence_min:g}s and no scene change far enough apart "
+                     "to start a chapter: the file gets one marker at 0:00"
+                     + (". Try " + " or ".join(tries) if tries else
+                        ", and the thresholds are already as low as this tool will suggest"))
+    total = len([1 for _s in silences]) + len([c for c in cuts if c > 0])
+    auto = {
+        "source": {"silence": "silence", "scenes": "scenes", "both": "silence+scenes"}[source],
+        "min_chapter": float(args.min_chapter),
+        "max_chapters": int(args.max_chapters),
+        "proposed": total,
+        "kept": len(proposed),
+        "titles": "placeholder",
+        "chapters": proposed,
+        "description_block": description_block(proposed),
+    }
+    entries = [{"start": c["at"], "title": c["title"]} for c in proposed]
+    for i, e in enumerate(entries):
+        e["end"] = entries[i + 1]["start"] if i + 1 < len(entries) else duration
+    info(f"proposed {len(entries)} chapters from {auto['source']} "
+         f"(titles are placeholders: Chapter 1..{len(entries)})")
+    return entries, auto
+
+
+def write_proposal(args, chapters: List[Dict[str, Any]]) -> Dict[str, Any]:
+    """--chapters-out / --description-out, the two side files a caller edits and feeds back."""
+    files: Dict[str, Any] = {"chapters": None, "description": None}
+    if args.chapters_out:
+        body = "\n".join(f"{fmt_chapter_time(c['at'])} {c['title']}" for c in chapters) + "\n"
+        if STATE.dry_run:
+            info(f"[dry-run] would write {args.chapters_out} ({len(chapters)} chapters)")
+        else:
+            Path(args.chapters_out).write_text(body, encoding="utf-8")
+            info(f"wrote {args.chapters_out} ({len(chapters)} chapters)")
+        files["chapters"] = args.chapters_out
+    if args.description_out:
+        body = description_block(chapters) + "\n"
+        if STATE.dry_run:
+            info(f"[dry-run] would write {args.description_out}")
+        else:
+            Path(args.description_out).write_text(body, encoding="utf-8")
+            info(f"wrote {args.description_out}")
+        files["description"] = args.description_out
+    return files
+
+
 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>_meta.<ext>)")
     ap.add_argument("--chapters", help="text file, one chapter per line: `TIME TITLE` (cut.py time syntax)")
     ap.add_argument("--clear-chapters", action="store_true", help="remove every chapter marker the input carries")
+    auto = ap.add_argument_group("proposed chapters (1.16)",
+                                 "Chapter timestamps measured from the file's own structure instead of read from a "
+                                 "file. The markers are proposed, the titles are not: every one is `Chapter N` and "
+                                 "renaming them is the caller's job -- knowing what is said in a chapter is not "
+                                 "something this skill can measure. Two detectors mean two full decodes of the "
+                                 "input; --from silence is the cheap path.")
+    auto.add_argument("--auto-chapters", action="store_true",
+                      help="propose the markers from measured pauses and scene changes instead of reading --chapters FILE")
+    auto.add_argument("--min-chapter", type=float, default=60.0,
+                      help="shortest chapter in seconds (default 60, a long-form default: a 12-minute episode gets at most 12)")
+    auto.add_argument("--max-chapters", type=int, default=0,
+                      help="cap the number of markers (default 0 = no cap); the weakest evidence is dropped first")
+    auto.add_argument("--from", dest="detect_from", choices=["silence", "scenes", "both"], default="both",
+                      help="which detector(s) propose the markers (default both)")
+    auto.add_argument("--silence-threshold", type=float, default=-35.0,
+                      help="silence level in dBFS for --auto-chapters (default -35)")
+    auto.add_argument("--silence-min", type=float, default=1.5,
+                      help="a pause must last this long to propose a chapter (default 1.5 -- deliberately longer than silence.py's 0.6: a chapter break is a long pause)")
+    auto.add_argument("--scene-threshold", type=float, default=8.0,
+                      help="minimum scdet score for a scene cut with --auto-chapters (default 8, as scenes.py)")
+    auto.add_argument("--chapters-out", help="write the proposal as a `TIME TITLE` file in this tool's own --chapters format, so the titles can be edited and fed back")
+    auto.add_argument("--description-out", help="write the YouTube description block (`00:00 Chapter 1` per line)")
     for key in TAG_KEYS:
         ap.add_argument(f"--{key}", help=f"set the container's {key} tag (empty string clears it)")
     add_common(ap)
@@ -96,9 +205,15 @@ def main() -> int:
 
     if args.chapters and args.clear_chapters:
         die("--chapters and --clear-chapters exclude each other")
+    if args.auto_chapters and (args.chapters or args.clear_chapters):
+        die("--auto-chapters proposes the markers; it excludes --chapters FILE and --clear-chapters")
+    if args.min_chapter <= 0:
+        die(f"--min-chapter must be > 0, got {args.min_chapter:g}")
+    if args.max_chapters < 0:
+        die(f"--max-chapters must be >= 0 (0 = no cap), got {args.max_chapters}")
     tags = {k: getattr(args, k) for k in TAG_KEYS if getattr(args, k) is not None}
-    if not args.chapters and not args.clear_chapters and not tags:
-        die("nothing to write: give --chapters FILE, --clear-chapters and/or --title/--artist/...")
+    if not args.chapters and not args.clear_chapters and not args.auto_chapters and not tags:
+        die("nothing to write: give --chapters FILE, --auto-chapters, --clear-chapters and/or --title/--artist/...")
     if args.chapters and not os.path.exists(args.chapters):
         die(f"chapters file not found: {args.chapters}")
 
@@ -107,12 +222,16 @@ def main() -> int:
     if os.path.abspath(output) == os.path.abspath(args.input):
         die("output must differ from the input (metadata.py never rewrites a file in place)")
     out_ext = Path(output).suffix.lower()
-    if (args.chapters or args.clear_chapters) and out_ext not in CHAPTER_CONTAINERS:
+    if (args.chapters or args.clear_chapters or args.auto_chapters) and out_ext not in CHAPTER_CONTAINERS:
         die(f"{out_ext or 'this'} container cannot hold chapter markers; write to one of "
             f"{', '.join(sorted(CHAPTER_CONTAINERS))} (the streams are copied, so choose the matching family: .mp4/.mov/.m4a for MPEG-4, .mkv/.mka/.webm for Matroska)")
 
     duration = meta.get("duration") or 0.0
     chapters: Optional[List[Dict[str, Any]]] = parse_chapters(args.chapters, duration) if args.chapters else None
+    auto: Optional[Dict[str, Any]] = None
+    notes: List[str] = []
+    if args.auto_chapters:
+        chapters, auto = propose(args, meta, duration, notes)
 
     cmd = ffmpeg_base() + ["-i", args.input]
     tmpdir = None
@@ -139,7 +258,13 @@ def main() -> int:
     if args.clear_chapters and not STATE.dry_run and written:
         die(f"{len(written)} chapters survived --clear-chapters", kind="output")
     info(f"wrote {output} ({len(written)} chapters, tags: {', '.join(sorted(tags)) or 'unchanged'}, streams copied)")
-    emit(output, chapters=written, tags=result.get("tags") or {}, streams_copied=True)
+    extra: Dict[str, Any] = {}
+    if auto is not None:
+        auto["files"] = write_proposal(args, auto["chapters"])
+        extra["auto_chapters"] = auto
+    if notes:
+        extra["notes"] = notes
+    emit(output, chapters=written, tags=result.get("tags") or {}, streams_copied=True, **extra)
     return 0
 
 

package/scripts/render.py

@@ -67,7 +67,7 @@ HERE = Path(__file__).resolve().parent
 TEMPLATE_DIR = HERE.parent / "templates"
 # The placeholders a delivery template carries; a block whose placeholder has no value
 # (no --logo, no --title, no cues) is dropped from the filled project rather than rendered empty.
-PLACEHOLDERS = ("$INPUT", "$OUTPUT", "$CUES", "$SRT", "$LOGO", "$TITLE", "$BRAND", "$CHAPTERS")
+PLACEHOLDERS = ("$INPUT", "$OUTPUT", "$CUES", "$SRT", "$LOGO", "$TITLE", "$BRAND", "$CHAPTERS", "$IMAGE")
 # Intermediates follow the delivery's own media kind: an audio-only project (the podcast
 # template) must not carry its stages through .mp4 containers.
 AUDIO_EXT = frozenset({".wav", ".m4a", ".mp3", ".flac", ".aac", ".ogg", ".opus"})
@@ -97,11 +97,14 @@ TEMPLATE = {
 OBJECT_KEYS: Dict[str, frozenset] = {
     "project": frozenset({"output", "frame", "clips", "transition", "silence", "brand", "captions",
                           "graphics", "overlays", "audio", "loudness", "fit", "export", "check", "chapters",
-                          "template"}),
+                          "audiogram", "template"}),
     "clips[]": frozenset({"src", "in", "out", "speed"}),
     "frame": frozenset({"aspect", "width", "height", "fps", "fit"}),
     "transition": frozenset({"type", "duration"}),
     "silence": frozenset({"threshold", "min_silence", "margin"}),
+    # 1.16: the picture an audio-only source gets before the rest of the chain can work on it
+    "audiogram": frozenset({"image", "image_fit", "style", "position", "vis_height", "opacity",
+                            "platform", "title", "color", "background", "width", "height", "fps"}),
     "captions": frozenset({"text", "srt", "ass", "font", "size", "color", "position", "margin",
                            "animate", "highlight_color", "outline", "karaoke", "bold", "box",
                            "lang", "offset", "max_lines", "min_duration"}),
@@ -202,9 +205,10 @@ def template_project(name: str, args) -> Dict[str, Any]:
         "$BRAND": os.path.abspath(args.brand) if args.brand else None,
         "$CHAPTERS": os.path.abspath(args.chapters) if args.chapters else None,
         "$TITLE": args.title,
+        "$IMAGE": os.path.abspath(args.image) if args.image else None,
     }
     for flag, path in (("--cues", args.cues), ("--srt", args.srt), ("--logo", args.logo),
-                       ("--brand", args.brand), ("--chapters", args.chapters)):
+                       ("--brand", args.brand), ("--chapters", args.chapters), ("--image", args.image)):
         if path and not os.path.isfile(path):
             die(f"{flag}: file not found: {path}")
     proj, _ = fill_template(tpl, values)
@@ -286,7 +290,7 @@ def render_pack(names: List[str], args) -> int:
         argv = [str(HERE / "render.py"), args.input, "--template", name, "-o", dest_out]
         for flag, value in (("--cues", args.cues), ("--srt", args.srt), ("--logo", args.logo),
                             ("--title", args.title), ("--brand", args.brand), ("--fit", args.fit),
-                            ("--chapters", args.chapters)):
+                            ("--chapters", args.chapters), ("--image", args.image)):
             if value:
                 argv += [flag, str(value)]
         info(f"→ pack: {name}")
@@ -355,7 +359,7 @@ def check_keys(obj: Any, schema: str, label: str) -> None:
 
 def validate_project(proj: Dict[str, Any]) -> None:
     check_keys(proj, "project", "project")
-    for name in ("frame", "transition", "silence", "captions", "audio", "loudness", "fit", "export", "check"):
+    for name in ("frame", "transition", "silence", "audiogram", "captions", "audio", "loudness", "fit", "export", "check"):
         check_keys(proj.get(name), name, name)
     check_keys((proj.get("audio") or {}).get("stems"), "audio.stems", "audio.stems")
     if isinstance(proj.get("chapters"), list):
@@ -508,6 +512,7 @@ def main() -> int:
     tpl.add_argument("--title", help="title text for the template's opening card / lower third")
     tpl.add_argument("--brand", help="brand.json the template's captions, graphics and overlays use")
     tpl.add_argument("--chapters", help="chapter file (podcast template)")
+    tpl.add_argument("--image", help="still image behind the visualisation (audiogram template); a local file, nothing is fetched")
     tpl.add_argument("--fit", choices=["crop", "pad", "blur"], help="override how the template reaches its aspect")
     tpl.add_argument("-o", "--output", help="output file (default: next to the input, <input>_<template>.mp4, "
                                             "or .m4a for an audio-only destination); for a list of templates "
@@ -544,7 +549,7 @@ def main() -> int:
     else:
         for flag, value in (("--cues", args.cues), ("--srt", args.srt), ("--logo", args.logo),
                             ("--title", args.title), ("--brand", args.brand), ("--chapters", args.chapters),
-                            ("--fit", args.fit), ("--write-project", args.write_project)):
+                            ("--image", args.image), ("--fit", args.fit), ("--write-project", args.write_project)):
             if value:
                 die(f"{flag} belongs to --template NAME INPUT; a project.json states it in the project itself")
         try:
@@ -645,6 +650,28 @@ def main() -> int:
         parts.append(part)
     stages_done.append("clips")
     current = parts[0]
+
+    # ---- audiogram: the picture an audio-only source needs before anything else can work on it
+    ag = proj.get("audiogram")
+    if ag:
+        if not ag.get("image") and not ag.get("background"):
+            die('audiogram: give an "image" (a local file) or a "background" colour -- this skill '
+                "never fetches a picture and never invents cover art", kind="input")
+        nxt = str(work / f"audiogram{mid}")
+        argv = [current, "-o", nxt]
+        for key, flag in (("image", "--image"), ("image_fit", "--image-fit"), ("style", "--style"),
+                          ("position", "--position"), ("vis_height", "--vis-height"),
+                          ("opacity", "--opacity"), ("platform", "--platform"), ("title", "--title"),
+                          ("color", "--color"), ("background", "--background"),
+                          ("width", "--width"), ("height", "--height"), ("fps", "--fps")):
+            if ag.get(key) is not None:
+                argv += [flag, str(ag[key])]
+        argv += brand_args
+        sh("waveform.py", *argv)
+        current = nxt
+        parts = [current]
+        stages_done.append("audiogram")
+
     if args.stop_after == "clips":
         emit(current, stages=stages_done)
         return 0

package/scripts/scenes.py

@@ -19,70 +19,12 @@ Examples:
 """
 import argparse
 import math
-import os
-import re
 import sys
 from typing import Dict, List, Tuple
 
-from _common import STATE, add_common, apply_common, default_font_file, die, emit, escape_filter_path, ffmpeg_base, info, print_json, probe, require_tool, run, run_analysis, decode_pcm_mono, rms_envelope
-
-SCORE_RE = re.compile(r"frame:(\d+)\s+pts:\d+\s+pts_time:([0-9.]+)")
-
-
-def detect_scenes(path: str, threshold: float, min_len: float, duration: float, ratio: float = 3.0) -> List[float]:
-    """Scene cuts = frames whose scdet score is above `threshold` AND stands out from its
-    neighbourhood (score > ratio x median of the surrounding +-12 frames). Sustained motion,
-    flashes and fast pans raise the score on many consecutive frames and are rejected;
-    a real cut is a one-frame spike. On real footage this roughly doubles precision at
-    equal recall compared with the raw scdet threshold."""
-    ffmpeg = require_tool("ffmpeg")
-    proc = run_analysis([ffmpeg, "-hide_banner", "-nostdin", "-i", path, "-an", "-vf",
-                         "scale=320:-2,scdet=threshold=0,metadata=print:file=-", "-f", "null", "-"])
-    # No `sc_pass=1` on scdet: on FFmpeg 5.x that option means "pass only the frames whose
-    # score exceeds the threshold", so every truly static frame (score exactly 0 -- a title
-    # card, colour bars) is dropped before metadata=print and the frame numbers are re-counted
-    # without them. The +-12-frame neighbourhood around a real cut then fills with the moving
-    # segment's scores instead of the still one's zeros, the cut fails the ratio test, and a
-    # 4 s smptebars scene made the cuts on both sides of it disappear (found by the 5.1.1 CI
-    # job, #146). 6.1+ passes every frame either way. Scores are still indexed by frame number
-    # and any frame the filter did not report counts as 0, so a build that drops frames again
-    # cannot shift the neighbourhood.
-    by_frame: Dict[int, Tuple[float, float]] = {}
-    cur = None
-    for line in proc.stdout.splitlines():
-        m = SCORE_RE.match(line)
-        if m:
-            cur = (int(m.group(1)), float(m.group(2)))
-            continue
-        if line.startswith("lavfi.scd.score=") and cur is not None:
-            try:
-                by_frame[cur[0]] = (cur[1], float(line.split("=", 1)[1]))
-            except ValueError:
-                pass
-    cuts = [0.0]
-    if not by_frame:
-        return cuts
-    n_frames = max(by_frame) + 1
-    times: List[float] = [by_frame[i][0] if i in by_frame else -1.0 for i in range(n_frames)]
-    scores: List[float] = [by_frame[i][1] if i in by_frame else 0.0 for i in range(n_frames)]
-    w = 12
-    for i, sc in enumerate(scores):
-        if sc < threshold:
-            continue
-        lo, hi = max(0, i - w), min(len(scores), i + w + 1)
-        neigh = sorted(scores[lo:i] + scores[i + 1:hi])
-        med = neigh[len(neigh) // 2] if neigh else 0.0
-        if sc < ratio * max(med, 0.5):
-            continue
-        # keep only the local maximum inside +-2 frames
-        if any(scores[j] > sc for j in range(max(0, i - 2), min(len(scores), i + 3)) if j != i):
-            continue
-        t = times[i]
-        if t - cuts[-1] >= min_len:
-            cuts.append(t)
-    if duration - cuts[-1] < min_len and len(cuts) > 1:
-        cuts.pop()
-    return cuts
+# `detect_scenes` moved into _common/probe.py in 1.16.0 (see silence.py); the body is unchanged.
+from _common import detect_scenes, STATE, add_common, apply_common, default_font_file, die, emit, escape_filter_path, ffmpeg_base, info, print_json, probe, run, decode_pcm_mono, rms_envelope
+
 
 
 def audio_envelope(path: str, step_s: float) -> List[float]:

package/scripts/silence.py

@@ -13,35 +13,13 @@ Examples:
 """
 import argparse
 import os
-import re
 import sys
 from typing import List, Tuple
 
-from _common import STATE, video_args, add_common, apply_common, audio_codec_for, cfr_args, default_output, die, emit, ffmpeg_base, info, is_audio_output, print_json, probe, require_tool, run, x264_args, X264_PRESETS, measured_level_dbfs, run_analysis, dry_run_input_pending, fmt_secs
+# `detect` moved into _common/probe.py in 1.16.0 so metadata.py --auto-chapters can measure the
+# same silences without importing this tool; the body is unchanged and the name still lives here.
+from _common import detect_silences as detect, STATE, video_args, add_common, apply_common, audio_codec_for, cfr_args, default_output, die, emit, ffmpeg_base, info, is_audio_output, print_json, probe, run, X264_PRESETS, measured_level_dbfs, fmt_secs
 
-SIL_RE = re.compile(r"silence_(start|end): ([0-9.]+)")
-
-
-def detect(path: str, threshold: float, min_silence: float) -> List[Tuple[float, float]]:
-    if dry_run_input_pending(path):
-        return []
-    ffmpeg = require_tool("ffmpeg")
-    cmd = [ffmpeg, "-hide_banner", "-nostdin", "-i", path, "-vn", "-af",
-           f"silencedetect=noise={threshold}dB:d={min_silence}", "-f", "null", "-"]
-    proc = run_analysis(cmd, check=False, record=True)
-    if proc.returncode != 0:
-        die(f"silencedetect failed:\n{proc.stderr.strip()[-800:]}", kind="ffmpeg")
-    silences: List[Tuple[float, float]] = []
-    start = None
-    for kind, val in SIL_RE.findall(proc.stderr):
-        if kind == "start":
-            start = float(val)
-        elif start is not None:
-            silences.append((start, float(val)))
-            start = None
-    if start is not None:  # silence runs to the end
-        silences.append((start, float("inf")))
-    return silences
 
 
 def keep_ranges(silences: List[Tuple[float, float]], duration: float, margin: float, min_keep: float) -> List[Tuple[float, float]]: