The tools

Seven tools. song_format first, then whatever the job needs.

song_format

No arguments. Returns the whole format in one go: the shape build_song takes, how bars and chords are written, every style with its grooves, kits and drum genre, what a section can say to the band (the DRUMS lane with its cymbal and fill words and the seven presets, the JAM lane), how to use the band like a drummer would, every energy, colour and tuning, the grip notation, and the limits.

Also available as the resource noise://format/guide, so a client that supports resources can keep it in context without a tool call. The machine-readable half is noise://format/vocabulary.

capabilities

No arguments. What NØISE can and cannot do, and which fields actually change something when a song loads.

check_chords

{ "chords": ["Am", "F", "E7", "Bm7b5"], "key": "Am" }

Per chord: whether NØISE can read it and where it breaks if not, the canonical spelling, whether it is diatonic, borrowed or outside the key, and whether a guitar grip exists.

Am -> Am (diatonic), grip xxx555
F -> F (diatonic), grip xx3211
E7 -> E7 (borrowed), grip 020100
Bm7b5 -> Bm7b5 (diatonic), no guitar grip

That last line is worth reading carefully: the chord is perfectly legal, it fits the key, and it will play. NØISE just has no library grip for a m7b5, so the fretboard shows nothing unless you state a grip yourself.

chord_shapes

{ "chords": ["F"], "category": "easy", "limit": 1 }

Real grips from NØISE's library, drawn:

F - EASY - xx3211 - F easy (xx3211)
       1  2  3  4
 e  ·  1  ·  ·  ·
 B  ·  1  ·  ·  ·
 G  ·  ·  2  ·  ·
 D  ·  ·  ·  3  ·
 A  x  ·  ·  ·  ·
 E  x  ·  ·  ·  ·

Each comes with a tag you can put straight into build_song. Categories are easy, open, barre, power and triads; pass a tuning and the grips are derived for it (an open tuning has none, and the answer says so rather than returning nothing).

Use this instead of inventing fret numbers. A model guessing at frets is the single easiest way to produce a song that looks right and is unplayable.

build_song

The main one. Takes a song, or a partial draft plus a mode, or an existing song to build on:

{
  "mode": "direct",
  "song": {
    "name": "What's Up",
    "author": "4 Non Blondes",
    "key": "A",
    "bpm": 132,
    "style": "rock",
    "sections": [
      { "name": "VERSE", "repeats": 2, "bars": ["A", "Bm", "D", "A"] },
      { "name": "CHORUS", "energy": "lift", "fillIn": "crash", "fillOut": "fill", "preset": "DRIVING", "bars": ["A", "Bm", "D", "A"] }
    ]
  }
}

Returns the .noisesong file link, the song's page, a summary, the document, and any warnings; a noise:// link only with link: true. fillGrips: true puts a library grip on every chord that has none; add gripCategory to say which kind.

Anything the server could not use comes back as a warning with what it used instead — an unknown groove, a bpm outside 20–300, a kit that does not belong to the style, a preset name it does not know, a cymbal word the app does not play yet. It never silently changes your song. A section that names its own band, jamKit or drums genre is refused, with the new place named: a song is one band with one kit, and a section says how that band plays (feel, fillIn, fillOut, preset, the knobs, drumsOff).

validate_song

The same checks, no questions and no link. For iterating until the song is right without leaving anything behind.

load_song

{ "source": "noise://song?d=…" }

Reads an existing song — a .noisesong document, a noise:// link, or a catalogue id — into the same shape build_song takes. The chart survives the round trip unchanged, so you can change one thing and build it again. See Recipes.