// Documentation (Doxygen) hook
/*! \mainpage KeyFinder library
 *
 * \section intro_sec Introduction
 *
 * `libkeyfinder` is a small C++11 library for estimating the musical key of digital audio. It is published under the GNU General Public License (GPL) version 3 or later.
 *
 * It was written by [Ibrahim Shaath](http://ibrahimshaath.co.uk/keyfinder/) who wrote it in 2011 as part of a master's thesis in computer science.
 * A [GUI application](https://github.com/ibsh/is_KeyFinder) to use it is available for [macOS](http://www.ibrahimshaath.co.uk/keyfinder/bins/KeyFinder-OSX-2-4.zip) and [Windows](http://www.ibrahimshaath.co.uk/keyfinder/bins/KeyFinder-WIN-1-25.zip), however that is no longer maintained and does not build on contemporary Linux distributions.
 *
 * In 2020, Ibrahim handed over maintenance of libkeyfinder to the [Mixxx DJ software](https://mixxx.org) team who incorporated it into Mixxx as of Mixxx 2.3.
 * If you want to discuss anything related to libkeyfinder with us, please get in touch on the [Mixxx Zulip chat](https://mixxx.zulipchat.com/#narrow/stream/109171-development/topic/KeyFinder).
 * Contributions are welcome by opening pull requests and issues on [GitHub](https://github.com/mixxxdj/libkeyfinder).
 *
 * \section example_basic Basic Example
 *
 * For the most basic use case, do something like this:
 *
 * ```
 * // Static because it retains useful resources for repeat use
 * static KeyFinder::KeyFinder k;
 *
 * // Build an empty audio object
 * KeyFinder::AudioData a;
 *
 * // Prepare the object for your audio stream
 * a.setFrameRate(yourAudioStream.framerate);
 * a.setChannels(yourAudioStream.channels);
 * a.addToSampleCount(yourAudioStream.length);
 *
 * // Copy your audio into the object
 * for (int i = 0; i < yourAudioStream.length; i++) {
 *   a.setSample(i, yourAudioStream[i]);
 * }
 *
 * // Run the analysis
 * KeyFinder::key_t key = k.keyOfAudio(a);
 *
 * // And do something with the result
 * doSomethingWith(key);
 * ```
 *
 * \section example_progressive Progressive Estimation Example
 *
 * Alternatively, you can transform a stream of audio into a chromatic representation, and make progressive estimates of the key:
 *
 * ```
 * KeyFinder::AudioData a;
 * a.setFrameRate(yourAudioStream.framerate);
 * a.setChannels(yourAudioStream.channels);
 * a.addToSampleCount(yourAudioStream.packetLength);
 *
 * static KeyFinder::KeyFinder k;
 *
 * // the workspace holds the memory allocations for analysis of a single track
 * KeyFinder::Workspace w;
 *
 * while (someType yourPacket = newAudioPacket()) {
 *
 *   for (int i = 0; i < yourPacket.length; i++) {
 *     a.setSample(i, yourPacket[i]);
 *   }
 *   k.progressiveChromagram(a, w);
 *
 *   // if you want to grab progressive key estimates...
 *   KeyFinder::key_t key = k.keyOfChromagram(w);
 *   doSomethingWithMostRecentKeyEstimate(key);
 * }
 *
 * // if you only want a single key estimate, or to squeeze
 * // every last bit of audio from the working buffer after
 * // progressive estimates...
 * k.finalChromagram(w);
 *
 * // and finally...
 * KeyFinder::key key = k.keyOfChromagram(w);
 *
 * doSomethingWithFinalKeyEstimate(key);
 * ```
 */
