HLC Clipper — render tools

Requirements: macOS + Homebrew + ffmpeg-full + Python 3 (Xcode CLT for the optional Swift matte tool) — full walkthrough in SETUP.md.

The render engines from 19Keys' personal AI video-clipping studio: the Python/ffmpeg scripts that turn a raw talking-head video into styled vertical clips and quote cards, plus the Swift/Vision tool used for masked (person-cutout) color grading.

This is the tools/ layer of a larger private studio (dashboard, job server, deploy pipeline). What's here is everything you need to understand and reuse the actual render logic — the ffmpeg filter chains, the ASS subtitle generation, the face-tracked auto-reframe, and the Vision-based person matte. What's not here (and why) is in "What's missing" below — read it before you expect a one-command render.

What this actually does

Every script is a standalone CLI you can run directly against a source video. No server, no database, no queue.

tools/luxury_render.py — the signature "luxury" grade: filmic curves, soft bloom, vignette, fine grain, a thin gold frame, and a letter-spaced Didot caption. Two registers baked in as cinematic (rich, moody, A24-ish) and quiet (near- monochrome, extreme restraint). Applies one of three LUTs — cool / warm / natural — on top of the procedural grade. Can run masked (subject cut out from a separately-graded background) via personmatte.
tools/personmatte.swift — Apple Vision (VNGeneratePersonSegmentationRequest) person-matte extractor. Streams a video in sequentially, reuses one segmentation request so the matte stays temporally stable, and writes raw grayscale matte frames to stdout for ffmpeg to composite. macOS + Vision only.
tools/reframe.py — auto-reframe: OpenCV face tracking across a clip, returns the ffmpeg crop that keeps the speaker centered for a target aspect (9:16 by default). Falls back to a centered crop if no face is found — a render never breaks because a face wasn't detected.
tools/quote_cards.py, tools/quotecard_render.py — freeze-frame quote cards (1080x1350, IG 4:5) with burned-in quote text and a brand watermark.
tools/style_render.py, tools/batch_cards.py — the repost/commentary card styles (conversation, quote, X-post/"xpost", editorial, culture) — HTML template rendered transparent via Playwright, composited over the cut footage with ffmpeg. batch_cards.py runs a ranked quote bank through this in one pass.
tools/quote_reel_overlay.py — a transparent overlay PNG (rounded quote box + cursive signature) to lay over a 9:16 video for a quote-reel look.
tools/screenplay_prep.py — formats a word-level transcript slice into the JSON a "screenplay scroll" motion composition consumes.
tools/word_captions.py — karaoke / word-by-word ASS captions from a transcript, remapped onto the output timeline after cuts.
tools/whisper_to_words.py — converts local whisper-cli JSON output into the same word-timing format the rest of the pipeline expects (no API key needed).
tools/motion_render.py, tools/hyperframes_render.py — drivers for two external motion-graphics engines (Remotion, HyperFrames) — not vendored here, these scripts just shell out to npx/bunx if you have them installed.
tools/fonts.py — scans your local font folders, resolves each file's real font-family name (not the filename), classifies it, and writes fonts.json so render tools can offer your own type as presets.

AGENTS.md and CLAUDE.md are the original operating rules for this studio (session harness, house render defaults, iron rules learned from real bugs). They reference pieces of the full studio (dashboard/, ops/, atomizer/, a Mac Mini deployment) that aren't part of this extract — read them for the reasoning, not as instructions you can execute here.

What's missing (read this before you run anything)

This is a scoped extract of tools/, not the whole studio. A few things won't work out of the box:

tools/luts/{cool,warm,natural}.cube — the three LUT files luxury_render.py loads are not included. Bring your own .cube LUTs at those paths, or strip the --grade step and rely on the procedural curves alone.
dashboard/styles/*.html — the actual visual templates for the quote-card and repost-style tools (quote_cards.py, quotecard_render.py, style_render.py, batch_cards.py) live in the dashboard layer, which is out of scope for this repo. These scripts will run but fail to find their template HTML until you supply your own — the Python here shows you the full render pipeline (ffmpeg composite, ASS captioning, Playwright screenshot) to build templates against.
fonts.json — checked in as a working example, but every path in it is absolute to the machine it was generated on (/Users/<user>/Library/Fonts/...). Regenerate it for your own machine with python3 tools/fonts.py.
tools/personmatte (the compiled binary) is intentionally not included — compile it yourself (one command, see below).

Requirements

macOS (Vision-based masking and swiftc are Apple-only; everything else is portable Python/ffmpeg)
ffmpeg-full, not the slim Homebrew formula — subtitle burn-in needs libass, which the slim build doesn't ship. brew install ffmpeg-full (keg-only).
Python 3 with opencv-python-headless (for reframe.py) and playwright (for the card-style renderers, if you supply your own templates)
Node 22+ if you want the Remotion/HyperFrames motion-graphics drivers
An ElevenLabs API key only if you use hosted transcription — the local-whisper path (whisper_to_words.py) needs no key

Quickstart

# 1. ffmpeg-full (subtitle burn-in requires libass; the slim formula lacks it)
brew install ffmpeg-full

# 2. compile the Vision matte tool (macOS + Xcode CLT)
cd tools && swiftc -O -o personmatte personmatte.swift && cd ..

# 3. python deps for face-tracked reframing
python3 -m venv tools/reframe-venv
tools/reframe-venv/bin/pip install "opencv-python-headless<5" numpy

# 4. copy the env template and fill in a key if you're using hosted transcription
#    (named env.example, not .env.example, so it doesn't get swept up by dotfile
#    secret-scanners in CI — same idea, just a plain filename)
cp env.example .env

# 5. run a grade directly against a source clip
/opt/homebrew/opt/ffmpeg-full/bin/ffmpeg -version   # confirm libass is present
python3 tools/luxury_render.py --video source.mp4 --start 12 --end 20 \
  --title "YOUR CAPTION HERE" --out out.mp4

init.sh and setup.sh are the original studio's verification/bootstrap scripts — init.sh in particular checks for files outside this extract (dashboard/server.py, atomizer/) and will fail as shipped. Treat both as reference for what a complete setup checks, not as a script you can run unmodified against this repo. setup.sh also references .env.example; this repo ships that same template as env.example (see the quickstart) — copy it to .env by hand rather than relying on setup.sh's auto-copy step.

Making it your own

Swap GOLD, CREAM, and the Didot font reference in luxury_render.py for your own brand marks and palette.
Build your own .cube LUTs (DaVinci Resolve, or any grading tool that exports 3D LUTs) and point GRADES in luxury_render.py at them.
Write your own dashboard/styles/*.html templates for style_render.py / quote_cards.py — they're plain HTML/CSS rendered headless via Playwright, so any web design skill transfers directly.
Run tools/fonts.py against your own font folders to build a fonts.json that reflects your own type library instead of the shipped example.

License / attribution

This is 19Keys' own tooling, shared with the community to build from. The two external engines referenced (video-use, hyperframes) are separate open-source projects — see setup.sh for their upstream repos and install their own licenses before vendoring them.