puntorigen/avatar-skills / avatar-reel-composer
avatar-reel-composer
VerifiedTurn a script + an existing avatar into a finished reel — 9:16 vertical (TikTok/Reels) or 16:9 landscape (YouTube), set via the storyboard `format`. Narrates the script once in the avatar's cloned voice, cuts it per scene by word-level alignment, generates lip-synced talking-head scenes (avatar-talking-video) and silent B-roll scenes (broll-generator) as voice-over, applies Ken Burns / zoom motion, and assembles with hard cuts under one master narration. Can weave in a GUEST/cameo scene (a clip of a DIFFERENT avatar speaking in its own voice) that keeps its own audio. Supports per-reel and per-scene LOCATIONS (alternate avatar looks built by avatar-location). Can also onboard a brand-new avatar from a public Instagram profile via create_avatar.py (download, analysis, frames, voice cloning, style profiling). Use when the user wants to produce a full reel/short from a script for an avatar that already exists (videos/, voices/, angles/ and/or talking_profile.json), or to onboard a new avatar from an Instagram URL, in the style of that avatar's analyzed reels.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 47.0 KB |
| examples/storyboard.example.json | config | 7.8 KB |
| requirements.txt | manifest | 84 B |
| scripts/_arc_common.py | script | 11.3 KB |
| scripts/assemble_narration.py | script | 11.4 KB |
| scripts/compose_reel.py | script | 45.8 KB |
| scripts/create_avatar.py | script | 19.1 KB |
| scripts/finish_reel.py | script | 72.7 KB |
| scripts/narrate.py | script | 28.2 KB |
| scripts/polish_reel.py | script | 22.4 KB |
| scripts/profile_transitions.py | script | 11.8 KB |
| scripts/setup_key.py | script | 1.6 KB |
scripts/profile_transitions.py
View on GitHub#!/usr/bin/env python3
"""Profile the VISUAL TRANSITION style of an avatar's ORIGINAL reels.
For every scene boundary in a ``*.analysis.json`` (video-scene-analysis), this
samples low-res frames around the cut in the original video and measures how
the picture deviates from its surroundings: a brightness lift + warm color
shift = the "golden flash" seen on some creators' reels; a neutral lift =
white flash; a brightness drop = dip-to-black; no significant deviation =
bare hard cuts.
The aggregated result is written to ``<avatar>/transition_style.json`` —
consumed by ``polish_reel.py`` the same way ``finish_reel.py`` consumes
``subtitle_style.json`` — so NEW avatars automatically get THEIR OWN measured
transition look (style, duration, strength) instead of another avatar's
defaults.
Measurement details:
* Frames are sampled at ~15fps in a ±0.6s window around each cut, at 48px
wide (mean channel statistics only — no detail needed).
* The baseline is taken 0.8-1.2s away on BOTH sides of the cut; the flash
metric is the peak deviation of brightness/warmth inside the window vs the
nearer baseline. PySceneDetect often reports a flashed cut slightly LATE
(the wash confuses it), which is why the window spans both sides.
* Flash duration = the contiguous span around the peak where the deviation
stays above 30% of the peak.
Usage:
python3 profile_transitions.py <video.analysis.json> [more.analysis.json …]
[--out <avatar>/transition_style.json] [--min-scene-gap 1.6]
"""
from __future__ import annotations
import argparse
import json
import subprocess
import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).parent))
import _arc_common as C # noqa: E402
import numpy as np # noqa: E402
SAMPLE_W = 48 # analysis frame width (stats only)
WIN_S = 0.6 # window sampled on each side of the cut
BASE_NEAR, BASE_FAR = 0.8, 1.2 # baseline band distance from the cut
FPS = 15 # sampling rate inside the window
# Peak thresholds (0-255 scale) for calling a flash:
TH_BRIGHT = 14.0 # brightness deviation
TH_WARMTH = 16.0 # (R-B) deviation
# Reference gain: the reference avatar's measured golden flash peaks at a mean
# brightness delta of ~110 (0-255); profiles are normalized so that == gain 1.0.
GAIN_REF_BRIGHT = 110.0
def _video_dims(video):
out = subprocess.run(
["ffprobe", "-v", "error", "-select_streams", "v:0",
"-show_entries", "stream=width,height", "-of", "csv=p=0", str(video)],
capture_output=True, text=True).stdout.strip()
w, h = (int(x) for x in out.split(",")[:2])
return w, h
def _sample_band(video, t0, t1, sample_h):
"""Decode [t0, t1) at FPS as tiny RGB frames; return (times, Nx3 means)."""
if t0 < 0:
t0 = 0.0
dur = max(0.0, t1 - t0)
if dur <= 0:
return np.zeros(0), np.zeros((0, 3))
cmd = ["ffmpeg", "-v", "error", "-ss", f"{t0:.3f}", "-i", str(video),
"-t", f"{dur:.3f}", "-vf", f"fps={FPS},scale={SAMPLE_W}:{sample_h}",
"-f", "rawvideo", "-pix_fmt", "rgb24", "-"]
try:
raw = subprocess.run(cmd, capture_output=True, timeout=120).stdout
except subprocess.TimeoutExpired:
return np.zeros(0), np.zeros((0, 3))
frame_bytes = SAMPLE_W * sample_h * 3
n = len(raw) // frame_bytes
if n == 0:
return np.zeros(0), np.zeros((0, 3))
arr = np.frombuffer(raw[: n * frame_bytes], dtype=np.uint8)
arr = arr.reshape(n, sample_h, SAMPLE_W, 3).astype(np.float32)
means = arr.mean(axis=(1, 2)) # (n, 3) mean R,G,B per frame
times = t0 + (np.arange(n) + 0.5) / FPS
return times, means
def _stats(means):
"""brightness Y, warmth (R-B) per frame."""
if len(means) == 0:
return np.zeros(0), np.zeros(0)
y = 0.299 * means[:, 0] + 0.587 * means[:, 1] + 0.114 * means[:, 2]
warmth = means[:, 0] - means[:, 2]
return y, warmth
def profile_cut(video, t_cut, *, total_dur, sample_h):
"""Measure one boundary. Returns a dict or None if unmeasurable."""
lo = max(0.0, t_cut - BASE_FAR)
hi = min(total_dur, t_cut + BASE_FAR)
if hi - lo < 1.0:
return None
times, means = _sample_band(video, lo, hi, sample_h)
if len(times) < 8:
return None
y, warmth = _stats(means)
rel = times - t_cut
base_mask = (np.abs(rel) >= BASE_NEAR)
win_mask = (np.abs(rel) <= WIN_S)
if base_mask.sum() < 3 or win_mask.sum() < 3:
return None
# Baseline per side (scene content differs across the cut), take the
# nearer side's baseline for each window sample.
def _side_base(arr):
pre = arr[base_mask & (rel < 0)]
post = arr[base_mask & (rel > 0)]
pre_v = float(np.median(pre)) if len(pre) else float(np.median(arr[base_mask]))
post_v = float(np.median(post)) if len(post) else float(np.median(arr[base_mask]))
return pre_v, post_v
yb_pre, yb_post = _side_base(y)
wb_pre, wb_post = _side_base(warmth)
dy = np.where(rel < 0, y - yb_pre, y - yb_post)
dw = np.where(rel < 0, warmth - wb_pre, warmth - wb_post)
dy_w, dw_w, rel_w = dy[win_mask], dw[win_mask], rel[win_mask]
mean_w = means[win_mask]
k = int(np.argmax(0.6 * dy_w + 0.4 * dw_w))
peak_dy, peak_dw = float(dy_w[k]), float(dw_w[k])
is_flash = peak_dy > TH_BRIGHT or peak_dw > TH_WARMTH
is_dip = (not is_flash) and float(-dy_w.min()) > 2 * TH_BRIGHT
out = {
"t": round(float(t_cut), 3),
"peak_dy": round(peak_dy, 1),
"peak_dw": round(peak_dw, 1),
"kind": "flash" if is_flash else ("dip" if is_dip else "none"),
}
if is_flash:
# duration: contiguous span around the peak above 30% of the peak metric
metric = 0.6 * dy_w + 0.4 * dw_w
th = 0.3 * metric[k]
i = k
while i > 0 and metric[i - 1] > th:
i -= 1
j = k
while j < len(metric) - 1 and metric[j + 1] > th:
j += 1
out["dur"] = round(float(rel_w[j] - rel_w[i]) + 1.0 / FPS, 3)
out["peak_offset"] = round(float(rel_w[k]), 3)
# channel deltas at the peak vs that side's baseline -> hue class
base_rgb = (means[base_mask & (rel < 0)] if rel_w[k] < 0
else means[base_mask & (rel > 0)])
if len(base_rgb) == 0:
base_rgb = means[base_mask]
d_rgb = mean_w[k] - np.median(base_rgb, axis=0)
out["d_rgb"] = [round(float(v), 1) for v in d_rgb]
dr, dg, db = d_rgb
out["hue"] = ("golden" if (dr > dg > db or (dr > 0 and db < 0.3 * dr))
else "white")
return out
def _rate(cuts, kind):
return round(sum(1 for c in cuts if c["kind"] == kind) / len(cuts), 2) if cuts else 0.0
def aggregate(per_cut, sources):
"""Boundary-type-aware aggregation. The originals don't dress EVERY cut —
e.g. lolo flashes 100% of B-roll ENTRIES but 0% of exits and almost no
talking-head cuts — so rates are computed per boundary type and the style
is declared for the type(s) that actually use it (``flash_at``)."""
measured = [c for c in per_cut if c]
n = len(measured)
by_type = {bt: [c for c in measured if c.get("boundary") == bt]
for bt in ("broll_entry", "broll_exit", "th_th")}
profile = {
"version": 1,
"sources": sources,
"boundaries_measured": n,
"flash_rate": _rate(measured, "flash"),
"flash_rate_by_boundary": {bt: _rate(cs, "flash") for bt, cs in by_type.items() if cs},
"dip_rate": _rate(measured, "dip"),
"per_cut": measured,
}
# Which boundary types use the flash? (>= 50% of that type's cuts)
flash_at = [bt for bt, cs in by_type.items() if cs and _rate(cs, "flash") >= 0.5]
flashes = [c for c in measured if c["kind"] == "flash"
and (not flash_at or c.get("boundary") in flash_at)]
if not flash_at and _rate(measured, "flash") >= 0.3:
flash_at = ["broll_entry", "broll_exit", "th_th"] # used loosely everywhere
flashes = [c for c in measured if c["kind"] == "flash"]
if flash_at and flashes:
golden = sum(1 for c in flashes if c.get("hue") == "golden")
durs = sorted(c["dur"] for c in flashes)
peaks = sorted(c["peak_dy"] for c in flashes)
profile.update({
"style": "golden_flash" if golden >= len(flashes) / 2 else "white_flash",
"flash_at": flash_at,
"flash_dur": round(min(0.6, max(0.2, durs[len(durs) // 2])), 2),
"flash_gain": round(min(1.6, max(0.4, peaks[len(peaks) // 2] / GAIN_REF_BRIGHT)), 2),
})
elif _rate(measured, "dip") >= 0.3:
profile["style"] = "dip_black"
else:
profile["style"] = "none"
return profile
def profile_videos(analysis_paths, *, min_scene_gap=1.6):
per_cut, sources = [], []
for ap in analysis_paths:
a = C.load_json(ap)
video = a.get("video_path") or ""
vp = Path(video)
if not vp.exists(): # try relative to the analysis file
vp = Path(ap).parent / Path(video).name
if not vp.exists():
print(f" Warning: video for {ap} not found; skipping.", file=sys.stderr)
continue
scenes = a.get("scenes") or []
total = max((float(s.get("end") or 0) for s in scenes), default=0.0)
def _is_broll(s):
return (s.get("scene_type") or "") == "supplementary_material"
cuts = []
for prev, cur in zip(scenes, scenes[1:]):
t = float(cur.get("start") or 0)
if t - float(prev.get("start") or 0) < min_scene_gap or total - t < 1.0:
continue
if _is_broll(cur) and not _is_broll(prev):
btype = "broll_entry"
elif _is_broll(prev) and not _is_broll(cur):
btype = "broll_exit"
else:
btype = "th_th"
cuts.append((t, btype))
w, h = _video_dims(vp)
sample_h = max(2, round(h * SAMPLE_W / w / 2) * 2)
print(f" {vp.name}: {len(cuts)} boundaries", file=sys.stderr)
sources.append(str(vp))
for t, btype in cuts:
r = profile_cut(vp, t, total_dur=total, sample_h=sample_h)
if r:
r["video"] = vp.name
r["boundary"] = btype
per_cut.append(r)
print(f" {t:7.2f}s {btype:11} {r['kind']:5} dy={r['peak_dy']:+6.1f} "
f"dw={r['peak_dw']:+6.1f}"
+ (f" dur={r['dur']:.2f}s hue={r['hue']}" if r["kind"] == "flash" else ""),
file=sys.stderr)
return aggregate(per_cut, sources)
def main():
ap = argparse.ArgumentParser(description="Measure the original reels' visual "
"transition style -> transition_style.json")
ap.add_argument("analysis", nargs="+", type=Path,
help="*.analysis.json files (video-scene-analysis output)")
ap.add_argument("--out", type=Path, default=None,
help="Output path (default: <avatar>/transition_style.json "
"next to the first video's avatar folder, else CWD)")
ap.add_argument("--min-scene-gap", type=float, default=1.6)
args = ap.parse_args()
profile = profile_videos(args.analysis, min_scene_gap=args.min_scene_gap)
out = args.out
if out is None:
# <avatar>/videos/<file>.mp4 -> <avatar>/transition_style.json
try:
v0 = Path(profile["sources"][0])
avatar = v0.parent.parent if v0.parent.name == "videos" else Path.cwd()
out = avatar / "transition_style.json"
except (IndexError, KeyError):
out = Path.cwd() / "transition_style.json"
C.save_json(out, profile)
print(f"\nTransition style profile -> {out}", file=sys.stderr)
print(json.dumps({k: v for k, v in profile.items() if k != "per_cut"},
ensure_ascii=False, indent=2))
if __name__ == "__main__":
main()
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |