masked_merge

masked_merge(
  input: [Clip, Clip, Clip],
  #{
    planes?: Array<Int>,
  }
)

Merges two clips using per-pixel weights from a third mask clip. A mask value of 0 keeps the first clip sample, and a full-scale mask value keeps the second clip sample.

Use array input form: std.masked_merge([first, second, mask], #{ ... }). The first and second clips must have the same fixed planar Gray, YUV, or planar RGB format, fixed resolution, frame count, and frame rate. The output keeps the first clip’s format, resolution, timing, and metadata.

The mask clip must have the same fixed resolution, frame count, and frame rate as the first clip. Its format must either match the input clips or be the matching Gray format with the same bit depth. Integer mask clips use full-range code values regardless of color range metadata. Float mask clips use 0.0 to 1.0 weights and are not clamped during rendering.

If the mask is Gray, its single plane is reused for every processed output plane. For subsampled chroma planes, the corresponding full-resolution Gray mask samples are averaged before merging.

If planes is omitted, every plane is processed. If planes is provided, only the listed zero-based plane indexes are processed; all other planes are copied from the first clip.

Examples

first = source("clean.mkv")
second = source("effect.mkv")
mask = source("mask.mkv").std.convert_format(#{ format: "gray8" })
output = std.masked_merge([first, second, mask])

first = source("base.mkv")
second = source("overlay.mkv")
mask = source("luma-mask.mkv").std.convert_format(#{ format: "gray8" })
output = std.masked_merge([first, second, mask], #{ planes: [0] })

Input

Three fixed-format planar clips: first input, second input, and mask.

Output

A clip with the same format, resolution, timing, and metadata as the first input, with selected planes merged using mask weights.

Options

• planes (Array<Int>, default: all planes) – Zero-based plane indexes to process. Unlisted planes are copied from the first clip.