# Introduction
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](http://www.mitpressjournals.org/doi/10.1162/COMJ_a_00209)_
37.4 (2013): 37-53.
([PDF](http://www.mitpressjournals.org/doi/pdf/10.1162/COMJ_a_00209))
Magalhaes, J. P., & de Haas, W. B. (2011, September). Functional modelling of
musical harmony: an experience report. In
_[ACM SIGPLAN Notices](http://dl.acm.org/citation.cfm?id=2034797&dl=ACM&coll=DL&CFID=792765209&CFTOKEN=90344854)_
(Vol. 46, No. 9, pp. 156-162). ACM.
([PDF](http://www.cs.uu.nl/groups/MG/multimedia/publications/art/icfp2011.pdf))
# Installation
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](
https://docs.haskellstack.org/en/stable/README/) 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
Commands:
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](http://ismir2005.ismir.net/proceedings/1080.pdf) 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)
[Piece[PD[D_1_1[S_1par_1[IIm_1[D:min]]][D_2_1[V7_2[G:7]]]]][PT[T_1_1[I_1[C:maj]]]]]
```
If you add `--print`, HarmTrace will render a .PNG image for you using
[http://ironcreek.net/phpsyntaxtree/](http://ironcreek.net/phpsyntaxtree/)