Boodler: Catalog of Soundscapes

These are the effects which are packaged with Boodler as of the time I packaged it up. More may be added when I feel like it. See the Boodler project web page.

The soundscapes in this package use the sounds in the Boodler sound library dated February 19, 2002 (021902). If you have an earlier version of the library, you may see errors about sounds not being found.

This catalog is divided up by module. Each module typically has several sound agents, some of which are really intended only for use by other agents in the module. (These are marked internal.) You are welcome to play internal agents, of course, but they may not sound very interesting on their own.

Also marked are terminating agents (which shut down after they are done, as opposed to running forever) and agents which affect channels (shut down the channel in which they run, or have some other effect. By convention, most agents do not affect the channel in which they run; this allows you to run several agents in a channel together. But a few agents are intended specifically to make some change in a channel.)

If an agent class takes arguments, they are listed in parentheses after the class name. Optional arguments are in square brackets (and the default values are shown). You may pass arguments on the command line; for example:

python play.OneSound environ/droplet-bloink.aiff
python play.OneSoundOpts environ/droplet-bloink.aiff 1.5 0.5

Table of Modules

Utilities, Tools, and Managers


The agent module is the basis for all Boodler sound agents. In addition to the base class Agent, this module contains a few agent classes which are generally useful.

Note that since you will generally have a from boodle.agent import * statement in your soundscape file, you can refer to these agents directly. (As StopAgent(), for example, rather than agent.StopAgent().)

This agent causes a channel (the channel it runs in) to stop playing. All notes and agents in the channel (and subchannels) will be discarded. (terminates; affects channel)
FadeOutAgent ([ duration = 0.005 ])
This agent causes its channel to fade down to zero volume over a given interval, and then stop. (terminates; affects channel)
FadeInOutAgent (agent, liveinterval, fadeinterval [, fadeoutinterval] )
This agent creates a channel with an agent. The agent begins running immediately; the channel fades up from zero volume, holds at full volume, fades out, and then stops.

The fadeinterval is the time the channel takes to fade in or out. The liveinterval is the duration of maximum volume (from the end of fade-in to the beginning of fade-out).

(If a third argument is given, then fadeinterval is the fade-in time, and fadeoutinterval is the fade-out time. If the third argument is omitted, these are the same.)

Note that unlike StopAgent and FadeOutAgent, this agent does not affect the channel it runs in. It creates a subchannel to do its work in. (terminates)

This does nothing. It is included for debugging purposes, or in case you feel like doing nothing. (terminates)


The play module includes basic tools for playing one or more sound files.

play.OneSound (sound)
Plays the given sound once. (The argument should be a filename in $BOODLER_SOUND_PATH, such as environ/droplet-plink.aiff. You can also use an absolute pathname.) (terminates)
play.OneSoundOpts (sound [, pitch=1, volume=1, pan=0 ])
Play the given sound once, optionally modifying the pitch, volume, and stereo panning position. (See Boodler Soundscape Basics for details on how Boodler understands pitch, volume, and pan values.) (terminates)
play.RepeatSound (sound)
Plays the given sound over and over, with no pauses between, repeating forever.
play.ExtendSound (sound [, duration=10 ])
Play the given sound once, extending it to the given duration (in seconds). This only works if the sound has looping parameters built into it. If it does not, the sound just plays in its standard form. (terminates)
play.SoundSequence (sound1, sound2, sound3, ...)
Play the given sounds, one after another, with no pauses between. (terminates)
play.RepeatSoundSequence (sound1, sound2, sound3, ...)
Play the given sounds, one after another, with no pauses between. When the last one is finished, start over with the first.
play.SoundShuffle (sound1, sound2, sound3, ...)
Play the given sounds, in a random order, with no pauses between. Continue forever.
play.RepeatSoundShuffle (mindelay, maxdelay, fadetime, sound1, sound2, sound3, ...)
Choose one of the sounds at random, and begin repeating it. After an interval (between mindelay and maxdelay), fade into another repeating sound, with a cross-fade duration of fadetime. (You may pass a single argument which is a list of sounds, instead of several sound argument.)
play.IntermittentSounds (mindelay, maxdelay, sound1, sound2, sound3, ...)
At intervals (between mindelay, and maxdelay), play one of the given sounds at random. (You may pass a single argument which is a list of sounds, instead of several sound argument.)
play.IntermittentSoundsOpts (mindelay, maxdelay, minpitch, maxpitch, minvol, maxvol, sound1, sound2, sound3, ...)
Same as IntermittentSounds, except the pitch of each sound is randomly chosen between minpitch and maxpitch, and the volume is randomly chosen between minvol and maxvol.
play.IntermittentSoundsPanOpts (mindelay, maxdelay, minpitch, maxpitch, minvol, maxvol, maxpan, sound1, sound2, sound3, ...)
Same as IntermittentSoundsOpts, except the panning location of each sound is randomly chosen between -maxpan and maxpan.


