C++ Constant-Q

h1. Wiki

{{>toc}}

 * [[Speed]] tests and optimisations

 * [[VampPlugin]] requirements / possibilities

h2. The method

*The method to be implemented* is that from "Anssi's Constant-Q Toolbox page":http://www.eecs.qmul.ac.uk/~anssik/cqt/.

 * The MATLAB toolbox reference implementation is "here":/projects/constant-q-toolbox.

 * The "QM-DSP":/projects/qm-dsp library also contains a Constant-Q implementation: there is a Vamp plugin of it in the "QM Vamp Plugins":/projects/qm-vamp-plugins set. I believe it is based on the method of Brown and Puckette. Our version isn't very good. Among other things, we should aim to produce an improved plugin. But this one may be useful as an extra reference.

*Has anyone already made one* corresponding directly to the Schörkhuber/Klapuri method? We don't want to duplicate effort. And if someone has, why don't I know about it? -- can we do anything to help make it more universally known?

*What other modern methods* exist in C++?

Emmanouil: there is a Dec 2011 discussion on music-ir about CQT implementations. It seems that there is a C++ GNU GPL 3 code for a forwards CQT available in the Qitch plugin for SuperCollider at http://sourceforge.net/projects/sc3-plugins/ (which however implements Judith Brown's old algorithm)

h2. What we want it for

The immediate requirement is as the first step in implementing Emmanouil Benetos and Simon Dixon's "music transcription":http://www.mitpressjournals.org/doi/abs/10.1162/COMJ_a_00146 method for a Vamp plugin.

But the reason we aren't using the QM-DSP constant-Q implementation is that it simply isn't good enough, and that means it isn't really good enough for the rest of the world either. We should make a better one to improve upon the existing QM Vamp Plugin as well.

The method described is invertible with some signal loss -- we should implement the inversion as well.

h2. Implementation notes

The Schörkhuber/Klapuri method has (at least) three useful qualities:

 # It's mathematically diligent. Decisions such as kernel and window shape are explained and supported in the paper.

 # There is an open source MATLAB implementation available, and others have tested it.

 # It is (somewhat) invertible. 

Also the nature of the constant-Q transform is such that it should be possible to test it using relatively little data.

This makes it a good case for implementation using a unit testing or test-first regime:

 # Mathematical support will help in generating synthetic test cases

 # The existing implementation gives a reference at each step (although we need to be careful not to trust it implicitly)

 # Invertibility means we can test the forward-backward transforms.

h2. Goals

This version needs to be:

 # *Correct* -- a lot of people have looked at the output of the existing QM-DSP constant-Q transform and said "hm, that doesn't look very good" but nobody who really knows their stuff has ever taken the time to figure out what's wrong with it. This sort of review after the fact just doesn't seem to happen. We should aim to see that it's right as we go along, with a suitable testing regime.

 # *Fast* -- the method has the potential to be pretty fast, we should make the most of it

 # *Compact* -- avoiding hard-to-satisfy library dependencies so that people can apply the code easily

h2. General procedure

 # Pick apart the MATLAB and implement it in another high-level language. I'm using Yeti with "May":/projects/may, because it has very strong typing and is easy to write tests for, so it should be possible to have a high confidence of getting correct code -- and because I like it. The main thing is to target a language without the same built-in syntax as MATLAB for matrix and complex arithmetic, so that you actually have to understand how the original algorithm works. Once I have a version in another high-level language that produces the same results, I can be confident I have understood (at some level) how the toolbox code works.

 # Refactor and introduce unit tests in addition to the high-level tests that compare results against the original MATLAB.

 # Port across the test structure and reimplement the code into C++.

Is this any more efficient or effective than porting directly to C++? Not sure, let's find out -- mostly in the past I've gone straight to C++ so this is a novelty for me.

h2. Test material

 * [[SketchesAndPlots|Sketches and Plots]]

 * [[SyntheticTest|Small synthetic test]]