Puts clip overlay on top of clip base using different blend modes, and with optional x,y positioning, masking and opacity.
- Input clips (base, overlay and mask) are converted to YV24 internally. The output is re-converted to the input colorspace (or to the output colorspace, if specified).
- In general all clips are treated as 0-255 values. This means that numbers will not be clipped at CCIR-601 range; you may use Limiter for this task afterwards. If your mask is 16-235, convert it to 0-255 – for example, with ColorYUV(levels="TV->PC") – or the mask will never be fully opaque.
- It is not recommended to do overlays on interlaced material, unless you know what you are doing.
Syntax and Parameters
Overlay(clip clip, clip overlay [, int x, int y, clip mask, float opacity, string mode,
bool greymask, string output, bool ignore_conditional, bool pc_range ] )
- clip clip = (required)
- This clip will be the base, determining the size and all other video and audio properties of the result, and the overlay picture will be placed on top of this.
- clip overlay = (required)
- This is the image that will be placed on top of the base clip. The colorspace or image dimensions do not have to match the base clip.
- int x, y = 0
- Define the placement of the overlay image on the base clip, in pixels. Can be positive or negative.
- clip mask = (full opacity)
- Optional transparency mask. Must be the same size as overlay. Where mask is darker, overlay will be more transparent. Must be 0-255 range. By default only the greyscale (luma) components are used, but this can be overridden with greymask=false.
- float opacity = 1.0
- Set overlay transparency. The value is from 0.0 to 1.0, where 0.0 is transparent and 1.0 is fully opaque. This value is multiplied by mask luminance to form the final opacity.
- string mode = "blend"
- Defines how your overlay should be blended with your base image.
|Blend||The default mode: ordinary blending in proportion to opacity.|
|Add||Add the overlay video to the base video, making the video brighter. To make this as comparable to RGB, overbright luma areas are influencing chroma and making them more white.[clarification needed]|
|Subtract||The opposite of Add. Make the video darker.|
|Multiply||Darkens the image in proportion to overlay lightness.|
|Chroma||Overlay only the color information of the overlay clip on to the base image.|
|Luma||Overlay only the luminosity information of the overlay clip on to the base image.|
|Lighten||Use overlay only where it is lighter than the base image.|
|Darken||Use overlay only where it is darker than the base image.|
|SoftLight||Lighten or darken the base clip, based on overlay luma. Where overlay luma is darker than 128, the output will be darker. Where overlay luma is lighter than 128, the output will be lighter. This is useful for adding shadows to an image. Pure black or white in the overlay produces a distinctly darker or lighter area, but unlike HardLight, does not result in pure black or white output.|
|HardLight||Lighten or darken the base clip, based on overlay luma. Where overlay luma is darker than 128, the output will be darker. Where overlay luma is lighter than 128, the output will be lighter. Pure black or white in the overlay results in pure black or white in the output.|
|Difference||Display the difference between the clip and the overlay. Note that like Subtract, a difference of zero is displayed as grey, but with luma=128 instead of 126. If you want the pure difference, use mode="Subtract" or add ColorYUV(off_y=-128).|
|Exclusion||Invert the image based on the luminosity of the overlay image. Blending with white inverts the base color values; blending with black produces no change.|
- bool greymask = true
- string output = (input)
- Set output colorspace. Possible values are "YV24", "YUY2", "YV12", "Y8", "RGB32" and "RGB24".
- bool ignore_conditional = false
- bool pc_range = false
- When set to true, this will make all internal RGB→YUV →RGB conversions assume that luma range is 0-255 instead of default 16-235 range. It is only recommended to change this setting if you know what you are doing. See RGB considerations below.
RGB inputs are accepted. However, as Overlay converts internally to YV24, this will lead to an RGB→YUV conversion. There are two modes for this conversion, toggled by the pc_range parameter. This parameter will extend the YUV range from 16-235 (this is the range used by all avisynth converters) to 0-255. There are some cases where enabling pc_range is a good idea:
- When overlaying an RGB clip using the add, subtract or multiply modes, the range of the overlay clip is better, if it is 0-255, since this will enable completely dark areas not to influence the result (instead of adding 16 to every value).
- When NOT doing a colorspace conversion on output. If the output colorspace (RGB vs. YUV) is different from the input, the scale will be wrong. If pc_range=true, and input is RGB, while output is YUY2, the YUY2 will have an invalid range, and not CCIR-601 range.
- It might be a good idea to let Overlay output YV24, even if your input colorspace is RGB, as this avoids a colorspace conversion back to RGB from YUV. You should however be aware that your material might be "overscaled", as mentioned above, if you use pc_range=true. You can correct this by using
ColorYUV(levels="pc->tv")to convert back to 16-235 range.
Inputting RGB for mask clip
- An RGB mask clip may behave a bit oddly if it contains color information. If you use a greyscale mask, or if you leave greymask=true, you will get the result you would expect. Note that mask values are never scaled, so it will automatically be in 0-255 range, directly copied from the RGB values.
Using RGB32 alpha channel
- Overlay ignores the alpha (transparency) channel in an RGB32 clip. If you want the alpha, you can use something like
Overlay(kitten, mask=kitten.ShowAlpha("RGB32")). For maximum quality, it is recommended to extract the alpha as RGB.
Repeated overlays on RGB base clip
- When doing repeated partial overlays on an RGB base clip, the unchanged parts of the base clip will undergo a RGB→YV24→RGB conversion for each call to Overlay, producing a progressive loss of color accuracy. In these situations, it is better to convert the base clip to YV24 before doing the overlays and convert back to RGB afterwards.
The global variables ol_opacity_offset, ol_x_offset and ol_y_offset are evaluated for each frame. The values may be set using FrameEvaluate, or they may be read from a file using ConditionalReader – see example below.
These values, after evaluation, will be added to the relevant filter parameters — for example, if you specify x=100 as a filter parameter, and ol_x_offset=50, the overlay clip will be positioned at x=150. This behaviour can be disabled by using ignore_conditional=true.
There is an example of conditional modification at the ConditionalReader page.
This will take the average of two clips. It can be used for example to combine two captures of different broadcast captures for reducing noise. A discussion of this idea can be found here. A sample script (of course you have to ensure that the frames of the two clips matches exactly, using Trim as needed):
Another use is to detect an altered video using Video Error Level Analysis (VELA), where clip2 is clip1 resaved using an h.263 Codec (e.g. XVID). This method is effective when the suspected altered video (clip1) has not been resaved multiple times. Levels is used to exaggerate contrast for view-ability:
Use a blue (or any other color) background (blue.jpg is a blue frame with subtitles in a black rectangle) as mask. The black rectangle containing the subtitles will be visible on the source clip (which is ColorBars here):
A tolerance of 60 is used here because the blue is not entirely uniform. Near the black rectangles the blue is given by R=23,G=22,B=124 – probably due to the compression artifacts of blue.jpg.
Move a red (or any other color) dot on a clip using ConditionalReader (dot.bmp is a red dot on a black background):
Make xoffset.txt containing the x-positions and yoffset.txt containing the y-positions of the moving dot (see ConditionalReader for more info), and put it in the same folder as your script:
thus the dot moves in the following way: (20,20)→(250,350)→(400,40). It's also possible to do this using script variables in place of text files, with Animate.
Base and overlay colorspaces must match.
- Layer, which supports YUY2 and RGB32 without internal conversion. Supports RGB32 alpha-channel masking.
Base and overlay colorspaces must match.
- uu_mt_blend, which does not support masking, but supports YV12, RGB24 and RGB32 blending without internal conversion.
Base and overlay colorspaces must match. Wide selection of blend modes. Most blend modes work best in RGB.
- Fusion, which uses image pyramids to blend clips together; most often used in the creation of HDR images and image stitching.
- and more – see External Filters: Averaging/Layering/Masking
|v2.6||Added output="Y8", "YV24"; input: "Y8", "YV16" and "YV24".|
|v2.55||mode="Multiply" functionality has changed, so it works as it supposed to do.|