Recipes

The following examples show how nodes are typically composed to create lighting effects. Each recipe includes a connection diagram and an explanation of the data flow.

Basic Beat Pulse

A beat envelope drives a gradient that fades between a color and black on each beat.

Data Flow

1. beat_clock outputs the BeatGrid for the current context.
2. beat_envelope receives the grid and generates a scalar pulse (0 to 1) on each beat, shaped by the ADSR parameters.
3. color provides a constant red RGBA signal, connected to the gradient's end_color input.
4. gradient interpolates between black (at value 0) and red (at value 1) using the beat envelope as the interpolation factor.
5. select resolves a tag expression to choose which fixtures are targeted.
6. apply_color writes the color signal to the selected fixtures.

Key Parameters to Tweak

• beat_envelope.subdivision -- change from 1.0 (quarter notes) to 0.5 (eighth notes) for faster pulses.
• beat_envelope.attack_curve -- set to -1.0 for snappy flashes, +1.0 for slow swells.
• gradient.end_color -- set to #000000 for fade-to-black, or another color for a color-to-color transition.

Spatial Chase

A traveling wave of light moves across fixtures arranged in a line.

Data Flow

1. select chooses the target fixtures (e.g., a row of wash lights).
2. get_attribute(normalized_index) assigns each fixture a value from 0.0 to 1.0 based on its position in the selection order.
3. beat_clock feeds ramp, which produces a monotonically increasing beat count (0, 1, 2, 3...).
4. math(subtract) subtracts the ramp from each fixture's index. This creates a value that decreases over time per fixture -- effectively a traveling wave.
5. modulo(1.0) wraps the result into the [0, 1) range, making the chase repeat every beat.
6. falloff shapes the transition. A narrow width creates a tight moving dot; a wide width creates a broad sweep.
7. gradient maps the shaped scalar to a color.
8. apply_color writes the result to the selected fixtures.

Key Parameters to Tweak

• falloff.width -- controls how many fixtures are lit simultaneously. Lower = tighter chase.
• falloff.curve -- -1.0 for sharp edges, +1.0 for smooth fades.
• get_attribute.attribute -- try angular_position for circular chases, rel_x for left-to-right sweeps.

Music-Reactive Strobe

Isolates the kick drum from the audio and triggers full brightness on strong hits.

Data Flow

1. audio_input provides the full audio mix.
2. stem_splitter separates it into drums, bass, vocals, and other. The drums_out port is used.
3. frequency_amplitude analyzes the drums stem in the 20-200 Hz range (kick drum frequencies), outputting an amplitude envelope.
4. threshold(0.8) converts the continuous amplitude into a binary trigger: 1.0 when the kick is strong, 0.0 otherwise.
5. select targets the desired fixtures.
6. apply_dimmer sets the dimmer to the binary signal -- full brightness on kick hits, off otherwise.

Variations

• Use [2000, 8000] for hi-hat reactive effects.
• Replace threshold with falloff for smoother amplitude-following behavior.
• Connect to apply_strobe instead of apply_dimmer to trigger strobe on kick hits.

Circular Chase

A rotating point of light sweeps around fixtures arranged in a circle.

Data Flow

1. select(circular) targets fixtures tagged as circular (e.g., a ring truss).
2. get_attribute(angular_position) uses PCA + RANSAC circle fitting to assign each fixture an angular position from 0.0 to 1.0 around the fitted circle. This works even for 3D arrangements.
3. beat_clock feeds ramp, producing a monotonically increasing beat count.
4. math(subtract) subtracts the ramp from each fixture's angular position, creating a rotating wave.
5. modulo(1.0) wraps the result so the chase repeats every beat.
6. falloff(width=0.3) shapes the beam width. At 0.3, roughly 30% of the circle is illuminated at any moment.
7. apply_dimmer writes the intensity to the selected fixtures.

Key Parameters to Tweak

• falloff.width -- controls the arc length of the lit section. 0.1 = narrow beam, 0.5 = half the circle.
• falloff.curve -- -1.0 for hard edges, +1.0 for soft fading.
• Use angular_index instead of angular_position if the circle fit is unreliable (angular_index uses equal spacing by selection order).

Harmonic Color Wash

Colors follow the song's chord progression, creating a wash that shifts hue with the harmony.

Data Flow

1. audio_input provides the audio for the current pattern context.
2. harmony_analysis extracts a 12-channel chroma distribution from pre-computed chord analysis. Each channel represents a pitch class (C through B), and the values represent relative strength at each time step.
3. chroma_palette maps the chroma distribution to an RGB color using a fixed pitch-to-color palette (C=Red, D=Orange, E=Yellow, G=Cyan, A=Blue, etc.). The output is a weighted blend of all 12 colors.
4. select targets the desired fixtures.
5. apply_color writes the harmonically-derived color to the selected fixtures.

Variations

• Add spectral_shift after chroma_palette to apply additional hue rotation based on the dominant pitch.
• Connect harmonic_tension to apply_dimmer to make the lighting intensity increase during dissonant passages.
• Use gradient instead of chroma_palette for a simpler two-color mapping driven by tension.