puntorigen/avatar-skills / reel-restyle
reel-restyle
VerifiedAnalyze ONE avatar's reels and re-apply their style to a DIFFERENT avatar. Distills a script-agnostic reel TEMPLATE from a reference avatar's existing video-scene-analysis (scene/beat sequence, talking-head vs B-roll pattern, per-beat camera angle, cut/zoom transitions, SFX placement, caption style and proportional pacing), then applies that template to a NEW avatar given only a picture + a voice sample + a script -- auto-scaffolding the new avatar's camera-angle stills, cloned voice, talking profile and copied caption/transition styles, and drafting a composer-ready storyboard. Use when the user wants to reuse one avatar's reel style/structure (e.g. "make a reel for this new person in lolo's style", "same camera angles, transitions, SFX and timing but a different face/voice/script", cross-avatar style transfer, reel templates).
| File | Kind | Size |
|---|---|---|
| REFERENCE.md | markdown | 9.0 KB |
| SKILL.md | skill md | 6.8 KB |
| examples/reel_template.example.json | config | 4.9 KB |
| scripts/_angle_map.py | script | 2.7 KB |
| scripts/_restyle_common.py | script | 6.8 KB |
| scripts/apply_template.py | script | 8.9 KB |
| scripts/extract_template.py | script | 13.6 KB |
| scripts/generate_storyboard.py | script | 13.9 KB |
| scripts/requirements.txt | manifest | 612 B |
| scripts/scaffold_avatar.py | script | 14.9 KB |
scripts/extract_template.py
View on GitHub#!/usr/bin/env python3
"""Distill a script-agnostic reel TEMPLATE from a reference avatar's analysis.
Reads one or more enriched ``*.analysis.json`` files (produced + vision-enriched
by the video-scene-analysis skill) plus the avatar's measured style files
(``transition_style.json``, ``subtitle_style.json``, ``talking_profile.json``)
and writes a compact ``reel_template.json`` -- the reusable "DNA" of the reel:
* a per-scene BEAT sequence (talking-head vs B-roll pattern),
* per-beat camera angle (mapped to an avatar-camera-angles move) + framing,
* the cut/transition vocabulary (zoom_from_previous per beat),
* SFX placement style + density,
* caption style, proportional pacing (dur_weight per beat) and a delivery seed.
It contains NO script-specific content, so generate_storyboard.py / apply_template.py
can re-apply it to a DIFFERENT avatar + voice + script. Scene DURATIONS are not
copied verbatim (a new script has its own rhythm); the template carries the
proportional pacing and structure, and the composer derives real durations from
the new narration's word alignment.
The beat STRUCTURE comes from a single representative reel (``--primary``, else
the analysis with the most scenes). Avatar-level style (transitions, captions)
is read from the measured style files, which are already aggregated across reels.
Usage:
python3 extract_template.py lolo/videos/2026-06-08_15-02-03.analysis.json
python3 extract_template.py lolo/videos/*.analysis.json --avatar-dir lolo \
-o lolo/reel_template.json
"""
from __future__ import annotations
import argparse
import json
import sys
from datetime import datetime, timezone
from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parent))
import _restyle_common as C # noqa: E402
from _angle_map import move_for_angle, needed_moves # noqa: E402
TALKING_TYPES = {"main_character_solo", "multi_person"}
# Coarse call-to-action hints (es/en) used only to label the narrative arc.
CTA_HINTS = (
"escr", "llama", "mensaje", "sígue", "sigue", "link", "comenta", "guarda",
"comparte", "agenda", "reserva", "contact", "message", "follow", "subscribe",
"comment", "save", "share", "dm", "book", "sign up",
)
DEFAULT_TRANSITIONS = {
"style": "golden_flash",
"flash_at": ["broll_entry"],
"flash_dur": 0.4,
"flash_gain": 0.99,
"_note": "Default transition style (no measured transition_style.json found).",
}
DEFAULT_MUSIC_PROMPT = (
"sparse, intimate instrumental bed under a voice-over; soft and unobtrusive, "
"no drums, no beat, no vocals -- TAILOR this to the new reel's topic + tone"
)
# ---------------------------------------------------------------------------
# Beat helpers
# ---------------------------------------------------------------------------
def beat_type(scene) -> str:
return "talking_head" if scene.get("scene_type") in TALKING_TYPES else "broll"
def derive_role(i: int, n: int, focus: str | None) -> str:
if i == 0:
return "hook"
if i == n - 1:
return "cta" if (focus and any(h in focus.lower() for h in CTA_HINTS)) else "close"
return "body"
def broll_camera_for(zoom: str | None) -> str:
return {"zoom_in": "push_in", "zoom_out": "pull_out"}.get(zoom or "", "handheld")
def beat_emphasis(scene) -> bool:
zoom = (scene.get("zoom_from_previous") or {}).get("type")
framing = (scene.get("camera") or {}).get("framing")
if zoom == "zoom_in":
return True
return framing in ("close_up", "extreme_close_up")
def cut_rhythm(avg: float) -> str:
if avg < 3.0:
return "fast"
if avg < 5.0:
return "medium"
return "slow"
# ---------------------------------------------------------------------------
# Selection / discovery
# ---------------------------------------------------------------------------
def enriched_score(data: dict) -> int:
"""How many talking-head scenes carry a real camera angle (enrichment)."""
score = 0
for s in data.get("scenes", []):
if beat_type(s) == "talking_head" and (s.get("camera") or {}).get("angle"):
score += 1
return score
def pick_primary(analyses: list[tuple[Path, dict]], explicit: Path | None):
if explicit:
for p, d in analyses:
if p.resolve() == explicit.resolve():
return p, d
raise SystemExit(f"--primary {explicit} is not among the provided analyses.")
# Prefer the richest enriched structure; tie-break by scene count, then duration.
def key(item):
_p, d = item
scenes = d.get("scenes", [])
dur = sum(float(s.get("duration") or 0) for s in scenes)
return (enriched_score(d), len(scenes), dur)
return max(analyses, key=key)
def find_style_file(avatar_dir: Path | None, explicit, name: str) -> Path | None:
if explicit:
p = Path(explicit).expanduser()
return p if p.exists() else None
if avatar_dir and (avatar_dir / name).exists():
return avatar_dir / name
return None
# ---------------------------------------------------------------------------
# Main extraction
# ---------------------------------------------------------------------------
def build_template(args) -> dict:
base = Path(args.base_dir).expanduser().resolve()
paths = [Path(p).expanduser() for p in args.analysis]
analyses: list[tuple[Path, dict]] = []
for p in paths:
if not p.exists():
print(f" ! skipping missing analysis: {p}", file=sys.stderr)
continue
d = C.try_load_json(p)
if d is None or not d.get("scenes"):
print(f" ! skipping analysis without scenes: {p}", file=sys.stderr)
continue
analyses.append((p, d))
if not analyses:
raise SystemExit("No usable *.analysis.json with scenes was provided.")
primary_path, primary = pick_primary(analyses, args.primary)
scenes = primary.get("scenes", [])
if enriched_score(primary) == 0:
print(" ! WARNING: the primary analysis has no enriched camera angles. "
"Run the video-scene-analysis agent vision pass first for accurate "
"angles; falling back to eye_level where missing.", file=sys.stderr)
# Avatar dir + measured style files.
avatar_dir = (Path(args.avatar_dir).expanduser().resolve()
if args.avatar_dir else C.infer_avatar_dir(primary_path))
trans_path = find_style_file(avatar_dir, args.transition_style, "transition_style.json")
subs_path = find_style_file(avatar_dir, args.subtitle_style, "subtitle_style.json")
prof_path = find_style_file(avatar_dir, args.talking_profile, "talking_profile.json")
transitions = C.try_load_json(trans_path) if trans_path else None
subtitle_style = C.try_load_json(subs_path) if subs_path else None
talking_profile = C.try_load_json(prof_path) if prof_path else None
# ---- Beats from the primary reel ----
total = sum(float(s.get("duration") or 0) for s in scenes) or 1.0
n = len(scenes)
beats = []
sfx_count = 0
has_music = False
for i, s in enumerate(scenes):
btype = beat_type(s)
cam = s.get("camera") or {}
audio = s.get("audio") or {}
summ = s.get("summary") or {}
zoom = (s.get("zoom_from_previous") or {}).get("type") or "none"
sfx_count += int(audio.get("sfx_event_count") or 0)
has_music = has_music or bool(audio.get("has_music_bed"))
beat = {
"index": i,
"role": derive_role(i, n, summ.get("focus")),
"type": btype,
"dur_weight": round(float(s.get("duration") or 0) / total, 4),
"zoom_from_previous": zoom,
"emphasis": beat_emphasis(s),
"has_sfx": bool(audio.get("has_sfx")),
"audio_profile": audio.get("audio_profile"),
"focus": summ.get("focus"),
}
if btype == "talking_head":
angle = cam.get("angle") or "eye_level"
if angle == "none":
angle = "eye_level"
beat["camera_angle"] = angle
beat["framing"] = cam.get("framing")
beat["move"] = move_for_angle(angle)
else:
beat["camera_angle"] = None
beat["broll_camera"] = broll_camera_for(zoom)
# A generic seed only; B-roll content MUST be re-authored per script.
beat["broll_hint"] = summ.get("focus") or (s.get("transcript") or "").strip()[:160]
beats.append(beat)
th = sum(1 for b in beats if b["type"] == "talking_head")
broll = n - th
avg = total / n
angles = needed_moves([b["camera_angle"] for b in beats if b["type"] == "talking_head"])
# ---- SFX density ----
sfx_density = round(total / sfx_count, 1) if sfx_count > 0 else 15.0
# ---- Captions ----
captions = {
"style_from": C.rel_to(subs_path, base) if subs_path else None,
"subtitle_style": subtitle_style, # embedded copy so the template is portable
}
words_per_caption = (subtitle_style or {}).get("words_per_caption", 6) or 6
# ---- Transitions (embed measured profile, else default) ----
if transitions:
transitions = dict(transitions)
transitions["_style_from"] = C.rel_to(trans_path, base) if trans_path else None
else:
transitions = dict(DEFAULT_TRANSITIONS)
# ---- Delivery seed (STYLE only, not identity) ----
delivery_seed = None
if talking_profile:
delivery_seed = talking_profile.get("mannerisms_summary") or talking_profile.get("video_prompt")
template = {
"version": 1,
"_comment": (
"Script-agnostic reel template extracted by reel-restyle. Re-apply it "
"to a NEW avatar + voice + script with apply_template.py. Structure "
"(beats/angles/transitions/SFX/captions/pacing) transfers; scene "
"DURATIONS do not -- the composer derives them from the new narration."
),
"extracted_at": datetime.now(timezone.utc).astimezone().isoformat(timespec="seconds"),
"source": {
"avatar": avatar_dir.name if avatar_dir else None,
"primary_analysis": C.rel_to(primary_path, base),
"analyses": [C.rel_to(p, base) for p, _ in analyses],
"transition_style": C.rel_to(trans_path, base) if trans_path else None,
"subtitle_style": C.rel_to(subs_path, base) if subs_path else None,
"talking_profile": C.rel_to(prof_path, base) if prof_path else None,
},
"summary": {
"total_scenes": n,
"talking_head": th,
"broll": broll,
"total_duration": round(total, 2),
"avg_scene_dur": round(avg, 2),
"cut_rhythm": cut_rhythm(avg),
"narrative_arc": [b["role"] for b in beats],
},
"angles_needed": angles,
"beats": beats,
"transitions": transitions,
"sfx": {
"density_sec": sfx_density,
"events": ["whoosh_before_broll", "boom_on_emphasis"],
"_note": "Soft whoosh leading each B-roll cut + soft low boom on emphasis "
"scenes; density measured from the reference reel.",
},
"captions": captions,
"music": {
"mood": "ambient",
"include": True,
"detected_music_bed": bool(has_music),
"prompt_hint": DEFAULT_MUSIC_PROMPT,
"words_per_caption": words_per_caption,
},
"delivery_style_seed": delivery_seed,
}
return template
def main():
ap = argparse.ArgumentParser(
description="Distill a reusable reel template from a reference avatar's analysis.",
formatter_class=argparse.ArgumentDefaultsHelpFormatter,
)
ap.add_argument("analysis", nargs="+", help="One or more enriched *.analysis.json files")
ap.add_argument("--primary", type=Path, default=None,
help="Which analysis defines the beat structure (default: richest/longest)")
ap.add_argument("--avatar-dir", default=None,
help="Reference avatar folder (auto-inferred from the analysis path)")
ap.add_argument("--transition-style", default=None, help="Override transition_style.json path")
ap.add_argument("--subtitle-style", default=None, help="Override subtitle_style.json path")
ap.add_argument("--talking-profile", default=None, help="Override talking_profile.json path")
ap.add_argument("--base-dir", default=".", help="Base for relative paths stored in the template")
ap.add_argument("--output", "-o", default=None,
help="Where to write reel_template.json (default: <avatar>/reel_template.json or ./reel_template.json)")
args = ap.parse_args()
template = build_template(args)
base = Path(args.base_dir).expanduser().resolve()
if args.output:
out = Path(args.output).expanduser()
else:
avatar = template["source"]["avatar"]
avatar_dir = (Path(args.avatar_dir).expanduser() if args.avatar_dir
else (base / avatar) if avatar else base)
out = Path(avatar_dir) / "reel_template.json"
C.save_json(out, template)
s = template["summary"]
print(f"\n Reel template written: {out}", file=sys.stderr)
print(f" {s['total_scenes']} beats ({s['talking_head']} talking-head, "
f"{s['broll']} B-roll) | {s['total_duration']}s | avg {s['avg_scene_dur']}s "
f"({s['cut_rhythm']}) | angles: {', '.join(template['angles_needed']) or 'none'}",
file=sys.stderr)
print(json.dumps({
"template": str(out),
"avatar": template["source"]["avatar"],
"beats": s["total_scenes"],
"angles_needed": template["angles_needed"],
"narrative_arc": s["narrative_arc"],
}, ensure_ascii=False))
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: 196k | 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: 196k | 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: 196k | Updated | Claude CodeCodex | Verified | Install |