User manual

[azslow3]

Here I am going to explain all aspects of AZ Controller configuration.

If you have not done that yet, I recommend you read About first and than check you are able to use my plug-in following Quick start 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.

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:

• All named objects recognized in system by internal (hidden) IDs, not by the text you are entering. System will not warn you in case you call 5 different rotors as "Rotor", they still are recognized as different. But that can confuse you later.  It is sometimes perfectly ok to use equal names, but only when the meaning is clear. For example, "Shift" can be "On" and "Off". Also "Alt" can be "On" and "Off". I recommend to use descriptive, distinguishable  but short names. That can save your time and nerves.
• All names are kept in lists. The first name entered will be the last in the list. In case you want see something ordered, please plan in advance. There is no possibility to change the order (for now). So, if you want to see "Prog1","Prog2" and "Prog3", create them as "Prog3", "Prog2" and "Prog1". The last entered Software State is special, see the explanation later
• Unlike with the rest on the interface, entering text and selecting items in combos are not immediately changing the configuration. Each section has separate "Save" button which affect only this section
• You can delete object when there is no more references to it. In case the object is in use, "Delete" button is greyed. There is no indication where it is used, but all possible places are predictable. You can modify an object name any time, it will be shown under the new name once you save the change.
• To create new Control/Set/State just select "<New control/set/state>" in the corresponding combo. Enter new name and press "Save".
• When you create a new Set, new State "Default" is automatically created in it because any Set should have at lease one State
• You can edit Set name by selecting "<Edit set>" in the State Combo.

Hardware controls
For each Hardware Control 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:

• Note: ON, OFF - indicate either the last event was "Note OFF" or "CC OFF" (the last one is triggered in case associated hardware control is a Pad and CC value was 0) . In all other cases it is "ON". All action conditions include predefined condition "Note: ON" which can be changed to "OFF", but can not be removed
• MIDI Track: Yes, No - either currently selected parameter comes from MIDI Track. In case the parameter is not valid or from ACT, the State will be "No"
• Last Action: OK, Failed - either previous executed Action was successful. Note that the status correspond to the very last executed Action (so, conditions for that action was ok) and it is overwritten every time. The exception is "Monitor" Actions in the logic list: since there are not really executed, they do not change the status. For example, you can check either "Catch" has already caught the value or not yet. Also you can implement "Is final" on Failure by inserting "Undefined" Action after the operation in question, with "Is final" set and "Last Action:Failed" condition.
• Selection: Valid, Invalid - indicate that the last parameter selection (ACT or Strip) was successful
• Sel. touched: Yes, No - indicate that currently selected parameter is touched using "Touch" action. It works in scope of the "Touch" action target control only, if the parameter is touched by other means (in other controls, using other surfaces, etc) that is not indicated
• Transport: Rec,Play,Stop - current SONAR transport state
• Additional transport related sets: Loop, Fast forward/Rewind, Scrub, Auto punch
• Context: Track,Console,Plugin,NoProject - current SONAR context (or NoProject)
• Container: None, UserBin, ProChannel. A plug-in from which UI container is currently in focus. Note, SoftSynth also have UserBin type
• ACT Map: No Mapping, names of all VSTs/PC modules seen by the plug-in so far
• Value: 0...127 - mapped to states last MIDI value

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.

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.

• Alternative direction for Endless encoders. In short, in case you need set Reverse flag in Set Value for endless encoders to get correct direction, you can set the flag globally here (and unset it in Set Value). Since some Actions which use Endless encoders (Set State) have no such flag, that is the only way to make them work right
• Use TTS (Text To Speech) if possible. At the moment, only SAPI 5 is supported. Use with "Say" function.
• Ignore MIDI input. Useful in case the instance of the plug-in with this flag set is used for sending MIDI commands to external hardware/loop devices. If the same device is used by other instance already, it make sense to set "Block all channels" and "Black all SysEx" even with this flag set
• Different blocking strategy can be specified in the next parameter. By default, the plug-in will block only all assigned events with some action specified. In case your controller has no keys and your are not going to use some "MIDI learn" in SONAR (for the Matrix view for example), it is safe to set "Block all channel messages". That is also good option during the assignment procedure, since in this case messages will not unexpectedly change something in VSTs. Other options are either to block one particular MIDI channel, or all channels except one. The last case is interesting for combined with keys devices, so you can allow keys on one channel go to the track and block everything else (on other channels). But note that once these options are used, assigned messages will not be blocked explicitly (SONAR limitation). For example, you block channel 1, but your slider is on channel 2. Your slider will "leak" into the track/VST settings. 
  
  Tip: in case you use ACT MIDI and Generic CS plug-ins simultaneously for one controller, you can block the controller by adding AZC (as the last!) and setting "Block all..." (may be also with "Block all SysEx"), without anything else in AZC.
  
• Unlike for other messages, SONAR has no fine blocking for SysEx messages. You either ask to block all of them or they all go throw. Note that there are some messages which are neither SysEx nor Channel. From my observation, they are not sent to plug-ins.
• To simplify reconfiguration it is possible:
  
  • Clear all current assignments. Usefully for example in case you completely changed the mapping on your controller.
  • Reset the configuration. Useful in case you have not created "Empty" preset.
  • Prepare genericpluginparams.xml (ACT configuration) for manual editing.
• Cooperation mode. See separate chapter (toward the end of this manual)
• MIDI interpretation mode (see the explanation is at the end if this manual)
• Window (Plug-in Property Page) height
• Enable one from the first 2 registered in OS game controllers as an input. Game controller operations are (fixed) mapped to MIDI events from "Third slave controller", so they will not interfere with normal MIDI input (till you cooperate more that 3 MIDI devices). Supported up to 6 axes, 32 buttons and (discrete) POV.

