The Complete Guide to using Zxx macros

[Harbinger]

I've come a long way since this thread, where i asked about the arcane laguage of Zxx commands and how to use them to manipulate VSTs. I now give you the Official Tutorial for using Zxx macros, especially for VSTs.

I intend this to be part of a bigger project, the Offline Help Manual, for which i will post elsewhere, so allusions to "chapters" can be ignored in this local context.

If there are corrections that need to be made, or additional information that will round out the knowledge (it should be the end-all for all things Zxx), please mention it in this thread, and provide links for previously discussed items if necessary, and i will amend this post later if confirmed. :wink:


Using Zxx Macros

With .it and compatible track file formats (including ModPlug's .itp and .mptm types), the Zxx channel effect can be used to handle certain parameters, and were originally termed 'macros'. Macros are used for two main reasons: 1.) to apply resonance and cutoff filters to samples, and 2.) to control settings in non-MPT sound generators and effects, like MIDI synthesizers and VSTs.

Applying Resonance and Cutoff
Using Zxx to apply resonance and cutoff to samples during playback is done the same way as applying other channel FX — in the channel FX column (the last set of entry fields in a column), enter Z and the value of the res/cutoff you wish to apply to the sound. Values Z00 – Z7F will filter the sample resonance, while Z80 – ZFF will filter it by cutoff. These can be changed in the Zxx Macro window.

When applied to instruments, this is the same as altering the respective sliders in the Instrument Tab.

Keep in mind this assumes that no other SFx values have been previously entered. If so, you will need to pass an SF0 value before using the Zxx parameters for res/cutoff control. (It is also possible to reconfigure the SF0 res/cutoff control to another SFx, or to use SF0 for VST control, bypassing the res/cutoff control capability.)

Controlling VSTs

If you use VST Effects or VST Instruments, however, you will probably be using Zxx macros to alter their settings, which is equivalent to turning knobs and clicking buttons on the VST, except that it's done during playback of the track or pattern. Zxx can also be used for passing MIDI messages to VSTs (that use them) or external MIDI synthesizers. The following is how to use Zxx macros for controlling your hardware or software synth (if you're unsure what VSTs are, see the chapter on VSTs to get an understanding of what this feature is).
Before getting started, make sure you have a VST applied to an instrument. See the chapter on VSTs to familiarize yourself with this procedure.

Configuring Macros Manually

1. Macros must be able to know which control to alter, so you must affix an SFx to a control of your VST. You can do this one of two ways — Manual Entry or Learning. If you know the value of the control, then you can enter it manually in the Zxx Macro window. Go to the Pattern page and click on the Zxx icon (or press your keyboard shortcut); this will bring up the Zxx dialog.

2. Click the button of one of the SF numbers you wish to use for controlling the particular VST setting; you can choose SF0 – SFF. This means there is a limit of 16 VST/MIDI parameters per plugin that can be controlled in a song (but see note at end). This SF number is the channel FX you will call up before using macros.

3. Select "Control Plugin Param" from the Macro Type popup menu, as shown above.

4. You will be presented with a list of VST plugins that this SFx will apply to. Select the plugin you're trying to control. Now choose the controller value from the Macro Value popup menu.

A well-written VST will have descriptions to help you choose the setting you wish to alter in the song. In this example we want to control the High Pass mix (controller 29) for our String Theory plugin.

5. Close this dialog window (click OK) and open the Pattern Tab.

6. In the Pattern Editor, input the note, then enter the SFx value that we wish to alter — in this case SF1, as shown by the red arrow.


It's important to remember, that the first time an SFx control is used in a channel, it must accompany an instrument assignment (the number in the Instrument column of the Pattern Editor), but not necessarily a note assignment. Any subsequent SFx calls are applied to the MOST RECENT instrument, if one isn't currently specified. It is therefore a good idea to keep one instrument per channel when using SFx controls, as it can get confusing pretty quickly when using many of them.

