Agent Pitch Map

A public AI-navigable pitch map for humans and agents to move notes across piano, standard guitar, theory layers, sound, and simple guitar tab.

Open mapAgent examplesllms.txtllms-full.txtOpenAPIHealthC4 note JSONC fretboard mapC4 best positionExample D4 mapC major voicingsChord APIIdentify F barreRoute from F barreFirst-position routeG7 to Cmaj7Top 3 resolutionsC guide-tone drillPlay-this-position drillTracker Synth patternTracker instrumentsComposer bridgeCompose Dorian ideaChord-scale advisorScale APID minor tab recipe

Decision Workflow Examples

Note translation

GET /api/map?note=C4&root=C&scale=major&piano=61-key

MIDI identity, frequency, piano key, guitar positions, and interval role.

Best position ranking

GET /api/positions?note=C4&root=C&scale=major&position=first&maxFret=12

Ranked single-note string/fret options with exact-pitch, hand-window, theory, fingering, tab, and share proof.

Route from barre shape

GET /api/route?notes=F4,G4,A4&root=F&scale=major&position=first&maxFret=12&frets=1,3,3,2,1,1

Ranked guitar route, shapeContext, barre proof, movement proof, fingering proof, structured tab events, tabRenderRequest, and share URLs.

Voice-leading resolution

GET /api/voice-leading?fromRoot=G&fromChord=dominant7&toRoot=C&toChord=major7&limit=3

Three ranked transitions with common-tone, guide-tone, motion proof, and per-rank links.

Shape identification

GET /api/identify?frets=1,3,3,2,1,1&contextRoot=F&limit=5

Ranked chord hypotheses with covered tones, omissions, bass role, barres[], barreDisplayProof, and likely function.

Constrained riff composition

GET /api/compose?key=D&scale=dorian&chord=minor7&motif=dorian-compass&position=first&bars=2

Playable ProjectState, two-measure ASCII tab, overlays, app URL, and compact URL.

Practice drill compiler

GET /api/practice/drill?target=guide-tones&key=C&level=beginner&position=first

MIDI targets, pulse timing, route proof, tab events, ASCII tab, and share URLs.

Practice route-position drill

GET /api/practice/drill?target=guide-tones&key=C&level=beginner&position=first&maxFret=7

Drillable positionDrill[] steps, positionTabPacket.tabNotes[], tabRenderRequest, and movement proof.

Tracker Synth pattern

GET /api/tracker/pattern?source=practice&target=guide-tones&key=C&position=first&maxFret=7

TrackerProject rows, synth instruments, scheduled events, structured tab, ProjectState, compact URL, and event proof.

Who Should Use It

  • Human players learning how piano notes map to guitar frets.
  • Teachers explaining exact pitch, octave, and note-name families.
  • Songwriters moving MIDI or piano ideas into playable guitar parts.
  • AI agents that need structured music data instead of visual guessing.

Agent Operating Rules

  • Use read-only APIs first, especially /api/map.
  • Use /api/note, /api/fretboard, /api/chord, and /api/scale for narrow stable calls.
  • Use /api/positions before guessing the best string/fret for one selected note.
  • Use the visual UI when the user needs to see or click the result.
  • Separate exact pitch from same note name across octaves.
  • Report theory membership and interval function separately.
  • Use /api/voicings before guessing playable guitar shapes.
  • Use barreDisplayProof from /api/identify and /api/voicings before explaining how to draw full or partial barres.
  • Use /api/route before guessing string/fret paths for melodies, riffs, or arpeggios.
  • Add frets=1,3,3,2,1,1 or shape=... to /api/route when a melody route should stay near an existing chord shape; read shapeContext for barre spans, hand-window source, and start-anchor proof.
  • Use tabRenderRequest from /api/route as the ready POST /api/tab payload when routes[0].tabNotes should be rendered with eventProof[].
  • After rendering a route request, verify eventProof[].stringFretMatchesMidi and project.tabProject.measures[0].notes before treating the tab as canonical.
  • Use /api/voice-leading?limit=3 before guessing guitar chord resolutions; compare transitions[0..2] by score, frets, and proof.
  • Use /api/practice/drill to compile loopable practice targets with pulse timing and route-ranked tab events.
  • Use positionDrill[] from /api/practice/drill when an answer needs exact beat-aligned string/fret targets for a play-this-position drill.
  • Use positionTabPacket.tabNotes[] from /api/practice/drill when the play-this-position drill should become structured tab events.
  • Use positionTabPacket.tabInsertion to replace TabProject.measures[measureIndex].notes from those packet events without parsing ASCII tab.
  • Use positionTabPacket.tabRenderRequest as the ready POST /api/tab payload when the packet should be rendered with eventProof[].
  • Use routePlan.routes[0] from /api/practice/drill when the answer needs the ranking proof behind positionDrill[].
  • Use /api/tracker/pattern when practice, route, or compose output should become tracker rows, synth instruments, scheduled events, structured tab, and proof.
  • Use tracker.patterns[0].cells[] as the canonical tracker row model and rendered.proof.eventProof[].stringFretMatchesMidi before treating tracker-rendered tab as canonical.
  • Use POST /api/tracker/render when the agent already has a TrackerProject and needs scheduled events, tab, ProjectState, URLs, and proof.
  • Use /api/composer for circle, common-tone, guide-tone, and guitar-anchor moves.
  • Use /api/compose when the answer should include a full playable project.
  • Use /api/chord-scale and /api/scales/containing for scale reasoning.
  • Use /api/recipes/tab when an explanation needs a quick example.
  • Use /api/project/compact when a shorter zproject URL is needed.
  • Use POST /api/tab to turn structured note/string/fret events into ASCII tab and ProjectState.
  • Use POST /api/project/render to derive tab and share URLs from ProjectState.

