Files
hyperframes/skills/media-use/references/grading.md
Miguel Ángel 3091dcb787 feat(cli): route media search through media-use (#4230)
* 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.
2026-09-21 18:35:47 -04:00

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