Manual: Macro Configuration

Zxx Macro Configuration Dialog

The Zxx Macro Configuration dialog is used to set up Zxx Macros.

Macro Syntax

Macros are parametered MIDI messages. They may contain uppercase constants and lowercase variables:

Constants

• The letters A through F and digits 0 through 9 are constants. They are transferred as 4-bit values (also called nibbles).

General Variables

• The letter n is substituted by the last triggered note on the same channel as the macro is called.
• The letter c is substituted by the 4-bit wide MIDI channel number that can be found in the instrument settings.
• Parametered macros (Z00 through Z7F) may also contain the letter z, which is substituted by the 7-bit wide Zxx parameter (00h through 7Fh).
• The letter h is substituted by the number of the tracker channel on which the macro was triggered.
• The letter o is substituted by the parameter of the last Set Offset (Oxx) effect.
• The letter m is substituted by the current play direction of the sample playing on this channel (forward: 0, backward: 1).
• The letter s is substituted by the Roland SysEx checksum of the current SysEx block.

Volume / Velocity Variables

• The letter v is substituted by the current note velocity, including volume slides and such.
• The letter u is substituted by the current computed velocity, which also includes the volume envelope.

Panning Variables

• The letter x is substituted by the current note panning.
• The letter y is substituted by the current computed panning, which also includes the panning envelope.

MIDI Program Change Variables

• The letter a is substituted by the high 7 bits of the MIDI bank number that can be found in the instrument settings.
• The letter b is substituted by the low 7 bits of the MIDI bank number that can be found in the instrument settings.
• The letter p is substituted by the MIDI program number that can be found in the instrument settings.

The Macro Help button shows a quick reference which explains all possible characters.

“Internal” macro messages start with the character combination F0F0 or F0F1 (which is in fact an invalid SysEx message) and are always four bytes (or eight nibbles) long. They are used to control the resonant sample filters and plugin settings. All other MIDI messages are “external” and are directly sent to plugins.

A macro may consist of several internal and external messages and may be up to 31 characters long, so it is for example possible to control filter cutoff and resonance at once in a single macro.

Parametered Macros

Current Macros: A list of the 16 parametered macros. Click on the SF0 through SFF buttons to change the settings for one of them, or select a macro from the Modify macro dropdown list. A Show All button is shown next to all macros that control plugin parameters. Clicking this button shows a list of plugins which can be controlled by this macro.

Only one parametered macro can be active on a pattern channel at a time. To select the active macro, use pattern effects SF0 through SFF to activate the respective macro for future usage with Zxx or \xx commands.

You may choose a pre-configured macro type from the Type dropdown list:

• Unused: This macro does nothing.
• Set Filter Cutoff: Sets the cutoff frequency of the resonant filter. Z00 represents the lowest cutoff frequency, Z7F the highest.
• Set Filter Resonance: Sets the resonance amount of the resonant filter. Z00 means no resonance, Z7F is full resonance.
• Set Filter Mode: Z00 activates the lowpass filter, Z10 activates the highpass filter.
• Plugin Dry/Wet Ratio: Controls the Dry/Wet Ratio of the currently active plugin on the channel the Zxx command occurs in. Z00 means 0% Wet / 100% Dry, Z7F 100% Wet / 0% Dry. Note that channel plugins are prioritised over instrument plugins if both are present on a channel (this is also true for the following macro types).
• Control Plugin Param: For plugin parameter control, you must also specify a parameter that shall be controlled. For this, choose a plugin from the dropdown list below and a parameter from the dropdown list next to that. Note that macros are not bound to a single plugin; they are applied to whatever plugin is active on the channel the Zxx or \xx command is encountered. This effectively means that the plugin dropdown list does not change the macro itself — it is only there to help you pick the correct parameter for the macro. It also means that one and the same macro can control the same parameter of several plugins. For example, the macro F0F08Fz may control parameter 15 of any loaded plugin. Plugin parameter macros may also be assigned from the plugin window.
• MIDI CC: Sends a MIDI Control Change to the active plugin. The actual MIDI CC can be chosen from the dropdown list below.
• Channel Aftertouch: Sends a channel aftertouch message to the active plugin.
• Polyphonic Aftertouch: Sends a polyphonic aftertouch message to the active plugin. The last note (the “n” character in the macro) triggered on the same channel as the MIDI Macro is automatically embedded into the MIDI message.
• Pitch Bend: Sends a pitch bend message to the active plugin. The lower 7 bits of the pitch bend message are always zero.
• Custom: Allows you to enter a custom macro.

The Value edit field shows the actual macro. You can enter a custom macro here, but it must follow the macro syntax described above. Custom macros are for example useful for sending raw MIDI events to plugins.

Fixed Macros

Here you can configure the 128 fixed macros. From the Preset list, you may choose one of the following presets:

• Unused: All fixed macros do nothing.
• Z80-Z8F controls Resonance (default): Sets the resonance amount of the resonant filter. Z80 means no resonance, Z8F is full resonance.
• Z80-ZFF controls Resonance: Same as above, but with increased granularity. Z80 means no resonance, ZFF is full resonance.
• Z80-ZFF controls Cutoff: Sets the cutoff frequency of the resonant filter. This is identical to the first default parametered macro, so it is pointless to use both in the same track.
• Z80-ZFF controls Filter Mode: Toggles the filter mode of the resonant filter. Z80 activates the lowpass filter, Z90 activates the highpass filter.
• Z80-Z9F controls Resonance + Filter Mode: Z80 through Z8F set the resonance of the resonant filter (like the first preset), Z90 activates the lowpass filter, Z92 activates the highpass filter.
• Z80-ZFF controls Channel Aftertouch: Sends a channel aftertouch message to the active plugin.
• Z80-ZFF controls Polyphonic Aftertouch: Sends a polyphonic aftertouch message to the active plugin. The last note (the “n” character in the macro) triggered on the same channel as the MIDI Macro is automatically embedded into the MIDI message.
• Z80-ZFF controls Pitch Bend: Sends a pitch bend message to the active plugin. The lower 7 bits of the pitch bend message are always zero.
• Custom: This “preset” is shown if you customize any of the 128 fixed macros. For example, you may copy any of the parametered macro presets to a fixed macro and replace the z character by two constants (A-F) or any of the other available variables.

Choose a macro from the Customize dropdown list to edit any of the fixed macros.

Default Configuration

OpenMPT’s default macro configuration is as follows:

• The first parametered macro controls cutoff.
• All other parametered macros do nothing.
• Fixed macros Z80 through Z8F control resonance, Z90 through ZFF do nothing.

This can be overridden by a default user macro configuration, which is used for all newly created tracks. If you happen to use a certain combination of parametered and fixed macros in many tracks, you can click the Set as default button to automatically load this macro configuration for all newly created tracks. It is explicitly not used for tracks which do not have macro information embedded.

Note that template modules provide a more sophisticated way of managing default macro configurations than using the Set as default button, so an empty template module should be preferred over this setting.