[teamai] Push 87 resource(s) from XingfenD
This commit is contained in:
@@ -0,0 +1,202 @@
|
||||
# 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:
|
||||
|
||||
| User intent | Lane |
|
||||
| --------------------------------------------------- | ------------------------------------------ |
|
||||
| too dark, flat, too warm, too many shadows | correction |
|
||||
| shape shadows/highlights or selected colors | wheels, curves, or HSL secondary |
|
||||
| polished, premium, warm, cinematic, fit the topic | preset or custom treatment |
|
||||
| retro, print, ASCII, glitch, camcorder | shader effect or effect-bearing preset |
|
||||
| obscure the whole selected media | privacy Blur or Pixelate |
|
||||
| hide one face, plate, address, or screen region | separate crop/mask/asset or external tool |
|
||||
| draw attention to media without changing its pixels | framing, motion, or optional overlay |
|
||||
| reveal, focus, depixelate, fade the treatment | finite seek-safe treatment keyframes |
|
||||
| REC HUD, light leak, flash, freeze-frame cutout | Registry overlay plus any justified pixels |
|
||||
|
||||
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
|
||||
|
||||
| User feedback | First action | Add only when the frames justify it | Never infer |
|
||||
| ------------------------------------- | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | ----------------------------------------------- |
|
||||
| too many shadows and a bit boring | lift shadows/protect highlights, then compare one restrained source-appropriate preset | mild contrast or vibrance | retro texture, HUD, or palette effect |
|
||||
| make the product footage feel premium | protect product color and labels, compare Product Polish | restrained vignette on lifestyle footage | a cinematic LUT or crushed blacks |
|
||||
| make this reveal cooler | preserve color and animate one supported effect or treatment value | a short owned overlay block | unrelated whole-clip styling |
|
||||
| make it feel like an old home video | compare 8mm and VHS language against the source | finite weave/flicker or justified HUD | that every old-video request means VHS |
|
||||
| hide this face | explain that realtime effects are whole-media; isolate the region first or use an external tool | whole-media Blur/Pixelate only when the user accepts that scope | face tracking or masking that was not performed |
|
||||
| keep the brand colors exact | leave UI/logo pixels unchanged; use framing and motion | demonstrated exposure-only correction | stylized preset, palette, or LUT |
|
||||
|
||||
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.
|
||||
|
||||
| Intent or source | Recipe heading to read |
|
||||
| -------------------------------------------------------- | ------------------------------------------------- |
|
||||
| Talking head, interview, presenter, people-focused photo | `Natural Portrait` |
|
||||
| Product footage, lifestyle footage, clean social polish | `Product Polish` |
|
||||
| Screen capture, dashboard, website, app UI | `UI Fidelity` |
|
||||
| Warm memory, restrained nostalgia | `Film Memory` |
|
||||
| Creator/UGC handheld camera character | `Creator Camcorder` |
|
||||
| Analog tape playback | `VHS Playback` |
|
||||
| Small-gauge home-movie character | `8mm Home Movie` |
|
||||
| Editorial dots or ink print | `Editorial Halftone` or `Two-Ink Editorial Print` |
|
||||
| Monochrome dot/line screen print | `Monochrome Screen Print` |
|
||||
| Engraved or hand-hatched illustration | `Engraved Illustration` or `Crosshatched Sketch` |
|
||||
| Curved scanlined display | `CRT Display` |
|
||||
| Glyph-based art | `Procedural ASCII` |
|
||||
| Realtime palette quantization | `Ordered Palette Dither` |
|
||||
| Exact historical error diffusion | `Cached Error Diffusion` |
|
||||
| Finite warm flare layer | `Organic Light Leak` |
|
||||
| Held-frame graphic interruption | `Freeze-Frame Cutout` |
|
||||
| Short exposure-flash transition | `Social Flash / Editorial Reveal` |
|
||||
|
||||
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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
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 --describe false \
|
||||
--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.
|
||||
|
||||
3. 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.
|
||||
4. 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 "<unique selector>" \
|
||||
--grading '<nested JSON patch>' --apply --json
|
||||
```
|
||||
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.
|
||||
5. 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.
|
||||
6. 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.
|
||||
7. 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.
|
||||
8. 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.
|
||||
Reference in New Issue
Block a user