The Fretwork Guitar Dataset

Use it in one line

curl https://guitarfretwork.com/data/chords.json

Python:

import json, urllib.request

chords = json.load(urllib.request.urlopen(
    "https://guitarfretwork.com/data/chords.json"))

f = next(c for c in chords if c["symbol"] == "F")
for s in f["shapes"]:
    print(s["position"], s["fret_string"])

JavaScript:

const chords = await (await fetch(
  "https://guitarfretwork.com/data/chords.json")).json();

const f = chords.find(c => c.symbol === "F");
console.log(f.shapes.map(s => s.fret_string));

The files are served with open CORS headers, so you can fetch them straight from a browser app. A .jsonl copy of each file sits beside it for streaming.

Every shape is verified

The chord shapes are not hand-typed and hoped for. A program works out which pitches each shape actually sounds in standard tuning, then compares them against the chord’s real tones. A shape is included only if:

• every note it sounds is a genuine chord tone — no stray notes
• the root sounds
• the third, or the suspended note, sounds
• the note that gives the chord its name — the 7th, the 9th — actually sounds
• for a slash chord, the named bass note is the lowest note

373 of 373 shapes pass. The checker is itself tested against deliberately broken shapes — an A minor with a major third, an F barre with a stray open string — and catches every one. Both runs are reproducible from the published source.

The barre flag is worked out from the shape’s geometry rather than its label, so a movable shape like x355xx is correctly marked as needing no barre.

How to read it

Chord frets run low E string first. null means the string is not played and 0 means open, so an open C is [null, 3, 2, 0, 1, 0] — written x32010 in fret_string. Tuning is standard, E A D G B E.

intervals are semitones above the root, so a major chord is [0, 4, 7].

Scale positions hold one entry per string, ordered the way a tab reads: high e first, low E last. string_number is 1 for the high e and 6 for the low E, so you never have to guess from the letter. root_frets marks which playable frets are the root.

Full field-by-field descriptions ship with the source as JSON Schema.

About the songs

These are traditional songs, spirituals, carols and sea shanties in the public domain — Amazing Grace, Scarborough Fair, House of the Rising Sun, Wayfaring Stranger and the like. The dataset holds metadata only: title, key, time signature, a difficulty band, and which chords the song uses. It contains no lyrics, no melodies and no notation.

A few early twentieth-century blues entries are public domain in the United States but may still be in copyright elsewhere under life-plus-seventy rules. Only factual metadata is recorded, but filter those out if you need worldwide public-domain certainty.

Files

Also on GitHub and Hugging Face

The same data, mirrored where developers already look:

• GitHub — with JSON Schema for every field, Python and JavaScript examples, and the verification script you can run yourself
• Hugging Face — loads straight into datasets.load_dataset()

from datasets import load_dataset
chords = load_dataset("HooshangBakht/fretwork-guitar-dataset", "chords")

Citation

@misc{fretwork_guitar_dataset,
  title  = {Fretwork Guitar Dataset},
  author = {{True Music School}},
  year   = {2026},
  url    = {https://guitarfretwork.com/data/},
  note   = {CC BY 4.0}
}

The same data powers the Fretwork MCP server, which lets AI assistants work with guitar chords, scales and practice plans directly.