Macros

Macros allow you to modify several parameters at once without specifying exact values for each one. You set up mathematical relationships between the parameters which are maintained as you increase and decrease them as a group.

This walk-through will create a macro where the MAX_WAVEFORM parameter is always set one number higher than the MIN_WAVEFORM parameter. For example, when MIN_WAVEFORM is set to 0 (sine wave) then we'll automate setting MAX_WAVEFORM to 1 (triangle wave) and when MIN_WAVEFORM is set to 3 (custom) then MAX_WAVEFORM will be set to 4 (pulse wave).

First we create an empty macro.

waveformMacro = new Synth.Macro();

Our formula for the MIN_WAVEFORM parameter will be the identity function. When our new macro parameter is set to 0 then MIN_WAVEFORM will be set to 0, when our macro is set to 1 then MIN_WAVEFORM will be set to 1, etc.

waveformMacro.set(Synth.Param.MIN_WAVEFORM, Synth.MacroFunction.ID);

Now we need to write a formula for the MAX_WAVEFORMparameter.

waveformMacro.set(Synth.Param.MAX_WAVEFORM, new Synth.MacroFunction(1, 5, 6, 1));

The first argument to the Synth.MacroFunction constructor tells us that when the macro parameter is set to 0 then MAX_WAVEFORM will be set to 1. The second and third arguments indicate that when the macro parameter is set to 5 then MAX_WAVEFORM will be set to 6. The final argument indicates that the formula used to interpolate values for MAX_WAVFORM for macro values greater than zero and less and five is linear. If this final argument was 2 then a quadratic curve would be used, and so on for any positive power (even non-integer ones). For macro values greater than five the value of MAX_WAVEFORM will be capped at six.

If the final argument were -2 then a quadratic curve would also be used. The difference between positive and negative values is that the curve is concave with respect to the x-axis when the curviness parameter is greater than +1 and convex when the curviness parameter is less than -1. A curviness value of 0.5 will use a square root curve (convex). The interval -1 ≤ curviness ≤ 0 is particularly confusing.

We can now use our macro in a similar way to how we'd change any other parameter. Lets play a note using a combination of the custom wave and the pulse wave. Note that Synth.Wave.CUSTOM is simply a more descriptive way of writing 3 and Synth.Wave.PULSE is a more descriptive way of writing 4.

changes = new Map();
changes.set(Synth.Param.MACRO, [new Synth.MacroChange(Synth.ChangeType.SET, waveformMacro, Synth.Wave.CUSTOM)]);
changes.set(Synth.Param.GATE, new Synth.Change(Synth.ChangeType.SET, Synth.Gate.TRIGGER));
channel1.setParameters(changes);

We can reuse the mathematical relationship established by the macro as many times as we wish simply by repeating these four lines and supplying another value in place Synth.Wave.CUSTOM. Note the use of array syntax. This allows us to adjust more than one macro at once.

There's also a simplified syntax, though it's more limited.

system.setMacro(macro, value, delay, changeType, channelNumber);

As with the regular set() method, the delay, change type and channel number parameters are all optional.

Macro calculations are performed before automation calculations.