* feat(cli): move media-use engine into the CLI * fix(cli): replace media-use compatibility asset * fix(cli): replace moved media-use tree * fix(cli): copy moved media-use files cleanly * fix(cli): copy media-use engine files individually * fix(cli): keep audio helper compatibility import * fix(cli): clear copied skill destinations * test(cli): preserve moved media-use test paths * fix(cli): preserve media-use script compatibility imports * fix(cli): preserve media-use telemetry shim * fix(cli): resolve packaged media-use LUT assets * fix(cli): resolve packaged bundled SFX assets * chore(skills): regenerate media-use manifest * fix(cli): preserve media-use parity coverage * fix(cli): cover relocated media-use tests * chore(skills): regenerate media-use manifest * fix(cli): format bundled media provider * fix(ci): run relocated media-use tests with node * fix(ci): preserve fallow script exemptions * fix(ci): scope media-use fallow exemption * refactor(cli): trim media-use essay comments * feat(cli): index media-use assets for catalog search * feat(catalog): commit media-use search vectors * chore(catalog): track media vector metadata * fix(catalog): validate media vector row order * fix(catalog): validate media artifact freshness * fix(catalog): cover media metadata and credits * fix(cli): reject malformed media rows * fix(catalog): compare complete media rows * feat(cli): route media search through media-use * refactor(cli): trim relocated media-use comments * fix(cli): make media search runtime-safe * fix(cli): preserve sfx fallback diagnostics * fix(cli): probe sfx fallback provider explicitly * chore(skills): regenerate manifest * refactor(cli): keep typed media ranker source * fix(cli): align media search checks with local-first flow * fix(cli): scope vector audit exceptions * fix(cli): ship resolver registry beside skill * fix(cli): keep media-use skill scripts standalone * test(cli): cover local vector validation * test(cli): correct media vector fixtures * fix(cli): prefer exact media keys * fix(cli): stem exact media keys * test(cli): skip media lint for snippets without media * fix(cli): align skills test discovery Keep the CI skills job's bash discovery as the single source of truth so its empty-list guard covers the exact files Node executes. Make hasMediaVectors private because it has no external callers and needs no Fallow suppression. * fix(cli): close media-use review gaps Prioritize literal ids before stemmed ids and cover the collision alongside the plural regression. Add command seam tests for engine discovery, actionable failure, and argv passthrough. Add a deterministic parity check for standalone media-use copies, with documented allowlists for the standalone media-fetch shim and self-contained npx resolver. Keep the bash-discovered skills test list as the CI source of truth. * fix(cli): lower parity check complexity Split missing-copy and unallowlisted-drift checks so the parity guard keeps its behavior without a threshold CRAP score. * fix(cli): close media-use review seams Run the parity test in the skills job so skills-only edits exercise the same check. Export the verb mapping and inject command dispatch for direct coverage. Keep missing-copy diagnostics separate from drift reads.
6.6 KiB
Color grading — grade blocks and LUTs
Use grade when you need a canonical HyperFrames grading/effects payload for
an <img> or <video>. Core presets and params-backed LUT entries resolve
locally; future CDN-backed LUT entries require network unless already
frozen. Persist a decided payload with the CLI rather than editing HTML by
hand:
For a vague but explicit polish request, do not jump directly from intent to a
preset name. Read media-treatments.md, choose a treatment whose subject and
avoid rules match the actual media, apply its conservative base with only
justified bounded tuning, then complete its visual verification steps. A named
owned treatment uses the exact preset/payload in its recipe; do not run the
generic grade/LUT resolver first.
Stop here and use that treatment workflow for requests such as retro, old home video, camcorder, film, print, ASCII, glitch, privacy, or a media reveal. Do not assemble those from a generic LUT plus handmade CSS vignette/grain/opacity.
Never cat/read a .cube file into context. A 3D LUT is ~size^3 lines of raw numbers (33^3 ≈ 36k lines at the default size). It bloats context and carries zero human/agent-legible signal. To understand or choose a LUT, use hyperframes grade-compare to see it rendered, or cube-validate.mjs for a one-line {ok,size} check. Read .media/index.md or luts/index.json for the description. Never read the LUT body itself.
npx hyperframes media-use resolve --type grade --intent "warm daylight" --project . --json
Preset-first output uses the core runtime vocabulary and does not freeze a file:
{
"preset": "warm-daylight",
"intensity": 1
}
Apply that payload to one unambiguous real media element:
hyperframes media-treatment --project . --file index.html \
--selector '#hero' \
--grading '{"preset":"warm-daylight","intensity":1}' --apply --json
Use --dry-run before writing when scope is uncertain and --clear to remove
the treatment. The low-level persisted result is still normal HTML:
<video
class="clip"
src="./media/scene.mp4"
data-color-grading='{"preset":"warm-daylight","intensity":1}'
></video>
Direct attribute authoring is a fallback for environments where the CLI is not available, not the primary agent workflow.
To build a treatment that is not already represented by a recipe, inspect the canonical toolbox first:
hyperframes media-treatment --capabilities --json
It reports a concise family map. Read --capability grading for the processing
order, then request only the focused family needed to get its legal controls
and ranges from Core. Compose one nested payload and pass it back through
hyperframes media-treatment; the command rejects unknown keys before
mutation. Do not generate or hand-edit a LUT merely to combine controls already
owned by the realtime shader.
For seek-safe effect motion, animate only the runtime-supported CSS properties on that same real media element with its registered paused GSAP timeline:
| CSS property | Range |
|---|---|
--hf-color-grading-intensity |
0 to 1 |
--hf-color-grading-lut-intensity |
0 to 1 |
--hf-color-grading-exposure |
-2 to 2 |
--hf-color-grading-blur |
0 to 1 |
--hf-color-grading-bloom |
0 to 3 |
--hf-color-grading-kuwahara |
0 to 1 |
--hf-color-grading-pixelate |
0 to 1 |
--hf-color-grading-ascii |
0 to 1 |
--hf-color-grading-dither |
0 to 1 |
Author the initial value directly in the media element's inline style, then
use finite tl.to() keyframes. Do not use a frame-zero tl.set(), CSS
animation clocks, timers, random values, or onUpdate callbacks. The static
data-color-grading payload remains the fallback and source of the other
controls.
For a reusable color transform beyond the preset vocabulary, freeze a validated
.cube under .media/luts/ and return a block that references it:
npx hyperframes media-use resolve --type grade --intent "teal orange blockbuster" --project . --json
{
"intensity": 1,
"lut": { "src": ".media/luts/grade_001.cube", "intensity": 0.85 }
}
Use lut when you only need the reusable .cube file:
npx hyperframes media-use resolve --type lut --intent "teal orange blockbuster" --project .
For a describable technical look, author an explicit parametric LUT with --params:
npx hyperframes media-use resolve --type lut --params '{"contrast":0.2,"temperature":-0.3}' --project .
npx hyperframes media-use resolve --type grade --params '{"exposure":0.2}' --project . --json
For a LUT generated by your own script, ingest it with --from; media-use validates it before registration and rejects invalid or oversized cubes:
npx hyperframes media-use resolve --type lut --from custom.cube --project .
Parametric math (buildCube) cannot reproduce real film stocks or emulsion
transforms. Use a CDN-backed scanned .cube entry or ingest a real scanned
.cube for those.
For visual selection, list reusable LUT candidates with
resolve --type grade --candidates, write the promising entries to a
grades.json, run
hyperframes grade-compare --for <frame> --grades grades.json, then commit the
winner with resolve -t grade as the final data-color-grading block.
For media already selected in a composition, use media-treatment --analyze
when you need side-effect-free ffmpeg/ffprobe signalstats evidence. It
returns source metadata, HDR/unknown-LOG warnings, and a bounded adjust
suggestion without modifying the composition. The suggestion is a starting
point for visual review, not an automatic neutralization of intentional color.
hyperframes media-treatment --project . --file index.html \
--selector '#hero' --analyze --json
For an unbound source file, resolve --type grade --for ... --analyze remains
available. Without --analyze, that resolver records a grade candidate in
.media; use that form only when you intend to keep the candidate.
Library LUT entries live in luts/index.json. Each entry keeps id,
description, tags, and intensity, then supplies either compact params
for on-demand buildCube(params) generation or a direct CDN url for future
scanned .cube files. Do not commit generated .cube bodies; resolve
validates generated or downloaded cubes as it freezes them under
.media/luts/.
npx hyperframes media-use resolve --type lut --intent "teal orange blockbuster" --project . --json
node skills/media-use/scripts/lib/cube-validate.mjs .media/luts/lut_001.cube