Skip to content

puntorigen/avatar-skills / broll-core

broll-core

Verified

Internal shared library for the broll-* B-roll skills (broll-web-capture, broll-browser-recorder, broll-terminal, broll-demo-avatar). Provides the canonical reel geometry/fps that match avatar-reel-composer, thin ffmpeg/ffprobe wrappers, the numbered-clip + manifest.json conventions, and the avatar picture-in-picture (PiP) compositor (pip_overlay, avatar- or base-driven). NOT invoked directly — it is imported by the other broll-* skills. Do not run this skill to make content; use broll-web-capture or broll-terminal.

FileKindSize
SKILL.mdskill md3.1 KB
scripts/_common.pyscript3.9 KB
scripts/pip_overlay.pyscript8.3 KB
scripts/requirements.txtmanifest13 B

scripts/pip_overlay.py

View on GitHub
#!/usr/bin/env python3
"""Composite a talking avatar over a base B-roll layer (the avatar PiP overlay).

Single source of truth for the "base layer + avatar PiP" architecture, shared by
every base-layer skill (broll-web-capture, broll-terminal, broll-browser-recorder)
and the overlay skill (broll-demo-avatar). Two layouts:
  * pip-circle (default) : avatar masked into a corner circle over a near-full base.
  * split                : base on top, avatar on the bottom (each cover-cropped).

Length modes (``length=``):
  * "avatar" (default): the avatar clip carries the narration, so its audio drives
    the output length and the base is looped to cover it. Best for short B-roll
    (broll-web-capture / broll-terminal).
  * "base": the base clip is the hero and drives the length (e.g. a recorded
    product demo). The base plays once; when the avatar's narration ends before the
    base does, the avatar freezes on its last frame and its audio is padded with
    trailing silence. Used by broll-browser-recorder.

The avatar clip MUST be a static, face-forward "pip" shot (avatar-camera-angles
`--move pip`), lip-synced LOCKED with avatar-talking-video (p-video-avatar): this
compositor never moves the avatar, so any drift inside the circle would come from
the source clip.
"""
from __future__ import annotations

import argparse
from pathlib import Path

import _common as C


def _has_audio(path: Path) -> bool:
    p = C.run(["ffprobe", "-v", "error", "-select_streams", "a:0",
               "-show_entries", "stream=index", "-of", "csv=p=0", str(path)], check=False)
    return bool((p.stdout or "").strip())


