Media treatments

A media treatment is a source-aware plan that composes existing HyperFrames color, effect, timeline, and Registry primitives. It is not a second runtime schema. Use this file to choose a primary direction. A matching recipe is an optional tested seed; bespoke requests may assemble a validated treatment from the canonical capability catalog.

Permission and scope

• An explicit request such as "polish this", "make it look better", or "make it fit the topic" delegates a conservative treatment. Apply it, verify it, and report what changed.
• During an unsolicited opportunity scan, show or suggest the treatment first.
• Target meaningful photographic media. Skip text, SVG, logos, icons, UI chrome, and intentionally stylized footage unless the user asks.
• Realtime grading and effects apply to the entire selected real <img> or <video>. They do not isolate or track a face, plate, address, or other region. For region-only work, first create a separate cropped/masked media layer or use an external segmentation/tracking tool; never imply that a whole-media Blur or Pixelate performed region isolation.
• The realtime treatment path is Rec.709/SDR. Do not silently process HDR, HLG, PQ, or camera LOG sources through it.

Classify the request

Choose the smallest lane that satisfies the request before choosing a recipe or assembling a custom treatment:

The lane identifies the primary reason for the change; it is not a one-feature limit. A final treatment may combine correction, a preset, finishing, multiple compatible shader effects, finite keyframed values, and optional overlays when the inspected media and user intent justify the complete combination. Keep one primary intent as the creative anchor so the result remains coherent and deterministic.

Do not add a stylized Effect when correction solves the complaint. Do not change color when the request is only temporal, and do not install an overlay when the selected media alone communicates the result.

Match strength to intent. When the user explicitly names a bold look such as VHS, glitch, ASCII, halftone, camcorder, print, or engraving, apply its signature effects strongly enough to read unmistakably. The guard against unrequested additions does not mean under-delivering an effect the user asked for. Correction and polish stay restrained; named stylization must be obvious in the after-frame.

Translate vague feedback conservatively

When more than one lane could fit, generate at most two candidates and choose from inspected before/after evidence. Ordinary correction or polish starts with one candidate; a second candidate is an escalation, not the default. Do not stack effects merely to make the answer look more sophisticated.

Seed or assemble

Use the table when a tested recipe directly fits. Read only that recipe section. Recipes are optional macros, not a closed list of allowed results.

Use rg -n '^## <heading>$' <SKILL_DIR>/references/media-treatment-recipes.md, then read only from that heading to the next ##. Do not load the entire cookbook for one request.

When source intent is unclear, inspect the concise capability overview:

hyperframes media-treatment --capabilities --json

It lists the complete surface by family with one-line descriptions. Then load only the family, effect, preset, or palette relevant to the inspected source:

hyperframes media-treatment --capability <id> --json

The focused result provides legal controls, recommended apply values, render cost, palette support, and the exact animation contract when supported. Use --all only for tooling/tests or a genuinely exhaustive audit. Compose one nested payload from these existing parts. Recipes and catalog-built payloads use the same renderer and persistence contract.

Treat renderLane: "multipass" as a cost signal. Blur, Bloom, and Kuwahara are bounded but more expensive than single-pass effects; avoid stacking several of them across many simultaneous media elements unless the composition needs it, then verify playback and a draft render. Cost follows treated pixel area as well as element count. More than two simultaneously visible full-frame multipass media layers requires a continuous playback check on the target machine; simplify or pre-render the stack if it drops frames. Do not impose or claim a universal hard cap from one machine.

Common workflow

1. Confirm the target is a real <img> or <video> and inspect source color metadata.
2. For an image, read it once. For video, capture early/middle/late output as one labeled sheet and read that one image:

bash hyperframes snapshot <project> --frames 3 --no-end \ --output snapshots/treatment-before

Read snapshots/treatment-before/contact-sheet.jpg; do not spend separate model turns reading each frame unless the sheet exposes a specific problem. Do not infer semantics from signal statistics alone.

1. Choose one primary lane. Use one matching recipe as a tested seed, or read the overview and one focused capability detail when the request is bespoke. A seed may be changed or combined with compatible catalog controls when the contact sheet justifies it. Do not invent keys, exceed reported ranges, or stack effects without a visual reason. Do not run the generic grade/LUT resolver first; it adds irrelevant candidates and may download an unused LUT. Use media-treatment --selector "#hero" --analyze --json only when correction needs measured signal evidence.
2. Persist pixel settings with hyperframes media-treatment; it validates and merges a patch into the existing nested data-color-grading contract. Use registered GSAP only for supported animated values and Registry overlay blocks only for authored dressing. ``bash hyperframes media-treatment --selector "<selector>" \ --grading '<nested JSON patch>' --apply --json ` A selector that matches several images or videos patches every match, each merged into its own current grading (the JSON reports count and each target); run --clear first for an identical look, or add --selector-index to patch only one. For a temporal reveal, use the focused capability result's animation contract. If it is null, the capability is static. Author the starting CSS property inline on the real media element and return temporary treatment values to neutral so the finished shot preserves its existing pixels. Prefer that bounded media animation first; if an overlay is justified, install the owned Registry block instead of recreating it with bespoke overlay markup. For correction and ordinary polish, keep those values as editable preset/adjustment JSON; do not generate a LUT for controls the realtime shader already owns. Use the canonical details/effects` fields for vignette, grain, blur, pixelate, and related primitives. Do not duplicate them with CSS filters, SVG turbulence, opacity, or decorative DOM overlays.
3. When the treatment calls for an overlay, install that named block with hyperframes add <name> --dir <project> --no-clipboard --json, inspect its returned data-composition-src host, and place it once using the block's timing contract. Check for the installed file and host element ID before insertion; never duplicate an existing overlay block. This is one treatment workflow: do not make the user discover Catalog or separately ask for the recipe's justified overlay.
4. For ordinary correction/polish, capture one after-sheet with the same three timestamps under snapshots/treatment-after, compare it to the before-sheet, and stop when the result is clearly better. Run the normal project check; do not encode a draft solely to prove a static correction.
5. Escalate only when evidence requires it. Read individual frames to diagnose a specific visual problem. Preview and render moving evidence when judging treatment keyframes, glitch/tape motion, overlays, playback smoothness, LUT timing, or any other temporal behavior. HDR/LOG, privacy, and brand-sensitive work also require the existing explicit caveats and stronger verification. If the treatment is not clearly better, keep the source unchanged.
6. Report the selected media, primary intent, recipe seed if used, final composed controls, optional overlays, and the frames/render that were actually checked. Do not report visual quality from command success alone.

media-treatment --analyze provides deterministic clipping and signal evidence for local composition media, not subject recognition or automatic taste. It reports HDR/metadata caveats and a bounded primary-correction patch; it does not invent wheels, curves, or HSL selections from statistics.