Command Macros, Command Plug-ins, and cmdutils for Sibelius

Command Macros in Sibelius are sequences of commands that can be run by the Execute Commands or Run Command Macro plug-ins. You can get an overview of these plug-ins in this Scoring Notes post. You can create either of these in Execute Commands by adding commands to the Command List. Once in the Command List you can reorder the sequence of commands, and add, delete, or edit the commands.

You can use Execute Command List to run the sequence of commands to try it out. You can use Export List to save the sequence to a text file, to act as a macro. You can also use New Plugin to generate and install a plug-in made up of those commands.

How cmdutils came to be

I spent some time trying to create some useful macros using only commands or calls to plug-ins, and I was often stymied by finding that something I wanted to do could be accomplished in a ManuScript plug-in but not as a sequence of commands. I also kept finding that certain Sibelius commands did not work in plug-ins.

I starting writing some helper plug-ins, but I realized I would need a lot of them, and it would be awkward managing all those plug-ins. So instead I wrote a plug-in library, a kind of mega-plug-in of routines that could be treated the same as commands by Execute Commands. This library is called cmdutils.plg.

If you install it, its commands will be added to several categories in Execute Commands, and they can then be used to create Command Macros or Command Plug-ins, or the routines can be called by ManuScript (“normal”) plug-ins.

Like the Sibelius Commands, these cmdutils commands act on the current selection of the active score.

If you install cmdutils and Execute Commands, you can see and trace the command in each category by selecting the category names in the Category List and clicking the Trace▲ button.

A full listing and description of each command can be found in the document The cmdutils library in Execute Commands.

I would like to take you on a brief-ish tour of the commands in the cmdutils categories, and give an overview of the kinds of things these commands will enable you to do without having to go directly into ManuScript code.

Add Object and “Add and Select” Commands

These add Lines, Text, or Symbols to the current selection. Normal Add commands leave the selection unchanged, while the AddSelect commands select only the added object when the command ends.

In this example, I started with a single note selected, but after each Add command, I added a Select next object command, which effectively moved me to the next note before adding the object.

The first thing I noticed is the importance of the original selection. If I made a passage selection instead of a single note selection, or had no selection at all, I would get very different results. In the example below, I actually ran out of notes and 2 pieces of text were unintentionally added to the same note. I really need to undo the results, add more notes, and run the plug-in again.

You need to keep an eye on the selection and the first and last bars, and the top and bottom staves in the score, because using those can give undesired results with any macros.

Here are the Add commands I used:

Add_Line_Box_cu() Add_Line_Bracket_Vertical_Left_cu() Add_Line_Bracket_Vertical_Right_cu()

These work better than when you add these from the Sibelius Line menu: the Box line is staff height and the length of the selection, and the brackets are staff height point the right way!

Add_Line_Hairpin_Crescendo_cu() Add_StaffSymbol_cu(Choral divide arrow) Add_SystemSymbol_cu(Coda)

This is a system symbol so it goes above the top staff

Add_Text_Dynamics_cu(mf)

This includes the Bold Italic format automatically

Add_Text_Expression_cu(pizz) Add_Text_Technique_cu(legato)

Add commands need a way to specify which object to add. The Add Line and Add Text commands have variants where the type is included in the name, such as Add_Line_Box_cu().

Some commands take a parameter in parentheses.

For the Add Symbol commands, you need to specify a symbol name or index, such as Add_StaffSymbol_cu(Choral divide arrow). The Add Text commands typically tell you the text style in the command name, but let you specify the actual text to be inserted in the parameter, as in Add_Text_Dynamics_cu(mf).

The command Add_Line_cu(line.staff.arrow.black.right) can be used for creating lines that do not have custom commands for a line style. For that command you need to include the line style name or style id as a parameter. The placeholder command includes the line style id for an Arrow line.

To add Text with a text style that is not included in one of the available commands, you need to run two commands. The first specifies the Text Style to use, the second specifies the actual text:

TextStyleDefaultForCommands_cu(text.system.page_aligned.title)
Add_Text_cu(\$Title\)

In Execute Commands lists, commands that need a parameter are given a placeholder parameter, so you know when you will need to have a parameter. You can add such commands to the Command List, and then use Edit Command to edit the parameter as needed.

cmdutils.plg contains lower-level (“_Full”) routines that let you specify styles and values for all the Add commands. These are not available in Execute Commands, but you can access them with ManuScript code in a plug-in.

Here is another sample macro. This one creates text objects containing wildcards for Title, Subtitle, Composer and Lyricist text styles, and then brings up the Score Info block of the Ribbon File tab, so you can enter the text you want. This is intended for when you have no text objects in the score for these fields; it will not delete existing text.

// Add Wildcards Title Subtitle Composer Lyricist // by Bob Zawalich - concept by Ilkay Bora Oder // Add 4 text objects using wildcards then bring up Score Info to fill in the text // // This will make a system selection in the first bar of the score GoToFirstBar_cu() TextStyleDefaultForCommands_cu(text.system.page_aligned.title) Add_Text_cu(\$Title\) TextStyleDefaultForCommands_cu(text.system.page_aligned.subtitle) Add_Text_cu(\$Subtitle\) TextStyleDefaultForCommands_cu(text.system.page_aligned.composer) Add_Text_cu(\$Composer\) TextStyleDefaultForCommands_cu(text.system.page_aligned.lyricist) Add_Text_cu(\$Lyricist\) goto_selection_start MessageBox_cu(Please fill in the Score Info fields for the title, subtitle, composer, and lyricist, then click the Ribbon Home tab.) score_info

You can copy this code and paste it into a text editor. Save the file, using a “.dat” extension, in the Execute_Commands folder of your default Scores folder. You can then run Execute Commands or Run Command Macro, and run the macro.

More details are available in the document Tutorial-Execute Commands cmdutils-Adding Text Lines and Symbols to a score.

Add lntervals Commands

These add specific intervals above or below each selected note or chord. These commands call into the Add Interval plug-in (version 01.18.00 or later), which must be separately installed, and which provides a greater selection of intervals than Sibelius itself does (Sibelius commands currently can only add diatonic intervals, for one thing).

The command names tell you the type of interval to add, and the parameters are numbers, where 1 is a unison, 2 a second, 3 a third, and so forth, including octaves for number greater than 7.

AddInterval_Down_Augmented_cu(5) AddInterval_Down_Diatonic_cu(2) AddInterval_Down_Diminished_cu(5) AddInterval_Down_DoubleAugmented_cu(2) AddInterval_Down_DoubleDiminished_cu(2) AddInterval_Down_Major_cu(3) AddInterval_Down_Minor_cu(3) AddInterval_Down_Perfect_cu(8) AddInterval_Down_Semitones_cu(1)

AddInterval_Up_Augmented_cu(5) AddInterval_Up_Diatonic_cu(2) AddInterval_Up_Diminished_cu(5) AddInterval_Up_DoubleAugmented_cu(4) AddInterval_Up_DoubleDiminished_cu(4) AddInterval_Up_Major_cu(3) AddInterval_Up_Minor_cu(3) AddInterval_Up_Perfect_cu(8) AddInterval_Up_Semitones_cu(1)

Transpose Intervals Commands

These transpose any selected notes or chords by the specified interval. They call into the Transpose By Interval plug-in (version 01.10.00 or later).

TransposeInterval_Down_Augmented_cu(5) TransposeInterval_Down_Diatonic_cu(2) TransposeInterval_Down_Diminished_cu(5) TransposeInterval_Down_DoubleAugmented_cu(4) TransposeInterval_Down_DoubleDiminished_cu(4) TransposeInterval_Down_Major_cu(3) TransposeInterval_Down_Minor_cu(3) TransposeInterval_Down_Perfect_cu(8)

TransposeInterval_Up_Augmented_cu(5) TransposeInterval_Up_Diatonic_cu(2) TransposeInterval_Up_Diminished_cu(5) TransposeInterval_Up_DoubleAugmented_cu(4) TransposeInterval_Up_DoubleDiminished_cu(4) TransposeInterval_Up_Major_cu(3) TransposeInterval_Up_Minor_cu(3) TransposeInterval_Up_Perfect_cu(8)

To move selected notes up or down an octave you can use TransposeInterval_Up_Perfect_cu(8) or TransposeInterval_Down_Perfect_cu(8).

Command Selection Commands

It was clear to me that the ability to manipulate the selection was a key requirement to being able to write successful macros.

This is a large group, which could be subdivided into subgroups which could be called

Select All
Contract Selection
Expand Selection
Go To
Select First Or Last
Other (including SaveSelection and RestoreSelection).

You can find descriptions of all these in Tutorial-Execute Commands-Understanding and Controlling the Selection, and I will just touch on a few highlights here.

Perhaps the most important of the selection commands are these:

SaveSelection_cu ()

Saves the current selection so it can be restored later. This is most useful for a passage selection.

RestoreSelection_cu ()

Restores the most recent selection saved by SaveSelection_cu.

Running commands and plug-ins can change the selection and these allow you to save the selection before it changes, and restore it afterward, as in

SaveSelection_cu() AddInterval_Up_Major_cu(3) filter_top_or_single_note_for_deletion cut RestoreSelection_cu()

In this code, each selected note has a new note a major 3rd higher added to it by AddInterval. These notes are then filtered and cut, which copies them to the clipboard and deletes them from the score. The cut notes can later be pasted to another location. After the cut, nothing would be selected in the score.

Here is a screenshot showing that command running on some selected notes. It ended after the cut and Restore Selection calls, and sometime later a paste could done independently of the macro. In this case we may have gotten away with having no selection restored at the end, but I prefer to leave a usable selection where possible when a macro ends. In the example below, the final selection is the result of the Paste.

Go To Commands

The Go To block of the Selection Commands is interesting. You can go to the next or previous page, relative to the start of the current selection:

GoToNextPage_cu() GoToPreviousPage_cu()

Makes a system passage selection in first bar of the desired page, and brings the selection into view.

Like the Sibelius Go To Bar command, the Page and Bar commands will make a system selection of the target bar, or of the first bar on the page. If you don’t like the look of it, you can select just the first object in a bar or page by following the Go To with a Select_First_Object_cu(), which selects the first object in the selection. You could use an Esc_cu() command to get rid of the selection, but the Go To commands need a selection to start from, and if there is no selection they always go to bar 1 or page 1, so that would not work if you wanted to navigate around a bunch.

Here are the rest of the Go To Commands:

GoToFirstScoreObject_cu()

Selects the first staff object in the score (not a passage selection), and brings the selection into view.

GoToFirstScoreObject_SystemOK_cu()

Selects the first staff or system object in the score (not a passage selection), and brings the selection into view.

GoToLastScoreObject_cu()

Selects the last staff object in the score (not a passage selection), and brings the selection into view.

GoToLastScoreObject_SystemOK_cu()

Selects the last staff or system object in the score (not a passage selection), and brings the selection into view.

GoToFirstBar_cu() GoToLastBar_cu() GoToNextBar_cu() GoToPreviousBar_cu()

Makes a system passage selection in the desired bar, and brings the selection into view.

There are many more selection commands, and they are discussed in more detail in Tutorial-Execute Commands-Understanding and Controlling the Selection.

ExitIf Commands

Command Macros and Command Plug-ins often work well only if the selection is in a particular state before the macro is run. There are no built-in commands to check the status of the selection, so normally the only way to make such checks would be to create a Command Plug-in and edit the generated code in the Plug-in Editor.

The ExitIf commands in cmdutils were designed to allow a macro to state that there is a problem with the selection, and either exit after displaying a message, or provide a small set of other options. There is more that you could do if you turned the commands into a plug-in and wrote specific ManuScript code, but these give you some control without requiring ManuScript programming.

These commands will check for an empty or non-passage selection, or a passage selection that does not include specific staves or bars, or whether a plug-in is installed. If found, they will give a warning and either Exit, or ask if you want to continue, possibly after selecting the entire score.

In this example, the macro will really only work consistently well with a passage selection where all bars are fully selected, and it will not work correctly if the last bar in the score is in the selection, since there is nowhere to shift. I added several ExitIf statements to the start of the macro, and if any of their conditions for failure are met, they will put up an error message and end the macro.

// ShiftSelectionRightOneBar // by Bob Zawalich // Move All selected objects one bar to the right

ExitIfSelection_NotPassage_cu(A passage selection is required. This plugin will now exit.) ExitIfSelection_Needs_FullSelect_cu(The selection must have all bars fully selected. This plugin will now exit.) ExitIfSelection_Avoid_LastBar_cu(The selection may not include the last bar. This plugin will now exit.)

cut ShiftSelectionNextBar_cu() paste

You might not need to do this for a quick one-time macro, but if you will use it over time, or you want to give it away, some safeguards up-front will save trouble in the end.

See Tutorial-Execute Commands cmdutils-ExitIf routines.

Text Formatting Commands

These commands change the case of selected text objects:

SetTextCase_Lower_cu() SetTextCase_Upper_cu() SetTextCase_ToggleCase_cu() SetTextCase_WordInitialUpper_cu()

Look in Tutorial-Execute Commands cmdutils-Changing Text Case for more details, including how to work with accented and other international characters.

These commands let you apply text formatting to selected text object. Due to the implementation of these commands using wildcards, you can only add the properties, not take them away, unless you use SetTextFormat_Normal_cu() first, and then set each of the properties you want to set.

SetTextFormat_BoldItalic_cu() SetTextFormat_Bold_cu() SetTextFormat_Italic_cu() SetTextFormat_Normal_cu() SetTextFormat_Underlined_cu()

SetTextFormat_Position_Subscript_cu() SetTextFormat_Position_Superscript_cu()

