VISUALSOUND is a modular instrument where audio and visuals live on the same canvas. Oscillators sit next to fluid simulations, a sequencer can play a filter or a kaleidoscope, and the same LFO that breathes through your delay can breathe through your colors. Signal flows left → right, always.

There are no pages, no hidden menus, no mode switches between "making sound" and "making image". You patch, it plays. The canvas zooms from the whole show down to a single knob, and everything you see — every cable, every meter, every glow — is the actual signal, live.

Six kinds of signal

• Audio — sample-rate sound. Oscillators, samplers, effects, the master OUT.
• Control — slower signals that play knobs: LFO, envelopes, sequencers, MIDI, math.
• Visual — GPU textures flowing between generators and effects, ending at VOUT.
• Geometry — 3D shape flowing between sculpting nodes, rendered by the LENS (see 3D Geometry).
• Data — words, numbers and flags at tick rate: SCRIBE writes them, TEXT reads them (silver cables).
• Notes & gates — pitch and trigger streams riding the control domain (SEQ, ARP, MIDI, VOICES).

Each domain has its own cable color, and ports only accept matching cables — the patch stays honest by construction. Audio reaches the visual world through one gate only: the FFT bridge (see Cables & Domains).

Sound

• Tap the + button (bottom right) and add an OSC, a FILTER and an OUT.
• Drag from OSC's output port to FILTER's in, then FILTER's output to OUT.
• Press PLAY in the header. Drag the cutoff bar on the FILTER — the sound follows your finger.

Movement

• Add an LFO. Cable its output into FILTER's cut port — the cutoff now breathes on its own.
• Add a SEQ and cable note → OSC note. Open its editor (the ≡ chip on the node) and draw a phrase.

Light

• Add an FFT, a PLASMA and a VOUT.
• Cable OUT's source (or the FILTER output) into FFT in, FFT out into PLASMA's warp inlet, PLASMA into VOUT.
• The canvas background ignites — the plasma is now dancing to your filter.

That's the whole grammar: sources → processors → OUT for sound, generators → effects → VOUT for image, and control signals played into any port that will take them. The rest of this manual is depth, not new rules.

Moving around

Editing

On every node

• Power LED (top-left): tap to bypass. Audio passes through clean, everything else mutes; the node dims under a veil. Saved with the patch.
• Editor chip (≡ or </> top-right): opens the node's dedicated editor — SEQ, KINETIC, GRANULAR, WTABLE, REEL, AURIS, LUMEN, SCRIBE, NOTES.
• ? chip (just left of the editor chip — on EVERY node): the node's full inline manual — what it does, every inlet, outlet and parameter explained, and a TRY THIS patch. For deep help on any module, the ? is always the shortest path.
• Param bars: drag horizontally to set, double-tap to reset to default — the app-wide law.
• Chips (dropdown values): tap to open the picker; discrete values switch instantly, no zipper.
• SPARK nodes put a playable button right on the node face — tap fires a gate, or flips a toggle.

Probes

Double-click any cable to spawn an inspector right where you clicked: audio cables show a live waveform, control cables a numeric readout, visual cables a texture thumbnail. Probes ride with the patch until you close them.

Grid & snap

The dotted working grid keeps large patches tidy; SNAP quantizes node positions to it. When a VOUT drives the background the grid politely hides — the visuals own the stage. (You can bring the grid back at any time with the visuals-off button, next chapter.)

Every port has a domain, every cable takes its color from its source, and connections only land where the domain matches. Thick cables carry textures; audio cables that go stereo draw as a twin strand so you can read the signal path at a glance.

Stereo

STEREO merges two mono signals into one stereo cable; GRANULAR, KINETIC, SAMPLER, LOOPER and the big effects (DELAY, REVERB, PITCH, FREEZE, RESONATOR) are stereo by nature. Stereo-ness propagates through processors automatically — GAIN on a stereo signal stays stereo, and the twin strand shows it.

The FFT bridge law

Audio never plugs straight into a visual port. It crosses through FFT — an analysis bridge with gain, band select (FULL / LOW / MID / HIGH), attack, release, floor and invert. That shaping is what makes visuals playable: a loud mix doesn't pin everything at maximum, a kick can hit only the low band, and an inverted envelope can carve darkness into light.

…and the reverse gate

The loop closes the other way through SONIFY: a texture scanline becomes a single-cycle wave — light drives sound. Point it at a LUMEN, feed its output back through the FFT, and the patch listens to what it paints.

Control into anything

Every audio node carries control inlets for its main parameters — cutoff, drive, mix, threshold, level… — and every visual node has one control inlet per knob. A patched control signal adds to the knob, clamped to its range: the knob sets the center, the signal plays around it.

PORTAL — wireless cables

PORTAL▸ transmits, ▸PORTAL receives: same channel + same type = a connection with no cable drawn, working across subpatch boundaries and in every domain, textures included. For big patches and clean stages.

Left cluster

• Logo — tap for About.
• Undo / Redo — whole-patch snapshots; continuous gestures (a knob drag, a node move) coalesce into single steps.
• Marquee · Arrange · Fit · Grid · Snap — canvas tools; active tools glow teal.
• New canvas — a clean slate (your current patch stays in Presets if you saved it).
• Preset pill — the current patch name; the amber LED means unsaved changes. Tap to open the library.

Tempo & transport

• Tempo stepper — tap the number to type an exact tempo (40–240); the stacked arrows step ±1 BPM, and holding one accelerates. In a DAW (AUv3) the host owns the tempo and this becomes a readout.
• Beat dot — flashes on the beat, from the transport clock, not from audio.
• PLAY — starts the engine and rewinds the musical clock to bar 1: loops, synced LFOs and sequencers all start in phase. The chip lights teal while playing.

Record & perform

• REC — records the session: audio always, video when a VOUT is live. Long-press for offline bounce (master 4/8/16 bars, or stems per OUT). See Recording & Export.
• MIDI — MIDI-learn mode: tap a knob, move a controller CC, done. Amber while armed.
• MOT — motion record: your knob gestures loop over 4 bars. Long-press to clear all loops.
• LINK — arms the remote bridge: iPhones on your Wi-Fi become stage controllers. The chip counts connected remotes. See VS Remote.
• tv.slash — hide the visual output and work on modules + grid; visuals keep running offscreen.
• sparkles.tv — installation mode: visuals full-screen, zero chrome. Esc or tap to come back.
• CPU meter — app CPU, Activity-Monitor scale (100% = one core). Green under 50, amber under 100, red above.

SOURCES 14

MODULATION 9

FILTERS 2

SHAPING 6

EFFECTS 8

MATH 7

CODE 3

STRUCTURE 4

WIRING 15

MIXING 8

BRIDGE 2

VISUAL 36

GEOMETRY 12

OUTPUT 1

THE REAL EDITOR

SEQ is a 16-step generative sequencer built around one idea: key and character are separate controls. ROOT and MODE are set once, in the editor's key menu; the ten VARIATION moods change everything else — progressions, sevenths, chord rhythm, melodic contour, register, hit density — computed in degree space, so two SEQs in the same key can never clash.

The editor

• Pitch grid — draw degrees; colors mark chord roles (root / 3rd / 5th / 7th / passing). Tap toggles a step, drag draws.
• RATCHET lane — 1–4 retriggers inside the gate window, per step.
• CONDITION lane — fire always, every 2nd loop, every 4th, or on the FILL pass.
• Chord track — when harmony is on, tap a card to repick the chord; the playing card lights up.
• New phrase — regenerates the melody inside the current mood. Same key, new sentence.
• Evolve — the machine plays itself: every N bars the phrase mutates by the amount you set.

Outputs

POLY — one timbre per chord voice

Flip POLY on the node face and the progression that was already playing under your melody becomes patchable: c1…c4 carry the chord's voices, cgate fires at every chord change. Patch each voice into a different instrument — c1 → OSC, c2 → WTABLE, c3 → FM, c4 → KARPLUS — and one envelope on cgate plays them as a single ensemble. The melody keeps running on note/gate, a fifth voice on top.

• Voice-leading (LEAD): each voice moves to the chord tone nearest its previous note — chords glide, and your timbres migrate through the harmony. CLOSE / OPEN / SPREAD force classic dispositions instead.
• Both layers at once: stabs come from gate (step rate), pads from cgate (chord rate) — no mode switch, just patch both.
• Custom chords: every card in the harmony track takes a quality — sus2, sus4, add9, 6th, quartal, power, cluster — or four hand-set tone offsets. All in degree space, so custom chords stay in key; on the CHROM scale the offsets become semitones and anything goes.
• Triads on four voices double the root an octave up — a patched timbre never goes silent.
• Harmony off + POLY on = unison ×4: four timbres, one line.

THE REAL EDITOR

Eight pads (BD SD CH OH CP RS CB CY), a classic analog-style kit synthesized on load, your own samples on any pad, and a step sequencer that goes far beyond on/off. The closed hat chokes the open one. It's the law.

Pattern length — up to 64, any number

