Nodaro DocsMask Composite
Place a foreground video over a background video through a mask video, with invert, feather, grow and audio options. It runs on every edition without a key.
The Mask Composite node places a foreground video over a background video through a mask video. Where the mask is white, you see the foreground. Where the mask is black, you see the background, and grey blends the two. Mask Composite runs no AI model, so the same inputs always give the same result.
Its natural partner is Video Mask. Mask a subject in its own footage with Video Mask, then use that footage as the foreground and any other video as the background. The subject then appears in the new scene.
Mask Composite needs no provider key, so it runs on every edition, including a Community Edition install without any keys.
When to use it
- Move a subject into a new scene, for example a dancer onto a beach.
- Replace the background behind a product or a presenter.
- Keep everything except the subject, with Invert mask, and put a new subject in its place.
- Combine two clips through a black-and-white matte made in another tool.
Quick start
Add the node
Press Tab on the canvas and choose Video › Cut & Assemble › Mask Composite.
Connect the three videos
Wire the footage with the subject into Foreground, the new scene into Background, and the mask video into Mask, for example the Mask output of a Video Mask node.
Adjust the edge
Open the settings panel. Keep Feather at 2 pixels for a soft edge, and set Grow / shrink below 0 if a thin line of the old background shows around the subject.
Run it
Click Run on the node. The composited video appears on the node.
Inputs
| Input | Accepts | What it does |
|---|---|---|
| Foreground | Video nodes, such as Upload Video and Generate Video | The footage whose white-masked region is kept. The result has its size, frame rate and length. Required. |
| Background | Video nodes | The video shown where the mask is black. Required. |
| Mask | Video nodes, such as Video Mask | The mask video. White shows the foreground, black shows the background. Required. |
The background is fitted to the foreground's frame, as Background fit sets, and loops when it is shorter than the foreground. The mask is stretched to the foreground's frame and holds its last frame when it is shorter. Near-black counts as fully background and near-white as fully foreground, so compression noise never leaves a faint ghost.
Outputs
| Output | What it carries |
|---|---|
| Video | The composited video, an MP4 with the foreground's size, frame rate and length. It has sound when the Audio setting keeps a track. |
The result is never watermarked.
Settings
| Setting | What it does |
|---|---|
| Invert mask | Swaps the sides: white shows the background and black shows the foreground. Use it to keep everything except the subject. Off by default. |
| Feather | Softens the mask's edge, from 0 to 20 pixels. The default is 2. At 0 the edge is hard. A few pixels hide the steps along the edge of a tracked mask. |
| Grow / shrink | Widens (a positive value) or narrows (a negative value) the white area, from −10 to 10 pixels, before the edge is softened. The default is 0. A negative value trims a thin line of the old background around the subject. |
| Background fit | How the background fills the foreground's frame. Cover (crop to fill), the default, fills the frame and crops what does not fit. Contain (letterbox) shows the whole background with black bars. Stretch stretches the background to the frame. |
| Audio | Which sound the result has. Foreground audio is the default. The other choices are Background audio, Mix both, at equal level, and No audio. When the chosen track does not exist, the result is silent. Mix both with only one track uses that track. |
Limits
- Length: a foreground up to 300 seconds long.
A foreground that Nodaro cannot read, or one longer than 300 seconds, is refused before anything is charged.
Credits
Mask Composite costs 11 credits for every started 5 seconds of the result. The result is as long as the foreground. A run counts at least one 5-second step: a 3-second result counts one step, a 10-second result counts two, and a 61-second result counts 13.
Before a run, the node knows the foreground's length only when the workflow tells it. Otherwise the node shows a range, from the price of one 5-second step up to the price of a 300-second result. The run measures the foreground before anything is charged, and you pay for its real length.
Tips
- Trim the foreground first. The result is as long as the foreground, so cut it to the moment you need with Trim Video.
- Use a background at least as long as the foreground. A shorter background loops, which can show a visible jump.
- Trim halos with a negative grow. Set Grow / shrink to a small negative value when a thin line of the old background shows around the subject.
- Keep a little feather. A few pixels of Feather hide the steps along the edge of a tracked mask.
- Any matte works. A black-and-white or greyscale video from another tool, such as a rendered shape animation, works as the mask.
Troubleshooting
The subject has a thin outline of the old background. Set Grow / shrink to a small negative value, and keep some Feather.
The background shows where the subject should be. The mask has the opposite polarity. Turn on Invert mask.
The result has no sound. The track chosen under Audio does not exist in that video. Choose the other video's audio, or Mix both.
The background has black bars or is cropped. Change Background fit. Cover (crop to fill) crops, Contain (letterbox) adds bars, and Stretch fills the frame without either.
From the API
POST /v1/mask-composite takes foregroundUrl, backgroundUrl and maskUrl, with optional invertMask, feather (0 to 20), grow (−10 to 10), backgroundFit (cover, contain or stretch) and audioSource (foreground, background, mix or none). It returns a job. The finished job's output carries videoUrl, thumbnailUrl, width, height and durationSec. A foreground longer than 300 seconds is refused with a 400 error before anything is charged.
- SDK:
maskComposite({ foregroundUrl, backgroundUrl, maskUrl, invertMask, feather, grow, backgroundFit, audioSource }). See Media and uploads. - MCP: the
mask_compositetool takes each of the three videos as<name>_urlor<name>_asset_id(foreground,background,mask), so avideo_maskjob id can be themask_asset_id. The settings areinvert_mask,feather,grow,background_fitandaudio_source. See the MCP tools. - CLI:
nodaro media mask-composite <foregroundUrl> <backgroundUrl> <maskUrl> [--invert] [--feather <px>] [--grow <px>] [--background-fit cover|contain|stretch] [--audio foreground|background|mix|none]. See Media and voice commands.
See Run a single node and Jobs.
Frequently asked questions
What does the Mask Composite node do?
Mask Composite combines three videos into one. Where the mask is white, you see the foreground video. Where the mask is black, you see the background video, and grey blends the two.
Where do I get the mask video?
The usual source is a Video Mask node, which tracks a subject that you describe through the foreground video. Any black-and-white or greyscale video works as the mask, for example a matte made in another tool.
What if the background is shorter or a different size?
The result follows the foreground's size, frame rate and length. The background is fitted to the foreground's frame and loops when it is shorter. The mask is stretched to the frame and holds its last frame when it is shorter.
How much does Mask Composite cost?
Mask Composite costs 11 credits for every started 5 seconds of the result, which is as long as the foreground. A foreground can be up to 300 seconds long.
Does Mask Composite need an API key on a self-hosted install?
No. Mask Composite runs no AI model and needs no provider key, so it runs on every edition, including Community Edition without any keys.
Related
Video Mask
Composite
Relight & Switch
Trim Video
Upload Video
Last updated on
Composite
Layer up to four videos into one composition with per-layer position, blend mode, opacity and timing. It costs no credits; Render Video turns it into an MP4.
Compose Video
Describe the video you want, and an AI model arranges your connected images, clips and audio into a timed, multi-track composition that Render Video renders.