1.1 --- a/djm-fix.cpp	Mon Dec 21 16:44:39 2020 +0100
     1.2 +++ b/djm-fix.cpp	Mon Jan 04 00:15:56 2021 +0100
     1.3 @@ -32,9 +32,53 @@
     1.4  	std::cerr << "interrupt()" << std::endl; // TODO: do not mess STDIO
     1.5  }
     1.6  
     1.7 +/**
     1.8 + * The support for Pioneer DJ DJM-250MK2 (an external USB sound card / mixer) was added to the Linux (kernel) by these patches:
     1.9 + *
    1.10 + *  - https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/sound/usb?id=73d8c94084341e2895169a0462dbc18167f01683 (playback)
    1.11 + *  - https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/sound/usb?id=14335d8b9e1a2bf006f9d969a103f9731cabb210 (recording)
    1.12 + *  - https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/sound/usb?id=cdc01a1558dedcee3daee7e1802d0349a07edb87 (mixer setup)
    1.13 + *
    1.14 + * These patches are enough for playback and for recording from post CH faders.
    1.15 + *
    1.16 + * However this mixer is somehow incapacitated and if we want to record the raw signal from the PHONO or LINE channels,
    1.17 + * we only get silence. This feature is important for DVS (Digital Vinyl Systems) setups where
    1.18 + * the timecode signal from special control vinyls flows from mixer to the computer
    1.19 + * where it is interpreted in a software like MIXXX and used for controlling the playback of files on our computer.
    1.20 + * The signal (usually music) from these files flows back to the mixer and then to speakers and headphones.
    1.21 + *
    1.22 + * To make this work and enjoy all the features of the device we have bought, we need to tell the mixer that we
    1.23 + * want the signal instead of silence on given channels. And this is the purpose of the djm-fix utility and
    1.24 + * it is done by sending some magic packet to the mixer.
    1.25 + *
    1.26 + * Implementation of this magic in the AlsaBridge.cpp file is based on publicly available documentation
    1.27 + * that can be found at <https://mixb.me/CDJHidProtocol/hid-analysis/handshake.html>.
    1.28 + * This page pointed me to the proper hash function (according to the constants, it is bit uncommon but publicly known Fowler–Noll–Vo hash function, FNV)
    1.29 + * and some magic bits. I wrote this standalone C++ program that talks with the mixer over MIDI SysEx messages and does the magic.
    1.30 + *
    1.31 + * When this program is started, it finds the mixer and makes it fully working.
    1.32 + * It needs to be running all the time, otherwise we will get silence on the PHONO/LINE channels again.
    1.33 + *
    1.34 + * Install dependencies:
    1.35 + *   apt install mercurial make pkg-config g++ libasound2-dev    # in Debian or Ubuntu (it will be similar in other distributions)
    1.36 + *
    1.37 + * Download djm-fix:
    1.38 + *   hg clone https://hg.frantovo.cz/midi/djm-fix/               # primary source
    1.39 + *   hg clone https://hg.globalcode.info/midi/djm-fix/           # or we can use this mirror
    1.40 + *
    1.41 + * Compile:
    1.42 + *   make                                                        # we can skip this step, it will be compiled on the first run
    1.43 + *
    1.44 + * Run:
    1.45 + *   make run
    1.46 + *
    1.47 + * Stop:
    1.48 + *   press Ctrl+C
    1.49 + */
    1.50 +
    1.51  int main(int argc, char**argv) {
    1.52  	std::string deviceName = argc == 2 ? argv[1] : "hw:1"; // FIXME: parse CLI options + automatic device search
    1.53 -	
    1.54 +
    1.55  	signal(SIGINT, interrupt);
    1.56  	std::unique_ptr<djmfix::DJMFix> djmFix(djmfix::create());
    1.57  	std::unique_ptr<djmfix::alsa::AlsaBridge> alsaBridge(djmfix::alsa::create(djmFix.get(), deviceName));