LEN runs from 1 to 64 — any value, not just multiples of 16. The grid pages 16 steps at a time; page chips appear past 16, with a white dot tracking where the playhead is running. Odd lengths against 16-step material are instant polymeters: try 23 against a SEQ and let it drift.

Per-step layers

Sound & mixer

• Per pad: LVL, TUNE (±12 st), DECAY, START, PAN, CUTOFF with LP/HP filter, REVERSE — all on orange knobs, double-tap resets.
• The MIXER page is a classic console: per-pad fader + pan, levels also exposed as node params (so scenes and MIDI learn can play them).
• Single outs: each pad has its own output port, PRE or POST the internal mixer — feed a pad to its own effect chain.
• External control: note picks a pad (60 + pad), gate retriggers — play KINETIC from SEQ, ARP or MIDI.

Kits

The machine has its own bank: factory grooves plus your kits (pattern + pad settings + imported audio, saved as one preset). Imported samples ride inside the kit file.

THE REAL EDITOR

GRANULAR scatters windowed grains over a sample and plays the cloud as an instrument. Feed it a note stream and it becomes a pitched voice; leave it free and it's a texture engine.

The editor

• Waveform theatre — zoom, pan, set the trim region by dragging its edges; the active region is what the cloud grazes.
• Slices — drop markers; slice mode walks them as scan anchors.
• Audition — preview the sample (or a slice) through the master, even with the transport stopped.
• Destructive tools (normalize, reverse) keep your slice markers where they belong.

Ports

THE REAL EDITOR

A wavetable oscillator: single-cycle frames of 2048 samples, swept through with POS (knob or CV — an LFO on morph makes the timbre travel while you play). Empty, it ships with eight built-in shapes; the editor makes the table yours.

The editor

• Import standard wavetable WAVs (2048-frame files land as-is).
• Draw frames by hand and reprocess them — the strip shows every frame, the morph path is what POS travels.
• NOTE in plays it like any voice; DETUNE in semitones on the face.

THE REAL EDITOR

Import a clip and REEL turns it into a playable machine: the video is transcoded once to an all-keyframe proxy (every jump lands instantly) and analyzed — scene cuts and audio onsets become markers, markers make slices, and the clip's own audio is sliced in sample-sync with the picture.

Modes

The editor

• Zoom — pinch, or the − / FIT / + chips; keyframes and waveform re-render for the window you're in.
• Preview transport — play/stop the clip through the master, fully detached from the patch: position markers with the sound in your ears.
• Marker flow — click the timeline to place the edit cursor, hit SET MARKER to plant one; drag markers to move, drag them out of the lane to delete.
• AUTO row — CUTS (scene changes), ONSETS (audio transients), GRID n, CLEAR: all STAGED — nothing touches the engine until ✓ MARKERS.
• ✦ VISION — content markers, computed on demand and cached: FACES (a face appears, moves, leans in) and SUBJECT (the scene changes meaning, not just brightness).

Performance ports & outs

THE REAL EDITOR

AURIS is the node that speaks GRAIN AUDIO — VISUALSOUND's own DSP language, created by Mike Gazzaruso. You type signal math; the node compiles it live into a bytecode program that runs on the audio thread — 48 000 times a second, allocation-free, glitch-free.

//! name: My First Grain
inlet level = 0.8;
out1 = in1 * level;
out2 = in2 * level;

Why it matters

• param lines become real knobs on the node face; inlet lines add control ports — LFOs and envelopes modulate your code at audio rate.
• buf delay lines survive live recompiles: edit the code while the echo rings, the tail keeps ringing.
• The LIBRARY chip loads six complete factory effects — Tape Echo, Cathedral, Dream Chorus, Liquid Flanger, Lo-Fi Crusher, Cosmic Comb — each a readable lesson.
• Scripts export/import as .grain text files. Share them anywhere.

Strict, like a stage

An AURIS that doesn't compile shows a red border and blocks Play — the last good program keeps running meanwhile, and the error points at line and column. No half-broken shows.

And the language doesn't stop at sound: LUMEN runs the same GRAIN code once per pixel on the GPU, SCRIBE once per tick over words and values — the next two chapters.

The full language reference — every keyword, operator, function, buffer command and recipe — is one tap away:

LUMEN is a visual node that speaks GRAIN. The exact same language — same knobs, same math, same compiler — but the program runs once per pixel, every frame, on the GPU. Type a line, see light. Keystroke to pixels is one live recompile: this is an instrument you can live-code on stage.

