Node Reference

Luma's pattern graph is a dataflow system where nodes are connected via typed ports to produce time-varying lighting output. This reference documents every available node type: its inputs, outputs, parameters, and behavioral details.

Port Types

Data flows between nodes through typed ports. Understanding these types is essential for building valid graphs.

Signal Dimension Conventions

• N (spatial): One value per fixture or spatial point.
• T (temporal): One value per time step. Typically SIMULATION_RATE * duration frames.
• C (channels): Data channels. 1 for scalar, 3 for RGB, 4 for RGBA, 12 for chroma, etc.

Node Categories

Input Nodes

Inject external data into the graph: audio streams, beat timing, and user-defined pattern arguments.

• audio_input -- Provides the audio segment for the current pattern context.
• beat_clock -- Provides the beat grid (BPM, beat positions, downbeats).
• pattern_args -- Exposes user-defined pattern arguments as output ports.

Audio Nodes

Transform audio signals: splitting stems, filtering frequencies, and extracting rhythmic envelopes.

• stem_splitter -- Separates audio into 4 stems (drums, bass, vocals, other).
• frequency_amplitude -- Extracts amplitude in selected frequency bands via FFT.
• lowpass_filter -- IIR lowpass filter.
• highpass_filter -- IIR highpass filter.
• beat_envelope -- Generates ADSR envelopes triggered at beat positions.

Analysis Nodes

Extract musical features from audio and present them as signals.

• harmony_analysis -- 12-channel chroma distribution from chord analysis.
• harmonic_tension -- Musical tension/dissonance via Shannon entropy.
• mel_spec_viewer -- Mel spectrogram for editor visualization.
• view_signal -- Debug node for signal visualization.

Selection Nodes

Extract spatial attributes from fixture arrangements. Fixture targeting is handled by the pattern's Selection argument (a group expression set when placing the pattern on a timeline), not by a node in the graph.

• get_attribute -- Extracts spatial or ordering attributes from fixtures.
• random_select_mask -- Randomly selects N items from a Selection on trigger.

Color Nodes

Generate and transform color signals.

• color -- Constant color generator.
• gradient -- Maps scalar input to a color range.
• chroma_palette -- Maps 12-pitch chroma to RGB via weighted palette.
• spectral_shift -- Rotates hue based on dominant pitch in chroma signal.

Signal Nodes

Mathematical operations, waveform generation, and signal timing/shape manipulation.

• math -- Element-wise binary math with broadcasting.
• round -- Rounding operations (floor, ceil, round).
• threshold -- Binary step function.
• normalize -- Min-max normalization to [0, 1].
• falloff -- Non-linear attenuation with adjustable width and curve.
• invert -- Reflects values around the midpoint.
• scalar -- Constant scalar value.
• ramp -- Linear beat counter.
• ramp_between -- Linear interpolation over pattern duration.
• modulo -- Modulo operation (positive remainder).
• sine_wave -- Continuous sinusoidal oscillator.
• remap -- Linear range remapping.
• noise -- 3D fractal Perlin-like value noise.
• time_delay -- Per-fixture time offset with interpolation.
• orbit -- Elliptical 3D circular motion.
• random_position -- Random 3D point held until trigger changes.
• smooth_movement -- Rate-limited pan/tilt simulating motor speed.

Position Nodes

Compute aiming angles for moving lights.

• look_at_position -- Computes pan/tilt to aim fixtures at a 3D target point.

Output Nodes

Terminal nodes that produce lighting output for the compositing system.

• apply_color -- Sets fixture color and brightness.
• apply_position -- Sets moving light pan/tilt angles.
• apply_strobe -- Sets fixture strobe/shutter effect.
• apply_speed -- Sets gobo/pattern rotation speed.

Recipes

Common pattern recipes showing how nodes compose into real lighting effects.