Harmony Analysis and Retrieval of Music https://github.com/haas/harmtrace

Latest on Hackage:2.2.1

This package is not currently in any snapshots. If you're interested in using it, we recommend adding it to Stackage Nightly. Doing so will make builds more reliable, and allow stackage.org to host generated Haddocks.

GPL-3 licensed by W. Bas de Haas and Jose Pedro Magalhaes


HarmTrace (Harmony Analysis and Retrieval of Music with Type-level Representations of Abstract Chords Entities) is a system for automatic harmony analysis of music. It takes a sequence of chords as input and produces a harmony analysis, which can be visualised as a tree.

Music theory has been essential in composing and performing music for centuries. Within Western tonal music, from the early Baroque on to modern-day jazz and pop music, the function of chords within a chord sequence can be explained by harmony theory. Although Western tonal harmony theory is a thoroughly studied area, formalising this theory is a hard problem.

With HarmTrace we have developed a formalisation of the rules of tonal harmony as a Haskell (generalized) algebraic datatype. Given a sequence of chord labels, the harmonic function of a chord in its tonal context is automatically derived. For this, we use several advanced functional programming techniques, such as type-level computations, datatype-generic programming, and error-correcting parsers. Our functional model of harmony offers various benefits: it can be used to define harmonic similarity measures and facilitate music retrieval, or it can help musicologists in batch-analysing large corpora of digitised scores, for instance.

HarmTrace is covered in depth in the following papers:

de Haas, W. B., et al. "Automatic Functional Harmonic Analysis." Computer Music Journal 37.4 (2013): 37-53. (PDF)

Magalhaes, J. P., & de Haas, W. B. (2011, September). Functional modelling of musical harmony: an experience report. In ACM SIGPLAN Notices (Vol. 46, No. 9, pp. 156-162). ACM. (PDF)


Because the main authors of HarmTrace are are no longer affiliated with academic institutions and HarmTrace is only modestly maintained, installing Harmtrace can be a challenge. However, Stack helps considerably. One of the difficulties is that HarmTrace currently only build on a relatively old version of GHC, namely 7.10. Provided that you have intalled a Haskell system and pulled this repository, Stack should take care of it:

stack init --solver --install-ghc

stack build

Running HarmTrace

You can use Stack to run HarmTrace:

>>> stack exec harmtrace
harmtrace [COMMAND] ... [OPTIONS]
  Harmonic Analysis and Retrieval of Music

  parse      Parse files into harmonic analysis trees
  match      Harmonic similarity matching
  recognise  Recognise chords from audio files

  -r=file            File to read flags from
  -?      --help     Display help message
  -V      --version  Print version information

All modes have separate help pages:

>>> stack exec harmtrace parse -- --help
parse [OPTIONS]
  Parse files into harmonic analysis trees

  -g      --grammar=string    Grammar to use (jazz|pop)
  -c      --chords=string     Input chord sequence to parse
  -i      --file=filepath     Input file to parse
  -d      --dir=filepath      Input directory to parse all files within
  -o      --out=filepath      Output binary file to write parse results to
  -k      --key=filepath      Ground-truth key annotation file
  -x      --key-dir=filepath  Ground-truth key annotation directory
  -p      --print             Output a .png of the parse tree
  -s      --print-insertions  Show inserted nodes
  -r=file                     File to read flags from
  -?      --help              Display help message
  -V      --version           Print version information

You can parse a chord sequence with --chords the chord should be in Harte syntax suffixed with a ;INT indicating the duration of the chord and separated by spaces. The first 'chord' represents a key signature. For instance:

>>> stack exec harmtrace parse -- --grammar=jazz --chords="C:maj D:min;1 G:7;2 C:maj;1"
parsed 3 chords into 1 analysis tree(s)

If you add --print, HarmTrace will render a .PNG image for you using http://ironcreek.net/phpsyntaxtree/




  • Made HarmTrace compile again using Stack.
  • updated README.md
comments powered byDisqus