Boodler: Using It

First, make sure you have downloaded the Boodler source and sound library packages; compiled and installed Boodler; and set the necessary environment variables. (See Installing Boodler.)

The use of Boodler, in its simplest form, is, um, simple: 

boodler.py module.ClassName

...where module is one of the files in $BOODLER_EFFECTS_PATH (without the .py suffix), and ClassName is one of the Agent classes in that file. For example: 

boodler.py crows.ParliamentOfCrows

Most Agent classes produce an unending stream of sound, causing Boodler to run forever (or until you hit ctrl-C). Some agents, however, come to a conclusion and shut themselves down. If you tell Boodler to run such an agent, Boodler will exit when the agent is finished.

Running agent classes with arguments

Some Agent classes take additional options, which you can add to the command line after the class name. For example, 

boodler.py play.OneSound environ/droplet-bloink.aiff

play.OneSound is an agent which takes exactly one argument -- the name of a sound -- and plays it once, and then exits. (The sound is searched for in $BOODLER_SOUND_PATH.)

play.OneSound requires one argument -- you will get an error if you try to pass none (or two or more). Some Agent classes, however, have optional arguments -- or both mandatory and optional arguments. If you try 

boodler.py play.OneSoundOpts environ/droplet-bloink.aiff

...you will hear exactly the same "bloink" noise as in the previous example. However, play.OneSoundOpts takes up to three additional arguments: the pitch, the volume, and the stereo (left-right) shift. You may do 

boodler.py play.OneSoundOpts environ/droplet-bloink.aiff 0.5 0.75 -1.0

...to hear this sound played an octave lower, at 75% volume, and shifted entirely to the left speaker channel.

Some Agent classes take arguments which are themselves the names of other Agent classes. Try this: 

boodler.py manager.Simultaneous crows.ParliamentOfCrows wind.Windstorm

The manager.Simultaneous agent takes as arguments any number of Agent classes; it sets them all playing at the same time. In this case, you get a bunch of crows complaining about the blustery weather.

(There is currently no way to pass arguments to any agents which are themselves arguments. You cannot, for example, say 

boodler.py manager.Simultaneous wind.Windstorm play.OneSound environ/droplet-bloink.aiff

...because manager.Simultaneous will just think that environ/droplet-bloink.aiff is supposed to be a third agent. I may come up with a way around this in some future release. In the meantime, it is trivial to write your own agent which accomplishes this simultaneity. See Designing New Soundscapes.)

Sending events to Boodler

Some Agent classes can receive events, or messages, sent by other programs. Boodler listens on a network socket for these messages if you give the --listen argument. (If you do not, Boodler does not listen for events, and event-receiving agents will not run. This is the default behavior for reasons of security paranoia.)

To send an event, use the boomsg.py program: 

boomsg.py go

This sends a simple message ('go') to a listening Boodler process -- by default, on the same machine. To send a message to a different machine, you would say: 

boomsg.py --hostname machine.addr.net go

You can also send a more complex message, with several words: 

boomsg.py go 5.47 cheese

The effect of an event depends on what agent has been posted to receive it. For examples of Agent classes that receive events, see the listen module in the list of soundscapes.

What soundscapes are there?

Here is the list of sound agents which come with Boodler.

Choosing an output driver

By default, Boodler uses an appropriate sound device for your computer. (The OSS library on Unixes; CoreAudio on MacOSX.) But there are many output drivers available. To see which ones were compiled in your Boodler installation: 

boodler.py --list-drivers

You can adjust the behavior of each driver with various command-line arguments. Most understand the --rate and --device arguments (although the meaning of the latter depends on the driver). Some drivers also accept additional arguments, using the --define opt or --define opt=val command-line arguments. (Use --hardware to show the driver details.)

Boodler currently offers these drivers:

file -- write file containing raw sample output

The file will be named "boosound.raw" by default. To change this, pass a filename as the --device.

The file will contain raw PCM sound sample data, two channels, 16 bits per sample, signed (centered at 0). By default the samples will be in the native endianness of your computer, but you can change this with --define end=big or --define end=little.

This driver limits the size of the file. By default, it will only write five seconds of sound data; you can change the limit with the --define time=interval option. If the sound agent stops before the time limit, you'll get a shorter file.

(Note that this driver writes to the file as quickly as possible. It probably won't take five seconds to generate a five-second sound file.)

--define time=interval
Generate approximately interval seconds of output. This defaults to five seconds.
--define end=big
Force the sound output to be written big-endian.
--define end=little
Force the sound output to be written little-endian.

stdout -- write raw sample output to stdout

This is similar to the file driver, but it streams its data to stdout, and there is no time limit. The --device argument is ignored.

The stdout driver, like the file driver, generates sound data as quickly as possible. This will probably be much faster than real time! If you pipe the output to a file, you will have a very large file very soon. This driver is intended to be piped to an application that can regulate its input, such as Ices.

--define end=big
Force the sound output to be written big-endian.
--define end=little
Force the sound output to be written little-endian.

oss -- Open Sound System

This is the default output driver on Linux and other Unixes. Use --device to control which audio hardware device is used; the default is /dev/dsp.

alsa -- Advanced Linux Sound Architecture

Another Unix sound framework. Use --device to control which ALSA device is used; the default is default.

--define buffersize=frames
Define the length of Boodler's generation buffer, in frames. The default is 4096.
--define hwbuffer=frames
Define the length of the ALSA sound buffer, in frames. The default is 16384. If you find that the sound skips when the CPU is busy, increase this value. The hwbuffer should not be shorter than the buffersize.
--define periodsize=frames
Define the length of the ALSA transfer period. This should be a fraction of the buffersize. The default is left up to the ALSA driver; it depends on the buffersize.

esd -- Enlightened Sound Daemon

Yet another Unix sound framework. The --device option defines the hostname to send sound to; it defaults to localhost. If no ESD daemon is running, this will attempt to write directly to /dev/dsp.

macosx -- MacOSX CoreAudio

This is the default output driver on MacOSX.

--define buffercount=count
Create a queue of count buffers. If you find that the sound skips when the CPU is busy (for example, when you're dragging or resizing windows), increase this value. The default is 6.
--define buffersize=size
Set each CoreAudio buffer to be size bytes long. The default is 32768. (I have found that using a value of 65536 or more causes clicking; I'm not sure why.)

vorbis -- write Ogg Vorbis file

This writes a file, like the file driver; but it generates an Ogg Vorbis file. The default filename is "boosound.ogg". To change this, pass a filename as the --device.

--define time=interval
Generate approximately interval seconds of output. This defaults to five seconds.
--define quality=val
Set the Vorbis VBR compression quality, from 0.0 (low bitrate and quality) to 1.0 (high).

shout -- Shoutcast or Icecast source

This generates an Ogg Vorbis stream, and sends it to a Shoutcast or Icecast server (using libshout).

--define shout-server=name
Connect to shoutcast or icecast server name. Can be a domain or an IP address. Defaults to "127.0.0.1".
--define shout-port=port
Use port port on the streaming server. Defaults to 8000.
--define shout-user=name
Login with username user to the server. Defaults to "source".
--define shout-password=password
Login with password password to the server. Defaults to "hackme".
--define shout-mount=mount
With an icecast server, mount the sound on mount. Defaults to "/boodler.ogg".
--define shout-protocol=type
Use type as the protocol. Use "http" for icecast2, "xaudiocast" for icecast1, and "icy" for a shoutcast server. Defaults to "http".
--define quality=val
Set the Vorbis VBR compression quality, from 0.0 (low bitrate and quality) to 1.0 (high).

lame -- write MP3 file with LAME encoder

This writes a file, like the file driver; but it generates an MP3 file. The default filename is "boosound.mp3". To change this, pass a filename as the --device.

--define time=interval
Generate approximately interval seconds of output. This defaults to five seconds.
--define quality=val
Set the LAME VBR compression quality, from 9 (low bitrate and quality) to 0 (high). Yes, it's backwards. The default is 2.
--define fast
Use a faster VBR encoding algorithm. (Reduces quality somewhat.)
--define abr=rate
Use ABR (fixed average bit rate) of rate KBPS. The rate can be from 8 to 320.
--define haste=val
Modify the speed of the encoding algorithm, from 0 (slow and careful) to 9 (hasty). This affects the quality (but not the bit rate) of the output. The default is 2.

All the obscure options

boodler.py [ options ] module.AgentClass [ data ... ]
--output driver
Select one of the available driver modules. The default is oss on Unix, or macosx on MacOSX.
--list-drivers
List the driver modules which are available. Any of the listed drivers may be used with the --output option.
--device device
Set the device which Boodler will write to. The details depend on which driver module you have selected.
--list-devices
List the devices which are available for this driver module. (Not all drivers provide such a list.)
--rate soundrate
Set the sampling rate (in frames per second) which Boodler will try to use. If the sound device does not support this rate, Boodler will try to fall back upon some sampling rate which is supported. The default depends on the output driver, but may be 44100.
--master volume
Set the master mixing volume for all sounds. The default is 0.5. You should not increase this. If you do, any soundscapes that play more than one sound at a time (most of them) are likely to suffer from clipping noise -- sporadic static. (To increase Boodler's volume, you should use a mixer application to adjust your sound driver, or just turn up your speakers.) If you hear clipping noise in complex soundscapes, try reducing this option below 0.5.
--verbose
Turn on verbose handling of exceptions. Normally, if an exception occurs in the execution of an agent, Boodler just prints the name of the exception and continues running. If you set --verbose, Boodler will print out the entire Python stack trace.
--hardware
Display the capabilities of your sound hardware at startup time. This shows you explicitly what sample format and frame rate Boodler is using. It also dumps whatever other information about the sound interface might (conceivably) be important.
--stats interval
Turn on periodic statistics reporting. At intervals (given in seconds), Boodler will print out a message saying how many agents, channels, sounds, and note are queued up. This may be helpful for debugging soundscapes; if you see a value which increases without limit, you probably have a bug.
--listen
Cause Boodler to listen for events on a network socket (port 31863). Agents can be triggered by these events. See above.
--port port
If --listen is used, this causes Boodler to listen on the given port number (instead of the default port 31863). The port may also be an absolute pathname (beginning with "/"), in which case Boodler uses a Unix domain socket instead of a network socket.
--define opt
--define opt=val
Pass an option in to the sound driver. The available options depend on which driver Boodler is compiled with. Note that if an =val is supplied, there may not be any spaces before or after the equals sign. See the previous section for the meaning of the many options.
Return to Boodler docs index