Video Overlay

The Video Overlay node shows images and videos on top of a video, each during its own time window. Use it for logos, product shots, screenshots and cards timed to a voice-over, and for two videos together: a landscape clip at the bottom of a vertical frame, two stacked clips, or a picture in picture. The node draws your exact files over the video, keeps the original audio, and shows a live preview on the node, all without an AI model.

When to use it

• You make a UGC ad and want product cards, app screenshots or web pages to appear while the speaker mentions them.
• You want a logo or a channel handle on screen for the whole video.
• You want a landscape clip at the bottom of a vertical frame, with a title card above it.
• You want two clips stacked, for a reaction or a before-and-after.
• You want a fixed picture in picture, such as a guest, a screen recording or a camera inset.
• You want price tags or "NEW" badges over product clips.

Quick start

Inputs

The output, Video, is the video with the layers drawn on it, as an MP4.

Use the + Layer and − Layer buttons in the settings panel to show between 1 and 12 layer handles. The count also grows by itself when you connect a higher handle. A layer can also carry an image or video URL instead of a connection. The API, MCP and templates use this, and it is how layers 13 and up exist. Connecting a node to the layer's handle replaces that URL.

Layer plan input

The Layer plan input takes a JSON list of layers in the node's own layer format: imageUrl or videoUrl, start, end, sound, and the box fields anchor, x, y, width, height and fit. Use it, for example, with a node that times screenshot cards to a voice-over, such as UGC Cards.

• Plan layers are drawn under the handle layers, so a logo badge on a handle stays on top.
• Each plan layer needs its own imageUrl or videoUrl. A plan layer never takes its file from a handle. A plan layer without one fails the run. The message starts with "Plan layer 1: no image or video".
• Plan layers count toward the limits. Plan layers and handle layers together can be at most 20, and their video layers together at most 2.
• The preview shows plan layers as read-only layers, marked From the layer plan.
• An empty plan passes the video through. When a layer plan is connected and there is no layer to draw, the node outputs its video unchanged, at no cost.

The live preview

Once a base video is connected, the node shows a frame of it with the layers drawn where the render will put them. A video layer shows its first frame.

• Select a layer by clicking its bar in the Timeline of the settings panel. The preview jumps to the layer's start and shows only the layers visible at that moment.
• Drag a layer to move it, and pull its corner handle to resize it. Every drag writes the new percentages into the layer's settings, so the preview and the run use the same numbers.
• Move the base video the same way, after you select it with Move on preview on the Base video card. See The base video.
• Result or Result (old). After a run, the node shows Result. A run started in any way counts: the node's own Run, a workflow run, a schedule, a webhook or an app run. When you change the settings afterward, for example move a layer, connect another image or video, or choose another layout, the label reads Result (old) until you run again.

Layer settings

Each layer has its own card in the settings panel, headed Layer 1, Layer 2 and so on.

Animate in/out is off by default for a video layer because a fade would show at the start and end of a stacked or inset video. On a layer handle, the default follows what is connected: connect a video and its fade is off unless you turn it on.

Placements

Every position and size is a percentage of the output frame.

The Card sits over the middle of the frame, which is over the speaker's face on a 9:16 selfie video. That is on purpose: product cards pop up over the talking head. Put a logo or a badge that must not cover the subject in a corner badge or a custom box.

Custom boxes

• Anchor is one of nine positions on the frame where the layer attaches.
• Offset X and Offset Y move the layer from the anchor, from −100 to 100% of the frame width and height. A negative offset on a right or bottom anchor moves the layer inward.
• Width is 1 to 100% of the frame width.
• Height (% of frame, optional) is 1 to 100% of the frame height. Without it, the height follows the image's or video's aspect ratio.
• Fit (when height is set) decides how the layer fills the box: Contain shows the whole image or video, centered. Cover fills the box and crops it.

Setting any box field turns a preset layer into Custom. Dragging or resizing a preset layer on the preview does the same. A tall image whose height follows its aspect ratio is always fitted inside the frame: a 1:10 image at 60% width on a 1080×1920 video is drawn at 192×1920. Drawn sizes are rounded down to even pixels, and are at least 2×2.

