Skip to content

puntorigen/avatar-skills / onboarding-script

onboarding-script

Verified

scripts/render_episode.py

View on GitHub
#!/usr/bin/env python3
"""Render episode beat sheets into the format-agnostic onboarding script package.

For each <slug>.episode.json, writes into --out:
  <slug>.script.md        human shooting script (beats, timing, VO, on-screen/demo, captions)
  <slug>.narration.txt    clean spoken VO only (feed voice-clone / avatar-reel-composer narrate.py)
  <slug>.reel.txt         avatar-video-reel plain-text script with [DEMO: url | intent] markers
  <slug>.storyboard.json  avatar-reel-composer storyboard scaffold (scene.text tiles the narration)
and (re)writes README.md — the series index, in order.

Pure stdlib.

    python3 render_episode.py onboarding/acme/episodes/*.episode.json --out onboarding/acme/scripts/
"""

from __future__ import annotations

import argparse
import json
import sys
from pathlib import Path

TALKING_MOTIONS = ["zoom_center", "push_in", "pull_out"]


def is_todo(text: str) -> bool:
    t = (text or "").strip()
    return not t or t.lower().startswith("todo")


def spoken_beats(ep: dict) -> list[dict]:
    """Beats that carry a voice-over (non-empty narration)."""
    return [b for b in ep.get("beats", []) if (b.get("narration") or "").strip()]


def md_escape(text: str) -> str:
    return (text or "").replace("|", "\\|").replace("\n", " ").strip()


def sanitize_demo_intent(text: str) -> str:
    # avatar-video-reel parses [DEMO: url | intent]; keep | and ] out of the intent.
    return (text or "").replace("|", "/").replace("]", ")").replace("\n", " ").strip()


# ---------------------------------------------------------------- narration.txt

def render_narration(ep: dict) -> str:
    parts = [(b.get("narration") or "").strip() for b in spoken_beats(ep)]
    return "\n\n".join(parts) + "\n"


# --------------------------------------------------------------------- reel.txt

def render_reel(ep: dict) -> str:
    lines: list[str] = []
    for b in spoken_beats(ep):
        narration = (b.get("narration") or "").strip()
        if b.get("kind") == "demo":
            demo = b.get("demo") or {}
            url = (demo.get("url") or "TODO_URL").strip() or "TODO_URL"
            intent = sanitize_demo_intent(demo.get("intent") or "TODO: demo intent")
            lines.append(f"[DEMO: {url} | {intent}]")
            lines.append(narration)
            lines.append("[/DEMO]")
        else:
            lines.append(narration)
        lines.append("")  # blank line between beats
    return "\n".join(lines).strip() + "\n"


# ---------------------------------------------------------------- storyboard.json

def render_storyboard(ep: dict) -> dict:
    scenes = []
    texts = []
    th_i = 0
    for i, b in enumerate(spoken_beats(ep), start=1):
        text = (b.get("narration") or "").strip()
        texts.append(text)
        kind = b.get("kind")
        sid = f"s{i}"
        if kind == "demo":
            demo = b.get("demo") or {}
            url = (demo.get("url") or "").strip()
            intent = (demo.get("intent") or "").strip()
            desc = intent or f"screen recording for {ep.get('title')}"
            if url:
                desc += f" (screen recording — e.g. broll-web-capture on {url})"
            scenes.append({
                "id": sid, "type": "broll", "text": text, "motion": "none",
                "broll_description": desc, "broll_camera": "push_in", "broll_action": "",
            })
        elif kind == "broll":
            scenes.append({
                "id": sid, "type": "broll", "text": text, "motion": "none",
                "broll_description": (b.get("broll") or f"B-roll for {ep.get('title')}"),
                "broll_camera": "push_in",
                "broll_action": "people/objects/UI, no presenter on camera",
            })
        else:  # talking_head
            motion = TALKING_MOTIONS[th_i % len(TALKING_MOTIONS)]
            th_i += 1
            scenes.append({
                "id": sid, "type": "talking_head", "text": text,
                "motion": motion, "angle": "eye_level",
                "emphasis": (i == 1),
            })
    return {
        "avatar_dir": "avatares/<AVATAR>",
        "slug": ep.get("slug"),
        "reference_analysis": None,
        "format": "reel",
        "resolution": "720p",
        "fps": 30,
        "voice": ep.get("voice") or {"emotion": "warm"},
        "language": ep.get("language", "en"),
        "script": " ".join(texts),
        "scenes": scenes,
        "_note": (
            "Set avatar_dir to a real avatar folder (see avatar-reel-composer). "
            "broll scenes are screen-capture/B-roll placeholders: keep the VO (text), "
            "and either refine broll_description or swap for a real screen recording "
            "(broll-web-capture / avatar-video-reel [DEMO])."
        ),
    }


# ----------------------------------------------------------------- script.md

