How to write a Good Macro - Tutorial 1 (Cubase)

[Support Team]

This is a tutorial on how to write good Macros for DTouch.
In this tutorial, let's pretend that we need a Macro to add 8 Mono Audio Tracks to our Cubase Project.
Please note that DTouch for Cubase version 1.1.12 or later is required in order to use the Macros attached to this topic, since we are using new Macro Engine functions that weren't available in previous DTouch versions.

First of all, we think about our "problem" and find a way to solve it by using Cubase directly:

1. We choose the "Project" >> "Add Track" >> "Audio..." Cubase menu.
2. The "Add Audio Track" window appears.
3. We select "Mono" from the configuration.
4. We double-click on the "Count" number and type "8" on our keyboard
5. We hit Enter on our keyboard

At this point, Cubase is adding the 8 new tracks to the Project.


We'll now try and translate this list of actions into Macro Commands for DTouch,
aiming at building the simplest possible Macro, and improving it on next steps.


For Step (a), we use the "Cubase Key Command" Macro Command in DTouch.
Select the "Add Track", "Audio" parameters for that Command.

Now, the "Add Audio Track" window would be there, but since we may have a heavy-loaded system while we run this Macro, let's add a little pause after this, in order to give it some time to appear.
Add a "Sleep" Macro Command, with a 500ms parameter.
This is Step (b) of our list of actions.

Let's look at the window that just appeared.

IMG1.png (24.92 KiB) Viewed 68418 times

Since Cubase remembers some parameters from the last time that we used this window, we need to set them, even if they are already correct for our current Macro.
We now need to select "Mono" as configuration (even if it's already set).
This is Step (c) of our list of actions.
The easiest way to accomplish this with DTouch is:

• Open the "Add Audio Track" window, using the Cubase Menu "Project" >> "Add Track" >> "Audio..."
  (You can temporarily minimize the Macro Editor in order to perform this)
• Select a "Mouse Move" Macro Command
• Tick (enable) the "Relative to Fg" checkbox (see note *1 below)
• Move your mouse exactly over the "Mono" Configuration type, and press the F2 key on your keyboard.
  The exact spot we used for this Command is indicated by the red arrow on the above image.
  The F2 key has populated the x,y coordinates with the current mouse location.
  Add this Macro Command to the Command list by pressing "ADD".
• Add a little pause, to stay safe: Add a "Sleep" Command, with a 50ms parameter.
• Add a "Mouse Left Button Click" Macro Command
• At this point, the Macro would have clicked on our defined point, and a pop-up menu would have appeared.
  Let's add another little pause, to stay safe: Add a Sleep Command, with a 50ms parameter.
• We now need to select "Mono" from the pop-up menu, and will do that using keyboard keypresses.
• Add a "Keyboard Shortcut" Command, with the DOWNARROW parameter. (Tip: in order to add the parameter, you actually need to press the down arrow key on your keyboard!)
• Add a "Keyboard Shortcut" Command, with the ENTER parameter.
• At this point, the pop-up menu would disappear, and we add another 50ms "Sleep" Command to stay safe.

Let's translate Step (d) into Macro Commands:

• Open the "Add Audio Track" window, using the Cubase Menu "Project" >> "Add Track" >> "Audio..."
  (You can temporarily minimize the Macro Editor in order to perform this)
• Select a "Mouse Move" Macro Command
• Tick (enable) the "Relative to Fg" checkbox (see note *1 below)
• Move your mouse exactly over the "1" Count, and press the F2 key on your keyboard.
  The exact spot we used for this Command is indicated by the yellow arrow on the above image.
  The F2 key has populated the x,y coordinates with the current mouse location.
  Add this Macro Command to the Command list by pressing "ADD".
• Add a little pause, to stay safe: Add a Sleep Command, with a 50ms parameter.
• We now need to double-click on that number. To do this, we add TWO "Mouse Left Button Click" Macro Commands.
• At this point, the number should be editable. Add a 50ms "Sleep" Command, to stay safe.
• We need to enter "8" in the Count, and for that, we'll add a "Type Text" Macro Command, with "8" (without quotes) as parameter.
• Add another 50ms "Sleep" Macro Command to stay safe.

Last Step (e) is simply translated into a "Keyboard Shortcut" Command, with an "ENTER" parameter.


Since we are building a good Macro, we'll add another 1000ms "Sleep" Macro Command, in order to give Cubase the time to add the 8 new Tracks to the Project, and finally we'll add a "Update DTouch Mixer Graphic" Command in order to tell DTouch to refresh its Mixer graphic state (since the new Tracks could have moved the Cubase Mixer around).


That's all for now!
The Macro we just built does accomplish the required task, and some of our users may even be completely satisfied with this one.
This is OK, since we designed DTouch to be flexible and adaptable to the different workflows of our users.

But, we want to write the best Macro we can, and so will improve this one in the next steps.

The Macro, as described in this post, is attached.

NOTES:

1. The "Relative to Fg" setting is important, since that makes your mouse movement relative to the current foreground window.
   This makes the Macro more flexible, as it is not strictly bound to where the window is currently placed.
   We strongly encourage the use of relative mouse coordinates, and the Macro Editor makes use of such coordinates
   when possible, in order to help you write better and universal Macros.

[/i][/size]

[Support Team]

In this step, we are going to improve our Macro by making it somewhat configurable.

We built a Macro for adding 8 Tracks, but what about adding 6 Tracks? Or 24?
In order to build a good Macro, it's always a good idea to identify some sections that could be re-used in the future to build some derived Macros.

To get this done, follow these steps:

• Add a "User Code" Macro Command, to the top of the Command List.
• The User Code Editor appears.
• Enter this text:

  Code: Select all

  nr_tracks = 8

• This defines a new variable of name "nr_tracks", assigning it the number 8.
• Save the new Command, and move it to the extreme top of the Command List by using the "MOVE UP" button.
• Go down to the "Type Text" Macro Command, and select it.
• We are going to change this Macro Command, making it use the new "nr_tracks" variable.
• Press the "MODIFY CMD" button. The User Code Editor appears, containing the text:

  Code: Select all

  dtmacro.send_text("8")

• Change it to this:

  Code: Select all

  dtmacro.send_text(str(nr_tracks))

• Save. The User Code Editor closes.

The Macro has improved: you can now change its behavior by simply editing the first Macro Command, and change the variable contents to 6, 24, or any number of Tracks that you want.
Tip: you could even ask the number to the user, using the Macro Player!

The updated Macro is attached to this post.

[Support Team]

In this step, we are going to improve our Macro by making it faster.
Remember when we added a fixed 500ms delay right after we sent the "Add Track", "Audio" KeyCommand?
We are going to make DTouch wait for the new window to appear, thus making the Macro as fast as your computer can: it will be faster most of the time, but if your computer is heavy-loaded, busy processing a lot of Tracks and Plug-ins, the Macro will wait even more than 500ms, until the desired window is actually there.
In order to get this done, we'll use the DTouch "Wait for window appear" Macro Command.
That Command halts the Macro execution until a window with a specified title appears.
The title of our wanted window is "Add Audio Track", in English; but we want this Macro to be compabible with any supported Cubase language, and so we choose the right window title to wait by asking DTouch the current Cubase language.

Follow these steps to improve our Macro further:

• Go to the 500ms "Sleep" Macro Command, right after the "Cubase Key Command" one, and select it.
• Press the "MODIFY CMD" button. The User Code Editor opens, with this code:

  Code: Select all

  dtmacro.sleep(500)

• Replace the code in the User Code Editor with this one:

  Code: Select all

  win_title = ""
  language_id = dtmacro.get_cubase_language()
  
  
  if language_id == 1:
  	win_title = "Add Audio Track"
  elif language_id == 2:
  	win_title = "Audiospur hinzufügen"
  elif language_id == 3:
  	win_title = "Ajouter piste Audio"
  elif language_id == 4:
  	win_title = "Añadir pista de audio"
  elif language_id == 5:
  	win_title = "Aggiungi traccia audio"
  elif language_id == 6:
  	win_title = "Adicionar pista de áudio"
  else:
  	return ""
  
  
  if dtmacro.wait_win_appear(win_title) != 0:
  	return ""

• Save this Macro Command.
• Since the last Python function we used has opened the Macro Player, we now need to close it.
  Add the "Hide Macro Player window" Macro Command to the list, right below the one we just changed.
• Add a 50ms "Sleep" Macro Command, to stay safe.

The Macro has improved: now it is faster if Cubase is fast to make the "Add Audio Track" window appear; and it will not fail clicking in wrong places if Cubase takes more than 500ms to create the "Add Audio Track" window (maybe because it's loaded with more important audio tasks).

The updated Macro is attached to this post.

[Support Team]

In this step, we are going to fix a problem of our Macro.
The "Browse" button on the "Add Audio Track" window changes completely the window look, and more importantly, the "Configuration" option is not available anymore.

IMG2.png (68.98 KiB) Viewed 68403 times

Cubase remembers the look of the "Add Audio Track" window since the last time it's been used and so, after you open the "Add Audio Track" window with the Cubase keycommand, it may look like in the above screenshot.
In order to go back to the previous look, you simply need to press the "Browse button".
Our Macro needs to check for this condition, and press that button.

How can we do that?
One way could be to compare the pixel color of the "Configuration" input box with that of the outside area: if they are equal, then the Browse section is opened.

Follow these steps to get this done:

• Add a "User Code" Macro Command, right above the first "Mouse Move" Command.
• The User Code Editor appears; enter this code:

  Code: Select all

  color1 = dtmacro.get_pixel_color("FOREGROUND", 15, 16)
  color2 = dtmacro.get_pixel_color("FOREGROUND", 192, 35)
  
  
  if color1 == color2:
  	# "Browse" section opened, close it
  	dtmacro.mouse_move_rel("FGWIN", 28, 39)
  	dtmacro.sleep(50)
  	dtmacro.mouse_leftbutton(1)
  	dtmacro.mouse_leftbutton(0)
  	dtmacro.sleep(100)

• Save

Et voilà! The Macro now handles even this condition, which would have resulted in it failing to set all the parameters correctly.

The updated Macro is attached to this post.

[Support Team]

This post has been reserved

[PeterZ]

Hi DT_support!

Thank you for doing this. Would you mind to give us the complete macros in a txt format so we can adjust the macros to our needs and then copy them into the DTouch macro engine?

I created some programms in fortran and C .... but that was in the late 80s and beginning 90s - now you can imagine my programming skills in the Python snake language!

But if I see the complete code from beginning to end I'm little optimistic I can reeingineer some things, understand better, and at least adapt those macros to my needs.

Peter

[Support Team]

Hi DT_support!

Thank you for doing this. Would you mind to give us the complete macros in a txt format so we can adjust the macros to our needs and then copy them into the DTouch macro engine?

I created some programms in fortran and C .... but that was in the late 80s and beginning 90s - now you can imagine my programming skills in the Python snake language!

But if I see the complete code from beginning to end I'm little optimistic I can reeingineer some things, understand better, and at least adapt those macros to my needs.

Peter

Hi PeterZ,

Please note that you can download and then IMPORT these Macros in the DTouch Macro Engine by using the DTouch Macro Editor.
You are then free to edit them as you like, make copies of them, and even re-EXPORT them and upload your edited version on this Forum or anywhere you like.

It is true that the underlying language of Macros is Python, but you don't need to be a Python programmer in order to change the behavior of a Macro.
Just use the Macro Editor and its tools and features to add/move/delete Macro Commands.
A Macro is not a static piece of code; it can be edited and improved over time, as you can see from this tutorial.
A Macro Command is a single entry on the Macro Command List (which is the table that you see on the bottom-right part of the Macro Editor).
Every Macro Command has an underlying associated Python code, but you don't need to know nor edit it.

We created the Macro Editor this way in order to be the simplest possible for anyone, yet be powerful enough for advanced users that want maximum flexibility.

Said that, you can create a flat listing of any Macro following these steps:

• Choose the Macro that you want to change to a flat listing, and select it in the Macro List on the Macro Editor
• Press the EDIT SEL button; the right section becomes available
• Press the SEL ALL button: all Macro Commands will be selected
• Press the MERGE button: all the selected Macro Commands will be merged into one big flat "User Code" Macro Command.
• You can look at the underlying Python code, as always, by pressing the MODIFY CMD button.

Please note that we don't encourage this; your Macro will be difficult to read and understand, even by yourself.
You can better organize Macro Commands, (and thus, entire sections of Python code) by leaving them separated; you can even add some comments in the Macro Editor interface.
Keep Macro Commands as-is if you can; only change to Python language if you have to implement something that's not available using standard Macro Commands (as you see in this tutorial: Step 1 is entirely made of Macro Commands; no Python involved)

[PeterZ]

Thank you, I will try!

[DT_bettinzana]

Hello all,

I want to add something to this thread.
Our macro editor have two levels of complexity to build your macros:

1) Macro Commands
2) Python User Code

The Macro Commands are the most simple tools to write a macro. You have a long list of basic macro commands which you can use for 90% of your macros. You don't need to have programmng skills to use it.

The Python User Code is the highest level of macro programming tool. With it you can capture values in variables, request values to the user, read pixel colors, check if a window is open/close, use "if" statements to control the flow of a macro, etc ... it has all the power of a modern and advanced macro/scripting language. Even more, Python is the industry standard in the field of scripting languages.

The two methodologies aren't disjointed. In fact, when you fire a macro, each Macro Command is immediately translated in a piece of Python code. You can see the Python code hidden in a Macro Command by transforming it in a "user code" command.

Why have we done this?
The answer is both simple and complex:

1) With Macro Commands you can write some simple macros
2) With Python language you can build very complex macros. For example you could read a txt file and use it to automatically rename your tracks, or ... who can say!

We have seen some Macro tools from some of our competitors and we have studied some of their macros. Due to the poor programming tools that they have in their applications, those macros are not smart at all. For the complex tasks, the user must check and adjust a lot of conditions in their DAW before firing the macro. In some case, the user must fire a first piece of a macro, then he must carry some manual task, then fire a second part of a macro, etc ...
This is due to the fact that without a smart language, you must have a well preconfigured layout/condition. Those macros cannot have an inner intelligence.
Our macro language can help a lot on this.

Off course, nothing is free! Writing a complex macro could be a daunting task and needs some programming skills. So, we think that very few of our users will invest some time to write the "perfect" macro. On our side, we will do our best to offer the highest quality macros.

If you read this thread from the init, you will see that the same macro can have many level of intelligence. If you are satisfied by the first level, this is good. If you want a macro which works in any condition, you must pay more attention and time during the programming and go to the next level.

That said, we can help you writing you preferred macros. You can play with the macro builder and if you find an obstacle, we are here to help you.

Last but not least: no macro engine can do EVERYTHING. In general we can mouse move/click, fire keyboard commands, virtually click on menu items, etc ... but we have no access to the inner database of a Cubase/Pro_Tools Project/Session. The best way to discover if one thing can be done is contacting us!

Enjoy!

Silvano Bettinzana
Devil Technologies

[MichaelScott]

Excellent tutorials. This has pointed me in the right direction as I was having issues buidling on simple macros. Thanks!