EnvelopeString class overview

Envelope Syntaxes

---

There are six types of envelope syntaxes recognized by the EnvelopeString class: CLM, LISP, MUSICKIT, MATHEMATICA, PLAIN, and SIG.

CLM Envelopes

A CLM envelope consists of a list of numbers separated by spaces and enclosed in parentheses. Commas are optional when reading in an envelope with the setEnvelope command. The output envelope with getEnvelope, however, will always contain no commas. The default dimension of envelope points is 2 unless specified otherwise in the setEnvelope command. Here is an example of a CLM envelope:

   (0 0 0.496 0.697 0.661 0.460 0.726 0.878 1 0)

LISP Envelope

A LISP Envelope is similar to a MusicKit envelope, except that the outer enclosure is a set of parentheses instead of square brackets. No stick point is allowed. An Example LISP Envelope:

  ((0.000 0.000)(0.496 0.697)(0.661 0.460)(0.726 0.878)(1.000 0.000))

For the EnvelopeString class, you may optionally add commas between numbers. The default interpolation type for LISP envelopes is linear interpolation.

MusicKit Envelope

A MusicKit Envelope is surrounded by square brackets, each pair of envelope points is surrounded by parentheses. A stick point is specified between envelope points by a pipe ("|"). There is only one stick point in an envelope, and it comes outside of the parentheses pairings. Here is an example of a MusicKit envelope:

   [(0,0)(0.496,0.697)(0.661,0.460)(0.726,0.878)|(1,0)]

For the EnvelopeString class, it is unimportant whether you include the commas in the envelope when calling the setEnvelope function. The default interpolation type for MusicKit envlopes is linear interpolation. If a stick point is included in the envelope, then time in envelope is described in seconds.

Mathematica Envelopes

Mathematica envelopes are similar to LISP envelopes, except that they use curly braces instead of parenthesis, and also, each envelope point is separated by commas as are the elements inside each envelope point. Here is an example of a Mathematica envelope:

   {{0, 0},{0.496, 0.697},{0.661, 0.460},{0.726, 0.878},{1, 0}}

Plain Envelopes

A plain envelope consists of a list of numbers separated by commas. Commas are optional when reading in an envelope with the setEnvelope command. The output envelope with getEnvelope, however, will always contain commas. The default dimension of envelope points is 2 unless specified otherwise in the setEnvelope command. Here is an example of a Plain envelope:

   0, 0, 0.496, 0.697, 0.661, 0.460, 0.726, 0.878, 1, 0

Sig Envelope

Sig envelopes are enclosed in parentheses. Each envelope point group is separated by a semi-colon (";"). Optional commas can delimit envelope point data. Optional interpolation data can be specified in the envelope. There are two optional dimensions to each envelope point: (1) the interpolation type, which is a single character (case insensitive), and (2) an optional interpolation parameter, which can be passed to the interpolation mechanism. The default interpolation is linear, however other interpolation types may be made the default by specifying their character value before the opening parenthesis of the envelope point set. An example Sig Envelope:

     G(0 0 L; 0.5, 0.7; 0.7 0.5; 0.8 0.9; s; 1.0 0.0)t

If a stick point is used, then an optional character following the closing ')' of the envelope will specify if the time units of the envelope represent time in seconds ('t'), or samples ('m'). The default is 'm'. Spacing in all envelopes is unimportant.

Types of interpolation recognized by a sig envelope:

   C = Constant interpolation: there is no interpolation between the
       current envelope point and the following point.  Use just the
       value of the last point.

   L = Linear interpolation.

   G = Geometric interpolation.

   H = Harmonic interpolation (not yet implemented).
 
   K = Turkey interpolation (not yet implemented).

   B = Cubic interpolation (not yet implemented).

   X = Exponential (MusicKit) interpolation (not yet implemented).

Other types of envelopes which may be allowed in the future:

• Arrays

Interpolation of Envelopes

---

Envelopes describe a function with a discrete set of points. Here for example, is a set of envelope points:

These envelope points can be used with various interpolation types to generate a continuous function which gives dependent values for any unspecified independent values.

Constant interpolation does not alter the dependent value(s) of the previous point until a new point is reached:

Linear interpolation draws straight lines between the envelope points:

Geometric interpolation draws straight lines between points on a log scale (on the y-axis), but when converting back to a linear scale, the lines curve:

Envelope Format Define Types

---

The Envelope format types are integers. Here are the defines for each type of envelope syntax:

Unknown Envelope        UNKNOWN_ENV     (0)
CLM Envelope            CLM_ENV         (1)
LISP Envelope           LISP_ENV        (2)
MusicKit Envelope       MUSICKIT_ENV    (3)
                        MK_ENV          (3)
Mathematica Envelope    MATHEMATICA_ENV (4)
                        MMA_ENV         (4)
Plain Envelope          PLAIN_ENV       (5)
Sig Envelope            SIG_ENV         (6)