Mask Type
mask
Cuts a still frame to a shape, the same way mask does on images. Outside the shape the still turns transparent on an output with alpha, or takes mask-bg on an opaque one.
Valid values are ellipse, corners, poly3 through poly32, or an image URL.
ellipsefills the frame with an ellipse.cornersrounds the frame’s corners. Usecorner-radiusto control how far.polyNdraws a regular N-sided polygon with a vertex at 3 o’clock, stretched to fill the frame.
Shape names are exact and case-sensitive. Anything else is treated as an image URL, fetched and stretched to the frame, keeping the picture by its luminance multiplied by its alpha. That includes a value such as poly6.png, which is an image rather than a hexagon. A relative URL resolves against the source’s folder, and an image that fails to fetch or decode draws no mask.
mask applies to still frames only. Video, animations and spritesheets draw no mask.
A bitmap mask image is read as sRGB, the same way watermark and blend layer images are. A mask carrying a non-sRGB ICC profile (Adobe RGB, Display P3, Generic RGB) produces an unexpected cut — convert it to sRGB first.
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.
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.
To cut a layer or text out of a frame instead of a shape, see blend-mode.
Examples
Each value below is applied to a PNG still of the same video, shown against the unmasked frame.
mask=ellipse — fills the frame with an ellipse.Default
ellipse
