Boodler: Installation

Prerequisites

Boodler can generate audio output to several destinations, each of which is defined by a driver module:

• file -- write file containing raw sample output
• stdout -- write raw sample output to stdout
• oss -- Open Sound System
• esd -- Enlightened Sound Daemon
• alsa -- Advanced Linux Sound Architecture
• macosx -- MacOSX CoreAudio
• vorbis -- write Ogg Vorbis file
• shout -- Shoutcast or Icecast source
• lame -- write MP3 file with LAME encoder

The contents of the archive

./setup.py

A script which compiles and installs Boodler on your machine.

./script/boodler.py

The Boodler program itself. This Python script starts up the Boodler engine.

./script/boomsg.py

A simple script for sending network events to Boodler.

./src/boodle/*.py

The boodle Python package. This contains several Python modules which are used by Boodler.

./src/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.

Setting up your environment

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.)

You may also want to make sure that Python's script directory is in your PATH. On most Unix systems, this will be /usr/local/bin. However, on MacOSX, it is the (somewhat unwieldy) /System/Library/Frameworks/Python.framework/Versions/Current/bin.

Building Boodler

1. Type python setup.py build.

   This tries to figure out the configuration of your system, and compiles the Boodler modules which can be compiled.

2. Type sudo python setup.py install.

   This installs Boodler in the system's Python directory. The sudo command will ask you for your password, which the setup script needs to write to a system directory. If you want to install to a different directory, you could instead type:

   python setup.py install --prefix directory

Testing Boodler out

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

• You're trying to build Boodler, 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.
• You install successfully, but you get the error "boodler.py: Command not found."
  • You probably don't have the Python script directory in your PATH. Try /usr/local/bin/boodler.py, or (on the Mac) /System/Library/Frameworks/Python.framework/Versions/Current/bin/boodler.py.
  • If you think you added one of those directories to your PATH, type rehash.
• The script aborts with the exception "ImportError: No module named cboodle_oss" or "No Boodler output driver has been selected."
  • The default output driver could not be built on your system. Type boodler.py --list-drivers to see a list, and then try adding -o driver to your Boodler command line.
• 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:

    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:

    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.