@topy-ai/maggie 0.8.10 → 0.8.12

package/bundled-tools/clis/maggie_image.py

@@ -0,0 +1,221 @@
+#!/usr/bin/env python3
+"""maggie_image - generate correct image-processing commands for marketing assets.
+
+A recipe generator distilled from ImageMagick, sharp, svgo, resvg, squoosh and
+imagemin (see references/image-recipes.md). Each subcommand prints the exact command
+(reviewable/loggable) and runs it with --run only when the tool is on PATH. Raster
+ops prefer ImageMagick (`magick` on IM7, else `convert`) since it is almost always
+present and covers nearly everything; vector ops use the dedicated tool (svgo, resvg)
+and are generate-only until it is installed. Web-delivery quality defaults follow
+sharp/squoosh (JPEG/WebP ~80, AVIF ~50); OG/social are cover-cropped, logos pad.
+
+Subcommands: resize, social, webp, avif, favicon, strip, compress, svgo, svg2png,
+montage, presets.
+"""
+import argparse
+import shlex
+import shutil
+import subprocess
+import sys
+
+# OG/social use cover-crop; name -> (W, H)
+SOCIAL = {"og": (1200, 630), "twitter": (1600, 900), "square": (1080, 1080),
+          "story": (1080, 1920), "reel": (1080, 1920), "landscape": (1920, 1080),
+          "linkedin": (1200, 627), "pinterest": (1000, 1500)}
+FAVICON_PNG = [16, 32, 48, 180, 192, 512]  # 180 = apple-touch
+
+
+def _im():
+    return ["magick"] if shutil.which("magick") else ["convert"]
+
+
+def _im_tool():
+    return _im()[0]
+
+
+def _montage():
+    return ["magick", "montage"] if shutil.which("magick") else ["montage"]
+
+
+def emit(args, run, tool):
+    print(" ".join(shlex.quote(a) for a in args))
+    if not run:
+        return 0
+    if not shutil.which(tool):
+        sys.stderr.write(f"{tool} not found on PATH; printed the command only.\n")
+        return 3
+    return subprocess.run(args).returncode
+
+
+def _resize_ops(w, h, mode, pad):
+    if mode == "cover":
+        return ["-resize", f"{w}x{h}^", "-gravity", "center", "-extent", f"{w}x{h}"]
+    if mode == "contain":
+        return ["-resize", f"{w}x{h}", "-background", pad, "-gravity", "center", "-extent", f"{w}x{h}"]
+    if mode == "shrink":
+        return ["-resize", f"{w}x{h}>"]
+    return ["-resize", f"{w}x{h}"]  # fit
+
+
+def c_resize(a):
+    w, h = a.size.lower().split("x")
+    cmd = _im() + [a.input, "-strip"] + _resize_ops(w, h, a.mode, a.pad) + \
+        ["-quality", str(a.quality), a.output]
+    return emit(cmd, a.run, _im_tool())
+
+
+def c_social(a):
+    w, h = SOCIAL[a.preset]
+    cmd = _im() + [a.input, "-strip"] + _resize_ops(w, h, a.mode, a.pad) + \
+        ["-quality", str(a.quality), a.output]
+    return emit(cmd, a.run, _im_tool())
+
+
+def c_webp(a):
+    if shutil.which("cwebp") and not a.force_im:
+        return emit(["cwebp", "-q", str(a.quality), "-m", "6", a.input, "-o", a.output], a.run, "cwebp")
+    cmd = _im() + [a.input, "-strip", "-quality", str(a.quality), "-define", "webp:method=6", a.output]
+    return emit(cmd, a.run, _im_tool())
+
+
+def c_avif(a):
+    if shutil.which("avifenc") and not a.force_im:
+        return emit(["avifenc", "-s", "6", "--min", "20", "--max", "40", a.input, a.output], a.run, "avifenc")
+    cmd = _im() + [a.input, "-strip", "-quality", str(a.quality), a.output]
+    return emit(cmd, a.run, _im_tool())
+
+
+def c_favicon(a):
+    import os
+    os.makedirs(a.out_dir, exist_ok=True)
+    rc = 0
+    ico = os.path.join(a.out_dir, "favicon.ico")
+    rc |= emit(_im() + [a.input, "-define", "icon:auto-resize=64,48,32,16", ico], a.run, _im_tool())
+    for s in FAVICON_PNG:
+        name = "apple-touch-icon.png" if s == 180 else f"favicon-{s}.png"
+        out = os.path.join(a.out_dir, name)
+        rc |= emit(_im() + [a.input, "-strip", "-resize", f"{s}x{s}", out], a.run, _im_tool())
+    return rc
+
+
+def c_strip(a):
+    return emit(_im() + [a.input, "-strip", a.output], a.run, _im_tool())
+
+
+def c_compress(a):
+    out = a.output.lower()
+    if out.endswith((".jpg", ".jpeg")):
+        cmd = _im() + [a.input, "-strip", "-interlace", "Plane", "-quality", str(a.quality), a.output]
+    else:  # png: palette-reduce + max zlib (pngquant is the better alt)
+        if shutil.which("pngquant") and not a.force_im:
+            return emit(["pngquant", "--quality", "60-82", "--strip", "--force",
+                         "--output", a.output, a.input], a.run, "pngquant")
+        cmd = _im() + [a.input, "-strip", "-colors", "256",
+                       "-define", "png:compression-level=9", a.output]
+    return emit(cmd, a.run, _im_tool())
+
+
+def c_svgo(a):
+    args = ["svgo", "--multipass"] if a.multipass else ["svgo"]
+    args += ["-i", a.input, "-o", a.output]
+    print("# svgo keeps viewBox and title by default (responsive + accessible).")
+    if not shutil.which("svgo"):
+        print("# svgo not installed (npm i -g svgo). Do NOT rasterize an SVG as a substitute.")
+    return emit(args, a.run, "svgo")
+
+
+def c_svg2png(a):
+    if shutil.which("resvg") and not a.force_im:
+        args = ["resvg"]
+        if a.width:
+            args += ["-w", str(a.width)]
+        if a.background:
+            args += ["--background", a.background]
+        args += [a.input, a.output]
+        return emit(args, a.run, "resvg")
+    if shutil.which("rsvg-convert") and not a.force_im:
+        args = ["rsvg-convert"]
+        if a.width:
+            args += ["-w", str(a.width)]
+        return emit(args + [a.input, "-o", a.output], a.run, "rsvg-convert")
+    # ImageMagick fallback: drive size via -density (it rasterizes at DPI); lower fidelity
+    dens = 384
+    bg = ["-background", a.background] if a.background else ["-background", "none"]
+    size = ["-resize", f"{a.width}x"] if a.width else []
+    print("# ImageMagick SVG fallback is lower fidelity; install resvg for correct rendering.")
+    return emit(_im() + bg + ["-density", str(dens), a.input] + size + [a.output], a.run, _im_tool())
+
+
+def c_montage(a):
+    cmd = _montage() + list(a.inputs) + ["-tile", a.tile, "-geometry",
+          f"{a.cell}+{a.pad}+{a.pad}", "-background", a.background, a.output]
+    return emit(cmd, a.run, _montage()[0])
+
+
+def c_presets(a):
+    print("Social/OG size presets (use with `social --preset <name>`; cover-cropped):")
+    for name, (w, h) in SOCIAL.items():
+        print(f"  {name:<10} {w}x{h}")
+    print("\nDefaults: strip metadata; JPEG/WebP quality 80, AVIF 50; favicon .ico "
+          "(64/48/32/16) + PNG set (16/32/48/180-apple/192/512).")
+    print(f"ImageMagick binary detected: {_im_tool()}")
+    return 0
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog="maggie_image", description=__doc__,
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--run", action="store_true", help="execute (needs the tool on PATH); default prints only")
+    ap.add_argument("--force-im", action="store_true", dest="force_im",
+                    help="force the ImageMagick path even if a dedicated tool exists")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    def io(p, out=True):
+        p.add_argument("--input", required=True)
+        if out:
+            p.add_argument("--output", required=True)
+
+    r = sub.add_parser("resize", help="resize+fit to WxH")
+    io(r); r.add_argument("--size", required=True, help="WxH, e.g. 1200x630")
+    r.add_argument("--mode", choices=["cover", "contain", "fit", "shrink"], default="cover")
+    r.add_argument("--pad", default="#ffffff"); r.add_argument("--quality", type=int, default=82)
+    r.set_defaults(fn=c_resize)
+
+    s = sub.add_parser("social", help="resize to a channel/OG preset")
+    io(s); s.add_argument("--preset", choices=list(SOCIAL), required=True)
+    s.add_argument("--mode", choices=["cover", "contain", "fit", "shrink"], default="cover")
+    s.add_argument("--pad", default="#ffffff"); s.add_argument("--quality", type=int, default=82)
+    s.set_defaults(fn=c_social)
+
+    w = sub.add_parser("webp", help="encode WebP"); io(w)
+    w.add_argument("--quality", type=int, default=80); w.set_defaults(fn=c_webp)
+    av = sub.add_parser("avif", help="encode AVIF"); io(av)
+    av.add_argument("--quality", type=int, default=50); av.set_defaults(fn=c_avif)
+
+    fv = sub.add_parser("favicon", help="favicon .ico + PNG set")
+    fv.add_argument("--input", required=True); fv.add_argument("--out-dir", dest="out_dir", required=True)
+    fv.set_defaults(fn=c_favicon)
+
+    st = sub.add_parser("strip", help="strip metadata (EXIF/GPS/ICC)"); io(st); st.set_defaults(fn=c_strip)
+    co = sub.add_parser("compress", help="compress JPEG/PNG"); io(co)
+    co.add_argument("--quality", type=int, default=82); co.set_defaults(fn=c_compress)
+
+    so = sub.add_parser("svgo", help="optimize an SVG (svgo)"); io(so)
+    so.add_argument("--multipass", action="store_true"); so.set_defaults(fn=c_svgo)
+    sp = sub.add_parser("svg2png", help="render SVG -> PNG (resvg)"); io(sp)
+    sp.add_argument("--width", type=int); sp.add_argument("--background"); sp.set_defaults(fn=c_svg2png)
+
+    mo = sub.add_parser("montage", help="contact sheet / grid")
+    mo.add_argument("--inputs", nargs="+", required=True); mo.add_argument("--output", required=True)
+    mo.add_argument("--tile", default="3x"); mo.add_argument("--cell", default="400x400")
+    mo.add_argument("--pad", type=int, default=10); mo.add_argument("--background", default="#ffffff")
+    mo.set_defaults(fn=c_montage)
+
+    sub.add_parser("presets", help="list size presets").set_defaults(fn=c_presets)
+
+    a = ap.parse_args(argv)
+    raise SystemExit(a.fn(a))
+
+
+if __name__ == "__main__":
+    main()

package/bundled-tools/clis/maggie_video.py

@@ -9,7 +9,7 @@ LGPL/GPL use); it links no libav and vendors no GPL code. Output is always force
 to a web-safe, platform-correct profile.
 
 Subcommands: encode, gif, trim, concat, social, overlay, subtitle, loudnorm,
-thumb, compile, captions, presets.
+thumb, compile, autocut, captions, presets.
 """
 import argparse
 import json
@@ -161,28 +161,36 @@ def _clip_dur(clip, default):
     return float(default)
 
 
-def _kenburns(w, h, fps, dur, direction="in", amount=0.12):
-    """A ken-burns (slow zoom) filter chain for an image clip, fit to WxH.
-    Prescales with headroom so the zoom stays sharp; animates over the clip."""
+def _kenburns(w, h, fps, dur, direction="in", amount=0.12, normalize_fps=False):
+    """A ken-burns (slow zoom) filter chain, fit to WxH. Prescales with headroom so
+    the zoom stays sharp and animates over the clip (d=1 keeps it smooth on video
+    too). normalize_fps prepends an fps filter so a video clip's input frame count
+    matches dur*fps (image inputs are already pinned via -framerate)."""
     bw, bh = int(w * 1.6), int(h * 1.6)
     n = max(1, round(dur * fps))
     if direction == "out":
         z = f"(1+{amount})-{amount}*in/{n}"
     else:
         z = f"1+{amount}*in/{n}"
-    return (f"scale={bw}:{bh}:force_original_aspect_ratio=increase,crop={bw}:{bh},"
+    lead = f"fps={fps}," if normalize_fps else ""
+    return (f"{lead}scale={bw}:{bh}:force_original_aspect_ratio=increase,crop={bw}:{bh},"
             f"zoompan=z='{z}':d=1:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)':"
             f"s={w}x{h}:fps={fps},setsar=1,format=yuv420p")
 
 
-def _kf_alpha_expr(keyframes, offset):
-    """A piecewise-linear ffmpeg expression (in t, seconds) for an opacity track."""
-    pts = [(offset + float(k["t"]), float(k["v"])) for k in keyframes]
-    expr = f"{pts[-1][1]}"
-    for (ta, va), (tb, vb) in reversed(list(zip(pts, pts[1:]))):
+def _kf_expr(points):
+    """A piecewise-linear ffmpeg expression in t (seconds) from (t_abs, value) points.
+    Holds the first/last value outside the keyframed range."""
+    expr = f"{points[-1][1]}"
+    for (ta, va), (tb, vb) in reversed(list(zip(points, points[1:]))):
         seg = f"({va}+({vb}-{va})*(t-{ta})/({tb - ta}))"
         expr = f"if(lt(t,{tb}),{seg},{expr})"
-    return f"if(lt(t,{pts[0][0]}),{pts[0][1]},{expr})"
+    return f"if(lt(t,{points[0][0]}),{points[0][1]},{expr})"
+
+
+def _kf_alpha_expr(keyframes, offset):
+    """Opacity (alpha) expression in t from keyframes relative to the clip offset."""
+    return _kf_expr([(offset + float(k["t"]), float(k["v"])) for k in keyframes])
 
 
 def _opacity_kfs(clip):
@@ -192,6 +200,29 @@ def _opacity_kfs(clip):
     return None
 
 
+def _move_exprs(clip, offset, W, H, base_x, base_y):
+    """x/y ffmpeg expressions (in t) for a move/slide effect, else (None, None).
+    Effect: {type: move|slide, x:[{t,v}...], y:[{t,v}...]} with v as %/px/0..1."""
+    for e in clip.get("effects", []) or []:
+        if e.get("type") in ("move", "slide", "position"):
+            xe = ye = None
+            if e.get("x"):
+                xe = _kf_expr([(offset + float(k["t"]), _px(k["v"], W)) for k in e["x"]])
+            if e.get("y"):
+                ye = _kf_expr([(offset + float(k["t"]), _px(k["v"], H)) for k in e["y"]])
+            return (xe if xe is not None else base_x, ye if ye is not None else base_y)
+    return (None, None)
+
+
+def _overlay_zoom_cfg(clip):
+    """direction, amount for an image-overlay zoom effect, else None."""
+    for e in clip.get("effects", []) or []:
+        if e.get("type") == "zoom" and e.get("keyframes"):
+            vs = [float(k["v"]) for k in e["keyframes"]]
+            return ("out" if vs[-1] < vs[0] else "in"), (abs(vs[-1] - vs[0]) or 0.15)
+    return None
+
+
 def _kenburns_cfg(clip):
     kb = clip.get("kenBurns")
     if isinstance(kb, dict):
@@ -204,6 +235,13 @@ def _kenburns_cfg(clip):
     return None
 
 
+def _color(c):
+    """Normalize a CSS-ish color for ffmpeg: expand #abc -> #aabbcc; pass the rest."""
+    if isinstance(c, str) and c.startswith("#") and len(c) == 4:
+        return "#" + "".join(ch * 2 for ch in c[1:])
+    return c
+
+
 def _px(val, total):
     """Resolve '80%' / 0.8 / 120 against a total dimension to an int pixel value."""
     if isinstance(val, str) and val.strip().endswith("%"):
@@ -260,9 +298,11 @@ def c_compile(a):
             idx = add_input([], asset.get("src", ""))
             s = clip.get("start", 0)
             trim = f"trim=start={s}:end={s + dur},setpts=PTS-STARTPTS,"
-            filters.append(f"[{idx}:v]{trim}{_fit(W, H, fit, FPS)}[v{i}]")
             if kb:
-                notes.append(f"clip {i}: ken-burns on a video clip not compiled (image clips only); shown as plain fit")
+                chain = _kenburns(W, H, FPS, dur, kb[0], kb[1], normalize_fps=True)
+            else:
+                chain = _fit(W, H, fit, FPS)
+            filters.append(f"[{idx}:v]{trim}{chain}[v{i}]")
         else:
             notes.append(f"clip {i}: unsupported type (need asset of type image/video)")
             continue
@@ -300,19 +340,19 @@ def c_compile(a):
             dur = _clip_dur(clip, def_dur)
             en = f"enable='between(t,{pos},{pos + dur})'"
             op_kfs = _opacity_kfs(clip)
-            if clip.get("effects") and not op_kfs:
-                notes.append("overlay effect other than opacity (e.g. zoom) not compiled on this overlay")
             ctype = clip.get("type")
             if ctype == "text":
                 st = clip.get("style", {})
                 rect = clip.get("rect", {})
-                x = _px(rect.get("x", "10%"), W)
-                y = _px(rect.get("y", "80%"), H)
+                bx, by = _px(rect.get("x", "10%"), W), _px(rect.get("y", "80%"), H)
+                mx, my = _move_exprs(clip, pos, W, H, bx, by)
+                xv = f"'{mx}'" if mx is not None else f"{bx}"
+                yv = f"'{my}'" if my is not None else f"{by}"
                 txt = str(clip.get("text", "")).replace(":", r"\:").replace("'", "’")
-                box = f":box=1:boxcolor={st['box']}:boxborderw=12" if st.get("box") else ""
+                box = f":box=1:boxcolor={_color(st['box'])}:boxborderw=12" if st.get("box") else ""
                 alpha = f":alpha='{_kf_alpha_expr(op_kfs, pos)}'" if op_kfs else ""
-                dt = (f"drawtext=text='{txt}':x={x}:y={y}:fontsize={st.get('size',48)}:"
-                      f"fontcolor={st.get('color','#FFFFFF')}{box}{alpha}:{en}")
+                dt = (f"drawtext=text='{txt}':x={xv}:y={yv}:fontsize={st.get('size',48)}:"
+                      f"fontcolor={_color(st.get('color','#FFFFFF'))}{box}{alpha}:{en}")
                 filters.append(f"{cur}{dt}{nxt}")
             elif ctype == "captions":
                 src = clip.get("src", "")
