Media Effects

Use Media Effects to transform real <video> and <img> pixels with deterministic blur, retro, print, and art treatments that can share one payload with Color Grading.

Effect Families

Essentials

Effect	What it does
Blur	Defocuses or softens the complete media layer
Pixelate	Converts the layer into a block mosaic
Bloom	Adds thresholded glow around bright regions

Retro & Glitch

Effect	What it does
Chroma Softening	Smears chroma while retaining central luma
Tape Damage	Adds deterministic tracking errors, noise, ghosting, and dropouts
Film Artifacts	Adds deterministic dust and short scratches
Scanlines	Adds configurable horizontal display lines
CRT Curvature	Warps media toward curved display geometry
Channel Separation	Offsets color channels along an angle
Digital Glitch	Combines line tears, blocks, displacement, pixelation, and channel split

When authoring JSON directly, Chroma Softening uses chromaBleed and Channel Separation uses chromaticAberration. Query the capability command for the canonical payload keys of all other controls.

Print

Effect	What it does
Halftone	Renders source color through a print-dot raster
Two-Ink Print	Reduces media to the built-in two-ink treatment
Ordered Dither	Quantizes media into an ordered limited palette
Mono Screen	Builds monochrome dot, shape, or line artwork

Art

Effect	What it does
ASCII	Renders media as configurable procedural glyph cells
Engraving	Translates luminance into directional engraved lines
Crosshatch	Translates media into layered hand-hatched lines
Kuwahara Paint	Applies edge-preserving painterly smoothing

Quick Start

Studio
Agent / CLI

Select real media

Select a real <img> or <video> in the preview, Layers panel, or Timeline. Effects do not appear for arbitrary divs or CSS background images.

Choose and tune an effect

Preview an effect preset or open Effects. Enabling an effect uses a calibrated default; expand it to adjust only the controls relevant to the intended result.

Verify motion and framing

Play and scrub videos at the beginning, middle, and end. Confirm that moving effects and object-fit/object-position framing remain correct.

Discover the narrow effect contract, then apply the complete treatment in one mutation:

Terminal

npx hyperframes media-treatment --capabilities --json
npx hyperframes media-treatment --capability digitalGlitch --json

npx hyperframes media-treatment \
  --project . \
  --file compositions/scene.html \
  --selector '#hero' \
  --grading '{"effects":{"digitalGlitch":0.55,"digitalGlitchColorSplit":0.25,"digitalGlitchLineTear":0.25,"digitalGlitchPixelate":0.15,"digitalGlitchBlockAmount":0.5,"digitalGlitchBlockDisplacement":0.25,"digitalGlitchSpeed":0.5}}' \
  --apply \
  --json

Project-local media is recommended; remote media requires compatible CORS. Media Overlays are separate editable composition layers rather than shader properties.

Media Effects use the SDR/Rec.709 shader pipeline. Studio can preview that pipeline on browser-decoded HDR media, but native HDR rendering preserves the HDR source separately and does not apply these SDR effects to native HDR layers. Convert or tone-map to SDR when an effect must appear in the final output. See Color Grading support and HDR Rendering.

Effect Presets

Creator Camcorder, VHS Playback, 8mm Home Movie, Editorial Halftone, and Two-Ink Print provide tested combinations of effect, correction, and finishing settings. Preview one as a starting point, then tune the underlying controls. They are normal shader payloads, not baked media or bundled LUTs.

Agent Guidance

Agents should discover only the part of the toolbox relevant to the user’s intent: The user may simply ask for “an old home-video feel”, “a useful privacy reveal”, or “something more graphic for this poster.” The media-use skill classifies that intent, then queries the narrow effect or recipe details instead of loading the exhaustive contract.

Terminal

npx hyperframes media-treatment --capabilities --json
npx hyperframes media-treatment --capability retro-glitch --json
npx hyperframes media-treatment --capability digitalGlitch --json

The concise overview lists capability families. A focused query returns the effect’s calibrated apply payload, controls, render lane, palette support, and seek-safe animation path. Use the canonical payload instead of guessing sub-control defaults. Recipes are tested shortcuts, not a closed list. An agent may assemble a custom payload when the source and intent justify it, but it should:

Choose one primary visual intent.
Query the exact effect or family contract.
Add only controls that visibly support that intent.
Avoid stacking several dominant stylizations without a reason.
Verify representative frames and a short render.

Palettes

palette accepts two to six exact #RRGGBB colors in authored order. Dark-to-light order creates normal luminance mapping; reversing the array intentionally inverts that mapping.

data-color-grading

{
  "effects": {
    "dither": 1,
    "ditherSize": 0.5
  },
  "palette": ["#080717", "#3c185f", "#d9339f", "#ff6b66", "#aafae0"]
}

Compatible effects are ASCII, Ordered Dither, Mono Screen, Engraving, and Crosshatch. A palette alone does not activate an effect. Discover built-in palettes without copying their values into instructions:

Terminal

npx hyperframes media-treatment --capability palettes --json
npx hyperframes media-treatment --capability electric-ink --json

Animation and Keyframes

The following paths have seek-safe CSS custom properties and may be animated by a paused, registered GSAP timeline:

