Boodler: Catalog of Soundscapes

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 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
  • agent
  • play
  • manager
  • listen
• Algorithmic Pseudomusic
  • snazz
  • endless
  • stoner
  • drumbeat
  • gregor
• Voices in the Night
  • timespeak
• The Natural World
  • frogs
  • crows
  • cricket
  • wind
  • fire
  • cavepool
  • pwrain
  • owstorm
• The Unnatural and Completely Strange World
  • clock
  • hardhat
  • office
  • journey
  • heartbeat
  • blop

Utilities, Tools, and Managers

agent

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().)

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)

NullAgent

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

play

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.

manager

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)

listen

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 boomsg.py program:

python boomsg.py sound environ/droplet-plink.aiff environ/droplet-bloink.aiff

listen.Sounds

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.

listen.RemoteTranslateVolume

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)

listen.TimeSpeak

Speak the current time when an event is received. Events:

time

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.

listen.Leash

Receive events from the leash.py Boodler user interface script. leash.py sends a variety of events, primarily agent events. This agent sets up the listeners which respond to them.

listen.Shutdown

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

snazz

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.

snazz.ComplexWeight

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

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

stoner.StonerSound

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

drumbeat

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.

drumbeat.DrumTrack

Begin the drum track.

drumbeat.DrumsWithClicks

The same, with an added repeating high-hat click.

drumbeat.DualDrums

Two drum tracks -- one on the left, one on the right. (Thanks to Abe for the idea.)

gregor

Again, this is a work in progress.

gregor.Chant

Begin the harmony line.

gregor.ChantWithDrums

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

Voices in the Night

timespeak

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

(terminates)

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

timespeak.TemporalFugue

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

frogs.FrogPond

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)

frogs.VaryingCheepers

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)

crows

crows.ParliamentOfCrows

Many crows croaking to each other, near and far, left and right.

crows.SomeCrows

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)

cricket

cricket.CricketMeadow

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.

cricket.VaryingContinuo

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)

cricket.VaryingChirps

Two of the more strident cricket-songs play, each changing every 20 to 40 seconds. (internal)

cricket.OccasionallyVaryingChirps

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)

wind

wind.VaryingWind

A continuous wind that varies widely in speed and intensity.

wind.HeavyVaryingWind

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)

wind.SteadyGale

Shrieking wind. (internal)

wind.VaryingGale

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)

wind.Windstorm

A mix of steady and gusty winds.

wind.GentleWindstorm

Same thing, but less gusty.

fire

fire.Bonfire

Steady fire, at a mix of pitches.

fire.Steady ([ pitch=1 ])

Continuous crackling fire, at the given pitch. (internal)

cavepool

cavepool.Cavern

The pool ripples softly, and water drips from the cavern ceiling.

cavepool.WaterFlow

Water lapping at the edge of the pool, shifting occasionally. (internal)

cavepool.Water

Water lapping steadily. (internal)

cavepool.Drip

A single stalactite, dripping periodically into the pool. (internal)

cavepool.Still

Stalactites dripping, here and there. (internal)

pwrain

pwrain.Rainforest

The full rainforest environment.

pwrain.RainSounds

Occasionally varying rain. (internal)

pwrain.WaterSounds

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)

owstorm

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

owstorm.RainForever

A repeating storm, which rises and fades in a one-hour cycle.

owstorm.OneStorm

A single, one-hour-long thunderstorm. (internal; terminates)

The Unnatural and Completely Strange World

clock

clock.TimeSpace

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)

clock.ChimeFadesOut

A clock begins chiming, plays for roughly ten seconds, and then fades out. (internal; terminates)

clock.ChimeFadesInOut

A clock begins chiming softly, fades in, plays for roughly ten seconds, and then fades out. (internal; terminates)

clock.SteadyRandomChime

A clock chimes forever. The pitch and stereo location are random. (internal)

clock.ManyTicks

Many layers of ticking fading in and out. (internal)

clock.VaryingTicks

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)

hardhat

hardhat.Site

A mixture of motors and the occasional pile-driver.

hardhat.GlassDisaster

Continual showers of shattering glass.

hardhat.ManyMotors

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)

hardhat.MotorRun

A random motor starts up and runs forever. (internal)

hardhat.OccasionalPileDriver

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)

hardhat.PileDriver

A steady pile-driver at a random pitch and stereo pan. (internal)

hardhat.OccasionalGlass

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)

journey

journey.BusyHighway

Cars rushing past, with occasional trucks and railway crossings.

journey.Highway

Cars rushing past.

journey.BusyRailway

Railroad track sounds, with occasional crossings.

journey.VaryingTrack

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)

journey.OccasionalCrossing

A railroad crossing goes past, fading in and out over the course of ten seconds. Another goes past every 30 to 120 seconds. (internal)

journey.RailroadCrossing

Random railway crossing bell, repeated forever. (internal)

journey.OccasionalTruck

A random truck-horn is heard, at random intervals up to 90 seconds apart. (internal)

journey.Transfer

Slow fade back and forth between car and rail travel.

office

office.Typewriter

Someone typing on an electric typewriter.

office.Keyboard

Someone typing on a computer keyboard.

heartbeat

heartbeat.ManyBeats

Several heartbeats (four, by default), of random pitch.

heartbeat.ComingAndGoing

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)

blop

blop.BlopSpace

Strange blopping noises in all directions.

blop.TapSpace

Strange echoey tapping noises in all directions.

blop.TonkSpace

Strange echoey tonking noises in all directions.

blop.EchoWorld

A mix of echoing noises, with an occasional gong in the distance.

blop.BlopEchoes

A single chain of blops, at a random pitch and location. (internal; terminates)

blop.TapEchoes

A single chain of taps, at a random pitch and location. (internal; terminates)

blop.TonkEchoes

A single chain of tonks, at a random pitch and location. (internal; terminates)

blop.OccasionalGong

A gong crashes at long intervals. (internal)