Stable Agent Endpoint Set

GET /api/health GET /api/note?note=C4 GET /api/fretboard?note=C&maxFret=12 GET /api/positions?note=C4&root=C&scale=major&position=first&maxFret=12 GET /api/map?note=D4&root=C&scale=major&piano=49-key GET /api/chord?root=C&chord=major&limit=3 GET /api/scale?root=C&scale=lydian&note=G2 GET /api/identify?frets=1,3,3,2,1,1&contextRoot=F&limit=5 GET /api/route?notes=F4,G4,A4&root=F&scale=major&position=first&frets=1,3,3,2,1,1 GET /api/route?notes=C4,D4,E4,G4&root=C&scale=major&position=first GET /api/voice-leading?fromRoot=G&fromChord=dominant7&toRoot=C&toChord=major7&limit=3 GET /api/practice/drill?target=guide-tones&key=C&level=beginner&position=first GET /api/practice/drill?target=guide-tones&key=C&level=beginner&position=first&maxFret=7 GET /api/tracker/pattern?source=practice&target=guide-tones&key=C&position=first&maxFret=7 GET /api/tracker/instruments POST /api/tracker/render POST /api/tab POST /api/project/render

Best Position API

GET /api/positions?note=C4&root=C&scale=major&position=first&maxFret=12 Returns: - bestPosition as the preferred single-note string/fret target - positions[] alternatives sorted by nondecreasing cost - exact-pitch preservation and hand-window proof - theory membership and interval proof - fingering proof for the chosen target - one-note structured tab project plus appUrl and compactUrl

Primary API

GET /api/map?note=D4&root=C&scale=major&piano=49-key Returns: - selected MIDI pitch and frequency - exact piano key - same-note-name piano keys - exact standard guitar fret positions - same-note-name guitar fret positions - active scale/chord membership - interval function against the selected root

Composer Bridge API

GET /api/composer?note=G2&root=C&scale=major Returns: - current circle-of-fifths neighbors - scale pitch classes sorted by fifths - dominant, subdominant, relative-minor, chromatic-mediant, and guide-tone moves - common tones for each move - low-position standard-guitar anchors for shared notes

Route Planner API

GET /api/route?notes=C4,D4,E4,G4&root=C&scale=major&position=first Returns: - ranked standard-guitar string/fret paths - fret movement, string movement, span, open-string, and theory-membership proof - tab-ready structured note events - tabRenderProof as the expected POST /api/tab verification target - tabRenderRequest as the ready POST /api/tab payload for routes[0].tabNotes - render-proof loop: POST tabRenderRequest.path with tabRenderRequest.body, then verify eventProof[].stringFretMatchesMidi and project.tabProject.measures[0].notes - ASCII tab derived from the best route - full and compact workbench URLs

Route Render Proof Task

Use this copy-paste task when a route must become canonical tab with string/fret/MIDI proof. The same proof workflow is linked from live route cards with data-agent-role="route-render-proof-link".

Worked route render proofRoute API example
Task: render and verify the best Agent Pitch Map route. 1. In the workbench, find: data-agent-role="route-tab-render-proof-target" data-agent-role="route-tab-render-request" data-agent-role="render-route-tab-request" data-agent-role="route-render-proof-link" data-agent-role="route-tab-render-response-proof" 2. Or call: GET /api/route?notes=C4,D4,E4,G4&root=C&scale=major&position=first&maxFret=7 3. Read: tabRenderProof tabRenderRequest.path tabRenderRequest.body routes[0].tabNotes 4. Confirm before posting: tabRenderProof.expectedEventCount === routes[0].tabNotes.length tabRenderProof.expectedEventProof === "eventProof[].stringFretMatchesMidi" tabRenderProof.expectedProjectPath === "project.tabProject.measures[0].notes" 5. POST tabRenderRequest.path with tabRenderRequest.body. 6. Verify before reporting success: eventProof[].stringFretMatchesMidi === true project.tabProject.measures[0].notes.length === routes[0].tabNotes.length

