@topy-ai/maggie 0.8.6 → 0.8.8

package/bundled-skills/maggie-video/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: maggie-video
+description: Produce and process marketing video - render a composition to MP4/GIF/WebM, assemble clips/images/text/captions/audio on a timeline, cut to channel aspects (reel/square/youtube), burn in captions, normalize loudness, watermark, transcode, and make social cuts. Engine-neutral over the renderer (ffmpeg for assembly/transcode, a programmatic engine for code-drawn animation). Use when the user wants to make, edit, cut, caption, resize, or export a video for marketing.
+metadata:
+  version: 0.1.0
+---
+
+# Maggie Video
+
+The video production lane: turn footage, images, text, captions and audio into a
+finished marketing video, and process existing video (cut, caption, resize,
+transcode, watermark, normalize). It is **engine-neutral** - the ffmpeg binary does
+assembly and transcode; a programmatic engine does code-drawn animation; it never
+links a GPL library or vendors GPL code.
+
+This complements [`maggie-design-motion`](../maggie-design-motion/SKILL.md), which
+animates a *static design* into a showcase and already implements the deterministic
+render-then-encode core (its Part C). `maggie-video` is broader: real footage,
+clip assembly, captions, platform cuts, and transcode. Finished videos publish
+through [`maggie-social-share`](../maggie-social-share/SKILL.md).
+
+Follow the [Maggie Memory Hook](../../references/memory-hook.md) at invocation and
+completion.
+
+## When to use
+
+- Cut, caption, resize, watermark, transcode, or normalize an existing video.
+- Assemble clips/images/text/VO/music into a video from a declarative spec.
+- Produce a data-driven or code-drawn animation as video (charts, kinetic type).
+- Make platform-correct social cuts (9:16 reel, 1:1 feed, 16:9 YouTube).
+
+## Pick the route
+
+- **Assembly / transcode / captions / resize of real footage** → the **ffmpeg
+  layer** directly. Every command is in [ffmpeg recipes](../../references/ffmpeg-recipes.md)
+  and generated by the CLI below.
+- **Declarative multi-clip composition** (clips + overlays + transitions + audio) →
+  author the [timeline model](../../references/video-timeline-model.md) JSON and
+  compile it to one ffmpeg `filter_complex` (or, for higher fidelity, emit MLT XML
+  and render with `melt` as an optional external GPL tool behind an adapter).
+- **Code-drawn animation** (kinetic type, charts, N data-driven variants) →
+  [programmatic video](../../references/programmatic-video.md): use **Revideo**
+  (MIT, headless, parameterized) by default; **CCapture** for an existing canvas
+  loop; **Remotion only as an option the end user licenses** (its license requires
+  a paid Company License for for-profit orgs over 3 employees - no hard dependency).
+- **Animating an existing rendered page/design** → stay in `maggie-design-motion`
+  Part C; do not reinvent it here.
+
+## The ffmpeg CLI
+
+`maggie_video.py` generates the correct ffmpeg command (printed, so it is reviewable
+and loggable) and runs it with `--run` when `ffmpeg` is on PATH:
+
+```bash
+maggie tool maggie_video.py social --input in.mp4 --output reel.mp4 --aspect reel        # 9:16, pad
+maggie tool maggie_video.py social --input in.mp4 --output feed.mp4 --aspect square --mode crop
+maggie tool maggie_video.py gif --input in.mp4 --output out.gif --fps 15 --width 480
+maggie tool maggie_video.py subtitle --input in.mp4 --srt vo.srt --output sub.mp4        # burn in
+maggie tool maggie_video.py loudnorm --input in.mp4 --output norm.mp4 --target -14       # social loudness
+maggie tool maggie_video.py overlay --input in.mp4 --logo logo.png --output branded.mp4
+maggie tool maggie_video.py trim --input in.mp4 --output cut.mp4 --start 5 --duration 10
+maggie tool maggie_video.py concat --inputs a.mp4 b.mp4 --output all.mp4 --reencode
+maggie tool maggie_video.py thumb --input in.mp4 --output poster.jpg --at 00:00:03
+maggie tool maggie_video.py --run encode --input in.mov --output out.mp4                 # actually runs
+maggie tool maggie_video.py presets
+```
+
+Subcommands: `encode` (web-safe MP4 / VP9 WebM), `gif`, `trim`, `concat`, `social`,
+`overlay`, `subtitle` (burn or soft-mux), `loudnorm`, `thumb`, `presets`.
+
+## Channel presets and safe areas
+
+- **9:16** (1080x1920) - Reels / Shorts / TikTok / Stories, <= 60s for feeds.
+- **1:1** (1080x1080) - feed posts.
+- **16:9** (1920x1080) - YouTube / landscape.
+- Keep captions and the CTA inside a safe area (roughly 10% margin top/bottom, more
+  at the bottom for platform UI). Logo in a fixed corner (see `overlay`). Default
+  loudness **-14 LUFS**. Prefer **crop (fill)** for full-bleed footage, **pad
+  (letterbox)** when the whole frame must be visible.
+
+## Output profile (shared with maggie-design-motion)
+
+H.264 high / `yuv420p` / `+faststart` / AAC 128k, even dimensions; GIF via
+`palettegen`+`paletteuse` (lanczos). Always force `-pix_fmt yuv420p` and `setsar=1`.
+
+## Quality bar
+
+- Output plays everywhere (yuv420p, faststart, even dimensions); aspect matches the
+  target channel with no distortion.
+- Captions are inside the safe area and readable; loudness normalized to target.
+- Every ffmpeg command is printed/logged before (or instead of) running.
+- No GPL library linked or vendored; ffmpeg/melt invoked at arm's length.
+
+## Guardrails
+
+- Rendering is a **local CPU/GPU/time cost**, not a paid API; flag long renders.
+  If any **hosted or LLM video generation** is wired in (e.g. a Q-category model),
+  the global BYOK rule (OpenRouter `provider.order` + `allow_fallbacks:false` +
+  explicit `max_tokens`) and the spend-first rule apply - state cost first.
+- Never claim a render ran unless `--run` executed and produced the file.
+- Licensing: adopt ideas/shape, not GPL code; invoke the `ffmpeg` binary (and
+  optionally `melt`) rather than linking libav. **Remotion** is reference-only (not
+  a free license for a commercial product).
+- Do not fabricate captions/transcripts; generate them from the real audio (see
+  the R-category caption tools, e.g. whisper) and let a human review.
+- Publishing a video is a separate approved step via `maggie-social-share`.
+
+## Related skills
+
+- `maggie-design-motion` - animate a static design into a showcase (shares the
+  render-then-encode core).
+- `maggie-social-share` - publish the finished video as platform-native posts.
+- `maggie-spirit` - brand marks/avatars that can appear in a video.
+- `maggie media generate` - AI image/video generation for b-roll (Q-category).
+
+## Boundaries
+
+- Engine-neutral production + processing; the data model and recipes live in the
+  references, channel presets and the ffmpeg layer live here. A human approves
+  publishing and any paid generation.
+
+## Credits
+
+Distilled (concepts and command shapes, not code) from the reference library's
+N-category video projects: moviepy, editly, auto-editor (MIT/Unlicense) for the
+ffmpeg command layer and timeline spec; Motion Canvas, Revideo, CCapture (MIT) for
+the programmatic render pattern; MLT / Shotcut / Kdenlive / OpenShot / Olive
+(LGPL/GPL) for the timeline data-model shape only; ffmpeg (LGPL/GPL) and HandBrake
+(GPL) invoked at arm's length.

package/bundled-tools/clis/maggie_video.py

@@ -0,0 +1,215 @@
+#!/usr/bin/env python3
+"""maggie_video - generate correct ffmpeg commands for marketing video tasks.
+
+A recipe generator distilled from moviepy, editly, auto-editor, FFmpeg and
+HandBrake (see references/ffmpeg-recipes.md). Each subcommand prints the exact
+ffmpeg command (so it is reviewable and loggable) and runs it only with --run,
+and only when `ffmpeg` is on PATH. It shells out to the ffmpeg binary (arm's-length
+LGPL/GPL use); it links no libav and vendors no GPL code. Output is always forced
+to a web-safe, platform-correct profile.
+
+Subcommands: encode, gif, trim, concat, social, overlay, subtitle, loudnorm,
+thumb, presets.
+"""
+import argparse
+import shlex
+import shutil
+import subprocess
+import sys
+
+PREFIX = ["ffmpeg", "-y", "-hide_banner", "-loglevel", "error"]
+MP4_OUT = ["-c:v", "libx264", "-profile:v", "high", "-pix_fmt", "yuv420p",
+           "-movflags", "+faststart"]
+# channel aspect presets (name -> WxH)
+SOCIAL = {"reel": (1080, 1920), "story": (1080, 1920), "tiktok": (1080, 1920),
+          "square": (1080, 1080), "feed": (1080, 1080),
+          "youtube": (1920, 1080), "landscape": (1920, 1080)}
+OVERLAY_POS = {"br": "W-w-{m}:H-h-{m}", "bl": "{m}:H-h-{m}",
+               "tr": "W-w-{m}:{m}", "tl": "{m}:{m}"}
+
+
+def emit(args, run):
+    printable = " ".join(shlex.quote(a) for a in args)
+    print(printable)
+    if not run:
+        return 0
+    if not shutil.which("ffmpeg"):
+        sys.stderr.write("ffmpeg not found on PATH; printed the command only.\n")
+        return 3
+    return subprocess.run(args).returncode
+
+
+def c_encode(a):
+    out = ["-crf", str(a.crf), "-preset", a.preset]
+    if a.vcodec == "vp9":
+        v = ["-c:v", "libvpx-vp9", "-crf", str(a.crf), "-b:v", "0", "-row-mt", "1",
+             "-pix_fmt", "yuv420p", "-c:a", "libopus", "-b:a", "128k"]
+        return emit(PREFIX + ["-i", a.input] + v + [a.output], a.run)
+    cmd = PREFIX + ["-i", a.input, "-c:v", "libx264", "-profile:v", "high",
+                    "-preset", a.preset, "-crf", str(a.crf), "-pix_fmt", "yuv420p",
+                    "-c:a", "aac", "-b:a", "128k", "-movflags", "+faststart", a.output]
+    return emit(cmd, a.run)
+
+
+def c_gif(a):
+    vf = (f"fps={a.fps},scale={a.width}:-1:flags=lanczos,split[s0][s1];"
+          f"[s0]palettegen[p];[s1][p]paletteuse")
+    return emit(PREFIX + ["-i", a.input, "-vf", vf, "-loop", "0", a.output], a.run)
+
+
+def c_trim(a):
+    dur = ["-t", str(a.duration)] if a.duration else (["-to", str(a.end)] if a.end else [])
+    if a.reencode:
+        cmd = PREFIX + ["-ss", str(a.start), "-i", a.input] + dur + \
+            ["-c:v", "libx264", "-preset", "medium", "-crf", "20", "-pix_fmt",
+             "yuv420p", "-c:a", "aac", "-movflags", "+faststart", a.output]
+    else:
+        cmd = PREFIX + ["-ss", str(a.start), "-i", a.input] + dur + \
+            ["-map", "0", "-c", "copy", "-avoid_negative_ts", "make_zero", a.output]
+    return emit(cmd, a.run)
+
+
+def c_concat(a):
+    if a.reencode or len(a.inputs) < 1:
+        ins = []
+        for p in a.inputs:
+            ins += ["-i", p]
+        n = len(a.inputs)
+        streams = "".join(f"[{i}:v][{i}:a]" for i in range(n))
+        fc = f"{streams}concat=n={n}:v=1:a=1[v][a]"
+        cmd = PREFIX + ins + ["-filter_complex", fc, "-map", "[v]", "-map", "[a]"] + \
+            ["-c:v", "libx264", "-crf", "20", "-pix_fmt", "yuv420p",
+             "-c:a", "aac", "-movflags", "+faststart", a.output]
+        return emit(cmd, a.run)
+    # fast path: a concat list file (same codec). Print how to build it.
+    print("# same-codec fast concat: write a list file, then run ffmpeg:")
+    print("#   printf \"file '%s'\\n\" " + " ".join(shlex.quote(p) for p in a.inputs) + " > concat.txt")
+    return emit(PREFIX + ["-f", "concat", "-safe", "0", "-i", "concat.txt",
+                          "-c", "copy", a.output], a.run)
+
+
+def c_social(a):
+    w, h = SOCIAL[a.aspect]
+    if a.mode == "crop":
+        vf = (f"scale={w}:{h}:force_original_aspect_ratio=increase,"
+              f"crop={w}:{h},setsar=1")
+    else:
+        vf = (f"scale={w}:{h}:force_original_aspect_ratio=decrease,"
+              f"pad={w}:{h}:(ow-iw)/2:(oh-ih)/2:color={a.color},setsar=1")
+    cmd = PREFIX + ["-i", a.input, "-vf", vf, "-crf", str(a.crf)] + MP4_OUT + \
+        ["-c:a", "aac", "-b:a", "128k", a.output]
+    return emit(cmd, a.run)
+
+
+def c_overlay(a):
+    pos = OVERLAY_POS[a.position].format(m=a.margin)
+    fc = (f"[1][0]scale2ref=w=oh*mdar:h=ih*{a.scale}[logo][base];"
+          f"[base][logo]overlay={pos}")
+    cmd = PREFIX + ["-i", a.input, "-i", a.logo, "-filter_complex", fc,
+                    "-c:a", "copy", "-c:v", "libx264", "-crf", "20",
+                    "-pix_fmt", "yuv420p", "-movflags", "+faststart", a.output]
+    return emit(cmd, a.run)
+
+
+def c_subtitle(a):
+    if a.soft:
+        cmd = PREFIX + ["-i", a.input, "-i", a.srt, "-c", "copy", "-c:s",
+                        "mov_text", "-metadata:s:s:0", f"language={a.lang}", a.output]
+    else:
+        style = f"force_style='FontName={a.font},FontSize={a.size},BorderStyle=3'"
+        cmd = PREFIX + ["-i", a.input, "-vf", f"subtitles={a.srt}:{style}",
+                        "-c:v", "libx264", "-crf", "20", "-pix_fmt", "yuv420p",
+                        "-c:a", "copy", a.output]
+    return emit(cmd, a.run)
+
+
+def c_loudnorm(a):
+    cmd = PREFIX + ["-i", a.input, "-af",
+                    f"loudnorm=I={a.target}:TP=-1.5:LRA=11",
+                    "-c:v", "copy", "-c:a", "aac", "-b:a", "128k", a.output]
+    print("# quick single-pass loudnorm (I=-14 LUFS = social/YouTube target).")
+    print("# for accuracy, measure first: ffmpeg -i IN -af loudnorm=...:print_format=json -f null -")
+    return emit(cmd, a.run)
+
+
+def c_thumb(a):
+    if a.smart:
+        cmd = PREFIX + ["-i", a.input, "-vf", "thumbnail,scale=1280:-1",
+                        "-frames:v", "1", a.output]
+    else:
+        cmd = PREFIX + ["-ss", str(a.at), "-i", a.input, "-frames:v", "1",
+                        "-q:v", "2", a.output]
+    return emit(cmd, a.run)
+
+
+def c_presets(a):
+    print("Channel aspect presets (use with `social --aspect <name>`):")
+    for name, (w, h) in SOCIAL.items():
+        print(f"  {name:<10} {w}x{h}")
+    print("\nOutput profile: H.264 high / yuv420p / +faststart / AAC 128k (web-safe).")
+    print("GIF: palettegen+paletteuse, lanczos. Loudness target: -14 LUFS.")
+    return 0
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog="maggie_video", description=__doc__,
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--run", action="store_true", help="execute (needs ffmpeg on PATH); default prints only")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    e = sub.add_parser("encode", help="transcode to a web-safe MP4 (or VP9 WebM)")
+    e.add_argument("--input", required=True); e.add_argument("--output", required=True)
+    e.add_argument("--crf", type=int, default=20); e.add_argument("--preset", default="medium")
+    e.add_argument("--vcodec", choices=["h264", "vp9"], default="h264"); e.set_defaults(fn=c_encode)
+
+    g = sub.add_parser("gif", help="high-quality palette GIF")
+    g.add_argument("--input", required=True); g.add_argument("--output", required=True)
+    g.add_argument("--fps", type=int, default=15); g.add_argument("--width", type=int, default=480)
+    g.set_defaults(fn=c_gif)
+
+    t = sub.add_parser("trim", help="cut a segment (copy by default, --reencode for frame-accurate)")
+    t.add_argument("--input", required=True); t.add_argument("--output", required=True)
+    t.add_argument("--start", required=True); t.add_argument("--duration"); t.add_argument("--end")
+    t.add_argument("--reencode", action="store_true"); t.set_defaults(fn=c_trim)
+
+    cc = sub.add_parser("concat", help="join clips (fast same-codec, or --reencode)")
+    cc.add_argument("--inputs", nargs="+", required=True); cc.add_argument("--output", required=True)
+    cc.add_argument("--reencode", action="store_true"); cc.set_defaults(fn=c_concat)
+
+    s = sub.add_parser("social", help="scale+pad or crop to a channel aspect")
+    s.add_argument("--input", required=True); s.add_argument("--output", required=True)
+    s.add_argument("--aspect", choices=list(SOCIAL), required=True)
+    s.add_argument("--mode", choices=["pad", "crop"], default="pad")
+    s.add_argument("--color", default="black"); s.add_argument("--crf", type=int, default=20)
+    s.set_defaults(fn=c_social)
+
+    o = sub.add_parser("overlay", help="overlay a logo/watermark")
+    o.add_argument("--input", required=True); o.add_argument("--logo", required=True)
+    o.add_argument("--output", required=True)
+    o.add_argument("--position", choices=list(OVERLAY_POS), default="br")
+    o.add_argument("--margin", type=int, default=24); o.add_argument("--scale", default="0.12")
+    o.set_defaults(fn=c_overlay)
+
+    sb = sub.add_parser("subtitle", help="burn in (default) or soft-mux an SRT")
+    sb.add_argument("--input", required=True); sb.add_argument("--srt", required=True)
+    sb.add_argument("--output", required=True); sb.add_argument("--soft", action="store_true")
+    sb.add_argument("--font", default="Inter"); sb.add_argument("--size", type=int, default=24)
+    sb.add_argument("--lang", default="eng"); sb.set_defaults(fn=c_subtitle)
+
+    ln = sub.add_parser("loudnorm", help="normalize loudness to a target LUFS")
+    ln.add_argument("--input", required=True); ln.add_argument("--output", required=True)
+    ln.add_argument("--target", default="-14"); ln.set_defaults(fn=c_loudnorm)
+
+    th = sub.add_parser("thumb", help="extract a poster/thumbnail frame")
+    th.add_argument("--input", required=True); th.add_argument("--output", required=True)
+    th.add_argument("--at", default="00:00:03"); th.add_argument("--smart", action="store_true")
+    th.set_defaults(fn=c_thumb)
+
+    sub.add_parser("presets", help="list channel aspect presets").set_defaults(fn=c_presets)
+
+    a = ap.parse_args(argv)
+    raise SystemExit(a.fn(a))
+
+
+if __name__ == "__main__":
+    main()

