dsh-papercut

Papercut explainer films, end to end — natively on Windows, no WSL.

A DeepSeek Harness plugin that turns one sentence of idea into a finished vertical (9:16) cut-paper explainer: script → local text-to-speech → word-level timed captions → Remotion render → QA contact sheets.

$ dsh --profile papercut
> 做一个关于剪纸的 25 秒短片
   → papercut_plan → papercut_voice → papercut_storyboard → papercut_render → papercut_qa
   → episodes/01-jianzhi/papercut/out/jianzhi-papercut.mp4   (1080×1920, 27.5 s, −14.7 LUFS)

Why this exists

The upstream papercut-explainer library is a beautiful Remotion kit, but its toolchain is 27 bash and Python scripts written for macOS (Apple rsync, mlx-whisper, Homebrew ffmpeg, readlink -f). Everything that touches the OS has been rewritten here in Node, so the whole pipeline runs on a stock Windows machine:

Piece	Upstream	Here
Choreography	render.py + render.sh	src/node/render.js — one bundle, per-scene ProRes HQ segments, content-keyed cache
Audio mix	mix.py (numpy)	ffmpeg sidechaincompress + alimiter + loudnorm
Voice	narrate.py (qwen-tts)	local IndexTTS-2.5 bridge over HTTP
Word timing	asr.py (mlx-whisper)	openai-whisper + forced alignment against the known script (py/align.py)
Chromium	system Chrome	the Edge that ships with Windows
ffmpeg/ffprobe	brew install	bundled static binaries from npm

No WSL. No Homebrew. No ffmpeg on PATH. Python is only needed for two leaf scripts (forced alignment, CJK font subsetting), and the plugin calls the interpreter you point it at.

The six tools

Tool	Arguments	What it does
papercut_list	—	Existing episodes, their duration, scene count and whether a render exists
papercut_plan	idea, slug?, comp?, lines?	Scaffolds the episode and returns the 7-line script brief
papercut_storyboard	slug	Camera / cut / SFX table derived from the real frame plan
papercut_voice	slug, engine?, force?, model?, keepWarm?	Local TTS per line, silence trim, forced word alignment, voiceover.wav + captions + plan
papercut_render	slug, force?, workers?, conc?	Segmented Remotion render, then one x264 pass with the audio bed
papercut_qa	slug, every?, scale?	Contact sheets every N frames, numbered, for visual review

Everything else — composing scenes, writing the hook, choosing assets — is the agent's job, guided by nine skills.

The nine skills

Installed into <DSH_HOME>/skills by npm run skills, so DSH picks them up live:

papercut-explainer (router / end-to-end) · papercut-strategy · papercut-hook · papercut-script · papercut-storyboard · papercut-build · papercut-voice · papercut-qa · papercut-setup (toolchain doctor for this machine).

Say "make a papercut reel about X" and the router takes it from there.

Install

# 1. the plugin
dsh plugin --profile papercut add "link:D:/path/to/dsh-papercut"
#    or, from npm:  dsh plugin --profile papercut add dsh-papercut

# 2. the skills (idempotent)
cd D:/path/to/dsh-papercut
node scripts/install-skills.mjs

# 3. check the toolchain
#    in DSH: "check my papercut install"   -> runs the papercut-setup doctor

What the workspace must look like

dsh-papercut drives a workspace directory holding the upstream library and the render app. The plugin finds it by walking up from its own package folder (and then from the current working directory) looking for app/node_modules + src/papercut-explainer-main/library, so a linked checkout and an npm-installed copy both work without configuration. Point it elsewhere with root in cordis.patch.yml, or the PAPERCUT_ROOT env var.

<root>/
  app/                          Remotion project (node_modules with remotion, ffmpeg-static, ...)
  src/papercut-explainer-main/  the upstream MIT library (kit, audio engine, scenes template)
  episodes/<slug>/              one folder per film
  tools/                        the Node CLI used during development

Use papercut-setup (or node tools/bin/papercut.mjs list) to see what is missing.

Requirements

• Windows 10/11 with Edge (any modern Edge has the headless Chromium Remotion needs)
• Node 22+
• A Python 3.11 virtualenv with openai-whisper + fonttools — only for the aligner and the CJK font subsetter. Point at it with python: in the plugin config.
• Optional: a local TTS HTTP bridge on 127.0.0.1:7865 (IndexTTS-2.5). The plugin probes /health and tells you how to start it; it never spawns the model itself, because that would hold VRAM hostage.

Configuration

cordis.patch.yml in this package:

- insert:
    - id: papercut
      name: dsh-papercut
      config:
        root: ''                 # workspace path, else PAPERCUT_ROOT, else the built-in default
        ttsUrl: http://127.0.0.1:7865
        python: D:/tts/index-tts/.venv/Scripts/python.exe
        chromePath: C:/Program Files (x86)/Microsoft/Edge/Application/msedge.exe
        defaultModel: small      # whisper model for forced alignment
        debug: false

Verified numbers

First film, episodes/01-jianzhi (1080×1920, 30 fps, 824 frames):

Voice + alignment	7 lines, 24.1 s of speech, ~4 s synth + ~3.3 s align per line
Render (cold)	55 s — bundle 2 s, 824 frames in 3 parallel workers, final encode 9 s
Render (one scene changed)	20 s — cache hits on the other six segments
Output	H.264 High, yuv420p, bt709, 8.6 Mbps, −14.7 LUFS, −1.0 dBTP, 0 decode errors

License

MIT. The bundled story kit comes from papercut-explainer (MIT), also credited in NOTICE.