hyperframes/docs/guides/media-overlays.mdx

---
title: Media Overlays
description: "Add editable, timeline-driven HUD, flash, light-leak, and freeze-frame dressing alongside video or image media."
---

Use Media Overlays to add editable, timeline-driven HUD, flash, light-leak, and
freeze-frame dressing around a video or image without baking it into the source
pixels.

## Included Overlays

| Registry block | Purpose |
| --- | --- |
| `camcorder-hud` | Responsive REC indicator, battery, editable date placeholder, and timeline-driven counter |
| `editorial-flash-overlay` | Finite neutral-warm light layers for a camera-flash cut or social reveal |
| `organic-light-leak-overlay` | Finite CSS light leak for memory beats and motivated transitions |
| `freeze-frame-dressing` | Timeline-driven paper, tape, and flash dressing for a freeze frame or background-removed subject |

These are first-party authored blocks. Their Catalog poster/video assets are
previews only; the installed result is editable composition source.

Unlike [Color Grading](/guides/color-grading) and
[Media Effects](/guides/media-effects), overlays are real HTML, CSS, and paused
GSAP timelines installed from the HyperFrames Registry. Their final paint order
follows authored track placement and CSS `z-index`.

## Quick Start

<Tabs>
  <Tab title="Studio">
    <Steps>
      <Step title="Select the media beat">
        Select the `<video>` or `<img>` the overlay should accompany.
      </Step>
      <Step title="Insert an overlay">
        Open **Overlays** in the Design panel and choose a preview card. Studio
        installs the composition source and aligns it to the selected beat.
      </Step>
      <Step title="Edit and verify">
        Use Layers, Timeline, Design, or Code to change content, timing, color,
        animation, or placement, then play through the entrance and exit.
      </Step>
    </Steps>
  </Tab>
  <Tab title="Agent / CLI">
    Discover the available overlay blocks, then install the one that supports
    the intended beat:

    ```bash Terminal
    npx hyperframes media-treatment --capabilities --json
    npx hyperframes add camcorder-hud --no-clipboard
    ```

    The command installs editable composition source under the project. Embed
    and time it with the host composition's normal sub-composition rules.
  </Tab>
</Tabs>

When the selected media has an authored track, Studio starts the overlay on the
next track. Otherwise, normal block placement defaults apply. The left Catalog
remains the browse-all Registry surface; **Overlays** is the selected-media
shortcut.

## Agent Guidance

An agent may combine grading, a shader effect, treatment animation, and an
overlay when they support one coherent intent. A restrained camcorder treatment
can combine a small source correction, tape damage on the media, the
`camcorder-hud` block, and a finite reveal or exit timed to the edit.

Use these constraints:

- Use an overlay when it adds information, motivated light, or useful visual
  language.
- Keep text and HUD fields editable.
- Align finite overlays to a deliberate beat rather than leaving them active
  for the entire video.
- Avoid adding decorative overlays automatically to accuracy-sensitive,
  brand-sensitive, or deliberately clean footage.
- Verify that the overlay does not obscure captions, faces, product UI, or
  essential content.

## Choosing the Right Overlay

### Camcorder HUD

Use for creator-camera, home-video, recording, or found-footage language. The
counter is timeline-driven and the REC behavior is deterministic. Edit the
date/label placeholders instead of rendering arbitrary timestamp text into the
source media.

### Editorial Flash

Use as a short cut accent or social reveal. It is finite by design and should
land on a motivated edit, capture, pose, or beat. It is not a permanent glow or
a replacement for shader Bloom.

### Organic Light Leak

Use sparingly for memory, warmth, film-language transitions, or a motivated
light event. It is a CSS/GSAP overlay rather than a LUT and does not permanently
change source color.

### Freeze-Frame Dressing

Use with a held frame or a subject cutout. The block provides paper, tape, and
flash dressing; it does not perform background removal itself.

For a transparent subject:

```bash Terminal
npx hyperframes remove-background subject.mp4 -o subject.webm
npx hyperframes add freeze-frame-dressing --no-clipboard
```

See [Remove Background](/guides/remove-background) for cutout and background
plate behavior.

## How Overlays Combine with Pixel Treatments

The compositing model is:

```text
source <img>/<video>
  -> color correction and grading
  -> LUT and shader effects
  -> visible media canvas

overlay, caption, and other composition layers
  -> composed with the visible media canvas by authored track and z-index
```

Color grading does not recolor overlay text or graphics. This is intentional:
HUD labels remain crisp and an organic light leak can be adjusted independently
from the source grade. Place captions, HUD fields, and other important graphics
on the intended track and verify their final stacking in Studio.

If an overlay should appear behind a subject, separate the subject into its own
transparent media layer and place the overlay between the background and
foreground layers.

## Editing and Reuse

Registry overlays are copied into the project rather than fetched at render
time. This keeps rendering deterministic and lets teams:

- Change the HTML and CSS.
- Replace labels and colors.
- Retune the paused GSAP timeline.
- Reuse the block across multiple compositions.
- Remove it without changing the media's `data-color-grading` payload.

Keep host-specific timing and placement in the host composition when possible.
That preserves the Registry block as a reusable visual unit.

## Next Steps

<CardGroup cols={2}>
  <Card title="Color Grading" icon="palette" href="/guides/color-grading">
    Correct and grade source media before adding visual dressing.
  </Card>
  <Card title="Media Effects" icon="wand-magic-sparkles" href="/guides/media-effects">
    Apply shader-based optical, retro, print, and art treatments.
  </Card>
  <Card title="Remove Background" icon="scissors" href="/guides/remove-background">
    Create transparent subject layers and paired background plates.
  </Card>
  <Card title="Keyframes" icon="diamond" href="/guides/keyframes">
    Edit deterministic overlay and host animation in Studio.
  </Card>
</CardGroup>