Timing rules

• Times are seconds from the start of the video, from 0 to 3,600. They keep the precision you type, and the render places them on the video's frame grid, so a layer can appear up to one frame early or late.
• A layer whose End (s) is past the end of the video is clipped to the end.
• A layer that starts at or after the end of the video is skipped, and its file is not downloaded.
• A layer shorter than 0.3 seconds uses half its length for each fade.

The panel warns about clipped and skipped layers as you type, using the length the browser reads. That length can differ from the video's own by a few hundredths of a second, so the run's warnings are the final word.

Video layers

A layer carries an image or a video, never both. On the API, a layer has an imageUrl or a videoUrl, and a layer with both is refused. A run takes at most 2 video layers. Everything else works as for an image layer: the box, Start (s), End (s), Opacity and Layer order (z). Images can sit above videos, and the base video is always at the bottom.

• A video layer plays from its own first frame, starting at the layer's Start (s).
• It stops at the layer's End (s), or at the end of the base video when the layer has no end.
• If the layer video is shorter, it holds its last frame until its window ends.
• Fit works as for an image. Contain shows the whole video in the box, and Cover fills the box and crops it. Without a height, the box follows the video's own shape.
• The output keeps the base video's frame rate. A layer video at another frame rate is drawn at the base's rate.
• On a layer handle, the connection decides whether the layer is an image or a video.

Sound

• By default, only the base video's sound plays, exactly as it does without video layers.
• A video layer is silent unless its sound is on. On the canvas, open the layer's Sound section, turn on Play this video's sound, then set Volume from 0 to 100%. On the API, set sound: { volume }, from 0 to 1, where 1 is the sound as recorded.
• A layer's sound is mixed with the base's sound during the layer's window, at its volume. The mix passes a limiter, so two loud sources at full volume do not clip. Normal levels are not raised or lowered.
• A mixed soundtrack is AAC, as long as the video. With a silent base video, the soundtrack is the layer's sound alone, padded with silence.
• A layer video without an audio track is drawn silent, and the run reports the layer_no_audio warning.
• Sound is for a video layer only. On the API, a layer that carries an image and a sound is refused. On a layer handle that receives an image at run time, a stored sound is skipped and the run goes ahead.

Layouts

A layout places the base video, the first video layer, or both, with one choice. The first video layer is the lowest video layer in the layer order. Image layers stay where you put them. On the canvas, choose it in the Layout select at the top of the settings panel. Custom means no layout. On the API, MCP, the SDK and the CLI, it is the request's layout field.

• Stack whole shows both videos whole, at the same width, touching. The pair is centered, with equal room above and below. The videos shrink together only when the two are taller than the frame. Two 16:9 videos on a 1080×1920 frame are drawn at 1080×606 each, with 354 pixels above and below.
• Stack filled on a 1080×1920 frame fills the top half (y 0 to 960) with the base and the bottom half (y 960 to 1920) with the video layer. Both are cropped.
• Video at bottom with a 16:9 base on a 1080×1920 frame draws the base at y 1314 to 1920, against the bottom edge. Image layers above it go where you place them.
• Video at bottom and Video at top need no video layer. With image layers only, the run keeps the image-only price.
• Picture in picture takes its corner from the first video layer's Corner, and replaces any box that layer had.
• Picture in picture and the two stacks turn off the first video layer's fade. Video at bottom and Video at top leave every layer as it is.

These requests are refused:

• A layout that needs an output aspect, without one: "layout video-bottom needs an outputAspect".
• A layout that needs a video layer, without one: "layout pip needs a video layer — set videoUrl on a layer or connect a video to a layer's handle".
• A stack layout with a base box, because a stack places the base itself: "A stack layout places the base itself — remove baseBox or choose Custom".

A base box you set yourself wins over Video at bottom and Video at top.

On the canvas:

• Choosing a layout that needs an output aspect, when none is set, sets Output aspect to 9:16.
• Choosing any layout removes a base box you placed yourself.
• Moving or resizing a layer, changing its placement, or moving the base video turns the layout into Custom. Everything stays where it is.
• Under Picture in picture or a stack, changing the fade of the first video layer also turns the layout into Custom.

