Willcuts

One CLI that turns raw show footage into captioned, platform-ready vertical clips.

Willcuts takes a video of a stand-up set (or any performance), transcribes it locally, syncs it to the soundboard audio, discovers the best cuts, and renders a finished vertical clip with burned-in PT-BR captions — through a review step you control at every stage.

Built for the workflow it runs in: a working comedian's own content pipeline. Everything runs locally; nothing about your footage leaves the machine unless you opt in.

---

The pipeline

raw footage
    │
    ▼
transcribe ──► faster-whisper, local CPU, PT-BR-first
    │
    ▼
sync ───────► board-audio alignment, clean-mic/crowd mix
    │
    ▼
discover ────► LLM cut discovery (--find), reaction bias (--reactions)
    │
    ▼
review ─────► editable subtitle gate (--review), approved cuts (--review-cuts)
    │
    ▼
render ─────► --mode reel (vertical, face-tracked) or --mode original

Features

• Local-first transcription — faster-whisper on CPU. Portuguese audio never leaves the machine; only timestamped transcript text is sent for translation when the source is another language.
• Deterministic processing — the same input and flags produce the same output. No hidden randomness in rendering.
• LLM cut discovery with review gates — willcuts find proposes cuts from the transcript; you approve before anything renders.
• Performer-aware Reel framing — MediaPipe face/shoulder tracking with a static fallback, so cuts stay on the performer without jump cuts.
• Board-audio sync and crowd mixing — aligns the clean mic with the soundboard and blends crowd reactions.
• Transcript cache reuse — full or range-scoped JSON caches are shared with the clipfinder format, so you never re-transcribe the same material.
• Opt-in censorship — local-only blur for flagged content when you ask for it.
• Tested — pytest suite covering framing, censorship, and core logic.

Install

Requirements: Python 3.10+, FFmpeg, and a machine with a few GB of RAM.

git clone https://github.com/illanrego/willcuts.git
cd willcuts
python3 -m venv .venv
.venv/bin/pip install -e '.[dev]'

For MediaPipe performer-following Reel framing:

.venv/bin/pip install -e '.[follow-performer]'

For non-Portuguese source videos, copy .env.example to .env and set DEEPSEEK_API_KEY (used only to translate transcript text to PT-BR). Never commit this file.

Quick start

Process a full video into a captioned vertical clip:

.venv/bin/willcuts input.mp4

Process a selected range:

.venv/bin/willcuts input.mp4 --from 00:01:12 --to 00:02:05

Output modes:

.venv/bin/willcuts input.mp4 --mode reel       # 720x1280 vertical, face-aware (default)
.venv/bin/willcuts input.mp4 --mode original   # native geometry, untouched
.venv/bin/willcuts input.mp4 --mode reel --no-crop  # legacy static framing, no MediaPipe

Force the source language (skips detection):

.venv/bin/willcuts input.mp4 --language pt
.venv/bin/willcuts input.mp4 --language en   # translates transcript to PT-BR

Discover and review cuts

.venv/bin/willcuts find input.mp4            # propose cuts from the transcript
.venv/bin/willcuts find input.mp4 --reactions  # prioritize reaction-heavy moments
.venv/bin/willcuts find input.mp4 --review     # write .review.json and stop
.venv/bin/willcuts find input.mp4 --render     # render approved cuts

Review subtitles before rendering

.venv/bin/willcuts input.mp4 --language pt --review

Willcuts writes an editable SRT and pauses. Edit and save it, then confirm in the terminal to validate and burn the captions into the MP4. Use [P] (performer, yellow) and [A] (audience, white) prefixes to tag caption roles; they are stripped from the final SRT.

Translate an existing SRT only

.venv/bin/willcuts input-en.srt --translate-srt

Writes input-en-ptbr.srt, preserving cue numbers and timestamps exactly.

Privacy model

Stage	Where it runs
Transcription (faster-whisper)	local CPU
Framing / face tracking (MediaPipe)	local
FFmpeg rendering	local
PT-BR translation of non-PT transcript text	opt-in, remote (DeepSeek API), text-only

Portuguese-language footage can be processed end to end without any network call.

Tests

.venv/bin/pytest

Project layout

.
├── src/willcuts/
│   ├── cli.py          # command surface (main/find, --review/--render)
│   ├── core.py         # transcription, sync, mixing, rendering orchestration
│   ├── auto_frame.py   # MediaPipe face/shoulder framing
│   ├── censorship.py   # local blur for flagged content
│   ├── discovery.py    # LLM cut discovery from transcripts
│   └── assets/         # packaged MediaPipe models
├── tests/              # pytest suite
└── pyproject.toml

History

Willcuts is the consolidation of two earlier tools — Clipfinder (transcription/cache) and WillReels (framing/rendering) — into a single command. The shared transcript-cache format remains clipfinder-compatible.

Credits

• faster-whisper — local transcription
• MediaPipe — face and pose models
• FFmpeg — all media processing