HarmTrace: Harmony Analysis and Retrieval of Music

[ gpl, music, program ] [ Propose Tags ]

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]


Note: This package has metadata revisions in the cabal description newer than included in the tarball. To unpack the package including the revisions, use 'cabal get'.

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees


Versions [RSS] 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 CHANGELOG.md
Dependencies array, base (>=4.2 && <5), binary (>=0.6.4), cmdargs (>=0.10.1), deepseq, Diff (>=0.1 && <0.2), 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.0-only
Copyright (c) 2010--2013 Universiteit Utrecht, 2012--2013 University of Oxford, 2017 Chordify BV
Author W. Bas de Haas and Jose Pedro Magalhaes
Maintainer haskelldevelopers@chordify.net
Revised Revision 2 made by BasDeHaas at 2017-10-03T11:32:11Z
Category Music
Home page https://github.com/haas/harmtrace
Uploaded by BasDeHaas at 2017-08-07T14:18:26Z
Reverse Dependencies 1 direct, 0 indirect [details]
Executables harmtrace
Downloads 13188 total (14 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs not available [build log]
All reported builds failed as of 2017-08-07 [all 2 reports]

Readme for HarmTrace-2.2.1

[back to package description]


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/