An envelope generator UGen. It uses a break point description in its envelope input, typically coming from an Env object. The envelope may be re-triggered using the gate input. Upon start and upon re-triggering, the envelope , levelScale , levelBias and timeScale parameters are polled and remain constant for the duration of the envelope.

To construct a manual envelope without the use of the Env class, the format should be as follows:

val env = Seq[GE](startLevel, numSegments, releaseNode, loopNode,
targetLevel1, duration1, curveType1, curvature1,
targetLevel2, duration2, curveType2, curvature2,
...)

Where the curve-type is one of Curve.step.id , Curve.lin.id , Curve.exp.id , etc. The curvature values are only relevant for the parametric curve type. The releaseNode and loopNode parameters are segment indices or the special value -99 indicating that there are no release or loop segments.

Note: The actual minimum duration of a segment is not zero, but one sample step for audio rate and one block for control rate. This may result in asynchronicity when in two envelopes of different number of levels, the envelope times add up to the same total duration. Similarly, when modulating times, the new time is only updated at the end of the current segment; this may lead to asynchronicity of two envelopes with modulated times.

Examples

// percussive one-shot
play { PinkNoise.ar(EnvGen.kr(Env.perc, doneAction = freeSelf)) }

// fixed duration amplitude envelope
play {
  val env = Env(0, Seq(0.01 -> 1, 0.5 -> 0.5, 0.02 -> 1, 0.5 -> 0))
  SinOsc.ar(470) * EnvGen.kr(env, doneAction = freeSelf)
}

// amplitude and frequency modulation
play {
  val env  = Env(0, Seq(0.01 -> 1, 0.5 -> 0.5, 0.02 -> 0.8, 0.5 -> 0, 0.2 -> 1.2, 0.5 -> 0))
  val gate = Impulse.kr(MouseX.kr(0.2, 3), 0.5)
  val gen  = EnvGen.kr(env, gate)
  SinOsc.ar(270, SinOsc.ar(gen * 473)) * gen * 0.2
}

// Dust-triggered envelope
play {
  val c   = Curve.parametric(-4)
  val env = Env(0, Seq((0.05,0.5,c), (0.1,0.0,c), (0.01,1.0,c), (1.0,0.9,c), (1.5,0.0,c)))
  val gen = EnvGen.ar(env, Dust.ar(1))
  SinOsc.ar(gen * 1000 + 440) * gen * 0.1
}

// two channels
play {
  val p = Curve.parametric(-4)

  def mkEnv(a: Double, b: Double) = {
    val env = Env(0.0, Seq((0.05,a,p), (0.1,0.0,p), (0.01,1.0,p), (1.0,b,p), (1.5,0.0,p)))
    EnvGen.ar(env, Dust.ar(1))
  }

  val gen: GE = Seq(mkEnv(-0.2, -0.4), mkEnv(0.5, 0.9))
  SinOsc.ar(gen * 440 + 550) * gen * 0.1
}

// control gate and done-action
val x = play {
  var gen = EnvGen.kr(Env.adsr(), "gate".kr(0), doneAction = "done".kr(0))
  SinOsc.ar(440) * gen * 0.1
}

x.set("gate" -> 1)  // turn on
x.set("gate" -> 0)  // turn off
x.set("gate" -> 1)  // turn on
x.set("done" -> freeSelf.id, "gate" -> 0) // turn off and free

// fast triggering
play {
  val freq = MouseX.kr(1, 100, 1)
  val gate = Impulse.ar(freq)
  val env  = Env.perc(0.1, 0.9)
  val gen  = EnvGen.ar(env, gate = gate, timeScale = freq.reciprocal)
  SinOsc.ar(440) * gen * 0.1
}