Repository navigation
Visuals
A VJ rig that reads your set. It runs beside open[flow] rather than inside it — its own window, its own machine if you want one — and draws generated visuals that follow the song, the section and the tracks you are playing.
It is the visuals half of open[flow], the name for this whole set of tools.
There is no second transport and no second launcher. A Live track is a layer and a Live scene is a column, so firing a scene fires a column of visuals because it is firing one.
npm run dev starts it alongside everything else. Then open:
http://localhost:17900 |
the rig — the picture, and everything you use to build one |
w |
send the picture to the projector |
f |
fullscreen this window |
e |
the console, over the picture |
i |
the status panel |
k |
line the projector up |
n |
turn to the next flow without changing the colourway |
1 |
"here is the one" — re-phase the rotation, without changing the picture |
It does not need Ableton to be running. That matters more than it sounds — see below.
Press w. A window with no tabs and no address bar opens on the projector, fullscreen,
and you never touch it again — the browser you were working in stays exactly as it was, with
the panel, the console and the picture still in it.
The first w after installing Chrome asks permission to see your displays, and that press is
spent on the question; press it again and the window opens. After that it is one press, and it
goes back to the display you used last. The status panel (i) shows which one, with a close
beside it.
Plug the projector in after starting the rig and it appears in the panel on its own. If you
have only one screen, or you say no to the permission, w still opens the window — you just
place it yourself.
Then press k and drag the four corners until the grid is square on the wall. The
handles are in this window and the grid is on the projector, so you line it up looking at the
thing you are lining up. Brightness is on the same bar. Both stay on this machine, because
they describe this projector in this room and would be wrong anywhere else.
Everything you can put on screen is a flow, and a flow is a canvas of nodes wired together. One output — the picture — and everything that feeds it is something you dropped on the canvas:
| every playing track | the Live set itself, drawn and mixed. Fire a scene and it changes |
| pictures | plasma, rings, sparks, a tunnel, checker and rays — thirteen lightweight sources |
| field | three bounded procedural algorithms: cells, clouds and metaballs |
| fractal | one bounded iterative picture, with Mandelbrot and Julia modes |
| light | four 2D lights: a lamp, a spotlight beam, sun shafts and water caustics |
| lens | eleven ways to move the point a picture is read at — zoom, fold, kaleido, ripple, slice |
| point and place | where this bit of the frame is, and a spot you name with two numbers |
| grade and spread | the colour where it is (levels, hue, posterize, invert), and the four that read all round it (bloom, smear, edge, shift) |
| Ableton | three nodes: playback (the beat, the bar, the meter), track (one track's level, fader or gate, smoothed as much as you like) and song (its key, tempo and section) |
| other flows | any flow you have made, whole, as one node |
A lens has two outlets, and which one you take is what it is. Take the point and it is
geometry — a zoom in front of a picture. Take the colour and it is an effect — the same
picture, read through the zoom. That is why kaleidoscoping the Live set is one node.
fractal is one node with two modes: mandelbrot and julia. Both take a point and
energy and give back a colour. Turn zoom to move down a bounded logarithmic range, turn
to rotate the plane and detail to choose between 8 and 32 orbit steps. Julia adds shape,
which moves through its family of connected forms. The beat moves the colour rather than
adding calculations, so the picture remains musical at the same rendering cost.
The limits are part of the node rather than suggested settings: there is no supersampling,
the orbit cannot exceed 32 steps and zoom stops before WebGL floating-point precision becomes
fiction. A flow may blend two fractals directly, but the editor refuses to put one underneath
bloom, smear, edge or shift, because those effects would evaluate the whole orbit at
every one of their sample points. Fractals are also absent from the per-track picture chooser,
so eight playing tracks can never turn one iterative picture into eight by accident.
light hangs a light in the frame. lamp is a soft point of light — a hot core over
a halo that dies away square, with carry for how far it throws and soft for how much is
core. beam is a stage spotlight: aim swings it about straight down, spread opens the
cone, and dust drifts through it. shafts fans crepuscular rays down from a hanging point,
with blades for how many streaks and haze for how far they carry. caustics is sunlight
through water — weave tightens the pattern, glint sharpens the flashes where its two
drifting layers cross. The lamp, beam and shafts hang where their from inlet says, so a
place node moves the light around the frame; energy drives only brightness, and the drift
is deliberately in seconds rather than beats — haze and water do not dance in tempo. Like
fields and fractals, each mode's fixed cost is declared to the compiler and lights are never
offered as per-track pictures.
field is the same safety rule for standard procedural algorithms. cells is a
nine-neighbour cellular-distance field, clouds is four fixed octaves of gradient noise,
and metaballs sums between two and seven finite Gaussian fields. Turn balls for the colony
size. apart starts with loose individual orbits, then settles them into a wide evenly spaced
ring at the far end; all seven bodies are visibly separate at maximum. Each mode declares its
maximum work to the compiler: all seven metaballs under a nine-tap bloom cost 63 of the graph's
64 units and still fit. Fields are not per-track pictures, so their hidden loops never multiply
by the number of playing tracks.
The column down the left is two shelves under one search box, and the split is the difference between the two things you can drop.
Flows are on top, one row each, marked ◈ and saying what is inside them — 9 nodes ·
reads the set. That count is the whole point: a source has no answer to "how many nodes",
so a row saying 9 nodes can never be mistaken for a plain picture. Each row does two
things:
- click the name to open it and edit it
-
click
⤵to drop it into the flow you already have open, as a single node
Press new for a fresh one, fork for a copy of the open one to take apart. To
delete a flow, hover its row and press × — the button turns to sure? and a second
press commits, right where you clicked; the tooltip warns if the flow is placed inside
others or pinned by songs. ⤵ is simply missing on any flow that would end up containing
itself, and the last flow cannot be deleted.
The whole column scrolls as one list; the flows and nodes headings hold at the top as their rows pass under. If a search or the port filter empties it, press show everything to clear both at once — Escape clears just the search box.
Nodes are below, one per row. Click the name and you get one. Click the ▸ on the
left and its presets open underneath — click source's and its thirteen lightweight pictures
appear; click field's for the three bounded procedural ones. Each preset drops its node
already set up.
On the right of every row is what it takes and what it gives: p n c → p n c, with the
ones that node has not got greyed out. The colours are the same blue, amber and purple the
ports and cords wear on the canvas, so you can match a colour rather than learn a letter —
p is a point, n a number, c a colour. That is the thing worth knowing before you drop
a node: whether the cord in your hand can reach it.
You can filter by them. The six switches under the search box are the same six positions
in the same three colours. Press the p under takes and the list narrows to nodes that
accept a point; press c under gives as well and it narrows to nodes that do both. ×
clears it. The search box asks what is it called; this asks what will connect.
There is one track row, and you choose which track on the node itself. Its list puts
your groups first, then individual tracks. A group is usually what you want — if you
have five kick tracks inside a DRUMS group, the group's meter is the one number worth
driving a picture from — but every track is there too, so you can take the one snare if
that is what you meant.
Flows are not in the node list, and that is deliberate. They used to be — every flow
appeared down there too, in the same chip as source and paint — so a graph of sixteen
nodes and a single shipped picture looked like the same kind of thing, and the only way to
find out which you had was to drop it.
Every node has the same face: its picture above the frame, its mode in the title, its outlets at the top right, one chooser band and one line per inlet. Press the swap arrows in the title and the browser narrows to that kind's modes; choosing one changes the node you already have rather than dropping another. The chooser band is for the other question a mode cannot answer — which track to read, which flow to draw, or what to call a value.
A flow node wears ◈ in its title, the same mark its row has in the browser, so you can
always tell "a whole flow, in here" from an ordinary node at a glance.
The search box reaches both shelves and reaches inside them — type "spark", "kaleido", "sine wave", a track's name or a flow's name, and drop what comes back.
Wire something into out and it draws. Every unwired inlet has a sensible answer, so a half-finished graph shows you a picture rather than going black — which is the only way these actually get built: drop a node, look at what it did, wire the next one.
Unwired numbers sit on the node itself. A posterize has a steps control on its face;
turn it and the picture changes. You only need a cord when the number should come from
somewhere else — a meter, the beat, one number you want in two places at once. Wire one in
and the same row disables itself and names what is driving it; unwire it and your number is
still where you left it. Its fill and reading keep moving with the number that arrives, at a
display rate that does not make the whole graph redraw every frame. The room's energy and
a wave's live phase are meters instead, because they are moving answers with nothing for
you to drag. A polar radius or angle is different at every pixel, so a row driven by one
names that outlet but shows no made-up number or fill.
The value node in numbers is for that last case: one number, on as many inlets as you wire it to, so turning it moves all of them together.
Out is the one node you do not add and cannot delete. Every flow arrives with exactly one; move it wherever you like, but it is what leaves and a flow without one is not a flow. Until something reaches it, the canvas says so underneath — a flow with nothing wired to out draws nothing, and that line is there so you can tell that apart from a flow that is simply dark.
Changing a node's mode changes its numbers, so any cord with nowhere to go is cut, and
so is any number you had set on one the new mode does not have. A ripple has waves,
depth and speed and a posterize has only steps; anything they have in common —
bloom and smear both have a reach — keeps both its cord and its setting.
A place builds a point out of two numbers, which is the other direction from what the
rest of geometry does: 0 to 1 across the frame in each, a half in each for the middle. Wire
two waves or two track meters into one and you have a spot that moves with the music. It is
the same spot everywhere in the frame, though, so a picture read at a place comes out as
one flat colour — which is exactly what you want when you are after a colour rather than a
picture, and never what you want on its own.
Press ⤢ on a flow node to open it. The flow it draws opens on the canvas and a trail
across the top shows how you got there — click back along it to come up again. Until now the
only way in was to find the flow's name again in the sidebar.
A flow inside a flow can be moved from outside. Wire a point into it and the whole nested flow is read there, exactly as a picture would be, so you can fold, zoom or tile something you already built without opening it.
Every node face shows what that node made, so you can read the canvas along the chain.
lens and polar make two things each. Their outlet names are buttons as well as cord
labels; the amber one is what the little picture shows, and clicking the other changes both
that picture and what you get when you promote it. Nodes with one outlet have no extra
choice to make.
Only the pictures worth seeing are live: visible faces draw, up to ten at once, with the promoted node and out first. A face over the budget, or every face while zoomed far out, holds its last frame and says paused rather than quietly burning the GPU. The live pictures switch beside the node browser pauses them all, and the count underneath says how many are live out of how many are visible. That switch stays on this machine; it does not change the scheme or follow the file to the projector.
The picture floats over the canvas. It is the finished flow, drawn by the same renderer that will put it on the wall. Drag it by its title bar, stretch it by its bottom-right corner, and park it wherever the graph is empty — it stays where you left it, on this machine, next time you open the console.
Click any node's little picture and it takes over the big one. That is how you actually
see what a node is doing without rewiring anything: click plasma, look at it full size,
click whole flow in the title bar to go back. The title bar names the node and turns
amber while you are on one, so you can always tell a node from the finished flow.
Nodes that carry a number or a point have no picture of their own, so what you get is a drawing of the signal — a number as brightness, a point as a plasma read through it. The title bar says so when that is what you are looking at.
You do not have to bind anything. The rig turns through every flow and every colourway you have made, on musical time — by default a new flow every 8 bars and a new palette every 16, plus a change whenever somebody launches a single clip out of band.
That means a set it has never seen still gets a show. Open set to change how often it
turns, or to narrow which flows and colourways it turns through. Press n at any time to
turn the flow once by hand; the projector and console move together, and the colourway stays
where it is.
Those bars are counted from "the one", and the rig has to be told where that is. Link's
beat started whenever the first machine in the building opened, so left to itself an 8-bar
wheel lands on some beat that has nothing to do with the music and stays there all night.
Starting Live's transport sets the one, so a set that stops between songs re-phases itself
for free; press 1 for a set that never stops. Neither changes what is on screen — only
when the next change happens.
Twelve flows come with it, and they are deliberately unlike each other because the fastest way to learn the canvas is to take one apart. Since the wheel turns through everything by default, they are also the show you get before you have made anything:
| Folded | the set and a ring of its own, read through a swirl that sways once a bar, then kaleidoscoped |
| Deep | a tunnel with the set screened into it, wobbling with how loud the room is |
| Weather | no set at all — a glowing disc coloured by the angle around it, under a drifting grain |
| Water | a surface that bends what you see through it, drifting on its own slow time |
| Vortex | a spiral that punches inward on every beat |
| Gateway | a corridor folded into wedges with rings coming up it, mirrored |
| Outline | your set as a diagram — the outlines kept, the fill thrown away, over a grid that always has edges |
| Poster | flat bands of colour over a slow wash, with the shade set by the key the song is in |
| Glitch | rows thrown sideways, blocked, channel-split and inverted on the beat |
| Lava | slow blobs drifting and merging in a lamp, on nobody's clock — the room only fattens them |
| Storm | a dark sky that cracks: forked light on a strike that is never the same size twice |
| The lot | three of the others at once — Water as the wash, Vortex folded into a window over it, and your set's outlines on top |
Three of them are portals and that is on purpose: Deep recedes, Vortex turns and Gateway opens. It is the thing this kind of rig reaches for most.
The lot is the one to open if you want to know what the canvas can do: the three flows in it are three nodes, wired like any other picture. Anything you make can go inside another flow the same way. It is also the heaviest thing here — if a machine struggles anywhere, it will struggle there first.
They are all built to move whether or not Ableton is running, so what you see at a desk is what you will see on the wall with the room quiet.
And they keep going when nothing is playing. Between songs, with only a click running, every one of them still has a picture and still moves in time: the motion comes off the beat and the meters only add to it, and the flows that draw your set have a picture of their own underneath for when no clip is up. There are no exceptions.
On the set page, every song in the running order has two dropdowns: a colourway and a flow. Both say turning until you change them.
Pick a flow and that song plays it instead of turning. Pick a colourway and it draws from that one. Most songs should say turning — an override is how you say "not this one", and every one you add is a thing that stops moving.
The console opens on design, and that is the order the work goes in.
Along the top is the room — every condition a flow reacts to, faked, so you can sit anywhere and make things with Ableton shut:
| playing / bpm / to the top | a clock of your own, so anything wired to the beat is in time |
| energy | how hard the room is going |
| section | intro, chorus, jam — your set's own [ROLE] names when it is connected |
| colourway | which palette the flow draws from |
| key | the song's musical key, for a flow that moves with it |
Turn the section to a chorus and the flow behaves as it will in a chorus. Nothing has to be playing, and you do not have to wait for a rehearsal to reach one.
With no set connected it also draws stand-in tracks, so a flow built on every playing track still shows you something.
Follow the room switches the lot off and draws the real show instead — its beat, its energy, its section, its colourway and its key — once there is a bridge to read one from.
visual[flow] includes a local MCP server for an agent that can speak Model Context Protocol. From the main repository folder, run:
npm --prefix visuals run mcpPoint the agent's MCP configuration at that command. The server lets it read every real node,
mode, inlet and outlet; inspect existing flows; validate a complete draft; and save one flow to
~/.openflow/visuals/scheme.json. The running visuals app follows that file, so an agent-authored flow
appears in the design library like one made on the canvas.
The save tool requires the revision returned when the agent read the library. If you change a flow in the app while the agent is working, its stale write is refused rather than overwriting your edit. It also refuses unknown ports, mismatched cord types, graph loops, recursive flows, missing output nodes and graphs beyond the renderer's limits.
The same server can review a proposal for a new node, including every port and mode description and whether it belongs as a mode of something already there. A node is program code, not scheme data, so that review returns the implementation and test work; it does not silently install a node into a running show.
| design | make flows: a canvas, your library, and every node there is |
| set | how often it turns, which flows it turns through, and the songs that say otherwise |
roll on the set page deals a fresh library from a seed: four new colourways and four freshly wired flows. Write the seed down and you can get that library back later; undo roll covers the one you just did.
Every rolled colourway is five colours in one harmony: two of them loud, one a light tint to read edges against, and always something across the wheel from the base so a wall is never one colour with a gel on it. Lightness is evened out by hue, because a blue and a yellow at the same setting are not the same brightness and it is always the blues that vanish on a cheap lamp.
The three chips beside the button choose how much of it lands. Turn colours off and a roll
keeps the palette you settled on and re-deals the flows. A flow you built by hand is never
touched — only the ones a previous roll wired get cleared.
In ~/.openflow/visuals/scheme.json, in your home directory. It is plain text, so a night
of tuning is something you can read back, diff and keep. Delete it and the built-in show
takes over — the rig always draws something. An older install that kept the file at
visuals/scheme.json inside the repository is picked up automatically: the first start
copies it into place, and the old file is left where it was.
Nothing on screen. Check the status panel with i. It says whether the server is up,
whether the bridge is connected, and whether it has a clock.
Nothing on the projector. Check the status panel with i — if wall offers a send
button, the window is not open. If the browser blocked it, allow pop-ups for the page and press
w again. A window that opened but did not fill the screen fills it when you click on it.
It says "no bridge". The Max device is not running, or Live is not open. The designer still works without it — it draws stand-in tracks so you can keep building.
npm run dev quits immediately. Something is already on one of its ports — usually a
visuals server left running from earlier.