🎹 gridi

readme

Route based midi generation.

quickstart

npm start

http://localhost:8080

Web MIDI needs a secure context, so use localhost or https. Any static server works; there is nothing to build.

It is published from main to https://bobbymeyer.github.io/gridi/, which is the secure context the browser wants and the copy the embed below loads. That needs Pages switched on once, under Settings → Pages → Build and deployment → Source: GitHub Actions; the workflow cannot do it for itself.

npm test

embedding

gridi builds itself into an element, so it can run somewhere that is not its own page — a note on bobbymeyer.com, for instance.

// Before the import, so the module does not start itself against #app.
window.__gridiEmbedded = true;
const { initGridi, destroyGridi } = await import('https://bobbymeyer.github.io/gridi/src/main.js');

initGridi(element, {
  embedded: true,        // theme the mount, not the host page's <html>
  mark: false,           // drop the lockup, keep the transport
  storagePrefix: 'note:' // its own patch, not the one you are working on
});

destroyGridi();          // stops the clock, the audio and the MIDI ports

Every lookup is scoped to the mount, so an embedded copy cannot collect the host page's elements. Its stylesheet is a whole application's worth of chrome though — a * reset, rules on html, body — so mount it in a shadow root and let the two documents keep their own styling. tests/embed.html does exactly that, and is the check that neither side reaches the other.

Give the mount a height. gridi fills it, and lays itself out to the width it finds there rather than the window's, so the same copy works in a column of text and on a phone.

Embedded, gridi waits to be clicked into before it answers the keyboard, the wheel or a paste, and lets go the moment you click out — a reader is reading, and a figure that swallows space, ⌘S and the scroll wheel has taken the page over. On its own page it takes all three from the start.

The SoundFont it ships with is thirty-two megabytes, and it is fetched on the first press of play rather than on load, so a page that merely mentions gridi costs its readers nothing.

Open http://localhost:8080/tests/audio-check.html for the synth checks, which need a browser.

the grid

A grid cell is worth a note value. A pulse crosses one cell in that much musical time, so a line's length is how long its pulses take to walk it. Moving a node retimes the patch.

The field is ruled in three weights: light for the cell, medium for the beat, heavy for the bar. They follow the grid setting.

Select a line to read its length in cells and what that comes to in beats.

nodes

Pulse

MIDI In

Split, Logic, Chance, Router

Note

Voice

LFO

An LFO is patched into a Param node, which sends the value. Note, Voice, Logic, Chance and Router ignore waves; Split, Key and Param act on them.

Param

Key

lines

A line carries state, not just a connection.

Scales: Major, Nat Minor, Harm Minor, Mel Minor, Dorian, Phrygian, Lydian, Mixolydian, Locrian, Maj Pent, Min Pent, Blues, Whole Tone, Chromatic.

Degree overflow: Extend carries past the end of the scale into the next octave, Fold wraps inside one octave, Clamp stops at the top.

library

Library is the second tab in the header, and it is the patch's tab as well as the shelves': the patch's name and what can be done to it — new, demo, keep, save, open, sounds — sit over two rows of patches. Picking one opens it like any other patch, undo included, and the row stays where it is, so the shelf is still there to try the next one from.

ships with is the five below, each with what it is. Copy on one puts it on the row underneath under a name of its own — "Bossa Nova copy" — and leaves the canvas alone, because copying is not opening.

yours is what this browser has been asked to keep. Keep puts the patch on the grid there, under whatever it is called; keeping it again under the same name replaces it, which is what saving twice means anywhere else. Rename edits the name in the cell it is in, and takes the patch's own name with it; renaming onto a name already on the shelf is refused rather than allowed to overwrite it. Remove takes one off, and asks first, because that is the one thing here that undo cannot reach. They live in this browser's local storage and nowhere else — no account, no sync, gone with the site data. Save is still how a patch leaves the machine.

Gridi opens on Bossa Nova out of that library, so a first visit arrives at a patch doing the thing the app is for rather than at an empty grid. Demo is the other starting point: a patch of built-in voices, which needs no SoundFont to make a sound.

The figures the percussion patches use, in sixteenths from the downbeat:

Drum voices are pinned with a chromatic line rooted at C, so a Note node's degree is a General MIDI note number and the key never moves them.

Which drum matters as much as which hit. General MIDI's standard kit has a mute surdo and an open one at 86 and 87, a cuíca at 78 and 79, a cabasa at 69 and a pair of timbales at 65 and 66 — a samba played on a low tom and a tambourine instead is a drum kit doing an impression of a bateria, which is what this one used to be. The cavaquinho is General MIDI's banjo, its nearest neighbour.

what keeps them moving

Every one of these patches hangs a few LFOs off the side of itself, wired to nothing that sounds. Each drifts one number on one node — a clock's velocity, a Chance node's odds, the rotation of a Euclid figure — and because they are wired to nothing, they cannot move anybody's timing.

Velocity is the one worth understanding. A SoundFont routes it to filter cutoff as well as to loudness, so a part played at one velocity is not merely undynamic: it is one timbre, from the first bar to the last. That is what made these sound like a demonstration rather than like playing. A CC sweep is no help — a controller goes out of the MIDI port and straight past the player built into Gridi, which reads a font's velocity and key routings and nothing else.

The shape is drift, which eases between hashed values instead of coming round: the twentieth bar is not the fourth, and the same seed gives the same twentieth bar every time. Rates that share no factors — one bar against two against four — mean the parts are never in the same place twice. Rendered for a minute and a half, every channel of every patch now plays at between twenty and seventy velocities, and no bar is an exact repeat of an earlier one; both are checked in tests/library.test.js.