7. Now you can enter Zxx values to alter the setting in realtime playback. Here, as indicated by the green arrow, we've entered Z values between 0 and 69 (hex $45). IMPORTANT: to alter any given setting, the desired SFx must be called BEFORE altering it with Zxx values. Any subsequent Zxx values alters the MOST RECENT SFx control that was called in that channel for that instrument.

8. Zxx sets an absolute value to that SFx control for that one row, but if you need to slide between two values smoothly, use the backslash effect instead of Z, shown by the blue arrow. This will slide the setting of your VST smoothly, based on the ticks you set in the General Tab. If you set the ticks to 8 (which is per row), ModPlug will turn the VST's knob gradually from one \xx value to the next in 8 levels of gradation. This can be useful for quick knob turns on your synth.

Assign Controllers with Learning

1. The other way of assigning SFx to VST controllers is to get the VST to "learn" which knob goes to which SFx. The first thing you have to do is open the VST interface. (If the VST does not have its own GUI, this will still work. ModPlug Tracker puts VSTs in their own dialog window, and affixes a special VST menu to it, so that every VST can be accessed the same way. ) For this exercise, we'll use one of my favorite VSTi's, String Theory.


2. In the "Info" menu, open the "Macros" submenu. Here you will see what each of the SFx controllers is assigned to. To "teach" MPT which knob to turn in this VST, select one of the empty SFx slots (in this example, SF1) and release the mouse button.

3. Then click on the desired slider or button in the GUI (you may have to move it a little). When MPT understands the control you wish to assign,  a dialog will appear to remind you what controller goes to which SFx. (Keep in mind, if you leave the GUI while MPT is under this "learning" mode, then MPT gets buggy. MPT either waits until you open the GUI later or it may read the control from another VST during playback; the "learning"behavior is not fully trapped.)
CAVEAT: There are a few VSTs that have so many controls that the number of many of the knobs and buttons cannot be assigned (and therefore controlled thru MPT); this is simply a hard-coded limit.

4. If you decide you want to reassign the SFx to some other VST controller, you must open the Zxx dialog and assign that SFx to "Unused" and start over.

NOTE CONCERNING SFx LIMITS

There are slots for only 16 different controllers for any one VST, including MIDI Control Assignments (numbered $F0 – $FF). However, the SFx assignments apply to different controllers for each VST. So even though the controller numbers are the same no matter what instrument is used, each instrument can have a different control that is accessed.
For example, suppose we set SF1 to control param 29. MPT does not allow us to alter this assignment in a track. However, Control 29 may apply to Hi Pass Mix in Instrument 1, but in Instrument 2 it may control Band Pass Cut, and in instrument 3, it may control Delay Wet/Dry. If you apply SF1 to these 3 different instruments, you will get different parameter controls, even if all called the same time (albeit you must use different channels).
To determine what one SFx assignment controls in ALL instruments, click on the Show All button next to the SFx you want info on. A list appears of what parameters are affected by that SFx assignment.


Assigning Parameter Values With Record Param

You can use the Zxx commands after an SFx has been declared in a channel to set the assigned controller to a particular parameter. But sometimes you're not sure what exactly the value should be. Sometimes sliders are not obvious in the range they can be set, and other times you can't tell how to activate a button so a feature is switched on. Still other times you need an EXACT value to for the playback to render the sound synthesis a very particular way.
Instead of guessing what the value might be, you can have the value recorded into the pattern editor as you control the GUI slider, knob, or button for the assigned controller. Here's how:

1. First, select a field in the fourth column of the channel in the Pattern Editor where you want to have the setting altered when it reaches that point in the playback. You can choose either the prefix place (where the channel FX letter or symbol goes) or the parameter (where the value would be entered).
2. Altho this step isn't necessary, it's usually best to hear how the setting is applied to the note, so you may want to play the pattern before going to the next step. If you do so, make sure the Loop Pattern checkbox is enabled. Also turn off Follow Song, and make sure the cursor is in the field you want to record the value.
3. Next open the VST's (instrument or effect) window. From the Pattern Editor window, this is done by clicking on the Plugin button next to the Main instrument field.
4. In the GUI window, select the Options Menu, then the Record Params menu item, as shown here using the mda Piano VSTi.


