Multistep Envelope

User ManualThe 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, markedby 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 line’s 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 FunctionsNow let’s 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 doesn’t 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 InputsG 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= 105Size Brkp=7, Y Pixel= 107Size 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)

BitmapsSome 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 EnsembleTo 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 EnsemblesTo 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.