In Sibelius, Command Search and the Command Menu will let you run one command at a time.
In order to allow us to run a sequence of commands, the plug-in language ManuScript was given a new instruction,
Sibelius.Execute(), which allows a plug-in to run a command on the current selection. A plug-in can include a series of
Sibelius.Execute() calls, and thus run them all as a single action.
Sam Butler gives some examples of adding
Sibelius.Execute() calls directly to ManuScript plug-ins in his blog post announcing Sibelius Ultimate 2021.2, and that is a good place to get an overview of the process.
I see two ways of using commands in plug-ins. The first is to run a sequence of Command Names (which I refer to as a Command Macro or a Command Plug-in), and the other way is to incorporate
Sibelius.Execute() calls in normal plug-in code.
Command Macros, Command Plug-ins, and the downloadable Execute Commands plug-in
Rather than creating a new plug-in and then using the Plug-in Editor, try using the downloadable plug-in Execute Commands.
Execute Commands lets you create a sequence of Command Names and save them as a text file (a Command Macro) or as a generated plug-in file (a Command Plug-in) without actually editing any plug-in code.
Execute Commands provides you with lists of all the available Command Names, organized by category. To find a command, either choose the category and find the command in the main list, or use Find in List, typing in any part of a command name and clicking on Find until you get a match.
Once you have selected a command in the middle listbox, click on the Add Command to Command List button, which will add the command to the bottom of the Command List. The buttons below the Command List will let you delete a command, or change the order of the commands by moving the selected command up or down.
When you have the commands in the desired order, you can see if they work as expected by clicking on the Execute button at the bottom right. This will close the dialog, and execute each command in the command list in order.
For this to work, your score will need to have a selection and contents appropriate for what the plug-in does. You can close Execute Commands at this point and set up the score, and then run Execute Commands again. Don’t close Sibelius, though unless you export your Command List first. The commands in the Command List will stay there for the same Sibelius session, but will be cleared the next time you close and restart Sibelius.
Run Execute Commands again if you need to change something.
Running a sequence of commands in this way should give the same results as running each of the commands in the list, one after the other, in Command Search. It is possible that there will be differences due to timing; when using Command Search to run the commands there will be a larger gap of time between commands than there will be run running the sequence as a macro or plug-in. Some commands may need time for the score to redraw before starting another command. As of this writing I have not found any commands that do not work as expected in a sequence, but it is a definite possibility.
Exporting Command Macros
Once you are comfortable with your sequence, you can save it, using Export List…, which will save the Command List as a text file in the Execute_Commands subfolder of your default Scores folder (as specified in File > Preferences > Saving and Exporting). You can use Import List to read in any file that you previously exported, and you can then Execute the commands you have imported.
Generating new Command plug-ins
You can also save the Command List as a plug-in file using New Plug-in…. New Plug-in will let you select a file name, a menu name and a plug-in folder to save the commands into. By default it will install it into the Execute_Commands subfolder. You will need to close and restart Sibelius before you can run or edit the generated plug-in, but once you do that it will behave exactly like any other plug-in. You can run it from Command Search, using the menu name as the search key – you might consider making the menu name something that will be easy to type into Command Search.
As with any other plug-in, you can also assign a shortcut to it or run it from within Run Plugins By Name, or find it in a plug-in menu on the Ribbon.
Here is one example of how this could make your life easier. In Philip Rothman’s review of Sibelius Ultimate 2021.2, he created a plug-in that contained a single instruction just so he could set the Menu Name of the plug-in to be
///. In Execute Commands you could find the 8 tremolos command and put it in the command list, then click on New Plug-in… In that dialog you need to name the plug-in, and in particular, set the menu name to be
You would need to close and restart Sibelius to be able to use this plug-in, but you would actually never need to edit it. If you edit the generated plug-in and look at the generated instructions, you can see that New Plug-in automatically converted the Command Name to a language-independent Command Id, and while there are still several steps to do this, you do not ever actually “touch code”. You can just run the generated plug-in.
If you had multiple commands in the Command List, they would all be included in the generated plug-in.
Running Command Macros in the downloadable Run Command Macro plug-in
The plug-in Run Command Macro puts all the Command Macros you have exported into a list box, sorted by name, and given a numeric index. To run a Command Macro, select its name in the list box and press Enter to run it. If you check the checkbox Run Macro if list box changes, the plug-in will run as soon as a new selection is made in the list box.
Sharing Command Macros or Command Plug-ins
Command macros are stored in the Execute_Commands subfolder of your default Scores folder. Find them there (they are Text files with .dat extensions), and send them away. The recipient will need to have create an Execute_Commands subfolder in their default Scores folder, and copy the .dat files to that subfolder.
To share a Command Plug-in, you will need to find the .plg file in the plug-in folder it was saved in, and the recipient will need to copy it into an appropriate plug-in subfolder, or use the downloadable plug-in Install New Plugin to move it to an appropriate location. They will need to close and restart Sibelius before that plug-in can be used, since Sibelius loads all plug-ins at startup.
Incorporating Commands into existing ManuScript code
You can use commands to do things in ManuScript plug-ins that were previously impossible, and this can be really helpful. That is a topic for another post, though!