From a4e6bc3254af622ad1b286979add556682893dd8 Mon Sep 17 00:00:00 2001 From: Ular Kimsanov Date: Mon, 26 Oct 2026 01:45:25 +0000 Subject: [PATCH] docs(guides): media pages titled by the task people search for (#6360) * docs(guides): media pages titled by the task people search for * docs(guides): background fixes as a visible section; list color grading as an agreed deletion --- docs/docs.json | 6 +- docs/guides/color-grading.mdx | 189 ---------------------------- docs/guides/export-and-share.mdx | 4 +- docs/guides/media-effects.mdx | 166 +++++++++++++----------- docs/guides/media.mdx | 2 +- docs/guides/remove-background.mdx | 161 ++++++++---------------- docs/guides/video-components.mdx | 124 +++++++++--------- docs/guides/voice-and-audio.mdx | 145 +++++++-------------- docs/packages/cli.mdx | 2 +- docs/prompting/color-grading.mdx | 4 +- docs/prompting/media-and-audio.mdx | 2 +- docs/reference/color-grading.mdx | 2 +- docs/reference/html-schema.mdx | 2 +- scripts/check-no-main-deletions.mjs | 4 + 14 files changed, 271 insertions(+), 542 deletions(-) delete mode 100644 docs/guides/color-grading.mdx diff --git a/docs/docs.json b/docs/docs.json index b0a8258413..d43cf8d8e0 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -178,7 +178,6 @@ "guides/avatar-presenter", "guides/voice-and-audio", "guides/remove-background", - "guides/color-grading", "guides/media-effects", "guides/export-and-share" ] @@ -1309,6 +1308,11 @@ "source": "/prompting/motion-graphics", "destination": "/guides/motion-graphics#prompts-that-work", "permanent": true + }, + { + "source": "/guides/color-grading", + "destination": "/guides/media-effects#fix-and-grade-the-color", + "permanent": true } ], "integrations": { diff --git a/docs/guides/color-grading.mdx b/docs/guides/color-grading.mdx deleted file mode 100644 index 5bc45a0be7..0000000000 --- a/docs/guides/color-grading.mdx +++ /dev/null @@ -1,189 +0,0 @@ ---- -title: "Color grade images and footage" -sidebarTitle: "Color grading" -description: "Fix exposure and color on an image or video, shape a look with wheels and curves, apply a LUT, and check the result against real measurements." ---- - -import { DocsVideo } from "/snippets/docs-video.jsx"; - -Grading changes how a photo or video **looks** — brighter, warmer, moodier, more -or less colorful. It runs on one media element at a time. The file on disk never -changes, and text, captions, SVG and ordinary HTML stay on their own layers, -untouched. - - - The same presenter frame before and after a restrained natural portrait grade - - - - -Every control moves and the picture answers. The numbers on screen are measured -from the frame, not illustrative — shadows lifted 2% to 23%, median 28% to 41%. - -## Correct first, then style - -Get exposure, white balance, contrast and saturation believable first. Then shape -the tonal ranges or a single color, then a preset or a LUT, then grain, vignette -and film effects last. No preset rescues blown-out highlights, shadows with -nothing left in them, or the wrong shot. - -## Try it in Studio - -Select an image or video — on the canvas, in Layers, or on the timeline — and -open **Grade** in the Inspector. - -Start with a preset. There are thirteen, from Neutral and Clean Studio to Night Lift, and Studio renders each as a thumbnail of **your** frame rather than -someone else's sample. **Strength** dials the chosen look between nothing and -full. - -{/* VISUAL NEEDED (1): Studio's preset thumbnail grid — all thirteen Grade presets on one real frame, Neutral through Night Lift. */} - -Hold the compare button in the panel header to flash back to the original. On -moving footage, scrub several places first — a grade that flatters one frame can -wreck the next. - -## What each control does - -| Control | Use it for | -| --- | --- | -| Preset and strength | Pick a whole look, then dial it back | -| Exposure, contrast, highlights, shadows, whites, blacks | Brightness and contrast, overall and per tonal range | -| Warmth, tint, vibrance, saturation | Take out a color cast, or push color further | -| Color wheels | Tint shadows, midtones and highlights separately | -| RGB curves | Redraw the brightness ramp — whole image, or red, green and blue one at a time | -| Hue curves | Pick one hue and move only it: shift, saturate or brighten | -| HSL selections | Key a band of hue, saturation and brightness, then correct only those pixels. Up to four, in order | -| Grain and vignette | Add texture, or darken the edges to pull the eye in | -| Custom LUT | Load a `.cube` file that maps every color to another | - -{/* VISUAL NEEDED (2): color wheels, a bent RGB curve, a hue curve and one HSL -selection, each beside the frame it produced. */} - -## Read the scopes, not your screen - -Scopes measure the picture live, so you are not guessing from a monitor that may -be too bright. Studio draws four. - -- **Histogram** — how much of the frame is dark, mid, or bright. Piled against - either end means detail is already gone. -- **Waveform** — brightness across the frame left to right, so you see *which - part* is blown out. -- **RGB parade** — that waveform split into red, green and blue. One channel - riding high is your color cast, named. -- **Vectorscope** — a circle of hues: direction is which color, distance from the - centre is how saturated. Skin tones land on one known line, so faces are quick - to check. - -{/* VISUAL NEEDED (3): the four scopes side by side, on the same frame before -and after a correction. */} - -## Compare candidate looks in one image - -Instead of flipping between options, render them all onto one reference frame: - -```bash -npx hyperframes grade-compare --for frame.png --grades grades.json -``` - -`--grades` takes a JSON array of `{ label, grading }` entries; `--for` takes an -image, or a video sampled at its first frame. The untouched frame leads as a cell -labelled `original` unless you pass `--no-baseline`. Up to sixteen cells land -four to a row in `grade-compare.png`, or wherever `--out` points. Swap `--grades` -for `--luts looks/a.cube,looks/b.cube` to compare LUT files the same way. - -Phone photos keep their displayed orientation and aspect ratio in the sheet; -the source image file stays unchanged. - -{/* VISUAL NEEDED (4): a real grade-compare.png sheet — the labelled grid with -`original` in the first cell. */} - -## Or describe the problem to the agent - -You do not need to name controls or invent values: - -```text -The interview looks too dark and slightly cold. -Keep skin natural, recover the background enough to read, and avoid a filtered look. -``` - -The agent can list what exists, and measure a local source before changing it: - -```bash -npx hyperframes media-treatment --capabilities --json -npx hyperframes media-treatment --selector '#interview' --analyze --json -``` - -`--analyze` reports the source's color metadata, where its brightness sits, what -is clipping, and a bounded correction to start from. For source-sensitive prompts -and worked before-and-afters, see -[Color grading and film effects](/prompting/color-grading). - -## Reuse a grade - -**Copy grade to** applies the current grade to other media, in this file or -across the project — a starting point, since the same numbers rarely suit two -shots. Project-wide copy refuses a relative LUT path, because that path means -something different from another composition's folder; stay in the current file, -or use a LUT reachable by URL or data URL. - -## Use a LUT only when you know what it expects - -A LUT is a lookup table: a file mapping every input color to an output color. -HyperFrames reads a 3D `.cube` file up to 64 points per side and blends it in at -an intensity you set. - -Nothing normalizes your footage first — HyperFrames does not identify camera -profiles or run an ACES or OCIO pipeline, the color-management systems film -finishing uses. The safe case is a creative Rec.709 LUT, built for ordinary web -and broadcast video, which is also the only color space these controls work in. -LOG footage, shot deliberately flat and grey so it holds detail for grading, -needs the transform its camera expects or comes out wrong rather than stylized. - -{/* VISUAL NEEDED (5): one frame under two or three .cube LUTs, plus the same -LUT at partial and full intensity. */} - -## Where the grade is stored - -Studio and the CLI write the result into `data-color-grading`, in named sections: -corrections under `adjust`, grain and vignette under `details`, stylized -treatments under `effects`. - -```html - -``` - -The nesting is not optional. A flat object such as `{"exposure":0.15}` renders -nothing at all; `npx hyperframes lint` catches it and names the section the -control belongs in. - -## What it cannot do - -Grading picks pixels by value, never by position: no face tracking, region -tracking, rotoscoping or masks — an HSL selection is a color qualifier, not a -shape. To treat one part of a frame, split it into its own media layer and grade -that layer, as in the [implementation reference](/reference/color-grading). It -targets `