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/create_avatar.py
View on GitHub#!/usr/bin/env python3
"""Stage 0 -- create a ready-to-compose avatar from a public Instagram profile.
Orchestrates the whole avatar-setup chain with IDEMPOTENT RESUME. Each stage
skips itself when its outputs already exist, so re-running picks up where it
left off (and after the two agent-only checkpoints below):
download instagram-videos -> <avatar>/videos/*.mp4
analyze video-scene-analysis -> <avatar>/videos/*.analysis.json (+ *_frames/)
[CHECKPOINT] AGENT vision enrichment of each analysis (avatar_profile.video_prompt)
frames avatar-frames -> <avatar>/frames/ + subtitle_style.json
voice voice-isolate + voice-clone -> <avatar>/voices/
transitions profile_transitions.py -> <avatar>/transition_style.json
profile export_talking_profile.py -> <avatar>/talking_profile.json
report -> <avatar>/avatar.json + readiness table
Two steps are NOT scriptable -- they need the agent:
1. Scraping the Picnob feed via the browser MCP (see the instagram-videos
SKILL) to produce the posts JSON this script downloads from.
2. Vision enrichment of each *.analysis.json (camera/framing, focus/emotion,
mannerisms and the reusable avatar_profile.video_prompt/negative_prompt),
per the video-scene-analysis SKILL.
The orchestrator detects both by inspecting outputs and stops with precise
instructions; re-run to continue.
Examples:
# after the agent saved posts-raw/meta/picnob_<handle>.json via the browser:
python3 create_avatar.py mara --handle mara_therapy
# ...enrich the analyses, then re-run to finish:
python3 create_avatar.py mara
# inspect readiness without running (zero API spend):
python3 create_avatar.py lolo --status
"""
from __future__ import annotations
import argparse
import os
import re
import shutil
import sys
from datetime import datetime, timezone
from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parent))
import _arc_common as C # noqa: E402
def resolve_avatar_dir(raw: str) -> Path:
"""Route a bare avatar name under ./avatares/ so onboarded 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()
# --- Sibling scripts (resolved against the project-local or user skills root) -
DOWNLOAD_VIDEOS = C.HOME_SKILLS / "instagram-videos/scripts/download_profile_videos.py"
ANALYZE_VIDEO = C.HOME_SKILLS / "video-scene-analysis/scripts/analyze_video.py"
EXPORT_PROFILE = C.HOME_SKILLS / "video-scene-analysis/scripts/export_talking_profile.py"
EXTRACT_FRAMES = C.HOME_SKILLS / "avatar-frames/scripts/extract_clean_frames.py"
EXTRACT_VOICE = C.HOME_SKILLS / "voice-isolate/scripts/extract_voice.py"
CLONE_VOICE = C.HOME_SKILLS / "voice-clone/scripts/clone_voice.py"
PROFILE_TRANSITIONS = C.SCRIPT_DIR / "profile_transitions.py"
PY = sys.executable or "python3"
# ---------------------------------------------------------------------------
# Context
# ---------------------------------------------------------------------------
class Ctx:
def __init__(self, args):
self.avatar_dir = resolve_avatar_dir(args.avatar_dir)
self.videos_dir = self.avatar_dir / "videos"
self.frames_dir = self.avatar_dir / "frames"
self.handle = _clean_handle(args.handle) or self.avatar_dir.name
self.posts_json = Path(args.posts_json).expanduser() if args.posts_json else None
self.timezone = args.timezone
self.language = args.language
self.voice_video = args.voice_video
self.force = set(args.force_stage or [])
def _clean_handle(h):
if not h:
return None
m = re.search(r"instagram\.com/([^/?#]+)", h)
if m:
h = m.group(1)
return h.strip("/@ ").strip() or None
# ---------------------------------------------------------------------------
# Inventory helpers
# ---------------------------------------------------------------------------
def _videos(ctx) -> list[Path]:
if not ctx.videos_dir.is_dir():
return []
return sorted(ctx.videos_dir.glob("*.mp4"))
def _analysis_path(video: Path) -> Path:
return video.parent / f"{video.stem}.analysis.json"
def _analyses(ctx) -> list[Path]:
if not ctx.videos_dir.is_dir():
return []
return sorted(ctx.videos_dir.glob("*.analysis.json"))
def _enriched_analyses(ctx) -> list[Path]:
"""Analyses the agent has enriched with a usable avatar_profile.video_prompt."""
out = []
for a in _analyses(ctx):
try:
d = C.load_json(a)
except (ValueError, OSError):
continue
if (d.get("avatar_profile") or {}).get("video_prompt"):
out.append(a)
return out
# ---------------------------------------------------------------------------
# Stage: done predicates
# ---------------------------------------------------------------------------
def done_download(ctx) -> bool:
return bool(_videos(ctx))
def done_analyze(ctx) -> bool:
# At least one analyzed reel is enough to derive the avatar's profiles; you
# don't need to analyze every downloaded video (e.g. lolo profiles from 3 of
# 10). On a FRESH avatar (zero analyses) run_analyze processes all of them.
return bool(_analyses(ctx))
def done_enrich(ctx) -> bool:
return bool(_enriched_analyses(ctx))
def done_frames(ctx) -> bool:
return (ctx.frames_dir / "manifest.json").exists()
def done_voice(ctx) -> bool:
voices = ctx.avatar_dir / "voices"
idx = voices / "index.json"
if idx.exists():
try:
d = C.load_json(idx)
if isinstance(d, dict) and any((v or {}).get("voice_id") for v in d.values()):
return True
except (ValueError, OSError):
pass
if voices.is_dir():
return any(p.name != "index.json" for p in voices.glob("*.json"))
return False
def done_transitions(ctx) -> bool:
return (ctx.avatar_dir / "transition_style.json").exists()
def done_profile(ctx) -> bool:
return (ctx.avatar_dir / "talking_profile.json").exists()
# ---------------------------------------------------------------------------
# Stage: run functions
# ---------------------------------------------------------------------------
def run_download(ctx):
posts = ctx.posts_json
if posts is None and ctx.handle:
posts = Path(f"posts-raw/meta/picnob_{ctx.handle}.json")
if not posts or not Path(posts).exists():
_stop(
"AGENT STEP NEEDED -- scrape the Instagram profile first.",
[
f"This avatar has no videos in {ctx.videos_dir} and no posts JSON "
f"was found"
+ (f" at {posts}." if posts else " (pass --handle or --posts-json)."),
"",
"Per the instagram-videos SKILL, using the browser MCP:",
f" 1. Confirm https://www.instagram.com/{ctx.handle}/ is PUBLIC.",
f" 2. Open https://www.picnob.com/profile/{ctx.handle}/ and run the",
" scroll+collect snippet to gather every .post_box.",
f" 3. Save the resulting array to posts-raw/meta/picnob_{ctx.handle}.json",
" 4. Re-run this command to download + continue.",
],
)
cmd = [PY, str(DOWNLOAD_VIDEOS), "--posts-json", str(posts),
"--output-dir", str(ctx.videos_dir), "--timezone", ctx.timezone]
C.run_cli_json(cmd, desc=f"instagram-videos: download @{ctx.handle}")
if not _videos(ctx):
raise SystemExit("download produced no .mp4 files -- check the posts JSON.")
def run_analyze(ctx):
pending = [v for v in _videos(ctx) if not _analysis_path(v).exists()]
if not pending:
return
for v in pending:
cmd = [PY, str(ANALYZE_VIDEO), str(v), "-o", str(ctx.videos_dir)]
if ctx.language:
cmd += ["--language", ctx.language]
C.run_cli_json(cmd, desc=f"video-scene-analysis: {v.name}")
if not _analysis_path(v).exists():
raise SystemExit(f"analysis not produced for {v.name}")
def run_frames(ctx):
vids = _videos(ctx)
if not vids:
raise SystemExit("no videos for frame extraction.")
fdir = ctx.frames_dir
fdir.mkdir(parents=True, exist_ok=True)
ready_records, by_video = [], {}
best_style, best_samples = None, -1
seq = 0
ocr_langs = f"{ctx.language},en" if ctx.language else None
for v in vids:
tmp = fdir / f".tmp_{v.stem}"
if tmp.exists():
shutil.rmtree(tmp, ignore_errors=True)
cmd = [PY, str(EXTRACT_FRAMES), str(v), "-o", str(tmp)]
if ocr_langs:
cmd += ["--ocr-langs", ocr_langs]
C.run_cli_json(cmd, desc=f"avatar-frames: {v.name}")
man_p = tmp / "manifest.json"
man = C.load_json(man_p) if man_p.exists() else {}
for entry in man.get("frames", []):
src = Path(entry.get("path", ""))
if not src.exists():
src = tmp / entry.get("file", "")
if not src.exists():
continue
seq += 1
dst = fdir / f"frame_{seq:04d}.png"
shutil.copy2(src, dst)
ready_records.append({
"seq": seq,
"file": dst.name,
"source_video": v.name,
"timestamp": entry.get("timestamp"),
"timestamp_fmt": entry.get("timestamp_fmt"),
"sharpness": entry.get("sharpness"),
"face_sharpness": entry.get("face_sharpness"),
"size": entry.get("size"),
"face": entry.get("face"),
})
style = man.get("subtitle_style")
if style and style.get("samples", 0) > best_samples:
best_style, best_samples = style, style.get("samples", 0)
by_video[v.name] = {
"frames_ready": man.get("frames_clean", len(man.get("frames", []))),
"frames_with_subtitles": man.get("frames_with_subtitles", 0),
}
shutil.rmtree(tmp, ignore_errors=True)
C.save_json(fdir / "manifest.json", {
"generated_at": datetime.now(timezone.utc).isoformat(),
"videos_processed": len(vids),
"output_dir": str(fdir),
"total_ready": len(ready_records),
"subtitle_style": best_style,
"frames": ready_records,
"by_video": by_video,
})
if best_style:
C.save_json(ctx.avatar_dir / "subtitle_style.json", best_style)
print(f" subtitle_style.json written ({best_samples} samples)", file=sys.stderr)
else:
print(" no burned-in captions detected -- subtitle_style.json not written "
"(captions will use the skill defaults).", file=sys.stderr)
print(f" frames: {len(ready_records)} reference frame(s) -> {fdir}", file=sys.stderr)
def _pick_voice_video(ctx) -> Path | None:
vids = _videos(ctx)
if not vids:
return None
if ctx.voice_video:
for v in vids:
if ctx.voice_video in (v.name, v.stem):
return v
raise SystemExit(f"--voice-video {ctx.voice_video!r} not found in {ctx.videos_dir}")
return max(vids, key=lambda v: C.ffprobe_duration(v))
def run_voice(ctx):
v = _pick_voice_video(ctx)
if not v:
raise SystemExit("no videos to extract a voice from.")
voice_dir = ctx.videos_dir / f"{v.stem}_voice"
concat = voice_dir / "voice_concat.mp3"
if not concat.exists():
cmd = [PY, str(EXTRACT_VOICE), str(v)]
if ctx.language:
cmd += ["--language", ctx.language]
C.run_cli_json(cmd, desc=f"voice-isolate: {v.name} (longest take)")
if not concat.exists():
raise SystemExit(f"voice-isolate did not produce {concat}")
C.run_cli_json(
[PY, str(CLONE_VOICE), str(concat), "--avatar-dir", str(ctx.avatar_dir)],
desc="voice-clone: train cloned voice",
)
if not done_voice(ctx):
raise SystemExit("voice-clone did not register a voice in voices/index.json")
def run_transitions(ctx):
analyses = _analyses(ctx)
if not analyses:
raise SystemExit("no analyses for transition profiling.")
cmd = [PY, str(PROFILE_TRANSITIONS)] + [str(a) for a in analyses] \
+ ["--out", str(ctx.avatar_dir / "transition_style.json")]
C.run_cli_json(cmd, desc="profile_transitions: measure scene-cut style")
def run_profile(ctx):
enriched = _enriched_analyses(ctx)
if not enriched:
raise SystemExit("no enriched analyses (avatar_profile.video_prompt missing).")
cmd = [PY, str(EXPORT_PROFILE)] + [str(a) for a in enriched] \
+ ["--avatar-dir", str(ctx.avatar_dir)]
C.run_cli_json(cmd, desc="export_talking_profile: write talking_profile.json")
# ---------------------------------------------------------------------------
# Stage table
# ---------------------------------------------------------------------------
# (name, done_fn, run_fn). run_fn=None marks the agent enrichment checkpoint.
STAGES = [
("download", done_download, run_download),
("analyze", done_analyze, run_analyze),
("enrich", done_enrich, None),
("frames", done_frames, run_frames),
("voice", done_voice, run_voice),
("transitions", done_transitions, run_transitions),
("profile", done_profile, run_profile),
]
def _stop(headline, lines):
print(f"\n ==> {headline}", file=sys.stderr)
for ln in lines:
print(f" {ln}", file=sys.stderr)
raise SystemExit(2)
def _enrichment_gate(ctx):
missing = [a.name for a in _analyses(ctx) if a not in set(_enriched_analyses(ctx))]
_stop(
"AGENT STEP NEEDED -- enrich the analyses, then re-run.",
[
"Each *.analysis.json must gain an `avatar_profile.video_prompt` (plus "
"per-scene camera/framing, focus/emotion and mannerisms) -- this is the",
"vision pass described in the video-scene-analysis SKILL. View each",
f"scene_XX.jpg under {ctx.videos_dir}/<stem>_frames/ and fill the fields.",
"",
"Analyses still missing avatar_profile.video_prompt:",
] + [f" - {m}" for m in missing] + [
"",
f"Then re-run: python3 create_avatar.py {ctx.avatar_dir.name}",
],
)
def write_report(ctx):
vids = _videos(ctx)
stage_status = {}
for name, done, _ in STAGES:
stage_status[name] = "complete" if done(ctx) else "pending"
ready = all(v == "complete" for v in stage_status.values())
report = {
"avatar": ctx.avatar_dir.name,
"handle": ctx.handle,
"updated_at": datetime.now(timezone.utc).astimezone().isoformat(),
"ready": ready,
"stages": stage_status,
"videos": [{"file": v.name, "duration_s": round(C.ffprobe_duration(v), 2)}
for v in vids],
# Paths are stored RELATIVE to the avatar folder so avatar.json stays
# portable across clones (no absolute machine paths in the repo).
"artifacts": {
"analyses": [f"videos/{a.name}" for a in _analyses(ctx)],
"frames_dir": "frames" if done_frames(ctx) else None,
"subtitle_style": _opt(ctx, "subtitle_style.json"),
"transition_style": _opt(ctx, "transition_style.json"),
"talking_profile": _opt(ctx, "talking_profile.json"),
"voices": _voice_ids(ctx),
},
}
C.save_json(ctx.avatar_dir / "avatar.json", report)
return report
def _opt(ctx, rel: str):
return rel if (ctx.avatar_dir / rel).exists() else None
def _voice_ids(ctx):
idx = ctx.avatar_dir / "voices" / "index.json"
if not idx.exists():
return []
try:
d = C.load_json(idx)
except (ValueError, OSError):
return []
return [v.get("voice_id") for v in d.values() if isinstance(v, dict) and v.get("voice_id")]
def print_table(ctx, report):
icon = {"complete": "[x]", "pending": "[ ]"}
print(f"\nAvatar '{report['avatar']}' (@{report['handle']}) -- "
f"{'READY' if report['ready'] else 'incomplete'}")
print(f" videos: {len(report['videos'])} | analyses: "
f"{len(report['artifacts']['analyses'])} | "
f"voices: {len(report['artifacts']['voices'])}")
for name, _, run in STAGES:
tag = " (agent)" if run is None else ""
print(f" {icon.get(report['stages'][name], '[ ]')} {name}{tag}")
print(f" report: {ctx.avatar_dir / 'avatar.json'}")
if report["ready"]:
print(f"\n Next: write a storyboard (see examples/storyboard.example.json) and run\n"
f" compose_reel.py {report['avatar']}/reels/NNN_slug/storyboard.json --finish")
# ---------------------------------------------------------------------------
# Main
# ---------------------------------------------------------------------------
def main():
ap = argparse.ArgumentParser(
description="Create a ready-to-compose avatar from a public Instagram profile.",
formatter_class=argparse.ArgumentDefaultsHelpFormatter,
)
ap.add_argument("avatar_dir", help="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("--handle", default=None,
help="Instagram handle or profile URL (default: avatar folder name)")
ap.add_argument("--posts-json", default=None,
help="Picnob posts JSON from the browser scrape "
"(default: posts-raw/meta/picnob_<handle>.json)")
ap.add_argument("--timezone", default="America/Santiago",
help="IANA timezone for downloaded filenames")
ap.add_argument("--language", default=None,
help="Language hint for analysis/voice (es, en, ...); auto if omitted")
ap.add_argument("--voice-video", default=None,
help="Video name/stem to clone the voice from (default: longest)")
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 without running anything")
args = ap.parse_args()
ctx = Ctx(args)
if args.status:
report = write_report(ctx)
print_table(ctx, report)
return 0
if not ctx.avatar_dir.exists():
ctx.avatar_dir.mkdir(parents=True, exist_ok=True)
print(f"Building avatar '{ctx.avatar_dir.name}' (@{ctx.handle})", file=sys.stderr)
for name, done, run in STAGES:
if run is None: # agent enrichment checkpoint
if not done(ctx):
_enrichment_gate(ctx)
print(f" [enrich] 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)
report = write_report(ctx)
print_table(ctx, report)
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: 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 |