focalcut
focalcut is MIT-licensed at github.com/isaacrowntree/focalcut; paths below are relative to a clone of it (e.g.
~/focalcut). Everything below is code in that repo.
Footage folders hold only data and settings: export/, camera files and focalcut/reel/reel.json. Never copy code
into a footage folder. If an event needs different behaviour, add a reel.json key and leave the code general.
cd <repo> && python -m venv .venv && .venv/bin/pip install -e ".[reel]" # once
.venv/bin/focalcut --help
What every deliverable includes
- Rendered video: 1080p 50 fps (or 4K: reel.json
"resolution": "4k", top level, per format or per cut), music at −14 LUFS. - FCP7 XML for Premiere: the editor finishes there. Rendered shots go on V1, untouched sources on a disabled V2.
- Review page:
review/<cut>.htmlshows one frame per shot with a copyable picks line. Open it in a browser (on WSL, for example:explorer.exe "$(wslpath -w review/<cut>.html)"). - Editor's picks: the review page's Scrub opens each shot's export video. The editor marks extra
shots (
A), swaps a shot to the playhead (S), bans it, or asks for more from that video. The source browser (review/sources.html) shows every export and the whole cut, takes in-out picks, and frames the portrait cut shot by shot (its Frame portrait view,sources.html#frame=<reel>: drag to pan the crop, click a dancer to follow them).focalcut reel serve <folder> [<folder> ...]serves them all from one port (each project at/p/<slug>/, an index at/) and the pages writefocalcut/reel/picks.jsondirectly; it takesban,prefer,add,more,portrait, andopen/end(the selection the reel opens on, under the logo, and ends on: the pick editor's Opening and Ending buttons), with times in each export file's own timeline. Picks win over the planner's shots, so a heavily picked reel is mostly picks; reel.json"keep": truekeeps the last rendered cut's footage for clips the editor left alone. A reel the editor has picked outright (a short cut of their selections) takes reel.json"mode": "picks"(or the same inside a cut): every pick once, whole, in the story's order, trimmed only when they overrun the reel (B-roll picks before people, the least starred first; in portrait B-roll picks go before a pick of people is trimmed), longer where the music is calm, B-roll they left alone filling the rest, the same picks in every format but for that, no coverage passes (docs/picks.md). Otherwise, when the picks are too many or too long, reel.jsonplan.<fmt>.pick_hold(beats, e.g. 4 landscape, 3 portrait) plays each pick's best few beats instead, condenses a clip with many picks to its best ones, keeps the picks to about half the reel (pick_share) and puts them between shots from the rest of the footage, picked clips included. Re-run--steps plan,render,xml,reviewafter any change.
Several reels from one shoot: reel.json "cuts": {"night": {"formats": ["portrait"], "footage": ["@portrait", "band"], "open": {}, "plan": {"portrait": {"acts": [...], "ending": null}}}, "day": {"footage": ["@landscape", "!band"]}}, then
focalcut reel run <folder> --cut night --steps plan,render,xml. A cut reuses the project's analysis; acts it has no
footage for can be given zero bars.
Three ways to make a clip
- A full recap reel (landscape + portrait, a story in acts):
focalcut reel init <folder> --song x.mp3 …, thenfocalcut reel run <folder>. Steps: units, score, shake, focus, subject, semantic, moments, faces, people, music, plan, render, xml, review. Each step caches, so--steps plan,render,xml,reviewre-cuts in minutes. Full guide:docs/recipes/recap-reel.md. - Any other cut (teaser, a player's highlight, a band promo, a 15 s story) from an analysed project:
- Build the sequence by hand with
plan.shot(), or withplan.Pickerfor fair sharing between clips. - Run it through
plan.place(). It does beat timing, velocity landings, reframing, shake and stabilise flags, and transitions by grammar. - Save it as
plan_<cut>.json. - Call
render.run/xml_export.run/review.runwithcut=<cut>. Output isout/<name>_<cut>.mp4. Worked example:skills/focalcut/examples/teaser.py <folder> --bars 8opens on a band player, cuts faces, hair flips and turns on the song's loudest phrase, and ends on the project's ending shot. Copy it and change PATTERN.
- Build the sequence by hand with
- One clip, one effect:
focalcut fx apply clip.mp4 -e hero --peak 1.2 [--closeup] [--cap 1.5]. Alsofocalcut fx listandfocalcut fx gallery clip.mp4.
A different song for a new cut: music.analyse(song, start_hint=…, max_len=…) returns the dict place() takes.
Pass song= to place() and the render and XML use it.
The concepts (each is its own piece of code)
Read references/concepts.md for the rule, the reason, the numbers and the code behind each. In brief:
| Concept | The rule | Code | reel.json plan.<fmt> key |
|---|---|---|---|
| Opening | festival B-roll (band, crowd) with the event logo centred, never dance first | plan.story teaser |
opening, top-level logo |
| Story in acts | teaser, arrival (day), shows, night, climax, finale on the song's sections | plan.story, default_acts |
acts, split, day, day_shows, night_shows |
| Use everything / card shuffle | every export file appears in each format it belongs to (hard requirement: more cuts, never a file dropped), several scenes each, spread out and interleaved, never a block | Picker, cover, weave, cover_all |
— |
| Cut on the action | turn→turn, travel keeps direction, a movement carries 2–3 cuts | flow.py, flow_link |
— |
| No same-y runs | static footage gets one long shot; never near-identical neighbours | weave |
— |
| Music-video rhythm | 8-beat phrases of varied lengths, peaks on beats, cuts 2 frames early, beat-exact frames | rhythm, in_point, ANTICIPATE |
night_pace |
| Subject | the salient, near, large dancer (+ partner/line), not just the sharpest | subject.py, frame.track |
— |
| Moments | middle of routines; spins, dips, tricks, shakes, close-ups; dancing the whole shot | moments.py |
— |
| Velocity edits | fast through the move (≤1.5x dancing) → ease → slow on the landing → hold → ease up | velocity.settle/landing, fx/speed.py |
heroes |
| Show the landing | every dance shot keeps the end of the move and about a beat of rest after it lands, borrowing a beat from a neighbour if needed | velocity.landed/hold_in, plan.lands |
land_hold |
| Transition grammar | mostly hard cuts; each act's own short vocabulary; a reason for every transition | grammar.py, plan.transitions |
grammar, caps, flash_at |
| Cohesive effects | one effect at a time, one subject effect (on the drop), effects target the subject | give_slot_fx, fx/subject.py |
— |
| Portrait framing | the crop is on the action (pose activity), never a bystander; a couple shares the frame, the follow featured (role step) and kept whole; group routines whole; faces (YuNet) strongly favoured; no backs | frame.follow/couple/activity/face_seen, role.py, plan.reframe |
— |
| Moments that play | the subject walking or standing, a crowd crossing the crop, someone blocking the camera: switched for a better moment | plan.plays, plan.assess, spot_rater |
— |
| Shake | measure; too shaky → another part of the clip; mildly shaky → stabilise | shake.py, plan.assess, render.stab |
shake |
| Band members | individual players cut in on the hardest musical hits, only where a player is on screen and sharp | plan.band_in, role.musician |
members, member_clips, band_in |
| Style look | one look for the film from a style library (glitch: digital damage; carnival: Latin carnival / tropical disco; edm: MilkDrop + white/dark flickers): its transitions, subject effects, accents and MilkDrop presets; chosen from the look book | fx/looks.py (glitch.py, carnival.py, edm.py LOOKS), plan.glitch_look, fx/lookbook.py --library |
look (its overlay sits under reel.json's own) |
| Ending | a chosen last shot that runs out exactly at its end time; its stretch reserved | plan.ending_record/reserve_ending |
ending |
| Song start | start on the bar nearest where the song proper begins | music.analyse |
top-level start_hint |
| Several songs | one song per act (a festival's sets), each around its drop, mixed like a DJ: tempo ramp, 4 bars beat on beat, bass swap on the downbeat | music.join/mix, plan.clock |
top-level songs, mix |
| Headliner last | the last set's footage kept for the climax and finale | plan.story |
late |
| EDM light show | MilkDrop-style presets (tunnels, mandala, kaleidoscope, lasers, particles, plasma, flame) in changing palettes every 8 bars, beat blinks, drop bursts; ≤1 full flash per beat | overlay.py |
top-level overlay |
| Everyone in it | every person found by face (YuNet + SFace, grouped across clips) and every kiss (SigLIP 2) gets a shot; the moment showing the most missing people goes in first, splitting long shots when needed | people.py, plan.cover_people |
— (the people step) |
| Clean masks | BiRefNet matte inside the SAM 3 mask, never raw upscaled SAM | fx/masks.py |
— |
| Pick rules | never a back, a split-up group, the crowd, a blurry or bored face, or a weaker moment of the same person; effects take in everyone or no one (references/concepts.md §19) | windows.py, plan.snap_windows, window_report |
— |
| Rule check | after planning, every shot the planner chose is measured as it plays (subject in focus, no back, nobody halved or out of frame, no head cut, a couple close, B-roll clip at most twice) and a failing one is replaced: its own clip first, then another unit (featured couples first), else flagged rule fail in the plan log; the editor's picks are only reported |
validate.py (plan.<fmt>.validate) |
— |
Before rendering, check the plan against the rules
The planner prints a summary per act: shots, transitions, effects. Look at plan_<cut>.json, or render with
--draft and open the review page, and check:
- The summary's picks line says "all in once, at full length, bans held". Anything it lists (a pick missing,
repeated, short, sped up or overlapped; a ban not held) gets fixed before rendering (
plan.pick_report). - Every export file is present in each format it belongs to (the summary's
unitsreads n/n); no clip cuts to itself; no B-roll sits next to B-roll. - Dance shots with a landing show the rest after it (
land,land_fitsin the plan). - Transitions are few (about 15 in 3 minutes) and each has a
why; none are back to back. - Speed effects never sit side by side; there is one subject effect; dancing is never above 1.5x.
- Portrait:
crop.faceis high on social-floor shots, there are no backs, andinsideis near 1. jitteris below the secondshakethreshold except on B-roll that is shaky throughout; those shots getstab.
Event-specific settings go in reel.json, never in code
Example from the shoot the recipe was built on (a 2026 salsa congress):
"start_hint": 17.0, and plan.<fmt>:
"members": ["singer", "violin"]"member_clips": ["C2003"]"ending": ["C2023", 126.6, 133.4, 0.45]"heroes": 3"day": ["class", "stage-setup", "panel"]"day_shows": ["demos"]"night_shows": ["animations"]actson the song's sections
Plus proxies for the DNxHD stabilised masters.
Practical notes
- Python environment: ML runs from the repo's
.venvwith thereelextra. SetFOCALCUT_DISABLE_CUDNN=1if cuDNN engines are broken. - Decoding and encoding (docs/hardware.md): Sony 10-bit 4:2:2 HEVC can't use NVDEC before Blackwell, and
Mesa's WSL VA-API bridge has no 4:2:2 decode. On WSL the render decodes it on the Intel iGPU with Quick Sync via a
Windows ffmpeg (
C:\tools\ffmpeg-*\bin\ffmpeg.exeorFOCALCUT_WIN_FFMPEG; needs-async_depth 1or cuts land 3 frames early), encodes with NVENC, and runs shots in parallel (FOCALCUT_DECODERS="qsv=5,cpu=2"). Analysis still decodes on the CPU; the shake pass decodes the H.264 exports on the GPU. - Faster analysis (option): the score step decodes every 4K source frame on the CPU (about 1.6x real time).
reel.json
proxiescan point each source at a 1080p H.264 copy that NVDEC decodes on the GPU, e.g.{"C2150.MP4": ["export/dusk/C2150.mp4"]}, adding[[0, -t0]]shifts for an export trimmed to start at t0. A proxy must cover the whole source, so a clip split across several exports needs one full-length 1080p copy of its own. Caveat: render also decodes from proxies, and a 9:16 strip from 1080p is only ~600 px wide (about 1,200 from 4K). Use proxies for the analysis steps, then remove the key before the render step. - GPU workers: for example, two scoring workers suit a 12 GB GPU; more can overflow VRAM (on WSL it pages to RAM).
- Long jobs: run them in the background. Kill workers by PID, or with an anchored
pgrep -af '^/full/path'; never an unanchoredpkill -f, which matches the calling shell. - Tests:
.venv/bin/python -m pytest -qandruff check .must stay clean.