JustMacros

Step one is to install the Standard Blackmagic Design ATEM Package suite of software. Just Macros uses the official SDK/API, and therefore requires users to install the official software suite. Please follow instructions from Black Magic Design. Once this is done, or if you are not planning on using a Blackmagic Design ATEM mixer you can now download the latest Just Macros full package from: Full Downloads Page

Downloads are either a ZIP file or a Self installing EXE file. In the case of ZIP Files, you should expand the ZIP file into a directory that you have read/write access to. JustMacros uses a subdirectory named Macros to store all your scripts, so if you do not have Local Administration Rights on your computer, you should ask your IT department for help deciding where to install.

Once you have created the JustMacros base directories, you need to create a shortcut to the JustMacrosXXXXXX.exe of your choice. If you are using a Blackmagic Design ATEM mixer, it is important to know the Firmware you have installed. The easiest way to discover this is to use the Blackmagic Design ATEM software, and go to the Help About window.

Identify the JustMacros EXE file that most appropriately matches your ATEM Firmware version. So if using ATEM firmware 3.4, you would require JustMacros33Plus.exe, if on 4.1.2, you will require JustMacros41Plus.exe. Now create a shortcut to the EXE on your desktop so that you can launch JustMacros.

If you want the very latest BETA version, also visit the patches page and download just the EXE file without the supporting DLLs and basic sample scripts, then copy the Patch EXE file into your JustMacros directory. The latest patch will only ever contain an EXE for the latest Blackmagic Design firmware release. This is because the patches are intended for users to test the latest features. Patches Page

When you first run JustMacros you will see the main graphical user interface used to configure your system.

The screen is divided into 5 sections. The left side has a panel which shows all the scripts loaded into the system. Users can right mouse click this area, to access popup menu options that allows for the creation of new directories, scripts and other files. The right side of the screen contains a list of commands. The general principle is that to execute one task, you should have to execute one command. To help users find the command required, at the top of the list is a search box. Type some words that describe the task you need. For example: If the input source for a key needs to be changed, a user might enter… set key source

The words are used together in an AND query, so each word entered will further limit the search results. As soon as the command required can be identified in the list, the user can double click the command to obtain HELP information in the 3rd section of this screen, the Log Window at the bottom. Additionally the command will be placed into the Single Line Command box, and the cursor positioned so that the user can type just the parameters, separated with commas, and press the ENTER key to execute the command.

The centre part of the screen is the main script editor. After you create new scripts, either with the popup menu or by using keyboard shortcut Ctrl-N. You can edit scripts in the main window. Changes to scripts will be indicated with a red mark to the left of the line of script which has been changed. Scripts can contain variable assignments, loops & conditional expressions. Lua is a widely used scripting language and many resources exist online to aid further with the learning of this scripting syntax.
JustMacros adds to the Lua language more than 1000 JustMacros specific commands that users can call from within the scripts. In the example below the CLS() – Clear the Log, VSLog – Add a line to the Log, and various ATEM commands can be seen, this short script lists the ATEM Mixer inputs in a table of values inside the Log. It is included in the Information Scripts included in the full package downloads. Most of the JustMacros specific commands are illustrated in one of the 1000 or so example scripts published to demonstrate various broadcast tasks. Please see the Sample Script downloads section of the website for more details.

The fifth part of the screen is the menu bar along the top. The first 4 buttons are fixed, MACROS, DEVICES, TASKMAN, and X-KEYS. There are 10 more slots for users to add their own buttons, and these can be accessed using commands starting GUI Button.

Snapshots are similar to EMEMs on Grass Valley mixers, and similar to the features introduced in version 4 of the ATEM control software, regarding saving and recalling configurations on the ATEMs from the software. Users can setup Keys or transitions or the SuperSource the way they want it to look. Then right mouse clicking on the list of macros on the main page gives access to the menu of what to snapshot.

When one of these menu options are selected a Script will be created, for example, if a user snapshots a DVE Key that is showing BARS in a box in the top left corner of the screen with a soft purple border, a script would appear called SnapShotNNNNN, and it would look like this:

As you can see the mixer number ME number and Key number are parameterized, so if the user snapshots KEY1 and wants to apply it at a later time to KEY4, just the variable assignment at the top of the script would require updating.

Scripts are executed using the EXECUTE button towards the top of the screen, and the EXECUTE button alongside the Single Line Command entry field runs any Lua command in that box.

It is recommended that users rename Snapshots with meaningful names, and store them in sub-directories. All scripts must have unique names, you cannot have two scripts both named SCRIPTA even if you store them in different sub-directories / folders. The folders are there purely to help organise your scripts. EVERY SCRIPT MUST HAVE A UNIQUE NAME.
Now to assign a Snapshot to an XKeys button, you use the ASSIGN key and functionality.

