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/scaffold_avatar.py
View on GitHub#!/usr/bin/env python3
"""Scaffold a NEW avatar from raw inputs so a reel template can be applied to it.
Given a reel_template.json (from extract_template.py), a single avatar PICTURE,
a raw VOICE sample and a name, this builds exactly the assets the
avatar-reel-composer needs -- with IDEMPOTENT RESUME (each stage skips itself
when its outputs already exist):
picture copy the reference picture -> <avatar>/refs/<file>
[author] AGENT writes scene.json + talking_profile.json (vision checkpoint)
angles avatar-camera-angles -> <avatar>/angles/<slug>_<move>_916.png
(or ..._169.png for --format landscape / 16:9 YouTube)
voice voice-clone -> <avatar>/voices/ (+ voice_id)
styles copy reference transition/subtitle styles -> <avatar>/{transition,subtitle}_style.json
One step is NOT scriptable -- it needs the agent's vision:
[author] Look at the picture and (a) describe scene.json
(subject/wardrobe/scene/light, per avatar-camera-angles) and
(b) write talking_profile.json (video_prompt describing the NEW
person + delivery seeded from the template's delivery_style_seed).
The orchestrator detects this by inspecting outputs and stops with precise
instructions; re-run to continue.
Examples:
python3 scaffold_avatar.py mara --template lolo/reel_template.json \
--picture refs/mara.png --voice samples/mara_voice.wav
# ...after writing scene.json + talking_profile.json, re-run to finish:
python3 scaffold_avatar.py mara --template lolo/reel_template.json \
--picture refs/mara.png --voice samples/mara_voice.wav
python3 scaffold_avatar.py mara --template lolo/reel_template.json --status
"""
from __future__ import annotations
import argparse
import os
import shutil
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
SCENE_FIELDS = ("subject", "wardrobe", "scene", "light")
def resolve_avatar_dir(raw: str) -> Path:
"""Route a bare avatar name under ./avatares/ so scaffolded avatars don't
clutter the project root. An explicit path (containing a separator or
absolute) is respected as-is. Override the root with AVATARES_ROOT."""
p = Path(raw).expanduser()
seps = os.sep + (os.altsep or "")
if not p.is_absolute() and not any(s in raw for s in seps):
p = Path(os.environ.get("AVATARES_ROOT") or "avatares") / raw
return p.resolve()
# ---------------------------------------------------------------------------
# Context
# ---------------------------------------------------------------------------
class Ctx:
def __init__(self, args):
self.base_dir = Path(args.base_dir).expanduser().resolve()
self.avatar_dir = resolve_avatar_dir(args.avatar_dir)
self.refs_dir = self.avatar_dir / "refs"
self.angles_dir = self.avatar_dir / "angles"
self.name = args.name or self.avatar_dir.name
self.slug = self.avatar_dir.name
self.picture = Path(args.picture).expanduser().resolve() if args.picture else None
self.voice = Path(args.voice).expanduser().resolve() if args.voice else None
self.scene_file = (Path(args.scene_file).expanduser().resolve()
if args.scene_file else self.avatar_dir / "scene.json")
self.language = args.language
self.quality = args.quality
self.fmt = args.format
self.angle_suffix = C.angle_suffix(self.fmt)
self.angle_crop_flag = C.angle_crop_flag(self.fmt)
self.force = set(args.force_stage or [])
self.template_path = Path(args.template).expanduser().resolve()
self.template = C.load_json(self.template_path)
self.moves = list(self.template.get("angles_needed") or [])
# ---------------------------------------------------------------------------
# done predicates
# ---------------------------------------------------------------------------
def done_picture(ctx) -> bool:
return C.first_image(ctx.refs_dir) is not None
def _scene_ok(ctx) -> bool:
d = C.try_load_json(ctx.scene_file)
return bool(d) and all((d.get(k) or "").strip() for k in SCENE_FIELDS)
def _profile_ok(ctx) -> bool:
d = C.try_load_json(ctx.avatar_dir / "talking_profile.json")
return bool(d) and bool((d or {}).get("video_prompt"))
def done_author(ctx) -> bool:
return _scene_ok(ctx) and _profile_ok(ctx)
def _angle_file(ctx, move) -> Path:
return ctx.angles_dir / f"{ctx.slug}_{move}{ctx.angle_suffix}.png"
def missing_moves(ctx) -> list[str]:
return [m for m in ctx.moves if not _angle_file(ctx, m).exists()]
def done_angles(ctx) -> bool:
return bool(ctx.moves) and not missing_moves(ctx)
def done_voice(ctx) -> bool:
idx = C.try_load_json(ctx.avatar_dir / "voices" / "index.json")
if isinstance(idx, dict) and any((v or {}).get("voice_id") for v in idx.values()):
return True
vdir = ctx.avatar_dir / "voices"
return vdir.is_dir() and any(p.name != "index.json" for p in vdir.glob("*.json"))
def done_styles(ctx) -> bool:
return (ctx.avatar_dir / "transition_style.json").exists()
# ---------------------------------------------------------------------------
# run functions
# ---------------------------------------------------------------------------
def run_picture(ctx):
if not ctx.picture:
C.stop("INPUT NEEDED -- no reference picture.", [
f"This avatar has no image in {ctx.refs_dir}.",
"Pass --picture <png|jpg> (a sharp, front-ish portrait of the new avatar).",
])
if not ctx.picture.exists():
raise SystemExit(f"picture not found: {ctx.picture}")
ctx.refs_dir.mkdir(parents=True, exist_ok=True)
dst = ctx.refs_dir / ctx.picture.name
if dst.resolve() != ctx.picture.resolve():
shutil.copy2(ctx.picture, dst)
print(f" reference picture: {dst}", file=sys.stderr)
def author_gate(ctx):
seed = ctx.template.get("delivery_style_seed") or "(no delivery seed in template)"
lines = [
"Look at the avatar PICTURE and write TWO files, then re-run to continue:",
"",
f"1) {ctx.scene_file} -- subject/wardrobe/scene/light of the NEW avatar,",
" exactly as the avatar-camera-angles skill expects, e.g.:",
' { "subject": "...", "wardrobe": "...", "scene": "...", "light": "..." }',
"",
f"2) {ctx.avatar_dir / 'talking_profile.json'} -- p-video-avatar prompts for",
" the NEW person (a DIFFERENT identity). Describe THIS person's look, then",
" carry over the reference's DELIVERY style (calm, addressing the lens, etc):",
' { "video_prompt": "...", "negative_prompt": "...", "mannerisms_summary": "..." }',
"",
" Reference delivery style to emulate (do NOT copy the identity):",
f" {seed}",
]
if not _scene_ok(ctx):
lines.append("")
lines.append(f" MISSING/incomplete: {ctx.scene_file}")
if not _profile_ok(ctx):
lines.append(f" MISSING/incomplete: {ctx.avatar_dir / 'talking_profile.json'} (needs video_prompt)")
C.stop("AGENT STEP NEEDED -- describe the new avatar (vision), then re-run.", lines)
def run_angles(ctx):
if not ctx.moves:
print(" template has no angles_needed -- skipping angle generation.", file=sys.stderr)
return
ref = C.first_image(ctx.refs_dir)
if not ref:
raise SystemExit("no reference picture in refs/ (run the picture stage first).")
todo = missing_moves(ctx)
if not todo:
return
ctx.angles_dir.mkdir(parents=True, exist_ok=True)
cmd = [C.PY, str(C.GENERATE_ANGLES),
"--ref", str(ref),
"--scene-file", str(ctx.scene_file),
"--slug", ctx.slug,
"-o", str(ctx.angles_dir),
ctx.angle_crop_flag, "--quality", ctx.quality]
for m in todo:
cmd += ["--move", m]
rc, _ = C.run_child_json(cmd, desc=f"avatar-camera-angles: {', '.join(todo)}")
if rc != 0:
raise SystemExit(f"angle generation failed (exit {rc}).")
still_missing = missing_moves(ctx)
if still_missing:
raise SystemExit(f"angle stills not produced for: {', '.join(still_missing)}")
def run_voice(ctx):
if not ctx.voice:
C.stop("INPUT NEEDED -- no voice sample.", [
f"This avatar has no cloned voice in {ctx.avatar_dir / 'voices'}.",
"Pass --voice <wav|mp3|m4a> (10s-5min of clean speech of the new avatar).",
])
if not ctx.voice.exists():
raise SystemExit(f"voice file not found: {ctx.voice}")
cmd = [C.PY, str(C.CLONE_VOICE), str(ctx.voice),
"--avatar-dir", str(ctx.avatar_dir), "--name", ctx.name]
rc, _ = C.run_child_json(cmd, desc="voice-clone: train cloned voice")
if rc != 0:
raise SystemExit(f"voice cloning failed (exit {rc}).")
if not done_voice(ctx):
raise SystemExit("voice-clone did not register a voice in voices/index.json")
def _copy_style(ctx, src_rel, embedded, dst_name) -> bool:
dst = ctx.avatar_dir / dst_name
if src_rel:
src = C.resolve_path(src_rel, ctx.base_dir)
if src.exists():
shutil.copy2(src, dst)
print(f" {dst_name}: copied from {src}", file=sys.stderr)
return True
if embedded:
C.save_json(dst, embedded)
print(f" {dst_name}: written from embedded template copy", file=sys.stderr)
return True
return False
def run_styles(ctx):
src = ctx.template.get("source", {}) or {}
caps = ctx.template.get("captions", {}) or {}
if not _copy_style(ctx, src.get("transition_style"),
ctx.template.get("transitions"), "transition_style.json"):
print(" ! no transition style available -- polish will use composer defaults.",
file=sys.stderr)
if not _copy_style(ctx, src.get("subtitle_style"),
caps.get("subtitle_style"), "subtitle_style.json"):
print(" ! no subtitle style available -- captions will use composer defaults.",
file=sys.stderr)
# ---------------------------------------------------------------------------
# Stage table (name, done_fn, run_fn). run_fn=None => agent checkpoint.
# ---------------------------------------------------------------------------
STAGES = [
("picture", done_picture, run_picture),
("author", done_author, None),
("angles", done_angles, run_angles),
("voice", done_voice, run_voice),
("styles", done_styles, run_styles),
]
def write_report(ctx) -> dict:
stage_status = {name: ("complete" if done(ctx) else "pending") for name, done, _ in STAGES}
ready = all(v == "complete" for v in stage_status.values())
report = {
"avatar": ctx.avatar_dir.name,
"name": ctx.name,
"updated_at": datetime.now(timezone.utc).astimezone().isoformat(timespec="seconds"),
"ready": ready,
"template": C.rel_to(ctx.template_path, ctx.base_dir),
"stages": stage_status,
"angles_needed": ctx.moves,
"artifacts": {
"scene": "scene.json" if _scene_ok(ctx) else None,
"talking_profile": "talking_profile.json" if _profile_ok(ctx) else None,
"angles": [f"angles/{ctx.slug}_{m}{ctx.angle_suffix}.png" for m in ctx.moves
if _angle_file(ctx, m).exists()],
"voices": _voice_ids(ctx),
"transition_style": "transition_style.json"
if (ctx.avatar_dir / "transition_style.json").exists() else None,
"subtitle_style": "subtitle_style.json"
if (ctx.avatar_dir / "subtitle_style.json").exists() else None,
},
}
C.save_json(ctx.avatar_dir / "restyle_avatar.json", report)
return report
def _voice_ids(ctx):
idx = C.try_load_json(ctx.avatar_dir / "voices" / "index.json")
if not isinstance(idx, dict):
return []
return [v.get("voice_id") for v in idx.values() if isinstance(v, dict) and v.get("voice_id")]
def print_table(ctx, report):
icon = {"complete": "[x]", "pending": "[ ]"}
print(f"\nAvatar '{report['avatar']}' -- {'READY' if report['ready'] else 'incomplete'}",
file=sys.stderr)
for name, _, run in STAGES:
tag = " (agent)" if run is None else ""
print(f" {icon.get(report['stages'][name], '[ ]')} {name}{tag}", file=sys.stderr)
print(f" report: {ctx.avatar_dir / 'restyle_avatar.json'}", file=sys.stderr)
def main():
ap = argparse.ArgumentParser(
description="Scaffold a new avatar from a picture + voice for a reel template.",
formatter_class=argparse.ArgumentDefaultsHelpFormatter,
)
ap.add_argument("avatar_dir", help="New avatar to build. A bare name goes under ./avatares/<name>; an explicit path is used as-is (e.g. mara, avatares/mara, path/to/mara)")
ap.add_argument("--template", required=True, help="reel_template.json from extract_template.py")
ap.add_argument("--picture", default=None, help="Reference portrait of the new avatar")
ap.add_argument("--voice", default=None, help="Clean voice sample of the new avatar (wav/mp3/m4a)")
ap.add_argument("--name", default=None, help="Voice/avatar name (default: avatar folder name)")
ap.add_argument("--scene-file", default=None, help="scene.json path (default: <avatar>/scene.json)")
ap.add_argument("--language", default=None, help="Language hint (es, en, ...)")
ap.add_argument("--format", default="reel", choices=["reel", "post", "landscape"],
help="Target output format. Selects the angle crop: reel/post -> 9:16 "
"(_916.png), landscape -> 16:9 (_169.png) for YouTube.")
ap.add_argument("--quality", default="high", choices=["low", "medium", "high", "auto"],
help="Angle-image fidelity passed to avatar-camera-angles")
ap.add_argument("--base-dir", default=".", help="Base for resolving template-relative paths")
ap.add_argument("--force-stage", action="append", default=[],
choices=[s[0] for s in STAGES],
help="Re-run this stage even if complete (repeatable)")
ap.add_argument("--status", action="store_true", help="Print readiness and exit")
args = ap.parse_args()
ctx = Ctx(args)
if args.status:
print_table(ctx, write_report(ctx))
return 0
ctx.avatar_dir.mkdir(parents=True, exist_ok=True)
print(f"Scaffolding avatar '{ctx.avatar_dir.name}' from template "
f"{ctx.template.get('source', {}).get('avatar')}", file=sys.stderr)
for name, done, run in STAGES:
if run is None: # agent checkpoint
if not done(ctx):
author_gate(ctx)
print(f" [{name}] complete", file=sys.stderr)
continue
if done(ctx) and name not in ctx.force:
print(f" [{name}] already complete -- skipping", file=sys.stderr)
continue
print(f" [{name}] running...", file=sys.stderr)
run(ctx)
print_table(ctx, write_report(ctx))
return 0
if __name__ == "__main__":
raise SystemExit(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 |