The manager module contains tools for managing other agents.

manager.Simultaneous (agent1, agent2, agent3, ...)
Start up all the given agents, and let them play simultanously. (The agents can be actual agent instance objects, or strings naming agent classes. In the latter case, the agent class must be instantiable without arguments.)
manager.SimultaneousVolume (agent1, vol1, agent2, vol2, agent3, vol3, ...)
Start up all the given agents, each at the given volume. Let them all play simultanously.
manager.Sequential (mindelay, maxdelay, class1, class2, class3, ...)
Create an agent of class1 (which must be an agent class, or the name of one, which is instantiable without arguments). Let it fade in, and then play for an amount of time which is randomly chosen between mindelay and maxdelay seconds. After that time is up, fade out class1 while fading in class2. Continue forever in this way: each class sequentially gets a turn, and each turn lasts a randomly-chosen interval.
manager.VolumeModulate (agent [, vol=0.8, delta=0.2, minfade=7, maxfade=20, mindelay=30, maxdelay=70 ])
Start up the given agent, at the given volume. Begin fading the volume up or down, to a new value which is randomly chosen within delta of vol (that is, between vol-delta and vol+delta). The volume change lasts for an interval between minfade and maxfade. Another volume change occurs at random intervals, each between mindelay and maxdelay. (Note that the delay interval is measured from the start of each volume change to the start of the next. Therefore, the four timing arguments should be in strictly increasing order to prevent volume changes from overlapping: minfade < maxfade < mindelay < maxdelay.)
manager.VolumeModulateChannel ([ vol=0.8, delta=0.2, minfade=7, maxfade=20, mindelay=30, maxdelay=70 ])
Perform the periodic volume modulation described for VolumeModulate. This changes the volume of the channel it is running in. (internal; affects channel)


The listen module contains tools which listen for Boodler events. Remember that these agents will not run unless you run Boodler with the --listen argument (before the agent name).

Each agent class listens for one or more types of events. (The type of the event is determined by its first word.) For example, the listen.Sounds agent class listens for events whose first word is sound. You could send such an event with the program:

python sound environ/droplet-plink.aiff environ/droplet-bloink.aiff
Actually, you do not need to use Any program which can open a TCP network connection can send a message to Boodler. See the External Events section of the programming documentation.

Play sounds according to the events that are received. Events:
sound sound [ sound2 sound3... ]
Play the given sound (or sounds), in sequence.
Note that although each event triggers a sequence of sounds played one after another, separate events are not sequenced. If two events arrive close together, their sounds will overlap.
listen.Agents ([ fadetime=2 ])
Run whichever agent is specified by events. Only one agent is run at a time; when each event is received, the previous agent is faded out. No agent is started up initially, so there is silence until the first event arrives. Events:
agent agentname [ arguments... ]
Start up the given agent (passing it the arguments, if supplied). The agent is faded in, and the previous agent is faded out, over an interval of fadetime.
listen.Volume (agent [, initvolume=1 ])
Run an agent, changing its volume according to the events that are received. (The agent can be an actual agent instance object, or a string naming an agent class. In the latter case, the agent class must be instantiable without arguments.) Events:
volume vol [ fadetime ]
volume up [ fadetime ]
volume down [ fadetime ]
Set the volume. (If muted, a nonzero volume unmutes.) The volume may be a number between 0 and 1, or the strings "up" or "down", which shift the volume by a tenth. If fadetime is supplied, the volume changes gradually over that interval.
mute [ fadetime ]
Set the volume to zero.
unmute [ fadetime ]
Set the volume to whatever the last volume event specified.
flipmute [ fadetime ]
Mute if playing; unmute if muted.
listen.RemoteVolume (agent [, initvolume=1 ])
This works the same as listen.Volume, but it also accepts standard remote-control button events to control the volume. Events (in addition to the ones listed above):
remote volup
Turn up the volume.
remote voldown
Turn down the volume.
remote mute
Mute or unmute.
This handles the event translation for listen.RemoteVolume. All it does is listen for remote events, as listed above, and send volume and flipmute events in response. (internal)
Speak the current time when an event is received. Events:
Speak the time.
listen.Catalog (class1, class2, class3, ...)
Switch between a list of agents, when an event is received. Events:
remote 1 .. 9
Switch to the given entry in the list.
remote chanup
remote chandown
Switch up and down the list.
Receive events from the Boodler user interface script. sends a variety of events, primarily agent events. This agent sets up the listeners which respond to them.
Shut down Boodler when an event is received. Events:
shutdown [ fadetime ]
Stop all sounds, channels, and agents, and cause Boodler to exit. If fadetime is supplied, everything fades out over that interval before Boodler exits. (terminates; affects channel)

