Nodaro DocsVideo Mask
Describe a subject in plain words and get a black-and-white mask video that tracks it through the clip, with SAM 3.1 or SAM 3, for clips up to 5 minutes.
The Video Mask node tracks a subject that you describe in plain words through a video, and returns a black-and-white mask video. The mask has the same length and frame rate as the clip. It is white on every pixel of the subject in every frame, and black everywhere else. The node runs SAM 3.1 or SAM 3.
The mask is an ordinary video, so you can connect it anywhere a video goes. Its main partner is Mask Composite, which uses the mask to place the subject from one video over another video. The mask also feeds the Mask video input of Relight & Switch in Custom mode.
When to use it
- Move a subject into a new scene, for example a dancer onto a beach, together with Mask Composite.
- Replace the background behind a product or a person in a clip.
- Make a frame-accurate matte video for the Custom mode of Relight & Switch.
- Keep everything except one subject, with Invert mask on Mask Composite.
Quick start
Add the node
Press Tab on the canvas and choose Video › Continue & Restyle › Video Mask.
Connect the video
Wire the clip into the Video input, for example from an Upload Video node.
Describe the subject
Open the settings panel. Under Describe what to mask, write a short noun phrase, such as the dancer or the red car.
Run it
Click Run on the node. The mask video appears on the node. Wire its Mask output into the Mask input of a Mask Composite node.
Inputs
| Input | Accepts | What it does |
|---|---|---|
| Video | Video nodes, such as Upload Video, Generate Video and Trim Video | The clip to mask. Required. |
| Prompt | Text nodes, such as Text or a list item | A description of the subject. A wired prompt replaces the description in the settings panel. Optional. |
Outputs
| Output | What it carries |
|---|---|
| Mask | The mask video, an MP4 of the same length and frame rate as the clip. White is the subject, black is everything else. |
White means the subject. Generate Mask, the node that masks a still image, uses the same rule, and Mask Composite expects it.
A rotated phone clip, a clip with a variable frame rate, or a clip larger than 1920 pixels on its long side is first converted upright, at a constant frame rate and at most 1920 pixels. The mask has that size. Mask Composite stretches the mask over the full-size footage, so you do not need to do anything.
The mask is never watermarked, on any plan.
Settings
| Setting | What it does |
|---|---|
| Describe what to mask | What to track, up to 500 characters. A short noun phrase works best, such as the woman in the red coat or the skateboard. Separate several subjects with commas, for example person, dog: the mask is white wherever any of them is. Required, unless a text node is wired into Prompt. |
| Detection threshold | How sure the model must be before it marks a region, from 0.05 to 0.95 in steps of 0.05. The default is 0.5. A lower value finds more regions, with less precision. Try 0.3 when nothing matches. |
| Model | SAM 3.1, the default, tracks several objects in one pass and runs faster. SAM 3 costs half the price. |
| Pre & post text | Text that is always added before and after the description. It is hidden from people who use your workflow as an app. See Prompt pre and post text. |
Limits
- Length: clips up to 5 minutes at 30 fps.
- Frame rate: a faster clip counts proportionally longer, because the model works frame by frame. A 60 fps clip counts as twice its length, so it can be up to 2.5 minutes long.
- Long clips: a clip longer than 60 seconds at 30 fps is processed in 60-second pieces, and the pieces are joined frame by frame. Tracking starts again at the start of each piece. The mask holds everything the description matches, so this rarely shows.
A clip that Nodaro cannot read, or a clip over the limit, is refused before anything is charged. Cut a long clip with Trim Video first.
Credits
The price follows the length of the clip, counted at 30 fps, and the model. The length is rounded up to a whole second, and the run is charged the first row that covers it.
| Clip length (at 30 fps) | SAM 3.1 | SAM 3 |
|---|---|---|
| Up to 5 seconds | 55 | 28 |
| Up to 10 seconds | 105 | 53 |
| Up to 15 seconds | 160 | 81 |
| Up to 30 seconds | 314 | 158 |
| Up to 60 seconds | 622 | 312 |
| Up to 90 seconds | 935 | 468 |
| Up to 2 minutes | 1,243 | 622 |
| Up to 3 minutes | 1,865 | 933 |
| Up to 4 minutes | 2,486 | 1,243 |
| Up to 5 minutes | 3,108 | 1,555 |
A clip faster than 30 fps counts proportionally longer. For example, a 12-second clip at 24 fps counts as 12 seconds, so on SAM 3.1 it costs 160 credits. A 10-second clip at 60 fps counts as 20 seconds, so on SAM 3.1 it costs 314 credits.
Before a run, the node knows the clip's length only when the workflow tells it, for example from a Trim Video window or the duration set on a video generation node. The node then shows the price of that length at 30 fps. Otherwise the node shows a range, from 55 to 3,108 credits on SAM 3.1, and from 28 to 1,555 credits on SAM 3. The run itself always measures the clip, including its real frame rate, and is charged that row.
Tips
- Use a short noun phrase.
the dancerworks better than a long sentence about the dancer. - Lower the threshold when nothing matches. Try 0.3 before you rewrite the description.
- Trim before you mask. The price follows the clip's length, so cut the clip to the moment you need with Trim Video.
- Choose SAM 3 to save credits. SAM 3 costs half the price of SAM 3.1. SAM 3.1 tracks several objects in one pass and runs faster.
- A subject that leaves the frame is found again. When the subject comes back, the mask follows it again. The frames where it is absent are black.
Troubleshooting
The run fails with "No region matched the mask prompt on any frame". Nothing in the video matched your description. Your credits are refunded. Shorten the description to a plain noun phrase, or lower the Detection threshold.
The clip is refused as too long. The clip is longer than 5 minutes at 30 fps, or a faster clip counts as longer than that. Cut it with Trim Video and run again.
The run fails on a self-hosted install. On a self-hosted install, Video Mask needs a key for the provider that runs its models. Without the key, the run fails with a message that says so. See Provider keys.
From the API
POST /v1/video-mask takes videoUrl, prompt (up to 500 characters; commas track several subjects), an optional threshold from 0.05 to 0.95 (default 0.5) and an optional provider, sam-3.1 (the default) or sam-3. It returns a job. The finished job's output carries videoUrl (the mask), thumbnailUrl, width, height, frames, chunks and coverage. A clip that cannot be read, or a clip over the limit, is refused with a 400 error before anything is charged.
- SDK:
videoMask({ videoUrl, prompt, threshold, provider }). See Media and uploads. - MCP: the
video_masktool takesvideo_urlorvideo_asset_id,prompt, and optionalthresholdandprovider. Its job id chains intomask_compositeasmask_asset_id. See the MCP tools. - CLI:
nodaro media video-mask <videoUrl> <prompt> [--threshold <n>] [--model sam-3.1|sam-3]. See Media and voice commands.
See Run a single node and Jobs.
Frequently asked questions
What does the Video Mask node do?
Video Mask tracks a subject that you describe in plain words through a video. It returns a black-and-white mask video of the same length and frame rate, white on the subject in every frame and black everywhere else.
Which model should I choose, SAM 3.1 or SAM 3?
SAM 3.1 is the default. It tracks several objects in one pass and runs faster. SAM 3 costs half the price of SAM 3.1.
How long can the video be?
Up to 5 minutes at 30 fps. A faster clip counts proportionally longer, so a 60 fps clip can be up to 2.5 minutes long. A clip over the limit is refused before anything is charged.
Can I track more than one subject?
Yes. Separate the subjects with commas, for example "person, dog". The mask is white wherever any of them is.
What happens when the prompt matches nothing?
When nothing matches on any frame, the run fails with "No region matched the mask prompt on any frame" and your credits are refunded. Use a shorter, plainer description, or lower the Detection threshold.
How do I put the masked subject into another video?
Wire the Mask output into the Mask input of a Mask Composite node. Wire the original video into its Foreground input and the new scene into its Background input.
Related
Mask Composite
Relight & Switch
Generate Mask
Trim Video
Prompt pre and post text
Last updated on
Video Depth
Turn any video into a depth video, where near is bright and far is dark, with Video Depth Anything or Depth Anything per frame, in grayscale or a colormap.
Trim Video
Cut a video by start and end time, trim seconds or frames from its edges, keep its first or last seconds, or cut at the cleanest loop point with Smart loop cut.