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
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;
python boodler.py play.OneSound environ/droplet-bloink.aiff
python boodler.py play.OneSoundOpts environ/droplet-bloink.aiff 1.5 0.5
Table of Modules
- Utilities, Tools, and Managers
- Algorithmic Pseudomusic
- Voices in the Night
- The Natural World
- The Unnatural and Completely Strange World
Utilities, Tools, and Managers
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
This agent causes a channel (the channel it runs in) to stop playing.
All notes and agents in the channel (and subchannels) will be
(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.
This does nothing. It is included for debugging purposes, or in case
you feel like doing nothing.
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
You can also use an absolute pathname.)
- 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.)
- play.RepeatSound (sound)
Plays the given sound over and over, with no pauses between,
- 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
- play.SoundSequence (sound1, sound2, sound3, ...)
Play the given sounds, one after another, with no pauses between.
- 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.
- 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
(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, ...)
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, ...)
IntermittentSoundsOpts, except the panning location
of each sound is randomly chosen between -maxpan and maxpan.
manager module contains tools for managing other
- 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
- 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
This changes the volume of the channel it is running in.
(internal; affects channel)
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
sound. You could send such an event with the
python boomsg.py 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.
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.
- sound sound [ sound2 sound3... ]
- Play the given sound (or sounds), in sequence.
- 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
- 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
- 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.)
- 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
All it does is listen for
remote events, as listed above,
flipmute events in
Speak the current time when an event is received.
- Speak the time.
- listen.Catalog (class1, class2, class3, ...)
Switch between a list of agents, when an event is received.
- 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
leash.py Boodler user interface
leash.py 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.
- shutdown [ fadetime ]
- Stop all sounds, channels, and agents, and cause Boodler to exit.
If fadetime is supplied, everything fades out over that interval before
(terminates; affects channel)
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
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.
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.
stoner module implements StonerSound, an "audio screen
saver" that I originally implemented for the Mac.
(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.)
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.)
gregor module is similar to
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.
Not exactly period Gregorian, but kind of nice.
Voices in the Night
timespeak module contains agents that speak the time,
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/timespeak.py, finding the
default_voice = ['...'] lines, and uncommenting the one
(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,
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
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
- timespeak.Now ([ opts=(SAY_TIME_IS | SAY_SECONDS) ])
Speak the current time -- the time at which the agent runs.
- 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
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.
- frogs.Cheepers ([ pitch=1 ])
Continuous night-cheepers, at the given pitch.
Waves of cheepers, each at a slightly different pitch. Each wave
lasts from 24 to 60 seconds, and then fades smoothly into 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.
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.
Two of the more strident cricket-songs play, each changing every 20
to 40 seconds.
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.
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.)
Shrieking wind, at varying speeds.
- 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.
- wind.GustyWind ([ mindelay=2, maxdelay=4 ])
Individual gusts of wind, at random speeds, repeated at intervals -- by
default, every 2 to 4 seconds.
A mix of steady and gusty winds.
Same thing, but less gusty.
fire module handles various combustiania.
Steady fire, at a mix of pitches.
- fire.Steady ([ pitch=1 ])
Continuous crackling fire, at the given pitch.
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.
Water lapping steadily.
A single stalactite, dripping periodically into the pool.
Stalactites dripping, here and there.
pwrain module creates a rainforest, with
occasional insects and frogs amid the downpour.
Contributed by Peter Williams.
The full rainforest environment.
Occasionally varying rain.
Occasionally varying flowing water.
- 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).
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.
The Unnatural and Completely Strange World
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
A clock begins chiming, plays for roughly ten seconds, and then fades
A clock begins chiming softly, fades in,
plays for roughly ten seconds, and then fades out.
A clock chimes forever. The pitch and stereo location are random.
Many layers of ticking fading in and out.
A ticking sound that changes pitch and speed every few seconds.
- clock.Tick ([ pitch=1 ])
A steady ticking at the given pitch. The stereo location is random.
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.
- hardhat.MotorRunFade ([ duration=3, fadetime=7 ])
A random motor starts up, runs for the given duration, and then fades out
over the given interval.
A random motor starts up and runs forever.
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
- hardhat.PileDriverInOut ([ duration=3 ])
A pile driver starts up, runs for the given interval, and then fades out
A steady pile-driver at a random pitch and stereo pan.
A pane of glass smashes, every few seconds.
- 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.
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.
A railroad crossing goes past, fading in and out over the course of ten
seconds. Another goes past every 30 to 120 seconds.
Random railway crossing bell, repeated forever.
A random truck-horn is heard, at random intervals up to 90 seconds
Slow fade back and forth between car and rail travel.
office module contains a couple of rather arbitrary
Someone typing on an electric typewriter.
Someone typing on a computer keyboard.
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
- heartbeat.OneBeat ([ pitch=1 ])
A single steady beat at the given pitch.
- heartbeat.OneSoftBeat ([ pitch=1 ])
Same, but a gentler sample.
- heartbeat.OneRandomBeat ([ pitch=1 ])
Same, but randomly chooses between the two samples.
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.
A single chain of taps, at a random pitch and location.
A single chain of tonks, at a random pitch and location.
A gong crashes at long intervals.
Return to Boodler docs index