Multistep Envelope

User Manual
The multistep envelope is a time/level type, where you specify levels, and the times that
it takes to get from one level to the next. Levels are specified by inserting breakpoints
along a line, then moving the breakpoints up or down to change levels, and left or right
to change times.
To insert a breakpoint do right-click wherever you want one. To delete a breakpoint do a
right-click on it. The first and last breakpoints move up and down together, because the
envelope starts from where it ended.
There are two breakpoints with a vertical red line running thru them. If there is no other
breakpoint between them, the red lines indicate the segment where the envelope
reaches the "sustain" level, marked
by the horizontal red line. On this level the envelope stays as long as the key is held
down. If you insert one or more breakpoints between the red markers the "sustain"
segment becomes a "loop". This means that this part will be repeated as long as the
note is sustained. If there are more than 3 breakpoints the sustain or loop segment can
be shifted by moving the vertical red lines with the mouse. They snap to the next
breakpoint, except the start and the end point. Please note that the envelope doesn't
jump from the loop end to the loop start. Instead it starts a segment from the loop end to
the next breakpoint to the right of the loop start breakpoint. The interrupted line indicates
this segment. If you want to simulate a jump from the loop end to the loop start you need
to insert a short segment at the end or beginning of the loop, which performs this jump.
Upon releasing the key, the envelope continues with the segments after the second red
marker. If it reaches the end breakpoint, it holds the end level until the envelope is
started again. Dragging the small squares between breakpoints can change the lines
shape between the breakpoints from concave, to straight, to convex.
Zoom and Envelope Ruler
There are two ways to set the visible range of the envelope. You can use the
background of the envelope as well as the the ruler underneath the envelope:
If you click on the background of the envelope without hitting the envelope itself, you can
shift the envelope and zoom in/out simultaneously: Dragging to the left or right shifts the
envelope, dragging up zooms out and dragging down zooms in. If you want to shift and
zoom in/out independendly you can use the ruler. Use the left mouse to shift and the
right mouse to zoom in.
Double-click on the ruler or on envelope display to set the zoom factor so that the whole
envelope fits on the display.
Please note that the zoom factor does not only change the display, but also sets the
quantization time for the 'Tempo Sync' function (described later). Note also that when
zooming, the point of the envelope where you right click is fixed. When zooming out this
is only the case until the beginning of the envelope is visible at the left end of the ruler.
Upon further zooming out, the zero point becomes fixed.
Envelope Parameter Displays and Functions
Now lets investigate the envelope parameter displays and functions above the
envelope. Clicking on a number and dragging up or down edits the value. Some of them
also update automatically if you select another breakpoint.
Step shows the index number of the selected breakpoint. Clicking on it and dragging up
or down selects another breakpoint.
Last shows and sets the total number of envelope breakpoints. The maximum number is
50.
Mode has two options, 'Sticky' and 'Fix'. In 'Sticky' mode, if you move a breakpoint left
or right, the envelope to the right of the breakpoint moves as well to maintain the same
times and levels past the breakpoint being edited. In 'Fix' mode, the total envelope time
doesnt change. Moving a breakpoint to the right not only lengthens its distance
compared to the breakpoint to its left, but shortens the distance compared to the
breakpoint at its right.
Time Abs, shortform of absolute time, shows and sets the amount of time in seconds
from the start of the envelope to the breakpoint being edited.
Time Rel, shortform of relative time, shows and sets the amount of time in seconds from
the breakpoint being edited to the breakpoint at its immediate left.
Level shows and sets the breakpoint level.
Shape shows and sets the shape of the line between breakpoints. 0.5 indicates a
straight line. 1 indicates a maximally convex curve. 0.05 indicates a maximally concave
curve.
Sync, shortform of 'Tempo Sync', superimposes a grid on the envelope display that
corresponds to rhythmic values, such as quarter notes, eighth notes, 16th notes, etc.
Breakpoints can be snapped to these points. The quantization value depends on the
current zoom factor (see section 'Zoom and Envelope Ruler'). If the incoming tempo
information at the BPM input of the macro (see below) changes, the envelope times are
re-computed to match the current song tempo. Example: If the envelope loop is set to a
1 beat duration, it will remain 1 beat long as the tempo changes. If an envelope has
already been created, enabling Tempo Sync will not change the existing breakpoints.
However, you can edit an existing envelope by moving the breakpoints so that they snap
to the nearest quantization value.
Please note that the breakpoints are snapping to the quantisation points if they are
dragged by the mouse. If the time values are changed by clicking and dragging on the
'Time Abs' and 'Time Rel' displays they do not snap, which allows 'in between' values.
The displayed times do not vary with changing tempo. Instead they are calculated for a
tempo of 120 BPM (beats per minute). Which means a length of 2 seconds equals a
whole note or one bar.
Grid shows the calibration of the ruler markings. When 'Tempo Sync' is enabled, the
ruler markings will be calibrated in rhythmic values instead of seconds. The grid size
depends on the current zoom factor (see section 'Zoom and Envelope Ruler'). Clicking
and dragging this display sets the zoom factor.
Beat Time shows and sets the absolute time of the breakpoint being edited in rhythm
notation. The first value is the number of bar, the second indicates the 1/4 note in that
bar and the third the 1/16 note in that 1/4 note. The counting starts with 1. Which means
the start of the envelope is 1/1/1. The displayed beat time do not vary with changing
tempo. Instead it is calculated for a tempo of 120 BPM (beats per minute). Please note
that the resolution of the beat time display is limited to 16th notes. So it is possible that
the actual segment time is in between two 16th notes.
Envelope Preset offers a drop-down menu that comes with several common envelope
types.
L means 'Load' and lets you load the selected envelope from the preset list.
S means 'Store" and lets you save the current envelope in the preset list. To save an
envelope you created, select an envelope in the list and click on the 'S'-button. You can
change the name of the stored envelopes in the properties of the preset list.
Builder Manual:
Important note: The envelope does not work correctly in ensembles set to 'Reaktor 4
Legacy Mode'. It will not initialise in the right way. Please make sure that 'Reaktor 4
Legacy Mode' in the left-most folder of the ensemble properties is not checked!!
Macro Inputs
G Input for the Gate signal. (G) > 0 starts the envelope and determines it's peak value.
(G) = 0 starts the release period.
TMd sets the re-trigger mode. It defines the way the envelope starts at incoming Gate
signals. With 0 the envelope first resets to the level of the start breakpoint (the first
visible breakpoint from the left) before it starts the first segment. With 1 the envelope
starts at its current level. With 2 the envelope will start at its current level if the first
segment is shorter than 100 ms, otherwise it will make a short additional segment of 5
ms to the start breakpoint. After that the actual first segment starts.
Mode 1 and 2 help to reduce glitches if "note stealing" occurs, which means if the
envelope is retriggered before it reaches its end. Mode 2 makes sure that the first
segment (with a duration longer than 100 ms) sounds always the same no matter if
"note stealing" occurs or not.Only the additional 5 ms segment will sound differently,
depending on the current level of the envelope at trigger trime. Mode 0 can be used for
modulation if "note stealing" is not a problem, e.g. pitch modulation, wavetable
modulation etc.
BPM sets the tempo in beats per minutes. The envelope times are synced to this tempo
if 'Tempo Sync' is enabled.
TSc sets the time scaling. The segment times are multiplicated by this factor. A value=1
leaves them unaltered. This input can be used to implement velocity sensitivity of the
segment times.
How to customize?
The envelope can be customized in some aspects. Mainly regarding the look of it. The
paths in the following text refers to the macro hierarchy inside the envelope's main
macro.
Object Colours (GUI/Graph Display/Color Constants) The color of the following objects
in the envelope display can be set: breakpoints, shapepoints, conecting line between
breakpoints, loop markers, frame around the envelope field, the middle line in the bipolar
envelope and the beat grid including different transparencies for bars, 1/4 notes. For the
ruler the colour of the grid can be set. All values should be in the range 0 to 1. More
infos can be found in the mouse over help of the constant names.
The Background Colours of the envelope display and the ruler can be set in the
properties of the corresponding 'multi displays'. These can be found on the panel
underneath the mouse area modules of the displays. In the structure you can find these
modules in the following macros: Env Display: (GUI/Graph Display), Ruler Display
(GUI/Graph Display/Ruler)
The Size of the Envelope Display and the Ruler can be set in the properties of the
corresponding 'multi displays' (see 'background colours' for location). It is necessary that
the ruler and the envelope display have the same 'Size X' number and that the mouse
area modules on top of the multi displays have the same size as the multi display
underneath them! If you change the size of the envelope display, you must also set the
'X Pixel' and 'Y Pixel' constants in GUI/Graph Display/Constants macro to the same
values as in the multi display. After changing the size just click on the display so the
graphic is redrawn.
The numbers of Y pixels of the envelope display determines the stepsize when a
breakpoint is dragged with the mouse in vertical direction to change the level. The
connection between value range, numbers of Y pixel, breakpoint size in pixel (see
below) and stepsize is the following:
unipolar (value range 0 to 1): stepsize=1/(Y pixel - breakpoint size in pixel)
bipolar (value range -1 to 1): stepsize=2/(Y pixel - breakpoint size in pixel)
For instance, to achieve a stepsize of .01 with an unipolar (.02 with a bipolar) envelope
you can choose following combinations:
Size Brkp=5, Y Pixel= 105
Size Brkp=7, Y Pixel= 107
Size Brkp=9, Y Pixel= 109 etc.
The Size of the Breakpoints and Shapepoints in pixels can be set in GUI/Graph
Display/Constants with the 'Size Brkp' and 'Size Sh' constants. Please note that they
have to be an odd number, due to symmetry reasons. Even numbers are converted
internally to odd numbers and the given equation in the previous section concerning the
stepsize isn't true anymore!
The Click Tolerance can be set with the constant 'Click Tol' in pixels. This value
increases the click area which lets you select the breakpoint or shapepoint. Zero means
that you need to hit inside the squares, one means that you can click also one pixel
beside them to select them.
The Length of the Grid Lines of the Ruler in 'Tempo Sync' can be set with the 'Length
Bar', 'Length 1/4', 'Length Rest'. As the names indicate, you can set different length for
grid lines that fall on the beginning of a bar, for 1/4 notes between bars, and the 'rest',
which are grid lines between 1/4 notes. The length is set in relation to the ruler heigth.
One means that the line goes from the top to the bottom of the ruler.
The Maximum Numbers of Grid Lines can be set with 'Max G B' (for 'Tempo Sync'
enabled) and 'Max G T' (for 'Tempo Sync' disabled). These values can be adjusted to
the X size of the envelope display judged by personal taste. With increasing X sizes of
the envelope display, there is space for more grid lines, so the maximum number could
be increased.
Note: If one of these values is changed it might be necessary to adjust the numbers of
objects of the multi display of the envelope AND the ruler!!. To find out the needed
numbers of objects just look at the value at the upper input of the substract module
underneath the envelope AND ruler multidisplay in the structure and type that number in
the 'number of objects' field of the properties of the multi displays. Doublecheck if the
output of the subtract module is zero! (see 'background colours' for the location of the
multidisplays).
The Numbers of Linear Subsegments in the Display can be set in with the 'Subsegs'
constant.If this value is changed it is necessary to adjust the numbers of objects of the
multi display of the envelope. To find out the needed numbers of objects just look at the
value at the upper input of the substract module underneath the multidisplay in the
structure and type that number in the 'number of objects' field of the properties of the
multi display. Doublecheck if the output of the subtract module is zero! (see 'background
colours' for the location of the multidisplay).
To change the Maximum Numbers of Breakpoints the new number has to be typed in
at several different module properties. It is necessary to type in the same value in all of
them!:
1. GUI/Memory Socket/Memory Plugin: the array size of all 'snap value []' modules
have to be set to this new number.
2. Gui/Preset: the 'Y Size' value of the following event table modules have to be set
to the new value: Time, Abs Time, Level, Shape
3. Audio Engine/Array and Marker/Array of Brkpnts Write: The size of all arrays has
to be set to the new value.
4. If the maximum numbers of breakpoints is changed it is necessary to adjust the
numbers of objects of the multi display of the envelope. To find out the needed
numbers of objects just look at the value at the upper input of the substract
module underneath the multidisplay in the structure and type that number in the
'number of objects' field of the properties of the multi display. Doublecheck if the
output of the subtract module is zero! (see 'background colours' for the location of
the multidisplay).
5. Please make sure that the mouse over text of the "Last" display mentions the
right maximum number of breakpoints.
In GUI/Graph Display/Constants you can also specify the Maximum Time a segment
can have. This value should not be greater than 999999, which corresponds to 999
seconds.
In (Audio Engine/Constants) you can set the following parameters:
Attack Thresh: Sets the Threshold of the Segment Time for the Trigger Mode 2 in
milliseconds. (see description of the 'TMd' macro input above)
Extra Ramp T: Sets the Length of the Additional Ramp in Trigger Mode 2 in
milliseconds. (see description of the 'TMd' macro input above)
Bitmaps
Some controls and displays which come with the envelope use bitmaps to show their
values. These are: Sync, Grid, 1/4 and 1/16 note display of the Beat Time, the L and S
buttons of the presets and Mode. They explain themself, just open their properties to see
the different 'animations'.
I included the original bitmaps seperatly so they can be edited.
Sharing Preset Memory of several Envelopes in one Ensemble
To let several envelopes share the same presets so you can exchange envelopes
between them you need to make the event tables in the Gui/Preset macro to share the
same memory, means that there is only one memory, but with multible clients. Please
read the manual about event tables.
Import-Export between different Ensembles
To import the data of one envelope to another you can choose one of two ways. You can
replace the 'GUI/Memory Socket/Memory Plugin' macro by the Memory Plugin macro of
the envelope you want to copy from. This macro contains all data of the envelope. Or
you can store the wanted envelope as a preset, save the Gui/Preset macro as a
seperate file, replace the preset macro of the envelope you want to copy to and load the
wanted preset in the envelope. Please note that presets do not store the state of the
'Tempo Sync' button.