Env

Description

An Env is a specification for a segmented envelope. Envs can be used both server-side, by an EnvGen within a SynthDef, and clientside, with methods such as -at and -asStream, below.

An Env can have any number of segments which can stop at a particular value or loop several segments when sustaining. It can have several shapes for its segments.

Env.new([0,1,0.9,0], [0.1,0.5, 1],[-5,0,-5]).plot;

The envelope is conceived as a sequence of nodes (not to be confused with a synthesis-Node) each of which has three parameters: a target level, a time duration from the previous node, and a shape. The three parameters for each node are kept in separate arrays as explained below.

Class Methods

*new (levels = [ 0, 1, 0 ], times = [ 1, 1 ], curve = 'lin', releaseNode, loopNode)

*newClear (numSegments = 8)

Standard Shape Envelope Creation Methods

The following class methods create some frequently used envelope shapes based on supplied durations.

*linen (attackTime = 0.01, sustainTime = 1, releaseTime = 1, level = 1, curve = 'lin')

s.boot;
Env.linen(1, 2, 3, 0.6).test.plot;
Env.linen(0.1, 0.2, 0.1, 0.6).test.plot;
Env.linen(1, 2, 3, 0.6, 'sine').test.plot;
Env.linen(1, 2, 3, 0.6, 'welch').test.plot;
Env.linen(1, 2, 3, 0.6, -3).test.plot;
Env.linen(1, 2, 3, 0.6, -3).test.plot;

*triangle (dur = 1, level = 1)

Env.triangle(1, 1).test.plot;

*sine (dur = 1, level = 1)

Env.sine(1, 1).test.plot;

*perc (attackTime = 0.01, releaseTime = 1, level = 1, curve = -4)

Env.perc(0.05, 1, 1, -4).test.plot;
Env.perc(0.001, 1, 1, -4).test.plot;	// sharper attack
Env.perc(0.001, 1, 1, -8).test.plot;	// change curvature
Env.perc(1, 0.01, 1, 4).test.plot;	// reverse envelope

Sustained Envelope Creation Methods

The following methods create some frequently used envelope shapes which have a sustain segment.

*adsr (attackTime = 0.01, decayTime = 0.3, sustainLevel = 0.5, releaseTime = 1, peakLevel = 1, curve = -4, bias = 0)

Env.adsr(0.02, 0.2, 0.25, 1, 1, -4).test(2).plot;
Env.adsr(0.001, 0.2, 0.25, 1, 1, -4).test(2).plot;
Env.adsr(0.001, 0.2, 0.25, 1, 1, -4).test(0.45).plot;	//release after 0.45 sec

*dadsr (delayTime = 0.1, attackTime = 0.01, decayTime = 0.3, sustainLevel = 0.5, releaseTime = 1, peakLevel = 1, curve = -4, bias = 0)

*asr (attackTime = 0.01, sustainLevel = 1, releaseTime = 1, curve = -4)

Env.asr(0.02, 0.5, 1, -4).test(2).plot;
Env.asr(0.001, 0.5, 1, -4).test(2).plot; // sharper attack
Env.asr(0.02, 0.5, 1, 'linear').test(2).plot; // linear segments

*cutoff (releaseTime = 0.1, level = 1, curve = 'lin')

Env.cutoff(1, 1).test(2).plot;
Env.cutoff(1, 1, 4).test(2).plot;
Env.cutoff(1, 1, 'sine').test(2).plot;

Inherited class methods

Instance Methods

-blend (argAnotherEnv, argBlendFrac = 0.5)

-delay (delay)

a = Env.perc(0.05, 1, 1, -4);
b = a.delay(2);
a.test.plot;
b.test.plot;

a = Env([0.5, 1, 0], [1, 1]).plot;
a.delay(1).plot;

-circle (timeFromLastToFirst = 0, curve = 'lin')

(
{ SinOsc.ar(
	EnvGen.kr(
		Env([6000, 700, 100], [1, 1], ['exp', 'lin']).circle.postcs)
	) * 0.1
	+ Impulse.ar(1) }.play;
)

(
{ SinOsc.ar(
	EnvGen.kr(
		Env([6000, 700, 100], [1, 1], ['exp', 'lin']).circle(1).postcs,
		MouseX.kr > 0.5)
	) * 0.1
	+ Impulse.ar(1) }.play;
)

-test (releaseTime = 3)

-plot (size = 400, bounds, minval, maxval)

-asSignal (length = 400)

-asArray

-isSustained

-range (lo = 0, hi = 1)

-exprange (lo = 0.01, hi = 1)

a = Env.adsr;
a.levels;
a.range(42, 45).levels;
a.exprange(42, 45).levels;

(
// Mapping an Env to an exponential frequency range:
{
	SinOsc.ar(EnvGen.ar(Env.perc(0.01, 0.2).exprange(40, 10000), doneAction: 2)
		, 0, 0.1).dup;
}.play(s)
)

Client-side Access and Stream Support

Sustain and loop settings have no effect in the methods below.

-at (time)

Env.triangle(1, 1).at(0.5);

-embedInStream (inval)

-asStream

(
{
e = Env.sine.asStream;
5.do({
	e.next.postln;
	0.25.wait;
})}.fork
)

