Read Me

vamp-live-host -- activate events based on features of live audio
=================================================================

This is a simple program that listens to live audio, runs one or more
Vamp audio feature extraction plugins on that incoming audio, and
causes a configurable set of events to occur in close to real-time
based on the features extracted from it.

This program was intended as a proof of concept and as a tool for use
in one particular project.  It isn't a very comprehensive or well
written program.  A more serious alternative might be better written
using other tools that offer better control capabilities (such as Pd).

To use vamp-live-host, you will need an audio input (mono or stereo)
and a configuration file to describe the plugins you want to use and
the events you want to happen.

An example configuration file (test.xml) is provided that picks
different images based on the tempo and spectral centroid of the
audio.  (This is not a very useful example, and the images themselves
are not actually included -- you would need to edit the file or copy
over some suitable images to use it yourself -- but it illustrates the
idea.)  There are comments in the test.xml file that describe the
expected file format and the available conditions and actions.

Needless to say, vamp-live-host is only useful with Vamp plugins that
are causal, i.e. that produce output at the same time as receiving
input (rather than needing to look ahead or receive all their input
before they can produce any output).  The Aubio plugins and a number
of low-level feature extractors are good examples.


Compiling
---------

vamp-live-host uses Sonic Visualiser's code libraries to do some of
its work.  To build it, you must first have compiled (though not
necessarily installed) Sonic Visualiser.  The compiled Sonic
Visualiser source code tree should be found in a directory called
sonic-visualiser with the same parent as the current one.  Edit
vamp-live-host.pro if it is located elsewhere.

To build, you will also need Qt4 and the Qt4 qmake program.  Run qmake
and then make.

It is probably possible to build vamp-live-host on Windows, OS/X and
Linux, but it's only been tested on Linux.

For audio input, vamp-live-host supports the JACK audio server or
platform audio using PortAudio v18.


Author
------

vamp-live-host was written by Chris Cannam at the Centre for Digital
Music, Queen Mary, University of London.

vamp-live-host code copyright (c) 2006 Queen Mary, University of London.