Visual Node Graphs & Node Reference Manual

Unilighter features a powerful visual programming engine called Node Graphs. They let you build custom lighting logic, audio-reactive effects, procedural sequences, and parameter macros using visual wiring instead of writing code.

🧠 Concept & Signal Processing Architecture

A Node Graph is a continuous signal processing chain where data flows from left to right:

[ Input Node ] ──(Data Wire)──> [ Process Node ] ──(Data Wire)──> [ Output Node ]
(Audio / LFO / Fader)           (Math / Sequence / Delay / Gate)  (Physical Fixture / Tagged Device)

• Real-Time Processing: The graph evaluates in sync with the console frame clock (40+ times per second).
• Live Editing: You can connect, disconnect, or reroute wires dynamically during a show without interrupting the DMX output.
• Scalar & Sequence Data: Ports can carry single numbers (scalars) or ordered numeric arrays (sequences). Sequence-aware nodes process spatial spreads and chasing offsets across multi-fixture tags natively.

Live port values

To display current input and output values beside node ports, open Settings → General → Global Settings and enable Show node port values.

This local application setting is off by default and is remembered across sessions. Displaying live values may increase system load. In Developer mode, port values are always shown, regardless of this switch. Unconnected numeric inputs keep their editable value fields.

Manual numeric fields leave room for decimal and negative values beside their step buttons. Typing applies on Enter or when leaving the field; Escape cancels the draft. Arrow keys and step buttons apply immediately. See numeric entry for the shared editing behavior.

🧭 Organizing and Editing the Canvas

The graph editor includes layout tools for keeping large shows readable while they remain live:

• Frame containers group related nodes visually. Select one or more nodes and click Frame Selected to create a frame that fits them, or add a frame from Add Node → Layout → Frame. Drag a frame header to move its children together, use the corner handle to resize it, double-click the title to rename it, and use the color swatch to distinguish sections.
• Reroute points keep long cables tidy without changing the signal. Double-click a cable to insert a reroute at that location. Its compact input and output ports pass Number, Sequence, and Audio data through unchanged.
• Double-click the empty interior of a frame to open Add Node at that location. The new node automatically becomes a child of that frame. Double-clicking its header still renames the frame.
• Drag a node into a frame to make it a child of that frame. Deleting a frame leaves its children in the graph; deleting the frame and its children together removes the whole group. Copy, paste, and duplicate preserve frame membership and internal connections.
• Connected inputs can be replaced by dragging from the compact port or by using click-to-click connection mode. The active port is highlighted while you choose the other end, and double-clicking a reroute port disconnects it.
• The add-node popup focuses Search nodes automatically on desktop but does not open a touch keyboard automatically on mobile devices. Type a node name, use Up and Down to highlight the previous or next match, and press Enter to add the highlighted node. The highlight wraps around the matching results. Escape clears the search first and closes the popup when it is already empty. Selected nodes use a clear outer glow, which helps when working in a dense graph.

While searching, combined nodes appear as individual ready-to-use variants: Fader, Fader + Buttons, Knob, Buttons, Dropdown, Frequency Meter, Frequency Split, Device, and Device Tag. Type Kno and press Enter to create a Knob immediately, or type tag to create a Device node with Tag mode selected. Matches starting with your query appear first within their category, so Buttons selects the button bank before Fader + Buttons. Click any other result, or highlight it with the keyboard, to add that variant instead.

Search can also create a Math node with its operation already selected. Type Multiply or Custom Equation and choose Multiply (Math) or Custom Equation (Math); searching Math lists all 15 operations. Creation results omit formula examples. With an empty search, Math remains one compact entry and creates an Add node.

Sequence, Oscillator and Router offer the same direct creation workflow. For example, search for Pack XY (Sequence), Random (Oscillator) or Auto (Router). Search the node type to list all its variants: 13 Sequence operations, six Oscillator waveforms or two Router selection modes. The unfiltered entries retain Manual, Sine and Switch as their respective defaults.

Clearing the search restores the compact category menu. Frequency Meter creates the parametric analyzer; Frequency Split creates the same node in Fixed mode with eight frequency bands. You can still change display or analysis modes on the node afterward. The popup moves upward when opened near the bottom edge and keeps its fitted position while you hover or use the keyboard. If the full list is taller than the window, use its scrollbar or mouse wheel to reach the remaining nodes.

These tools change the graph's presentation and wiring only; they do not add processing or interrupt the graph's live output.

⚡ Enabling & Disabling Node Graphs

Open Node Graphs → Graphs to start or stop a graph directly from its card with the On / Off button. The button displays the current state: click Off to start the graph, or On to stop it. This leaves the list open; click the graph's name or the rest of its card to open the editor.