package/package.json

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

package/references/ffmpeg-recipes.md

@@ -0,0 +1,125 @@
+# ffmpeg recipes
+
+The distilled, correct ffmpeg command layer for marketing video, used by
+`maggie-video` (and shared with `maggie-design-motion`'s export). These are the
+commands `maggie_video.py` generates; this reference explains each so they can be
+adapted. Distilled from moviepy, editly, auto-editor, FFmpeg and HandBrake (see
+the design reference library category N). We **invoke the `ffmpeg` binary** (not
+link libav), so this stays license-clean; most ffmpeg builds bundle x264/x265 and
+are GPL binaries - fine to invoke, do not vendor a GPL build into a package.
+
+Common prefix: `ffmpeg -y -hide_banner -loglevel error`. Always force
+`-pix_fmt yuv420p` and `setsar=1` on output for universal playback (moviepy has a
+latent `yuva420p` typo - do not copy it).
+
+## Encode (web-safe MP4)
+
+```bash
+ffmpeg -y -i IN -c:v libx264 -profile:v high -preset medium -crf 20 \
+  -pix_fmt yuv420p -c:a aac -b:a 128k -movflags +faststart OUT.mp4
+```
+
+`+faststart` moves the moov atom to the front for web streaming. CRF 18-23 (lower =
+larger/better). WebM (VP9): `-c:v libvpx-vp9 -crf 32 -b:v 0 -row-mt 1 -pix_fmt
+yuv420p -c:a libopus -b:a 128k`.
+
+## High-quality GIF (one-pass palette)
+
+```bash
+ffmpeg -y -i IN -vf "fps=15,scale=480:-1:flags=lanczos,split[s0][s1];\
+[s0]palettegen[p];[s1][p]paletteuse" -loop 0 OUT.gif
+```
+
+Scale/fps down first to keep size sane; the palette pass avoids banding. Keep bayer
+dithering (`paletteuse=dither=bayer:bayer_scale=4`) when a photo is in frame.
+
+## Trim
+
+```bash
+# fast, no re-encode (cuts at the nearest keyframe)
+ffmpeg -y -ss START -i IN -t DURATION -map 0 -c copy -avoid_negative_ts make_zero OUT.mp4
+# frame-accurate: drop -c copy and re-encode with the MP4 recipe
+```
+
+## Concat
+
+```bash
+# same codec (fast): concat.txt has lines  file '/abs/clip1.mp4'
+ffmpeg -y -f concat -safe 0 -i concat.txt -c copy OUT.mp4
+# mixed sources (re-encode via filter)
+ffmpeg -y -i a.mp4 -i b.mp4 -filter_complex \
+  "[0:v][0:a][1:v][1:a]concat=n=2:v=1:a=1[v][a]" -map "[v]" -map "[a]" \
+  -c:v libx264 -crf 20 -pix_fmt yuv420p -movflags +faststart OUT.mp4
+```
+
+## Scale + pad or crop to a channel aspect
+
+```bash
+# 9:16 reel (1080x1920); use 1080x1080 square or 1920x1080 landscape likewise
+# pad (letterbox, no distortion):
+ffmpeg -y -i IN -vf "scale=1080:1920:force_original_aspect_ratio=decrease,\
+pad=1080:1920:(ow-iw)/2:(oh-ih)/2:color=black,setsar=1" \
+  -c:v libx264 -crf 20 -pix_fmt yuv420p -movflags +faststart OUT.mp4
+# crop (fill): force_original_aspect_ratio=increase,crop=1080:1920,setsar=1
+```
+
+## Overlay / watermark (logo bottom-right, scaled to 12% height, 24px margin)
+
+```bash
+ffmpeg -y -i IN -i logo.png -filter_complex \
+  "[1][0]scale2ref=w=oh*mdar:h=ih*0.12[logo][base];[base][logo]overlay=W-w-24:H-h-24" \
+  -c:a copy -c:v libx264 -crf 20 -pix_fmt yuv420p OUT.mp4
+```
+
+## Subtitles
+
+```bash
+# burn in (hardsub) from SRT
+ffmpeg -y -i IN -vf "subtitles=subs.srt:force_style='FontName=Inter,FontSize=24,BorderStyle=3'" \
+  -c:v libx264 -crf 20 -pix_fmt yuv420p -c:a copy OUT.mp4
+# soft-mux (toggleable track, MP4)
+ffmpeg -y -i IN -i subs.srt -c copy -c:s mov_text -metadata:s:s:0 language=eng OUT.mp4
+```
+
+## Loudness normalize (EBU R128; -14 LUFS = social/YouTube target)
+
+```bash
+# quick single pass
+ffmpeg -y -i IN -af loudnorm=I=-14:TP=-1.5:LRA=11 -c:v copy -c:a aac -b:a 128k OUT.mp4
+# accurate two pass: measure first (reads JSON from stderr), then apply measured_* values
+ffmpeg -i IN -af loudnorm=I=-14:TP=-1.5:LRA=11:print_format=json -f null -
+```
+
+editly's cheaper alternative is `dynaudnorm=g=5:maxgain=30`.
+
+## Thumbnail / poster
+
+```bash
+ffmpeg -y -ss 00:00:03 -i IN -frames:v 1 -q:v 2 OUT.jpg       # at a timestamp
+ffmpeg -y -i IN -vf "thumbnail,scale=1280:-1" -frames:v 1 OUT.jpg  # most representative frame
+```
+
+## Silence auto-cut (auto-editor's idea, via the CLI)
+
+```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)
+```
+
+## Transitions (between two clips)
+
+`xfade=transition=fade:duration=0.5:offset=5.0` for video and `acrossfade=d=0.5`
+for audio. editly/gl-transitions names (`fade`, `dissolve`, `directional-left`, ...)
+map onto xfade's transition list.
+
+## The CLI
+
+`maggie_video.py` generates every command above (and runs it with `--run` when
+`ffmpeg` is on PATH). It prints the command so it is reviewable and loggable:
+
+```bash
+maggie tool maggie_video.py social --input in.mp4 --output reel.mp4 --aspect reel
+maggie tool maggie_video.py gif --input in.mp4 --output out.gif --fps 15 --width 480
+maggie tool maggie_video.py --run encode --input in.mov --output out.mp4   # actually runs
+maggie tool maggie_video.py presets
+```

package/references/programmatic-video.md

@@ -0,0 +1,80 @@
+# Programmatic video: the render-then-encode pattern
+
+How to produce video from code deterministically, distilled from the leading
+engines (Motion Canvas, Remotion, Revideo, CCapture). Used by `maggie-video`;
+`maggie-design-motion`'s Part C is one concrete implementation of this pattern (the
+DOM/Playwright case). Author your own code from this; adopt engines per the license
+table below.
+
+## The pattern (every engine agrees)
+
+1. **The frame is the unit of truth; the wall clock is the enemy.** Deterministic
+   output comes from driving content by an **absolute frame index or a virtual
+   clock**, never real time. Two techniques:
+   - **Seek by frame:** re-evaluate the scene at frame N (`playback.seek(frame)` in
+     Motion Canvas / Revideo; the current-frame hook in Remotion).
+   - **Fake the clock:** monkeypatch `performance.now`, `requestAnimationFrame`,
+     `Date`, timers and `currentTime`, and advance one fixed step per captured frame
+     (CCapture's `TimeWarp`; Playwright's `page.clock` + `__tick` in Part C).
+2. **Render then encode, decoupled.** Produce frames as fast as the machine allows
+   (not realtime) into a canvas/DOM, then feed an encoder as a separate stage.
+3. **Two encode routes.** (a) **Shell out to ffmpeg** via a pipe - `image2pipe`
+   base64 PNG (Revideo) or `rawvideo`/rgba (Motion Canvas), output
+   `-pix_fmt yuv420p -movflags +faststart` (the exact profile in
+   [ffmpeg recipes](ffmpeg-recipes.md)). (b) **In-browser WebCodecs** (CCapture) -
+   no ffmpeg dependency, hardware-accelerated.
+4. **Headless browser as the frame factory** when the composition is web tech:
+   Revideo = Puppeteer, Remotion = headless Chromium, Part C = Playwright. The page
+   renders; the driver screenshots or reads back each frame.
+5. **One source → preview + render + parameterized batch.** The same scene file
+   drives a live preview and the headless render; **variables/props** turn one
+   template into many videos (N brand variants, localized cuts, per-product reels).
+
+## Composition models
+
+- **React components** (Remotion, Revideo also supports React) - animation driven by
+  the current frame via hooks.
+- **Generator functions** (Motion Canvas, Revideo) - a scene is
+  `makeScene2D(function* (view) { view.add(<Rect/>); yield* all(rect().position.x(100, 1)); yield* waitFor(0.5); })`;
+  timing is the generator's control flow; signals (`createSignal`) provide
+  reactivity. These read cleanly for an LLM to author from a prompt.
+- **Canvas draw calls + a recorder** (CCapture) - any existing rAF canvas loop plus
+  one `capturer.capture(canvas)` line.
+
+## Choosing an engine (decision)
+
+- **Animating an existing rendered page/design** → stay in
+  `maggie-design-motion` Part C (Playwright fake-clock). No new engine needed; this
+  is the common Maggie case (social/hero motion from a design).
+- **Programmatic, data-driven video from scratch** (N variants from brand data,
+  charts, captions) → **Revideo** - MIT, headless-first, parameterizable
+  (`renderVideo({projectFile, variables, settings:{outFile, workers}})`),
+  parallelizable across workers, and it ships a `revideo serve` render endpoint
+  (with `callbackUrl` + SSE progress) for render-as-a-service.
+- **A pure canvas sketch already using rAF** that just needs recording → **CCapture**
+  (WebCodecs, no ffmpeg).
+- **Simple clip assembly / transcode / captions** (not code-drawn animation) → the
+  ffmpeg layer directly ([ffmpeg recipes](ffmpeg-recipes.md)) or the declarative
+  [timeline model](video-timeline-model.md).
+
+## Licenses (critical)
+
+| Engine | License | Adopt? |
+|---|---|---|
+| Motion Canvas | MIT | Yes (generators; editor-driven render) |
+| **Revideo** | MIT | **Yes - recommended programmatic default** (headless, parameterized, parallel) |
+| CCapture.js | MIT | Yes - the WebCodecs recorder / clock-faking reference |
+| video.js | Apache-2.0 | Playback only, not production |
+| **Remotion** | **Remotion License (source-available; paid Company License for for-profit orgs > 3 employees)** | **No hard dependency** - reference/option the end user may license; keep Maggie's default on the MIT stack |
+
+Rendering is a **local CPU/GPU cost** (ffmpeg, a headless browser), not a paid API -
+flag long renders as a time/resource cost, consistent with "local tools only". If
+any hosted or LLM video generation is wired in, the global BYOK + spend-first rules
+apply.
+
+## Shared encode profile
+
+`maggie-video` and `maggie-design-motion` share one profile:
+`libx264 -crf 14-20 -preset slow/medium -pix_fmt yuv420p -movflags +faststart`,
+even dimensions, plus 960px / 800x500 GIF deliverables. For transparent output,
+Revideo uses per-format pixel formats (`yuva420p` WebM, `yuva444p10le` ProRes).