Boodler: Installation

Boodler uses the standard Python distutils system for building and installation.

Prerequisites

First, download and unpack the source code from the Boodler web site.

Boodler is written in Python; you must have a Python interpreter installed on your system in order to run it. (Python version 2.3.5 or later is recommended. No, it doesn't work in Python 3.)

Boodler can generate audio output in any of several forms, 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

Boodler will compile all of these drivers that it can find libraries for. If you have a Mac, CoreAudio is available if you have the Mac Developer Tools installed. On Linux, one of OSS, ESD, or ALSA is likely to be available.

The contents of the archive

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

./setup.py

A script which compiles and installs Boodler on your machine.

./setup.cfg

If you want to modify the installation process, you can put changes here.

./script/boodler

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

./script/boodle-mgr

A script for installing and managing Boodler soundscape components.

./script/boodle-event

A simple script for sending network events to Boodler.

./src/...

The source code for Boodler. This includes Python code, and also some native C code which is needed to resample sound data efficiently.

./etc/...

A few optional configuration files.

./doc/*.html

This documentation.

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

Try this command:

boodler --testsound

You should hear a quick melody 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: Command not found."
  • You probably don't have the Python script directory in your PATH. Try /usr/local/bin/boodler, or (on the Mac) /System/Library/Frameworks/Python.framework/Versions/Current/bin/boodler.
  • 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 --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 --device /dev/whatever --testsound
    

• 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.
  • 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. (This is unlikely on a modern desktop machine, but it could happen on an older or low-power device.)
  • 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 --define buffercount=12 --testsound
    

  • 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