def render_markdown(ep: dict) -> str:
    beats = ep.get("beats", []) or []
    total = sum(int(b.get("seconds", 0) or 0) for b in beats)
    lines: list[str] = []
    lines.append(f"# {ep.get('order', '?'):02d} · {ep.get('title', ep.get('slug'))}")
    lines.append("")
    lines.append(f"- **Company:** {ep.get('company_name') or ep.get('company') or '—'}"
                 f"  ·  **Audience:** {ep.get('audience', '—')}"
                 f"  ·  **Language:** {ep.get('language', '—')}")
    lines.append(f"- **Target:** {ep.get('target_seconds', '—')}s (beats sum to {total}s)")
    lines.append(f"- **Objective:** {ep.get('objective', '—')}")
    if ep.get("sources"):
        lines.append(f"- **Sources:** {', '.join(str(s) for s in ep['sources'])}")
    lines.append("")
    lines.append("| t | Beat | Kind | Spoken (VO) | On-screen / Demo | Caption |")
    lines.append("|---|------|------|-------------|------------------|---------|")
    clock = 0
    for b in beats:
        dur = int(b.get("seconds", 0) or 0)
        span = f"{clock}-{clock + dur}s"
        clock += dur
        kind = b.get("kind", "?")
        if kind == "demo":
            demo = b.get("demo") or {}
            on_screen = f"DEMO {demo.get('url', '')} — {demo.get('intent', '')}"
        elif kind == "broll":
            on_screen = f"B-ROLL: {b.get('broll', '')}"
        else:
            on_screen = b.get("on_screen", "")
        lines.append(
            f"| {span} | {b.get('id', '?')} | {kind} | {md_escape(b.get('narration', ''))} "
            f"| {md_escape(on_screen)} | {md_escape(b.get('caption', ''))} |"
        )
    lines.append("")
    lines.append("> Keep VO short and spoken (captions show one phrase at a time). "
                 "demo beats = voice-over spoken while the screen recording plays.")
    lines.append("")
    return "\n".join(lines)


# ----------------------------------------------------------------------- README

def render_index(episodes: list[tuple[dict, str]], company_name: str) -> str:
    lines: list[str] = []
    lines.append(f"# {company_name} — onboarding reel series")
    lines.append("")
    lines.append("Ordered onboarding video scripts. Each episode ships four files: the human "
                 "shooting script (`.script.md`), the clean narration (`.narration.txt`), an "
                 "[`avatar-video-reel`](../../../avatar-video-reel/SKILL.md) script "
                 "(`.reel.txt`, with `[DEMO]` markers) and an "
                 "[`avatar-reel-composer`](../../../avatar-reel-composer/SKILL.md) storyboard "
                 "(`.storyboard.json`).")
    lines.append("")
    for ep, stem in sorted(episodes, key=lambda x: x[0].get("order", 0)):
        secs = sum(int(b.get("seconds", 0) or 0) for b in ep.get("beats", []))
        lines.append(f"## {ep.get('order', '?'):02d}. {ep.get('title', stem)}  ·  ~{secs}s")
        if ep.get("objective"):
            lines.append("")
            lines.append(ep["objective"])
        lines.append("")
        lines.append(f"- Shooting script: [`{stem}.script.md`]({stem}.script.md)")
        lines.append(f"- Narration: [`{stem}.narration.txt`]({stem}.narration.txt)")
        lines.append(f"- avatar-video-reel: [`{stem}.reel.txt`]({stem}.reel.txt)")
        lines.append(f"- avatar-reel-composer: [`{stem}.storyboard.json`]({stem}.storyboard.json)")
        lines.append("")
    return "\n".join(lines)


def expand_inputs(paths: list[str]) -> list[Path]:
    files: list[Path] = []
    for p in paths:
        path = Path(p)
        if path.is_dir():
            files.extend(sorted(path.glob("*.episode.json")))
        elif path.exists():
            files.append(path)
        else:
            print(f"WARN  input not found: {p}", file=sys.stderr)
    # de-dup, preserve order
    seen, out = set(), []
    for f in files:
        if f not in seen:
            seen.add(f); out.append(f)
    return out


def main() -> int:
    ap = argparse.ArgumentParser(description="Render onboarding episode beat sheets into the script package.")
    ap.add_argument("episodes", nargs="+", help="episode.json file(s) or a directory of them")
    ap.add_argument("--out", type=Path, help="Output dir (default: <episodes-parent>/../scripts or the parent)")
    ap.add_argument("--no-index", action="store_true", help="Do not (re)write README.md")
    args = ap.parse_args()

    files = expand_inputs(args.episodes)
    if not files:
        print("ERROR: no episode.json inputs found", file=sys.stderr)
        return 1

    if args.out:
        out_dir = args.out
    else:
        parent = files[0].parent
        out_dir = (parent.parent / "scripts") if parent.name == "episodes" else parent
    out_dir.mkdir(parents=True, exist_ok=True)

    rendered: list[tuple[dict, str]] = []
    company_name = "Company"
    for f in files:
        try:
            ep = json.loads(f.read_text(encoding="utf-8"))
        except Exception as exc:  # noqa: BLE001
            print(f"ERROR: could not read {f}: {exc}", file=sys.stderr)
            continue
        stem = f.name.removesuffix(".episode.json").removesuffix(".json")
        company_name = ep.get("company_name") or ep.get("company") or company_name

        (out_dir / f"{stem}.script.md").write_text(render_markdown(ep), encoding="utf-8")
        (out_dir / f"{stem}.narration.txt").write_text(render_narration(ep), encoding="utf-8")
        (out_dir / f"{stem}.reel.txt").write_text(render_reel(ep), encoding="utf-8")
        (out_dir / f"{stem}.storyboard.json").write_text(
            json.dumps(render_storyboard(ep), ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
        print(f"  -> {out_dir}/{stem}.{{script.md,narration.txt,reel.txt,storyboard.json}}")
        rendered.append((ep, stem))

    if rendered and not args.no_index:
        (out_dir / "README.md").write_text(render_index(rendered, company_name), encoding="utf-8")
        print(f"  -> {out_dir}/README.md  ({len(rendered)} episodes)")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall