FFmpeg maskedmerge: align both pictures and the mask

Identify all three resources and their intended relationship

Keep the authorized base, alternate picture and mask independently. Record which source should remain where the mask is dark and which should appear where it is bright. Under the native filter definition, a zero component selects the first picture and the maximum component selects the second; intermediate values blend them. Reversing the two picture inputs changes that meaning.

Check actual dimensions, pixel representation and the mask’s origin. A matte made for a cropped or stabilized derivative may not fit the original recording. Matching filenames or dimensions alone does not establish spatial registration. Compare meaningful edges throughout a short moving passage, including any point where framing changes.

Prepare common geometry and source timing deliberately

Inspect ffmpeg -h filter=maskedmerge. Its input roles are base, overlay and mask, and its planes option controls which components are affected. Keep compatible dimensions and pixel representations through the prepared graph. If a mask carries only one intended brightness representation, prepare that representation explicitly rather than assuming unrelated chroma components provide the same weights.

For three already registered eight-bit yuv444p resources of the same cadence, an illustrative bounded graph is ffmpeg -n -t 5 -i base.mkv -t 5 -i alternate.mkv -t 5 -i mask.mkv -filter_complex "[0:v] setpts=PTS-STARTPTS[b]; [1:v] setpts=PTS-STARTPTS[a]; [2:v] setpts=PTS-STARTPTS[m]; [b][a][m] maskedmerge[out]" -map "[out]" -an -c:v ffv1 review-mask.mkv. The example assumes intentionally aligned starts and a prepared equal-component grayscale mask. It does not create those prerequisites.

Verify the changing mask rather than only its first image

Resetting timestamps can put starts on a common local origin, but it does not synchronize different captured events. Inspect a recognizable movement and verify that mask boundaries follow the correct picture region. Check later frames for drift, unexpected blending and a mask that remains still while the subject moves. Do not accept a mask solely because all inputs have equal reported duration.

Check the end of the intended interval and confirm that a shortened or ended companion has not caused an unintended retained result. Inspect the saved artifact independently from the graph preview. If a mask needs inversion or another geometric change, make that a documented separate preparation and verify it against the unchanged resources before accepting a full render.

Retain an honest receiving handoff

This bounded example selects only the combined picture. Required sound, captions and other resources need explicit mapping and receiver verification in the final delivery. Combining picture values is different from saving a reusable transparent foreground; confirm whether the recipient wants a flattened image or a separate alpha-bearing resource before choosing output packaging.

Retain the source-to-mask association and the accepted input versions, settings and interval. A new source edit can invalidate a previously matched matte. SocialVidDownloader does not expose arbitrary three-stream maskedmerge graphs or automatic mask tracking. Its working image watermark remains a different tool. If the resource relationship is uncertain, preserve the parents and leave the composite unapproved rather than claiming the native filter reconstructed a reliable foreground.

Worked example

Example: a mask follows an earlier stabilized version while the alternate picture uses a later crop. Equal output dimensions make the graph run, but moving edges reveal the wrong relationship. The editor obtains the correctly matched mask and verifies the saved interval instead of using completion alone as proof of alignment.

Related guidance

• Separate alpha companions: retain geometry and matching timing
• Timed FFmpeg overlays: verify origins, alpha and the ending

Sources and verification

• FFmpeg maskedmerge input and weight definition

Reviewed 2026-10-13. Product behavior is limited to available source formats and provider access; it is not a promise that every public link works.