> ## Documentation Index
> Fetch the complete documentation index at: https://hyperframes-canary-calibration-notes.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Color grade images and footage

> 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.

export const DocsVideo = ({src, poster, title, autoPlay = false, loop = false, portrait = false}) => {
  const videoRef = useRef(null);
  const playerRef = useRef(null);
  const hideTimerRef = useRef(null);
  const progressFrameRef = useRef(null);
  const [enhanced, setEnhanced] = useState(false);
  const [playing, setPlaying] = useState(false);
  const [waiting, setWaiting] = useState(false);
  const [muted, setMuted] = useState(false);
  const [currentTime, setCurrentTime] = useState(0);
  const [duration, setDuration] = useState(0);
  const [playbackRate, setPlaybackRate] = useState(1);
  const [controlsVisible, setControlsVisible] = useState(false);
  const [fullscreen, setFullscreen] = useState(false);
  const [fullscreenSupported, setFullscreenSupported] = useState(false);
  const [previewing, setPreviewing] = useState(false);
  const [scrubbing, setScrubbing] = useState(false);
  const [previewTime, setPreviewTime] = useState(0);
  const [previewPosition, setPreviewPosition] = useState(0);
  const formatTime = seconds => {
    if (!Number.isFinite(seconds) || seconds < 0) return "0:00";
    const minutes = Math.floor(seconds / 60);
    const remaining = Math.floor(seconds % 60);
    return `${minutes}:${String(remaining).padStart(2, "0")}`;
  };
  const clearHideTimer = () => {
    if (hideTimerRef.current) {
      window.clearTimeout(hideTimerRef.current);
      hideTimerRef.current = null;
    }
  };
  const revealControls = () => {
    setControlsVisible(true);
    clearHideTimer();
    hideTimerRef.current = window.setTimeout(() => setControlsVisible(false), 2200);
  };
  const togglePlayback = async () => {
    const video = videoRef.current;
    if (!video) return;
    if (video.paused || video.ended) {
      if (video.ended) video.currentTime = 0;
      setWaiting(true);
      try {
        await video.play();
      } catch {
        setWaiting(false);
        setPlaying(false);
      }
    } else {
      video.pause();
      setControlsVisible(true);
    }
  };
  const toggleMute = () => {
    const video = videoRef.current;
    if (!video) return;
    if (video.muted && video.volume === 0) video.volume = 0.8;
    video.muted = !video.muted;
    setMuted(video.muted);
  };
  const seek = event => {
    const video = videoRef.current;
    if (!video) return;
    const nextTime = Number(event.target.value);
    video.currentTime = nextTime;
    setCurrentTime(nextTime);
  };
  const updateScrubPreview = (event, seekMainVideo = false) => {
    if (!duration) return;
    const rect = event.currentTarget.getBoundingClientRect();
    const ratio = Math.min(1, Math.max(0, (event.clientX - rect.left) / rect.width));
    const nextTime = ratio * duration;
    setPreviewing(true);
    setPreviewTime(nextTime);
    setPreviewPosition(ratio * 100);
    if (seekMainVideo) {
      const video = videoRef.current;
      if (video) {
        video.currentTime = nextTime;
        setCurrentTime(nextTime);
      }
    }
  };
  const cyclePlaybackRate = () => {
    const video = videoRef.current;
    if (!video) return;
    const rates = [1, 1.25, 1.5, 2];
    const currentIndex = rates.indexOf(video.playbackRate);
    const nextRate = rates[(currentIndex + 1) % rates.length];
    video.playbackRate = nextRate;
    setPlaybackRate(nextRate);
  };
  const toggleFullscreen = async () => {
    const player = playerRef.current;
    const video = videoRef.current;
    if (!player || typeof document === "undefined") return;
    try {
      if (document.fullscreenElement) {
        await document.exitFullscreen();
      } else if (player.requestFullscreen) {
        await player.requestFullscreen();
      } else if (video?.webkitEnterFullscreen) {
        video.webkitEnterFullscreen();
      }
    } catch {}
  };
  const handleKeyboard = event => {
    if (event.target !== event.currentTarget) return;
    const video = videoRef.current;
    if (!video) return;
    if (event.key === " " || event.key === "Enter") {
      event.preventDefault();
      togglePlayback();
    } else if (event.key === "ArrowLeft") {
      event.preventDefault();
      video.currentTime = Math.max(0, video.currentTime - 5);
    } else if (event.key === "ArrowRight") {
      event.preventDefault();
      video.currentTime = Math.min(duration || video.duration || 0, video.currentTime + 5);
    } else if (event.key.toLowerCase() === "m") {
      event.preventDefault();
      toggleMute();
    } else if (event.key.toLowerCase() === "f") {
      event.preventDefault();
      toggleFullscreen();
    }
  };
  useEffect(() => {
    setEnhanced(true);
    setFullscreenSupported(Boolean(playerRef.current?.requestFullscreen || videoRef.current?.webkitEnterFullscreen));
    return () => {
      clearHideTimer();
    };
  }, []);
  useEffect(() => {
    if (typeof document === "undefined") return undefined;
    const syncFullscreen = () => setFullscreen(document.fullscreenElement === playerRef.current);
    document.addEventListener("fullscreenchange", syncFullscreen);
    return () => document.removeEventListener("fullscreenchange", syncFullscreen);
  }, []);
  useEffect(() => {
    clearHideTimer();
    if (!playing) return undefined;
    hideTimerRef.current = window.setTimeout(() => setControlsVisible(false), 2200);
    return clearHideTimer;
  }, [playing]);
  useEffect(() => {
    if (!playing) return undefined;
    const updateProgress = () => {
      const video = videoRef.current;
      if (video && !video.paused) setCurrentTime(video.currentTime);
      progressFrameRef.current = window.requestAnimationFrame(updateProgress);
    };
    progressFrameRef.current = window.requestAnimationFrame(updateProgress);
    return () => {
      if (progressFrameRef.current) window.cancelAnimationFrame(progressFrameRef.current);
      progressFrameRef.current = null;
    };
  }, [playing]);
  const progress = duration > 0 ? currentTime / duration * 100 : 0;
  const replaying = duration > 0 && currentTime >= duration - 0.15;
  return <div className="hf-docs-video-block" data-portrait={portrait ? "true" : "false"}>
      <div ref={playerRef} className="hf-docs-video" role="region" aria-label={title} tabIndex={0} onKeyDown={handleKeyboard} onPointerMove={revealControls} onPointerLeave={() => setControlsVisible(false)} onFocus={revealControls} onBlur={event => {
    if (!event.currentTarget.contains(event.relatedTarget)) setControlsVisible(false);
  }}>
        <video ref={videoRef} aria-label={title} src={src} poster={poster} autoPlay={autoPlay} loop={loop} playsInline preload="metadata" controls={!enhanced} onClick={togglePlayback} onDoubleClick={toggleFullscreen} onLoadedMetadata={event => {
    const nextDuration = event.currentTarget.duration || 0;
    setDuration(nextDuration);
    setMuted(event.currentTarget.muted);
  }} onDurationChange={event => setDuration(event.currentTarget.duration || 0)} onTimeUpdate={event => setCurrentTime(event.currentTarget.currentTime)} onPlay={() => setPlaying(true)} onPause={() => setPlaying(false)} onPlaying={() => setWaiting(false)} onWaiting={() => setWaiting(true)} onCanPlay={() => setWaiting(false)} onEnded={() => {
    setPlaying(false);
    setControlsVisible(true);
  }} onVolumeChange={event => setMuted(event.currentTarget.muted)} />

        {enhanced && <>
            {!playing && (currentTime <= 0.2 || replaying) && <button type="button" className="hf-docs-video-hero-play" onClick={togglePlayback} aria-label={replaying ? "Replay video" : "Play video"}>
                <span className="hf-docs-video-hero-icon" aria-hidden="true">
                  <svg viewBox="0 0 24 24">
                    <path d="M8 5.5v13l10-6.5z" />
                  </svg>
                </span>
              </button>}

            {waiting && playing && <span className="hf-docs-video-spinner" aria-label="Loading" />}

            <div className="hf-docs-video-controls" data-visible={controlsVisible ? "true" : "false"}>
              <div className="hf-docs-video-scrub-preview" data-visible={previewing ? "true" : "false"} style={{
    "--hf-video-preview-x": `${previewPosition}%`
  }} aria-hidden="true">
                <span>{formatTime(previewTime)}</span>
              </div>

              <input className="hf-docs-video-progress" type="range" min="0" max={duration || 0} step="0.01" value={Math.min(currentTime, duration || 0)} aria-label="Video progress" aria-valuetext={`${formatTime(currentTime)} of ${formatTime(duration)}`} onChange={seek} onPointerEnter={updateScrubPreview} onPointerMove={event => updateScrubPreview(event, scrubbing || event.buttons === 1)} onPointerDown={event => {
    setScrubbing(true);
    event.currentTarget.setPointerCapture?.(event.pointerId);
    updateScrubPreview(event, true);
  }} onPointerUp={event => {
    setScrubbing(false);
    if (event.pointerType !== "mouse") setPreviewing(false);
  }} onPointerCancel={() => {
    setScrubbing(false);
    setPreviewing(false);
  }} onPointerLeave={() => {
    if (!scrubbing) setPreviewing(false);
  }} style={{
    "--hf-video-progress": `${progress}%`
  }} />

              <div className="hf-docs-video-control-row">
                <button type="button" className="hf-docs-video-control" onClick={togglePlayback} aria-label={playing ? "Pause video" : "Play video"}>
                  {playing ? <svg viewBox="0 0 24 24" aria-hidden="true">
                      <path d="M7 5h4v14H7zm6 0h4v14h-4z" />
                    </svg> : <svg viewBox="0 0 24 24" aria-hidden="true">
                      <path d="M8 5.5v13l10-6.5z" />
                    </svg>}
                </button>

                <button type="button" className="hf-docs-video-control" onClick={toggleMute} aria-label={muted ? "Unmute video" : "Mute video"}>
                  {muted ? <svg viewBox="0 0 24 24" aria-hidden="true">
                      <path d="M4 9v6h4l5 4V5L8 9zm11.5 1.1 1.4-1.4 1.6 1.6 1.6-1.6 1.4 1.4-1.6 1.6 1.6 1.6-1.4 1.4-1.6-1.6-1.6 1.6-1.4-1.4 1.6-1.6z" />
                    </svg> : <svg viewBox="0 0 24 24" aria-hidden="true">
                      <path d="M4 9v6h4l5 4V5L8 9zm11 1.2v3.6c1-.5 1.7-1.5 1.7-2.8S16 10.7 15 10.2zm0-4v2.1c2.2.6 3.7 2.5 3.7 4.7s-1.5 4.1-3.7 4.7v2.1c3.3-.7 5.7-3.5 5.7-6.8S18.3 6.9 15 6.2z" />
                    </svg>}
                </button>

                <span className="hf-docs-video-time" aria-hidden="true">
                  {formatTime(currentTime)} <span>/</span> {formatTime(duration)}
                </span>

                <span className="hf-docs-video-spacer" />

                <button type="button" className="hf-docs-video-rate" onClick={cyclePlaybackRate} aria-label={`Playback speed ${playbackRate} times`}>
                  {playbackRate}×
                </button>

                {fullscreenSupported && <button type="button" className="hf-docs-video-control" onClick={toggleFullscreen} aria-label={fullscreen ? "Exit fullscreen" : "Enter fullscreen"}>
                    {fullscreen ? <svg viewBox="0 0 24 24" aria-hidden="true">
                        <path d="M8 3H6v3H3v2h5zm8 0v5h5V6h-3V3zM3 16v2h3v3h2v-5zm13 0v5h2v-3h3v-2z" />
                      </svg> : <svg viewBox="0 0 24 24" aria-hidden="true">
                        <path d="M3 8h2V5h3V3H3zm13-5v2h3v3h2V3zM5 16H3v5h5v-2H5zm14 3h-3v2h5v-5h-2z" />
                      </svg>}
                  </button>}
              </div>
            </div>
          </>}
      </div>

    </div>;
};

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.