It will highlight in YELLOW, to indicate the system is waiting for the user to push a button on an XKeys panel. If more than one panel is attached, it may be necessary to press the required button twice, as the first selection will select the panel, and the second select the button. When the snapshot has been assigned to a button the ASSIGN button will return to normal.

This button can now be used to recall the configuration of the DVE key. The process can be repeated for SuperSource layouts, or Multiviewer configurations.

Whereas the main JustMacros screen allows scripts to be written for virtually any purpose at all. JustMacros also endeavours to meet the needs of those users who do not intend to write any scripts at all. For example, a user who wishes to create a simple Programme / Preview Cut panel, can create an entire workflow without writing any scripts. A user accesses the X-Keys screen by clicking on the X-Keys button on the top menu bar of the application.

This screen is again divided up into 3 main sections: Top Left corner shows the list of X-Keys panels currently attached to the system. If the panel was added after JustMacros was started, it will be necessary to execute an… XKeysScanForPanels()… command, or restart JustMacros to pick up the panel. When a specific panel is selected, a representation of the panel will be displayed. If a User pushes buttons on the panel, the representation will indicate a depressed button by turning it Yellow on the screen.

The most important thing to do to any new panel is to allocate it a “Unit Identifier”. This must be a number between 1 and 255. After setting a value using the Text Box, users should select the UPDATE button to send the change to the panel. Now if the panel is removed and replaced, or plugged into another computer, the ID given to the panel will remain.

The bottom left hand side of the screen shows the list of Profiles. A Profile is a mapping table, mapping an XKeys Unit Identifier to Macros and/or built in functions. Essentially it is a virtual panel. Profiles also get IDs, and where the physical Panel ID matches a Profile ID, the two are linked, and so when the physical button is pressed, JustMacros find the linked profile and checks what that profile says should be done when that button is pressed. This model is very flexible, allowing users to configure multiple profiles, and effectively re-task the panel by changing its ID between different profiles. Profiles can be created manually, or the easiest way is to select the EDIT button on the XKeys representation, and then press one of the physical buttons on the panel. A dialog will be displayed asking the user if they wish to create a profile for the panel, answer the question YES.

Because the EDIT process was interrupted by the creation of a new profile, users will need to repeat the EDIT process again to start assigning functions to buttons. After the profile has been created, the EDIT process will respond to a button press by opening a function select screen.

Most common ATEM functions that map to a button action, can be selected from this list. Double clicking or selecting (single click) then clicking OK, will map the action to a button. However some commands require a little more information, for example if a user wanted to define a button to switch upstream Key 2 on and off, the user would select KEYONAIR function. The system would then present the user with a screen to allow them to select the MIXER, ME and KEY numbers.

The user can also enter a couple of lines of caption text. This text is currently only used for Printing XKeys labels. Users can print sheets of labels for panel profiles by right mouse clicking on the Profiles panel (bottom left), and using the “Print Profile Keys” menu option. After the properties are set the user should select the OK button. The XKeys button will then toggle the USK on and off.

In this case the red LED back-lamp will illuminate when the USK is on air. Most of these predefined action buttons will have default LAMP behaviour. For instance, if a Key is defined as a ATEMPROGRAMSOURCE, then when the selected source is on AIR the RED back-lamp will illuminate, but ATEMPRESETSOURCE will illuminate BLUE when that source is on preview. Essentially all the buttons you find on the main Blackmagic Design application switcher page, are reproduced here as predefined button actions.

This should allow for a basic mixer panel to be created. In the sample videos section and on the VIS Visual Information Systems Youtube channel, various videos show different layouts of panels, these samples and other examples are available for download, but users are encouraged to develop their own. As described here, the process is point and click, and this way users can create exactly the layout they need with nothing more and nothing less.

Where more changes to the mixer than a simple snapshot can provide are required, or sequences of actions need to be played back multiple times, Recording Macros can be a useful technique. Start By selecting the Record Button displayed just below the ASSIGN button.

As changes are made to the Mixer, either using Blackmagic design Application or Panel, or running actions from JustMacros, whatever changes on the mixer, will appear in the main edit window. You can tell the script is auto-writing because the font will display in RED whilst the recording is taking place. Once all the actions have been manually performed, the highlighed STOP button should be selected for the user to indicate the process is complete. The Script will then change to the standard colour scheme.

The user may now re-execute the script by selecting the EXECUTE button towards the top of the screen.

On examination of the script, it can be seen that each command will normally be separated with a Sleep command. The Sleep command is a very important command in JustMacros. You should use them in most types of scripts. It functions primarily as a delay, and the number in the brackets indicates the amount of time to wait measured in milliseconds. Therefore if a 2 second delay is required, a Sleep( 2000 ) command should be added in the script. Understanding this, after a user has recorded a script, by adjusting the Sleep commands, the sequence can be more precisely controlled.

