Using commands in plug-ins in Sibelius Ultimate

Tutorials

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!

Further listening

On the Scoring Notes podcast, David MacDonald and Philip Rothman talk about updates to Dorico and Sibelius and have some fun along the way, with Dorico’s support for M1 Apple Silicon Macs, and Sibelius’s refreshed Command Search bar and new scripting features. Listen now:

Scoring Notes
Scoring Notes
Getting down and nerdy with Dorico and Sibelius updates
/

 

Comments

  1. Jane Frasier

    I created an Execute_Command and it worked fine. Then I clicked on New Plugin and got the spinning circle and it never stopped and I had to Force Quit Sibelius. Is there something I missed?

  2. Bob Zawalicvh

    I have never had a problem with doing it. New Plugin will have to create a new subfolder, if it does not already exist, in your user plugins folder and write to that folder. There may be a permissions issue on the folder. You could try going to File>Plug-Ins>Edit Plugins and click on New. Give the plugin any name (I like Delete_Me for something like this), and for the category, say Execute_Commands.

    Assuming that succeeds, look for Delete_Me in the list of plugins and choose Edit. If the plugin comes up in the editor, that means you have created the Execute_Commands folder if it was not already there and have written to it. Which is good.

    If that fails, then the problem is not the Execute_Commands plugin’s. If it succeeds but New Plugin is still failing, I don’t really have a good answer for you. New Plugin just writes a text file to that folder and usually it works as long as one is able to write into that folder.

    Just FWIW, this is really not the best location for tech support questions. I suggest using either the Sibelius Tech Support Forum or one of the Facebook Sibelius forums for that kind of question.

    I hope this works, though!

  3. Jane Frasier

    Thanks so much. It worked. Your articles are so useful. I wish you could just sit next to me and help me as I work on a score.

    I will check the forum next time when I need help.

    Jane

    1. Philip Rothman

      The closest thing we can offer to Bob sitting next to you is our recent podcast interview with him, which is well worth a listen: Plugged in with Bob Zawalich

Leave a Comment

Your email address will not be published. Required fields are marked *