inlet glow = 0.6;
let cx = x - 0.5;
let cy = y - 0.5;
let d = sqrt(cx * cx + cy * cy);
r = (0.5 + 0.5 * sin(d * 28 - t * 3)) * glow + bass;
b = (1 - d * 1.4) * glow + high * 0.5;

What changes from GRAIN

• param and inlet work exactly as in GRAIN: knobs on the node face, control ports on the node — an LFO plays your code.
• Audio-only pieces (in1/out1, sr, buf) are clear compile errors: the editor tells you what to use instead.
• The LIBRARY chip ships eight looks — Aurora, Scanlines, Neon Rain, Stardust, Warp Lens, Meter, plus Pump Zoom and Edge Fire, which drive the tex AND audio inputs together.
• LUMEN has a texture input (for pick) and an audio input (for the bands) — it's a generator and an effect.

Light, not sound

A broken LUMEN never blocks Play. It wears the red border and keeps rendering the last good look while you fix the line — the strict rule protects the stage, and pixels aren't the stage's heartbeat.

The full reference — with a dedicated visual-context section — is one tap away:

SCRIBE is the third body of GRAIN. It runs about 30 times a second on the main thread — far from the audio path, which is why it can do what the other two can't: strings. It reads your signals (data, control, notes, gates, audio features) and emits DATA — text, numbers, flags — on silver cables.

state word = "READY";
word = rise(gate) ? notename(note) : word;
out1 = word + "  ·  " + format(bpm, 0) + " BPM";

The set, solved

Wire o1 into a TEXT node's text port and whatever string you compose replaces the text on screen, live — the playing note by name, the bar counter, a peak readout, a message that answers another SCRIBE. No pre-written lines: the text is computed.

Ports

• param/inlet work exactly as in AURIS and LUMEN — same knobs, same additive law.
• state persists between ticks and can hold TEXT: counters, peaks, the last word seen.
• The LIBRARY ships Note Ticker, Peak Meter and Bar Counter — three readable lessons.
• A broken SCRIBE never blocks Play: last good program keeps ticking, red border while you fix it.

The full GRAIN DATA reference is one tap away:

THE REAL EDITOR

The Geometry domain is a fourth cable type: violet ports that carry shape, not sound or pixels. Geometry nodes never render anything themselves — they describe a 3D scene as pure mathematics (signed distance fields), and one node turns it into image: LENS, the camera. Everything upstream of a LENS is sculpture; everything downstream is ordinary visual signal, so BLOOM, FEEDBACK, KALEIDO and the whole 2D chain work on 3D for free.

The modules

Two minutes to liquid 3D

• Add two FORMs (make one a CUBE), a MELD, a LENS and a VOUT.
• Cable FORM → MELD a, FORM → MELD b, MELD → LENS geo, LENS → VOUT.
• Drag the forms' x apart, then raise MELD's k — watch them fuse like mercury.
• Cable an FFT into MELD's k inlet: the music now welds the geometry.
• Cable an LFO into LENS orbit: the camera circles your sculpture on its own.

Sound in, shape out

Every geometry parameter has a control inlet — the same law as everywhere else: CV adds to the knob, clamped to its range. The LENS also has a REACT knob (audio pulses light, glow and a subtle dolly-push) and an audio input: wire a signal there and any TERRAIN in the scene grows spectrum ridges — your mix becomes a mountain range scrolling under the camera.

Materials & color

• PRISM — every FORM wears its own hue; MELD blends colors where shapes fuse.
• CHROME — iridescence from the surface normal, tinted by the LENS hue.
• MONO — one hue for everything: the sculpture as a single material.

SUBPATCH

• Select two or more nodes and hit GROUP — they collapse into one box; cables through the boundary become INLET / OUTLET pass-throughs automatically.
• INLET / OUTLET nodes define the box's ports (top-to-bottom order); their dropdown sets the domain.
• Double-tap the box to enter it — the breadcrumb bar tracks where you are. Subpatches nest freely.
• EXPOSE a node inside and its params appear on the box face, grouped under its name, in its color — with the editor chip riding along for SEQ/AURIS/KINETIC.

Wiring utilities

Scenes

• Eight pads in the footer. Hold to store the current knob state, tap to recall.
• Recalled while playing, scenes morph in time: the chip cycles CUT / 1 / 2 / 4 / 8 bars. Continuous params glide, discrete ones switch at the halfway point. Stopped = instant.
• Stored pads show a lit LED; the active pad glows solid. Scenes save with the preset.

MIDI learn

