Unlike with music, in programming every single character should be right!
No one likes when Sonar or other program crash, even musicians. But less people realize that can be a consequence of one single character mistake. May be just a typo, may be it comes from a hurry development or not understanding what is going on (there is such example with TouchOSC, in this preset there is a workaround with an explanation).
So, independent from how you learn things, if you want good working result, everything should be "perfect". From your replies, I do not expect you will follow that rule. But I want you understand which result produce every tiny "bit" in my example preset, and so what will happened if it is not there or set incorrectly. As an illustration to my "philosophical" statements, to show what that means in practice
I attach TouchOSC layoout (vertical... I only have a phone at the moment) and AZ Controller preset in SPP format. If you attach presets, please do this in SPP using Cakewalk Plugin Manager and not "Export..." in the Options Tab.
TouchOSC sideAll essential parameter for establishing communication I have explained in the OSC Phone installation instructions/video. So I just want to mention that "ping" (explained later) and "touch" (also explained later) should be turned on.
In the layout, names are arbitrary. They are not a part of communication. But OSC message names, while also arbitrary, is. As I have mentioned, it is good to keep them organized. To simplify presets writing, it is better to keep all names related to the same Control with example the same "prefix". F.e., /volume -> /volume/label, /volume/origin, etc.; /enc12 -> /enc12/label, /enc12/value, etc.
For buttons, set "Local feedback off". Otherwise buttons will light when you press them and that can be not correct on Sonar side. F.e. "Mute" button for not existing track will light when you press it, but not existing track can not be muted. When you release, the light will go off, even when on Sonar side it should be On (f.e. you have muted existing track). So AZ Controller preset should take care about correct lighting, not TouchOSC.
"Text" and "Buttons" are independent controls in TouchOSC, even when the text is just to label the button. Using proposed naming convention, from AZ Controller perspective they both can be like a one control. F.e. /stop and /stop/label, when /stop is the button and /stop/label is the text. Sometimes more then one text field is desired for one control, in this example /volume, /volume/value, /volume/origin and /volume/parameter are all related to the fader (/volume).
Colors can be controlled, but most of them stay as originally configured.
When "touch" is enabled, all active controls produce /<name>/z messages when you touch them. Obviously it is a bad idea to name some control with "/z" at the end. The same is true for "/<name>/color".
AZ Controller sideOptions Tab"OSC Configure" dialog should have correct values and enable the communication. Explained in OSC Phone installation instructions/video (I have already mentioned that, I know...)
For this example preset, I have defined one "SyncDone" Software State Set, with two states "No" (default) and "Yes". The reason is explain in "/ping" and "/sync" controls.
Each control should be first created in the "Options" tab as a "Hardware control". In these example preset, there are 4 controls defined. All of them correspond to messages sent by TouchOSC (that is not always the case, controls can be used as a "function" or just for monitoring). Important here are control types:
* /sync is a Button on TouchOSC side, it sends "/sync 1." when pressed and "/sync 0." when released (in OSC world, like in VST and mostly in Sonar, all values are between 0. and 1., f.e. pan center is 0.5, left 0, right 1. In the MIDI world, most values are between 0 and 127, without floating point. So in the MIDI world, pan center is 64, left 0, right 127. AZ Controller is "both worlds" oriented, sometimes MIDI approach is used sometimes OSC/VST one. It is important to realize that when in AZ Controller something like "Value:127" is used, that means "value == 1." in OSC). The hardware type is set to "Pad", because we are not interested in "release" message.
* /ping is a special message. When enabled, TouchOSC periodically (also when just started) sends "/ping". That is used in this preset to detect TouchOSC is started and so it is time to send current Sonar situation to it (labels, values, etc.). Since it is periodically sent, it can be annoying. You modify your preset and than it comes... AZ Controller switch to "/ping" control immediately. To avoid that, it is declared as "System" control. The only difference to "unknown" is not showing the message in the "Last MIDI event" and so not switching to "/ping" control. If you want to see when it comes, you can temporarily switch the type to "unknown" (and then back, the result is immediate as everything in AZ Controller)
* "/volume" is the fader, hardware type "Slider". Unlike "Pad" and "System", there is no special processing. So that is like "unknown" just labeled differently, for clarity.
* "/volume/z" is tricky. TouchOSC send "/volume/z 1." when the fader is touched and "/volume/z 0." when it is released. So from logical perspectives that is "a button". But I find it also annoying - every time you have moved the fader, you see "/volume/z 0." as the last action. So I define touch messages as "system". But there is a consequence... "system" controls have no special "pad" processing, both press and release will be processed by default. See the control definition how to deal with that.
Hardware TabHere all 4 controls was attached and assigned ("attach" is for many logical controls associated with one phisical control, f.e. when hardware surface has several "presets" and can send different messages from the same control, that is rarely used at all and make no sense for OSC).
There is one trick to note when assigning from TouchOSC. Since with enabled touch every control sends "/<name>/z" after finger release, when you want to lean the control itself "/<name>" you should press "Assign OSC" button while physically still touching the control on surface. Just check that "OSC Address" has no "/z" at the end when you do not want it.
Touch make sense for faders and encoders, but TouchOSC also send it for buttons... annoying. After you have OSC Assigned all controls, you can set "Do not show unknown messages" in the "OSC Configure" Options dialog.
Logic TabHere is defined what each control does "directly", when particular assigned to control message is received (part is used in "Monitoring", but I simplify this particular description for clarity)
"/sync". I have defined "/sync" button in the layout, it sends "/sync 1" (pressed) and "/sync 0" (released). It also send "/sync/z" on touch, but we have not assigned it and the message is ignored.
"/sync 0" (release) will not be processed, all action have default "Note:ON" condition, so they all are skipped because "/sync 0" for "Pad" control type set "Note:OFF".
So the action list is effectively called on Press only. The purpose is to (re)"sync" the Layout with Sonar.
In a "good" preset, all "feedback" should be in so called Monitors. It is possible to send OSC in direct reaction, but that is in general "bad style" because syncing is much harder to implement then.
But this preset is "good", so I just have to re-trigger ALL monitors (the first Action in the list).
I also set "SyncDone" to "Yes" (explained in /ping) and set color of the button to "green". The later is not strictly required, but I set initial color to "red" in the layout. So as soon as AZ Controller can sync with TouchOSC, the button become green. That is a simple visual indication everything is "right" (in an empty project, it can happened no parameters exist and the whole layout is not changed much after syncing).
"/ping". I have already written that TouchOSC sends this message once started and then periodically. In the first case, I want AZ Controller is automatically sync. So manual syncing is not required when you start TouchOSC after Sonar. But I do not want "sync" periodically, so I have to somehow remember I have already synced. "SyncDone" is used for that, once synced it is set to "Yes". So in "/ping" I check if sync was already done and "exit" execution in this case ("*" after Undefined means that). For syncing I just call "/sync", since it does what I want (I could "copy/paste" Actions there).
In both cases, a "good style" is to response on "/ping" ("Hello!") with "/pong" ("Hello!"). Touch OSC will know it is welcome then.
"/volume". Here the whole practical functionality of this preset happens. First I select "Current Track Volume" as the parameter. On that can be anything, you can change "Volume" to "Pan", you can replace it with "ACT S1" or you can add "Send"/"Filter"/"FX" parameter. You will immediately notice on your tablet new parameter.
After parameter is selected, I change its value with "Value" Action. In case of OSC Fader, "Direct Linear" is the best option. It set parameter to direct position of the fader (remember, each parameter is 0. to 1. and the fader sends from 0. to 1., so that "works" for any parameter!). For encoders, that will be "Endless" type of change, with particular "resolution" (freely definable for your taste). For buttons (like Mute,Solo), "Toggle" is the right option. It checks current value (0 or 1) and reverse it. Another important option in our case is "Manual touch". Our OSC fader explicitly inform us when it is touched, so we do not need default "automatic guess", "timeout touch". When transport is stopped, that option has no big sense. But when you (re)write Track Automations, that option is crucial. Sonar should know when you want overwrite current value and when not. Without explicit (manual) touch, there is no deterministic way to detect that. With explicit touch available, you can indicate that you want overwrite the automation by touching the fader, even when you do not move it, current constant position will overwrite whatever changes was already written. As soon as you release the finger, the fader will again start to follow already written changes.
The last action is "Value Monitor", I will return to is later in the "Feedback Tab", where it is defined. That is most complicated topic in AZ Controller, but for this example it is sufficient to know whatever parameter was selected before (in our case "Current Track Volume") will be "monitored" for changes, in value (f.e. you move fader by mouse, or it was moved by previous "Value" action, or there is Volume Track Automation) or for parameter itself (f.e. when you focused another track, changed "Volume" to "Pan" in the preset, etc.). Options are important there! So the type is "Value Monitor" (many different things can be monitored, including unconditional timer). The speed is set to "Ultra". That will check for changes ~13 times per second (fastest speed for Control Surfaces). Other speeds will check for changes slower, so labels will be updated not immediately and OSC fader will move is significant "steps" even when the automation is smooth. For old computers, some slow hardware surfaces, slow monitoring can make sense. But not for OSC (so make all your monitor "Ultra"). Priority specify in which order different Monitors are checked. In complicated cases that is important, but not in this example (we have only one Monitor). I prefer "3" for all feedback monitors, to leave "0-2" for "priority" monitors when required (f.e. if you want "track" which pane is Sonar has focus, track or bus, that Monitor should have lower priority since we want "current strip volume" in this case, the the "strip" can be "outdated" till corresponding Monitor is executed... wrong order normally does not break functionality, correct situation is sent 1/13sec after, but that produce some "flickering" on display).
"/volume/z". As I have mentioned, "/volume/z 1" and "/volume/z 0" are sent by TouchOSC when you touch and release the fader. And as I have explained, we want to use that as "Manual touch" for the parameter we operation by the fader. But that does not happened "auto-magically", we should explicitly instruct to do this. On "Touched" we call "Touch Touch /volume", on "Released" we call "Touch Release /volume" (and let AZ Controller find currently controlled by the fader parameter).
Do you remember we have specified "system" as "/volume/z" control type? It is important now! The list is called the same way on touch and release, so we need some way to find when we are called. Touch sends value 1., release value 0.. Do you remember my comment about MIDI value range? Here I use "Value:0" and "Value:127" condition (so 0. and 1. in OSC) for Actions I want to execute. In case the control defined as a "pad", we have to use (default) "Note:ON" and (explicit) "Note:OFF" conditions instead.
In the last action, I explicitly reset "/Volume" Value Monitor... That is a part of "workaround" for the TouchOSC logical bug, explained a bit later.
Feedback TabWhen we define a Monitor in the Logic Tab, we specify the conditions to trigger it. So which parameter to monitor, how and how often. When the monitor is triggered, its own list of Actions is executed, and that list is specified in the Feedback Tab.
The tab is called "Feedback" because originally Monitoring in AZ Controller was to allow the feedback to Control Surfaces. In the mean time monitors are also used for other purpose, but we use it here for the feedback only.
In the example, we have just one Monitor. As I have explained, it is triggered every time something related to our fader parameter is changed (the value, track, the parameter, etc.).
As first, we send current parameter value text to "/volume/value" TouchOSC label (placed on the fader in my layout). For that, I first prepare the text. It can happened the parameter does not exist (we have no tracks in the project), we still want overwrite/reset the text. So I set it to "" (empty) and then try(!) to set it to parameter value (can fail). We send it to TouchOSC then. Since I have a good naming convention, I use "<Ctrl>" as the prefix. I could use "fixed" /volume/value here, but this way I potentially can change OSC name for volume with just reassigning it to the control or I can use the same "code" for many controls ("functional programming" paradigm... too far away from the music, I know...).
As next I send the parameter value (as a number, not as text) to the fader itself. If parameter does not exists, I want to send "0.". But I do not want send it every time, so I first try with real value and send "0." if that "does not work" (Last action:failed). I could use the same for Text before, but text Action does not send anything, so one "extra" initialization is not significant. If I do the same here, TouchOSC will always receive "0. , <real value>". That is not what I want.
But... you see one more condition, I check we have not "touched" our fader. It is time to explain TouchOSC logical bug.
Original "touch sensitive motorized faders" (on hardware surfaces) are "smart". When the fader is touched, the device does not try to "fight" with your finger in case a DAW set it position. Instead DAW position is "remembered" and set only after the fader is released. TouchOSC developers "forgot" to implement that, so when we move the fader on tablet, in case DAW sends position value, the fader is "jumping" all the time between DAW position and finger position. Not only that is visually odd effect, that influence values which TouchOSC sends! When you move slowly, the changes in values are tiny. Sonar, and so AZ Controller, does not "apply" new values instantly. So there is some "delay" between new value is visible in the Monitor, and so fast movement produce quite bug jumping. Not nice.
To "workaround" the problem, I do not send values as long as we touch the fader. But what happens if we manually selected "impossible" value? The fader will become not in sync with Sonar. So, I explicitly "reset" the monitor after the touch is released (in the "/volume/z"), that explicitly sends current Sonar value. And so we have exactly the same (nice) behavior as with correctly implemented hardware faders.
As next, I want to send text with the "origin" and with "parameter name" to corresponding TouchOSC labels. Note that "default" text for not existing parameter can be not empty, I send "Not exist" to origin. And I do not want to send these labels every time only value is changes, I know the labels are still the same. So I "exit" before sending them using "Mon. par. not changed" function (which succeed in case only value is changed, notice "*" at the end indicating the action is "Final" when it succeed).
Notice that while Text Action is represented just as "Parameter Name" in the list, there are different parameters, the first use "Origin name", the second "Parameter". That is an "imperfection" of AZ Controller interface, the list will be too "busy" if I mention all possible Action parameters there.
Final words.
I hope you can understand now, that changing Action order, "forgetting" some Action, even changing one parameter in any Action can make the preset useless/broken or at least inefficient.
During the second car driving lesson, I have unintentionally crossed the street on red light, with tempo 90kmh (in the town, tempo limit 60 and there way many cars and people on that crossing...)
My driving teacher has allowed (!) me to do this, but he has stopped the car 100m later and said:
"You will drive over speed limit, you will drive on red light, you will drive completely drunk... That is live. But you SHOULD NEVER break driving rules without clear understanding which particular rules you are breaking at the moment!"
I had a huge luck with most teachers in my live