Papercut Voice

Before you start: read this whole install prompt, tell me in a few lines what this skill does and what installing it involves, and wait for my go-ahead before you do anything else. Prerequisites: none for the install itself: no account, no API key, no paid service, and nothing else to install first — this install copies one instruction file only. Read this before using the skill afterwards, because the file alone cannot voice anything: "papercut-voice" is NOT self-contained. Using it requires a whole pre-existing setup that this install does NOT provide and must never install for me: (1) the entire papercut-explainer library of the same repository, found via $PAPERCUT_LIB or the PAPERCUT_LIB= line in ~/.config/papercut-explainer/config.env — in practice a Standard or Full install of the whole system, done separately through the papercut-setup skill / the repository's install.sh (Standard is enough for the placeholder voice only; a real voice needs Full, or the voice packages installed by hand); (2) a project already scaffolded by papercut-build (step 1), holding narration/script.json and papercut/episode.json with scenes — new_episode.sh copies build_timing.py into narration/; (3) for path A (local Qwen3-TTS), the voice venv built by library/voice/setup_tts.sh (Python 3.10-3.12, qwen-tts and torch) and a Qwen3-TTS model of 2.3-4.2 GB downloaded from Hugging Face; for path B (my own recording or another TTS), an ASR backend — mlx-whisper on Apple Silicon or faster-whisper elsewhere — plus librosa and numpy for the pitch pass, in the Pythons named by ASR_PY and QWEN_TTS_PY; for path C (placeholder), ffmpeg only, and macOS for the optional --say voice; plus ffmpeg in every path, and the rubberband command-line tool only if a voice tempo other than 1.0 is set; (4) disk for the local voice: Full adds about 4-6 GB (about 1.5 GB of venv plus the model). The Qwen3-TTS weights are Apache-2.0 and the Whisper weights are MIT (see the repository's THIRD_PARTY.md; check each model card), and Remotion — used by the stages after this one — is free for individuals and small teams but has its own paid licence above a size threshold: check https://www.remotion.dev/license before commercial use. The repository's README estimates about $14-19 in agent API costs per 25-30 s reel, billed by my own agent provider; the voice itself runs locally and is not metered. The use-time sends (the Hugging Face model downloads on first use, the PyPI installs of the Full setup, and anything a TTS or speech-to-text tool I choose myself would receive) are all disclosed in point 2 below, before any of them happens. Only clone a voice I have the right to use, with the speaker's consent. Install "papercut-voice" for me. It voices one papercut explainer episode and times it to the picture, by one of three paths: (A) local Qwen3-TTS generation from a per-series voice/voice.json (a built-in CustomVoice speaker, or a cloned voice from a reference clip with the Base model), with several takes per line, automatic picking by ASR match and pitch, trimming and loudness normalisation to -16 LUFS; (B) my own recording or another TTS I already have, dropped in as one WAV per line or as raw takes; or (C) a placeholder voice (silent WAVs, or the macOS say voice) so the reel can be built and timed first and re-voiced later. On every path it then builds the word timings (timing_narrator.js), joins the lines into public/vo/voiceover.wav, writes the word-by-word captions (public/vo/captions.json) and the scene plan (src/plan.json), and writes the Timing section of the storyboard — the hand-off papercut-build reads next. Repository: https://github.com/0xS4N4TG/papercut-explainer (the skill is the whole skills/papercut-voice/ folder at the pinned commit: SKILL.md only, 1 file) Pinned version: install the code at commit ff8223abc8136cc09e8d7e9b62ecb5d080c389e1 exactly. Do not substitute a newer version. If this commit is unreachable, stop and tell me. 1. Clone https://github.com/0xS4N4TG/papercut-explainer into a temporary folder, check out commit ff8223abc8136cc09e8d7e9b62ecb5d080c389e1, and copy the skills/papercut-voice/ folder from that checkout. Then compare every file in the folder with the fingerprints recorded for this listing on 2026-10-19: [FINGERPRINTS] - SKILL.md: SHA-256 9a5333d955bf4a49056488cb02d7ea24e86dfce33dc6909585da6496ba04c9a3 If a file does not match, it changed since the listing was prepared: do not install it yet, tell me what you found and let me decide. 2. Read SKILL.md in full, and tell me in plain words: what the skill does when used, which services it connects to, whether it reads or sends any personal information or keys, and anything that seems unusual. Stop on any red flag and tell me before going further. Confirm these points from the file: - The skill folder holds 1 file only: SKILL.md (7,335 bytes). It contains no script, no audio and no reference file, and it is NOT autonomous: almost everything it names lives outside its folder, in the same repository. Its full script reference is library/voice/README.md, and it drives the shared library at $PAPERCUT_LIB: the whole voice pipeline under library/voice/ (voice.example.json, narrate.sh/narrate.py, asr.py, analyze.py, pick.py, finalize.sh, build_timing.py, split_take.py, setup_tts.sh), the tools under library/tools/ (placeholder_vo.py for path C, build_vo.py and timing_md.py for captions and the scene plan), library/env.sh (sourced at preflight; it loads ASR_PY, QWEN_TTS_PY and the other values from the config file), and library/new_episode.sh (which copied build_timing.py into the project's narration/ folder when the project was scaffolded). It also depends on sibling skills that are NOT part of this install: papercut-setup (repair via ./install.sh --doctor when the chosen path needs more than the current install has), papercut-build (step 1 scaffolds the project this skill works in, and the hand-off at the end — stubs, scenes, sound, render — is papercut-build reading src/plan.json and the Timing section of papercut/STORYBOARD.md), and papercut-explainer, whose references/style-guide.md (sections 11 and 13) sets the caption rules this skill follows. Its preflight reads the PAPERCUT_LIB= line in ~/.config/papercut-explainer/config.env when $PAPERCUT_LIB is unset, and sourcing env.sh loads the other lines of that file — that config file holds install paths and model names (PAPERCUT_LIB, PAPERCUT_PY, QWEN_TTS_PY, ASR_PY, QWEN_TTS_MODEL), not credentials. Its inputs are narration/script.json and papercut/episode.json, plus, per series, voice/voice.json copied from voice.example.json and edited by me (speaker or clone reference, instruct, takes_per_line, tempo, qa_targets), an optional num.json numeral map, and, on path B, my own WAV files. - Nothing is sent anywhere during installation itself; the only download at install time is the skill folder from GitHub at the pinned commit. No script is run during installation, no key is asked for, and there is no telemetry in the folder: SKILL.md names no https URL, no cloud TTS or speech-to-text service, and no API key at all. - What leaves this machine at use time, disclosed here before it ever happens — using the skill is a separate step that only starts when I ask to voice or re-voice an episode, and the sends below happen only inside the setup or the tools the skill drives: (a) Model downloads from Hugging Face on first use, when the model is not already in the local Hugging Face cache (~/.cache/huggingface, or $HF_HUB_CACHE / $HF_HOME): on path A, narrate.py loads the Qwen3-TTS model with Qwen3TTSModel.from_pretrained and downloads it if it is missing — Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice (about 4.2 GB) or the 0.6B CustomVoice (about 2.3 GB), or the same-size Base model for a cloned voice — and the Full setup that prepares path A (library/voice/setup_tts.sh, run through papercut-setup, never by this install) downloads the same models explicitly with huggingface_hub snapshot_download (HF_HUB_DISABLE_XET=1, retried 3 times). The ASR step downloads its Whisper model the same way on first use: asr.py with mlx-whisper transcribes with mlx-community/whisper-large-v3-turbo, and with faster-whisper it builds a WhisperModel named large-v3-turbo (or the name in FASTER_WHISPER_MODEL), which downloads its weights if they are missing. These downloads send only the model name to Hugging Face; no script, audio or project file is sent with them, and afterwards HF_HUB_OFFLINE=1 can stop the network checks. (b) The Full setup's package installs: setup_tts.sh creates the voice venv (uv venv --python 3.12 if uv is present, otherwise a Python 3.10-3.12 venv) and installs qwen-tts, mlx-whisper or faster-whisper, librosa, soundfile, numpy and huggingface_hub (torch is large; the venv is about 1.5 GB) from PyPI — the package names go to PyPI, nothing of mine does. Setting that setup up is papercut-setup's job, disclosed here because papercut-voice hands over to it (./install.sh --doctor, then papercut-setup) when a path needs more than the current install has. (c) A TTS or speech-to-text service I choose myself, and only that one: on path B the skill uses a TTS I already have, as it is — it asks once which one and where it runs — so if that TTS is a cloud service, the script text (each line's text or its tts respelling, and its instruct) goes to that service under my own account and its terms, and if it runs locally, nothing leaves; the Qwen Voice Design mode, which narrate.py does not drive, works the same way (I generate with it elsewhere and bring the WAVs back through path B: the voice description and the script text go to wherever I generate it). Likewise, only in the no-library fallback for captions, the WAVs are transcribed with the Remotion captions skill (whisper.cpp, local) or with any speech-to-text tool I pick that returns word timestamps — if I pick a cloud tool, the narration audio goes to it under my account; the library pipeline itself never does this. The skill names no such service, holds no key for one, and never chooses one for me. (d) Everything else at use time is local, and in particular my voice never leaves on the library paths: path A generation runs the Qwen model on this machine (MPS on Apple Silicon, CUDA on NVIDIA, CPU otherwise — minutes per line on CPU), one process at a time; a cloned voice's ref_audio clip and ref_text are read locally by that local model and sent nowhere (only clone a voice I have the right to use, with the speaker's consent); my own recordings on path B stay local; finalize.sh runs asr.py and analyze.py (pitch, via librosa) over the takes locally, pick.py chooses one take per line (ASR match at least qa_targets.asr_match, default 0.9, and median pitch in range), ffmpeg trims, high-passes and loudness-normalises to -16 LUFS at 48 kHz mono (rubberband stretches the audio first, locally, only when tempo is not 1.0), asr.py re-runs on the finals and build_timing.py writes timing_narrator.js (with no ASR it only estimates 2.75 words a second, so captions drift); split_take.py cuts one whole-script take into per-line files locally; placeholder_vo.py writes silent WAVs locally (or uses the macOS say command, a local operating-system voice, converted with ffmpeg); build_vo.py joins the lines with ffmpeg into public/vo/voiceover.wav and writes public/vo/captions.json and src/plan.json, and timing_md.py writes the Timing section of STORYBOARD.md. Playing the first three lines to me before a full run is a local playback in my own session. No step of papercut-voice itself reads a secret file, an API key or a credential — the environment variables it and its scripts read are paths and settings only (PAPERCUT_LIB, PAPERCUT_PY, QWEN_TTS_PY, ASR_PY, QWEN_TTS_MODEL, QWEN_TTS_HOME, HF_HUB_CACHE, HF_HOME, HF_HUB_OFFLINE, FASTER_WHISPER_MODEL, and per-run settings such as ONLY, SPEAKER, TAKES, SEED_BASE, TTS_TEXT, ROLE, SKIP_PICK, CHOSEN, TIMING_OUT, VO_TIMING) — and no usage data or telemetry is sent to the repository author or to any fixed third party. - Do not install the library, a venv, Python packages or any model during this install, do not run install.sh, ./install.sh --doctor or library/voice/setup_tts.sh, do not download any Qwen or Whisper model, do not run narrate.sh, finalize.sh, asr.py, placeholder_vo.py, build_vo.py, timing_md.py or any other library script, and do not generate, record or transcribe any voice: setting up the Standard or Full system, choosing a voice path, and voicing an episode are my decisions, later, when I actually ask for them. 3. When I say "yes, install", install it as a skill: copy the whole papercut-voice folder into the agent's skills directory, in a folder named "papercut-voice", keeping its 1 file (SKILL.md at its root). A manual clone followed by copying the skills/papercut-voice folder into ~/.claude/skills/ is the route described here; any other route is fine only as long as every installed file matches its fingerprint. 4. Verify with no network calls: frontmatter valid (name: papercut-voice), the 1 file in place with a matching fingerprint. Do not run any library script or tool to verify, and do not download any model to verify. 5. Report what was installed, where, and what I still need to do myself (for example: get the whole system set up separately if it is not already — a Standard install of the full repository through papercut-setup / install.sh suffices for the placeholder voice only, while a real voice needs Full (a voice venv of about 1.5 GB plus a 2.3 or 4.2 GB Qwen3-TTS model from Hugging Face, and a Whisper ASR model downloaded on first use) or the voice packages installed by hand, with ffmpeg (and rubberband only for a non-1.0 tempo); scaffold the episode project with papercut-build first so narration/script.json and papercut/episode.json exist; create the series voice/voice.json from voice.example.json and choose the speaker, or provide my own recording or my own TTS, or settle for the placeholder; check the Remotion licence before commercial use of the finished reel; using the skill is a separate step that only starts when I ask to voice an episode, and the use-time sends disclosed above — the Hugging Face Qwen and Whisper model downloads on first use, the Full setup's PyPI installs if I still need them, and the script text or narration audio to a cloud TTS or speech-to-text tool only if I myself choose one on path B or in the no-library captions fallback — happen only then). GitHub is optional: if I have a GitHub account or the gh CLI, you may use it; otherwise public access is fine. Never require it unless it's in the prerequisites above. Rules: don't touch anything outside the temp folder and the install target. If anything looks off, stop and ask me.