Running a series of Sibelius commands using the Execute Commands plug-in

Philip Rothman published a recent post describing how to reset cautionary accidentals to their default settings in Sibelius. After describing in detail how Sibelius works here, he summarized the process in three easy steps:

• Select the material to be reset
• Double-tap the Bracket accidental key
• Double-tap the Suppress auto cautionary accidentals key

I saw that this was a sequence of Sibelius commands, which is something that can be very easily automated using the Execute Commands plug-in. I thought this might make a good tutorial on using Execute Commands to automate a sequence of Sibelius commands, and, well, here we are!

Sibelius commands

When you press a Keypad button, it runs a Sibelius command. To run commands in Execute Commands, you need to know the name of the command. If you hover your mouse over a keypad button, you will see the name of the command that will be run. For our purposes, we will want to run the commands Bracket accidental and Suppress auto cautionary accidental, from the sixth keypad layout.

Plug-ins and Execute Commands

Plug-ins are extra features, and if you are not familiar with plug-ins, you can read about them in a document I created entitled Plug-ins 101 – Finding, Installing, and Running Plug-ins in Sibelius.

Execute Commands is a plug-in that can run sequences of Sibelius commands and plug-ins. It must be installed using File > Plug-ins > Install Plug-ins before it can be used.

Execute Commands is only available in Sibelius Ultimate 2021.9 or later. You can find an overview on Execute Commands in this Scoring Notes post.

Collecting a sequence of commands in Execute Commands

Execute Commands brings up a large dialog that contains lists of command categories and the commands in each category. It will be slow to start the first time you run it in a Sibelius session.

To find the commands you want to use, type part of the command name into the Find in list box, or, if you know the category name you can open the list for that category, in the Command categories list. Since we know we want some keypad commands, the Keypad (accidentals) category is a good place to look, and we will find the commands we want in the middle listbox.

To run the commands, we need to select them in the middle list box and add them to the Command List (the rightmost listbox) by pressing the Add Command to Command List button or the Enter key. Select Bracket accidental and press Enter twice, then select Suppress auto cautionary accidental and press Enter twice.

The Command List should now look like this:

Commands in the Command List need to be unique, so if the same command is used more than once in the list, the second and later copies will have a suffix “~” followed by a number. In the example above, some commands have a “~2” suffix. Execute Commands handles this automatically, and the suffixes will only appear in the Command List.

If something has gone wrong, you can use the Remove selected command or Remove All buttons to delete commands from the list, or the Up and Down buttons to change the order.

You can run the commands in the Command List by pressing Execute Command List. This will close the Execute Commands dialog, and the commands will act on everything in the current selection of the active score.

Saving your sequence of commands

Even after the dialog closes, the commands we have put in the Command List will stay there for the rest of the Sibelius session, but I like to use the Export List button to write the commands to a macro file so I can find them later by using Import List. Press Export List, and give the sequence a name, such as Reset Accidentals To Defaults.  Saving to a macro file gives you a backup and makes it easy to modify your sequence in Execute Commands if you need to make changes in the future.

Macro files are text files that use a .dat extension and are stored in the special Execute_Commands subfolder of your default Scores folder.

Here is a screenshot of the Export List dialog:

Testing the command sequence

One should always test whether the command sequence works correctly. Press Cancel to close Execute Commands, set up a score that will demonstrate whether it works as expected, and then run Execute Commands again to test it.

You will want to have a score that has incorrect accidentals so you can run the sequence and see that it corrects them. Let’s use the same data Philip used in his post:

I created a Sibelius score using Philip’s modified data and then made a copy of the notes in the staff below. I selected the notes in the second staff, then brought up Execute Commands again. The commands I wanted were still in the Command List.

I pressed Execute Command List to run the commands.

Here are the “before” and “after” examples Philip used:

And this is what I got by running the command sequence:

Looks good to me!

This is a pretty simple sequence and I knew what to expect, so I made just a few more tests before I was satisfied that it was working. If I had discovered that I needed to correct the sequence or add more commands, I would have made the changes in the Execute Commands Command List and saved the changed command list using Export List until I was convinced everything worked.

In many cases, I would spend much more time testing before trusting that the commands are doing what I want, but let’s say I am satisfied that things are working, and I now want to save the sequence as a new macro or plug-in.

Saving the sequence as a macro

To save the sequence as a macro, use the Export List button to save the commands in a macro file.

Once a macro file is saved, you can bring it back into Execute Commands with Import List and run it again, or you can install and run the plug-in Run Command Macro and use it to run your macros.

Saving the sequence as a plug-in

When you have saved the commands as a plug-in, you can assign a keyboard shortcut to it or run it with one of the many plug-ins that can find and run other plug-ins. You can also use your new plug-in as a command in Execute Commands.

Start the process by using Export List to save the Command List to a macro file. If you need to make changes it is easier to edit the Command List in Execute Commands than it is to edit the generated plug-in in the Plug-in Editor.

The commands that will make up the new plug-in must be loaded in the Command List. Use Import List if you need to load saved commands into the Command List.

The New plug-in… button will incorporate the contents of the Command List into a new plug-in file. By default, the plug-in file will be saved into the Execute_Commands folder of your user plug-ins folder, and this folder will be created if it does not exist.

When you press the New Plug-in… button in the most recent version of Execute Commands…

you should see something like this:

You will need to type the plug-in name, as it will appear in plug-in menus, into the edit box, then click OK or press Enter. This should be a descriptive name, typically made of words with upper-case first letters separated by spaces. In this case I will choose the name Reset Accidentals to Defaults.

When I press OK, I see this message box, telling me where the plug-in file has been written:

This text will also be written to the plug-in Trace window, so you can still find the name after the message box comes down.

You now need to close and save any open scores, then close and restart Sibelius.

Running your new plug-in

Open the score you have been using to test the macro code and run the new plug-in against that score. Any plug-ins generated by New Plug-in… will have a _CP (for Command Plug-in) suffix added to the menu name and file name, so I would see the plug-in I just generated listed as Reset Accidentals to Defaults_CP if I looked for it in Command Search or a plug-in menu.

There are many way of finding and running plug-ins, and several of these are described in the aforementioned document I created entitled Plug-ins 101 – Finding, Installing, and Running Plug-ins in Sibelius. My favorite way to run plug-ins is to run the installable plug-in Run Plugins By Name, which provides a sorted list of all your installed plug-ins, with no setup required.

Editing and debugging your new plug-in

If you find the plug-in does not work as expected, I recommend going back to Execute Commands. Use Import List to load your macro file, and debug the problems there, since macro files are more forgiving than ManuScript plug-in code. If you want to try editing the ManuScript code directly, you can edit the plug-in file by going to File > Plug-ins > Edit Plug-ins, typing the menu name into its Find box, and pressing Find until the plug-in you want is selected. Now press Edit… and you will be off on an interesting adventure. The code you want to look at will be in the method ProcessScore.

Reset Accidentals To Defaults

The sample plug-in Reset Accidentals To Defaults (without the _CP suffix in its name) has been published, so you can install it using File>Plug-ins>Install plug-ins in the category Accidentals. It will run in Sibelius Ultimate 2021.9 or later.