Algorithmic Pseudomusic


The snazz module generates a running drum solo. The rhythm is not a simple repeating sequence; it mutates over time, in a way which (I hope) has some aural interest. It's really rather catchy, in a bongo sort of way.

The underlying algorithm for snazz comes from an idea I had about representing drum measures as binary tree. Really!

snazz.Simple ([ repeat=4 ])
Repeat a rhythm four times (or however many are specified), and then change to a completely new rhythm.
snazz.Complex ([ repeat=4 ])
Repeat a rhythm four times (or however many), and then change to a new rhythm. This agent uses a more complex algorithm, which permits arbitrary trees, not just binary trees. You will sometimes hear a measure which changes slightly as it repeats. This is a tree node with three or five children, which creates three-against-two or five-against-two rhymthic variations.
Repeat a rhythm, and then change to a new one. Each measure is repeated two, four, or six times, depending on how interesting it is. A very simple "dah dah dah dah" will only repeat twice; a complex three-based or five-based rhythm will repeat six times, allowing you more time to appreciate it.
snazz.Mutate ([ repeat=4 ])
Repeat a rhythm four times (or however many), and then change it. The change sometimes gives a completely new rhythm, but more often it is a mutation, which affects only part of the measure and leaves the rest recognizable. Mutations may make the rhythm more complex, or simplify it.


The endless module implements the Shepard aural illusion of endlessly rising (or falling) scales.

endless.Rising ([ octaves=3, notes=octaves, samp='voice/z-baa-proc.aiff', rate=0.4 ])
Play a rising series of chords. The cycle spans the given number of octaves, and by default the number of notes in the chord is equal to the number of octaves -- that is, the notes are one octave apart. You can increase the number of notes, which causes them to be closer together, but the overall effect quickly is lost.

The sample defines which sound is used, and the rate is the duration of each note, in seconds.

endless.Falling ([ octaves=3, notes=octaves, samp='voice/z-baa-proc.aiff', rate=0.4 ])
The same, but with descending chords.


The stoner module implements StonerSound, an "audio screen saver" that I originally implemented for the Mac. (See StonerSound project page.)

Perform StonerSound.

