{ "openapi": "3.1.1", "info": { "title": "Tonegrid Pattern Builder API", "version": "1.0.0", "summary": "Turn x-and-dot step notation into a Tonegrid project and a MIDI file.", "description": "Every endpoint performs the same calculation as the human page and returns inputs, result, units, assumptions, sources, warnings and computedAt. MCP endpoint: /mcp." }, "servers": [ { "url": "https://tonegridpatternbuilder.usefulweb.app" } ], "paths": { "/api/v1/calculate": { "post": { "operationId": "calculate", "summary": "Turn x-and-dot step notation into a Tonegrid project and a MIDI file.", "description": "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.\n\nMethodology:\n- 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.\n- 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).\n- 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.\n\nThe 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.", "tags": [ "apps" ], "x-mcp-tool": "tonegrid_pattern_builder", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TonegridPatternBuilderInput" }, "examples": { "example1": { "summary": "Pentatonic melody with a simple beat", "value": { "name": "Ripple beat", "pattern": "# melody (note names) and drums: x = hit, . = rest\nG4 .... ..x. .... ..x.\nE4 .... x... .... x...\nA3 ..x. .... ..x. ....\nE3 x... .... x... ....\nkick x... .... x... ....\nsnare .... x... .... x...\nclosed-hat x.x. x.x. x.x. x.x." } }, "example2": { "summary": "Twelve-step melody against a sixteen-step beat", "value": { "name": "Phase sketch", "root": 57, "scale": "minorPentatonic", "bpm": 96, "swing": 20, "repeats": 3, "pattern": "E5 x... ..x. ....\nC5 ..x. .... x...\nA4 .... x... ..x.\nA3 x... .... ....\nkick x... ..x. x... ....\nhat ..x. ..x. ..x. ..x." } } } } } }, "responses": { "200": { "description": "Calculation result envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TonegridPatternBuilderResult" } } } }, "400": { "description": "Malformed JSON body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid input (see errors[]).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded (see Retry-After).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/tool": { "get": { "operationId": "getToolDefinition", "summary": "Inputs, output schema and examples for this tool", "responses": { "200": { "description": "Tool definition.", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "schemas": { "Problem": { "type": "object", "description": "RFC 9457 problem details. 422 responses include per-field `errors`.", "required": [ "type", "title", "status", "detail" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "TonegridPatternBuilderInput": { "type": "object", "additionalProperties": false, "properties": { "name": { "title": "Project name", "type": "string", "maxLength": 100, "default": "API melody" }, "pattern": { "title": "Pattern lines", "description": "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).", "type": "string", "maxLength": 20000, "default": "# melody (note names) and drums: x = hit, . = rest\nG4 .... ..x. .... ..x.\nE4 .... x... .... x...\nA3 ..x. .... ..x. ....\nE3 x... .... x... ....\nkick x... .... x... ....\nsnare .... x... .... x...\nclosed-hat x.x. x.x. x.x. x.x." }, "root": { "title": "Key (root MIDI note)", "description": "48 is C3, 57 is A3, 60 is C4. The root is the lowest melody row.", "type": "number", "minimum": 48, "maximum": 71, "default": 48 }, "scale": { "title": "Scale", "type": "string", "enum": [ "pentatonic", "minorPentatonic", "major", "minor", "dorian", "mixolydian", "harmonicMinor", "blues", "chromatic" ], "default": "pentatonic" }, "rows": { "title": "Melody rows", "description": "How many scale notes the melody grid has, counted up from the root.", "type": "number", "minimum": 1, "maximum": 24, "default": 16 }, "voice": { "title": "Melody sound", "type": "string", "enum": [ "bell", "sine", "triangle", "pluck", "pad" ], "default": "bell" }, "bpm": { "title": "Tempo (BPM)", "type": "number", "minimum": 40, "maximum": 220, "default": 100 }, "swing": { "title": "Swing (%)", "description": "Delays every second step by this share of a step.", "type": "number", "minimum": 0, "maximum": 45, "default": 0 }, "repeats": { "title": "Repeats in the MIDI file", "type": "number", "minimum": 1, "maximum": 16, "default": 2 } }, "required": [] }, "TonegridPatternBuilderResult": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "tool", "computedAt", "inputs", "summary", "result", "units", "assumptions", "sources", "warnings", "presentation", "links" ], "properties": { "schemaVersion": { "type": "string", "const": "1.0" }, "tool": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "version" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" } } }, "computedAt": { "type": "string", "format": "date-time" }, "inputs": { "type": "object", "description": "Normalised inputs actually used, including applied defaults." }, "summary": { "type": "string" }, "result": { "type": "object", "additionalProperties": false, "required": [ "project", "stats", "melodyRows", "drumRows", "midiFile", "projectFile", "openInApp" ], "properties": { "project": { "type": "object", "description": "Tonegrid project (format \"tonegrid\", version 3); see /project.schema.json on the Tonegrid host." }, "stats": { "type": "object", "additionalProperties": false, "required": [ "notes", "drumHits", "melodySteps", "drumSteps", "drumRows", "cycleSteps", "loopSeconds", "songSeconds", "lowestNote", "highestNote" ], "properties": { "notes": { "type": "integer" }, "drumHits": { "type": "integer" }, "melodySteps": { "type": "integer" }, "drumSteps": { "type": "integer" }, "drumRows": { "type": "integer" }, "cycleSteps": { "type": "integer", "description": "Steps until melody and drums line up again (and swing parity repeats)." }, "loopSeconds": { "type": "number" }, "songSeconds": { "type": "number" }, "lowestNote": { "type": "string" }, "highestNote": { "type": "string" } } }, "melodyRows": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "row", "note", "midi", "hits" ], "properties": { "row": { "type": "integer" }, "note": { "type": "string" }, "midi": { "type": "integer" }, "hits": { "type": "integer" } } } }, "drumRows": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "drum", "midi", "hits" ], "properties": { "drum": { "type": "string" }, "midi": { "type": "integer" }, "hits": { "type": "integer" } } } }, "midiFile": { "type": "object", "additionalProperties": false, "required": [ "artifactId", "filename", "mime", "bytes", "sha256", "path" ], "properties": { "artifactId": { "type": "string" }, "filename": { "type": "string" }, "mime": { "type": "string" }, "bytes": { "type": "integer" }, "sha256": { "type": "string" }, "path": { "type": "string", "description": "Download path on the same site (valid for about 2 hours)." } } }, "projectFile": { "type": "object", "additionalProperties": false, "required": [ "artifactId", "filename", "mime", "bytes", "sha256", "path" ], "properties": { "artifactId": { "type": "string" }, "filename": { "type": "string" }, "mime": { "type": "string" }, "bytes": { "type": "integer" }, "sha256": { "type": "string" }, "path": { "type": "string", "description": "Download path on the same site (valid for about 2 hours)." } } }, "openInApp": { "type": [ "string", "null" ] } } }, "units": { "type": "object", "additionalProperties": { "type": "string" } }, "assumptions": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "title" ], "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "publisher": { "type": "string" }, "retrievedAt": { "type": "string" }, "note": { "type": "string" } } } }, "warnings": { "type": "array", "items": { "type": "string" } }, "presentation": { "type": "array", "items": { "type": "object" }, "description": "Display blocks used by the human page (same data)." }, "links": { "type": "object", "additionalProperties": false, "required": [ "human", "api", "openapi", "methodology" ], "properties": { "human": { "type": "string", "format": "uri" }, "api": { "type": "string", "format": "uri" }, "openapi": { "type": "string", "format": "uri" }, "methodology": { "type": "string", "format": "uri" } } } } } } } }