Short vertical cut-paper explainer reels, made by your coding agent. Nine Agent Skills plus a Remotion library. Works with Claude Code, OpenCode, Codex, Gemini CLI, Cursor, Copilot and more.
TypeScript agent-skillsagents-mdclaude-codeclaude-code-skillscodexexplainer-videosgemini-cliopencodepapercutremotiontext-to-speechvideo-generation
# Butt the final narration lines together, write word captions and the scene plan. Config: episode.json
# {"narration": "../narration", "timing": "timing_narrator.js", "fps": 30, "start": 0.2, "gap": 0.22, "hold": 2.3,
# "scenes": [["S01Hook", "l1_hook", 0], ["S02Yes", "l1_hook", "and"], ...]} (first word: index or exact word)
# "hook": {...} (optional, see below)
# out: public/vo/voiceover.wav, public/vo/captions.json (Remotion Caption[]), src/plan.json
# usage (from the Remotion project dir): python3 $PAPERCUT_LIB/tools/build_vo.py
import json, os, subprocess, wave
EP = json.load(open("episode.json"))
SRC = EP.get("narration", "../narration")
FPS, START, GAP, HOLD = EP.get("fps", 30), EP.get("start", 0.2), EP.get("gap", 0.22), EP.get("hold", 2.3)
VO = json.loads(open(f"{SRC}/" + os.environ.get("VO_TIMING", EP.get("timing", "timing_narrator.js"))).read().split("const VO = ", 1)[1].rstrip().rstrip(";"))
SCENES = [tuple(s) for s in EP["scenes"]]
GAPS = EP.get("gaps", {})
words, t, parts, line_at = [], START, [], {}
for lid in VO["order"]:
seg = VO["seg"][lid]
w = wave.open(f"{SRC}/{seg['file']}"); dur = w.getnframes() / w.getframerate()
line_at[lid] = (t, len(words))
for x in seg["words"]:
words.append({"text": x["w"], "startMs": round((t + x["s"]) * 1000), "endMs": round((t + x["e"]) * 1000), "line": lid})
parts.append((seg["file"], t)); t += dur + GAP + GAPS.get(lid, 0) # "gaps": {"l7_setup": 0.3} = an extra beat after a line
total = t - GAP + HOLD
os.makedirs("public/vo", exist_ok=True)
inp, flt = [], []
for k, (f, at) in enumerate(parts):
inp += ["-i", f"{SRC}/{f}"]; ms = int(round(at * 1000))
flt.append(f"[{k}:a]aresample=48000,adelay={ms}[a{k}]")
flt.append("".join(f"[a{k}]" for k in range(len(parts))) + f"amix=inputs={len(parts)}:normalize=0,apad,atrim=0:{total:.3f}[o]")
subprocess.run(["ffmpeg", "-v", "error", "-y", *inp, "-filter_complex", ";".join(flt), "-map", "[o]", "-ac", "1", "public/vo/voiceover.wav"], check=True)
# silent music/fx placeholders until audio/render.mjs writes the real ones, so scene agents' qa.sh renders work
os.makedirs("public/audio", exist_ok=True)
for a in ("music", "fx"):
if not os.path.exists(f"public/audio/{a}.wav"):
subprocess.run(["ffmpeg", "-v", "error", "-f", "lavfi", "-i", "anullsrc=r=48000:cl=stereo", "-t", f"{total:.3f}", f"public/audio/{a}.wav"], check=True)
caps = [{"text": (" " if i else "") + w["text"], "startMs": w["startMs"], "endMs": w["endMs"], "timestampMs": (w["startMs"] + w["endMs"]) // 2, "confidence": 1}
for i, w in enumerate(words)]
json.dump(caps, open("public/vo/captions.json", "w"))
starts = []
for sid, lid, first in SCENES:
base = line_at[lid][1]; lw = [w for w in words if w["line"] == lid]
idx = first if isinstance(first, int) else next(i for i, w in enumerate(lw) if w["text"] == first)
starts.append(base + idx)
cut = [0] + [round((words[i]["startMs"] / 1000 - 0.08) * FPS) for i in starts[1:]] + [round(total * FPS)]
plan = {"fps": FPS, "durationInFrames": cut[-1], "scenes": []}
for k, (sid, lid, _) in enumerate(SCENES):
a, b = cut[k], cut[k + 1]
ws = [{"text": w["text"], "f": round(w["startMs"] / 1000 * FPS) - a, "e": round(w["endMs"] / 1000 * FPS) - a}
for w in words if a <= round(w["startMs"] / 1000 * FPS) < b]
plan["scenes"].append({"id": sid, "from": a, "durationInFrames": b - a, "words": ws})
# Optional hook title (the cover text on screen from frame 0; see kit/paper/hook.tsx):
# "hook": {"lines": [["AI", "LEAKED"], ["13,000+"]], "hot": ["13,000+"], "until": "yes" | ["yes", 2], "size": 108, "top": 220}
# It leaves at the onset of the `until` word (its n-th occurrence), or after "hold" seconds (default 2.4).
H = EP.get("hook")
if H:
if "until" in H:
uw, un = (H["until"], 1) if isinstance(H["until"], str) else H["until"]
hits = [w for w in words if w["text"].strip(".,!?;:'\"").lower() == uw.lower()]
out = round(hits[un - 1]["startMs"] / 1000 * FPS)
else:
out = round(H.get("hold", 2.4) * FPS)
plan["hook"] = {**{k: v for k, v in H.items() if k not in ("until", "hold")}, "outAt": out}
print(f"hook title until frame {out} ({out / FPS:.2f}s)")
json.dump(plan, open("src/plan.json", "w"), indent=1)
for s in plan["scenes"]:
flag = " <-- under 1.2 s: merge it into a neighbour" if s["durationInFrames"] < 36 else ""
print(f"{s['id']:16s} {s['from']/FPS:6.2f}s {s['durationInFrames']/FPS:4.2f}s " + " ".join(f"{w['text']}@{w['f']}" for w in s["words"]) + flag)
print("total", round(total, 2), "s", cut[-1], "frames")