
Q-Audio
=======

This package contains three modules to write digital audio applications in the
Q programming language:

- The audio module implements a (near-)realtime audio interface on top of Phil
  Burk's PortAudio library v19 (http://www.portaudio.com/). To build this
  module, you must have libportaudio installed, which must be built from cvs
  sources (nightly tarballs of the v19 cvs sources are available on
  http://www.portaudio.com/). (Please note that PortAudio v19 is *really*
  required; Q-Audio does *not* work with PortAudio v18 any more.)

- The sndfile module allows you to access sound files in various formats using
  Erik de Castro Lopo's libsndfile library V1.0 or later. To build this
  module, you must have libsndfile installed, which is available at
  http://www.mega-nerd.com/libsndfile/.

- The wave module provides basic operations for creating and manipulating wave
  data, including operations to convert sample rates, to calculate Fourier
  transforms and to display wave data in a GGI visual. To build this module,
  you need Erik de Castro Lopo's libsamplerate (http://www.mega-nerd.com/SRC/),
  libfftw3 (http://www.fftw.org/) and the ggi module (contained in the Q base
  package).

A simple graphical audio player (audio_player.q) is also included. This
program also uses the tk module, hence Tcl/Tk must be installed as well (any
Tcl/Tk version >=8.0 should do).

Q-Audio 2.x is now based on PortAudio v19, which adds support for ALSA and
Jack on Linux systems and ASIO on OS X and Windows. Due to changes in the
PortAudio API, the new version is not fully compatible with Q-Audio 1.x.
However, most existing applications should work with minimal or no changes.
The API changes affect the device enumeration mechanism (see the description
of the audio_drivers and audio_devices functions in audio.q for details), and
the open_audio_stream function (the optional NBUFS parameter of the INFO
argument is not supported any more). Moreover, the draw_wave module has been
replaced by the new wave module, which contains a lot of additional operations
for manipulating wave data.

At the time of this writing, the package has been tested on Linux and
Windows. Other UNIX systems supported by PortAudio v19 should work, too, but
might require some fiddling.

The package is distributed under the GPL V2 (see COPYING), and requires the Q
programming system, which can be found at the Q homepage:

	http://q-lang.sourceforge.net.

Make sure you get Q version 7.0 or later. Under the above URL you'll also find
the latest Q-Audio sources and binary packages.


INSTALLATION
============

To install from the sources, get libportaudio, libsamplerate, libsndfile and
libfftw3 and install them on your system (these should be readily available in
most Linux distributions, except PortAudio v19 for which we provide RPMs on
the Q homepage). Then run

	./configure --prefix=/usr && make && make install

(assuming your Q installation lives under /usr).

Binary packages for Linux (RPM) and Windows (MSI) are available from the Q
homepage.


SYSTEM-SPECIFIC NOTES
=============== =====

FREEBSD
-------

You probably have to add some compilation options s.t. the compiler finds
includes and libraries in /usr/local. Also make sure to link with the c_r
library (FreeBSD pthread replacement). (Recent FreeBSD versions might now
include a "real" pthread library, in this case you can omit this flag.) E.g.:

	CFLAGS="-I/usr/local/include -L/usr/local/lib" \
	./configure --with-pthread=-lc_r

(Add other compilation flags like -O3 to CFLAGS as needed.)

OS X
-- -

With older OS X versions you might have to disable Apple's "smart"
preprocessor to get the sources to compile. Configure as follows:

	CFLAGS=-no-cpp-precomp ./configure --prefix=/usr

WINDOWS
-------

A binary package is available from the Q homepage. The default implementation
uses the Windows MME driver. If you have DirectX installed, you might get
better latencies with the DirectSound driver. To these ends, rename
audio_ds.dll in the Qpad/lib directory to audio.dll (after removing or
renaming the default audio.dll).


USAGE
=====

To use the Q-Audio functions, simply import audio.q, sndfile.q and/or wave.q
in your script. See the source scripts for a description of the provided
functions. Some basic examples can be found in the audio_examp.q script.

The graphical player can be invoked on Unix systems using the shell command
`audio_player filename' where `filename' is the name of a sound file in one of
the formats supported by libsndfile. You can also invoke the player from a Q
script by importing audio_player.q and invoking the `play' function with the
name of a sound file as a string argument.


Enjoy! :)

January 2008
Albert Graef
ag@muwiinfa.geschichte.uni-mainz.de, Dr.Graef@t-online.de
http://www.musikwissenschaft.uni-mainz.de/~ag
