Patches

A cable takes something the music is doing (the bass, the beat, a build, a slow clock, even another layer) and uses it to turn one knob. Patches is where you connect them. Pro

Making a cable

The window has sources on the left, a lane in the middle, and every knob of every layer on the right (plus the scene's colors). Each source and each knob has a small circle, its port.

Drag from a source's circle to a knob's circle. A cable appears between them, in the source's color.
Tap the cable (or tap a row's name) to open its settings: how much it moves the knob, how smoothly, and how it is shaped.
Drag a cable's end to another circle to move it.
To remove a cable, open it and tap the trash, then tap again to confirm. On a Mac, select it and press Backspace.

A knob can take several cables; their effects add up. Press and hold (or hover over) any name for a short help text. Only knobs marked "Cable: yes" on the Elements page can be targets.

Tip. Elements already react to the music on their own, so you rarely need a cable on every knob. One or two purposeful cables per layer beat ten.

What a cable does

Tap a cable to see its small graph (the source in faint, the result in bright, the last 3 seconds) and these settings:

Setting	What it does
Amount	How far the cable moves the knob, as a share of the knob's whole range, from -1 to 1. Negative moves it down. The knob's own slider is the starting point; the cable adds to it. (Not shown for Numbers and Time sources, which set the knob directly.)
Smooth	How slowly the knob follows, in seconds (0 to 3). 0 follows every jump. About 0.05 to 0.15 suits hits, 0.2 to 0.6 suits bass and pulses, 1 to 3 suits slow drifts.
Curve	Reshapes the 0-to-1 signal before it reaches the knob. See below.
In from, In to	The part of the source that counts. Values at or below In from become 0; values at or above In to become 1. Raise In from to ignore quiet passages.
Threshold	Appears for the Threshold and Gate curves: the level (0 to 1) the signal has to pass.

Curves

Curve	Shape
Linear	The signal as it is.
Invert	Flipped (1 minus the signal): loud becomes quiet.
Ease	A soft S; gentler at the ends.
Exp	Quiet parts get quieter: waits, then leaps.
Log	Quiet parts get louder: leaps, then settles.
Threshold	A soft step: off below the level, on above it.
Gate	0 below the level; above it, the signal itself.

A color knob works a little differently. A number source moves it along a list of colors: the layer's own palette, else the scene colors, else round the color wheel. Amount 1 at full signal travels the list once round; 0.25 moves a quarter of the way. A color source (see Colors) blends the knob toward that color by Amount. A switch is on while the cable's signal is above one half.

All the sources

Sources come in groups, in this order in the window. Every value runs from 0 to 1 unless noted.

Group	What is in it
Music	Bass, mid, treble, level, energy, onset, beat, beat phase, bar phase, transition, thin.
Bands	Slices of the spectrum, from deep bass to the highest treble.
Song structure	Section, build, drop, downbeat, progress, harmony, tension, chord root, melody.
Random	Smooth or stepped random values.
Colors	The moving palette color, a scene color, the color under a layer.
Layer outputs	Signals other layers publish, such as a burst.
Layers below	How bright, colorful or busy the layers underneath look.
Numbers	Steps on the beat or bar, in the knob's own units. You type these.
Time	Gates, ramps, saws, triangles and sines over seconds of the song. You type these.

Music, live

These work with everything: songs, radio, the microphone and This Mac.

Source	Value
`bass`	How loud the low end is (kick drum, bass). Fast.
`mid`	How loud the middle is (voices, guitars, keys).
`treble`	How loud the top end is (cymbals, hi-hats, air).
`level`	Overall loudness right now, smoothed over about a tenth of a second.
`energy`	Slow loudness over about 3 seconds: high in choruses and drops, low in quiet parts. The best source for big, gentle changes.
`onset`	Spikes on sudden hits (drums, plucks, attacks). For flashes and kicks.
`beat`	1 at the moment a beat lands, else 0. Give the cable some Smooth (0.1 to 0.3) to make a pulse instead of a click.
`beatPhase`	Ramps from 0 to 1 over each beat, then starts again. Steady pulsing.
`barPhase`	Ramps from 0 to 1 over each bar of four beats. Slow, locked turns.
`transition`	Rises from 0 to 1 while one song crossfades into the next.
`thin`	0 for the full mix, up to 1 when the music thins out: the drums or bass drop away, a break, or just a voice and a pad. Slow and smooth. Use it to open a scene up when the song gets sparse. It reads the whole song once analyzed (it can see a quiet part coming); until then, and on radio before the analysis catches up, it works from the last half minute of sound and reacts only after the music thins. It sees the low end, the loudness and how many bands are lit, so it does not notice a lone kick being removed while a sustained bass stays.

Bands

The spectrum is split into 64 bands: band 0 is the deepest bass (about 30 Hz) and band 63 the highest treble (about 16 kHz). A bands source averages a run of them, each scaled to its own recent range so quiet bands still move. The window offers 12 ready ones; to use another run, ask for it in a scene file (bands:A-B).

Source	Covers
`bands:0-7`	Deep bass
`bands:0-3`, `bands:0-15`	The deepest four bands, and the lowest quarter of the spectrum
`bands:16-39`	The mids
`bands:40-63`	The highs
`bands:8-15`, `16-23`, `24-31`, `32-39`, `40-47`, `48-55`, `56-63`	Eight even slices, low to high

Song structure

These need Nebula to know how the song is built: your own songs once Nebula has analyzed them (see How Nebula hears a song), and radio songs it has heard ahead of or remembers. They stay at 0 until then, and with the microphone.

Source	Value
`section`	How intense the current part of the song is, easing toward the next part as it nears. Changes when the song moves to a verse, chorus or bridge.
`build`	Rises as the music builds toward a big moment.
`drop`	Jumps when a build releases into a drop or big chorus, then fades.
`downbeat`	1 on the first beat of each bar.
`sectionProgress`	0 to 1 through the current part.
`songProgress`	0 at the start of the song, 1 at the end.
`harmony`	Brighter, major-sounding chords read high; darker, minor ones low.
`tension`	High when the chord is far from the song's home key: the music feels unresolved.
`chordRoot`	Which chord is playing, as its root note, 0 to 1 round the twelve notes.
`melody`	How high the sung or lead melody is, 0 low to 1 high.
`melodyConfidence`	How sure the analysis is that someone is singing or a lead is playing.

Random

Source	Value
`random:smooth`	A value that glides to a new random one every beat, never jumping. The same song gives the same values.
`random:smooth/bar`	The same, one new value every bar.
`random:smooth:7`	The same with seed 7. Another number gives another pattern. Seed 1 is the default.
`random`	Jumps to a random value in the knob's range on every beat. Use Smooth to soften the jumps.
`random/bar`	The same, every bar.

With no tempo (for example the microphone) random:smooth keeps going at two values a second.

Numbers (steps on the beat)

A Numbers source counts through numbers you choose, one per beat, and sets the knob to that number directly, in the knob's own units. Amount is not used. Type the source into the Numbers box in the window (for example 1-5:1) and it appears as a row you can wire.

Syntax

You type	What it does
`1-5:1`	Steps 1, 2, 3, 4, 5, then back to 1, one per beat.
`0-1:0.25`	0, 0.25, 0.5, 0.75, 1, then again.
`1-5:1/bar`	The same, one step per bar (four beats) instead of per beat.
`0-1:random`	A random value between 0 and 1 each beat (any value in between).
`1-5:1:random`	A random step each beat: only 1, 2, 3, 4 or 5.
`0-1:random:7`, `1-5:1:random:7`, `random:7`	The same with seed 7: another seed, another pattern. The same seed always repeats.
`random`	A random value across the knob's whole range each beat.
`0-1:random/bar`	A random value each bar. Add `/bar` to any of them.

Details: the form is low-high:step, optionally followed by :random (random steps), :seed (a whole number) and /bar or /beat. If you write the range backwards (5-1:1) Nebula flips it. The step must be above 0 and give no more than 1000 values. A source can be at most 64 characters, and spaces are ignored.

In the window, Numbers you made show an Edit and a ×. Edit changes the source and keeps its cables on their knobs; the delete removes the source and its cables.

Tip. Numbers are great for knobs that take whole steps, such as the number of emitters, and for switching a look every bar.

Time (seconds of the song)

Time sources change over seconds of song time, not beats. They also set the knob directly (Amount is not used). Type them into the Time box. The window starts you off with 0-1:gate/4s,4s, 0-1:tri/30s and 0-1:ramp/30s.

Shape	You type	What it does
Gate	`gate/3s,7s`	On for 3 seconds, off for 7, repeating. Two lengths: on, then off.
Ramp	`ramp/20s`	Glides from the low value to the high one over 20 seconds, then holds there. `ramp/0s` is an instant jump.
Saw	`saw/20s`	Climbs from low to high over 20 seconds, snaps back and repeats.
Triangle	`tri/30s`	Up and back down once every 30 seconds, in straight lines.
Sine	`sine/45s`	The same up-and-back cycle, smooth at both ends.

Options

A range. Put low-high: in front, for example 0.2-0.8:tri/30s. Without one, the source uses the knob's whole range. A high-to-low range such as 1-0:ramp/20s is kept, so it runs downward.
A late start. Add @30s at the end, for example 0-1:gate/3s,7s@30s or ramp/20s@10s. Until then the value is the low one.
Lengths are 0.1 to 3600 seconds, each ending in s. Only a ramp may use 0s.
A whole example: 0.3-1:gate/2.5s,12s@45s is off (0.3) for the first 45 seconds, then on (1) for 2.5 seconds out of every 14.5.

How the clock runs

Song time stands still when the music is paused, follows you when you jump around the song, and starts again from 0 with each new song. A scene change does not restart it.

Tip. Time sources are good for slow scenes: fade a layer in over a minute with ramp/60s, let a color drift with tri/90s, or flash a layer for a few seconds every half minute with a gate.

Colors

Source	Value
`colour:scene`	The moving palette color: the color every palette-mode visual is at right now.
`colour:scene:3`	Scene color 3 (the numbering starts at 1, up to 12), including any cable on it.
`below:2:rgb`	The average color of everything under layer 2.

Into a color knob, a color source blends the knob toward that color by Amount. Into any other knob it gives the color's lightness.

Layer outputs and layers below

Layer outputs. Some Elements publish a signal, such as Fireflies' burst. It is listed under the Element on the Elements page. In a scene file it is layer:<number>:<output>, counting layers from the top, starting at 0. Wire layer:1:burst into another layer's brightness and it flashes with the swarm.

Layers below. These look at what the layers beneath a layer produce:

Source	Value
`below:<n>:brightness`	How bright the layers beneath layer n look.
`below:<n>:colour`	How colorful they are.
`below:<n>:motion`	How much they are changing.
`below:<n>:0.5,0.5`	The brightness at one point of the picture (x then y, 0 to 1; 0,0 is the top left). The window offers the center.

The bottom layer has nothing beneath it, so it has no Layers below sources.

The math

For a number knob:

knob = base + amount × shaped value × (knob max − knob min)

The result is kept inside the knob's range. Base is where you set the knob's own slider, and shaped value is the source after In from / In to and the curve. So a knob that should rise with the music needs a base low enough to leave room: Pin height runs from 0 to 2, so a base of 0.6 and an amount of 0.4 can rise to 1.4. Several cables on one knob add up.

Numbers and Time sources skip this: they put the knob at their value directly.

Recipes

Starting points; adjust to taste. "Wire" means drag from the source to the knob.

Goal	Source → knob	Settings
Bass swell	`bass` → a size or height knob	Amount 0.15 to 0.3, Smooth 0.25
Flash on hits	`onset` → glow or brightness	Amount 0.2, Smooth 0.1, Curve Gate, Threshold 0.3
Chorus lift	`energy` (or `section`) → brightness or density	Amount 0.3, Smooth 2, In from 0.3, In to 0.9
Build-up and drop	`build` → a speed or swirl knob; `drop` → a burst or ripple knob	Build: Amount 0.4, Smooth 0.5. Drop: Amount 0.5, Smooth 0.2
Mood color	`harmony` → the scene's Color shift	Amount 0.3, Smooth 3. Minor chords slide the palette one way, major the other.
Slow life in quiet songs	`random:smooth/bar` → a drift or swirl knob	Amount 0.15, Smooth 2
Change a look every bar	`1-4:1/bar` → a knob with whole steps	Amount does not apply
Fade a layer in over a minute	`0-1:ramp/60s` → a layer's opacity-like knob such as brightness	Amount does not apply
A glow for 3 seconds every 30	`0-1:gate/3s,27s` → glow	Smooth 0.5 to soften the edges

In a scene file

Scenes are saved as .nebula files, and cables are written in them as text. This is useful if you let an AI assistant write a scene for you, or edit one by hand. A cable looks like this:

{ "source": "bass", "target": { "layer": 0, "key": "height" },
  "amount": 0.25, "smooth": 0.2, "curve": "ease", "range": [0.1, 0.8], "threshold": 0.5 }

target.layer counts layers from the top (0 is the top layer), or is "scene" for the scene colors (shift, speed, colour1 and so on). range is the same as In from and In to. Source names are the ones on this page. A cable whose source can't be read, or whose layer or knob doesn't exist, is skipped without a message. See Scenes › The .nebula file.