Skip to content

Commit 72d4016

Browse files
committed
docs: rewrite four pages that told instead of showed
**Color grading** was the worst page in the docs by the measure that matters: 33 table rows against one image, for the most visual feature in the product. Four of the five tables were restating jargon in a grid — "Waveform | Brightness by horizontal image position" tells you nothing you could act on. Those are prose now, and the scopes section explains what each one is *for* (skin tones land on one known line of a vectorscope, so faces are quick to check). The control lookup stays a table, because that one is a genuine lookup. Four factual errors in the old page, each verified at source before changing: Studio's group is **Grade** in the flat Inspector, not "Color grading" in Design; the controls are `whites`/`blacks`, not "white point/black point"; LOG and HDR were conflated into one sentence when they are different cases; and the project-wide LUT copy refuses a relative path in favour of a URL or data URL, not a "project-root path". Two things the page never mentioned and should have: `hyperframes grade-compare`, which renders every candidate look onto one reference frame, and the fact that `data-color-grading` nests under adjust/details/effects — a flat object renders nothing at all. **vs Remotion** argued for 851 words with nothing to look at and no code. It now carries the same three-second title card written both ways. The HyperFrames one is a real composition, not illustrative markup: extracted and run through lint (0/0) and the full browser gate — runtime, layout, motion and contrast all pass. It also concedes what Remotion genuinely does better, because a comparison page that only flatters us is not worth reading. **Choose how to create** never said what the four options were before comparing them. It opens with the actual decision now — they all give you a video, the difference is what you keep — and a four-row table of what you walk away with. **Bring in a design** loses the 7-row keep-vs-rebuild table for one plain rule, and the bullet list that used semicolons. Every internal link on all four checked against the real page set. Where a visual belongs but no approved asset exists, there is a JSX comment marking the spot rather than a URL that would 404.
1 parent 84b5160 commit 72d4016

4 files changed

Lines changed: 342 additions & 240 deletions

File tree

Lines changed: 30 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1,70 +1,58 @@
11
---
22
title: "Choose how to create"
33
sidebarTitle: "Choose how to create"
4-
description: "Choose between a local HyperFrames project, hosted chat, a design-first handoff, or a HeyGen-generated video."
4+
description: "Four places to make a HyperFrames video, and how to tell which one is yours."
55
---
66

7-
## I want an editable project on my computer
7+
There are four places to make a HyperFrames video. They all give you a video.
8+
The difference is what you keep afterwards. Unsure? Take the first one.
89

9-
Use a coding agent with the HyperFrames skills. The agent writes an ordinary
10-
HTML project that you can revise with the agent, open in Studio, inspect in
11-
source, render locally, or automate later.
10+
| Start here | You end up with |
11+
| --- | --- |
12+
| A coding agent on your computer | A project folder you own and keep editing |
13+
| An AI chat | A video made and kept in your HeyGen account |
14+
| A design tool | A look to finish on your computer |
15+
| HeyGen Video Agent | A finished video, assembled for you |
1216

13-
This is the default path for a video that will keep changing.
17+
## Start on your computer if the video will change
18+
19+
A coding agent — an AI assistant that works in a folder on your machine, like
20+
Claude Code or Cursor — writes a plain HTML project. Revise it with the agent,
21+
open it in Studio, read the source, make the MP4 locally.
1422

1523
```text
1624
Using /hyperframes, make a 10-second product intro for https://example.com.
1725
```
1826

19-
<Card title="Make your first local video" icon="play" href="/quickstart" horizontal arrow>
20-
Install the skills and create the first editable version.
21-
</Card>
22-
23-
## I want to create inside an AI chat
27+
[Make your first local video →](/quickstart)
2428

25-
Use the hosted HyperFrames MCP connector. It creates and renders through your
26-
HeyGen account without a local HyperFrames setup.
29+
## Start in an AI chat if you want nothing installed
2730

28-
Choose this when convenience matters more than owning the complete project
29-
folder. Rendering and account access are hosted; local Studio, source editing,
30-
self-hosting, and precise debugging belong to the local path.
31+
The hosted HyperFrames connector (an MCP connector — a plug-in an AI chat can
32+
use) builds and renders through your HeyGen account. You give up the project
33+
folder, Studio, and local rendering.
3134

3235
[Connect HyperFrames to an AI chat →](/guides/mcp)
3336

34-
## I want to establish the visual direction first
35-
36-
Start in Figma, Claude Design, or Open Design when brand, layout, and scene
37-
direction are the unresolved part. Then hand the project to a coding agent for
38-
motion refinement, media, validation, and rendering.
37+
## Start in a design tool if the look is the open question
3938

40-
The design tool supplies a first draft, not a substitute for watching and
41-
checking the finished movement.
39+
Figma, Claude Design, and Open Design settle brand, layout, and scene direction
40+
first. Hand that draft to a coding agent for the motion, media, and rendering —
41+
no design tool can tell you whether the movement works.
4242