(Note: I only have one instrument implemented, because there aren't enough good musical samples in the Boodler sound library. In a future version I may add more -- preferably multirange sounds.)


The drumbeat module generates a running drum machine track. (This is an earlier attempt at the snazz idea. It doesn't work as well, but it's still worth including.)

A change occurs about every four bars. Some changes are temporary, and return to the basic theme after a few bars. Some changes are permanent.

Begin the drum track.
The same, with an added repeating high-hat click.
Two drum tracks -- one on the left, one on the right. (Thanks to Abe for the idea.)


The gregor module is similar to drumbeat, except that it works in harmony rather than rhythm. It generates a mutating line of harmony from a (fixed) melodic line. Sometimes the harmony is simple chords; sometimes it is a more complex polyphony.

Again, this is a work in progress.

Begin the harmony line.
Combines the gregor and drumbeat modules. Not exactly period Gregorian, but kind of nice.

Voices in the Night


The timespeak module contains agents that speak the time, in English.

Two voices are available for speaking. However, I don't have a particularly good way to select a voice. You're best off going into effects/, finding the default_voice = ['...'] lines, and uncommenting the one you want.

(Remind me to write a general configuration-file system for Boodler...)

timespeak.Time (timeval [, opts=(SAY_TIME_IS | SAY_SECONDS) ])
Speak the given time. The time value is given as a tuple (year, month, day, hour, minute, second, weekday, julian, daylight) -- see the Python time module. (In fact, timespeak only considers the hour, minute, and second entries.) The time value may also be given as a floating point number, seconds since the epoch, which is converted to a local time tuple and then spoken.

By default, the spoken format is: "The time is twelve fifteen and thirty-one seconds", or "The time is ten o'clock exactly".

You may also supply a second argument, a bitwise-or mask of the constants timespeak.SAY_TIME_IS (begin "The time is...") and timespeak.SAY_SECONDS (include "...and N seconds"). The default is both. If you pass 0 as the second argument, the format will be reduced to "Twelve fifteen".


timespeak.Now ([ opts=(SAY_TIME_IS | SAY_SECONDS) ])
Speak the current time -- the time at which the agent runs. (terminates)
timespeak.Periodic ([ period=15 ])
Speak the time every N minutes. This will not necessarily begin right away; it occurs on the hour, and every even fraction of an hour. (So the period must be between 1 and 60, and must evenly divide 60. The default is quarter-hours.)
Begin speaking the time once per second, forever. This produces a polyphonic spoken chant, which is more hypnotic than one might expect.

The Natural World


The frogs module does amphibious environments.

Occasional bullfrog calls against a background of night cheepers.
frogs.Bullfrogs ([ mindelay=0.75, maxdelay=3.5 ])
A series of bullfrog calls, each at a random pitch and stereo location. The arguments determine the minimum and maximum delay between each call and the next. (internal)
frogs.Cheepers ([ pitch=1 ])
Continuous night-cheepers, at the given pitch. (internal)
Waves of cheepers, each at a slightly different pitch. Each wave lasts from 24 to 60 seconds, and then fades smoothly into the next wave. (internal)


The crows module was the first one I wrote.

Many crows croaking to each other, near and far, left and right.
A sequence of crow calls. Each call has a different pitch, stereo location, and duration, and calls are spaced up to 3.5 seconds apart. (internal)


The cricket module is mostly collected from the "Singing Insects of North America" collection at University of Florida.

A steady soft chirp in the background (the Texas Meadow Katydid) with various other crickets taking turns.
cricket.ManyCrickets ([ numbugs=3 ])
A steady chirping that occasionally switches from one species to another; and some number (default 3) of more strident crickets, which also occasionally change species.
One of the more steady, even cricket-songs plays for 30 to 60 seconds. It then fades into a different songs, which plays for 30 to 60 seconds, and so on. (internal)
Two of the more strident cricket-songs play, each changing every 20 to 40 seconds. (internal)
One of the more strident cricket-songs plays for a time (phasing slightly every ten to twenty seconds). It then fades into a different song, and so on. (internal)


The wind module does the motion of the ocean of air.

A continuous wind that varies widely in speed and intensity.
Same thing, but a bit heavier and more complex.
wind.SteadyWind ([ pitch=1 ])
A perfectly steady wind, at the given pitch. (This chooses randomly between two wind sounds, so a particular pitch will not always produce the same sound.) (internal)
Shrieking wind. (internal)
Shrieking wind, at varying speeds. (internal)
wind.IntermittentGale ([ mindelay=9, maxdelay=12 ])
A shrieking wind blows up and fades out over an interval of about ten seconds. This is repeated every so often -- by default, every 9 to 12 seconds, so that it never completely stops. (internal)
wind.GustyWind ([ mindelay=2, maxdelay=4 ])
Individual gusts of wind, at random speeds, repeated at intervals -- by default, every 2 to 4 seconds. (internal)
A mix of steady and gusty winds.
Same thing, but less gusty.


The fire module handles various combustiania.

Steady fire, at a mix of pitches.
fire.Steady ([ pitch=1 ])
Continuous crackling fire, at the given pitch. (internal)


The cavepool module simulates a still, icy pool which half-fills a cavern, far beneath the Misty Mountains.

The pool ripples softly, and water drips from the cavern ceiling.
Water lapping at the edge of the pool, shifting occasionally. (internal)
Water lapping steadily. (internal)
A single stalactite, dripping periodically into the pool. (internal)
Stalactites dripping, here and there. (internal)


The pwrain module creates a rainforest, with occasional insects and frogs amid the downpour. Contributed by Peter Williams.

The full rainforest environment.
Occasionally varying rain. (internal)
Occasionally varying flowing water. (internal)
pwrain.LightWind ([ vol=0.075, delta=0.05 ])
Varying light wind. The volume varies up and down, with delta of vol. (That is, from delta-vol to delta+vol). (internal)


The owstorm module creates a summer thunderstorm. It builds up to a peak and then tails off, over the course of an hour. Contributed by Owen Williams.

This module is extremely rich and complex, with many internal agents -- too many to document here. Feel free to look at the source.

A repeating storm, which rises and fades in a one-hour cycle.
A single, one-hour-long thunderstorm. (internal; terminates)

The Unnatural and Completely Strange World


The clock module generates clock ticking and chiming effects. (Note how complex soundscape effects are built up out of agents, which are themselves made of simpler agents.)

Hundreds of clocks drifting by, ticking. Occasionally one strikes the hour -- some hour, at least.
clock.OccasionalChimes ([ mindelay=15, maxdelay=90, useinout=0 ])
A clock begins chiming every so often. (The mindelay and maxdelay arguments control this period, so by default, a chime begins every 15 to 90 seconds.) The chiming lasts roughly ten seconds, and then fades away. If useinout is set to 1, the chiming fades in slowly instead of beginning abruptly. (internal)
A clock begins chiming, plays for roughly ten seconds, and then fades out. (internal; terminates)
A clock begins chiming softly, fades in, plays for roughly ten seconds, and then fades out. (internal; terminates)
A clock chimes forever. The pitch and stereo location are random. (internal)
Many layers of ticking fading in and out. (internal)
A ticking sound that changes pitch and speed every few seconds. (internal)
clock.Tick ([ pitch=1 ])
A steady ticking at the given pitch. The stereo location is random. (internal)


The hardhat module does noises of heavy motors and construction equipment. Also some destruction equipment.
A mixture of motors and the occasional pile-driver.
Continual showers of shattering glass.
A mixture of motors. (internal)
hardhat.MotorRunFade ([ duration=3, fadetime=7 ])
A random motor starts up, runs for the given duration, and then fades out over the given interval. (internal; terminates)
A random motor starts up and runs forever. (internal)
A pile driver starts up at a random pitch and volume. It runs for from 3 to 15 seconds, and then fades out. The cycle repeats every 30 to 90 seconds. (internal)
hardhat.PileDriverInOut ([ duration=3 ])
A pile driver starts up, runs for the given interval, and then fades out and stops. (internal; terminates)
A steady pile-driver at a random pitch and stereo pan. (internal)
A pane of glass smashes, every few seconds. (internal)
hardhat.GlassForest ([ snd='mech/glass-breaking-reverb.aiff', mindelay=0.25, maxdelay=0.4 ])
Repeated showers of broken glass. The given sound is repeated at intervals which range from mindelay to maxdelay. The pitch drifts slowly and randomly up and down. (internal)


The journey module performs sounds of travel.

Cars rushing past, with occasional trucks and railway crossings.
Cars rushing past.
Railroad track sounds, with occasional crossings.
Railroad track sounds, varying every so often in pitch and quality.
journey.Track ([ pitch=1 ])
Railroad track sounds, at the given pitch, but chosen randomly from a list of sound samples. (internal)
A railroad crossing goes past, fading in and out over the course of ten seconds. Another goes past every 30 to 120 seconds. (internal)
Random railway crossing bell, repeated forever. (internal)
A random truck-horn is heard, at random intervals up to 90 seconds apart. (internal)
Slow fade back and forth between car and rail travel.


The office module contains a couple of rather arbitrary workaday environments.
Someone typing on an electric typewriter.
Someone typing on a computer keyboard.


The heartbeat module fills a space with invisible circulation.

Several heartbeats (four, by default), of random pitch.
One heartbeat begins, then another, then another and another. Then, one at a time, they fade away. Silence. The cycle repeats.
heartbeat.ComeGoBeat ([ fadetime=4, livetime=10 ])
A random heartbeat fades in, continues for a time, and then fades out and stops. (internal; terminates)
heartbeat.OneBeat ([ pitch=1 ])
A single steady beat at the given pitch. (internal)
heartbeat.OneSoftBeat ([ pitch=1 ])
Same, but a gentler sample. (internal)
heartbeat.OneRandomBeat ([ pitch=1 ])
Same, but randomly chooses between the two samples. (internal)


The blop module emits strange electronic blopping noises.

Strange blopping noises in all directions.
Strange echoey tapping noises in all directions.
Strange echoey tonking noises in all directions.
A mix of echoing noises, with an occasional gong in the distance.
A single chain of blops, at a random pitch and location. (internal; terminates)
A single chain of taps, at a random pitch and location. (internal; terminates)
A single chain of tonks, at a random pitch and location. (internal; terminates)
A gong crashes at long intervals. (internal)

Return to Boodler docs index