Patches live in patches/, listed in patches/index.json. Add one by saving a patch into that folder and adding a line to the index. The ones that ship were built by the scripts in tools/, because an offset is a distance and solving several of them is arithmetic:

node tools/build.mjs

soundfont

Gridi ships with GeneralUser GS 2.0.3 by S. Christian Collins, and fetches it on the first press of play. 261 instruments and 13 drum kits in 32MB — too much to spend on somebody who has not asked to hear anything yet, which is what loading it on boot spent.

https://www.schristiancollins.com/generaluser

His licence is in soundfont/LICENSE.txt, unaltered. It permits use in software projects and redistribution, and asks that nobody link directly to his download files — which is why the copy is in this repository rather than fetched from his site. If you get use out of it, buy him a coffee.

Drop any other .sf2 on the canvas to play through that instead.

Velocity goes through the font rather than around it: it reaches loudness and filter cutoff by the routings the font carries, so an instrument gets darker as well as quieter as you play softer.

Samples are decoded when a preset is first played and kept after, so a thirty-megabyte font costs the file plus the few sounds a patch uses.

With no font at all, Note nodes audition through a single triangle oscillator. That is a click track for building a patch, not an instrument.

sounds

Sounds, on the library tab, lists the channels a patch plays on, worked out from the graph, and sets a General MIDI program for each. Gridi sends them as program changes 50ms before the first note, so a receiving module is on the right sound before it has anything to play.

Bank select is not sent, so a module with more than 128 sounds needs its bank chosen on the device.

What the library asks for:

Ambient also sends CC 74 from an LFO, which is filter cutoff by convention.

patches

A patch is one JSON file: nodes, lines, tempo, grid, key. Name it on the library tab; Save names the file after it, and Keep puts it on the shelf there under the same name.

Opening replaces the canvas and goes on the undo stack. ⌘Z puts back what was there.

Files are stamped "app": "gridi". Anything that is not a patch is declined, not opened. Files saved before the stamp are recognised by their shape and still open.

Device bindings are not in the file. A patch names output slots A–D; each machine binds its own devices.

MIDI

Every control below is on the MIDI in & out tab, the second of the two in the header.

Outputs are named slots. A patch stores the slot letter; each machine binds its own devices, remembered between sessions.

Sent: note on, note off, control change, program change, clock at 24 PPQN, start, stop, continue, song position.

Received: clock, start, stop, continue, song position, note on.

On a single channel, note length is capped by the retrigger rate — two instances of one pitch on one channel cannot overlap. Use different pitches or channels.

controls

New, Demo, Save, Open and Sounds sit with the patch name on the library tab. The theme toggle is in the footer, with the level and the counts: what is app-wide rather than about this patch or the machine it is played on. The transport — play and the bar count — is the rule between the settings and the grid, and holds nothing else. Patches autosave to local storage.

Embedded in someone else's page, every key and the wheel above waits until the app has been clicked into, and stops again when it is clicked out of.

limits

Past these, Gridi drops what it cannot carry and says so in a banner.

Repeated overloads stop the transport. Note-offs and clock are never dropped.

task recipes

drive a DAW

1. Open a virtual MIDI port: IAC Driver on macOS, loopMIDI on Windows.
2. Press Enable MIDI, pick slot A, choose that port.
3. Set the DAW to receive on it, and to external sync if it should follow the tempo.
4. Select the line feeding your Note nodes, set channels to Set here, pick the channels.

drive two instruments from one pulse

1. Bind slot A and slot B to different devices.
2. Select the line, Set here, pick output A and its channels.
3. Switch the output selector to B and pick its channels.
4. Give the B channels a transpose if the second instrument sits in another register.

send a filter sweep

1. Place an LFO and a Param node, and patch LFO into Param.
2. On the Param node, set Scope to CC and Controller to the number the instrument listens on — 74 is filter cutoff by convention.
3. Select the line between them, Set here, pick the output and channel.
4. On the LFO, set Cycle to the sweep length and From/To to the range.
5. Patch a Pulse into the LFO to restart the sweep in time.

put two parts in step

1. Patch a Split into two Note nodes.
2. Put both Note nodes in the same row as each other. Equal lengths, so their pulses arrive together.
3. Drag one of them a row down and play it again: the line got longer, so that part is now late. Select the line to see by how much.
4. Use the Grid setting to scale the whole patch at once — 1/16 halves every travel time, 1/4 doubles it.

share a patch

1. Give it a name on the library tab.
2. Save. The file lands in your downloads, named after the patch.
3. Send the file, or its text.
4. They drop it on their canvas, or paste it there.

follow another sequencer

1. Choose the master's port under MIDI in.
2. Press Sync. The tempo readout follows the master and the project BPM is left alone.
3. Press play on the master.

play the patch from a keyboard

1. Choose the keyboard's port under MIDI in.
2. Place a MIDI In node and patch it into a Note node.
3. Set Played note to Key to retune the patch from the pitch played, Transpose to shift it, Gate to ignore the pitch.
4. Start the transport; played notes need it running.

tech

Vanilla ES modules. No build, no dependencies. Web Audio for the built-in voices and the SoundFont player, Web MIDI for output and input. The SoundFont parser is src/sf2.js and touches no browser API, so it is read and checked outside one.

npm test runs 350 tests under node --test. engine, model, music, rhythm, voice, sync, lfo, limits, shelf and geometry have no DOM, audio or MIDI dependencies and are tested directly; the engine runs against a fake clock and stub outputs. The synth is checked in a browser at tests/audio-check.html.

Web MIDI: Chrome, Edge, Opera, Firefox 108+. Not Safari and not any iOS browser, which all run WebKit — those get the built-in voices only.