Overlay

Mode	Example	Description
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

Specifies whether chroma should be used for chroma transparency. Generally you want to leave this alone. External filters like mSharpen and Masktools are able to export proper chroma maps.

string  output = (input)

Set output colorspace. Possible values are "YV24", "YUY2", "YV12", "Y8", "RGB32" and "RGB24".

AVS+ All 8-16 bits colorspaces e.g. "YUV420P14" and "RGB64"

bool  ignore_conditional = false

Ignore any given conditional (runtime) variables. See the Conditional Variables section for more information.

bool  pc_range = false

When set to true, this will make all internal RGB→YUV →RGB conversions assume that YUV sources are full-range instead of the default TV range. It is only recommended to change this setting if you know what you are doing. See RGB considerations below.

bool  use444 = true

AVS+ If set to false, Overlay uses conversionless mode where possible instead of going through YUV 4:4:4. However, for Luma and Chroma modes, RGB must be converted to YUV 4:4:4.

default value is adaptive:

false when mode="blend" and format is RGB

false when mode="blend", "luma" or "chroma and format is YUV420/YUV422 (YV12/YV16). Original format is kept throughout the whole process, no 4:4:4 conversion occurs.

true for all other cases (input is converted internally to 4:4:4)

RGB inputs are accepted. However, as Overlay converts internally to YV24 (see AVS+ exceptions), 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.
• AVS+ planar RGB formats are also supported besides 8 bit packed RGB formats and RGB48/RGB64.
• AVS+ "blend" mode keeps original RGB format, no YUV intermediate conversion is used.

[edit] Outputting RGB

It might be a good idea to let Overlay output YV24 (or YUV444P10-16 in AVS+), 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 (or equivalent ranges to 10+ bits).

[edit] 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 full-range, directly copied from the RGB values.

[edit] Using RGB32, AVS+ RGB64 or planar RGBA 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.

[edit] 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 4:4:4 format (e.g. 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.

# Prepares some sources.
bg = ColorBars(512,384).ConvertToYUY2
text = BlankClip(bg).Subtitle("Colorbars", size=92, 
\          text_color=$ffffff).ColorYUV(levels="tv->pc")

# Overlay the text in three different versions.
return Overlay(bg, text, x=50, y=20, mode="subtract", opacity=0.25)
return Overlay(text, x=50, y=120, mode="add", opacity=0.5)
return Overlay(text, x=50, y=240, mode="blend", opacity=0.7)

# Overlay yuy2 clip with rgb clip using a yuy2 mask
# (note that the luma range of the mask is [0-255]). 
return Overlay(yuy2clip, rgbclip, mask=rgbclip.ShowAlpha("yuy2"))

# ...which is the same as 
mask = rgbclip.ShowAlpha("rgb").ConvertToYUY2
\             .ColorYUV(levels="TV->PC")
return Overlay(yuy2clip, rgbclip, mask=mask)

# ...which is the same as 
mask = rgbclip.ShowAlpha("rgb")
return Overlay(yuy2clip, rgbclip, mask=mask)

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):

clip1 = AviSource("F:\shakira-underneath_your_clothes.avi")
clip2 = AviSource("F:\shakira-underneath_your_clothes2.avi")
Overlay(clip1, clip2, mode="blend", opacity=0.5)

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:

clip1 = AviSource("SuspectVideo.avi")
clip2 = AviSource("SuspectVideo_resaved.avi")
result= Overlay(clip1,clip2,mode="Subtract").Levels(0, 5.0, 100, 0, 255)

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):

testcard = ColorBars

# get a blue mask clip (the same blue as in ColorBars is used: R16 G16 B180)
maskclip = BlankClip(testcard, color=$0f0fb4)

# Example subtitle file with blue backgroud as above
subs = ImageSource("F:\TestClips\blue.jpg").ConvertToRGB32

maskclip = ColorKeyMask(subs, $0f0fb4, 60)

Overlay(testcard, subs, mask=maskclip.ShowAlpha, mode="blend", opacity=1)

maskclip	overlay

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):

a1 = ColorBars.Trim(0,399)
a2 = ImageSource("F:\TestClips\dot.bmp").ConvertToRGB32

# a2.Greyscale returns a grey dot on a black background;
# Levels makes the dot white
mask_clip = Mask(a2, a2.GreyScale.Levels(0, 1.0, 75, 0, 255))
Overlay(a1, a2, mask=ShowAlpha(mask_clip), y=0, x=0,
\                              mode="blend", opacity=1)

ConditionalReader("xoffset.txt", "ol_x_offset", false)
ConditionalReader("yoffset.txt", "ol_y_offset", false)

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:

xoffset.txt:

Type int
Default -50

R 0 100 20
I 100 200 20 250
R 200 300 250
I 300 400 250 400

yoffset.txt:

Type int
Default -50
 
R 0 100 20
I 100 200 20 350
R 200 300 350
I 300 400 350 40

The figures:

dot.bmp over black	dot.bmp over color bars

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.

• Merge, MergeChroma and MergeLuma – simple blending in any colorspace.

• Layer, which supports YUY2 and RGB32 without internal conversion. Supports RGB32 alpha-channel masking.

• uu_mt_blend, which does not support masking, but supports YV12, RGB24 and RGB32 blending without internal conversion.

• 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