You could make a plug-in out of each of these commands, and then assign a shortcut to each plug-in.

You can find more detail in Tutorial-Execute Commands cmdutils-Changing Text Formatting.

Horizontal (X) and Vertical (Y) Offset Commands

SetXOffsets_Left_Absolute_cu (xOffsetInSpaces) SetXOffsets_Left_Relative_cu (xOffsetInSpaces) SetXOffsets_Right_Absolute_cu (xOffsetInSpaces) SetXOffsets_Right_Relative_cu (xOffsetInSpaces)

SetYOffsets_Down_Absolute_cu (yOffsetInSpaces) SetYOffsets_Down_Relative_cu (yOffsetInSpaces) SetYOffsets_Up_Absolute_cu (yOffsetInSpaces) SetYOffsets_Up_Relative_cu (yOffsetInSpaces)

These are similar to what the X and Y offsets in the Inspector do, or the arguments to the X Y Offset plug-in. They shift selected objects left, right, up and down. When Lines are selected, both ends of the lines will be shifted by the same amount. In this example I use SetXOffsets_Right_Relative_cu and SetYOffsets_Down_Relative_cu.

Mute/Unmute Commands

MuteSelectedNotes_cu () UnMuteSelectedNotes_cu ()

These mute or unmute selected notes by setting all Play On Pass passes on or off. You need to keep track of what you have muted, though. Coloring them might be a useful marker (using ApplyNamedColor_cu, perhaps).

“Other” Commands

There are more in this category, but these seem particularly useful.

Esc_cu

A synonym for Execute(“cancel_stop_selectnone”); It cancels a selection, among other things.

RunPluginHideDialog_cu (strPluginMenuName)

Runs the named plug-in, and requests it to not show its dialog
Only plugins that have been updated to support this feature will hide the dialog
Unsupported plug-ins will be run as usual.

If is often useful to run a plug-in with no dialog, though you need to be careful to check that the options that would appear when the dialog appears are the ones you want to use when the dialog does not appear.

The separate plug-in Run Plugin Hide Dialog can be used for this purpose. It uses cmdutils routines to do its work.

See Tutorial-Execute Commands-Run Plugin Hide Dialog for more details.

SplitBarRestsAtBeat_cu(2.0)

Splits selected bar rests at the specific beat position (beat size depends on the time signature). Split at beat1 to convert a bar reset into one or more normal rests. This will ignore hidden staves but not staves excluded from a passage selection with Ctrl/Command+click.

SplitBarRestsForPassage_cu()

Splits bar rests enclosed by a partial-bar passage selection so that any portions of the bar rests in the first or last selected bar that are out of the selection will be split off as “normal” rests. This will ignore hidden staves but not staves excluded from a passage selection with Ctrl/Command+click.

The need for these came up when extending a partial bar passage selection into a bar with no notes, especially if it became the only bar selected, but it will work for any bar rests. You can split them so there are normal rests at the start and end of a passage selection, or split them so a normal rest will appear at the specified beat.

ApplyNamedColor_cu(colorName) ApplyNamedColor_List_cu()

Applies color to selected objects.
colorName can only be one of these color names: Black, Blue, Brown, Dark blue, Dark cyan, Dark green, Dark magenta, Dark salmon, Gray, Green, Indigo, Light blue, Light green, Light slate gray, Medium blue, Medium green, Olive, Orange, Orange red, Pink, Purple, Red, Tan, Violet, Yellow, or White.
The spelling of the colors names must be exact matches, including case.
To remove coloring, set the color to Black.
The “List” version displays a list of colors so you do not need to know exactly how to spell the color name.
The plugin Apply Named Color (version 01.22.00 or later) must be installed to use this command.

RunPluginEntry_cu(Valid parameters string)

This routine lets a Command Macro or Command Plug-in call an appropriately designed plugin so that it runs the plugin with specific dialog settings without needing to show the plug-in dialog.
Currently the plugins that support this are Filter Notes By Duration, Filter Notes By Position, Filter Notes By Beat, and Flip Selected Notes. (See more about Flip Selected Notes in this post.)
This feature allows people to expand what is available to Command Macros by writing plug-ins that can be called using RunPluginEntry_cu.
The plug-ins that support this feature all have a Trace macro button that generates the appropriate command line for the current dialog settings. You can copy the traced command line, and then paste it into a Command Macro by using the Add new command button in Execute Commands.
Here is an example of the dialog for Filter Notes By Duration, and the command line written to the plug-in Trace window.

This was a lot to cover, and it really only scratches the surface.

The reference manual for these commands is The cmdutils library in Execute Commands, and I will hope it will answer most of your questions.

Good luck with your macros and plug-ins!