Mask Image
Activating Imgix Video
Set fm to a video output format — mp4, hls, or dash — for Imgix Video parameters to take effect.
mask cuts a still frame to a shape, the same way it does on images. Outside the shape the still turns transparent on an output with alpha, or takes mask-bg on an opaque one. This covers the common cases — a circular avatar from a video frame, a rounded-corner poster, or a custom shape from an image mask.
?fm=png&mask=ellipse # a circular still
?fm=png&mask=corners&corner-radius=40 # rounded corners
?fm=png&mask=poly6 # a hexagon
?fm=png&mask=shape.png # a custom image maskMasks apply to still frames only
Video, animations and spritesheets draw no mask. Request a still output — fm=png, jpg, webp, avif, jxl, or a thumbnail — for mask to take effect.
Choosing an output format
A mask only produces transparency on an output that supports alpha, such as png, webp, avif or jxl. On an opaque output like jpg, the area outside the mask is filled with mask-bg, defaulting to white.
auto=compress keeps a masked still opaque
With auto=compress and no explicit fm, a masked still stays a JPEG on mask-bg rather than switching to PNG to preserve transparency — which is what the Rendering API does for an image. Set fm explicitly when you need the transparency.
Where it composites
The mask covers the whole still, including fit=fill bars. It is applied after the gradient and fade and before watermarks and text, so marks and text are never clipped by it. A text cut (txt-blend-mode) cuts the masked frame.
dpr scales pixel radii and the feather. The waveform and the progress bar draw over the masked area.
Feathering the edge
With mask=ellipse or mask=corners, a bare fade feathers the mask’s edge inward rather than fading the frame’s edges. The feather goes no deeper than half the shorter side, and a value under 1 pixel is a hard edge. The side-specific fade parameters still fade the frame’s edges as usual. On video output a bare fade belongs to the mask and draws nothing, so use the side-specific parameters (fade-left, fade-right, fade-top, fade-bottom) there instead.
Examples
Each example renders a still of the same video. Pick a shape to see it against the unmasked frame.
mask=ellipse — fills the frame with an ellipse. Square the frame with w, h and fit=crop for a circular avatar.Default
ellipse
Related
To cut a layer, a color or text out of the frame rather than a geometric shape, use the cut blend modes — see blend-mode.