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.
Papercut library
A Remotion kit for short vertical (9:16) explainer reels in a cut-paper style, plus the scripts around it. The kit has paper components, 24 backdrops, camera moves, scene transitions and film-look layers. The audio folder has 79 sound effects and 8 music beds, all synthesised in code. The scripts scaffold an episode, time it to a voiceover, mix the sound, render it and pull reusable pieces back into the library.
The idea is that an episode is mostly choosing and configuring. Whoever builds it (you, or an agent following ../skills/papercut-explainer/SKILL.md) reads two short catalogs instead of the kit source, picks sounds and a music bed by name, reuses kit components and scene templates, and writes new code only for what the episode needs that the kit lacks.
Layout
library/
README.md HARVEST.md CHANGELOG.md
env.sh sourced by the scripts; fills the env vars below from ~/.config/papercut-explainer/config.env
new_episode.sh scaffold <series>/episodes/NN-slug/ (template project + synced kit + node_modules)
audio/
CATALOG.md every SFX and bed preset, one line each (generated)
engine.js Web Audio kit (noise, tone, pop, chime, pluck...) and one parametric music bed
sfx/<name>.js one file per effect, first line "// @sfx name | tags | sec | description | origin"
beds/<preset>.json music beds as data (bpm, instrument, chords, pattern, percussion...)
render.mjs cues.json + bed -> public/audio/music.wav + fx.wav (loads only the SFX the cues use)
papercut/
CATALOG.md every kit export with its props and a doc line (generated)
AGENT_BRIEF.md the brief a scene agent gets (what to read, file ownership, QA loop)
kit/ the Remotion kit; copied into each project as src/lib/
tokens.ts fonts.ts paper/ ui/ cast/ props/ scenes/ (scenes/ holds parametric scene templates)
template/ empty episode project (Root, PapercutVideo and scene.ts read episode.json)
public/ default paper textures, fonts and the backdrop images; copied into each project
backdrops-src/ React sources of the code-drawn backdrops, for redrawing or tweaking them
tools/ textures.py (procedural paper textures)
sync_kit.sh stubs.py re-sync the kit into a project; write scene stubs and index.ts from episode.json
tools/
build_vo.py narration lines + timing -> voiceover.wav, captions.json, src/plan.json
cues.py per-scene SFX rows -> tools/cues.json
render.sh render.py cached per-scene render -> out/<name>.mp4
mix.py qa.sh sheet.py audio mix, QA stills and labelled contact sheets
timing_md.py writes the "Timing" section of STORYBOARD.md from plan.json
capture.mjs screenshot a web page for the kit's RealShot component
placeholder_vo.py silent (or macOS `say`) narration, so a reel can be timed with no TTS
selftest.sh scaffold + build the bundled example (../examples/hello-reel), typecheck, render SFX and a still
catalog.py harvest.py regenerate the two catalogs; list what an episode should give back to the library
dialogue_timeline.py two-speaker dialogue -> timeline.json + vo.wav (no template for it ships here)
voice/ optional local voiceover pipeline, see voice/README.md
Quick start
Prerequisites.
- Node 20 or newer, and npm.
- ffmpeg and ffprobe on PATH.
rsyncfor the kit sync. - Python 3.10 or newer with numpy and Pillow (textures and contact sheets) and soundfile (audio mix).
- Chrome or Chromium for the audio render and
capture.mjs. SetCHROME_PATHif it is not in a usual macOS or Linux location. Remotion downloads its own headless browser for video. - Optional: Qwen3-TTS and a speech-to-text backend for the voice pipeline (
voice/README.md). Without them you can useplaceholder_vo.py, or record the narration yourself.
Setup.
git clone <this repo>
export PAPERCUT_LIB="$PWD/library"
../install.sh at the repo root can do the same setup for you (skill links, Python tools, optionally the voice venv). ./install.sh --doctor lists what it finds.
Make a first episode.
$PAPERCUT_LIB/new_episode.sh ~/videos/my-series 01-first Episode first-reel
cd ~/videos/my-series/episodes/01-first/papercut
npx remotion studio
A series is a folder that holds episodes/, and optionally voice/voice.json, papercut-assets/ (textures and props laid over the defaults in each project's public/) and SERIES.md (audience, voice and palette notes). new_episode.sh copies node_modules from $DONOR, else from the newest <series>/episodes/*/papercut/node_modules, else runs npm i.
An episode, step by step
Run these from the series folder unless noted.
$PAPERCUT_LIB/new_episode.sh . NN-slug CompId out-name- Research into
episodes/NN-slug/research/facts.md, then writenarration/script.jsonas[{"id": "l1_hook", "text": "..."}, ...]. - Narration takes:
$PAPERCUT_LIB/voice/narrate.sh voice/voice.json episodes/NN-slug/narration. One TTS process at a time. Skip this and step 4 withplaceholder_vo.pyor your own recording. - Pick takes, fix pace and write timing:
$PAPERCUT_LIB/voice/finalize.sh voice/voice.json episodes/NN-slug/narration episodes/NN-slug/narration/voice/takes/narrator [num.json]. - In
papercut/episode.json, setscenes(cuts on words),banners,bed,whipSceneand optionallyhook. Frompapercut/, runpython3 $PAPERCUT_LIB/papercut/stubs.py, thenpython3 $PAPERCUT_LIB/tools/build_vo.py. The second command flags any scene under 1.2 s. - Build the first scene and
STORYBOARD.mdyourself. Give each scene agent$PAPERCUT_LIB/papercut/AGENT_BRIEF.mdand its scene list. Each agent also writes its SFX rows totools/cue_sheet.d/<Scene>.json. - From
papercut/:python3 $PAPERCUT_LIB/tools/cues.py && node $PAPERCUT_LIB/audio/render.mjs. Check scenes with$PAPERCUT_LIB/tools/qa.sh NAME FROM-TO NTH, then render with$PAPERCUT_LIB/tools/render.sh. - From
papercut/,python3 $PAPERCUT_LIB/tools/harvest.py .lists what the episode should give back. Promote it (HARVEST.md), then runpython3 $PAPERCUT_LIB/tools/catalog.py.
Token rules
These keep an agent's context small.
- Read
papercut/CATALOG.md(about 60 KB) andaudio/CATALOG.md(about 9 KB), not the kit source (about 350 KB) or the sound code. Open a source file only for one specific detail. - Reuse before writing. A kit component, a props set (
props/council,props/everyday) or a scene template (scenes/CtaPhoneDM) beats new drawing code. New code goes in the scene file, and anything reusable gets harvested afterwards. - Pick SFX by name. A new sound is a new
sfx/<name>.jsfile with the header line, never an edit inside a large score file. - A music bed is a JSON preset. A new mood is a new preset.
- Beds with
"style": "night"(beds/night-rain-piano-F.json) replace the plucked loop with rain on glass, room tone, a sparse felt piano and a soft pad through a convolution reverb. They also takethinFrom,thinToandresolveAt. Beds withoutstylerender the plain loop. - One QA command per scene, and contact sheets of at most 45 frames at 200 px, keep image tokens low.
- Each project keeps a copy of the kit (
src/lib/), so an old episode renders the same after the library changes. Re-sync withpapercut/sync_kit.shwhen you want the new version.
Environment variables
The scripts read these. env.sh supplies the defaults and also loads KEY=value lines from ${PAPERCUT_CONFIG:-~/.config/papercut-explainer/config.env}; anything already set in your shell wins.
| Variable | Meaning | Default |
|---|---|---|
PAPERCUT_LIB |
Absolute path to this folder. The skill and the agent brief use it. | the folder env.sh sits in |
PAPERCUT_PY |
Python with numpy, Pillow and soundfile. Used by qa.sh, render.sh (audio mix) and the texture tools. |
python3 |
QWEN_TTS_PY |
Python with qwen-tts and torch installed. Used by voice/narrate.sh, and by finalize.sh for the pitch pass (needs librosa). |
python3 |
QWEN_TTS_HOME |
Folder to add to PYTHONPATH, only if you run qwen_tts from a source checkout instead of pip. |
unset |
QWEN_TTS_MODEL |
Model repo for custom-voice mode when voice.json has no model key. |
Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice |
ASR_PY |
Python with mlx-whisper or faster-whisper, for voice/asr.py. |
python3 |
FASTER_WHISPER_MODEL |
Model name when asr.py uses faster-whisper. |
large-v3-turbo |
CHROME_PATH |
Chrome or Chromium binary for audio/render.mjs and tools/capture.mjs. |
tries the usual macOS and Linux paths |
DONOR |
A node_modules folder for new_episode.sh to copy. |
newest <series>/episodes/*/papercut/node_modules |
CONC |
Browser tabs per render job. | 4 for render.sh, 2 for qa.sh |
PAPERCUT_CONFIG |
Path of the config file. | ~/.config/papercut-explainer/config.env |
The voice scripts take more (ROLE, SCRIPT, SKIP_PICK, ONLY, TAKES, SEED_BASE, and the usual Hugging Face variables). They are listed in voice/README.md.
Status
The scripts were written on macOS (Apple Silicon) for one author's workflow and have only been run end to end there. The shell scripts are bash and pass bash -n, the Python passes py_compile, and new_episode.sh falls back to a plain copy where APFS cloning isn't available. Linux should work, Windows probably needs WSL, and neither has been tried.
Things to know before you rely on it.
- The voice pipeline is optional and the least tested part. It was built around Qwen3-TTS and mlx-whisper. The CUDA path in
narrate.pyand the faster-whisper path inasr.pywere written afterwards and not run on real hardware by the author. render.pyandqa.shpass--gl=angleto Remotion and use ProRes intermediates, which take several GB per episode inout/cache. If your Chrome build rejects the flag, change it inrender.py(FPS_FLAGS) andqa.sh.dialogue_timeline.py, theSPEAKERandROLEoptions in the voice scripts, and the dialogue branch inrender.pyandmix.pysupport two-speaker videos. No template for those ships here.- The catalogs are generated. Run
tools/catalog.pyafter you add or change anything in the kit or the audio folder, or agents will read stale ones.