PyChoReLib for Python 2.3

Why this project?

  • This projection was born out of enthusiasm
    • Enthusiasm about music and different ways to describe it using one of many music theories.
    • Enthusiasm about the Python programming language.

  • This project was born out of frustration
    • Existing open source auto-accompaniment systems typically specify chords using chord names
      despite lists of note names feeling more natural to me.
    • Not many people have open sourced their code to recognize chords --- or if they have, they hid it well.
      Many projects, on the other hand, have some plans to add chord recognition capabilities to their system in the "future".


  • The library provides in a number of classes which offer the following functionality:
    • transformation of a list of note names to a chord name:
      e.g. ['a', 'c#', 'e', 'g'] => A7
      Inversions are indicated using a slash and the root note.
      e.g. ['e', 'g', 'a', 'c#'] => A7 / E
      Chord recognition (for pragmatic reasons) ignores the difference between e.g. 'f#' and 'gb'.

    • Alternatively one can also recognize intervals. Recognition here does take
      into account the difference between e.g. 'f#' and 'gb'.
      e.g. ['c','f#'] => 'augmented fourth' or ['c', 'gb'] => 'diminished fifth'

    • Intervals and chords can be transposed:
      e.g. ['c','e'] transposed to 'f#' => ['f#','a#']
              ['c','e'] transposed to 'gb' => ['gb','bb']

  • For now, internally the library works with note names 'a', 'b', 'c', 'd', 'e', 'f', 'g'
    and modifiers '#' (sharp), 'b' (moll), 'x' (double sharp), 'bb' (double moll)

Current features

PyChoReLib in its current form is very much in Alpha-state. Nevertheless:
  • PyChoReLib can already recognize and name hundreds of chords.
  • New chords can be taught to the system "by example".
    e.g. teach the system that ['c','e','g'] is called 'C', and using its built-in music theory
    knowledge it immediately knows how to recognize and label all major
    chords in all inversions or (more generally) permutations.
  • Once chord recognition definitions have been taught to the system,
    they can be saved to file, allowing for quick initialization of the recognizer.
  • Intervals and chords can be transposed.
  • PyChoReLib comes with two demo programs:
    • tests the functionality offered by the library using Python's unit testing framework
    • real-time converts midi input from midi devices (ALSA for linux, MME for win32) to chord names
      NOTE: This latter program needs the PyPortMidi software package to be installed and running.

Planned features

  • Extending the chord recognition database with new chord patterns.
  • Build in more music theory knowledge to automatically recognize more chords, while requiring less teaching.
    (Based on matching notes to scales?)
  • Add functionality to suggest a scale which can be used to improvise over a chord
  • Extensions to the midiinput proof of concept:
    • a teach mode in which the system can be taught new chords interactively
    • a GUI
    • proof of concept auto-arranger capabilities
  • Add support for alternative note names
(As you may have guessed, I suck at web design, which explains why this pages loads so fast and displays properly in most browsers.)
Please use the sourceforge infrastructure for communication about this project.
There be screenshots!