@@ -321,46 +361,75 @@ def c_compile(a):
                 asset = assets[clip["asset"]]
                 rect = clip.get("rect", {})
                 ow = _px(rect.get("w", "15%"), W)
-                idx = add_input(["-loop", "1"], asset.get("src", ""))
-                filters.append(f"[{idx}:v]scale={ow}:-1[ov{step}]")
-                x = _px(rect.get("x", "80%"), W)
-                y = _px(rect.get("y", "5%"), H)
-                filters.append(f"{cur}[ov{step}]overlay={x}:{y}:{en}:eof_action=pass{nxt}")
+                bx, by = _px(rect.get("x", "80%"), W), _px(rect.get("y", "5%"), H)
+                zoom = _overlay_zoom_cfg(clip)
+                if zoom and rect.get("h") not in (None, "auto"):
+                    oh = _px(rect.get("h"), H)
+                    idx = add_input(["-loop", "1", "-framerate", f"{FPS}", "-t", f"{dur}"],
+                                    asset.get("src", ""))
+                    filters.append(f"[{idx}:v]{_kenburns(ow, oh, FPS, dur, zoom[0], zoom[1])}[ov{step}]")
+                else:
+                    if zoom:
+                        notes.append("image-overlay zoom needs rect w+h; placed at a static size "
+                                     "(use a programmatic engine for free-form overlay scaling)")
+                    idx = add_input(["-loop", "1"], asset.get("src", ""))
+                    filters.append(f"[{idx}:v]scale={ow}:-1[ov{step}]")
+                mx, my = _move_exprs(clip, pos, W, H, bx, by)
+                xv = f"x='{mx}'" if mx is not None else f"x={bx}"
+                yv = f"y='{my}'" if my is not None else f"y={by}"
+                filters.append(f"{cur}[ov{step}]overlay={xv}:{yv}:{en}:eof_action=pass{nxt}")
             else:
                 notes.append(f"overlay clip of type {ctype!r} not compiled")
                 continue
+            if clip.get("effects") and not (op_kfs or _move_exprs(clip, pos, W, H, 0, 0) != (None, None) or _overlay_zoom_cfg(clip)):
+                notes.append("an overlay effect was not recognised (supported: opacity, move/slide, zoom on sized images)")
             cur = nxt
             step += 1
     filters.append(f"{cur}format=yuv420p[vout]")
 
-    # --- audio: mix audio[] tracks with gain + optional loudnorm ---
-    aud = spec.get("audio", [])
-    alabels = []
+    # --- audio: mix audio[] tracks with gain, sidechain ducking, loudnorm ---
+    aud = [t for t in spec.get("audio", []) if assets.get(t.get("asset"), {}).get("src")]
+    # which assets are used as a ducking key (the VO under which music ducks)
+    keys = {t["ducking"]["under"] for t in aud if t.get("ducking") and t["ducking"].get("under")}
+    asset_track = {}
+    raw = {}   # track index -> its raw [araw{i}] label
     for i, tr in enumerate(aud):
-        asset = assets.get(tr.get("asset"), {})
-        if not asset.get("src"):
-            continue
-        idx = add_input([], asset["src"])
-        chain = f"[{idx}:a]"
+        idx = add_input([], assets[tr["asset"]]["src"])
+        parts = []
         pos = float(tr.get("position", 0))
         if pos > 0:
             ms = int(pos * 1000)
-            chain += f"adelay={ms}|{ms},"
-        gain = tr.get("gain", 0)
-        if gain:
-            chain += f"volume={gain}dB,"
-        if tr.get("ducking"):
-            notes.append("audio ducking (sidechain) not compiled; set music gain lower instead")
-        chain = chain.rstrip(",") + f"[a{i}]"
-        filters.append(chain)
-        alabels.append(f"[a{i}]")
+            parts.append(f"adelay={ms}|{ms}")
+        if tr.get("gain"):
+            parts.append(f"volume={tr['gain']}dB")
+        chain = ",".join(parts) if parts else "anull"
+        filters.append(f"[{idx}:a]{chain}[araw{i}]")
+        raw[i] = f"[araw{i}]"
+        asset_track.setdefault(tr["asset"], i)
+    # split any track that serves as a ducking key into a mix copy and a key copy
+    mix = dict(raw)
+    keyl = {}
+    for aid in keys:
+        j = asset_track.get(aid)
+        if j is None:
+            continue
+        filters.append(f"{raw[j]}asplit=2[amx{j}][akey{j}]")
+        mix[j], keyl[aid] = f"[amx{j}]", f"[akey{j}]"
+    # apply sidechain ducking: music under its key VO
+    for i, tr in enumerate(aud):
+        d = tr.get("ducking")
+        if d and keyl.get(d.get("under")):
+            filters.append(f"{mix[i]}{keyl[d['under']]}sidechaincompress="
+                           f"threshold=0.03:ratio=8:attack=20:release=300[aduck{i}]")
+            mix[i] = f"[aduck{i}]"
+            notes.append(f"ducking: '{tr['asset']}' compressed under '{d['under']}' (sidechain)")
+    alabels = [mix[i] for i in range(len(aud))]
     have_audio = bool(alabels)
     if have_audio:
         if len(alabels) == 1:
             filters.append(f"{alabels[0]}aresample=async=1[amix]")
         else:
-            filters.append(f"{''.join(alabels)}amix=inputs={len(alabels)}:duration=longest[amix]")
-        norm = next((t for t in aud if isinstance(t, dict)), {})  # master normalize lives on audio? use output
+            filters.append(f"{''.join(alabels)}amix=inputs={len(alabels)}:duration=longest:normalize=0[amix]")
         tgt = (spec.get("audio_normalize") or {}).get("I", -14)
         filters.append(f"[amix]loudnorm=I={tgt}:TP=-1.5:LRA=11[aout]")
 
