## Boodler: Installation

Boodler does not, as yet, have a formal installation procedure. The source archive (boodler.tar.gz) unpacks into a single directory tree; it is simplest to run Boodler from there.

### Prerequisites

Boodler is written in Python; you must have a Python interpreter installed on your system in order to run it. (Python version 1.5.2 is required. Later versions of Python should work as well.)

Boodler can be built to use either the OSS sound driver interface, the ALSA sound driver interface, or the ESD (EsounD) sound server library. (On MacOSX, it can use the standard CoreAudio interface or the OSX port of ESD.) It can also write raw sound output to a file.

### The contents of the archive

If you list the source directory, you will see the following arrangement:

./configure.py
  A script which configures the Boodler source to compile on your machine.
./boodler.py
  The Boodler program itself. This Python script starts up the Boodler engine.
./boomsg.py
  A simple script for sending network events to Boodler.
./boodle/*.py
  The `boodle` Python package. This contains several Python modules which are used by Boodler.
./cboodle/*.c
  The C source for the `boodle.cboodle` module. This module performs the resampling, linear interpolation, and mixing operations which are at the heart of Boodler. It is written in C for efficiency.
./effects/*.py
  The sound effects. Each Python module in this directory contains one or more `Agent` classes; each `Agent` class creates and controls an individual soundscape. When you start up Boodler, you select an `Agent` to run. (Note that this is a directory full of Python modules, but it is not a true Python package -- it lacks an `__init__.py` module.)
./doc/*.html
  This documentation.

You will also need the Boodler sound library, which is available as a separate download (boodler-snd.tar.gz).

### Setting up your environment

Download and uncompress the source archive and the sound library. (For example's sake, let us say that these are in `/home/zarf/src/boodler` and `/home/zarf/lib/boodler-snd` respectively.)

Boodler requires two environment variables to be set:

`BOODLER_SOUND_PATH`
  The directory containing the Boodler sound library. (`/home/zarf/lib/boodler-snd`, for example.)
`BOODLER_EFFECTS_PATH`
  The directory containing the Boodler sound effect modules. (`/home/zarf/src/boodler/effects`, for example.)

Either of these variables can also be given as a colon-separated list of directories, if you want to search in several places for either sounds or sound effects.

You will also need to have the `boodle` package in your Python path. The easiest way to do this is simply to cd to the source directory (`/home/zarf/src/boodler`) -- Python is always willing to load packages from the current directory. If you wish to run Boodler while in another directory, you can add the source directory to your `PYTHONPATH`.

### Building Boodler

1. Type python configure.py.

   (This tries to figure out the configuration of your system, and sets up Boodler to compile properly.)

2. Type make.

   (This compiles the C source code for `boodle.cboodle`, and copies the resulting module library to the `./boodle` directory.)

### Testing Boodler out

Try this command:

    python boodler.py play.OneSound pure/stereotest.aiff

You should hear a seven-note series of test tones -- first alternating between left and right channels, and then playing in both.

You can now begin using Boodler.

### If it doesn't work

- The `configure.py` program complains that none of Boodler's sound drivers are compatible.
  - Boodler currently recognizes five different interfaces to a machine's sound hardware:
    - OSS (the Open Sound System) is a low-level sound driver. If you build Boodler to use OSS, it will monopolize the sound hardware -- no other sound-producing program will be able to run.
    - ALSA (the Advanced Linux Sound Architecture) is a more modern and powerful sound driver. As with OSS, only one ALSA program can use the sound hardware at a time. (ALSA is designed to emulate OSS, so if your machine has ALSA installed, you can probably build Boodler using either the OSS or ALSA interfaces.)
    - ESD (EsounD, the "Enlightened Sound Daemon") is a more flexible system. Many programs can use the ESD sound interface on your computer at the same time. However, the ESD form of Boodler will use somewhat more CPU time. (Also, ESD is kind of junky and unsupported. I never liked it much.)
    - MACOSX (MacOSX CoreAudio) uses the CoreAudio framework. This is the configuration you will likely want under MacOSX. (Although ESD should also work, if you're running the MacOSX port of ESD.)
    - FILE is an interface that does not play sounds at all. Instead, it writes raw sound data to a file on disk. This may be useful. (I used it to generate the Boodler samples on the web site.)
    You can select one or the other by typing `python configure.py --driver alsa`, et cetera. To see which of them your computer supports, type `python configure.py --list`.
  - If your sound interface header files or libraries are in a non-standard location, you will have to configure Boodler to find them. Type `python configure.py --help` for details.
- You're trying to build Boodler (with the `make` command), and you see the error "Python.h: No such file or directory".
  - Probably you don't have the Python development package installed on your machine. This is the set of include files needed to compile C modules for Python.
  - If your OS uses RPM packages (Red Hat format), find the "python-devel" RPM package; if you use some other installation system, the name will be something similar. Make sure you get the headers that match your version of Python.
  - On MacOSX, you can either install Python via Fink, or download the Python source and build it yourself.
- The script aborts with the exception "ImportError: No module named cboodle".
  - The `boodle.cboodle` module does not exist. Did you forget to make?
- The script aborts with the exception "IOError: unable to initialize audio device".
  - The `boodle.cboodle` module was unable to open the sound device. The first line of the error message will have a more specific explanation.
- Boodler cannot initialize the audio device because `/dev/dsp` is not found.
  - You may have your sound device installed in a different location. You can use the `--device` argument to indicate the correct location:

        python boodler.py --device /dev/whatever play.OneSound pure/stereotest.aiff

- Boodler appears to hang forever, never producing any sound.
  - Some other program may be using the sound device.
  - When Boodler is built using the OSS or ALSA interfaces, it is a greedy beast and insists on monopolizing the sound device itself, the entire time it is running. When Boodler is built using ESD, it is willing to share with other ESD programs, but it is still possible for some other program to hog the device and prevent ESD from starting up.
- Boodler runs for a few seconds and then stops, but you hear no sound. (The stereotest sound is 2.8 seconds long.)
  - You need to mess around with your speakers, headphones, cables, or some other irritating piece of the real world.
- Most soundscapes skip or sound choppy.
  - Your computer is unable to keep up with Boodler's computation.
  - Run fewer applications at the same time as Boodler.
  - Try rebuilding Boodler using the `python configure.py --integer` configuration option. This reduces the number of floating-point operations, at the cost of less accurate volume fading.
  - If you are using MacOSX, increase the number of sound buffers, using the `--define buffercount=count` option. The default is 6; increasing it to 12 or 16 should help:

        python boodler.py --define buffercount=12 play.OneSound pure/stereotest.aiff

  - Get a beefier computer.
- You hear clipping noise (mild static) in some soundscapes.
  - You need to reduce the amplitude of Boodler's sound stream as it passes through your drivers. There are two ways of doing this:
  - Use a mixer application (such as `xmixer`, `amixer`, or `alsamixer`) to reduce the "PCM" component of your sound driver. You can compensate by turning up the "Master" component, or just turning up your speakers.
  - Or, use the `--master` argument to Boodler, giving it a master mixing volume less than the default of 0.5. Again, you can compensate with a mixer application or by turning up your speakers.

Return to Boodler docs index