The HarmTrace package

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.



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]


Versions0.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, 2.2.1
Dependenciesarray, 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]
Copyright(c) 2010--2013 Universiteit Utrecht, 2012--2013 University of Oxford 2016 Chordify BV
AuthorW. Bas de Haas and Jose Pedro Magalhaes,
Home page
UploadedMon Aug 7 14:17:57 UTC 2017 by BasDeHaas


Maintainers' corner

For package maintainers and hackage trustees

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