The base video

By default, the base video fills the output as described under Output settings. With an output aspect, you can also place the base video yourself, with a base box. A base box uses the same fields as a layer's custom box: Anchor, Offset X, Offset Y, Width, an optional Height and Fit. On the API it is baseBox: anchor and width are required, x and y default to 0, and fit defaults to contain. A base box overrides Video fit. Any part of the frame that the base does not cover shows the Padding colour. A base box without an output aspect is refused: "baseBox needs an outputAspect".

The Base video card in the settings panel shows where the base is:

• Without an output aspect, the card says that one is needed to move the base.
• Under a stack layout, the card says that the layout places the base. It offers Move on preview once the shapes of the two videos are read.
• Placed by Video fit, the card offers Move on preview.
• Under Video at bottom or Video at top, with no box of its own, the card shows the layout's box as fields, with Move on preview. Editing a field turns the layout into Custom.
• With a box of its own, the card shows the box's fields and Reset. Reset removes the box, so Video fit places the base again.

Press Move on preview to select the base video. You can then drag and resize it on the preview, like a layer, and the first move gives it a box of its own. Under any layout, the first move turns the layout into Custom and keeps everything where it is. When the base is not selected, it takes no clicks on the preview, so dragging the node body moves the node as before.

Output settings

Without an output aspect, the result keeps the video's own display size and frame rate. A phone clip stored sideways renders upright, non-square pixels are corrected, and odd dimensions are rounded down to even numbers, so a 1079×1919 source renders at 1078×1918.

The result is an H.264 MP4 that starts playing before it has fully downloaded. Only the first audio track of the base video is kept, and a video without audio stays silent, unless a video layer has its sound on. See Sound.

Limits

• Layers: 1 to 20 per run. A node with more than 20 layers that have an image or a video is refused before the run, and the Run button says so. Remove layers to get back to 20; the remaining layers keep their numbers. No layer is dropped silently, and nothing is charged.
• Video layers: at most 2 per run. A request with more is refused, for example "At most 2 video layers (got 3)".
• Base video length with a video layer: up to 60 seconds. The base video is measured before anything is charged, on the API and in a workflow run. A longer base is refused with "The base video is 61 seconds. A Video Overlay with a video layer takes a base of up to 60 seconds — trim it first." A base that cannot be read is refused with "Could not read the base video. The file may be corrupted or an unsupported format." On the canvas, the settings panel warns about a base past 60 seconds, and the server's measurement decides. A run with image layers only has no length limit.
• Layer videos: up to 200 MB each. A larger one fails the run, for example "Layer 2: video is too large (over 200 MB)". A video that cannot be downloaded fails with "Layer 2: video could not be fetched". A file that is not a video, such as an image, an audio file or a web page, fails with "Layer 2: not a video".
• Images: PNG, JPEG or WebP, up to 25 MB each and 100 MB together, up to 8,192 pixels on the longest edge and 400 megapixels together. Photo orientation from the camera is applied.
• SVG is refused. Turn an SVG into a PNG with Image Overlay first.
• Animated images such as animated WebP and APNG show their first frame.
• The base must be a video. An audio file, an image, or a web page saved as .mp4 fails with "The base input is not a video".
• A stacked video that starts too late: with a stack layout, a first video layer that starts at or after the end of the base video is refused before anything is charged.
• Render time: a render stops after 10 minutes.
• API rate: up to 30 requests a minute per user.

Warnings

A successful run can report warnings. The settings panel shows them in one Last run line.

When every layer starts after the end of the video, the run fails instead, with the message "Every layer starts after the video ends". With a video layer, this is checked before anything is charged. A layer image that cannot be downloaded also fails the run, for example "Layer 3: image could not be fetched". A failed run is not charged.

Credits

• Image layers only: 22 credits per run, whatever the number of layers or the length of the video.
• Any video layer: the run is priced per started 5 seconds of the base video, which is also the length of the output. A fraction of up to 0.05 seconds past a whole second is ignored, so a 10.01-second base counts as 2 units, not 3.