Again these sequences can be assigned to an XKeys button using the ASSIGN command. When a script which is assigned to an XKeys button runs, whilst that script is executing JustMacros will illuminate the back-lamp of the assigned XKeys button RED, this gives operators a visual indication that a script is running, particularly useful if towards the beginning of the sequences, changes are not visible on the output. This is also true of the previously discussed snapshots that are assigned to XKeys buttons, however typically snapshots execute extremely quickly and therefore this behaviour is far more noticeable when playing back sequences that have been recorded.

When users require even lower level control of the system, manually writing Lua scripts becomes essential. Most problems can be expressed as a number of loops containing conditional tests, and acting based on the state of components. We refer to these as Just Macro Monitoring Scripts, and many examples are available to download in the downloads section. When we implement these scripts they always follow the same process.

Start by creating 2 new scripts, one called MY_MONITORING_PROCESS and one called MY_MONITORING_STOP. Obviously change the prefix on the name to something meaningful and related to what you are monitoring. In the example shown we are going to switch an XKeys RED backlamp on when our HyperDeck is recording, and switch it off when the Hyperdeck is not recording.

So to understand how to do this we must introduce a concept in JustMacros called The Environment. Each script in JustMacros runs within its own Lua virtual machine and thread. This allows multiple scripts to be executing simultaneously. However it has a drawback. Scripts cannot interact with each other, each script is effectively running a separate program that gets launched when you EXECUTE it, and terminates when it has no more commands to run. This means if you establish variables within a script, when the script ends, the variables are destroyed and are no longer accessible.

The JustMacros Environment helps solve this problem. The JustMacros environment is a Key/Value store that persists always. It is cached to the Windows registry and internal file on Mac, however it is primarily held in main memory (only being stored to disc no more often than 2 seconds). Each Environment Key/Value pair is protected by a critical section, this is a mechanism that prevents the system crashing when two scripts try to read/write the same environment variable at the same time, but users can simply assume they can use EnviroRead ( Variable-Name ) and EnviroWrite ( Variable-Name, Variable-Value ), from any script and be assured the values will remain between different scripts even after restarts and reboots.
We now have a mechanism whereby we can start a script, and put it in a never ending loop waiting for another script to terminate it, we can write a monitoring script that looks like this

The monitoring script is currently doing nothing, except if the environment variable is already set TRUE, it sets it to FALSE, and then waits an appropriate amount of time for any existing monitoring process to terminate. This means users can edit the monitoring script whilst it is running, by hitting EXECUTE after making changes the existing process will terminate, and the new modified one will start. The Stop script that looks like this:

All that is now required is to add the conditional that checks to see if the Hyperdeck is recording and sets the XKeys button. This code looks like:

We have introduced two more variables XKEYS_PANEL_INDEX and XKEYS_BUTTON_NUMBER. Which is added at the top of the script where we originally were just defining the HYPERDECK_NUMBER to be one.

We must convert from the Unique ID we have given our XKeys Panel, and the index that panel is currently enumerated at. Because this is a common process, VIS Visual Information Systems provides a number of samples utility script libraries. One of these is called XKeysTools, and it contains a function called XKeysPanelIDToIndex. In order to access functions in other scripts, the other scripts need to be loaded into memory when the processing script runs, basically compiled into the Lua Virtual machine that is running the script. This is done using a JustMacros $$USES technique.
Put simply, when JustMacros runs a script, it first reads through the script looking for comment lines containing:

$$USES “ScriptName”, “AnotherScriptName”

Although Lua itself has a mechanism for including scripts in other scripts, that involves accessing the hard drive. JustMacros loads all scripts into memory at start up, and hence when including scripts using the $$USES technique, there is no need to access the disc. Essential when running millions of scripts per day. So the completed monitoring script, with all required parts now looks like this:

As many monitoring scripts as you like can be running in the background. It is important to have a Sleep(XX) in the script, otherwise the loop will run many thousands of times per second, and be very wasteful of CPU resource. It is expected that users will actually have just a few monitoring scripts, that will monitor groups of related properties and functions.

We should also now introduce one other type of XKeys Button type. The STANDARD type XKeys Button. This is one of the options when EDITING an XKeys button as discussed in the First XKeys Panel section of the website. However a STANDARD button has no default behaviour whatsoever, it simply exposes the Button Pressed and Button Released events, and allows users to allocate Lua code (rather than a prepared Script file) to buttons.

Our Hyperdeck Record button indicator light, really needs to be able to start and stop recording, and a STANDARD button type makes this a very easy task.

So we now have a Button on an XKeys panel that will start and stop the HyperDeck Recording, and illuminate when it is recording, in response to the Hyperdeck, not whether or not JustMacros has asked it to record. This means you can start and stop recording from the front panel on the Hyperdeck, or from the XKeys Panel, or another script, and the XKeys back-lamp will show correctly, because it is not only being updated when the button is pressed, but whenever anything changes on the hyperdeck by the Monitoring Script.