🖼️ Compose Overlay Image

MF_ComposeOverlayImage is the general-purpose "put a picture on top of the video" node in MediaForge's Compose pipeline. You give it an image, a position, a scale, and an optional time window, and it appends an overlay op to the MF_COMPOSE_OPS chain that MF_ComposeVideo renders in the single encode. Lower-third nameplate, a sticker, a logo bug, a "SUBSCRIBE" graphic - this is the node for "I need this specific image at this specific spot."

The distinction worth making up front: if your image is a watermark - a logo you want placed in a corner, scaled relative to the frame, at some opacity - use MF_ComposeWatermark instead. This node is for absolute position and absolute scale; the watermark node is a preset wrapper around the same mechanism with proportional sizing and opacity built in. Reaching for the watermark node for a one-off sticker is fine either way; reaching for this one when you want proportional watermarking across resolutions is where you fight it.

How it works

It writes an overlay filter op with your position expressions, scale, and visibility window. MF_ComposeVideo compiles the whole overlay chain into one filter_complex graph - so your overlay costs one decode/encode pass no matter how many overlays are stacked.

The inputs that matter

• image_path - PNG, JPG, whatever FFmpeg can decode. PNG with alpha if you want anything but a rectangle.
• x_expr / y_expr - position, and these are expressions, not just numbers. 10 / 10 is top-left with padding; W-w-10 puts it 10px from the right edge (uppercase W/H are the main frame, lowercase w/h the overlay). You can even use t for time-dependent motion.
• scale_w - target width in px; 0 = keep the original size (height auto-scales by aspect). Set this when your source image isn't already the size you want.
• start_sec / end_sec - visibility window. Both 0 = always visible.

Optional overlays chains the previous overlay node; output overlays feeds the next overlay or MF_ComposeVideo.

Install

It's part of MediaForge - one install covers it:

cd ComfyUI/custom_nodes
git clone https://github.com/leon80148/comfyui_MediaForge.git
# restart ComfyUI

Or ComfyUI Manager → "MediaForge". No extra Python deps beyond the pack's requirements.txt.

Common issues

The scale gotcha: scale_w=0 means "original size," so a 4000px-wide PNG overlay appears at 4000px wide. If you're placing a logo you exported at canvas size, set scale_w explicitly. And x_expr/y_expr are strings - a stray space or an unclosed paren breaks the filter at encode time with the pack's standard RuntimeError: ffmpeg ... failed (stderr is printed above it). Paths with : [ ] ' , ; are auto-escaped, but if your overlay image lives in a path with those characters and something breaks, that's the first thing to test.