How To Use GuitarTheory

Selecting a Key

• ›Click any segment on the outer ring to select a major key.
• ›Click the inner ring to select the relative minor key.
• ›The selected key plays a note on click so you can hear the root.
• ›Toggle between Major and Minor view using the button below the circle — the mode selector adapts accordingly.

Key Information Panel

• ›Once a key is selected, the right panel shows the key signature (e.g. 2♯, 3♭) and related keys: dominant (a fifth up), subdominant (a fifth down), and relative major/minor.
• ›The scale for the selected key and mode is displayed with all notes listed.
• ›Clicking a related key loads it instantly.

Enharmonic Keys

• ›Three positions on the circle have two valid spellings: B/Cb, F#/Gb, and Db/C#.
• ›When one of these is selected, a pill button (e.g. "= Cb") appears in the info panel.
• ›Click it to switch the entire view to the enharmonic spelling — scale notes, diatonic chords, related keys, and the fretboard all update together.
• ›Click again to switch back.

Mode Selector

• ›Seven church modes available in major view: Ionian, Dorian, Phrygian, Lydian, Mixolydian, Aeolian, Locrian.
• ›Minor view adds Harmonic Minor and Melodic Minor.
• ›Changing the mode updates the scale notes displayed in the info panel.

Diatonic Chords

• ›Below the circle controls, all seven diatonic chords for the selected key are shown (I through vii°).
• ›Color-coded by quality: gold = major, indigo = minor, red = diminished.
• ›Click any chord to hear it played — clicking a different chord stops the previous one.
• ›Click the active chord again to stop playback.

Chord Progression Builder

• ›Build progressions by adding chords from the palette below the circle.
• ›Choose from 11 chord types per chord: triads, suspended, 7ths, extended, and power (5th) chords.
• ›Switch chord type mid-progression with the per-chord dropdown on each card.
• ›Each chord card shows a live mini diagram — use the ← → arrows to cycle through available voicing positions. Diagram size (Small/Large) is controlled in Preferences.
• ›Reorder chords with the ← → move buttons on each card.
• ›Set BPM with the tempo slider (40–240 BPM) — affects playback timing.
• ›Hit Play to hear the full progression with the Rhodes-style FM piano sound.
• ›Load from the template library — 28 curated progressions across Pop, Rock, Metal, Blues, Jazz, Country, Funk, R&B, and more, each with difficulty badges and famous song examples.
• ›Templates automatically transpose to your selected key.
• ›Sign in to save progressions — chord voicings are saved alongside chord symbols and restored when you reopen them.
• ›Export any saved progression as PNG or PDF from the library page.

Browsing Chords

• ›Select a root note and chord type from the controls at the top.
• ›The info panel shows the chord's notes, interval degrees, staff notation, and a list of compatible scales.
• ›All voicing positions appear as clickable diagrams below — click any to hear it played.
• ›Chord diagrams show finger positions, fret numbers, open strings (green circles), and muted strings (✕).
• ›Purple dots indicate the root note; blue dots indicate other chord tones.

Alternate Tuning Voicings

• ›Select a tuning from the Tuning dropdown alongside the root and chord type selectors.
• ›Available tunings span five groups: Standard (6 and 7-string), Drop Tunings (Drop D, Double Drop D, Drop C), Transposed (Half Step Down, Full Step Down), Modal/Celtic (DADGAD, FACGCE), and Open Tunings (Open G, Open D, Open E, Open A).
• ›For standard 6-string, the hand-crafted voicing library is used — the same named positions (Open Position, Barre shapes, CAGED) you're used to.
• ›For any other tuning, voicings are computed automatically: the algorithm maps each string's chord tones across fret windows and searches for valid, playable shapes. Open strings are preferred for their resonant character in alternate tunings.
• ›The diagram string labels update to reflect the actual open string notes for the selected tuning, so what you see matches what you're playing.
• ›Audio playback for each shape uses the tuning's actual open string pitches — not standard tuning — so it sounds correct.
• ›The positions header shows a tuning badge when a non-standard tuning is active so you always know the context.
• ›Open tunings like Open G or Open D often reveal simpler chord shapes — a G major in Open G is all six strings open.
• ›Drop D unlocks one-finger power chords across the lowest three strings.

Chord Information Panel

• ›Notes — the chord tones spelled with correct enharmonic accidentals (flats for minor/dominant chords, sharps for major/augmented).
• ›Degrees — interval names (1, ♭3, 5, ♭7, etc.) with the formula shown below.
• ›Staff — treble clef notation for the chord tones, with the root highlighted in purple.
• ›Works With — up to five scales that contain all of this chord's tones, helpful for improvisation and songwriting.
• ›Play button — hear the chord as a piano voicing.

Choosing a Scale

• ›Select a root note from the 12-button grid.
• ›Choose a scale type from the categorized list: Modes, Pentatonic, Blues, Melodic Minor, Harmonic Minor, Symmetric, and World scales.
• ›The fretboard, notation, and TAB update instantly.

Fretboard View

• ›Full fretboard diagram showing all scale tones highlighted — standard orientation with low E at the bottom, high e at the top.
• ›Toggle between 6, 7, and 8-string guitar.
• ›Switch between 12-fret and 24-fret views.
• ›Display modes: Dots, Note Names, Intervals, or Scale Degrees.
• ›Hover a note dot to see the note name, string, fret, and interval.

Fingering Patterns

• ›CAGED system shapes — 5 positions covering the full neck.
• ›3-Notes-Per-String (3NPS) patterns for speed and economy of motion.
• ›Box patterns for compact, position-based playing.
• ›Each pattern shows a mini fretboard diagram — low E at bottom, high e at top, matching the main fretboard orientation.
• ›Clicking a pattern updates the Notation & TAB section below.
• ›When an alternate tuning is active, CAGED / 3NPS / Box patterns are dimmed (they are calculated for standard tuning). Instead, five Neck Position patterns are generated automatically for the current tuning — Open, Position 2, Position 3, Position 4, and Position 5.

Alternate Tunings

• ›Select a tuning from the dropdown in the Fretboard View — the entire visualizer updates together: fretboard, fingering patterns, notation, and TAB.
• ›Available tunings include standard (6, 7, 8 string), Drop D, Double Drop D, Drop C, half-step and full-step down, DADGAD, FACGCE, Open G, Open D, Open E, Open A, and more.
• ›The fretboard always reflects the actual open string pitches for the chosen tuning.
• ›Notation & TAB uses absolute semitone arithmetic so written positions are correct for every tuning — not just standard.
• ›The context header in Notation & TAB shows the active tuning name so you always know what you're looking at.

Notation & TAB

• ›Standard staff notation displayed alongside guitar TAB for the selected pattern.
• ›Guitar transposing convention applied (written one octave higher than concert pitch — standard for guitar notation).
• ›The header shows the scale name, pattern, fret range, and tuning (when non-standard).
• ›Play Scale button plays exactly the notes shown in the notation, in the correct octave.
• ›TAB note columns are aligned precisely with the staff notes above.
• ›6, 7, and 8-string TAB supported.

Favorite Scales

• ›Sign in to save specific root + scale combinations as favorites (e.g. "E Harmonic Minor").
• ›Click the ♡ heart button next to the scale name in the info panel to save it.
• ›Your favorites appear as chips at the top of the left panel — click any to instantly reload it.
• ›Favorites are stored to your profile and persist across sessions.

Exporting

• ›Click the Export button (↓ download icon) next to the scale name to open the export preview.
• ›The export includes: scale title and character description, notes in scale, scale degrees with interval labels, step pattern (W/H/W+H), a full fretboard diagram, and standard notation + TAB (when a fingering pattern is selected).
• ›The fretboard diagram shows all scale notes across the neck — root notes in purple, scale tones in blue, open strings as unfilled circles. String labels and inlay dots aid orientation.
• ›If you have the 24-fret view active, the fretboard diagram is split into two rows (frets 0–12 and frets 13–24) so notes remain large and easy to read.
• ›The diagram reflects your current tuning — alternate tuning names appear in the export header when non-standard.
• ›Export as PNG (high resolution, 2× pixel density) or PDF (portrait A4).