@@ -374,6 +443,61 @@ def c_compile(a):
     return emit(cmd, a.run)
 
 
+def c_autocut(a):
+    """Remove silent gaps automatically (auto-editor's idea, via ffmpeg
+    silencedetect). Prints the detect command; with --run it detects, computes the
+    kept ranges (padded by --margin), and renders the trimmed video+audio."""
+    import re
+    detect = ["ffmpeg", "-hide_banner", "-i", a.input, "-af",
+              f"silencedetect=noise={a.noise}:d={a.min_silence}", "-f", "null", "-"]
+    print("# step 1 (detect): " + " ".join(shlex.quote(x) for x in detect))
+    print("# step 2: kept ranges = complement of detected silence, padded by --margin, then trim+concat.")
+    if not a.run:
+        print("# re-run with --run to detect and render the cut (needs ffmpeg + ffprobe).")
+        return 0
+    if not (shutil.which("ffmpeg") and shutil.which("ffprobe")):
+        sys.stderr.write("autocut --run needs ffmpeg + ffprobe on PATH.\n")
+        return 3
+    total = float(subprocess.run(["ffprobe", "-v", "error", "-show_entries",
+                 "format=duration", "-of", "csv=p=0", a.input],
+                 capture_output=True, text=True).stdout.strip() or 0)
+    err = subprocess.run(detect, capture_output=True, text=True).stderr
+    starts = [float(x) for x in re.findall(r"silence_start: ([0-9.]+)", err)]
+    ends = [float(x) for x in re.findall(r"silence_end: ([0-9.]+)", err)]
+    if len(ends) < len(starts):     # trailing silence runs to the end
+        ends.append(total)
+    sil = list(zip(starts, ends))
+    keep, cur = [], 0.0
+    for s, e in sil:
+        if s > cur:
+            keep.append([cur, s])
+        cur = max(cur, e)
+    if cur < total:
+        keep.append([cur, total])
+    m = a.margin
+    padded = [[max(0.0, s - m), min(total, e + m)] for s, e in keep]
+    merged = []
+    for seg in padded:
+        if merged and seg[0] <= merged[-1][1]:
+            merged[-1][1] = max(merged[-1][1], seg[1])
+        else:
+            merged.append(seg)
+    print(f"# detected {len(sil)} silence gap(s); keeping {len(merged)} segment(s), "
+          f"{round(sum(e - s for s, e in merged), 2)}s of {round(total, 2)}s")
+    if not merged:
+        sys.stderr.write("autocut: everything was silence; nothing to keep.\n")
+        return 1
+    parts, labels = [], []
+    for i, (s, e) in enumerate(merged):
+        parts.append(f"[0:v]trim=start={s}:end={e},setpts=PTS-STARTPTS[v{i}]")
+        parts.append(f"[0:a]atrim=start={s}:end={e},asetpts=PTS-STARTPTS[a{i}]")
+        labels.append(f"[v{i}][a{i}]")
+    fc = ";".join(parts) + f";{''.join(labels)}concat=n={len(merged)}:v=1:a=1[v][a]"
+    cmd = PREFIX + ["-i", a.input, "-filter_complex", fc, "-map", "[v]", "-map", "[a]"] + \
+        MP4_OUT + ["-c:a", "aac", "-b:a", "128k", a.output]
+    return emit(cmd, True)
+
+
 def c_captions(a):
     """Transcribe speech to an SRT with a local, offline engine (no paid API).
     Pairs with `subtitle` (burn in) and `compile` (a captions overlay)."""
@@ -470,6 +594,14 @@ def main(argv=None):
     cp.add_argument("--output", help="override the output path from the spec")
     cp.set_defaults(fn=c_compile)
 