Practice Loop API

GET /api/practice/drill?target=guide-tones&key=C&level=beginner&position=first&scale=major&chord=dominant7&maxFret=7 Returns: - MIDI-backed targets[] with note, interval, role, startBeat, and durationBeats - pulse[] count-in, target, and loop-reset events for local practice timing - routePlan.routes[0] as the preferred guitar path with movement and span proof - positionDrill[] as prejoined beat-aligned exact string/fret play-this-position targets - positionTabPacket.tabNotes[] as structured tab events derived from positionDrill[] - positionTabPacket.tabInsertion as the TabProject measure replacement target - positionTabPacket.tabRenderRequest as the ready POST /api/tab round-trip payload - structured TabNote events, derived ASCII tab, ProjectState, appUrl, and compactUrl - the same target/level contract used by the workbench Practice loop panel

Structured Tab API

POST /api/tab Input: { "title": "C major arpeggio", "tuning": "standard", "tempo": 96, "timeSignature": "4/4", "events": [ { "note": "C3", "string": 5, "fret": 3, "beat": 1 }, { "note": "E3", "string": 4, "fret": 2, "beat": 2 }, { "note": "G3", "string": 3, "fret": 0, "beat": 3 }, { "note": "C4", "string": 2, "fret": 1, "beat": 4 } ] } Returns: - ASCII tab derived from structured events - canonical MIDI-backed ProjectState - string/fret/MIDI proof for each event - full and compact workbench URLs

Composition API

GET /api/compose?key=D&scale=dorian&chord=minor7&motif=dorian-compass Returns: - complete MIDI-backed ProjectState - full workbench URL and compact zproject URL - two-measure ASCII tab - selected chord-scale context - semantic overlay marks for teaching targets and guide tones

Error Contract

HTTP 400 { "error": "Human-readable error message." }

Voice-Leading API

GET /api/voice-leading?fromRoot=G&fromChord=dominant7&toRoot=C&toChord=major7&limit=3 Returns: - transitions[0..2] as ranked source-to-target guitar voicing options - each transition id, efficiencyScore, source frets, and target frets - common pitch classes, retained fretted positions, and guide-tone motion - fret and MIDI voice-motion proof for every returned transition - transitionLinks[] with per-rank full and compact workbench URLs - tab-ready structured note events and derived ASCII tab - full and compact workbench URLs

Scale Atlas APIs

GET /api/scales?family=jazz GET /api/scale-map?root=C&scale=lydian&note=G2 GET /api/chord-scale?root=G&chord=dominant7&contextRoot=C GET /api/scales/containing?notes=C,E,G,Bb Returns: - scale definitions by family - pitch-class degree maps - selected-note scale membership - chord-scale candidates and tensions - guitar anchors for playable scale/chord tones

Project And Tab APIs

GET /api/project?note=D4&root=C&scale=major&piano=49-key GET /api/recipes/tab?key=D&scale=naturalMinor&style=beginner-riff GET /api/voicings?root=C&chord=major GET /api/route?notes=C4,D4,E4,G4&root=C&scale=major&position=first GET /api/voice-leading?fromRoot=G&fromChord=dominant7&toRoot=C&toChord=major7 GET /api/identify?frets=1,3,3,2,1,1&contextRoot=F&limit=5 GET /api/composer?note=G2&root=C&scale=major GET /api/compose?key=D&scale=dorian&chord=minor7&motif=dorian-compass GET /api/chord-scale?root=G&chord=dominant7&contextRoot=C GET /api/project/compact?project=<encoded-project-state> GET /api/tab/export?project=<encoded-project-state> Project JSON stores: - selected MIDI-backed pitch - theory layer and interval functions - piano mapping preferences - transport state - structured TabProject measures and TabNote events - optional semantic overlays for agent/recipe teaching marks

Browser Agent Contracts

The map exposes stable attributes for browser agents:

data-testid="piano-key-D4" data-testid="fret-S2-F3" data-note="D4" data-midi="62" data-interval="2" data-interval-name="second" data-overlay-role="target" data-overlay-label="Target: D opening target" data-agent-role="exact-selected-pitch" data-agent-role="same-note-name"

Boundaries

This version exposes read-only public endpoints. It does not expose write-capable MCP or A2A task execution. Agents can generate shareable read-only project states and semantic teaching overlays, then hand users the returned workbench URL.