Inherited instance methods

Undocumented instance methods

-shapeNumber (shapeName)

-asOSCArgEmbeddedArray (array)

-asControlInput

-releaseNode [= z]

-releaseTime

-plotOld (size = 400, bounds, minval, maxval, parent)

-loopNode [= z]

-hash

-storeArgs

-== (that)

-asPseg

-segment (start, end, normalize = false)

-plot2 (size = 400, bounds, minval, maxval)

Examples

s.boot; 	//.test below will run a synthesis example
		// to demonstrate the envelope, so the Server must be on

// different shaped segments: .plot graphs the Env
Env.new([0,1, 0.3, 0.8, 0], [2, 3, 1, 4],'linear').test.plot;
Env.new([0.001, 1, 0.3, 0.8, 0.001], [2, 3, 1, 4],'exponential').test.plot;
Env.new([0, 1, 0.3, 0.8, 0], [2, 3, 1, 4],'sine').test.plot;
Env.new([0.001, 1, 0.3, 0.8, 0.001],[2,3,1,4],'welch').test.plot;
Env.new([0, 1, 0.3, 0.8, 0], [2, 3, 1, 4],'step').test.plot;
Env.new([0, 1, 0.3, 0.8, 0], [2, 3, 1, 4], -2).test.plot;
Env.new([0, 1, 0.3, 0.8, 0], [2, 3, 1, 4], 2).test.plot;
Env.new([0, 1, 0.3, 0.8, 0], [2, 3, 1, 4], [0, 3, -3, -1]).test.plot;

If a release node is given, and the gate input of the EnvGen is set to zero, it outputs the nodes after the release node:

// release node is node 1; takes 0.5 seconds to go from 0 to 1,
// sustains at level of 1, then released after three seconds
// (test causes the release after three seconds, given the argument 3),
// taking 2 seconds to finish
Env.new([0,1,0],[0.5,2],'linear',1).test(3).plot

// more complex examples
// release node is node 2; releases after 5 sec
Env.new([0.001,1,0.3,0.8,0.001],[2,3,1,4] * 0.2, 2, 2).test(5).plot;
Env.new([0.001,1,0.3,0.8,0.5,0.8,0],[2,3,1,2,2,1] * 0.2, 2, 2).test(5).plot;

// early release: goes straight onto the release node after 0.1 seconds
Env.new([0.001,1,0.3,0.8,0.5,0.8,0],[2,3,1,2,2,1] * 0.2, 2, 2).test(0.1).plot;

If a loop node is given, the EnvGen outputs the nodes between the loop node and the release node (not including the release node itself) until it is released:

// release node is node 2, loop node is node 0: so loops around nodes 0 (lvl 1, dur 0.5)
// and 1 (lvl 0.1, dur 0.5) 		//until released after 3.5 seconds
Env.new([0,1,0.1,0],[0.5,0.5,2], 'lin', 2, 0).test(3.5).plot;

// this just sustains at node 0, because there is no other node to loop around!
Env.new([0,1,0],[0.5,2], 'lin', 1, 0).test(3.5).plot;

// more complex example: release node is node 3, loop node is node 1
Env.new([0.001,1,0.3,0.8,0.5,0.8,0],[2,1,1,2,3,1] * 0.1, 'lin', 3, 1).test(3).plot;

newClear

(
SynthDef(\help_Env_newClear, { |i_outbus=0, t_gate|
	var env, envctl;
	// make an empty 4 segment envelope
	env = Env.newClear(4);
	// create a control argument array
	envctl = Control.names([\env]).kr( env.asArray );
	Out.ar(i_outbus, SinOsc.ar(EnvGen.kr(envctl, t_gate), 0, 0.3));
}).send(s);
)
(
s.bind {
	// must not have more segments than the env above
	e = Env([700,900,900,800], [1,1,1], \exp); // 3 segments
	x = Synth(\help_Env_newClear, [\t_gate, 1]);
	x.setn(\env, e.asArray);
};
)
(
// reset then play again
e = Env([800,300,400,500,200], [1,1,1,1], \exp); // 4 segments
x.setn(\env, e.asArray);
x.set(\t_gate, 1);
)
x.free;

blend

a = Env([0, 0.2, 1, 0.2, 0.2, 0], [0.5, 0.01, 0.01, 0.3, 0.2]).test.plot;
b = Env([0, 0.4, 1, 0.2, 0.5, 0], [0.05, 0.4, 0.01, 0.1, 0.4]).test.plot;

(
Task({
	f = (0, 0.2 .. 1);
	f.do { |u|
		blend(a, b, u).test.plot;
		2.wait;
		Window.allWindows.pop.close; // close last opened window
	}
}).play(AppClock);
)

// blend in a SynthDef
(
SynthDef(\help_EnvBlend, { | fact = 0 |
	Out.ar(0, EnvGen.kr(Env.perc.blend(Env.sine, fact), 1.0, doneAction: 2)
		* SinOsc.ar(440,0,0.1)
	)
}).send(s));

(
{
f = (0, 0.1..1);
f.do({|fact| Synth(\help_EnvBlend, [\fact, fact.postln]); 1.wait;});
}.fork;)