The HarmTrace package

[Tags:gpl, program]

HarmTrace: Harmony Analysis and Retrieval of Music with Type-level Representations of Abstract Chords Entities

We present HarmTrace, a system for automatically analysing the harmony of music sequences. HarmTrace is described in the paper:

[Skip to Readme]


Versions 0.1, 0.1.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 1.0, 2.0, 2.1, 2.2.0, 2.2.1
Change log
Dependencies array, base (>=4.2 && <5), binary (>=0.6.4), cmdargs (>=0.10.1), deepseq, Diff (==0.1.*), directory, filepath, ghc-prim (>=0.2), HarmTrace-Base (<1.2), instant-generics (>=0.6), ListLike (>=3.0.1), matrix (>=0.3.4), mtl, parallel (>=3), process (>=1.0), sox (>=, template-haskell (>=2.4 && <2.11), uu-parsinglib (>=2.7.4), vector (>=0.7) [details]
License GPL-3
Copyright (c) 2010--2013 Universiteit Utrecht, 2012--2013 University of Oxford, 2017 Chordify BV
Author W. Bas de Haas and Jose Pedro Magalhaes
Category Music
Home page
Uploaded Mon Aug 7 14:18:26 UTC 2017 by BasDeHaas
Updated Mon Aug 7 15:20:03 UTC 2017 by BasDeHaas to revision 1
Distributions NixOS:2.2.1
Downloads 3989 total (154 in the last 30 days)
0 []
Status Docs not available [build log]
All reported builds failed as of 2017-08-07 [all 2 reports]
Hackage Matrix CI


Maintainer's Corner

For package maintainers and hackage trustees

Readme for HarmTrace

Readme for HarmTrace-2.2.1


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