Text patterns and the Pattern Builder API

Every Tonegrid pattern can be written as plain text. That makes patterns easy to keep in notes, to send in a chat, and to generate with scripts or AI agents.

The notation

One line per note or drum. A line starts with a note name (C4, D#4, Eb4) or a drum name (kick, snare, closed-hat, open-hat, clap, tom, rim, shaker), followed by x for a hit and . for a rest:

G4         .... ..x. .... ..x.
E4         .... x... .... x...
E3         x... .... x... ....
kick       x... .... x... ....
closed-hat ..x. ..x. ..x. ..x.

Spaces and | are ignored, so you can group steps in fours. Lines starting with # are comments. Short names work too: hat is the closed hi-hat, bd the kick, sd the snare.

Copy and paste in the app

• Edit → Copy pattern as text puts the current pattern on the clipboard, one line per row that has hits.
• Edit → Paste text pattern… opens a dialog with the current pattern written out row by row. Change it or paste your own text and press Replace pattern A (or B, C …).

Notes must belong to the current key, scale and number of rows; if one does not, the dialog names the line and the range of notes the grid can play. Lines shorter than the grid are filled with rests; longer lines are rejected. The change is one undo step.

Build projects with the API

The Tonegrid Pattern Builder tool takes the same text plus key, scale, rows, sound, tempo, swing and repeats. It returns a checked project, a MIDI file and an Open in Tonegrid link. Use it from its tool page, or from code:

POST /api/v1/tools/tonegrid-pattern-builder/calculate
{ "name": "Curl test", "pattern": "C4 x... x...\nkick x.x. x.x.", "bpm": 120 }

That request returns two melody notes and four kick hits on 8 steps; the loop lasts 1.00 second and the MIDI file with the default two repeats 2.00 seconds. result.midiFile.path is the MIDI download and result.openInApp the link.

On the Tonegrid host the same tools are available over MCP (/mcp) as tonegrid_pattern_builder and tonegrid_scale_planner, together with the three audio tools the export dialog uses. The project format is documented at /project.schema.json, and any valid project opens with /app#project=<base64url JSON>.

Scale planning

The Tonegrid Scale and Sequence Planner answers the opposite question: which note and frequency is on each row, and when does each square start? Give it a key, scale, tempo, swing and step,row pairs, and it lists the pitches and start times — useful to check a pattern before you write it, or to understand how swing moves the offbeats.

Good to know

• Text patterns describe one pattern. Arrange several in the app with the Song arrangement panel.
• Agents should keep the key and scale in mind: with C major pentatonic, F and B are not available.
• All tool runs follow the site's normal rate limits; a 429 answer means wait and try again.