Drive parameters with expressions

An expression in Nodespell is a short calculation that sets a parameter’s value, such as blur1.size * 2 or if($F < 24, 0, 1). Expressions link parameters together, so changing one value updates every parameter that reads it, and in compositors they can change over time. The parameter shows the live result in its normal control.

Add an expression to a parameter

1. Select the node and find the parameter in Parameters.
2. Right-click the parameter and choose Use an expression. In a text or number field you can also type = when the field is empty or all of its text is selected.
3. Type in the expression bar. Suggestions list Functions, This node, Nodes, Parameters and Time; press Tab or Enter to accept one.
4. Read the result line under the bar as you type.
5. Press Enter or Cmd/Ctrl+Enter, or select Apply, to save. Press Esc to cancel.

Select Pick a parameter in the bar, then click a parameter in Parameters or a node on the canvas, to insert a reference without typing it. Functions opens a searchable list of every function with examples. Empty expressions offer starters such as Use this node’s own values, Switch on a condition, Keep a value in range and Change over time.

To edit later, right-click the parameter and choose Edit expression…. Hover the expression chip to see its Result, Type and what it Reads, with Edit, Bake to value (replace the expression with its current result) and Remove expression. Show expressions in Parameters switches every row to show its source text instead of its result.

Refer to other parameters and nodes

To read	Write
A parameter on this node	$size
A parameter on another node on the same Level	blur1.size
The node this Level is inside	parent.size
A node one Level further out	parent.parent.blur1.size
A node inside a Group on this Level	group1.blur1.size
A node from the top of the project	root.tex.blur1.size
One channel of a colour	grade1.gain.r, $gain.g
A name with spaces or symbols	"my blur".size, blur1."edge size"

Names are case-sensitive. A reference reads the other parameter’s current value: if that parameter has its own expression, its result; if it is animated, its value at that node’s frame. A parameter driven by a connection cannot be read, because its value is only known when the graph runs.

Time variables

In compositor nodes, five variables describe the current frame. They are not available elsewhere.

Variable	Meaning
$F	Current frame
$T	Current time in seconds
$PERC	Progress through the clip, from 0 to 1
$DURT	Duration in seconds
$DURF	Duration in frames

Values and operators

Expressions work with numbers, text, true/false, colours and lists. Constants are true, false and pi.

Operators	Meaning
+ - * /	Arithmetic. + joins text when either side is text.
%	Remainder, always with the sign of the divisor, so -1 % 4 is 3
^	Power
== != < > <= >=	Comparison
and, or, not (or &&, !)	Logic; or can also be written as two vertical bars
[1, 2, 3], list[0]	Lists and indexing; a negative index counts from the end

Text uses double or single quotes. Colours support + and - with another colour, and * and / with a number, per channel. A single = is an error; use == to compare.

Functions

Function names are lowercase; the editor fixes the case for you.

Group	Functions
Maths	abs sign floor ceil round(x, digits) trunc sqrt pow exp ln log(x, base) mod min max clamp(x, lo, hi)
Angles (radians)	sin cos tan asin acos atan atan2(y, x) degrees radians
Shaping	lerp(a, b, t) fit(x, inLo, inHi, outLo, outHi) smoothstep(lo, hi, x) rand(seed)
Logic	if(condition, a, b)
Text	upper lower trim length replace(s, find, with) contains(s, part) split(s, sep) join(list, sep) pad(n, width) number(s)
Lists	range(n) or range(start, end) first last sum mean sort reverse
Colour	rgb(r, g, b)

Useful details: round rounds halves away from zero; fit stops at the ends of the new range but lerp does not; rand returns a number from 0 up to 1 and the same seed always gives the same number; range(3) is [0, 1, 2]; pad(3, 3) is "003"; rgb values above 1 are allowed.

Worked examples

Goal	Expression
Keep a second blur at twice the first	blur1.size * 2
Match this node’s height to its width	$width
Fade in over the first second of a clip	clamp($T, 0, 1)
Pulse a value once per 24 frames	sin($F / 24 * 2 * pi) * 0.5 + 0.5
Switch at frame 48	if($F < 48, 0, 1)
Number shot names	"shot_" + pad($F, 4)
Use only the red channel of a grade	grade1.gain.r
A fixed random value per seed	rand("hero") * 10

Fix expression errors

When an expression has a problem, the parameter uses its default and the row shows the message. A spelling or reference problem anywhere in the expression stops it from running, even in an if branch that would not be taken.

Message	Cause and fix
“…” is not a node, a function or a value.	A typo or missing node. Use the suggested name if one is offered.
There is no node named … on this level.	References look on the current Level. Use parent. or root. for other Levels.
That node has no parameter named ….	Check the parameter name; hover it in Parameters to see it.
Wrong number of values.	The function takes a different number of arguments; the message shows how it is written.
This expression ends up reading itself.	Two expressions read each other. Break the loop.
$F only works on compositor nodes.	Time variables are only available in compositors.
This reads a parameter that a connection drives.	Read a typed value instead, or connect the same source to this node.
This divides by zero.	Guard the divisor, for example with max(x, 0.0001).
The result is …, but this parameter needs ….	Convert the result, for example with number() or rgb().

Expressions also have limits: 4,096 characters, 64 levels of nesting, lists of 10,000 items and text of 65,536 characters.

Frequently asked questions

Which wins if a parameter has an expression and a connection?

The connection wins, then keyframes, then the expression. An expression that is not in use stays saved and editable, and the row says what is driving the parameter.

How do I turn an expression back into a normal value?

Hover the expression and choose Bake to value to keep the current result as a fixed value, or Remove expression to drop it. Use a fixed value in the right-click menu does the same as baking.

Can I use expressions outside compositors?

Yes. References, operators and functions work in any node’s parameters. Only the time variables need a compositor node.

Does Reset to default keep my expression?

No. Resetting a parameter removes its expression; the message offers Undo if you change your mind.

Related

• Edit parameters: typed values, connections and defaults
• Keyframes: animate values on the timeline
• Compositing: where time variables apply
• Levels and Folders: how parent and root paths work
• Data and logic nodes: calculations as nodes instead of expressions