4343
[Bring a design into a project →](/guides/design-tools)
4444

45-
## I want to create inside HeyGen
45+
## Start in HeyGen if you want it done for you
4646

47-
Use HeyGen Video Agent when you want a hosted prompt-native workflow that
48-
assembles the script, visuals, narration, avatar, and motion for you. HyperFrames
49-
can power its HTML motion graphics, but the delivery surface is different: the
50-
local path gives you the project folder, source, Studio, and CLI; Video Agent
51-
keeps generation and revision inside HeyGen.
47+
HeyGen Video Agent takes a prompt and assembles the script, visuals, narration,
48+
avatar, and motion. It stays inside HeyGen — no folder, no source, no CLI — and
49+
it can draw on your account allowance or credits. Rendering on your own computer
50+
never does.
5251

5352
[Learn how HeyGen Video Agent works →](https://help.heygen.com/en/articles/12402907-how-to-get-started-with-video-agent)
5453

55-
If a generated person is only one layer in a locally editable film, [add the
56-
presenter as media inside a HyperFrames project](/guides/avatar-presenter).
57-
HeyGen generation can use an account allowance or credits; local HyperFrames
58-
rendering does not.
59-
60-
## If you are unsure
61-
62-
Start with the local path. It preserves the most options because the project
63-
stays editable. Use the [developer journey](/developers) instead when your goal
64-
is an application or automated pipeline rather than one video.
65-
6654
## Related topics
6755

6856
- [Make a first local video](/quickstart)
69-
- [Create through a hosted AI chat](/guides/mcp)
70-
- [Bring a design into a HyperFrames project](/guides/design-tools)
57+
- [Add an avatar presenter to a project you can still edit](/guides/avatar-presenter)
58+
- [Build an app or a pipeline instead of one video](/developers)

‎docs/guides/color-grading.mdx‎

Lines changed: 126 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,13 @@
11
---
22
title: "Color grade images and footage"
33
sidebarTitle: "Color grading"
4-
description: "Correct exposure and color, shape a look, apply a LUT, and review the result in Studio."
4+
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."
55
---
66

7-
Use Color Grading when an image or video needs correction or a deliberate
8-
visual look. It changes that media element only; text, captions, SVG, and normal
9-
HTML remain separate layers.
7+
Grading changes how a photo or video **looks** — brighter, warmer, moodier, more
8+
or less colorful. It runs on one media element at a time. The file on disk never
9+
changes, and text, captions, SVG and ordinary HTML stay on their own layers,
10+
untouched.
1011

1112
<Frame caption="The same source before and after a restrained natural-portrait grade.">
1213
<img
@@ -15,114 +16,161 @@ HTML remain separate layers.
1516
/>
1617
</Frame>
1718

18-
## Work in this order
19+
## Correct first, then style
1920

20-
| Pass | Purpose |
21-
| --- | --- |
22-
| Correct | Fix exposure, white balance, contrast, and saturation |
23-
| Grade | Shape tonal ranges or a selected color |
24-
| Apply a look | Start from a preset or a compatible `.cube` LUT |
25-
| Finish | Add restrained detail or film effects |
21+
Get exposure, white balance, contrast and saturation believable first. Then shape
22+
the tonal ranges or a single color, then a preset or a LUT, then grain, vignette
23+
and film effects last. No preset rescues blown-out highlights, shadows with
24+
nothing left in them, or the wrong shot.
25+
26+
## Try it in Studio
27+
28+
Select an image or video — on the canvas, in Layers, or on the timeline — and
29+
open **Grade** in the Inspector.
2630

27-
Correct before stylizing. A strong preset cannot rescue clipped highlights,
28-
unreadable shadows, or the wrong source.
31+
Start with a preset. There are eighteen, from Clean Studio and Skin Soft to VHS
32+
Playback, and Studio renders each as a thumbnail of **your** frame rather than
33+
someone else's sample. **Strength** dials the chosen look between nothing and
34+
full.
2935

30-
## Grade in Studio
36+
{/* VISUAL NEEDED (1): Studio's preset thumbnail grid — all eighteen presets on
37+
one real frame, Clean Studio through VHS Playback. */}
3138

32-
1. Select an image or video on the canvas, in Layers, or on the timeline.
33-
2. Open **Color grading** in **Design**.
34-
3. Start with a preset or small corrections.
35-
4. Use the scopes and compare control to check the result.
36-
5. Scrub several moments before judging moving footage.
39+
Hold the compare button in the panel header to flash back to the original. On
40+
moving footage, scrub several places first — a grade that flatters one frame can
41+
wreck the next.
3742

38-
The controls answer different questions:
43+
## What each control does
3944

4045
| Control | Use it for |
4146
| --- | --- |
42-
| Preset and strength | Establish a starting look |
43-
| Exposure, contrast, highlights, shadows, white point, black point | Correct brightness and contrast |
44-
| Warmth, tint, vibrance, saturation | Correct or shape color |
45-
| Color wheels | Shift shadows, midtones, or highlights |
46-
| RGB curves | Remap luminance or individual channels |
47-
| Hue curves | Move, saturate, or brighten a selected hue |
48-
| HSL selections | Correct pixels inside a hue, saturation, and luma range |
49-
| Grain, vignette, blur, and effects | Finish or deliberately degrade the image |
50-
| Custom LUT | Apply a known 3D `.cube` transform |
51-
52-
HyperFrames supports up to four ordered HSL selections. They are static
53-
pixel-value qualifiers, not object tracking, rotoscoping, or spatial masks.
54-
55-
Studio scopes are inspection tools:
56-
57-
| Scope | Shows |
58-
| --- | --- |
59-
| Histogram | Overall dark-to-bright distribution |
60-
| Waveform | Brightness by horizontal image position |
61-
| RGB Parade | Channel balance and clipping |
62-
| Vectorscope | Hue direction and saturation |
47+
| Preset and strength | Pick a whole look, then dial it back |
48+
| Exposure, contrast, highlights, shadows, whites, blacks | Brightness and contrast, overall and per tonal range |
49+
| Warmth, tint, vibrance, saturation | Take out a color cast, or push color further |
50+
| Color wheels | Tint shadows, midtones and highlights separately |
51+
| RGB curves | Redraw the brightness ramp — whole image, or red, green and blue one at a time |
52+
| Hue curves | Pick one hue and move only it: shift, saturate or brighten |
53+
| HSL selections | Key a band of hue, saturation and brightness, then correct only those pixels. Up to four, in order |
54+
| Grain and vignette | Add texture, or darken the edges to pull the eye in |
55+
| Custom LUT | Load a `.cube` file that maps every color to another |
56+
57+
{/* VISUAL NEEDED (2): color wheels, a bent RGB curve, a hue curve and one HSL
58+
selection, each beside the frame it produced. */}
59+
60+
## Read the scopes, not your screen
6361

64-
## Give the agent the visible problem
62+
Scopes measure the picture live, so you are not guessing from a monitor that may
63+
be too bright. Studio draws four.
6564

66-
You do not need to prescribe shader values:
65+
- **Histogram** — how much of the frame is dark, mid, or bright. Piled against
66+
either end means detail is already gone.
67+
- **Waveform** — brightness across the frame left to right, so you see *which
68+
part* is blown out.
69+
- **RGB parade** — that waveform split into red, green and blue. One channel
70+
riding high is your color cast, named.
71+
- **Vectorscope** — a circle of hues: direction is which color, distance from the
72+
centre is how saturated. Skin tones land on one known line, so faces are quick
73+
to check.
74+
75+
{/* VISUAL NEEDED (3): the four scopes side by side, on the same frame before
76+
and after a correction. */}
77+
78+
## Compare candidate looks in one image
79+
80+
Instead of flipping between options, render them all onto one reference frame:
81+
82+
```bash
83+
npx hyperframes grade-compare --for frame.png --grades grades.json
84+
```
85+
86+
`--grades` takes a JSON array of `{ label, grading }` entries; `--for` takes an
87+
image, or a video sampled at its first frame. The untouched frame leads as a cell
88+
labelled `original` unless you pass `--no-baseline`. Up to sixteen cells land
89+
four to a row in `grade-compare.png`, or wherever `--out` points. Swap `--grades`
90+
for `--luts looks/a.cube,looks/b.cube` to compare LUT files the same way.
91+
92+
{/* VISUAL NEEDED (4): a real grade-compare.png sheet — the labelled grid with
93+
`original` in the first cell. */}
94+
95+
## Or describe the problem to the agent
96+
97+
You do not need to name controls or invent values:
6798

6899
```text
69100
The interview looks too dark and slightly cold.
70101
Keep skin natural, recover the background enough to read, and avoid a filtered look.
71102
```
72103

73-
The agent can inspect the current capability contract and analyze a local
74-
source before changing it:
104+
The agent can list what exists, and measure a local source before changing it:
75105

76106
```bash
77107
npx hyperframes media-treatment --capabilities --json
78108
npx hyperframes media-treatment --selector '#interview' --analyze --json
79109
```
80110

81-
For source-sensitive prompts and worked A/B examples, continue to
111+
`--analyze` reports the source's color metadata, where its brightness sits, what
112+
is clipping, and a bounded correction to start from. For source-sensitive prompts
113+
and worked before-and-afters, see
82114
[Color grading and film effects](/prompting/color-grading).
83115

84-
## Reuse a grade carefully
116+
## Reuse a grade
85117

86-
In Studio, use **Copy grade to** for other media in the current file or project.
87-
Treat the copy as a starting point and inspect each source.
118+
**Copy grade to** applies the current grade to other media, in this file or
119+
across the project — a starting point, since the same numbers rarely suit two
120+
shots. Project-wide copy refuses a relative LUT path, because that path means
121+
something different from another composition's folder; stay in the current file,
122+
or use a LUT reachable by URL or data URL.
88123

89-
Project-wide copy rejects project-relative LUT paths because the same path can
90-
resolve differently from another composition. Use a project-root path, a data
91-
URL, or copy only within the current file.
124+
## Use a LUT only when you know what it expects
92125

93-
## Use LUTs with known intent
126+
A LUT is a lookup table: a file mapping every input color to an output color.
127+
HyperFrames reads a 3D `.cube` file up to 64 points per side and blends it in at
128+
an intensity you set.
94129

95-
Import a project-local 3D `.cube` LUT only when you know the look or conversion
96-
it expects. HyperFrames does not identify camera profiles or apply an automatic
97-
ACES/OCIO workflow.
130+
Nothing normalizes your footage first — HyperFrames does not identify camera
131+
profiles or run an ACES or OCIO pipeline, the color-management systems film
132+
finishing uses. The safe case is a creative Rec.709 LUT, built for ordinary web
133+
and broadcast video, which is also the only color space these controls work in.
134+
LOG footage, shot deliberately flat and grey so it holds detail for grading,
135+
needs the transform its camera expects or comes out wrong rather than stylized.
98136

99-
A creative Rec.709 LUT is the safest normal path. LOG or HDR footage requires a
100-
known source transform.
137+
{/* VISUAL NEEDED (5): one frame under two or three .cube LUTs, plus the same
138+
LUT at partial and full intensity. */}
101139

140+
## Where the grade is stored
102141

103-
## Current limits
142+
Studio and the CLI write the result into `data-color-grading`, in named sections:
143+
corrections under `adjust`, grain and vignette under `details`, stylized
144+
treatments under `effects`.
104145

105-
| Source or workflow | Status |
106-
| --- | --- |
107-
| SDR image or video | Supported |
108-
| 4K SDR media | Supported with higher preview and render cost |
109-
| iPhone HDR, HLG, or Dolby Vision-style media | Studio can show an SDR preview; native HDR delivery is a separate path |
110-
| LOG footage | Requires a known matching transform or LUT |
111-
| Full-scene grade including HTML text | Not supported; grading targets individual media elements |
112-
| Face or region tracking | Not supported |
113-
| Remote media | Requires compatible CORS headers |
114-
| ACES/OCIO finishing | Outside the current browser shader pipeline |
115-
116-
Continue to [Media effects](/guides/media-effects) for blur, bloom, retro,
117-
print, glitch, and art treatments. Use [HDR rendering](/guides/hdr) when the
118-
final delivery must remain HDR.
119-
120-
<Card title="Implement a grade in HTML" icon="code" href="/reference/color-grading">
121-
Persist a grade, animate supported properties, or isolate a graded region.
122-
</Card>
146+
```html
147+
<video src="./interview.mp4" data-color-grading='{"preset":"skin-soft","intensity":0.7,"adjust":{"exposure":0.15},"effects":{"bloom":0.4}}'></video>
148+
```
149+
150+
The nesting is not optional. A flat object such as `{"exposure":0.15}` renders
151+
nothing at all; `npx hyperframes lint` catches it and names the section the
152+
control belongs in.
153+
154+
## What it cannot do
155+
156+
Grading picks pixels by value, never by position: no face tracking, region
157+
tracking, rotoscoping or masks — an HSL selection is a color qualifier, not a
158+
shape. To treat one part of a frame, split it into its own media layer and grade
159+
that layer, as in the [implementation reference](/reference/color-grading). It
160+
targets media elements only, so a whole scene including HTML text cannot be
161+
graded.
162+
163+
SDR images and video are the supported case; 4K works at a higher preview and
164+
render cost. An HDR source — iPhone HDR, HLG, Dolby Vision-style — gets an SDR
165+
preview and a banner saying so: the render may stay HDR-tagged, but this is not
166+
true HDR grading yet. Remote media needs permissive CORS headers and can vanish
167+
before render time, so keep media in the project.
168+
169+
For blur, bloom, retro, print, glitch and art treatments, see
170+
[Media effects](/guides/media-effects).
123171

124172
## Related topics
125173

126174
- [Apply media effects](/guides/media-effects)
127-
- [Use images and video](/guides/video-components)
175+
- [Implement a grade in HTML](/reference/color-grading)
128176
- [Deliver an HDR render](/guides/hdr)

0 commit comments

Comments
 (0)