# Video Overlay

> Show up to 20 images over a video, each in its own time window, as a card, corner badge, full frame or custom box, with a live preview and the audio kept.

Source: https://nodaro.ai/docs/nodes/video/video-overlay

The **Video Overlay** node shows images 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. The node draws your exact image files over the video, keeps the original audio, and shows a live preview on the node, all without an AI model.

- Found in: Video › Titles, Graphics & Captions
- API type: `video-overlay`

## 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 picture-in-picture stills, before-and-after images or reaction images.
- You want price tags or "NEW" badges over product clips.

## Quick start
### Add the node

Press Tab on the canvas and choose **Video › Titles, Graphics & Captions › Video Overlay**.

### Connect the video and the images

Connect the base video to the **Video** input. Connect each image to its own layer handle: **Layer 1**, **Layer 2** and so on. The node starts with 4 layer handles.

### Time and place each layer

Open the settings panel. For each layer, set **Start (s)** and **End (s)**, then choose a **Placement**. Drag a layer on the node's preview to move it, or pull its corner handle to resize it.

### Run it

Click **Run**. The node renders the video with every layer in its window. The preview label changes from **Preview** to **Result**.

Workflow: A screenshot pops up as a card and a logo stays in the corner; captions go on top, then the video is posted.

- Upload Video → Video Overlay (video)
- Upload Image → Video Overlay (layer 1)
- Upload Image → Video Overlay (layer 2)
- Video Overlay → Add Captions (video)
- Add Captions → TikTok Post

## Inputs
| Input | Accepts | What it does |
| --- | --- | --- |
| **Video** | Video nodes, such as Upload Video and Generate Video | The base video. Required. |
| **Layer 1** to **Layer 12** | Image nodes, such as Upload Image, Generate Image and Image Overlay | One image per layer. Layer 1 is the first handle, Layer 2 the second, and so on. |

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.

## 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.

- **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.
- **Result or Result (old).** After a run, the node shows **Result**. When you change the settings afterward, for example move a layer or connect another image, 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.

| Setting | What it does |
| --- | --- |
| **Start (s)** | When the layer appears, in seconds from the start of the video. The default is `0`. |
| **End (s)** | When the layer disappears. It must be after **Start (s)**. Leave it empty to show the layer until the video ends. |
| **Placement** | **Card**, **Corner badge**, **Full frame** or **Custom**. A connected layer you have not changed is a bottom-right corner badge for the whole video. |
| **Corner** | For **Corner badge**: **Top left**, **Top right**, **Bottom left** or **Bottom right** (the default). |
| **Anchor**, **Offset X**, **Offset Y**, **Width**, **Height (% of frame, optional)**, **Fit (when height is set)** | For **Custom**. See [Custom boxes](#custom-boxes). |
| **Layer order (z)** | From 0 to 100. A higher layer draws on top. Empty means the layer number, so Layer 1 is at the bottom. The preview's up and down buttons set it too. |
| **Opacity** | From 0 to 100%. The default is 100%. |
| **Animate in/out** | On by default. The layer fades in while it grows from 96% to 100% of its size over 0.15 seconds, and does the reverse at its end. |

### Placements

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

| Placement | Where the layer lands |
| --- | --- |
| **Card** | Centered, 4% above the middle, fitted inside 78% × 60% of the frame. The image keeps its aspect ratio. |
| **Corner badge** | 18% of the frame width, 4% in from the chosen corner. |
| **Full frame** | Covers the whole frame. The image is cropped to fill it. |
| **Custom** | Your own box. |

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 aspect ratio.
- **Fit (when height is set)** decides how the image fills the box: **Contain** shows the whole image, centered. **Cover** fills the box and crops the image.

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 image 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.

## Output settings

| Setting | What it does |
| --- | --- |
| **Output aspect** | **Same as video** (the default), `16:9` (1920×1080), `9:16` (1080×1920), `1:1` (1080×1080) or `4:5` (1080×1350). With an output aspect, layer percentages are of that new frame. |
| **Video fit** | With an output aspect only. **Cover** (the default) fills the frame and crops the video. **Contain** shows the whole video and pads it. |
| **Padding colour** | With **Contain** only. The color of the padding. The default is black. |

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.

## Limits
- **Layers:** 1 to 20 per run. A node with more than 20 layers that have an image 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.
- **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](https://nodaro.ai/docs/nodes/image/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".
- **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.

| Warning | API code | Meaning |
| --- | --- | --- |
| Clipped | `clipped` | The layer's end was past the end of the video, so it was shown until the end. |
| Skipped | `skipped` | The layer started at or after the end of the video, so it was not drawn. |
| Animated image | `animated_first_frame` | The image was an animated WebP, so its first frame was used. |
| Audio re-encoded | `audio_reencoded` | The video's audio could not be copied into MP4 as it was, so it was re-encoded to AAC. |

When every layer starts after the end of the video, the run fails instead, with the message "Every layer starts after the video ends". A layer image that cannot be downloaded also fails the run, for example "Layer 3: image could not be fetched".

## Credits
Video Overlay costs 20 credits per run, whatever the number of layers or the length of the video. 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:

| Layer | Image | Start (s) | End (s) | Placement |
| --- | --- | --- | --- | --- |
| 1 | pricing-page.png | 1.2 | 2.6 | Card |
| 2 | dashboard.png | 3.0 | 4.4 | Card |
| 3 | logo.png | 0 | to end | Corner badge, Top right |

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`:

```json
{
"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" }
]
}
```

AI assistants use the `overlay_images` MCP tool, where each layer takes a `url` or an `asset_id`. From the command line, use `nodaro media video-overlay`.

## 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.
- **Cut first.** Use [Trim Video](https://nodaro.ai/docs/nodes/video/trim-video) before Video Overlay to shorten the base video.
- **Caption after.** Connect the result to [Add Captions](https://nodaro.ai/docs/nodes/video/add-captions). The layers stay under the captions.
- **Style a badge first.** Connect an [Image Overlay](https://nodaro.ai/docs/nodes/image/image-overlay) result to a layer handle to put text, a QR code or a styled badge on the video.

## Frequently asked questions

### How many images can Video Overlay place on one video?

Up to 20 layers per run. The canvas node has up to 12 layer handles for connected images. Layers 13 to 20 come from image URLs set through the API, MCP or a template.

### Does Video Overlay change the audio of my video?

No. The audio of the base video is kept. It is copied as it is when it is AAC, MP3, AC-3 or Opus, and otherwise re-encoded to AAC, which the run reports as a warning.

### Why does my card cover the speaker's face?

The Card placement sits over the middle of the frame on purpose, so product cards pop up over a talking head. For a logo or a badge that must not cover the subject, use Corner badge or a Custom box.

### Which image formats can a layer use?

PNG, JPEG and WebP, up to 25 MB each and 100 MB together. SVG is refused, so turn it into a PNG with Image Overlay first. An animated image shows its first frame.

### How many credits does Video Overlay cost?

20 credits per run, whatever the number of layers or the length of the video. No AI model runs. On a self-hosted Community Edition install, the node runs without credits or API keys.