AZSlow

AZ Controller plug-in for Cakewalk SONAR => Documentation => Topic started by: azslow3 on May 29, 2014, 12:08:28 PM

Title: User manual
Post by: azslow3 on May 29, 2014, 12:08:28 PM
Here I am going to explain all aspects of AZ Controller configuration.

If you have not done that yet, I recommend you read About (http://www.azslow.com/index.php/topic,7.0.html) first and than check you are able to use my plug-in following Quick start (http://www.azslow.com/index.php/topic,9.0.html) instructions.

In case you have never written programs in conventional programming languages or some terminology in the following is unclear for you, please check my introduction into programming (http://www.azslow.com/index.php/topic,11.0.html).

User interface.
User interface for AZ Controller is implemented inside SONAR Control Surface Property Page. It can be called from "Utilities" menu or from ACT Module Doc. For more information how to open the window, work with presets and "ACT Learn" button please read SONAR documentation.

I recommend to close the window when you are not changing/checking the configuration. While internal engine is speed optimized, the graphical part is not. The probability of crash is significantly increased once the window is opened.

The window is divided into "Last MIDI event" indicator, several pages (Tabs) configuration section and pure informational footer. In case you report any problem with this plug-in, do not forget to mention what you can see  in "Version" and "SONAR version" areas in the lower right corner.

Last MIDI event
When the plug-in receives some MIDI event it is immediately displayed. Only the very last event is shown. In case you press a key on your keyboard and do not keep it pressed, "Note OFF" event is shown. "Note" (assuming ON) is actually also displayed, but you should keep the key pressed to see it.

Current version of the plug-in recognizes all possible MIDI messages. Known messages are displayed with abbreviation ( N(ote), Ch(annel), CC (Control Change), PC (Program Change), etc). Most SysEx messages are shown in Hex form.

If "OFF" is not displayed, the event is processed with "Note:ON" software state set (explained later).

In some situation, single MIDI message is not shown as an Event (RPN/NRPN, see Parameters in Options Tab).

If the event is assigned to some Logical Control, the information about this Logical Control is also displayed. In case Logical Control is attached to some Hardware Control Context, the Context is shown. Internal Logical Control ID is shown otherwise.

MIDI messages assigned to some "System" Control are still processed normally, but they are not shown as "Last event". In case some periodic MIDI message disturb you, you can assign it to  "System" Hardware Control (see below). You can any time change the control type from "System" to something else to see the event and associated actions.

In case OSC is activated, you can also observe incoming OSC messages. Note that all OSC messages have exactly one parameter, independent from the real message.

Options Tab
Except you planning to use the plug-in for ACT mapping only (see corresponding section), you should start configure AZ Controller here.

All user definable names are entered in this Tab. Several common rules (limitations) applies:

Hardware controls
For each Hardware Control (http://www.azslow.com/index.php/topic,12.0.html) which generate recognizable MIDI Event you should register exactly one "Hardware control" in this plug-in. Even in case such control generate more then one MIDI Event depending on some state (see Hardware States). The only reasonable exceptions are normal keys, in case your controller is combined with a keyboard as well as any modulators. You can check which controls produce recognizable events using "Last MIDI event" monitoring.

There is yet another important exception when you want create 2 Hardware Controls for one physical control: in case this control is touch sensitive (that is not the same as velocity/pressure sensitive). You can recognize such controls by precisely looking what "Last event" display.
Once you have touched such control without moving it, you see one event type (note or CC) but as soon as you start moving/turn it, you see another message type. In that case it make sense to define in addition to "Slider1" control type "Slider" another "Slider1_touch" control with "System" type and assign the first (touch) MIDI event to it. Most practical Action list for such control will be "Touch 'Slider1'" Action (see the 'Touch' Action description).

If your hardware controller allows that, I strongly recommend to check that no different controls under any conditions generate the same MIDI Event. I mean exactly the same, if the Channel is different it is ok. In case one control general the same MIDI Event in many state that is obviously not a problem. If you do not follow this rule, "Instant" mode will not work at all and "Catch" mode is not going to work properly.

Correct controller type (Pad/Rotor/Slider) should be set. This type is used when the same events for different types have different meaning.

The System type has special interpretation. All MIDI assigned to Logical Controls for Hardware Control with such type will not be shown in the "Last MIDI event". Also Action execution progress for these Controls will not appear in the "Overview" tab. That is useful in case your controller generates some periodic events on it's own ("ping" or some "time code" not blocked by SONAR), which prevents you to see (and assign...) normal messages. The whole "protocol handshake" can be "hidden" there as well.

Example: for my MPK Mini I define 8 pads: "B1"..."B8" and 8 rotors: "R1"...."R8". I should NOT define hardware Banks/mode/prog switches and normal keys.

"Dup.(licate)" button. This button can be used to duplicate the whole hardware control, with related context(es) and action lists (but assignments are not duplicated). For example, once you have completely defined "Fader 1" control, it is simpler to duplicate it and modify the copy then recreate near exactly the same control from scratch. Effectively, this button create new Hardware control, context and logical control. In case you use the same logical control for several hardware controls (not recommended in general), the logical control is still duplicated instead of referencing the original one. But not  in case you use the same logical control in several contexts of one hardware control.

Hardware states
If there is some Hardware Control which trigger no MIDI Event but is changing what other controls send, it should be defined as "Hardware State Set". And all its possible positions should be defined as States in this Set.

There is no reason to define controls which have no influence on what the plug-in receives. For example, arpeggiators, power buttons and such.

Example: for my MPK Mini I define "Prog": "Prog1"..."Prog4", "Pad bank": "Bank1" and "Bank2", "Pad mode": "Note","CC","PC".

Software states
There are several system defined sets, which you can not modify (and so they are not visible in the Options Tab). But they can be used in Action Condition (see later) the same way as User defined Software States:

User defined State Sets are not touched and not used by the system. The first State in the list will be Default State. But you can change that (every time you prepend state, it will become default. For historical reason). It is set as current every time SONAR is started or preset is reloaded. Note: when you have just defined Software State Set, the first defined State (so, the last one once you have entered more) is the current. In case you save and reload the preset, the first state in the list will be the current. So I recommend change the state immediately after definition of the whole set to the first (on the Overview Tab). You can Add (prepend) or Append States. You can also append 10 states at once, they will get positional numbers as names prefixed by specified in the text field string. The order of the states can be changed with "spin" buttons, the effect is not immediately visible (till you open the drop box) but it is immediate.

It is not mandatory to define any User State Set. But defining and using them uncover real power of logic programming in this plug-in. It is up to your creativity.

Just to give you an idea what it can be. To implement "ACT MIDI Controller" build in  logic, you need "Shift":"On","Off"; "ACT":"On","Off"; "Strip": "Track", "Bus", "Master"; "Button bank": "1".."4", "Rotor bank": "1".."4" and "Slider bank": "1".."4" (see "ACT MIDI Explained" tutorial).

Advanced: you can declare user Set as dependent  from some other user Set. In this case there will be separate "current" State for each State in that other Set. For example, you have "Resolution" with states "Coarse" and "Fine". But you want remember resolution for each "Mode" ("Mix", "Act") separately. You can define "Resolution_Mix" and "Resolution_Act" as 2 separate Sets. But using such Sets require duplicated actions (like "Mode:Mix Resolution_Mix:Coarse - Value MIDI", "Mode:Act Resolution_Act:Coarse - Value MIDI". You can say that "Resolution" depends on "Mode" instead. In whatever Action you use "Resolution" then (even in Set State Actions), the current State of "Resolution" corresponding to the current state of "Mode" will be used. State monitors on dependent Set are also called when the "master" current State is changed, even in case that does not produce the change in dependent Set (in the example, in case "Mode" is changed, State Monitor for "Resolution" will be called even in case current states in both modes are the same).

Display
Independent from the Property Page, "always on top" not re-sizable window can be used to show some information. The information is organized as a matrix of cells. The size of this matrix, the number of characters per cell, the alignment within cells, the font and backgound color can be customized. Cells can be visually grouped (for example, to use one cell for parameter name and another for the value).

The display can be activated/deactivated either by the button there or by "Display" set of Function Action.

The content of each cell is set separately. See "Display" Action documentation.

Filters
Since ProChannel introduction, there is a bug which prevents determine which ProChannel modules are in strips (names). AZ Controller has some predefined list of modules, which are detected using parameter number and names. Since there are many modules which I do not have and FX Chains have different set of parameters in general, it is possible to "define" another modules using Filters dialog. In the track view, you can see which automation parameters each modules has. Write down the total number and some distinguishable parameter name, it is better if that is the last parameter (for speed), but it is not always unique. Then open Filters dialog, and with "New" selected, enter that information (the name of the module is arbitrary, the rest should match with the module). To delete definition, select "Delete" in the number of parameters (position "zero").

OSC
In this section you see Configure buttons, current OSC status and a button to forget OSC clients. For more information check OSC documentation (http://www.azslow.com/index.php/topic,119.0.html).

Parameters
determine general behavior of the plug-in. It is important to set them correctly. The default should work fine for most cases, do not modify anything there till you understand what are you doing.

"IO options..." dialog. SysEx timing allows limit the number of SysEx messages sent to X per time period Y.  "Suppression" flags are to work with devices which echo values they receive (f.e. some old digital mixers). With "echo from" set, when a message is sent out of control (directly or in monitoring), the next exactly the same message from the device will be ignored. When "echo to" is set, if we are going to send exactly the messages we have sent from that control or received from the device (for that control), it will not be sent. The functionality can be reset with "Reset all monitors" action (to allow complete feedback update).

Current preset can be exported/imported using corresponding buttons. Note that SPP format (using Cakewalk Plug-in Manager) is still preferred way to preserve and publish presets. The feature is not working on old (pre Vista) OS. Note that "Text" export can be used to compare changes in presets ONLY, with some external text "diff" utility. It can not be imported back, the format is cryptic, not documented and can be changed in any version without notice or "backward compatibility". After finding where something is changed, use AZ Controller Interface to find what the changes are.
Continued in the next post...
Title: Re: User manual
Post by: azslow3 on May 30, 2014, 04:42:14 PM
Hardware Tab
Here we teach the plug-in to understand what is going on with our Hardware Controller.

For each Hardware Control defined in the Options Tab we should define one or more Hardware Context. It is a combination of States from Hardware State Sets in which the Control trigger particular MIDI Event.

Each distinct MIDI Event (only channel and type, value is not considered) you are going to use should have associated Logical Control. While not recommended, several contexts can generate the same MIDI Event. That is why "Context" and "Logical control" are separated.

The following procedure you can repeat for all your controls in all states, but for test purpose I recommend start just with several. MPK mini can have up to  4x2x3x8=192 pads contexts and 8x4=32 rotor contexts.  It can take a while to define them all.

If your Controller does not have any mode switches, so each control can generate one and only one MIDI Event, you just have one Context per control.

What to do in case MIDI Event is already in use? If it is used only in other context of the same Hardware control, there is no problem. Just select "<New context>", find already defined "Logical control" and press "Attach". Define the context as usual. But in case that code is used by other physical control, while you can do the same, you are looking for troubles. While not so bad for buttons, for rotors and sliders you no longer can use instant or catch mode mapping. Not to say the indication in the "Last MIDI event" will be wrong, since the plug-in has no chance to find out which from these controls was really engaged.

Once you have defined Hardware Contexts and Logical Controls for some set of your Controller, I recommend to recheck there is no mistakes. Touch your controls and check that "Last MIDI event" displays your control/context correctly.

There can be some Logical Controls without any MIDI assigned. They can be used to organize control independent monitors (State monitors, Timers) up to some "program" sequence (initial bidirectional communication with some advanced controllers).

If OSC is activated, you can also assign OSC addresses to your controls. Any control can have MIDI and OSC assignment in parallel, while that make sense for buttons only since since value processing should be different (OSC controls have hi precision and feedback, even "encoders" produce reversed values in most cases). OSC address is independent from the control name. As with MIDI, one address can be assigned to one control only.

MIDI controls can be included into Control Groups ('A' - 'D'). Special Action is available to temporarily "Forget MIDI" assignments for some group, effectively switching physical controls between control and MIDI modes. For example, that allows you to use Pads for control purpose but switch them into normal MIDI  mode to record drums. Logical control can be in several groups. If at least one of this groups is disabled, the control is in MIDI mode.

Continued in the next post...
Title: Re: User manual
Post by: azslow3 on May 30, 2014, 08:57:29 PM
Logic Tab
Now, when AZ Controller knows what our Hardware Controller is doing, it is time for the most interesting part of the configuration. We can define what the plug-in should do.

While you can select Logical Control in question directly, is it easier just touch corresponding Hardware Control. Correct Logical Control is selected then.

If you plan to use some controls as MIDI input into SONAR, for example in Matrix or playing drums, do not define any Action for them. As soon as you add some action, even "Undefined", corresponding MIDI code is blocked. SONAR can no longer receive the code (till you cleanup the action list).

It is possible to change the position of Actions, so unlike state definition you no longer asked to think "in advance".

If you do not have any Actions in the list, the only enabled button is "New". It adds new "Undefined" action into the list. Every time you press "New" yet another action is added. You can select any action to "Delete", "Move"  or modify it. Warning: All operations have instant effect, especially dangerous are Monitor actions list for Timer monitors since they are executed without explicit action from your side. I can recommend temporarily switch the speed of such monitors to "Once" during the action list modifications.

Without selected Action "New" put new Action as the first into the list. Otherwise new Action is inserted right after selected Action.

It is possible to select several sequential actions using Shift+Arrows or mouse with Shift or Control (usual Windows list operations). Move, Delete, Copy and Play will work with the whole selected block. Note that still only one Action is Focused, even in case you have more Actions selected. Action options, New and Paste operations referencing this Focused Action.

"Copy" works a bit special. If some Actions are selected, the reference to them is remembered. If no actions are selected, the whole list of Actions is remembered. Note, that only reference is saved. In case you change the action after "Copy", the reference will point to the modified Action and not to the original one.

"Paste" inserts marked by "Copy" Actions right after currently Focused Action or on top of the list. You can paste Action(s) into the same or another Logical Control. But you can not paste inside copied block, so to replicate several Actions inside one list, select the block from top to bottom (so focused action is the last one in selection). Otherwise last selected in the block action will be the first and paste will not work.

When the Action List is in focus, Ctrl+C, Ctrl+V, Ins and Del keyboard keys are working as shortcuts for mentioned operations.

"Play". When one Action is selected, it is executed unconditionally. If there is no selection or several actions are explicitly selected the list is executed with conditions, as it will be when corresponding hardware control is touched. Previous "value" (from whatever control it was) is used and "Note" is always "On". To test response on some particular input, use MIDI with "loop" option (see corresponding explanation later). When using "Play" in the Monitor list, Monitor conditions (in the corresponding Logical List) are always checked.

For each Action you can define Conditions which must be met. Condition has meaning "Current state of Set X is Y", for example "Current state of Transport is Rec". The Action is executed only in case all such conditions are True. So, that is equivalent to "Execute the action if: Transport is Rec AND Context is Console AND Selection is Valid AND etc". If at least one condition is False, the action is not executed (see my intro into programming). Please note that in case an action is changing State explicitly, that will affect condition checks in next actions. If an action change some Sonar State implicitly (for example, you execute "Fast Forward" command), corresponding State Set is not updated immediately and following in the same list actions still see old State.

You can mark an action as "Final" (check box near the action type). If action is executed (so Conditions check was passed) AND Action was "successful" (that is action type dependent) AND the "Final" flag is set, the action list processing is stopped. Following actions are not executed.

The list of possible Actions is long and the subject for extension (also on special requests, post them in the "Wishes" section):

Continued in the next post...
Title: Re: User manual
Post by: azslow3 on May 31, 2014, 11:55:00 AM

Continued in the next post...
Title: Re: User manual
Post by: azslow3 on May 31, 2014, 01:48:53 PM

Overview Tab
This page shows what it going on with the plug-in.

On top you can see:

In the next section you can monitor States of User defined State Sets. You can also manually change the current State (as with changes from Actions, the Current State is not saved into preset).

The next section allows you to enable or disable control groups. See "Hardware" Tab description and "Ctrl groups" Action for more information.

"Last control actions" section lists successfully executed Actions from one Action List. If some Action List has no such Actions, the information is not removed. At the moment, selecting already selected parameter (ACT or Strip) is not counted as successful action. That is why only Value set action is shown when you continuously modify the same parameter.

Feedback tab
For each Monitor Action, corresponding Feedback Action List can be configured there. Only relevant system states and actions (at the moment MIDI only) are allowed. The interface is the same as for the Logical Control Action list. Please note that depending from surface, additional actions are needed for proper indication. For example my MPK midi switch off LED under pad once the pad is depressed. To keep it on (after "Play" command for example), I have to send "On" event on "Button off" in the Logic section (if "Transport" state is "Play"). I also switch it On/Off here to keep the indication correct when it is changed by other methods.

For Parameter Monitors, current "Value" (can be selected in the MIDI Action) is the value from the monitored Parameter.

ACT Tab
This Tab is special. It is not connected with other Tabs and it is not related to your Hardware Controller.

This Tab shows ACT Mapping for current ACT context. You can browse "pages" with the "Range" combo.

In ACT Learn mode, each parameter is a clickable button. When you press is, the plug-in send to SONAR current value of this parameter. That is a convenient way to change your ACT mapping.  Since the value is not changed, there is no risk to unintentionally modify your current settings. And since Hardware Controller is not required, you can just use it stand alone.

Please read ACT (http://www.azslow.com/index.php/topic,13.0.html) topic for more information.

Cooperation mode
It is possible to control several physical surfaces inside one preset. Two controllers  then work in Cooperation mode. For example, in case one of your controllers has buttons and other encoders, you can "cooperate" them so you can switch what encoders control using buttons. AZ Controller support one chain of up to 4 devices. One device should be configured as Master, and other as Slaves. Instances for slave devices simply forward MIDI messages to and back from the master.

To switch instance into Master or Slave mode, select corresponding option in the Options Tab. The configuration of Slave instances (except this mode option and events blocking) is then unused. The whole configuration of all devices should be done in the master instance.

Since separate devices can send the same MIDI messages, it is important to distinguish between such messages. Messages from slave instances inside AZC Property Page are prefixed by "Sx", where "x" is the slave number. Messages from the device connected to the Master instance are not prefixed (shown as in default Stand Alone mode).

Warning: SONAR is a bit buggy in preset operations for several instances of the same plug-in. When loading/saving a preset in one instance, please hide Property Pages of all other instances. The preset of the First (in the Control Surface list) instance will be saved otherwise, independent from the window you have pressed the button. Also note that in all instances SONAR show the same preset name.

So, practical configuration sequence:

Title: Re: User manual
Post by: azslow3 on May 31, 2014, 01:48:54 PM
Incoming MIDI processing

Most MIDI messages are self contained, one message means one event to react on.

But there is one MIDI message type, "Control Change" (or CC, started with Bx byte) which is different. While all CC messages also can be interpreted as self contained with one byte of data (7bit, 0...127), some of them can (and should) be interpreted as a part of compound message. Note that there is no hint in the message itself either it is self contained or just a part of something else. Some CC messages can be a part of several (up to 3!) different compound messages.

Another problem is no strict restrictions how compound message should be delivered. I mean in which order and either all parts should be transfered every time. MIDI specification explicitly mention that it is not required in some cases. But hardware producer are free to do what they want.

Terminology:
To understand how MSB and LSB are working, let say both of them are just a digit from 0 to 9. Putting 2 together, we get  00,01,02...48...97,98,99. The first digit will be more significant then the second. When MSB is received, it means let say 70. LSB means 5. and MSB+LSB = 70+5 = 75.


Any CC can be self contained, but that is the whole list of overlapping CCs. :

As you can see, extremely hard case is CC6. It can be:

Speaking about the second problem, should we expect CC31 after CC0, even in case we already KNOW they are MSB and LSB for CC 14bit 0?
Lets say MSB and LSB (CC7 and CC39) are 2 digit in the value of Volume in form "-2.8dB". So, CC7=2 means "-2.0dB" and CC39=8 means "-0.8dB".
1) Lets have a look what is going to happened when the fader is always sending both values.
1.a in case we react on LSB only, everything is ok. We receive CC7=2 (remember, but not trigger) and then CC39=8, calculate "-2.8dB" and set the volume. Everything as it should be.
1.b in case we react on both messages, there is going to be some jumping. We receive CC7=2 and set "-2.0dB", then we receive CC39=8 and set "-2.8dB". That means, continuous moving of this fader is going to produce: "-2.0dB", "-2.4dB", "-2.0dB", "-2.5dB"..."-2.0dB", "-2.9dB". Do you see the problem? It is "jumping" from "-2.9dB" to "-2.0dB" when it is not required. In case we "keep" LSB instead, we have jumps in reverse direction: "-3.0dB", "-2.0dB", "-2.9dB". Not so many as in the first case, but still.
2) If the fader is NOT sending MSB/LSB till that is required, so it send CC7=2 and then CC39=1, CC39=2,... CC39=9, CC7=3.
2.a in case we react on LSB only, we "skip" some cases when it is not sent.
2.b in case we react on both messages, we have the same problem as in 1.b
So, it looks like there is no "perfect" solution in this case.

With NRPN and RPN the situation is even worse, there are 2 "address" messages before (always the same) CC6 and CC38 with data.

Incoming MIDI processing in AZ Controller

At the moment, AZ Controller has 2 modes processing assigned messages and 3 additional modes which make required assignments possible.

2 general modes:
In general, till your hardware is extremely tricky, you should use "strict" mode.

3 additional modes to make the assignment possible:
Please note, that once assigned, CC7bit is recognized in ALL modes. 14bit messages (CC/RPN/NRPN) with identifier in data (MSB or LSB) are recognized in all strict 14 bit modes. "Normal" 14bit messages (CC/RPN/NRPN) are recognized in all modes except "simple 7bit".

Incoming SysEx processing in AZ Controller
While most messages have explicit "value" part, SysEx messaged have arbitrary structure. For simple commands without value (f.e. MMC), the whole message is a "message type" which can be assigned to control. But if message includes some "value", only the beginning of the message should be assigned to control. Otherwise with each value change, the whole message will be separate message type and it will not be recognized as control message. Since there is no way to detect that automatically, you should set correct size of the "fixed" part in Options using 'SysEx key length' combo box.

In the "Last MIDI Event" you will see "dynamic" part in square brackets ("[ ... ]"). Start operating the control and look at "Last MIDI Event". The goal is that not changing part is just before brackets and changing part is inside brackets. Adjust the parameter in Options till that is the case, than assign that SysEx to Control. Note that the option is affecting unassigned messages only, once assigned, the setting is remembered with this particular control. That means different controls can have different length of the fixed part.

Which mode is required for my device?
That is device specific. You normally can find that information in the documentation.

Examples: