ComParser source code

ComParser
index

	ComParser	1.42
	source code

ComParser is written in platform independant ISO/ANSI C as far as possible. Platform dependant code (for audio, midi, and user i/o) is kept in separate files and directories, away from the core ComParser code, which consists of:

PREP: audio preprocessor object. Reads in chunks of audio and yields feature vectors.
AVALANCHE: avalanche object for spatiotemporal recognition. It processes feature vectors and may trigger statetransitions in the parenting NETWORK during score-following.
NETWORK: larger structure containing one or more AVALANCHEs in sequential but also parallel order. Internal network structure is limited to 'railroad tracks' for now.

The commandline version of ComParser relies on Portaudio for realtime audio input. In the current implementation, the callback routine forms the background thread that runs the preprocessing layer, while the foreground thread, which also handles incoming MIDI events and the communication with the user, runs our spatiotemporal layer.

Under UNIX, this approach works fine (foreground process does not get interrupted too much). On the Macintosh, however, the spatiotemporal process may get hindered by concurrent processes (user-clicks, mouse, MacOS, other applications, etc). So for the Macintosh implementation we'd better move the avalanche-code to the background (in which case an overload-protection must be built in), or a separate, third thread must be created for it.

Background thread:
(Portaudio callback routine)
-	Realtime audio input in chunks of 512, 1024 or 2048 sampleframes, at any user-selectable samplerate).
-	Apply 100% overlapping Hamming window (windowsize = 1024 samples).
-	Perform 1024, 2048, or 4096 point, real-input, FFT (always yielding 513 squared magnitudes (any higher bins are thrown away)).
-	Reorganize FFT output on to a (more or less) logarithmic frequency scale with the 'varidist' or 'equidist' algorithm. For example 27 equidist bands (minor thirds) or 60 varidist bands (slightly narrowing, from major third up to minor second).
-	Include some more linear measurements like RMS and peak magnitude and normalize the composite input vector.
-	Store vectors in a large circular buffer in RAM (storage for 1 hour just takes some Megabytes).

Foreground thread:
-	Run the following network which reads from the large circular buffer in RAM that is filled by the background process.
-	Perform simultaneous audio recording to file (again large circular buffer in RAM that is filled by the background process).
-	Send out MIDI messages when audio fragments are recognized.
-	Process user commands from the console.
-	Process incoming MIDI events.
-	In case of errors, report these on the console (or file).

fig.3: Preprocessing and spatiotemporal layers are run as separate processes.

MIDI i/o has been implemented for Silicon Graphics IRIX and for Apple Macintosh (OS 7,8,9) OMS. Stephane Letz contributed MidiShare support, which may be helpfull for the Linux, Windows, and OSX implementations. Many thanks!

Contrary to the standalone version of ComParser, the PD external runs both the preprocessor and the neural network in the same thread.

Project guidelines / standards / choices made

Standard C is the language of choice.
If C++ may sometimes be necessary (for PortAudio with ASIO for instance), so be it.
We use an object-oriented C style (idiom?) with 'symmetrical' constructors and destructors.
Global variables should be banned altogether, we don't mind long argument-lists.
Very simple user interfaces and APIs are the ultimate goal.
We don't want to add many features. We try to keep it a 'high end' program with as less as possible options and parameters for the user to specify.
No graphical user interface (we use PD or jMAX for that).
No automatic configuration tools (no ./configure, autoconf, automake, etc.). There is only 1 makefile and it can easily be configured manually. We'll try to keep it human-readable.
No platform-optimizations that pollute the code (the author uses this software on a 10-year old Silicon Graphics machine, using only some percents of CPU, so efficiency is less a concern).
Except for the makefile, no TAB characters should be present in any of the sourcefiles, headers or documentation.
Documentation is written manually (not generated) in HTML code that conforms to the W3C standards.
Syntaxes of (text)files generated and parsed by the software should be defined in EBNF.

Download source code

The latest version of ComParser may be downloaded from http://kmt.hku.nl/~pieter/SOFT/CMP.

	CMP1.42.tar.gz	Complete ComParser sources, binaries and documentation, version 1.42, tarred and gzipped (about 5 Megabytes).
After unpacking this, subdirectory '/src' should look something like this (below, files can also be viewed or downloaded individually):
	aiff	To read and write audiofiles in AIFF format (endian-safe).
	CMP.c	Main() for the standalone ComParser.
	CMP.h	Version number, included by both the standalone ComParser and the PD external.
	CMP_audiorecord.c	Record audiofile while following (handy during rehearsels with musicians).
	CMP_audiorecord.h	Headerfile.
	CMP_avalanche.c	To write and read avalanche files.
	CMP_avalanche.h	Headerfile defining memory and file structures.
	CMP_network.c	To load network files in memory (linked list management).
	CMP_network.h	Headerfile defining internal memory structure and the network file format.
	CMP_portaudio.c	Realtime analysis object (wrapping the PREP with PortAudio).
	CMP_portaudio.h	Datastructures and constants for realtime audio analysis based on PortAudio.
	CMP_prep.c	Implements preprocessing object (delivers feature vectors).
	CMP_prep.h	C API header for audio preprocessor.
	console/	Platform specific code for polling console-input (done SGI and Mac). Quite clumsy, actually... We'd better create a separate 3rd thread for the spatiotemporal layer, instead of avoiding blocking fgets-calls.
	fft/	FFT code and code-generators from Eyal Lebedinsky.
	gt/	Minimal graphic toolkit for drawing and writing (not reading) JPG-files. Incorporates the compression-part of the JPEG-library from the Independent JPEG Group (version 6b, 27-Mar-1998). Include source gt/gt.c in the compiler-project.
	midi/	MIDI API. Support for SGI and Mac-OMS and a generous gift from Stephane Letz for MidiShare support.
	pd	The comparser~ external for Pure Data (sourcecode, PD-helpfile plus precompiled binaries).
	portaudio	Copy of the portable audio library by Phil Burk and Ross Bencina (renamed 'index.html'), version 18 (CVS-patch).
	makefile	To compile the standalone program and the PD-external under IRIX, Linux and Mac OSX.
	macCW.sit.hqx	To compile on Apple Macintosh, OS 7, 8 or 9. Contains a projectfile for the Metrowerks Codewarrior compiler, version 5 (IDE version 4.0); a picture resource; and some additional sources (for strdup(), usleep() etc).

Older versions

Some of the older versions are kept available.

CMP0.68.tar.gz The first successfull attempts from 2002.
CMP1.00.tar.gz After returning from Italy (concerts and masterclass) summer 2003.
CMP1.25.tar.gz Shortly after the concert in Eindhoven, april 2004.
CMP1.30.tar.gz Backup of work done in spring 2004 (just before the PD-external).

All versions up to 1.30 compile under IRIX and Mac OS 7.6 to 9 and use the portaudio v18 API. All tarred and gzipped packages contain full sources, documentation and some precompiled binaries.

Contributions

CaseyMarshall_feb2003 for version CMP 0.68 on linux by Casey Marshall.
You may also have a look at http://metastatic.org/source/comparser/.
CMP0.68.linux.patch for version CMP 0.68 on linux by Simon de Bakker.