What decides the price is whether any layer is a video, not the layout. Video at bottom over image layers only keeps the image-only price.

The Run button shows the price before a run. For a run with a video layer, it uses the base video's length when the workflow already knows it, and the 60-second limit when it does not, so the quote is never below the charge. A layer handle connected to a node that may hand over a video, and a layer plan whose layers are known only at run time, are quoted as a run with a video layer. The layer plan from UGC Cards holds card images only, so it keeps the image-only price.

The render measures the base video again. If a link now serves a longer video than the one the run was priced for, the run is refused before anything is drawn, and the charge is refunded.

On the API, GET /v1/credits/model-cost?model=video-overlay returns the image-only price, and GET /v1/credits/model-cost?model=video-overlay:video returns the price of one 5-second unit.

A failed run is not charged. On a self-hosted Community Edition install there are no credits, and the node runs without any API key.

Example: product cards over a talking head

A 9:16 selfie video with three images, each shown while the speaker mentions it:

On a 1080×1920 video, each card's box is 842×1152 pixels at (119, 307). A screenshot with a 1:2 aspect ratio is drawn at 576×1152 pixels inside it, centered.

The same request through the API, POST /v1/video-overlay:

{
  "videoUrl": "https://example.com/selfie.mp4",
  "layers": [
    { "imageUrl": "https://example.com/pricing-page.png", "start": 1.2, "end": 2.6, "preset": "card" },
    { "imageUrl": "https://example.com/dashboard.png", "start": 3.0, "end": 4.4, "preset": "card" },
    { "imageUrl": "https://example.com/logo.png", "start": 0, "preset": "corner-badge", "corner": "top-right" }
  ]
}

Examples: videos together

A 16:9 video at the bottom of a 9:16 frame, with a card above it. The base video is drawn at 1080×606, at y 1314 to 1920. The card sits in the black space above it. This run has image layers only, so it keeps the image-only price.

{
  "videoUrl": "https://example.com/talk-16x9.mp4",
  "outputAspect": "9:16",
  "layout": "video-bottom",
  "layers": [
    { "imageUrl": "https://example.com/card.png", "start": 0, "anchor": "top", "x": 0, "y": 8, "width": 80 }
  ]
}

Two 16:9 videos stacked, whole. Each video is drawn at 1080×606, with 354 pixels above and below. If the second video is shorter than the base, it holds its last frame.

{
  "videoUrl": "https://example.com/a.mp4",
  "outputAspect": "9:16",
  "layout": "stack-whole",
  "layers": [ { "videoUrl": "https://example.com/b.mp4", "start": 0 } ]
}

A fixed picture in picture with the inset's sound on. The inset is 30% of the frame width, 4% in from the top-right corner. Its sound is mixed with the base's sound at 80%.

{
  "videoUrl": "https://example.com/main.mp4",
  "layout": "pip",
  "layers": [ { "videoUrl": "https://example.com/guest.mp4", "start": 0, "corner": "top-right", "sound": { "volume": 0.8 } } ]
}

AI assistants use the overlay_images MCP tool. Each layer takes a url or an asset_id for an image, and a video_url or a video_asset_id for a video. The tool also takes layout and base_box. From the command line, use nodaro media video-overlay, with video layers in --layers-file, and the --layout and --base-box options.

Tips

• Keep cards short and separate. Show a card for a second or two, and do not let cards overlap in time, so one is on screen at a time.
• Use corners for long-lived layers. A logo, a handle or a price that stays up for long belongs in a corner badge or a custom box, away from the speaker.
• Use transparent PNGs for logos. An opaque JPEG is placed as a rectangle.
• Keep the video's own frame. Set Output aspect only when you need a different frame than the source.
• Choose a layout first for two videos. Then adjust from there.
• Cut first. Use Trim Video before Video Overlay to shorten the base video. A run with a video layer takes a base of up to 60 seconds.
• Turn on a layer's sound only when it should be heard. At full volume over a loud base video, lower one of the two.
• Caption after. Connect the result to Add Captions. The layers stay under the captions.
• Style a badge first. Connect an Image Overlay result to a layer handle to put text, a QR code or a styled badge on the video.