5. Now click on the slider or button you wish to manipulate (you may have to move the mouse a little while you adjust the control). The correct value should be entered into the field where you left the cursor. The prefix is designated as the Slider symbol (the backslash \ ) as this is usually the preferred method of assigning macro values. You can, however, set it to Z if so desired.
6. If you don't need to record any values from the VST's window, you must turn off the Record Params option. It doesn't reset itself, even if you close the window.
7. Just remember, this macro parameter will be applied to the last SFx assignment that was last passed in that channel. So be sure to assign the controller to an SFx assignment before it reaches this point in the track.

[Nahkranoth]

Thanks for this info, Harbinger! Though I already knew most of it, I never used the "Learn" function. My usual way is to look for the needed parameter to automate in the list of published vst params. This post hopefully will teach me to make it a lot faster, especially if the published parameters have names like "param 1, param 2, etc".
I sincerely hope there will be a complete manual some day, there are so many little quirks and features of which I know not.
//phew, this was too much for my English

[maleek]

Excellent.

I never knew about the learn function either. That certainly makes a very worthy addition to the macro-arsenal.

Good job!

[Harbinger]

Glad to be of help!

And if anyone has any questions because it's not covered in this page or it's unclear, i want to know. Like i said before, this should be the repository for all questions regarding Zxx and VSTs. This way if any new users do a search trying to learn about controlling VSTs, they'll hit this page for complete help.
Soon, once i get my Alesis hooked up, i will start using the MIDI aspects and do a write-up on manipulating MIDI with Zxx (altho much of it is the same, using MIDI CC assignments).

At some point in the future, i will "declare" this page complete, and if someone knwos how to write in the Wiki, they can post it there as part of the ONLINE help manual.

[Saga Musix]

For ultimate completeness, you'll also have to cover the "MIDI Mapping" dialog which can be found in the "View" menu.

[LPChip]

Great article, deserves to be in the technical documents section.

[Sam_Zen]

Right on.

[Harbinger]

Thanks for the move, LP! I was hoping you would do that!

UPDATE:

Added a section on the end for Recording Parameter values from the VST. Take a read! :wink:

[BooT-SectoR-ViruZ]

very well made guide...

...though:

It's important to remember, that the first time an SFx control is used in a channel, it must accompany an instrument assignment (the number in the Instrument column of the Pattern Editor), but not necessarily a note assignment. Any subsequent SFx calls are applied to the MOST RECENT instrument, if one isn't currently specified. It is therefore a good idea to keep one instrument per channel when using SFx controls, as it can get confusing pretty quickly when using many of them.

that's not necessarily true... if you assign your VST to the whole channel, you don't need an initial note or instrument.

to not tell you rubbish here i'll investigate this a little in the evening and post it here.


edit:
confirmed....

[Harbinger]

Good info. I want all aspects covered including the little nuances like this. Draft of the manual will be updated.

Thanks BSV!

[maleek]

I would love to see this FAQ updated later with more information on how to get external midi-controllers to work with OMPT. I am having a hard time getting my Trigger Finger to work with it as is. But I guess since it is such a new addition, it might still be highly experimental.

Edit: I just saw the boot-sector tutorial, I'll try out that first before I'll ask more questions.  

[Saga Musix]

I'm not sure if this is the right place to mention as the topic title says that this tutorial is about Zxx, but it should be mentioned that you can also control plugin parameters using dedicated parameter control notes now.

[Harbinger]

I've already written it up in the OHM .4 beta, in a different section than the Macro tutorial, mostly because it's really a completely new and streamlined process -- and for very particular circumstances.