"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...

[azslow3]

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.

• Put the controller into known to you hardware state (in respect to program,bank,mode,etc)
• Touch some Control, let say Rotor 1. You should see it's MIDI code in the "Last MIDI event" monitor
• Select right name from the "Hardware Control" combo, "Rotor 1", "R1" as you called it before
• Select "<New context>" right from the control name (if that is the first context you are going to define, it is already selected)
• Select "<New control>" in the "Logical control" section
• Touch your Hardware Control again. Does something is changed? If yes, this MIDI code is already in use. This special case is explained later.
• Now you should see "Attach" and "Assign MIDI" buttons enabled. Press them both in any sequence. "Attach" will connect Logical Control to the Context and Assign will connect MIDI Event to the Logical Control. Context and Control are created, and so you no longer see "<New context>" and you see something like "(Ch:...) Rotor 1" in Logical Control combo
• If you know that the code this Hardware Control generates depends on some Hardware State, select it in the Hardware Context section (first select the Set and then the State). Repeat that for all dependencies. If you want to undo, just select "<Any>" in the corresponding set. If some hardware mode does not change the code control generates (for example: for MPK mini, "Pad mode" and "Pad bank" does not change Rotors operation), just keep "<Any>" for such set. The Context name  (and a part of the Logical Control name) contains the list of selected Hardware States. For example: "B5 : 'CC' 'Pad bank 2' 'Prog1'", for my Pad number 5, within Program 1, Bank2 and CC mode
• Proceed with next Context/Control

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...

[azslow3]

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):

• Undefined. That "Action" does nothing, but always successful. If you want block MIDI code from some control without defining something else (to avoid unwanted influence on your work in SONAR, some MIDI codes can do almost or completely invisible changes in VST plugin setting). So, it is not useless.
• Set state. Change current State in some User defined State Set. "Loop" means switch to to the first after the last or to the last before the first. Special is "Map MIDI value". That can make your Rotor function as a software states switch. For example I have found that more easy then switching banks using buttons. It is also possible to change the state from MIDI Value, "Next" or "Previous" will be selected based on controller nature (Step, Endless, Ribbon). In Monitors (not during Monitor "dry run" of Logic Actions nor during normal Logic execution) "<Set to monitored>" will set real state from current temporarily state. "Map paramater value" takes current value of selected parameter and map the same way as MIDI. The same for automations read and write. Note that if it is used after Value action, it will take it into account. "Map Left/Right Level" should be used in Level monitors only. That provides the way to indicate stereo levels separately (use "Map MIDI value" to simply get the max of all channels). "Map strip color" requires special state names in form "BBGGRR", which specify required color in Hex (f.e. "ff0000" is blue). "Last sel.(ectable)" tries to set state number corresponding to the last selectable container for currently selected parameter (Strip/Send/FX/Filter/Rack), falling back to the first state and failing when not possible. "By text" match state name with current text, fail if not found. When "Set engine state" flag is set, both temporarily and the real states are changed in Monitors. When "Set engine state" flag is set in the Control Action, the action will not modify temporary state during Monitor "dry run". That way it is possible to detect "real engaged" controls in monitoring. Flag "in own ctrl. only" let detect either control is executed directly (from MIDI event) or as a function. When the flags is set and control is executed as a function, the state is not changed. The flag has no influence on execution during monitoring. Please be careful with that option, since it is easy to create "busy loop" by changing the state in the State Monitor for itself.
• ACT. Select ACT parameter. You directly specify which one (see ACT topic). Note, that will just select the parameter, not change it. In addition to the direct number, it is possible to specify "Shift" Software State Set. The shift will be the position of current State withing this Set. For example, in case the Set "ParShift" has state "0","1","2","3" (in the order as seen in the Overview Tab) and the current state is "2", there will be additional shift 2. The state name plays no role, so in case you rename "2" to "OneTwoThree", the shift is still 2 as the position of the state (counted from zero!). You can also specify yet another shift with "multiplier" other then 1. State Set shift with multiplier are useful  to configure "banks". Just define "Bank" state set, let say with state "1","2","3". Then you can configure controls as "ACT+R1+'Bank'x8", "ACT+R2+'Bank'x8"...etc till "ACT+R1+'Channel'+'Bank'x8". To switch bank, you then put "Set State 'Bank' <Next>" action for some button. Please note, that "Bank" 2 really define shift 1 (counted from zero, so "1" is 0, "2" is 1) and the result is R1+1*8=R9 for the first encoder
• Strip. Select Strip and Strip Parameter. You have plenty of possibilities to find correct strip, with offset and skipping MIDI tracks when desired. Special case is selection by name. For that, define some State Set (for example "Track") and the state with the name in question (for example "VOX"). The plug-in will search for the strip with such name and will take it as a reference (the subject for shift and skipping MIDI). If the track and parameter are found, "Selection" is set to "Valid" and to "Invalid" otherwise. You can use it in the next Action condition, for example to select different parameter. If correct strip is already selected by previous Strip Action, you can change the parameter only by choosing "<No>" as the Strip type. Strip type can be set directly or using position of current State in some Set. Normally that is going to be "Strip" Software State Set with States: "Track"/"Bus"/"Master" (exactly in that order to have desired effect). "Current" parameter is (read only) indication that the strip has the focus (1.0) or not (0.0). "Rude solo" (read only) when set to 1.0 indicates that at least one track is soloed (bus solo does not affect it). "Rude mute" (read/write) is to mute/unmute all tracks, monitored with value 1.0 in case some track is muted. "Rude rec." indicates global Record Arm status, when used with Autormation Write monitor, indicates global Automation Write status. As with ACT, that action only select parameter.
• Send.  Use "Strip" Action to select the strip first. Leave "Volume" parameter there. The Send is specified by number, as seen in the strip. The number can be calculated as position of the current State in the specified Software State Set. As other "Select" actions, it does not set the value. Use "Value" Action afterwards.
• Value. Set selected parameter value. It assumes ACT, Strip or Synth parameter selection is done before. All parameters in SONAR are mapped to the range 0.0 to 1.0 (so 0.23, 0.333, etc.), independent from final parameter (button, switch with 4 positions, volume, etc). Simple MIDI controls send values from 0 up to 127, or no values at all. The following options to select desired value are provided (for the case controller value is used, the Logical Control should be associated with exactly one Hardware Control):
  
  • Direct. Last registered value from Hardware Control is mapped directly or reversed.
  • Catch. Hardware Control should first pass current value for parameter. It works as Direct then.
  • Instant. Hardware Control starts to change parameter immediately. The change will be proportional to the difference between Hardware Position and real Parameter Position. In case these position matches, it starts to function as Direct.
  • Toggle. Change parameter value from 0 to 1 and from 1 to 0. Input value is not used, useful for buttons (toggle on/off).
  • 0, 1, or other Absolute value. Just set specified value (0.5 is exactly "middle" point, for example pan center). Interleave for Buses accept 0.5 for auto detection.
  • Step. Special mapping for Rotors and Sliders to imitate endless encoders. When the control is Right/Top from the center, it will increase the value when it is turned right and do nothing when it goes left. When the control is Left/Bottom  from the center, it will decrease the value when it is turned left and do nothing when it  goes right.
  • Inc/Dec. Increment or Decrement parameter value by one "Step".
  • Endless. The only option for Endless encoders. Please note that "Acceleration" is a hardware control property, not a software feature. Try different combinations of "Accelerated" and "Reversed" to get correct working result, starting with both unset.
  • Ribbon. Apply relative change in value to parameter. Introduced with ribbon strips in mind, to support sliding (should be used with touch events to ignore the first position after touch since it can be arbitrary)
  • Current. Set the value the parameter already has. Make sense during ACT Learn only.
  Step, Increment and Decrement have the Step Size parameter. MIDI means the step is 1/127, the same as one "tick" in Direct Linear mode. Fine has step size "0.001", close to 10 times more precise then Direct value. You can also specify the tick in percent from the whole range. It is good idea to either have one dedicated rotor with "Step Fine" or 2 buttons with "Inc/Dec Fine" to fine tune all parameters. Since the last parameter changed is remembered by plug-in, you set approximate value by other controls and then use these dedicated controls for precision. "Native" step size tries to use the Step size specified by SONAR. Unfortunately, SONAR either report 0.0025 or nothing at all, so it is useless at the moment.
  Direct, Catch and Instant modes use mapping curves, Convex has more precision at the middle (good for the Volume for example) and Concave is opposite to Convex (I have not found good example for it). I tend to think "Instant Convex" works better then "Instant Linear" for me.
  Tip: Reverse flag can make normal rotor/slider act as a cross-fader.
  The last option is Touch related. The default is "Auto". "Touch" should be used in cooperation with "Touch" Action (see below), and is "Auto" in case the control is not yet touched. Check SONAR documentation for "Timeout" meaning (I have not used it and I do not know what it means).
• WAI. SONAR has information which strips (for each strip type) are currently controlled by particular plug-in instance. You can see that by color bars near corresponding strips (in case there was no Control Surface configured when the project is loaded, you can see these bars after project reload or SONAR restart). You can configure AZ Controller to operate with arbitrary strips, so that is up to you what to show as WAI. If "width only" flag is set, only the number of strips is set and the current first WAI strip is kept unchanged. In case this flag is not set, "Strip" Action should be used prior WAI Action to select the first strip in range. The strip can be aligned so you set WAI to fixed positions only (for example, with align set to 4, WAI Action with strips 1 to 4 still set WAI to the track 1). Only one Strip Type WAI can be changed by one WAI Action, the strip should exist. But you can change or keep the width for each strip type in one Action. To set "default" width, use "Initial" flag. All WAI Actions with this flag set act as "Set width only" during preset loading and executed unconditionally. In case there are several "initial" actions, all of them are applied in the loading sequence (which is somehow arbitrary).
• FX. Select FX parameter. Use "Strip" Action to select the strip first. Leave "Volume" parameter there. The strip in question should have some effects with controllable parameters in FX Bin (not PC). The first option is the name of FX. All used by any track FXes should be listed there. You can also select "<any>". The next parameter is "Shift". If no particular FX is specified, the "Shift" is the FX number in the chain (zero based). In case of specific FX, "Shift" number of such FXes should be skipped. Current state position of some Software State Set can be used instead of absolute number. For example, you have "EQ", "Comp","DDD" and again "EQ". To control the second "EQ" you can specify either "<any> 3" or "EQ 1". The third parameter is the parameter number within FX. In case you have selected particular FX and it is currently used somewhere in the project, its parameter names are displayed after the number. The order of parameters is the same as in the "Add automation..." list. Parameter "Shift" can be configured the same way as for ACT Action. As other "Select" actions, it does not set the value. Use "Value" Action afterwards.
• Command. Execute SONAR Command. SONAR expose a list of commands (more then 400!) plug-in can ask to execute. I put Menu commands under different combo, just for convenience. All commands have no parameters. Please search in SONAR documentation what each command does, or you can just try them to see the effect (I must say some of these commands does not produce expected result, but that is out of my control). At the end of the list, there are all capital commands with "*" at the beginning. These are not reported by SONAR commands, hardcoded into API. Most of these commands are obsolete and not functional, but some of them are still working "undocumented" features. It would be nice to do cleanup here and give meaningful names to still working commands

Continued in the next post...

[azslow3]

• Functions. A collection of actions which does not required additional parameters. They are separated from Commands for clarity, Commands are provided by SONAR while Functions are programmed inside the plug-in.
  
  • ACT Lock. Fix the context. See SONAR documentation for details (ACT support only one context in time, so you can not have 2 different ACT for two different surfaces).
  • ACT Learn. Turn on/off ACT Learn mode. See separate ACT topic in the documentation section and Control Surfaces/ACT board.
  • Select strip. The strip should be already specified by the Strip Action. This function makes chosen strip current (selected). That does not change focus between strip types. Tracks and Buses both have the "current" strip, but only one from them is highlighted in SONAR. You still can move the other one, but that will be "invisible" till you change the focus using mouse (or using "Move input focus..." Command Action from plug-in).
  • Automations. Read/Arm automations and Snapshot function. The parameter should be preselected with Strip(FX,Send), ACT or Rack Actions. To turn the automation on all parameters for the strip, set "Select" to "All"  in the previous Strip Action. Synth parameters are not affected by "all parameters" functions.
  • User Interface. Show/hide AZC User interface (the Property Page).
  • Context. Switch ACT context. "Focus" changes current context, "Open" changes the context and open the plug-in window, "Close" changes the context and close the plug-in window (toggling the window is not supported by API). "Next" and "Previous" cycle forward/backward along all FXes of all strip. To use "pure" functions, select plug-in with Strip/FX/Rack or ACT Actions. "ACT R1" will select the current context ("R1" is safer than "B1" since the parameter should exists in the SONAR ACT mapping). "Focus" does not work for Synth Rack ("Open" works). If some track is selected, the operation is done on related Synth. Examples:
    
    • Close current plug-in and open the next one: "ACT R1", "Close", "Open next"
    • Open Channel tools for the first Track in WAI (not closing the current FX): "Strip Track <First in WAI> +0 Volume", "FX 'Channel Tools'", "Function Context Open"
    Floating and in focus function succeed if the window is for selected plug-in. Foreground window is the one with focus, its title is saved to text.
    
  • Transport. Direct control for transport related function. Also move current time to In/Out time of Loop and Punch as well as setting these times from the current time. The result can be different from SONAR commands with the same name. Two major differences I have found: Scrub command does not allow scrubbing with jogger, while Scrub function does; Rewind and Fast forward as commands are not working correctly when the operation was stopped by the time line (the beginning of the project for Rewind). GoTo Data Cursor works in Clip Select/Edit mode only (there is no Data Cursor otherwise).
  • Display. Show/hide internal Display window.
  • Focus container. Move focus to one of the strip "containers". Interoperability with the "Focus" function is yet to be understood. In the CW code, VS700 plug-in only make use of that method to switch between "User bin" and "ProChannel"
  • All strips operations. (Dis)arm all tracks, (Un)mute all tracks/buses, (Un)solo all tracks/buses.
  • Update status of plug-in (which is shown in Control Surface Module on SONAR Control Bar) from current Text
  • ACT last change Scan. Detect which ACT parameter was changed since the last call. For normal operations should be put into timer
  • ACT last change Select. Select detected by Scan parameter for future processing (Value for example)
  • Focus strip type. Move focus to specified strip type view.
  • Some endless encoders have a kind of "jitter". They periodically send opposite value even in case you continuously turn the encoder in one direction. This Function, inserted with "Final" flags set before Value Action (it normally "Fail", till it think the value from encoder should be ignored), check either current value is opposite from the last one, so the first such change is ignored
  • Select. "Select clip in centered track" (in track view) nearest to the time line. "Select clip" if project has no folders (does not work otherwise, Sonar limitation) selects the clip on currently focused track
  • Say. Use TTS engine (should be enabled in the Options Tab and supported by Windows) to speak current text (see Text Action)
  • Find FX. Starting from currently selected Strip (with Strip Action), this function search for the first existing FX till the end of strip type. If found, it is selected (for future Focus/Open/etc functions), otherwise current selection will be invalid (means FX not found)
  • Select Synth. Using currently selected Track (with Strip Action), this function selects related Synth (parameter 1) for future Focus/Open/etc functions, otherwise current selection will be invalid (means synth not found, for example for synth unrelated tracks)
  • Select Plug-in. For all functions, corresponding strip should be selected before. For "Delete", FX should be selected. For "Insert" in case FX is selected the plug-in is inserted before it, otherwise plug-in is appended to the FX list. Navigation is organized in the same hierarchical menu as you can see during normal plug-in insertion. All these functions "fail" when they can not do the operation.
  • Group. (Un)Solo all record armed tracks
  • Mon. par. not changed. To be used inside monitors (only). For Value/Automation monitors, succeed in case the monitor was triggered by value change only (monitored parameter is the same as during the last call).
  • Send append and delete. Before calling this function the strip in question should be selected for append and the send in question should be selected for delete
  • Plug-in parameter. Move to the next or previous from selected ACT, FX, Synth or ProChannel parameter
  • Roland VM-C7X00 checksum. This function adds correct checksum to already formed DT1 SysEx (see the device documentation for the explanation)
  • Is Snap on. Fails in case snap is not on or function is not supported by Sonar
  • Set IO from Text. Input/Output/Send output should be selected and Text is set
• Keyboard. Trigger Shortcuts. The first 3 "keys" are special, they can be used in menus (as specified by API). All other keys can be "pressed" with "Shift", "Alt" and/or "Ctrl" engaged. These modified keys can be also pressed alone (sometimes useful with "Alt"). Key send can be repeated several times (useful for predefined selection in presets). Also current Text (set by Text Action) can be translated into key sequence.Warning: when using modifier keys Down and Up separately, the failure in configuration can result in "hanging" modifier keys
• Rack. Select Synth and the Synth parameter in the Synth Rack. The same rules as for FX selection applies. Selected Synth parameter can be used as any other selected parameter, the subject for subsequent Value, Automation and Context change actions. Parameter "Shift" can be configured the same way as for ACT Action.
• Filter. An attempt to direct control Filters (ProChannel modules in X). Theoretical procedure is the same as for FX and Synth. But focus/UI are working only with (to be understood) cooperation with "Focus container" Function and parameter control is extremely buggy. EQ and Compressor parameters almost work. To control other modules, the strip must be highlighted. That is current SONAR (up to X3e) limitation. Only delivered with SONAR Modules are recognized, I do not own other (tested on X2 and X3, X1 is untested). Till SONAR is fixed in that respect, that Action should be used with care.
• MIDI. Send short midi events back to the controller.  "Initial" flag can send the specified command on preset load (unconditionally). This action can be used to switch LEDs, highlight rings near endless encoders and potentially move motorized sliders (I do not have any). All possible midi messages are supported. To simplify configuration, there is"<Use Ctrl MIDI>". The message assigned to the related control (works for Monitors as well) will be used in this case. "Value" as the value to send will take last value received for normal action or current monitored parameter for Monitor action. Value "0" is sent as "Note OFF" when the message type is "Note". In case it is not desired (so it should send "Note ON Velocity 0"), select "Send 0 as ON". In case this instance is the Master in Cooperation mode, it is possible to send the message to "Slave" instances. See Cooperation mode chapter. When the "Loop" flags is set, the message is looped back to the input of the plug-in instead of devices. That can be used for assigning messages you can not generate other way (when construction presets for a device you do not have at the moment), testing control actions and organize time delayed reactions (like double clicks, see tutorial)
• Monitor. That is not an Action by itself. It establish the Monitoring Point. Either periodically (for all Monitor types except State Monitor) or on the State Change (for State Monitor), the whole list of Action up to the Monitor Action in question is executed in "Dry run" mode. That creates environment which is identical to what is going to happened in case the Control is activated by assigned MIDI message (except for control value dependent lists and State changes with "Set engine state" flag set). Note, that all changes during such execution (state switches, values, etc.) will not be applied really. But they are visible in the Monitor Feedback actions. "Note" condition for the Monitoring Action is set in that environment prior the execution, so it is possible to monitor "Note OFF" as well. Once the actions are executed and only in case the Monitor Action was "executed" as well (if it's Conditions are valid), the decision is taken either the Feedback Actions for this Monitor should be executed, depending on the Monitor type:
  
  • Timer Monitors are executed unconditionally.
  • For Parameter Name Monitor, the system check either the Parameter selected at the Monitor Action point is changed. The parameter selection works the same way as for the Value Action
  • Parameter Value Monitor is executed in case the value of selected Parameter is changed
  • State Monitor is activated only in case specified state was changed
  • Command feedback is activated in case the last executed "static" Action (command, function, etc.) is different.
  • Level Monitor watching strip level value. It is then available for "Set State <Map MIDI value>" Monitor action or other actions which use current value. Note that some Strip parameter should be activation before monitor
  • Parameter Automation Read Monitor is executed in case Automation Read is changed for the parameter. The value is set to 0/127 (0./1.) when it is disabled/enabled
  • Parameter Automation Write Monitor is executed in case Automation Write is changed for the parameter. The value is set to 0/127 (0./1.) when it is disabled/enabled
  • Control Value monitor monitor changes in hardware control value. Effectively the same as performing actions in the Logic list for corresponding Logical control, but react on changes in any context, which can simplify the configuration
  • Software State based monitor. Specified Set should have states: Value, Auto.Read, Auto.Write, Command and Level. The result is the same as setting corresponding type explicitly, but allows to change it on the fly. That allows to keep only one monitor per control to feedback current value instead of separate monitors (with error prone synchronization between them)
  
  Monitor checks can be "reset" by special action (see later). So monitor (or all of them) can be forces to be re-executed.
  
  In case "double trigger" flag is set, Monitor is executed second time even in case there was no changes. That is useful only in case your controller periodically "skip" MIDI command on input.
  
  Each Monitor has a Priority. During one monitoring Cycle, it is guarantied that Monitors with lower number in priority will be evaluated first. The order inside one priority is random. In case Monitor reset/trigger some other Monitor, it can be triggered within the same cycle. With priority specified, you can be sure that is going to happened. For example let say State Monitor priority 0 trigger 2 other Monitors with Priority 1 and 2. Than these Monitors will be triggered exactly in that order, within one monitoring cycle. They are rare cases when it is required, normally you can leave the default priority (0 for State Monitors and 1 for all other).
  
  Monitor has a "minimal re-trigger rate" in cycles (~1/13 of a second). It can be that your hardware is not able to accept display (or value) update rate on maximum speed (13 times per second). But you still want to see the first change fast (perceptible update speed is way better then). In that case you can set how fast your device is able to accept data (6 cycles for 2 times per second) while keeping your monitor speed "ultra". The first change will be spotted and displayed as fast as possible, but next change will be transfered only 1/2 of a second after the first one.
  
  "DM Sync" monitor speed is special. It checks parameters once per ~4 seconds, but switch to "Ultra" for parameters which are currently changing. Useful for DM devices synchronization (when the number of monitored parameters is hight)
  
• SysEx/MIDI. Send SysEx message or arbitrary MIDI message(s) back to the controller (or Slave controller in Cooperation mode). It can be specified "as is" or in peaces. In the last case, the message construction should be started with "Begin" and ended with "End". Parts can be bulk, from Software Set, from Text (as ASCII) or from currently selected/monitored parameter value. Current state position can be appended as one byte. Also the label of the current state can be appended. I this case, it should follow the same rules as the message: 2 hex digits per byte, bytes can be space separated. In both cases, some number can be added to the position or the last byte in label respectively. Only one SysEx message can be constructed in "one go" but in MIDI mode several messages can be specified (auto detected). SysEx (but not MIDI) can be looped back to the plug-in (see loop flag in MIDI action)
• Jog. Move time line. Mapping is the same as in "Value" Action. MBT and SMPTE units are supported, with multiplier.
• Touch. It is possible to inform SONAR that some parameter is "touched". That is very useful for recording automations with touch sensitive motorized faders. If there is no "touch" (the default is "Auto"), SONAR will only record changes. In case some automation already exists, it will change the parameter (and move the fader!) once you are no longer changing the value. So, touch is the way to say "I am controlling the parameter now, forget what was written before till I am done". Normally, the action is assigned to separate touch MIDI message from the same physical controller ("Touch" on Note ON and "Release" on Note OFF), but in case you control is not touch sensitive, you can assigned that action to some other button. You do not specify the parameter to touch directly, instead you specify which Logical Control you touch. The plug-in will deduct which parameter that control is going to change the same way as for Monitoring, but looking for the first working "Value" Action.
  For the case you forgot to release something (some logical bug in you configuration), there is "Release all" option (release everything touched before). Please note that more then one control can be simultaneously touched and each Touch requires corresponding Release. Also do not forget to set "Manual touch" in the corresponding "Value" Action. Touch will have no effect otherwise.
  
• Text. Text Action prepare the text for future operations (display).
  
  • Fixed text is just a constant
  • Parameter name form the string from current selected (or monitored) parameter. "Origin" is the topmost origin of the parameter (strip, synth, ACT context), "Container" is the second order origin (FX inside strip).
  • Parameter value is current controller value in the Logical Control Action list and retrieved from SONAR current value for the monitored parameter in the Monitor Action List
  • Current time in SONAR (as MBT or SMPTE)
  • Current state of some Software State Set
  • Fixed text specified by HEX numbers. Some hardware displays support special characters which are hard to enter otherwise
  • Current state of some Software State Set, the State name is interpreted as HEX numbers.
  • The text from Sonar Accessibility Window, if corresponding option is enabled in the registry.
  Formed string is subject for fitting into specified number of characters. By filling with spaces, by trimming or by "smart" abbreviating. In case filling is required, you can specify alignment.
  After formating, the result can replace current Text or it is appended/prepended to the current text.
  
• Product specific send send MIDI/SysEx messages to the controller which are specific for the hardware. At the moment, only Mack.. LC (complete), MCU and C4 (partial) sends are supported. For complete description of these sends, get the official Logic Control User Manual (can be found in the Internet). I am going to write dedicated tutorial as well. Here is short description only:
  
  • Hello. Should be send as the first message to set the device id. This id is remembered and is used in all successive operations. Normally trigger "EHLO" response from the device, on which plug-in should answer with "Connect". Then the device reply either with "Confirm" or "Error" message. In the first case, device has accepted the invitation and is in "Online" mode. Some devices require periodic "Ping" from plug-in to stay online.
  • LCD transfer current text (see Text Action) to display
  • Time/Assign display also transfer text, but to 7segment displays. The information can be transfered either incremental (changes only) or complete (make sense to do this after device reconnection). Either SysEx on MIDI way is supported (not every device support both modes).
  • VPot transfer current/monitored parameter value to the specified endless encoder ring
  • Meter will set meter on the device from strip origin of current/monitored parameter. Other sends are used to configure its behavior
  • Time display on HUI (compatible) devices. Only digits are supported there, with optional dots. Text MBT and Text LC SPMTE time formats can be used.
• Monitor reset can reset remembered value for monitor(s). That effectively trigger Parameter monitor next time it is checked and State monitor immediately. When used with particular monitor, it is possible to specify when it should be checked next time. It is possible to say that in case the Monitor in question is already planned to be executed, the execution time should not be changed. "As usual" for Once monitors disarm them (but remembered condition is still cleaned)
• Display draw current text (see Text Action) into specified cell (with optional dynamic shifts using Software Set current State) of the internal display. That information is saved even when display is hidden. Tip: there is no "Initial" flag for that action, since it needs cooperation with the Text action. One possible way to draw initial text into the display, is to define Software Set "Initialized" and create Monitor for it.  The first action should exist the monitor with "Initialized:Yes" condition, then output required text and set "Initialied:Yes" with "Set engine state"

Continued in the next post...

[azslow3]

• Marker. Move "current" time (cursor) to specified Marker (GoTo) or save the name of this Marker as the Text. You can select the reference marker (from which the shift is counted) and the shift. In addition to direct absolute shift, you can specify Software State Set based shift (as for parameters in ACT Action). Set based shift is not applied and Marker is searched BY NAME if concrete State or search by text is selected. In case of "From the end" or "From cursor, backward" Set based shift and search are done in reverse direction (absolute shift is applied directly). For example, "From the end" -1 "XXX" "MyMark" (where "MyMark" is the name of some State from "XXX" Set) will search for Marker "MyMark" starting second from the last marker inside the project (not the last! for that use "+0"!). "From cursor, forward" "-1" is the same as "Previous Marker" Command, with the same rules applied (in case current cursor is between markers, it will be moved to the current marker).
• Range. This action has 2 purpose. In case your hardware controller for some reason produce strange maximum value, you can set "HW Min/Max" parameters. In case you want control only subrange of some parameter, you can set it (and leave HW empty). All values are specified in range from 0 to 16383 which correspond to the minimum and maximum parameter values in sonar (0 to 1.). Such "strange" number is the maximum representable within 14 bits, most precise resolution supported by MIDI (in Pitch Bend messages, for example). Example: let say you want limit the range 0..1 to 0,25...0,75. You should then set Low to 0,25*16383=4096 and Hi to 0,75*16383=12227. In case this action is inserted BEFORE Parameter Monitor Action, during MIDI sending in monitor the reverse calculation is done. Let say you have slider which controls specified range (0.25 .. 0.75) and it is motorized. You obviously expect that the position sent back by the plug-in will be the same as you use to set the parameter.
• Call. Execute actions from another control. Think about Subroutine in programming or Channel Strip preset in DAW. Can be used to define some action list in one control and use it from several other controls instead of replication the same actions. Note that the action is "successful" only in case some action with Final flag inside called control was successful, so it is possible to set Final for the call action itself with logical result. Calls can be used from Monitors as well. But the action list is still defined as a "control". Note that in such case only actions available in Monitors are going to work, "Logic only" actions (list parameter selection) will not be executed
• Text buffer. There are several global Text buffers which can be used to save/combine/retrieve current Text. For example there are separate Monitors for each channel but you want compose the whole text for Hardware Display. Then each Monitor can save it's text into specific part of one Text Buffer and then the whole buffer is transfered to the hardware. Note that "Set" operation set the current Text from the buffer, while "Replace", "Insert" and "Append" operations update the Text Buffer using current Text.
• Sync FX. It will try to synchronize all parameters from one (in case some FX parameter is the peer, set by FX Action) or all FXes of some strip (previously specified by Strip Action) to/from FXes of the strip, specified in this Action. The selection is close th the same as in Strip Action. "Next"/"Previous" means next or previous to the peer strip. "Limit" options specify the maximum number of parameters which are different. If FXes do not match in more parameters, there will be no synchronization attempt. For real practical use, put this action into Time Monitor and use Strip Name based selections to avoid problems (if you use absolute track numbers, once you insert another track, that action will start synchronize something you was not expecting).
• Save/Recall current parameter. Currently selected parameter (the result of Strip/ACT/FX/... Actions) can be Saved into one of several slots. You can Recall it later. It is also possible to "recall" current focused strip. The differences between such recall and Strip <current>: recall set Track/Bus dependent on focus and recall can be used in Monitors. During recall, it is possible to set some Set into the Strip Type of the parameter (see Strip Action for such Set rules). If there is no sufficient states in this set or not strip parameter is selected (ACT, Synth), current State in this Set is unchanged. For the meaning of "Set engine state" see Set State Action description.
• Shuttle. Turn Fast Forward/ Fast Backwards based on the current State in specified Software State Set. The set should be in the form "<<2", "<<1", "Stop", ">>1", ">>2". If the number of Stated is Even, there will be no "Stop" triggered by this Action. You can defined more sates to increase the number of possible "speeds" and change the Step size to adopt the "weight" of each state. Use example with Knob: in the Knob Actions list add "Set State" "From MIDI" <the State set>, "Shuttle" "4" <the State set>. The Knob is a "Shuttle wheel" now. Note: implemented as FF/RWD Sonar functions, it does not work with Scrub.
• JitterFix. In case some control (for example Motorized Fader) periodically send some values on its own,  your parameters can be unexpectedly changed by your surface without you, which is not nice at all. JitterFix (it has "Success" when the message should be blocked, so use with "Final" flag and before any "Value" or other parameter changing Action) setup the range within which all changes are ignored. Note that in case you send parameter value back to the control, you should use "<Use Ctrl MIDI>" so the system knows about it. You can change the range at any place, up to 16383 to ignore all values. In case you do not want the input till feedback send some value, set "Block till set by MIDI" flag, this JitterFix Action will be "successful" till the value is initialized by MIDI Send value.
• Select. Sonar has special functionality to select data in the track view. Without surface, it can be controlled by Numeric keyboard part. Selection is done by (independent from timeline and currently focused/selected tracks) cursor, which is always vertically centered in the track view upon mode activation. Data can be selected by time or by clip. The selection can be extended. Encoders/knobs can be used (in step, endless and ribbon mode). All relevant parameters can be in parametric mode (using State Sets with 2 States)
• Clip. Selected clip (see previous action) can be modified. Supported are: nudge, crop (beginning/end) and fade (beginning/end)
• Scroll/Zoom. To be used with Select/Clip Actions. Scroll/Zoom Track view. Not all combinations of parameters produce reasonable result, but that is how Sonar react on them.
• OSC. Send OSC messages to all known OSC clients. "Ctrl addr to Text" copy current control OSC address with possible suffix into Text for future manipulation, with that option no message is sent. The first part of the address can be taken from the Control OSC address, Text, the first Text Buffer or it can be empty. Fixed suffix can be added to that address. The message can be sent without parameters, with current parameter value (should be preselected with ACT/Strip/etc. Actions), with Text as parameter, with Text parsed into zero or more  integer or float parameters or as fixed float value. Send operation fail in case OSC is not enabled, there is no clients of parameter is not valid (in case parameter value is used as the argument).
• Ctrl groups. You can put any logical control into Control Group (see "Hardware" Tab) and then use this Action to exclude the whole group from controlling operations. When excluded, the same hardware controls can be used as MIDI controls till the group is enabled again. That way you can use your Pads, Mod wheel, etc. to record MIDI and control parameters in Synth, while normally using the same controls for other operations. It is also possible to retrieve current status of any group or current control, for that you need a Software Set with at least 2 States. The first state will indicates the group/control is enabled, the second indicates the group/control is disabled. That information is essential to organize correct monitoring for controls (you do not want LED under your pads still indicate Mute status when you play drums). "Set engine state" has the same meaning as for "Set state" Action
• Value from SysEx. Extract value from current SysEx message and set it as current value (for this message). The action is failing in case that is not possible (message too short, current message is not SysEx, etc). The position is specified starting from the first dynamic byte of the message and is zero based. Additional shift for the position can be specified by the position of current State in the specified Software Set. The value of Hardware control in which this Action is defined (even when used as a function) is updated. Also till the end of current list, effective Logical Control is set to current, even it was different before. That allows all actions work as this Logical Control was called as a reaction on some event with this value, even in case it is really called as a function from different control (implemented for SysEx with values for different controls in one message)
• Compare. It is possible logically compare current State from some Set with either some fixed State from the same Set or with current State from different Set. If the comparison is logically True, the action is successful. Otherwise the action fail. That can be used either with "Final" flag on this action or checking "Last action" Set right after. Also the result can be saved into another Set, False set the first, True set the second State (there is no Engine flag, in feedback lists use 'Set state to Engine' separately when required). The comparison is done by State position, not by text/value. So, if you have Set "Apple":"Red","Green", Set "Orange":"Big", "Small", Set "Numbers": "0","1","2" and Set "Count": "1", "2". Then all following comparisons are true: "Apple":"Green" == "Orange":"Small", "Orange":"Big" == "Numbers":"0" and "Numbers":"1" == "Count":"2".
• Strip marking. Selected by Strip action strip can be marked. Several strips can be marked at the same time. This marking can be checked later, f.e. to organize specific reaction for some subset of strips. The mark is bound to Sonar strip, it is kept even in case you reorganize or rename strips. But marks are not persistent and will be discarded on the project reload
• Time save/Go To. Save current cursor position into one from 32 slots to return (Go To) later.
• Exclusive Arm. Should be put into some timer Monitor. Disarm tracks except one (last armed).
• Text comparison. Compares current text with State or fixed text.

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

On top you can see:

• current SONAR Context,
• current ACT Map name with the number of detected controls of each kind: (R)otors, (S)liders and Switches(B)
• last changed ACT parameter (from SONAR direction, so not only what is changed with Controller). The control id, internal value (is is always between 0 and 1), the name of changed parameter and the latest value are shown

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 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:

• add required number of instances in the SONAR configuration and attach corresponding devices as Inputs/Outputs
• for each slave, reset configuration and select "Slave X" in the option Tab. You can save the preset as "Slave X" (manually typing in the preset name field), but that is not required (SONAR always save current configuration with presets and that "preset" is simple to restore).
• for the master, manually change the preset name as "Master <whatever>" (you will see "Slave X" in case you saved something for slaves!), just to not forget to do this later.
• from that moment on, use Master property page only. Save Master preset periodically (just in case SONAR will corrupt automatic file, which unfortunately happens in case of crashes). In case you open Slave Property page, you will still see "Master" in the preset name. That is "normal", but do not try to press "save" there.

[azslow3]

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:

• MSB - Most Significant Byte. MIDI messages can use up to 2 bytes values, in reality they can use only 7 bit (our of 8 ) from each byte. That means 2 distinct numbers. Each can be 0..127. Resulting number is <number 1>*128+<number 2>. Where <number 1> is going to be "Most Significant", and so MSB
• LST - Least Significant Byte. It is <number 2> in the previous formula.

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. :

• CC0 - CC31: can be MSB of 14bit CC compound message, but see later for future use cases
• CC32 - CC63: can be LSB of 14bit CC compound message, but see later for future use cases
• CC96 - CC97: can be increment/decrement for parameters
• CC98 - CC99: can specify the identifier of Non-Registered Parameter Numbers (NRPN) (see later)
• CC100 - CC101: can specify the identifier of Registered Parameter Numbers (RPN) (see later)
• CC6 and CC38: can set the data for (N)RPNs

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

• Just normal 7bit CC
• MSB from 14bit CC 6
• data MSB from (any) RPN
• data MSB from (any) NRPN

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 "flexible" mode, each MIDI message trigger corresponding event. Like 1.b/2.b in the previous example. And as explained, that is never optimal but somehow works always.
• In "strict" mode, the plug-in will trigger an event only in case corresponding messages was sent in fixed order and only on the last message in a sequence. For CC 14 bit, the sequence is "MSB then LSB". Fro (N)RPN it is "MSB address, LSB address, MSB data, LSB data".

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

3 additional modes to make the assignment possible:

• Simple 7 bit. All CC messages are interpreted as self contained. Let say you want assign CC6 as 7bit and CC7+CC39 as 14bit. Without this mode, CC6 will be interpreted as a part of CC6+CC38 14bit CC.
• Strict, with additional "address" part in data MSB. There is a hardware which use CC 14 bit (so CC6+CC38 for example) to send 7bit data, but MSB of the data is used as an additional identifier. So CC6=2+CC38=9 means that "Volume 2 is -0.9dB" and CC6=3+CC38=7 means that "Volume 3 is -0.7dB" (and not "Volume 6 is -2.9dB" and "Volume 6 is -3.7dB" respectively).
• The same as previous, but with an identifier in the data LSB

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:

• Most simple devices as well as some more advanced (MCU) are communicating by 7bit CC only. In case your device can be configured such way, I strongly recommend to do so
• Faderport's fader is sending CC 14bit
• HUI is using CC14 and CC7 bit (even from CC14 range). Also it make use of "ID in data MSB".
• StudioMix communicate by NRPNs only, fortunately in strict mode
• QU in mixer control mode (not in DAW control mode where it interact with 7bit CC only!) communicate with NRPNS with "ID in data LSB"