The editor toolbar and the Node Graph Widget also provide On / Off buttons. They share the same graph state, so changing it there updates the list. Internal Group graphs follow their parent; the Subgraphs tab manages reusable definitions rather than independent playback.

• Enabled: The graph is active and streaming data to fixtures or virtual parameters.
• Disabled: The graph stops evaluating and releases its hold on the fixtures.
• Safety Rule: When using the AI Assistant Panel to restructure a graph, make sure to disable it first to avoid sudden flashes or erratic movements on stage.

Graph priority

Set Priority in the editor's top toolbar to choose the graph's place in the control priority stack. It defaults to 0. New Device Output nodes inherit this value for both individual fixtures and tags, including nodes inside nested Groups.

Changing the priority of a running graph updates inheriting Device nodes even when their input values are constant. A Function Widget can temporarily override this value when it launches the graph. That launch priority stays in effect until the graph stops; editing the saved graph priority does not replace it. Enable Custom priority on a Device node to give that output its own priority, which also takes precedence over a widget override. Existing projects keep their previous per-node priorities with this switch enabled; turn it off when you want a node to follow the graph.

Inside a Group editor, the toolbar displays the inherited priority with From main graph and is read-only. Change it in the outermost graph, or use a Device node's own override. The unwired Device Control node retains its separate control behavior.

📦 Node Graphs as Reusable Functions

Node Graphs run as independent logic blocks in the background:

• You can create multiple graphs per project, handling different tasks (e.g., one for strobe generation, another for a continuous pan/tilt sweep).
• Because they are registered as Functions, you can map them to a Function Widget on your Dashboard to easily toggle them on and off during a live performance.

🔌 Socket Data Types

Nodes use color-coded sockets to indicate the type of data they send and receive:

📚 Node Reference Manual

Functional nodes are divided into Input, Process and Output categories, with layout nodes and modular Subgraphs.

1. Input Nodes (input)

Input nodes sit at the beginning of your graph to generate or capture control signals.

🎙️ Audio Input (AudioNode)

Captures live audio from your system (microphone or line-in) and performs real-time Fast Fourier Transform (FFT) analysis. You can pick the exact audio interface to listen to, adjust the input gain for quiet signals, and add smoothing so the lights don't jitter too aggressively.

It provides a raw Audio FFT output for frequency analysis and an Audio RMS output for overall signal level. The RMS Meter and Spectrum displays can be toggled independently, and the spectrum includes readable frequency and level guides.

Example: Wire Audio FFT into a Frequency Meter Node, then send the selected band's RMS through a Gate Node to the intensity of your wash lights so they pulse to the kick drum.

Read the dedicated Audio Input Node Manual.

🎨 Color (ColorNode)

Provides an interactive color wheel right on the canvas. It outputs a standardized color signal that downstream fixtures can understand, regardless of whether the physical light uses RGB, CMY, or a color wheel.

Example: Connect this node's output to a group of moving heads to quickly change the ambient stage color by dragging your mouse around the wheel.

🎚️ Fader / Knob / Dropdown (ValueNode)

Creates a manual control interface on the canvas. You can configure it to display as a vertical fader, a rotary knob, a dropdown list, or a group of toggle buttons.

• Fader & Knob: Perfect for continuous numerical values. You can specify the exact Min, Max, and Step size.
• Dropdown & Buttons: Allow you to define explicit text labels mapped to specific numerical values (e.g. "Slow" = 0.2, "Fast" = 0.8).

Example: Add a rotary knob to control the sweep speed of an oscillator, giving the lighting operator a clear visual control to tweak during the show.

🕹️ XY Pad (XYNode)

Gives you a 2D touch surface with a crosshair that outputs X (horizontal) and Y (vertical) coordinates.

Example: Wire the X and Y outputs to the Pan and Tilt inputs of a spotlight. This effectively turns the XY Pad into a virtual joystick to manually aim the light across the stage.

🌊 Oscillator (OscillatorNode)

Generates repeating mathematical waves used for continuous motion or chasers. It can run freely in Hertz or lock to the show's master BPM.

• Shapes: Sine, Sawtooth, Square, Impulse, Triangle, Noise.
• Output Mode: Can output a Single Value for unison movement, or a Sequence array (based on a spread and sequenceLength) to create chasing offsets across multiple fixtures.
• BPM Sync: Can sync to fractions from x16 (extremely fast) down to /16 (very slow).
• Control Sockets: Sequence control inputs (Frequency, Phase, Spread) remain scalar to produce clean one-dimensional wave series.

Example: Send a slow Sine wave to the Tilt channels of your moving heads to make them slowly sweep up and down in the background.

🌐 Shared Values (SharedValuesNode)

Allows you to read global variables that are shared across your entire project. Shared values support scalar numbers, sequences (number-array), polymorphic Number or Sequence, and audio data.

Example: If you want multiple independent node graphs to react to a single "Master Speed" fader or a shared procedural sequence pattern, you can bind them all to the same Shared Value instead of building a massive, cluttered single graph.

2. Process Nodes (process)

Process nodes manipulate, combine, transform, or filter signals before they reach the fixtures.

➕ Math (MathNode)

Takes one or two input numbers and performs arithmetic, bounding, range remapping, or custom JavaScript mathematical equations.

MathNode is numeric-polymorphic:

• Scalar Math: When every input is scalar, the result is scalar.
• Sequence Math & Broadcasting: When any input is a sequence, the output is a sequence whose length matches the longest input sequence. Scalar inputs automatically broadcast to all elements, while shorter sequences repeat cyclically. If any connected sequence is empty, the result is an empty sequence.
• Custom Equations: Evaluated per element with variables a, b, min, max, fromMin, fromMax, toMin, toMax, i (current element index), n (result sequence length), and seq.<name> exposing full normalized input sequences.

Read the dedicated Math & Expression Node Manual.

🔢 Sequence (SequenceNode)

Generates, resizes, and structurally transforms numeric sequences up to 64 elements long. Scalar inputs are automatically treated as single-element sequences. Every operation exposes both the calculated Sequence array and a single Item extracted via the cyclic Item Index input.

Available Operations:

• Manual: Direct editable, reorderable list of numbers saved within the graph.
• Fill: Repeats a single scalar value up to the requested length.
• Range: Produces evenly spaced values between Start and End, inclusive.
• Concat: Joins sequences A and B into a combined sequence.
• Reverse: Flips element order from back to front.
• Rotate: Cyclically shifts elements by a signed integer Offset.
• Resize (Cycle): Truncates or cyclically repeats values to target length (ideal for repeating fixture clusters).
• Resample: Resizes sequence using nearest-neighbor sampling while preserving endpoints.
• Interpolated Resample: Resizes with smooth linear interpolation (ideal for stretching short curves across tag fixture counts).
• Mirror: Symmetrically mirrors elements without duplicating the center ([a, b, c] becomes [a, b, c, b, a]).
• Seeded Shuffle: Deterministic Fisher-Yates shuffle where identical input and seed guarantee reproducible ordering.

⏳ Delay (DelayNode)

A stateful numeric delay line providing a single scalar Value input with two simultaneous outputs:

• Delayed: Emits the historical scalar value from Delay steps ago.
• Sequence: Emits a tapped sequence [current, value(-Delay), value(-2*Delay), ...] spanning Length taps (1–64). Perfect for driving tagged fixtures with trailing wave offsets.

Clock & History Modes:

• Updates Clock: Advances history on every incoming value change/request delivered to the socket.
• Frames Clock: Samples input once per console frame clock tick, allowing single transients to continue propagating across taps even when input stops updating.
• Warm-Up Modes: Zeros (initializes history with zero) or First Value (primes history with first received sample).

🚪 Gate (GateNode)

Acts as a dynamic envelope filter and peak trigger with Attack and Release timings.

• Polymorphic Signal Processing: Accepts either a scalar number or a sequence on Signal In.
• Per-Element Envelope State: When fed a sequence, envelope tracking and Attack/Release filtering are maintained independently for each fixture element.
• Scalar Controls: Threshold, Attack (ms), and Release (ms) remain scalar for uniform envelope shaping.

Read the dedicated Gate & Envelope Follower Node Manual.

🔀 Splitter (SplitterNode)

Sends Value to one of several outputs selected by Switch. With Disable inactive branches enabled, unselected branches release their device control while animation clocks keep running. Use it to select different fixtures or processing variations from one state control.

Read the dedicated Splitter Node Manual.

🔀 Router (RouterNode)

Selects one of several inputs and forwards it to a single output. Switch selects by index; Auto takes the first active connected input, ignoring inactive alternatives. Connect the variations from a Splitter to Router in Auto mode to control the entire pipeline with one selector. Number, Sequence, Number or Sequence, and Audio signals are supported.

Read the dedicated Signal Router Node Manual.

📊 Frequency Meter (FrequencyMeterNode)

Analyzes the raw audio spectrum and isolates a highly specific frequency band (Min Freq to Max Freq). In Parametric mode, the selected window is highlighted on the spectrum. Fixed mode provides eight bands with adjustable crossovers, automatic distribution for the incoming FFT resolution, and 0–6 dB/oct spectrum slope choices (4.5 by default). The spectrum guides and output labels follow the selected band shift.

Example: Connect this to the Audio FFT output of an Audio node, dial it in to 40-100 Hz, and route the result to your strobe lights. They will now flash precisely when the sub-bass hits, ignoring the rest of the music.

Read the dedicated Frequency Meter Node Manual.

👥 Group (GroupNode)

A local Group contains an editable node graph with named inputs and outputs. Choose Make Shared to turn it into a Shared Subgraph whose common logic is reused by several graphs, with separate instance parameters and state.

The linked version after conversion:

⏱️ BPM & Audio Tempo Clock (BpmNode)

Estimates a repeating musical grid from timestamped audio analysis independently of graph frame rate.

• Master Tempo and Phase: Control tempo allows a confidently acquired grid to gradually steer the project clock. Response ranges from cautious locking to rapid Provisional tempo following; the default is 25% · Careful. Provisional estimates steer tempo before beat phase is confirmed.
• Hold Tempo or Follow Phase: Stable/Careful holds the accepted tempo until a change is freshly confirmed. Sync beat phase is enabled by default; switch it off to follow tempo only, accepting possible drift from the audio beat.
• Separate Outputs: Clock provides musical pulses with the selected fraction; Transient reports audio attacks. Historical mixed Trigger connections remain supported.
• Selected Frequency Band: The detector defaults to a 40–200 Hz attack band, with 40–4000 Hz rhythmic context. Its main tracker normally uses eight seconds, extending history for minimum tempos below 60 BPM; Fast also uses a short recent window. Ambiguous or sparse music may require manual TAP.

Read the dedicated BPM & Audio Tempo Node Manual.

3. Output Nodes (output)

Output nodes route processed signals to fixture channels or global parameters.

💡 Device (DeviceNode)

Maps node logic directly to physical fixture parameters or tagged device groups.

• When bound to a tagged device group, feeding a Sequence to a channel socket (such as Dimmer or Pan) distributes each array element directly to the corresponding fixture head in the tag.

🎛️ Device Control (DeviceControlNode)

A high-level node for triggering presets, macros, and global parameter overrides across devices.

4. Layout Nodes (layout)

Layout nodes organize the canvas without changing the signal values.

🖼️ Frame (Frame)

A frame is a colored, resizable container for related nodes. Creating one around a selection automatically adds padding and records the selected nodes as its children. Moving the frame moves unselected children with it, while dragging a child into another frame updates its membership. Frames have no input or output sockets.

↪️ Reroute (Reroute)

A reroute point has one input and one output and supports Number, Sequence, and Audio signals. It simply forwards the received value, so it is useful for bending a cable around a node, splitting a complex graph into readable sections, or reconnecting a cable without moving the source and target nodes. Double-click an existing cable to place one automatically at the clicked point.

5. Subgraphs & Function Interface Nodes

Encapsulates complex node chains into reusable, modular building blocks with custom inputs and outputs.

🧱 Group Inputs & Outputs (GroupInputsNode / GroupOutputsNode)

• Group Inputs Node: Declares exposed parameter sockets supporting Number, Sequence, Number or Sequence, and Audio.
• Group Outputs Node: Streams calculated scalars, sequences, or audio back to parent graphs.
• Encapsulated Scope: Internal math equations, delay buffers, and envelope states remain cleanly contained inside the subgraph.

Local Groups keep their own contents. Shared Subgraphs reuse one definition across graphs, with separate parameters and runtime state for each instance. Open Node Graphs → Subgraphs to manage them, or select nodes and choose Create Shared Subgraph.

Read the dedicated Subgraph Interface Manual.

⚡ Typical Signal Flow Recipes

# 1. Procedural generative chase across tagged lights
Oscillator (Sequence) ──> Math (Clamp / Map Range) ──> Device (Tag Dimmer)

# 2. Dynamic trailing wave from a single control or fader
Value / Oscillator (Single) ──> Delay (Tapped Sequence) ──> Device (Tag Dimmer)

# 3. Custom curve resampled to match fixture count
Sequence (Manual / Range) ──> Sequence (Interpolated Resample) ──> Device (Tag Pan)

Movement and packed per-fixture controls

The Movement node produces Pan/Tilt patterns with a live preview, BPM synchronization, per-fixture homes and limits, spread, fan, mirroring, blocks, groups and wings. Connect Single Value to one device or Sequence to a fixture tag.

Sequence now includes Pack and Pack XY, making several manual values or XY pads available as per-fixture inputs. Tagged Device nodes also expose supported miscellaneous channels, such as Pan/Tilt Speed.

Reuse and deletion

Combo Functions can coordinate an existing graph with scenes and animations. Deleting a graph with usages lists its linked controls and memberships. Keep the cleanup toggle off to retain references and assignments, or turn it on to remove those usages while retaining unrelated functions and group containers.