Global treatment intensity
LUT intensity
Exposure
Blur
Bloom
Kuwahara Paint
Pixelate
ASCII
Ordered Dither

Example blur-to-focus reveal:

index.html

<div
  class="clip"
  data-composition-id="media-effect-demo"
  data-start="0"
  data-duration="4"
>
  <video
    id="hero"
    src="assets/hero.mp4"
    muted
    playsinline
    style="--hf-color-grading-blur: 0.8"
    data-color-grading='{"effects":{"blur":0.8}}'
  ></video>
</div>

<script>
  const tl = gsap.timeline({ paused: true });
  tl.to(
    "#hero",
    {
      "--hf-color-grading-blur": 0,
      duration: 1.2,
      ease: "power2.out",
    },
    0,
  );
  window.__timelines = window.__timelines || {};
  window.__timelines["media-effect-demo"] = tl;
</script>

Author the initial custom-property value inline. Do not use timers, unseeded randomness, frame-zero set() calls, or onUpdate callbacks. Query an effect’s focused capability to get its exact animation property and range. Tape damage, digital glitch, film artifacts, and similar effects may contain deterministic internal motion even when their overall strength is not one of the keyframeable paths above.

Important Effect Behavior

Tape Damage is the primary analog-tape amount. Tracking controls moving tears, Noise controls row jitter/noise, and Speed controls their deterministic motion. Those subordinate controls do not activate tape damage by themselves.
Film Artifacts adds sparse deterministic dust and scratches. Grain, vignette, color, and optional wrapper motion such as a subtle gate weave are separate choices.
Halftone uses fixed print-oriented channel angles and edge behavior. Cell size remains adjustable.
Two-Ink Print is HyperFrames’ own fixed two-ink mapping. Do not describe it as a named commercial print process or stack it with Halftone by default.
ASCII uses procedural glyph cells. Size, style, ink behavior, rotation, and a compatible palette remain configurable.
Ordered Dither uses a temporally stable 4x4 Bayer matrix. It is not Floyd-Steinberg or another sequential error-diffusion algorithm.
Bloom extracts bright regions before blurring them; it is different from raising highlights or whites.
Kuwahara Paint smooths regions while preserving major edges. Radius, sharpness, and saturation shape the result.

Deterministic Pipeline Order

HyperFrames evaluates combined treatment stages in one fixed order:

Source framing and multipass Blur/Kuwahara preparation
Chromatic and digital-glitch transforms
Primary correction, color grading, and LUT blended by global intensity
Grain and film artifacts
Mono, engraving, crosshatch, halftone, two-ink, dither, and ASCII
Bloom, scanlines, vignette, and CRT display masking
Before/after comparison

The order cannot currently be rearranged. A fixed order keeps Studio, playback, seeking, and final rendering deterministic and prevents agents from inventing incompatible effect graphs.

Performance

Performance follows the number of treated pixels and the selected render lane, not only the number of elements.

Blur, Bloom, and Kuwahara use multipass rendering.
Several tiled media elements can be cheaper than several overlapping full-frame elements.
When more than two full-frame multipass-treated elements are visible together, verify continuous playback on the target machine.
Simplify or pre-render a stack when preview frames drop.
Kuwahara uses bounded half-float intermediate targets when supported and otherwise reports itself unavailable.

For 4K delivery, verify the effect at the final composition size. Resolution- aware effects preserve their intended scale, but 4K still processes more pixels than 1080p.

Low-Level HTML Contract

Media effects live in the same persisted contract as grading:

index.html

<img
  id="poster"
  src="assets/poster.jpg"
  data-color-grading='{
    "effects":{
      "ascii":1,
      "asciiSize":0.066,
      "asciiStyle":0,
      "asciiColor":1,
      "asciiRotation":0
    },
    "palette":["#001100","#00ff00"],
    "colorSpace":"rec709"
  }'
/>

Unknown keys are rejected and values are normalized by the Core contract. The CLI should remain the primary authoring surface for agents.

Next Steps

Color Grading

Correct and grade media with scopes, wheels, curves, selections, and LUTs.

Media Overlays

Add authored HUD, flash, light-leak, and freeze-frame layers.

Keyframes

Edit and verify deterministic GSAP animation in Studio.

Performance

Diagnose source resolution, browser, decoder, and composition cost.

Getting Started

Concepts

Guides

Deploy

Effect Families

Essentials

Retro & Glitch

Print

Art

Quick Start

Effect Presets

Agent Guidance

Palettes

Animation and Keyframes

Important Effect Behavior

Deterministic Pipeline Order

Performance

Low-Level HTML Contract

Next Steps

Color Grading

Media Overlays

Keyframes

Performance

​Effect Families

​Essentials

​Retro & Glitch

​Print

​Art

​Quick Start

​Effect Presets

​Agent Guidance

​Palettes

​Animation and Keyframes

​Important Effect Behavior

​Deterministic Pipeline Order

​Performance

​Low-Level HTML Contract

​Next Steps

Color Grading

Media Overlays

Keyframes

Performance

Effect Families

Essentials

Retro & Glitch

Print

Art

Quick Start

Effect Presets

Agent Guidance

Palettes

Animation and Keyframes

Important Effect Behavior

Deterministic Pipeline Order

Performance

Low-Level HTML Contract

Next Steps