def _circle_masks(diameter: int, work: Path, ring: bool, ring_w: int):
    from PIL import Image, ImageDraw
    d = diameter
    fill = Image.new("L", (d, d), 0)
    ImageDraw.Draw(fill).ellipse([0, 0, d - 1, d - 1], fill=255)
    fill_p = work / "_pip_circle.png"
    fill.save(fill_p)
    ring_p = None
    if ring:
        r = Image.new("RGBA", (d, d), (0, 0, 0, 0))
        ImageDraw.Draw(r).ellipse([ring_w // 2, ring_w // 2, d - 1 - ring_w // 2,
                                   d - 1 - ring_w // 2],
                                  outline=(255, 255, 255, 235), width=ring_w)
        ring_p = work / "_pip_ring.png"
        r.save(ring_p)
    return fill_p, ring_p


def overlay_pip(base, avatar, out, *, layout="pip-circle", aspect="9:16",
                corner="br", diameter_frac=0.36, margin_frac=0.045, ring=True,
                bottom_clear=0, face_bias=0.4, length="avatar",
                fps=C.DEFAULT_FPS) -> Path:
    base, avatar, out = Path(base), Path(avatar), Path(out)
    W, H = C.aspect_dims(aspect)
    work = out.parent
    work.mkdir(parents=True, exist_ok=True)
    has_audio = _has_audio(avatar)

    if length == "base":
        # The base recording is the hero (e.g. a product demo): it drives the
        # length and plays once. The avatar freezes on its last frame once its
        # narration ends (tpad clone) and its audio is padded with silence.
        dur = C.ffprobe_duration(base) or 5.0
        base_inputs = ["-i", str(base)]
        ava_vpre = f"tpad=stop_mode=clone:stop_duration={dur},"
        if has_audio:
            aud_fc, amap = ";[1:a]apad[aud]", ["-map", "[aud]"]
        else:
            aud_fc, amap = "", []
    else:
        # avatar-driven (default): the avatar's narration sets the length and the
        # base loops to cover it.
        dur = C.ffprobe_duration(avatar) or 5.0
        base_inputs = ["-stream_loop", "-1", "-i", str(base)]
        ava_vpre = ""
        aud_fc = ""
        amap = ["-map", "1:a"] if has_audio else []

    if layout == "split":
        if W > H:
            # Landscape (16:9): side-by-side halves (base left, avatar right) —
            # a stacked split would squash both panels on a wide frame.
            half = (W // 2) - ((W // 2) % 2)
            fc = (f"[0:v]scale={half}:{H}:force_original_aspect_ratio=increase,"
                  f"crop={half}:{H},setsar=1[left];"
                  f"[1:v]{ava_vpre}scale={half}:{H}:force_original_aspect_ratio=increase,"
                  f"crop={half}:{H},setsar=1[right];"
                  f"[left][right]hstack=inputs=2,format=yuv420p[v]" + aud_fc)
        else:
            # Portrait / square: stacked halves (base top, avatar bottom).
            half = (H // 2) - ((H // 2) % 2)
            fc = (f"[0:v]scale={W}:{half}:force_original_aspect_ratio=increase,"
                  f"crop={W}:{half},setsar=1[top];"
                  f"[1:v]{ava_vpre}scale={W}:{half}:force_original_aspect_ratio=increase,"
                  f"crop={W}:{half},setsar=1[bot];"
                  f"[top][bot]vstack=inputs=2,format=yuv420p[v]" + aud_fc)
        cmd = ["ffmpeg", "-y", *base_inputs,
               "-i", str(avatar), "-filter_complex", fc, "-map", "[v]", *amap,
               "-t", f"{dur}", "-r", str(fps), "-c:v", "libx264",
               "-pix_fmt", "yuv420p", "-shortest", str(out), "-loglevel", "error"]
        C.run(cmd, desc=f"pip split ({length}) -> {out.name}")
        return out

    # pip-circle
    d = int(W * diameter_frac); d -= d % 2
    margin = int(W * margin_frac)
    fill_p, ring_p = _circle_masks(d, work, ring, ring_w=max(4, d // 60))
    by = margin + max(0, int(bottom_clear))  # lift bottom corners to clear a caption
    xy = {
        "br": (f"W-w-{margin}", f"H-h-{by}"),
        "bl": (f"{margin}", f"H-h-{by}"),
        "tr": (f"W-w-{margin}", f"{margin}"),
        "tl": (f"{margin}", f"{margin}"),
    }.get(corner, (f"W-w-{margin}", f"H-h-{by}"))

    fb = max(0.0, min(1.0, face_bias))  # vertical crop bias: lower = keep more of the top (face)
    inputs = [*base_inputs, "-i", str(avatar), "-loop", "1", "-i", str(fill_p)]
    fc = (f"[0:v]scale={W}:{H}:force_original_aspect_ratio=increase,"
          f"crop={W}:{H},setsar=1[bg];"
          f"[1:v]{ava_vpre}scale={d}:{d}:force_original_aspect_ratio=increase,"
          f"crop={d}:{d}:(iw-{d})/2:(ih-{d})*{fb}[sq];"
          f"[2:v]format=gray,scale={d}:{d}[m];"
          f"[sq][m]alphamerge[ava];"
          f"[bg][ava]overlay=x={xy[0]}:y={xy[1]}:shortest=1[comp]")
    last = "comp"
    if ring and ring_p:
        ring_idx = 3  # inputs: base(0), avatar(1), circle-mask(2), ring(3)
        inputs += ["-loop", "1", "-i", str(ring_p)]
        fc += (f";[{ring_idx}:v]format=rgba[ring];"
               f"[comp][ring]overlay=x={xy[0]}:y={xy[1]}:shortest=1[comp2]")
        last = "comp2"
    fc += f";[{last}]format=yuv420p[v]" + aud_fc
    cmd = ["ffmpeg", "-y", *inputs, "-filter_complex", fc, "-map", "[v]", *amap,
           "-t", f"{dur}", "-r", str(fps), "-c:v", "libx264", "-pix_fmt", "yuv420p",
           "-shortest", str(out), "-loglevel", "error"]
    C.run(cmd, desc=f"pip circle ({corner}, {length}) -> {out.name}")
    return out


def main() -> int:
    ap = argparse.ArgumentParser(description="Composite avatar PiP over a base clip.")
    ap.add_argument("base", type=Path, help="base B-roll layer (web/terminal)")
    ap.add_argument("avatar", type=Path, help="talking avatar clip (carries audio)")
    ap.add_argument("-o", "--out", type=Path, required=True)
    ap.add_argument("--layout", default="pip-circle", choices=["pip-circle", "split"])
    ap.add_argument("--aspect", default="9:16")
    ap.add_argument("--corner", default="br", choices=["br", "bl", "tr", "tl"])
    ap.add_argument("--diameter", type=float, default=0.36, help="circle diameter as frac of width")
    ap.add_argument("--no-ring", action="store_true")
    ap.add_argument("--bottom-clear", type=int, default=0,
                    help="px reserved at the bottom (lifts a bottom-corner PiP above a caption)")
    ap.add_argument("--face-bias", type=float, default=0.4,
                    help="vertical crop bias for the circle (0=top..1=bottom; lower keeps the face)")
    ap.add_argument("--length", default="avatar", choices=["avatar", "base"],
                    help="who drives the clip length: avatar narration (default) "
                         "or the base clip (e.g. a recorded demo; avatar freezes at its end)")
    args = ap.parse_args()
    C.require_tool("ffmpeg")
    overlay_pip(args.base, args.avatar, args.out, layout=args.layout, aspect=args.aspect,
                corner=args.corner, diameter_frac=args.diameter, ring=not args.no_ring,
                bottom_clear=args.bottom_clear, face_bias=args.face_bias, length=args.length)
    print(str(args.out))
    return 0


if __name__ == "__main__":
    raise SystemExit(main())
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall