playing-guitar-with-pytheory

Playing guitar (and strings) with PyTheory

PyTheory models the fretboard: chord shapes, fingerings, tablature, scale diagrams, alternate tunings, and chord identification — for guitar and ~20 other stringed instruments — plus a real-time tuner. The fretboard tools are pure Python (run a script or one-liner); the tuner is a CLI that listens to your mic.

If PyTheory isn't installed, prefer uv when available: uv pip install pytheory (or uv add pytheory in a uv project); otherwise pip install pytheory.

Fingerings, chord shapes & tab

from pytheory import Fretboard, Chord

fb = Fretboard.guitar()

print(fb.tab("Am"))          # ASCII tablature for a chord (high e on top)
# A minor
# e|--0--
# B|--1--
# G|--2--
# D|--2--
# A|--0--
# E|--x--

shape = fb.chord("Am")       # a Fingering object
shape.positions              # (None, 0, 2, 2, 1, 0)  — None = muted string
shape.string_names           # ('E', 'A', 'D', 'G', 'B', 'e')  — data model, low-to-high
print(shape.tab())           # same ASCII tab (always high-to-low display)

• Fretboard.guitar() and friends build a fretboard; .chord("Cmaj7") returns a Fingering, .tab("Cmaj7") returns the ASCII tab string directly.
• .fingering(0, 2, 2, 1, 0, 0) builds a Fingering from explicit fret numbers (low-to-high), e.g. to check a shape you have in mind.
• A Fingering has .positions, .string_names, .tones, .tab(), .identify(), and .to_chord().

Charted-chord coverage: .chord()/.tab() look the name up in a library of ~144 common voicings — every root in major, minor, 5, 6, 7, m7, maj7, 9, m9, maj9, and dim. Names outside that set (e.g. sus4, m7b5, aug, add9) raise KeyError. For those, either build the shape yourself with .fingering(...), or work from the chord's notes via Chord.from_symbol("F#m7b5") (see "Identify a chord"). CHARTS["western"].keys() lists everything charted.

Other instruments

All take the same .chord() / .tab() / .scale_diagram() API: