# Tonegrid Pattern Builder

> Turn x-and-dot step notation into a Tonegrid project and a MIDI file. Write a melody and a beat as lines of x and dots, one line per note name or drum. The builder checks every note against the chosen key and scale, returns an editable Tonegrid project with a link that opens it in the app, and a Standard MIDI File with the melody and General MIDI drums.

Part of usefulweb.site (https://usefulweb.site/). Results are deterministic calculations from the inputs and the listed assumptions; the API returns exactly what the web page shows.

## Use it
- Human interface: https://tonegridpatternbuilder.usefulweb.site/ (interactive tool at https://tonegridpatternbuilder.usefulweb.site/tool)
- JSON API: POST https://tonegridpatternbuilder.usefulweb.site/api/v1/calculate with a JSON object of inputs (schema: https://tonegridpatternbuilder.usefulweb.site/api/v1/tool)
- OpenAPI: https://tonegridpatternbuilder.usefulweb.site/openapi.json
- MCP (Streamable HTTP): https://tonegridpatternbuilder.usefulweb.site/mcp - tool `tonegrid_pattern_builder`

## Inputs
- name (text): Project name
- pattern (textarea): Pattern lines - One line per note (C4, D#4, Eb4) or drum (kick, snare, closed-hat, open-hat, clap, tom, rim, shaker), then x for a hit and a dot for a rest. Spaces and | are ignored; lines starting with # are comments. All melody lines need the same length, and so do all drum lines (1–32 steps).
- root (number): Key (root MIDI note) - 48 is C3, 57 is A3, 60 is C4. The root is the lowest melody row.
- scale (select): Scale
- rows (number): Melody rows - How many scale notes the melody grid has, counted up from the root.
- voice (select): Melody sound
- bpm (number): Tempo (BPM)
- swing (number): Swing (%) - Delays every second step by this share of a step.
- repeats (number): Repeats in the MIDI file

## Method
- Each melody line is matched to a row of the grid: the root note is the lowest row and the scale repeats upward, so a note that is not in the key and range is rejected with the range that would fit.
- Steps are sixteenth notes. The melody and drum grids may have different lengths; they line up again after the least common multiple of both lengths (rounded up to an even number of steps for swing).
- The MIDI file (type 1, 480 ticks per quarter note) repeats the pattern as often as requested. Melody notes are on channel 1 with a General MIDI instrument that matches the sound; drums are on channel 10 with General MIDI percussion keys (kick 36, snare 38, closed hi-hat 42, open hi-hat 46, clap 39, low tom 45, rim 37, maracas 70). Swing delays odd steps by the swing share of a sixteenth.

## Limits
- The MIDI file contains notes only; the Tonegrid synth sounds and mixer settings are not part of it, so your music software chooses the instrument sounds.