EnvelopeString class overview
Goto: [
Envelope Syntaxes |
Envelope Interpolation |
Defines
]
An EnvelopeString describes a function with one independent variable
and one or more dependent variables. Usually the independent variable
is "time" but can represent anything, such as "harmonic".
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:
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:
Geometric interpolation can be used to sweep through frequecy on an
equal-interval basis, whereas linear interpolation would sweep through
frequency on a harmonic basis. Note that numbers less than or equal
to 0 are not allowed in a geometric interpolation, so there is no
curve shown above when the envelope points are at 0.
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)