Arm MIDI, tap any knob (canvas bars included), move a controller CC — bound. The map is per-preset; tapping a bound knob in learn mode unbinds it. Bindings resolve to the actual engine parameter, so they keep working inside subpatches.

Motion record

Arm MOT and play: every knob gesture is recorded into a dense 4-bar loop (8 samples per beat) and replays on the transport clock. Touch the knob again and your hand takes over; release and the loop resumes. Long-press MOT to clear everything.

Installation mode

The sparkles.tv button (or the Settings toggle, for launch-time) hides every scrap of interface and gives the room to the visuals, at full brightness. Tap or Esc brings the cockpit back. With autoplay on, the piece starts itself — gallery-ready.

A LIVE SESSION, IN THE HAND

Run VisualSound on an iPhone and it becomes a remote controller for the instrument on your iPad or Mac — same app, same Wi-Fi, no extra hardware. Blackout the interface with installation mode, give the projector the whole canvas, then walk the room and play every exposed parameter from your pocket.

Linking up

• On the host (iPad/Mac): arm LINK in the header. The chip shows how many remotes are on the line.
• On the iPhone: open the app — hosts on your Wi-Fi appear by name. Tap one to connect.
• Several phones can join at once; the last touch wins on any control.

Exposing modules

• With LINK armed, select any module and tap EXPOSE TO REMOTE in the footer — its params land on every connected phone, grouped under the machine's name, with real values and real units.
• Exposed modules wear a small teal ring next to their power LED.
• The exposed set is remembered per project: close and reopen the session, the phone finds the same surface.

Playing from the phone

• Faders — continuous params are full-width horizontal faders: drag left/right to play, up/down still scrolls the page. Double-tap resets to default, as everywhere.
• Chips & toggles — tap cycles an option (long-press for the full menu); toggles flip on tap.
• Transport — start/stop the set, roll a recording, arm motion record and step the tempo, all from the phone.
• Scenes — the host's eight PERFORM pads ride along: recall (and morph) the whole show from across the room.
• Long-press a module's nameplate to choose which of its params show on the surface.

DECKs

A DECK is your own arrangement of the surface: which modules, in what order, with which params visible. Decks are saved on the phone, bound to the host project, and every edit saves itself — they reappear whenever that project is loaded. Each session opens on ALL (everything exposed, host order); build a deck from the menu when the show has a shape.

Live capture

• REC captures the master, sample-accurate, straight from the audio engine.
• When a VOUT is live, video records too — timestamped from the audio clock, so image and sound can never drift.
• Stop → one shareable file: a .mov with both, or a .wav for audio-only takes. The share bar slides up when it's ready.

Offline bounce

• Long-press REC: Master at 4, 8 or 16 bars — rendered offline, faster than real time, bar-exact.
• Stems: one file per OUT node. Name your OUTs, get named stems.

Patch as text

Presets export and import as .vspatch files — the whole canvas as JSON, embedded samples included. Mail a patch, version it, post it. The preset browser has both buttons.

MIDI in

• The MIDI node turns your controller into patch signals: note + gate/velocity CV, port and channel selectable on the node.
• VOICES unpacks polyphony: four voices, four note+gate pairs, oldest-note stealing — wire four OSCs and play chords.
• MIDI learn (header) binds CCs to any knob — see Performing.

Microtuning

Tuning is global: every pitched module — oscillators, samplers, strings, FM, resonators — resolves notes through one table. In Settings, pick 12-TET, any EDO from 5 to 96, or import a Scala .scl file (cents and ratios both supported, one degree per semitone from middle C).

Settings

• Power Saver — drops the canvas to 30 fps when truly idle. The moment you touch anything, full rate.
• Autoplay — the transport starts itself at launch.
• Installation at launch — boots straight into the full-screen visual stage.
• LUMEN half resolution — renders LUMEN nodes at half size and upsamples; off by default, relief for older iPads.
• Tuning — the global microtuning table (previous chapter).
• macOS: Settings live under ⌘, — iPad has the gear in the header.

Inside a DAW

• VISUALSOUND ships as an AUv3 on Mac and iPad — the full canvas inside your host.
• The host owns tempo and transport: BPM becomes a readout, the beat clock follows the project, synced LFOs and sequencers land on the grid.
• The entire patch saves inside the project file — reopen the session anywhere and the canvas is exactly where you left it.

Performance honesty

The CPU meter reads like Activity Monitor: 100% = one core. The audio engine is lock-free and allocation-free by design; the canvas culls what you can't see and sleeps when nothing moves. If the meter climbs, it's the patch working — not the paint.

Canvas

Editing

Performance

Everywhere