PyChord

Overview

PyChord is a Python library to handle musical chords.

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>
>>> print(c.info())
Am7
root=A
quality=m7
on=

Transpose a Chord

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

Get component notes

>>> c = Chord("Am7")
>>> c.components()
['A', 'C', 'E', 'G']
>>> c.components_with_pitch(root_pitch=3)
['A3', 'C4', 'E4', 'G4']

Compare Chords

>>> Chord("C") == Chord("D")
False
>>> Chord("C#") == Chord("Db")
True
>>> c = Chord("C")
>>> c.transpose(2)
>>> c == Chord("D")
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>]

Create and handle 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>

Advanced Usage

Create a Chord from note index in a scale

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

Overwrite the default Quality components with yours

>>> 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']

Inversions

Chord inversions are created with a forward slash and a number indicating the order. This can optionally be combined with an additional forward slash to change the bass note:

>>> 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 with an added F bass
['F', 'Bb', 'C', 'Eb', 'G']

Examples

• pychord-midi.py - Create a MIDI file using PyChord and pretty_midi.

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

• PyPI
• GitHub
• Documentation

Author

• Yuma Mihira

License

• MIT License

The logo is made from Freepik.