1. System requirements
----------------------

- X.Org >=7.1 (tested on 7.1 through 7.3)
- ALSA sound system, libasound >=1.0.13
- tested on Linux/x86 32 and 64 bit, other platforms *may* work; if you find
it does not work on your system, please complain to me, I intend to support as
many platforms as I can
- demo programs require libaudiofile >=0.2.6; make sure header files are
installed in order to be able to compile the demos (see configure output)

2. Installation and configuration
---------------------------------

1. Make sure you have X.Org server development headers installed (on Debian it's
the package xserver-xorg-dev).

2. Compile the server extension and client library using "make" (tweak the
Makefile if required)

3. Install the server extension, client libraries and headers using "make
install" (tweak the Makefile to install somewhere else besides /usr/lib/xorg
and /usr/local)

4. The extension requires pthread - this means that the X server must run with
a reentrant version of libc. The easiest way to achieve that is to rebuild the
X server with the -pthread flag, however on Linux systems you can simply
preload libpthread.

MAKE SURE YOU THAT THE X-SERVER ALWAYS USES A REENTRANT LIBC (either by
rebuilding or by preloading the library) as long as you load the audio
extension into the server. Unfortunately the extension *will* load without a
warning even if you neglect this (because libasound is implicitly linked
againts libpthread), but it *will* crash with obscure errors.

Linking with (or preloading) libpthread does not have any ill side effects;
in theory it incurs a performance penalty, but at least on Linux it is so small
that I have been unable to measure it. YMMV and I am interested in reports.

You can run the "check-xorg-server.sh" script 

4. Add the following line to the "Module" section of your /etc/X11/xorg.conf:

	Load "audio"

5. Restart the X server

6. Compile the sample programs in the demo/ subdirectory, or write your own
audio programs

7. If you want to use the ALSA plugin, copy the file
  alsa-plugin/libasound_module_pcm_xaudio.so
to
  /usr/lib/alsa-lib/libasound_module_pcm_xaudio.so

and add the following lines to ~/.asoundrc:

  pcm.xaudio {
    type xaudio
  }

If you want to use xaudio as default audio device, just add:

  pcm.!default {
    type xaudio
  }

Programs that are known to work using the ALSA plugin are: xmms, vlc, all
ALSA sample programs. Programs that are known *not* to work include: Flash
player.

3. Demo programs
----------------

You can compile a few demo programs by executing

	make demo

The program "xaudiodev" lists audio devices attached to your X server
and allows you to change the "default" device used by audio applications.
If you have libaudiofile installed, then two programs "player" and
"shmplayer" will be compiled as well. They can be used to play back
WAV files (or any other file type understood by libaudiofile) through
the X server. "player" will stream the audio data through the X protocol,
while "shmplayer" will setup a shared memory segment.

4. Audio manager
----------------

The extension allows a separate program to act as an "audio manager";
its job is similiar to the window manager in that it instructs the server
how to multiplex multiple clients to a single audio device. This
distribution contains a very primitive sample audio manager that you
can compile using

	make am

Future project revisions will contain a vastly improved audio manager that
is currently being written from scratch.

5. If it doesn't work...
------------------------

... or if it does and you want to tell me, feel free to contact me!

Helge Bahmann <hcb@chaoticmind.net>