<Frame caption="The same source before and after a restrained natural-portrait grade.">
  <img src="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/color-grading-before-after-v1.png" alt="The same presenter frame before and after a restrained natural portrait grade" />
</Frame>

<DocsVideo title="Correction, presets, curves, selective colour, scopes and a LUT on real footage" src="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/color-grading-demo-v1.mp4" poster="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/color-grading-demo-v1.jpg" />

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.

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                                               |

## 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.

## Compare candidate looks in one image

Instead of flipping between options, render them all onto one reference frame:

```bash theme={null}
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.

## Or describe the problem to the agent

You do not need to name controls or invent values:

```text theme={null}
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 theme={null}
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.

## 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 theme={null}
<video src="./interview.mp4" data-color-grading='{"preset":"skin-soft","intensity":0.7,"adjust":{"exposure":0.15},"effects":{"bloom":0.4}}'></video>
```

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 media elements only, so a whole scene including HTML text cannot be
graded.

SDR images and video are the supported case; 4K works at a higher preview and
render cost. An HDR source — iPhone HDR, HLG, Dolby Vision-style — gets an SDR
preview and a banner saying so: the render may stay HDR-tagged, but this is not
true HDR grading yet. Remote media needs permissive CORS headers and can vanish
before render time, so keep media in the project.

For blur, bloom, retro, print, glitch and art treatments, see
[Media effects](/guides/media-effects).

## Related topics

* [Apply media effects](/guides/media-effects)
* [Implement a grade in HTML](/reference/color-grading)
* [Deliver an HDR render](/guides/hdr)