+    ac = sub.add_parser("autocut", help="remove silent gaps automatically (silencedetect)")
+    ac.add_argument("--input", required=True); ac.add_argument("--output", required=True)
+    ac.add_argument("--noise", default="-30dB", help="silence threshold, e.g. -30dB")
+    ac.add_argument("--min-silence", dest="min_silence", type=float, default=0.5,
+                    help="minimum silence length to cut (s)")
+    ac.add_argument("--margin", type=float, default=0.1, help="padding kept around speech (s)")
+    ac.set_defaults(fn=c_autocut)
+
     ca = sub.add_parser("captions", help="transcribe speech to SRT (local whisper)")
     ca.add_argument("--input", required=True); ca.add_argument("--output", required=True, help="target .srt")
     ca.add_argument("--engine", choices=["whisper", "whispercpp", "whisperx"], default="whisper")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topy-ai/maggie",
-  "version": "0.8.10",
+  "version": "0.8.12",
   "description": "Install and manage Maggie Skills for AI coding agents",
   "license": "MIT",
   "type": "module",

package/references/captions-transcription.md

@@ -0,0 +1,41 @@
+# Captions and transcription
+
+Local, offline speech-to-text for video captions and transcripts, used by
+`maggie-video`'s `captions` subcommand. All engines run on the user's machine - **no
+paid API** - so transcription has no per-minute cost, only local CPU/GPU time.
+Distilled from the reference library's R-category projects.
+
+## Engines
+
+| Engine | What / how | License | Reach for it when |
+|---|---|---|---|
+| openai-whisper | The reference Python CLI: `whisper IN --model base --output_format srt --output_dir DIR` | MIT | the default; simplest install (`pip install openai-whisper`) |
+| whisper.cpp | C/C++ port, fast on CPU, GGML models: `whisper-cli -m model.bin -f IN -osrt -of OUTBASE` | MIT | no GPU / fastest CPU / embedding in a pipeline |
+| whisperX | whisper + forced alignment for **word-level timestamps** and diarization: `whisperx IN --model large-v3 --output_format srt --output_dir DIR` | BSD-4 | word-accurate caption timing or speaker labels |
+
+Model size trades speed for accuracy: `tiny` / `base` (fast, rough) -> `small` /
+`medium` -> `large-v3` (slow, best). Use `--lang` to skip auto-detect when known.
+
+## Workflow (voiceover -> captions -> on-screen)
+
+1. **Transcribe** the voiceover or the video's audio to SRT with a local engine
+   (`maggie_video.py captions --input vo.mp3 --output vo.srt --engine whisper
+   --model base`). A larger model is slower but more accurate.
+2. **Review** the SRT - never ship an unreviewed transcript; whisper mishears names,
+   numbers, and brand terms. A human edits it.
+3. **Put it on screen**, one of:
+   - burn in (`maggie_video.py subtitle --input video.mp4 --srt vo.srt --output out.mp4`),
+   - soft-mux a toggleable track (`subtitle --soft`), or
+   - a `captions` layer in a `maggie_video.py compile` timeline (see
+     [video timeline model](video-timeline-model.md)).
+
+## Rules
+
+- Captions lift watch time and serve sound-off viewing - caption every social video.
+- **Never fabricate a transcript**; generate it from the real audio and have a human
+  review before publishing (accuracy, names, and brand terms).
+- Local/offline: no audio leaves the machine, no paid API. If a hosted transcription
+  API is ever wired in instead, the global spend-first rule applies - state the cost.
+- Keep caption text inside the safe area (see `maggie-video` channel presets).
+
+See `maggie-video` for the subcommands and the burn-in / soft-mux / compile options.

package/references/ffmpeg-recipes.md

@@ -103,9 +103,13 @@ ffmpeg -y -i IN -vf "thumbnail,scale=1280:-1" -frames:v 1 OUT.jpg  # most repres
 
 ```bash
 ffmpeg -i IN -af silencedetect=noise=-30dB:d=0.3 -f null -   # detect ranges
-# then build a select/concat of the kept ranges (pad each ~0.2s)
+# then build a trim+concat of the kept ranges (pad each ~0.1s)
 ```
 
+`maggie_video.py autocut --input talk.mp4 --output tight.mp4 --run` does both:
+detects the silence with `silencedetect`, computes the kept ranges padded by
+`--margin`, and renders the trimmed video+audio.
+
 ## Transitions (between two clips)
 
 `xfade=transition=fade:duration=0.5:offset=5.0` for video and `acrossfade=d=0.5`