Blending

Activating Imgix Video

Set fm to a video output format — mp4, hls, or dash — for Imgix Video parameters to take effect.

blend puts a color or an image over the picture, composited in one of the CSS blend modes, or cuts the picture with it. It works the same way it does on images, so one URL produces the same result on a video source and on an image.

?fm=mp4&blend=80000000&blend-mode=normal           # a 50% black scrim over the whole frame
?fm=mp4&blend=8000ff&blend-mode=multiply           # a brand-color tint
?fm=mp4&blend=logo.png&blend-w=0.3&blend-align=bottom,right

Stacking layers

Up to four layers stack: blend (or blend[0]) at the bottom, then blend[1] through blend[3]. Every parameter in the family takes the same [N] suffix, and each also has a base64 twin such as blend64. A layer is drawn once it has a color or an image.

?fm=mp4&blend=80000000&blend[1]=logo.png&blend-w[1]=0.2&blend-align[1]=top,right

A blend layer has no timeline. The same layer is drawn on every frame, and a GIF or video supplied as blend= draws only its first frame.

Where layers draw

Output	Blend modes	Cuts (`destination-out` / `-in`)
A still from a video (an image `fm` such as `jpg`, `png`, `webp`, `avif` or `jxl`, optionally with `video-thumbnail` to pick the frame)	Yes	Yes
An audiogram’s still	Yes	Yes
An animation (`gif`, `awebp`, `aavif`, `apng`, animated `jxl`)	Yes	No
MP4, WebM, and an audiogram’s video	Yes	No
HLS and DASH, every rendition	Yes	No
Assembled clips (`video-assembly`) and previews	As the output they produce	As the output they produce
Spritesheets and storyboards	No	No

A cut needs a picture that can be transparent, and only stills can — video and animations are opaque. A cut on them draws nothing. To cut a shape out of a video frame rather than a layer, render a still and use mask instead.

Layer order

A blend layer sits on the sized picture, underneath everything else: gradient, fade, mask, image watermarks, text, the waveform, the progress bar and picture-in-picture all draw over it. A blend-color multiply tints the picture, not a logo placed over it.

On video, Imgix Video’s own grade — video-eq, LUTs, video-blur, video-sharpen and video-vfx — runs before the blend layer.

Gradients and fades on a layer

A blend layer can carry its own gradient or edge fade, applied to the layer image before the layer’s warps. These use the same grammar as gradient and fade, prefixed with blend-:

blend-gradient, and the modifiers blend-gradient-type, blend-gradient-angle, blend-gradient-stops, blend-gradient-cs, blend-gradient-hue, blend-gradient-alpha, blend-gradient-mode, blend-gradient-mask, and the radial forms blend-gradient-radial-shape, blend-gradient-radial-size, blend-gradient-radial-x, blend-gradient-radial-y.
blend-fade, and the side forms blend-fade-top, blend-fade-bottom, blend-fade-left, blend-fade-right.

Each takes the same [N] layer suffix as the rest of the family.

A layer’s gradient and fade always go to transparent; they never take bg.

Orientation and sizing

A layer image is drawn upright, as browsers show it. EXIF Orientation is honored for JPEG, PNG, WebP and TIFF, mirrored values included, while XMP and IPTC orientation are ignored. HEIC and AVIF follow their container rotation and mirror, falling back to their EXIF Orientation.

The layer mirrors along with the picture when the picture is flipped — marks, text and the gradient do not.

Streaming and fill

On HLS and DASH, the layer is drawn once in the base pass, before the ladder splits, so every rendition carries it scaled with the picture. Pixel lengths are the top rendition’s pixels, which means a pixel size looks smaller on lower renditions. Use fractional sizes to keep a layer proportional across the ladder.

With fit=fill, a still’s layer covers the whole canvas including the fill. On video the layer covers the picture alone and the fill around it is left untouched, the same way the video gradient behaves. blend-align, blend-x, blend-y and fractional sizes all measure against the picture.

Troubleshooting

Symptom	Likely cause	Fix
No layer appears	The image did not fetch or decode, `blend-mode` matched nothing, or the output is a spritesheet	Check the `X-Imgix-Video-Operations` response header: it lists `blend` when a layer is actually drawn. Then check the URL and the spelling of the mode
A cut does nothing on video	Cuts draw on stills only	Render a still, or use `mask`
`b=` with a URL draws nothing	`b` is a color-only alias	Spell it `blend=`
A layer image looks wrong in color	It carries a non-sRGB ICC profile (Adobe RGB, Display P3, Generic RGB), which is read as sRGB	Convert the image to sRGB
A pixel size looks smaller on low HLS renditions	Lengths are the top rendition’s pixels	Use fractional sizes

Waveform Y Position Blend Layer