update for clarity

envelopes.lib

@@ -235,10 +235,10 @@ adsr_bias(att, dec, sus, rel, bias_att, bias_dec, bias_rel, legato, gate) = enve
 with {
   ugate = gate>0;
 
-  // In these functions below
-  // b: bias between 0 and 1. Bias above 0.5 pulls values upward.
+  // In the functions below, we use the equation `y=bias_curve(b,x)`.
+  // b: bias between 0 and 1. Bias of 0.5 results in `y=x`. Bias above 0.5 pulls y upward.
   // x: input between 0 and 1 that needs to be remapped/biased into `y`
-  // y: `x` after it has been biased.
+  // y: `x` after it has been biased. (y==0 iff x==0) AND (y==1 iff x==1)
   bias_curve(b,x) = (x / ((((1.0/b) - 2.0)*(1.0 - x))+1.0));
 
   // d/dx of bias_curve(b,x)
@@ -249,31 +249,33 @@ with {
 
   fb(_state, _y) = nextState, nextY
   with {
-    // legato control
+    // Legato control
     onset = ba.impulsify(ugate);
     state = select2(onset, _state, 0), _state : select2(legato);
     y = select2(onset, _y, 0), _y : select2(legato);
 
-    // state 0: release
-    // state 1: attack
-    // state 2: dec 
+    // State 0: release
+    // State 1: attack
+    // State 2: decay 
 
     y_at_release = y : ba.latch(ugate==0);
 
-    // slope is a y-distance divided by a number of samples
+    // Slope is a y-distance divided by a number of samples
     att_slope = 1 / max(1,(att*ma.SR));
     dec_slope = -(1-sus) / max(1,(dec*ma.SR));
     rel_slope = -y_at_release / max(1,(rel*ma.SR));
 
-    k = bias_rel, bias_att, bias_dec : select3(state) : aa.clip(.03, .97);
+    // Get bias based on the state, then clip for safety.
+    b = bias_rel, bias_att, bias_dec : select3(state) : aa.clip(.03, .97);
 
+    // We will remap from an input domain to [0..1] based on the current state.
     from1 = ba.if(state==2, sus, 0);
     from2 = ba.if(state==0, y_at_release, 1);
 
-    // prevent divide-by-zero in it.remap
-    pct = it.remap(from1, from2, 0, 1, y), 0.5 : select2(from1==from2) : bias_curve_inverse(k);
+    // Prevent divide-by-zero in it.remap
+    pct = it.remap(from1, from2, 0, 1, y), 0.5 : select2(from1==from2) : bias_curve_inverse(b);
 
-    slope = rel_slope, att_slope, dec_slope : select3(state) : _*bias_curve_d_dx(k, pct);
+    slope = rel_slope, att_slope, dec_slope : select3(state) : _*bias_curve_d_dx(b, pct);
 
     nextY = y + slope : aa.clip(from1, 1);
     nextState = select2(ugate,
@@ -319,10 +321,10 @@ ahdsr_bias(att, hol, dec, sus, rel, bias_att, bias_dec, bias_rel, legato, gate)
 with {
   ugate = gate>0;
 
-  // In these functions below
-  // b: bias between 0 and 1. Bias above 0.5 pulls values upward.
+  // In the functions below, we use the equation `y=bias_curve(b,x)`.
+  // b: bias between 0 and 1. Bias of 0.5 results in `y=x`. Bias above 0.5 pulls y upward.
   // x: input between 0 and 1 that needs to be remapped/biased into `y`
-  // y: `x` after it has been biased.
+  // y: `x` after it has been biased. (y==0 iff x==0) AND (y==1 iff x==1)
   bias_curve(b,x) = (x / ((((1.0/b) - 2.0)*(1.0 - x))+1.0));
 
   // d/dx of bias_curve(b,x)
@@ -333,34 +335,35 @@ with {
 
   fb(_state, _y) = nextState, nextY
   with {
-    // legato control
+    // Legato control
     onset = ba.impulsify(ugate);
     state = select2(onset, _state, 0), _state : select2(legato);
     y = select2(onset, _y, 0), _y : select2(legato);
 
-    // state 0: release
-    // state 1: attack
-    // state 2: hold
-    // state 3: dec 
+    // State 0: release
+    // State 1: attack
+    // State 2: hold
+    // State 3: decay 
 
     y_at_release = y : ba.latch(gate==0);
 
-    // slope is a y-distance divided by a number of samples
+    // Slope is a y-distance divided by a number of samples
     att_slope = 1 / max(1,(att*ma.SR));
     hold_slope = ba.if(gate, att_slope, rel_slope);
     dec_slope = -(1-sus) / max(1,(dec*ma.SR));
     rel_slope = -y_at_release / max(1,(rel*ma.SR));
 
-    // release, attack, hold, decay
-    k = bias_rel, bias_att, .5, bias_dec : ba.selectn(4, state) : aa.clip(.03, .97);
+    // Get bias based on the state, then clip for safety.
+    // Note that for the hold state, we choose a bias of 0.5 (the middle value).
+    b = bias_rel, bias_att, .5, bias_dec : ba.selectn(4, state) : aa.clip(.03, .97);
 
     from1 = ba.if(state==3, sus, 0);
     from2 = ba.if(state==0, y_at_release, 1);
 
-    // prevent divide-by-zero in it.remap
-    pct = it.remap(from1, from2, 0, 1, y), 0.5 : select2(from1==from2) : bias_curve_inverse(k);
+    // Prevent divide-by-zero in it.remap
+    pct = it.remap(from1, from2, 0, 1, y), 0.5 : select2(from1==from2) : bias_curve_inverse(b);
 
-    slope = rel_slope, att_slope, hold_slope, dec_slope : ba.selectn(4, state) : _*bias_curve_d_dx(k, pct);
+    slope = rel_slope, att_slope, hold_slope, dec_slope : ba.selectn(4, state) : _*bias_curve_d_dx(b, pct);
 
     hold_time = ma.SR * hol;
     hold_timer = ugate : +~(*(ugate * (state != 1)));