Envelope

Envelopes shape an AudioSample's volume over time, giving its sound individual quality or timbre.

Envelope objects are used to help shape the sound of AudioSample instruments used to play notes. They utilize four adjustable parameters:

• Attack models the beginning of the sound, i.e, how long it takes for the sound to begin sounding fully, once it has been started. It is the initial build up of the sound.
• Delay models the initial loss of energy after the Attack, i.e., how long it takes for the sound to reach its normal level, after the maximum of the initial attack.
• Sustain models how long the sound maintains its normal level.
• Release models the end of the sound, i.e., how long it takes for the sound to finish sounding, after it has been stopped.

All times are in milliseconds, each measured from the previous one. The exceptions are the first attack time (measured from the start of the sound) and the release time (which extends past the end of the sound). Volumes run from 0.0 (silence) to 1.0 (full).

For more information on Envelopes, see here and here.

Creating an Envelope

You can create an Envelope using the following functions:

Envelope()

Envelope(attackTimes, attackVolumes, delayTime, sustainVolume, releaseTime)

Parameter	Type	Default	Description
attackTimes	list[int]	[2, 20]	The attack times, in milliseconds, each measured from the previous one (the first from the start of the sound).
attackVolumes	list[float]	[0.5, 0.8]	The volumes to reach at the attack times, each from 0.0 to 1.0; parallel to attackTimes.
delayTime	int	20	How long to take reaching the sustain volume, in milliseconds after the last attack time.
sustainVolume	float	1.0	The volume held through the body of the sound, from 0.0 to 1.0.
releaseTime	int	150	How long the sound takes to fade to silence after it ends, in milliseconds.

For example,

envelope = Envelope([100, 200], [0.8, 1.0], 300, 0.6, 1200)

creates an Envelope object envelope, which may be used to help shape an AudioSample.

Functions

Once an Envelope envelope has been created, the following functions are available:

Function	Description
envelope.getAttackTimesAndVolumes()	Return the envelope's attack times and the volumes reached at them.
envelope.setAttackTimesAndVolumes(attackTimes, attackVolumes)	Set the envelope's attack times and the volumes reached at them.
envelope.getSustainVolume()	Return the envelope's sustain volume.
envelope.setSustainVolume(sustainVolume)	Set the envelope's sustain volume.
envelope.getDelayTime()	Return the envelope's delay time.
envelope.setDelayTime(delayTime)	Set the envelope's delay time.
envelope.getReleaseTime()	Return the envelope's release time.
envelope.setReleaseTime(releaseTime)	Set the envelope's release time.
envelope.performAttackDelaySustain(audioSample, volume, voice)	Apply the envelope's attack, delay, and sustain to a voice of an audio sample.
envelope.performReleaseAndStop(audioSample, voice)	Apply the envelope's release (fade-out) to a voice of an audio sample, then stop it.

Example

The following demonstrates how to use an envelope to shape the sound of a loop:

audioLoopWithEnvelope.py

# audioLoopWithEnvelope.py
#
# Demonstrates how to create a loop using an audio file and an envelope.
# This may be used for ambient or drone backdrops of sound to build on.
#

from music import *

loopTimes = 4

# load audio instruments
a1 = AudioSample("moondog.Bird_sLament.wav")

# define an envelope
e1 = Envelope([20, 60, 100, 10], [0.0, 0.8, 1.0, 0.8], 30, 0.6, 30)
#e1 = Envelope()

# create musical data structure
score = Score()

part1 = Part(0, 0)

phrase1 = Phrase()

# create musical data
pitches   = [A4] * loopTimes
durations = [4.12152] * loopTimes   # duration is in seconds (assuming 60bpm)
volumes   = [120] * loopTimes
pannings  = [0.5] * loopTimes
lengths   =  durations              # force playing length to be same as noted duration!

phrase1.addNoteList(pitches, durations, volumes, pannings, lengths)

part1.addPhrase(phrase1)

score.addPart(part1)

# play it!
#Play.audio( score, [a1] )
Play.audio( score, [a1], [False], [e1] )