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 map llms.txt OpenAPI Example D4 map C major voicings Composer bridge Chord-scale advisor D minor tab recipe

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 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 /api/composer for circle, common-tone, guide-tone, and guitar-anchor moves.
Use /api/chord-scale and /api/scales/containing for scale reasoning.
Use /api/recipes/tab when an explanation needs a playable share URL.

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

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/composer?note=G2&root=C&scale=major
GET /api/chord-scale?root=G&chord=dominant7&contextRoot=C
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.