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
#!/usr/bin/env python3
# Placeholder narration: builds what voice/finalize.sh builds, from script.json alone, so a reel can be built and
# timed with no TTS installed. Re-voice later: swap the wavs, rerun finalize.sh, and the word cues follow.
# usage (from an episode's narration/ folder): python3 $PAPERCUT_LIB/tools/placeholder_vo.py [--wps 3.0] [--say [VOICE]]
# reads script.json [{"id": "l1_hook", "text": "..."}, ...]
# writes voice/final_narrator/<id>.wav silent by default; --say uses the macOS `say` voice (needs ffmpeg)
# timing_narrator.js the same format build_timing.py writes (tools/build_vo.py reads it)
# Word times are spread over the line by word length. --wps is the silent pace in words per second.
import argparse, json, os, platform, shutil, subprocess, sys, tempfile, wave
ap = argparse.ArgumentParser()
ap.add_argument("--wps", type=float, default=3.0)
ap.add_argument("--say", nargs="?", const="", default=None, metavar="VOICE")
ap.add_argument("--script", default="script.json")
ap.add_argument("--out", default="timing_narrator.js")
a = ap.parse_args()
if a.say is not None and (platform.system() != "Darwin" or not shutil.which("say")):
sys.exit("--say needs macOS")
script = json.load(open(a.script))
os.makedirs("voice/final_narrator", exist_ok=True)
SR = 48000
seg = {}
for ln in script:
words = ln["text"].split()
wav = f"voice/final_narrator/{ln['id']}.wav"
if a.say is None:
dur = len(words) / a.wps + 0.2
with wave.open(wav, "wb") as w:
w.setnchannels(1); w.setsampwidth(2); w.setframerate(SR)
w.writeframes(b"\x00\x00" * int(dur * SR))
else:
tmp = tempfile.mkdtemp(); aiff = os.path.join(tmp, "l.aiff")
subprocess.run(["say", *(["-v", a.say] if a.say else []), "-o", aiff, ln.get("tts", ln["text"])], check=True)
subprocess.run(["ffmpeg", "-v", "error", "-y", "-i", aiff, "-ac", "1", "-ar", str(SR), wav], check=True)
with wave.open(wav) as w: dur = w.getnframes() / w.getframerate()
shutil.rmtree(tmp)
weights = [len(x) + 2 for x in words]; total = sum(weights); t = 0.0; out = []
body = dur - 0.2 if a.say is None else dur
for x, wt in zip(words, weights):
d = body * wt / total
out.append({"w": x, "s": round(t, 3), "e": round(t + d, 3)}); t += d
seg[ln["id"]] = {"dur": round(dur, 3), "file": wav, "words": out}
open(a.out, "w").write("// generated by placeholder_vo.py\nconst VO = " + json.dumps({"order": [l["id"] for l in script], "seg": seg}) + ";\n")
print({k: v["dur"] for k, v in seg.items()}, "total", round(sum(v["dur"] for v in seg.values()), 1))