# Composite images and video with compositors

> Build layered composites in Nodespell with Image Compositor and Compositor nodes, Merge blend modes, custom channel expressions and canvas sizing.

Source: https://docs.nodespell.com/edit/compositing/ · Last updated: 2026-11-10

A compositor in Nodespell is a node that holds its own node graph for layering images and video, much like a Nuke script inside one node. **Image Compositor** produces a still image and **Compositor** produces a video. Everything inside renders on the GPU in your browser, and the result leaves through one output that the rest of your graph, including AI generators, can use.

## Which compositor should you use?

Nodespell has two compositor nodes. Both hold a node graph, both use the same effect nodes, and you can convert one into the other.

|                                                                                                                                                                                  | **Image Compositor**             | **Compositor**                                                             |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | -------------------------------------------------------------------------- |
| Produces                                                                                                                                                                         | A still image (output **Image**) | A video (outputs **Video**, **Compositor** and **Preview Frame**)          |
| Input on the node                                                                                                                                                                | **Images**                       | **Assets**                                                                 |
| Timeline, playhead and keyframes                                                                                                                                                 | No                               | Yes, with **Frame Rate** (default 30) and **Duration Seconds** (default 5) |
| Time-based nodes (Retime, Time Offset, Freeze Frame, Reverse Time, Optical Flow, Motion Blur, Camera Shake, Switch/Dissolve, Image Sequence, Timeline Source, Compositor Source) | Not supported                    | Supported                                                                  |
| Audio                                                                                                                                                                            | None                             | **Audio Source**: **First Input** or **None**                              |
| **Result** choices with colour management on                                                                                                                                     | **Review PNG** or **Master EXR** | **Review video**, or **HDR review** where your device supports it          |

If an Image Compositor contains a time-based node, it cannot render a still and names the node so you can remove it or convert back to Compositor.

The menus that convert between the two call the video compositor **Video Compositor**; it is the same node as **Compositor**.

## Create a compositor

1. In the Graph, press `Tab` to open the [Tab menu](https://docs.nodespell.com/graph/add-nodes/) and add **Image Compositor** or **Compositor**.
2. Connect your images or videos to the compositor's input (**Images** or **Assets**). The input accepts several connections, in order.
3. Select the compositor and press `Enter` to go inside it. Press `U` to come back out.
4. Inside, a new compositor already contains a **Compositor Input** connected to a **Compositor Output**. Add effect and Merge nodes between them.
5. Select the compositor or any node inside it to see the composite in the [Design panel](https://docs.nodespell.com/edit/viewers/).

You can also build a chain of image effects in the Graph first, select those nodes, right-click and choose **Convert to Video Compositor** or **Convert to Image Compositor**. Nodespell moves the selected nodes into a new compositor. If some connections cannot be carried inside, a message says how many were removed; use Undo to restore them. To switch an existing compositor between still and video, use the **Actions** submenu on the compositor node.

## How do Compositor Input and Compositor Output work?

**Compositor Input** brings the media connected to the parent compositor into its inner graph. Its **Index** parameter is zero-based: index 0 is the first connection on the compositor's input, index 1 the second, and so on. It has two outputs, **Asset** (the one item at that index) and **Assets** (all of them). Add one Compositor Input per source you want to work with separately.

**Compositor Output** marks what the compositor delivers. Whatever you connect to its **Source** input becomes the compositor's result. On a video Compositor, **Use In/Out Points** (on by default) renders the playback range; turn it off to set **Start Frame** and **End Frame** yourself.

A video Compositor also offers source nodes for other kinds of media: **Image Set Source** (several stills for switching or dissolving), **Image Sequence** (stills spread over time by **Total Length**, **Each Image Length** or **Manual Index**), **Timeline Source**, **Compositor Source** (a nested compositor) and **Switch/Dissolve**.

## Layer images with Merge

**Merge** combines one **Background** with one or more **Foregrounds**. Each foreground is merged over the result so far, in connection order, using the chosen **Mode** (default **Over**). **Mix** (0–1, default 1) fades the merged result back toward the background.

Merge follows Nuke's conventions: A is the foreground and B is the background. Foregrounds are premultiplied before merging, so you can feed straight-alpha images directly; only **Matte** reads the foreground unpremultiplied. Inputs whose size differs from the canvas are scaled to fit inside it without cropping.

Outside a compositor, the **Composite** node in the Graph does the same job for still images, with the same modes and matching results, including transparent inputs. Composite also has **Edit Composite**, where you move, rotate and scale each foreground layer.

## Blend modes in Merge and Composite

In the formulas, A and B are the foreground and background colour values per channel, and a and b are their alphas. Values are not clamped, so float and HDR values pass through.

| Mode                  | Result                                                 | Typical use                                  |
| --------------------- | ------------------------------------------------------ | -------------------------------------------- |
| **Over**              | A + B × (1 − a)                                        | Standard layering of a premultiplied element |
| **Under**             | A × (1 − b) + B                                        | Put A behind B                               |
| **Atop**              | A × b + B × (1 − a)                                    | Layer A only where B exists                  |
| **In**                | A × b                                                  | Keep A inside B's alpha                      |
| **Out**               | A × (1 − b)                                            | Keep A outside B's alpha                     |
| **Mask**              | B × a                                                  | Keep B inside A's alpha                      |
| **Stencil**           | B × (1 − a)                                            | Cut A's shape out of B                       |
| **XOR**               | A × (1 − b) + B × (1 − a)                              | Show each only where the other is absent     |
| **Conjoint Over**     | Over that treats overlapping alphas as shared coverage | Layers cut from the same matte               |
| **Disjoint Over**     | Over that treats alphas as non-overlapping             | Layers that meet edge to edge                |
| **Matte**             | Mix B toward unpremultiplied A by a                    | Straight-alpha foregrounds                   |
| **Copy**              | A                                                      | Replace with the foreground                  |
| **Add** / **Plus**    | A + B                                                  | Light, glows, fire, flares                   |
| **Minus**             | A − B                                                  | Subtract the background from A               |
| **From**              | B − A                                                  | Subtract A from the background               |
| **Multiply**          | A × B                                                  | Shadows, darkening, applying dirt            |
| **Divide**            | A ÷ B                                                  | Removing a multiplied pass                   |
| **Screen**            | A + B − A × B (Max when either is outside 0–1)         | Soft brightening                             |
| **Overlay**           | Multiply or screen, chosen by B                        | Contrast and texture                         |
| **Hard Light**        | Multiply or screen, chosen by A                        | Strong texture overlays                      |
| **Soft Light**        | W3C soft-light formula                                 | Gentle contrast                              |
| **Color Dodge**       | Brighten B by A                                        | Hot highlights                               |
| **Color Burn**        | Darken B by A                                          | Deep, saturated darks                        |
| **Difference**        | \|A − B\|                                              | Checking alignment or changes                |
| **Exclusion**         | A + B − 2 × A × B                                      | Low-contrast difference look                 |
| **Average**           | (A + B) ÷ 2                                            | Blending two plates equally                  |
| **Geometric**         | 2 × A × B ÷ (A + B)                                    | Averaging that favours the darker value      |
| **Hypot**             | √(A² + B²)                                             | Combining reflections                        |
| **Max** / **Lighten** | Larger of A and B                                      | Keep the brightest                           |
| **Min** / **Darken**  | Smaller of A and B                                     | Keep the darkest                             |
| **Custom**            | Your own expressions                                   | Per-channel control                          |

## Write a custom merge with channel expressions

Set **Mode** to **Custom** to combine inputs with your own maths. Two fields appear: **Colour** (default `A.rgb`) and **Alpha** (default `A.a`).

> **Caution:** In Custom mode the letters change meaning. **A is the background**, and B, C, D and so on are the foregrounds in connection order, up to H. This differs from the blend-mode formulas above.

- **Pick channels** with `.rgb`, `.r`, `.g`, `.b`, `.a`, or combinations such as `.rg`.
- **Colour** must give three numbers, or one number for grey. **Alpha** must give one number.
- **Position and time:** `x` and `y` (pixels, y counted up from the bottom), `u` and `v` (0 to 1), `width`, `height`, `frame` and `time` (seconds).
- **Operators:** `+ - * / ^`, comparisons, `&&`, `||`, `!` and `condition ? a : b`.
- **Functions** include `abs`, `floor`, `ceil`, `round`, `fract`, `sqrt`, `exp`, `ln`, `log2`, `sin`, `cos`, `tan`, `atan2`, `pow`, `min`, `max`, `mod`, `step`, `clamp`, `saturate`, `lerp`, `smoothstep`, `fit`, `luma`, `dot`, `length`, `premult`, `unpremult`, `vec2` and `vec3`.

Inputs in Custom mode are straight (unpremultiplied) alpha, and so is the result. An input the expression reads but nothing is connected to reads as transparent. **Mix** sets how much of the custom result replaces input A. Expressions are limited to 600 characters.

| Goal                                              | Colour                    | Alpha           |
| ------------------------------------------------- | ------------------------- | --------------- |
| Blend B over A using C's red channel as the matte | `lerp(A.rgb, B.rgb, C.r)` | `max(A.a, B.a)` |
| Take red from B, keep A's green and blue          | `vec3(B.r, A.g, A.b)`     | `A.a`           |
| Left half A, right half B                         | `u < 0.5 ? A.rgb : B.rgb` | `A.a`           |

## Set the canvas size

**Canvas size** sets the compositor's frame. New compositors start on **First input**; compositors saved before canvas sizing existed stay on **Custom**.

| Option                                 | Canvas                                                                                                                                                               |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **First input**                        | The dimensions of the first connected input                                                                                                                          |
| **Largest input** / **Smallest input** | The input with the most or fewest pixels; ties keep connection order                                                                                                 |
| **Custom**                             | Your own width and height (1920 × 1080 by default). The first switch to Custom starts from the current size                                                          |
| Presets                                | 720p Landscape · 1280 × 720, 1080p Landscape · 1920 × 1080, 4K UHD Landscape · 3840 × 2160, 1080p Portrait · 1080 × 1920, Square · 1080 × 1080, DCI 4K · 4096 × 2160 |

Automatic sizes use the original media dimensions, including orientation, never a thumbnail's size. While dimensions are loading, the compositor shows **Waiting for input dimensions.** You can also change the size from the compositor's right-click menu under **Canvas size**. Changing the canvas size does not change frame rate, duration or colour settings.

## How does a composite feed generators downstream?

Connect the compositor's output to any node that accepts an image or video. An Image Compositor's **Image** output carries the still; a video Compositor's **Video** output carries the rendered clip and **Preview Frame** carries a still of the current frame. When you edit a composite, downstream generators receive the updated result the next time they run.

Compositing runs in your browser, not on Nodespell's servers. What the compositor delivers depends on its colour settings; see [Color management](https://docs.nodespell.com/edit/color-management/).

## Frequently asked questions

### Does compositing use credits?

Compositor rendering and its effect nodes run on your device's GPU in the browser. Credits apply to AI model nodes, such as a generator you feed the composite into, not to compositing itself.

### Why can't I find some nodes in the Tab menu inside a compositor?

Inside a compositor, the Tab menu shows only nodes that work in compositors. Inside an Image Compositor it also hides time-based nodes such as Retime and Camera Shake, which need a video Compositor.

### Can I animate a Merge or effect inside an Image Compositor?

No. An Image Compositor has no timeline. Convert it to a video Compositor to set [keyframes](https://docs.nodespell.com/edit/keyframes/).

### What is the difference between Merge and Composite?

Merge works inside compositors; Composite works in the ordinary Graph on still images. They share the same blend modes and give matching results.

### Why does the Custom mode use A for the background?

Custom mode names inputs in connection order, starting with the Background as A. The fixed blend modes use Nuke's naming, where A is the foreground.

## Related

- [Masks and keying](https://docs.nodespell.com/edit/masks-and-keying/): build mattes for Merge and effects.
- [Transforms and crop](https://docs.nodespell.com/edit/transforms-and-crop/): position and size layers.
- [Color management](https://docs.nodespell.com/edit/color-management/): working space, viewing and delivery.
- [Keyframes](https://docs.nodespell.com/edit/keyframes/): animate compositor parameters.
- [Viewers](https://docs.nodespell.com/edit/viewers/): inspect the composite in the Design panel.
- [Composite and finish recipe](https://docs.nodespell.com/recipes/composite-and-finish/): a worked example.