Saving & Managing

• ›Build a progression in the Circle of Fifths, then hit Save — give it a name, key, mode, tags, and BPM.
• ›Edit or delete saved progressions from the library page.
• ›Search across names, chords, and tags. Filter by key or mode. Sort by date, name, or views.

Playback

• ›Each progression card has a ▶ play button — hear it at the BPM it was saved with.
• ›Chord cards display mini fretboard diagrams showing the saved voicing and position label.
• ›Only one progression plays at a time — clicking another stops the current one.
• ›The BPM is shown on every card.

Sharing

• ›Make a progression public to generate a unique share link.
• ›Share links work without an account — anyone can view and hear the progression.
• ›View counts track how many times a shared progression has been visited.

Signing In

• ›Open the menu (☰ top right) and tap Sign In.
• ›Create an account with an email and password, or sign in if you already have one.
• ›An account unlocks: saving progressions, saving favorite scales, and your personal profile.

Profile Page

• ›Access your profile from the menu or the avatar card at the top right.
• ›Upload a custom avatar photo (JPEG/PNG/WebP, up to 2 MB) — or let the app generate one from your initials.
• ›Edit your display name and change your password.
• ›View your stats: total progressions saved, favorite scales, and member since date.

Preferences

• ›Choose from four themes: Dark Purple, Dark Blue, Dark Green, and Dark Slate.
• ›Set a default key — the Circle of Fifths and Scale Visualizer start with this key selected.
• ›Set default guitar type (6, 7, or 8 string) and tuning.
• ›Choose your Guitar Sound — Acoustic Steel, Electric Jazz, Distortion, or Overdriven. This controls the sample library used for all audio playback across the app. Defaults to Acoustic Steel if you're not signed in.
• ›Toggle fretboard display mode: Dots, Note Names, or Intervals.
• ›Enable colorblind mode — replaces color-only cues in the Circle of Fifths with patterns.
• ›Set Progression Diagram Size (Small or Large) — controls the size of chord voicing diagrams in both the Chord Progression Builder and the My Progressions library.
• ›All preferences are saved to your account and applied automatically on every page.

How It Works

• ›GT Game is a timed music theory quiz with 20 progressively harder levels organised into Bronze (1–5), Silver (6–10), Gold (11–15), and Master (16–20) tiers.
• ›Each level contains 10 questions drawn from that tier's topic set — scales, intervals, chords, modes, and more.
• ›Answer correctly within the time limit (20 seconds at Level 1 down to 5 seconds at Level 20). Wrong or timed-out answers show the correct answer and a detailed explanation.
• ›Pass a level by hitting its passing threshold (6–9 out of 10 depending on tier) to earn that level's badge and unlock the next level.
• ›You can replay any completed level to improve your score. Your best score per level is saved.

Level Select & Badges

• ›The Level Hub shows all 20 levels as hexagonal badges arranged by tier. Locked levels appear greyed out until the previous level is passed.
• ›Earned badges display in full colour; locked badges are dimmed. Your current highest badge is shown at the top of the hub.
• ›Badge colours follow the tier: bronze, silver, gold, and a purple–pink gradient for the Master tier.
• ›Clicking a level card shows the level name, description, time limit, passing score, and your best previous score before you start.

Playing a Level

• ›A 3-second countdown plays before each level starts.
• ›Questions are drawn randomly from that level's topic pool, so replaying the same level gives different questions.
• ›Each question shows a text prompt and optionally a visual hint — coloured note chips for scale/chord questions, or a semitone pattern for mode/interval pattern questions.
• ›Select one of the four multiple-choice answers. The timer bar drains as time counts down; if it hits zero the question counts as wrong.
• ›After each answer you see whether you were right or wrong, the correct answer, and a plain-English explanation.

Progress & Profile

• ›GT Game requires a free account — your progress and badges are saved to your profile automatically.
• ›Visitors without an account can browse the game page and see how it works, but must sign up to play and save progress.
• ›Your game progress card on the Profile page shows your highest level, total points, and a mini strip of all 20 badges.
• ›Enable "Show game badge on avatar" in Preferences to display a small badge overlay in the lower-right corner of your avatar throughout the app.
• ›Access GT Game from the hamburger menu or navigate directly to /game.

Scales & Modes

Chords

Keys

Fretboard

Intervals

Getting an API Key

• ›Without a key: up to 60 requests/minute per IP address — fine for testing.
• ›With a free key: up to 200 requests/minute, plus a usage dashboard.
• ›Register at /api/v1/keys/register with your name and email. The key is shown once — save it.
• ›Send the key with every request via the X-API-Key header.
• ›Check your usage at /api/v1/keys/usage (requires X-API-Key header).
• ›Full interactive docs (Swagger UI) available at /docs.

# Register (one-time — key is shown once, save it)
curl -X POST https://www.guitartheory.com/api/v1/keys/register \
  -H "Content-Type: application/json" \
  -d '{"name":"My App","email":"you@example.com"}'

# Use your key on every request
curl -H "X-API-Key: gt_live_..." https://www.guitartheory.com/api/v1/scales/C/major

# Check your usage
curl -H "X-API-Key: gt_live_..." https://www.guitartheory.com/api/v1/keys/usage

JavaScript / TypeScript

const BASE = 'https://www.guitartheory.com/api/v1'

// Get scale notes
const res = await fetch(`${BASE}/scales/D/dorian`)
const scale = await res.json()
console.log(scale.notes)
// ['D', 'E', 'F', 'G', 'A', 'B', 'C']

// Get diatonic chords for A minor
const key = await fetch(`${BASE}/keys/A/minor`).then(r => r.json())
key.diatonicChords.forEach(c =>
  console.log(`${c.numeral}: ${c.name}`)
)
// i: Am   ii°: Bdim   III: C   iv: Dm   v: Em   VI: F   VII: G

// Get guitar voicings for G7
const chord = await fetch(`${BASE}/chords/G/dom7`).then(r => r.json())
chord.voicings.forEach(v => console.log(v.name, v.positions))

Python

import requests

BASE = 'https://www.guitartheory.com/api/v1'

# E Phrygian scale
scale = requests.get(f'{BASE}/scales/E/phrygian').json()
print(scale['notes'])
# ['E', 'F', 'G', 'A', 'B', 'C', 'D']

# Interval between D and F#
interval = requests.get(f'{BASE}/intervals/D/F%23').json()
print(interval['intervalName'])   # 'Major Third'
print(interval['semitones'])      # 4

# Scale on fretboard
positions = requests.get(f'{BASE}/fretboard/scale/A/minor?frets=12').json()
roots = [p for p in positions['positions'] if p['isRoot']]
print(f"Root notes on fretboard: {len(roots)}")

URL Encoding for Sharp Notes

• ›Notes with # must be URL-encoded: C# → C%23, F# → F%23, G# → G%23
• ›Flat notes (Db, Eb, Gb, Ab, Bb) do not need encoding.
• ›Example: /scales/F%23/lydian (not /scales/F#/lydian)

What It Demonstrates

• ›GET /api/v1/scales/{root}/{mode} — generates scale degree questions from live scale data.
• ›GET /api/v1/intervals/{note1}/{note2} — generates interval identification questions.
• ›GET /api/v1/keys/{note}/major — generates relative key questions using the relativeMinor field.
• ›GET /api/v1/modes — fetched once at load, cached in memory for mode character questions.
• ›Every question shows the exact API endpoint being called so you can see exactly what's happening.

Using It in Your Project

• ›Download the single HTML file — no npm, no build step, no dependencies.
• ›By default it calls the GuitarTheory public API at guitartheory.com/api/v1, which has CORS enabled so it works from any domain.
• ›Self-hosting GuitarTheory? Change the one BASE_URL constant at the top of the script to your server URL.
• ›The documentation section within the file explains each API call with annotated code snippets and full response shapes.
• ›Use it as a starting point — adapt the question generators and build your own UI on top of the API.