Grade #
A local app for grading camera footage in bulk before it goes into OpenFilm: pick a look, set exposure, white balance, tint, contrast and saturation across many clips at once, watch it live, and export graded copies when it looks right. It's dark or light as the Mac's appearance is set (or, in the composer's Grade tab, as the composer is); full screen stays dark.
On the owner's laptop it is always running: launchd starts it at login and restarts it if it exits
(dev.kualta.grade, ~/Library/LaunchAgents/dev.kualta.grade.plist, log ~/Library/Logs/Grade/server.log), from
the main checkout. Open http://127.0.0.1:4777 rather than starting it. It loads its code once, so after a
scripts/grade change is merged and master is pulled there, restart it once nothing is exporting:
launchctl kickstart -k gui/$(id -u)/dev.kualta.grade
Elsewhere, start it by hand:
bun run grade # http://127.0.0.1:4777, opens in the browser
With the agent running, port 4777 is taken. To try a branch, start it on another port, and point it at other folders too, since a second server reads and writes the same grades and exports (it only reads LUTs, so it can share them):
GRADE_PORT=4778 GRADE_ROOT=/tmp/grade/movies GRADE_DATA=/tmp/grade/data GRADE_CACHE=/tmp/grade/cache \
GRADE_LUTS="$HOME/Library/Application Support/Grade/luts" bun run grade
Where clips come from #
Clips from (top bar) lists shoot days from two places:
- Pocket 4P: the camera's card while it's plugged in (
/Volumes/Pocket4P/DCIM,GRADE_CAMERA), by the date in each DJI file name. Clips stay on the card: nothing is copied off it, and nothing is written to it except by ⌘⌫ (below). Thumbnails come from the still each DJI file carries; a clip's preview is made from the card when you select it. - On this Mac: the video in
~/Movies/Original/, for clips that aren't on the camera, by the date in a DJI name or else the file's own date.
Each day shows how many of its clips have an export, and the clip list can show only graded or ungraded clips.
What the app writes #
~/Movies/ GRADE_ROOT
Original/ clips on this Mac (above)
Exported/ exports and nothing else:
DJI_…_0234_D.mp4 8-bit H.264 BT.709, near lossless (or at the quality chosen), sound copied
DJI_…_0234_D_f0102.png Export frame: frame 102, graded, full size
~/Library/Application Support/Grade/ GRADE_DATA
grades.json every clip's grade, by file name, saved as you work
exports.json what each export was made with: source, base look, grade, key, quality
ledger.json the footage ledger (below), also kept in the site's archive
luts/ GRADE_LUTS: base looks (below)
~/Library/Caches/Grade/ GRADE_CACHE: metadata, thumbnails, previews; safe to delete
Clips are known by file name, so a clip graded off the card and the same clip copied into Original/ share one grade
and one export. An export put in Exported/ by hand counts as graded too.
The ledger, the composer's Footage tab, and its Grade tab #
The app keeps the footage ledger: a record of every clip it has ever seen, with its profile, its grade, and where its
copies are (the original on the camera, on this Mac in Original/ or in the Cloudflare archive; the graded copy on
this Mac in Exported/, in the Cloudflare archive or on YouTube). It's shown in the composer's Footage tab
(post.kualta.dev/footage, Footage in the top bar), from phone or laptop; here, the selected clip's panel says where
its copies are in a line.
The server looks every 30 seconds (and after an export or ⌘⌫) and merges what it sees into what it knew, so a clip off the card or the Mac keeps its record. What it can't look at keeps its last answer: the card's clips while it's unplugged (the Footage tab says as of when), and the archive between askings (every 10 minutes). The sources:
- the card and
Original/, and each clip's profile from its metadata (clips not yet probed are probed a few at a time, none while an export reads the card); grades.json,exports.jsonandExported/;- YouTube: the crossposter helper's
.publisher/footage.jsonin this checkout (GRADE_PUBLISHERnames the folder), what the footage archive put up; - Cloudflare: the archive's film projects, each manifest read once per archiving. A file of a clip's that's the original's size is the original; any other is a graded copy, the current one when it's the export's size (the same goes for YouTube);
- films: the OpenFilm projects in
~/Movies/OpenFilm/Projects(GRADE_PROJECTS) and in the archive, each with the ledger's clips in itsassets/andzh/assets/(projectsin the ledger, with whether it's on this Mac and archived). The composer's Pipeline pieces name a film or a shoot day and say how its clips stand.
ledger.json is the ledger as last merged. Whenever anything in it changes it's sent whole to the site's archive
(ledger/footage.json, through helper/archive/ledger on the helper's pairing), but only once the archive's copy has
been read back and merged in, so a fresh ledger.json on a new Mac can't drop clips only the archive knows. Each
clip's thumbnail (made in the cache a dozen per look, from the original's still or a frame, or from the graded copy
once the original is gone) goes to ledger/thumbs/<clip>.jpg once, and the clip's record says thumb. Without a
paired helper the ledger stays on this Mac.
Grade tab. post.kualta.dev/grade shows this app in a frame, loaded from http://127.0.0.1:4777: it still reads
the card and ~/Movies itself, previews on the browser's GPU and exports with ffmpeg here. The frame is allowed local
network access, and Chrome asks once whether post.kualta.dev may reach this device: allow it. Away from the Mac, or
until it's allowed, the tab says so. Only the composer may frame the app (frame-ancestors: post.kualta.dev, and the
site run locally on port 4321). In the frame the app says it's there, opens the clips the Footage tab's Grade
asks for (#clip=<file> in its address, or a message; /api/find says which day holds it), and takes the
composer's light or dark.
Offload: the card to this Mac, this Mac to Cloudflare #
Offload (top bar) shows what's on the camera, what's on this Mac not in Cloudflare yet, and the room on this Mac; Start offloading takes it all, and nothing starts until you click it. Two things go on at once:
- Off the card, a clip at a time, oldest first, while this Mac has room for the next with
GRADE_KEEP_FREE(5 GB) to spare: copied intoOriginal/(as a hidden.partuntil it's checked), hashed (SHA-256) as it's read, read back and checked against that, given the card's time, then deleted from the card with its.LRF. The camera is needed only until the last clip is on the Mac: the status line says when to unplug it, and unplugging earlier just ends this half. - Up to Cloudflare, two clips at a time: each sent unless the archive already holds those bytes (whole up to
16 MiB, else 16 MiB a request, so each lands well inside a request's ten minutes on a slow uplink; through
helper/archiveon the helper's pairing), filed in its shoot day's manifest in the archive,_originals-<day>(asassets/<file>, the manifest saved again after every clip), then deleted from this Mac. That makes room for the next clip off the card.
offloaded.json (beside grades.json) records each clip's hash, size and day. A clip already there whose hash the
archive still holds is only deleted; one the archive has lost goes again. A clip being exported stays put. The status
line shows both halves, waiting for room, speed and time left; Stop offloading cuts the request in flight and keeps
what's in. A request that fails stops the run, saying why; the next run picks up where it stopped. With no room on
this Mac and nothing there to go up, the card half stops and says so.
While a run goes the grade app keeps the composer counted as watching the footage uploads (helper/footage/watch),
so the helper puts graded clips up to YouTube meanwhile, as it does while the Footage tab is open. Log clips without a
grade get the default look as settings first (GRADE_DEFAULT_LOOK, OpenDRT Colorful), to change before any export.
The ledger counts offloaded clips as in Cloudflare (an archived file the original's size); _originals-* aren't
films. To bring a day back: bun run publisher restore _originals-<day> <folder>.
Grading #
- Look: the base look for the clip's camera profile, read from its own metadata tag. D-Log2, D-Log and HLG get the ACES conversions (from DJI's curve math, out through ACES 2.0 or 1.0), ARRI, AgX, OpenDRT, Fujifilm film simulations and Sony looks; D-Log2 and D-Log also get DJI's own Rec.709 LUTs, and D-Log2 the twelve P4P looks. Rec.709 clips are graded as shot. A new clip starts on ACES 2.0.
- Exposure in stops, Temperature in Kelvin (as if the camera had been set to it; it starts at the camera's own), Tint (+ magenta, − green), Contrast around 18% grey, Saturation. All of it happens in scene linear light before the look.
- Deflicker (under Light): Off, Light or Strong, for artificial light flickering at a shutter that
doesn't match it, and exposure that jumps from frame to frame in timelapse-like shots. ffmpeg's
deflickerscales each frame's brightness to the mean of it and the frames after it: 6 for Light, 12 for Strong (mode=am). Mains light at a mismatched shutter pulses every few frames (50 Hz light every 6 frames at 24 fps, every 3 at 30 or 60, every 12 at 48), and a window of whole pulses cancels them: 6 frames cancels 2-, 3- and 6-frame pulses, 12 also 4- and 12-frame ones. Light (a quarter second at 24 fps, a tenth at 60) suits handheld, where brightness that changes as the camera moves should stay; Strong, twice as long, suits tripod and timelapse shots, where nothing should. The mean, not the median: the window looks ahead, so a real change in light comes in as a ramp over it rather than a jump half a window early. A clip's last few frames, with less after them, are evened out less. It works on the graded picture, after the LUT (it scales brightness: right for Rec.709, where a change in light is close to a scale, wrong for log, where it's an offset), and only in exports. The preview can't show it, as the panel says; Export frame reads the frames after the one on screen too, so the still is that frame of the export. Off, a grade has nodeflickerfield at all, so exports made before it stay current. - Select several clips (⌘-click, shift-click, Select all or ⌘A) and a change sets that control on all of them. Copy grade / Paste copies a whole grade.
- Split and Original compare against the flat original; hold B to flash it. Space plays, ↑ ↓ change clip.
- The preview plays the original itself at full resolution (streamed off the card), so focus and detail are as shot. It is still 8-bit on screen, because Chrome hands video to WebGL at 8 bits even from a 10-bit file, so judge banding on an export. HLG clips play a 1280 px preview copy instead, so the browser can't tone-map them. Full screen (or F) gives the viewer and its transport the whole screen.
- Export (top right) bakes the selected clips. Its ∨ menu has Export frame (the frame on screen, graded, as a
full-size PNG in
Exported/), Re-export N changed (every graded clip whose grade moved since its export) and Quality: 100% (each time the app opens) is near lossless, whatever size that takes; below it the video gets that share of the original's bitrate, so the menu can say the size first (50% ≈ half the original file), and Export shows the percentage. Exports come from the 10-bit originals (off the card, for a camera day) at 16-bit precision, not from the preview. A camera day can't export while the camera is unplugged. Exporting more than ten clips at once asks for a second click; Stop exporting (top bar, while anything exports) drops the queue and stops the clip in progress, which leaves its previous export and record as they were. - ⌘⌫ moves the selected clips to the Trash, each with the files beside it under the same name (the camera's
.LRFproxy), as Finder would: a camera day's go to the card's own Trash, so Finder can put them back, and the space comes back when the Trash is emptied. Their grades and graded copies stay. More than ten at once asks for a second press; a clip that is exporting can't be trashed.
Base looks (luts/) #
| Group | Files | From |
|---|---|---|
| DJI | dji/DJI OSMO Pocket 4P D-Log2 to Rec.709 [vivid] V1.0 size65.cube, … D-Log … V2.0 size33.cube |
DJI's own, listed on dji.com/lut (no HLG) |
| ACES | <profile>-to-rec709-aces2.cube, …-aces1.cube |
make_luts.py, OpenColorIO's ACES configs |
| AgX | agx/<profile>-<look>.cube |
make_luts.py, Blender's OpenColorIO config (needs Blender in /Applications) |
| ARRI, Fujifilm, Sony, OpenDRT | <pack>/<profile>-<look>.cube |
make_luts.py, from the makers' LUTs in vendor/<pack>/ (below) |
| P4P | p4p/P4P_01_Neutral_size65.cube … P4P_12_Punch_… |
Codebater/pocket4-luts (CC BY 4.0), D-Log2 only |
| Custom | custom/<dlog2|dlog|hlg|rec709>/*.cube |
your own; each shows up as a look for that profile |
uv run --with opencolorio --with numpy scripts/grade/make_luts.py "~/Library/Application Support/Grade/luts"
Other cameras' LUTs take their own log, so make_luts.py converts each profile's footage into it (through
ACES2065-1, exact for every curve and gamut involved) and runs the maker's LUT on that, unmodified. Missing packs are
skipped. Each vendor/<pack>/SOURCE.txt records its download:
vendor/ |
Looks | Input | Download |
|---|---|---|---|
fujifilm/ |
Provia, Velvia, Astia, Classic Chrome, Reala Ace, Pro Neg. Std, Classic Neg., Eterna, Eterna Bleach Bypass, Acros | F-Log2 / F-Gamut | GFX ETERNA 55 3D-LUT v1.10, 65Grid/F-Log2/ (personal, noncommercial use; keep it out of git) |
arri/ |
ALEXA 35 REVEAL, ALEXA Classic | LogC4, LogC3 EI800 | ARRI's LogC4 and LogC3 LUT packages (arri.com, Color › LUTs): the Rec709 D65 gamma 2.4 files |
sony/ |
s709, Cool, Teal & orange, Vintage, Warm | S-Log3 / S-Gamut3.Cine | s709Cubes.zip, NewCubes.zip |
opendrt/ |
Default, Colorful, Umbra | its own OCIO config | OpenDRT v1.0.0 mini config (MIT), unzipped whole |
Every base takes the profile's own code values, read as limited range (the default; the P4P README's advice to read full range lifts blacks). DJI's own LUTs agree: read as limited, D-Log2 and D-Log both put 18% grey at 0.414, and P4P Neutral shares the D-Log2 tone curve exactly.
How the preview stays honest #
color.mjs is shared by the browser and the export: a clip's grade becomes one LUT built by the same function in
both, sampled live on the GPU over a small proxy of the clip's own code values, and baked by ffmpeg from the
original. Deflicker is the one step outside the LUT: it needs the frames around each one, so only the export does
it. On startup the browser decodes a grey ramp encoded like the proxies and compares it with ffmpeg; a decoder
that lands more than 1.5 levels off gets corrected. node scripts/check-grade.mjs (not in CI; it needs WebGL; pass
CHROMIUM_PATH and optionally SCREENSHOT_DIR) grades a synthetic clip, exports it and a frame of it, and checks
both against the preview: mean 0.6 and 0.5 of 255, 95% within 2. It also sets Deflicker through the panel.
Into OpenFilm #
Edit with the files in ~/Movies/Exported/: the originals may only exist on the camera. exports.json says what
each was made with; a clip is current when its record's key matches gradeKey(resolveGrade(grades.json's entry)),
which the app shows as "graded" and otherwise as "changed since export". A clip graded in the app but never exported
shows as "grade not exported"; one with no export and the starting grade shows as "not graded". Regrading and exporting
again replaces the file under the same name, so trims and captions in a film stay valid.