Skip to content
Projects

yuma-m/pychord has 292 GitHub stars and 51 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-19 07:07 UTC. Last push 2026-11-03.

How these counts are measured

Measured star growth

in 24h
0
in 7 days
Collecting history
in 15 days
Collecting history
in 1 month
Collecting history

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

Python library to handle musical chords.

Creative & Media

README.md

Original

PyChord

PyChord

PyPI Python versions Build Status Documentation Status License: MIT

Overview

PyChord is a pure-Python library for working with musical chords. It parses chord names, lists component notes, transposes chords and progressions, and finds chords from a set of notes.

Installation

PyChord supports Python 3.11 and above.

$ pip install pychord

Basic Usage

Create a chord

>>> from pychord import Chord
>>> c = Chord("Am7")
>>> c
<Chord: Am7>
>>> c = Chord("Am7/G")
>>> c.root, str(c.quality), c.on
('A', 'm7', 'G')

Unknown chord names raise ValueError:

>>> Chord("Cfoo")
Traceback (most recent call last):
  ...
ValueError: Unknown quality: foo

Transpose a chord

>>> c = Chord("Am7/G")
>>> c.transpose(3)
>>> c
<Chord: Cm7/Bb>

Pass a key as the second argument to control whether sharps or flats are used:

>>> c = Chord("C")
>>> c.transpose(1)
>>> c
<Chord: Db>
>>> c = Chord("C")
>>> c.transpose(1, "D")
>>> c
<Chord: C#>

Get component notes

>>> c = Chord("Am7")
>>> c.components()
['A', 'C', 'E', 'G']
>>> c.components_with_pitch(root_pitch=3)
['A3', 'C4', 'E4', 'G4']
>>> c.components(visible=False)  # semitones from C
[9, 12, 16, 19]

Compare chords

>>> Chord("C") == Chord("D")
False
>>> Chord("C#") == Chord("Db")
True

Find chords from notes

>>> from pychord import find_chords_from_notes
>>> find_chords_from_notes(["C", "E", "G"])
[<Chord: C>]
>>> find_chords_from_notes(["F#", "A", "C", "D"])
[<Chord: D7/F#>]
>>> find_chords_from_notes(["F", "G", "C"])
[<Chord: Fsus2>, <Chord: Csus4/F>]

Chord progressions

>>> from pychord import ChordProgression
>>> cp = ChordProgression(["C", "G/B", "Am"])
>>> cp
<ChordProgression: C | G/B | Am>

>>> cp.append("Em/G")
>>> cp
<ChordProgression: C | G/B | Am | Em/G>

>>> cp.transpose(+3)
>>> cp
<ChordProgression: Eb | Bb/D | Cm | Gm/Bb>

>>> cp[1]
<Chord: Bb/D>
>>> len(cp)
4

>>> cp.insert(1, "Fm")
>>> cp.pop()
<Chord: Gm/Bb>
>>> cp + ChordProgression(["Fm", "Bb7"])
<ChordProgression: Eb | Fm | Bb/D | Cm | Fm | Bb7>

Advanced Usage

Create a chord from a scale degree

>>> Chord.from_note_index(note=1, quality="", scale="Cmaj")  # I of C major
<Chord: C>
>>> Chord.from_note_index(note=3, quality="m7", scale="Fmaj")  # IIIm7 of F major
<Chord: Am7>
>>> Chord.from_note_index(note=5, quality="7", scale="Amin")  # V7 of A minor
<Chord: E7>

Supported and custom chord qualities

All built-in qualities are defined in pychord/constants/qualities.py and can be listed with QualityManager().get_qualities().

You can add a new quality or override an existing one. The change applies process-wide to chords created afterwards; call load_default_qualities() to restore the defaults.

>>> from pychord import Chord, QualityManager
>>> Chord("C11").components()
['C', 'E', 'G', 'Bb', 'D', 'F']

>>> quality_manager = QualityManager()
>>> quality_manager.set_quality("11", ("1", "3", "5", "b7", "11"))
>>> Chord("C11").components()
['C', 'E', 'G', 'Bb', 'F']

>>> quality_manager.load_default_qualities()

Inversions

Append /N to a chord name for its Nth inversion. You can also add a bass note after another slash:

>>> Chord("C/1").components() # First inversion of C
['E', 'G', 'C']
>>> Chord("C/2").components() # Second inversion of C
['G', 'C', 'E']

>>> Chord("Cm7/3/F").components() # Third inversion of Cm7 over F
['F', 'Bb', 'C', 'Eb', 'G']

Examples

Development

Development tools are declared as dependency groups in pyproject.toml (requires pip 25.1 or later).

$ pip install -e . --group dev

# Run tests with coverage
$ coverage run -m unittest -v && coverage report

# Lint, format and type check
$ ruff check pychord test examples
$ ruff format --check pychord test examples
$ mypy pychord

# Build the documentation
$ pip install -r docs/requirements.txt
$ make -C docs html

Links

Author

License

  • MIT License

The logo is made from Freepik.