## Boodler: Using It

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

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

    python 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:

    python 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,

    python 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

    python 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

    python 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:

    python 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

    python 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:

    python 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:

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

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

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

### All the obscure options

    python boodler.py
      [--device /dev/device] [--rate soundrate] [--master volume]
      [--verbose] [--hardware] [--stats interval] [--listen] [--port port]
      module.AgentClass [ data ... ]

`--device /dev/device`
  Set the device which Boodler will write to. This must support the OSS sound API. The default is `/dev/dsp`.
`--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.
`--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. (Use `--hardware` to show the driver details.) Note that if an =val is supplied, there may not be any spaces before or after the equals sign.
  - OSS driver -- no options
  - ALSA driver -- no options
  - ESD driver -- no options
  - MACOSX driver
    `--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.)
  - FILE driver
    `--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. (FILE output is always 16-bit, signed, stereo.)
    `--define end=little`
      Force the sound output to be written little-endian.

Return to Boodler docs index