ManuScript Language Guide

for Sibelius Ultimate

Legal Notices
© 2025 Avid Technology, Inc., (“Avid”), all rights reserved. This guide may not be duplicated in whole or in part without the written consent of Avid.

For a current and complete list of Avid trademarks visit: [Link]

Bonjour, the Bonjour logo, and the Bonjour symbol are trademarks of Apple Computer, Inc.

Thunderbolt and the Thunderbolt logo are trademarks of Intel Corporation in the U.S. and/or other countries.

This product may be protected by one or more U.S. and non-U.S. patents. Details are available at [Link]

Product features, specifications, system requirements, and availability are subject to change without notice.

ManuScript Language Guide for Sibelius Ultimate • Created 4/4/2025 • REV A

2
 Contents

Contents
Contents iii
1 Introduction xiii
Rationale xiii

Technical Support xiv

System Requirements and Compatibility Information xiv

Conventions Used in Sibelius Documentation xiv

Resources xiv

Account Activation xiv

Product Registration xv

Product Downloads xv

Support and Downloads xv

Get Started Fast xv

Training and Education xv

Products and Developers xv

2 Sibelius ManuScript Language Tutorial xvi

Edit Plug-ins xvi

A Simple Plug-in xvi

Three Types of Information xviii

Editing the Code xx

Where Plug-ins are Stored xx

Line Breaks and Comments xx

Variables xxi

Converting Between Numbers, Text, and Objects xxi

Loops xxii

“for” and “while” xxii

The if statement xxii

Arithmetic xxiii

Objects xxiv

Objects in Action xxiv

iii
 Contents

Representation of a Score xxv

The System Staff xxvi

Representation of Notes, Rests, Chords, and Other Musical Items xxvi

The “for each” Loop xxvii

Indirection, Sparse Arrays, and User Properties xxix

Indirection xxix

Sparse Arrays xxix

User Properties xxx

Dictionary xxxi

Using User Properties as Global Variables xxxii

Watch Out for Recursive Cycles! xxxiii

Other Things to Look Out For xxxiii

Dialog Editor xxxiii

Showing a Dialog in a Plug-In xxxiii

Creating or Editing a Dialog xxxiii

Dialog Properties xxxiv

Laying Out Controls xxxiv

Undo and Redo xxxv

Testing the Dialog xxxv

Saving Changes xxxv

Set Creation Order xxxvi

Control Properties xxxvi

Combo Boxes and List Boxes xxxviii

Radio Buttons xxxviii

Static Text xxxviii

Buttons xxxviii

Debugging Plug-ins xxxix

Undo xxxix

Plug-in Trace Window xxxix

Checking the Validity of Objects xxxix

Stopping the Plug-in xl

iv
 Contents

Storing and Retrieving Preferences xl

How Does it Work? xl

Initializing the Database xl

Accessing Data xli

Commands for Local Variables xlii

Miscellaneous xliii

Basic Example xliii

3 Reference xlv
Syntax xlv

Expressions xlvii

Operators xlix

Condition Operators xlix

Arithmetic xlix

4 Object Reference l
Hierarchy of Objects l

All Objects l

Methods l

User Properties liii

Accessibility liii

Methods liii

Variables liii

AnnotationItem liii

Methods liii

Variables liii

Bar liii

Methods liii

Variables lix

Barline lx

Methods lxi

Variables lxi

BarObject lxi

v
 Contents

Methods lxi

Variables lxii

Deleting Multiple Objects from a Bar lxiv

BarRest lxiv

Methods lxiv

Variables lxv

Bracket lxv

Methods lxv

Variables lxv

Barlines lxv

Methods lxv

Variables lxvi

Brackets and Braces lxvi

Methods lxvi

Variables lxvi

Clef lxvi

Methods lxvi

Variables lxvi

Comment lxvii

Methods lxvii

Variables lxvii

ComponentList lxvii

Methods lxvii

Variables lxviii

Component lxviii

Methods lxviii

Variables lxviii

DateTime lxviii

Methods lxviii

Variables lxviii

Dictionary lxix

vi
 Contents

Methods lxix

Variables lxx

Converting Old-Style Hash Tables to Dictionaries lxx

DocumentSetup lxx

Methods lxx

Variables lxx

DynamicPartCollection lxxii

Methods lxxii

Variables lxxiii

DynamicPart lxxiii

Methods lxxiii

Variables lxxiii

EngravingRules lxxiii

Methods lxxiv

Variables lxxiv

File lxxvii

Methods lxxvii

Variables lxxvii

Folder lxxviii

Methods lxxviii

Variables lxxviii

GuitarFrame lxxviii

Methods lxxviii

Variables lxxx

GuitarScaleDiagram lxxxii

Methods lxxxii

Variables lxxxii

HitPointList lxxxiii

Methods lxxxiii

Variables lxxxiii

HitPoint lxxxiii

vii
 Contents

Methods lxxxiii

Variables lxxxiii

InstrumentChange lxxxiii

Methods lxxxiv

Variables lxxxiv

InstrumentTypeList lxxxiv

Methods lxxxiv

Variables lxxxv

InstrumentType lxxxv

Methods lxxxv

Variables lxxxv

KeySignature lxxxvi

Methods lxxxvii

Variables lxxxvii

Line lxxxvii

Methods lxxxvii

Variables lxxxvii

LyricItem lxxxvii

Methods lxxxvii

Variables lxxxviii

NoteRest lxxxviii

Methods lxxxviii

Variables lxxxix

Note xcii

Methods xcii

Variables xcii

PageNumberChange xcv

Methods xcv

Variables xcv

PluginList xcvi

Variables xcvi

viii
 Contents

Plugin xcvi

Methods xcvi

Variables xcvi

RehearsalMark xcvii

Methods xcvii

Variables xcvii

Score xcvii

Methods xcvii

Variables ciii

Selection cvi

Methods cvi

Variables cviii

Copying Multiple Selections from One Bar to Another cix

Sibelius cx

Methods cx

Variables cxvii

SoundInfo cxx

Methods cxx

Variables cxx

SparseArray cxxi

Methods cxxi

Variables cxxii

Converting Old-style Arrays to New Sparse Arrays cxxii

SpecialBarline cxxii

Methods cxxii

Variables cxxii

Staff cxxii

Methods cxxii

Variables cxxiv

Syllabifier cxxvi

Methods cxxvi

ix
 Contents

Variables cxxvii

SymbolItem and SystemSymbolItem cxxvii

Methods cxxvii

Variables cxxviii

SystemObjectPositions cxxviii

Methods cxxviii

Variables cxxviii

SystemStaff, Staff, Selection, Bar and, all BarObject-derived Objects cxxviii

Variables cxxviii

SystemStaff cxxix

Methods cxxix

Variables cxxix

Text and SystemTextItem cxxix

Methods cxxix

Variables cxxix

TimeSignature cxxx

Methods cxxx

Variables cxxx

TreeNode cxxxi

Methods cxxxi

Variables cxxxi

Tuplet cxxxi

Methods cxxxi

Variables cxxxii

Utils cxxxii

Methods cxxxii

VersionHistory cxxxvii

Methods cxxxvii

Variables cxxxvii

Version cxxxvii

Methods cxxxviii

x
 Contents

Variables cxxxviii

VersionComment cxxxviii

Methods cxxxviii

Variables cxxxviii

5 Command IDs cxxxix

6 Sibelius Connect clxxvii
User Interface clxxvii

Websocket Connection clxxvii

Initial Handshake clxxvii

Commands clxxviii

ManuScript Plug-ins clxxviii

7 Global Constants clxxx

Truth Values clxxx

Measurements clxxx

Positions and Durations clxxx

Style Names clxxxi

Bar Number Formats clxxxi

Text Styles clxxxi

Line Styles clxxxiii

Clef Styles clxxxvii

Instrument Types clxxxvii

Beam Options ccv

Bracket Types ccv

Breaks ccv

Accidentals ccvi

Note Style Names ccvi

MuteMode Constants ccvii

Articulations ccvii

SyllableTypes for LyricItems ccvii

Accidental Styles ccviii

Time Signature Strings ccviii

xi
 Contents

Symbols ccviii

Special Page Break Types ccx

Interval Types ccx

InMultirest Values ccx

Page Number Visibility Values ccx

Page Number Format Values ccxi

Special Barlines ccxi

Bar Rest Type Values ccxi

GuitarScaleDiagram Type Values ccxi

FeatheredBeamType Values ccxii

Units Values ccxii

Orientation Values ccxii

PageSize Values ccxiii

MarginType Values ccxiii

StaffScaleFactor Values ccxiii

Tuplets ccxiii

SingleTremolos ccxiv

DoubleTremolo Values ccxiv

BarNumberFrequencyCategory Values ccxiv

Instrument Name Values ccxiv

Types of Objects in a Bar ccxiv

Interpreter Options ccxv

Index 217

xii
 1 Introduction

1 Introduction
ManuScript is a simple, music-based programming language used to write plug-ins for Sibelius Ultimate.
ManuScript is based on Simkin, an embedded scripting language developed by Simon Whiteside, and has
been extended by him and the rest of the Sibelius team ever since. (Simkin is a spooky pet name for Simon
sometimes found in Victorian novels.) For more information on Simkin, and additional help on the language
and syntax, visit the Simkin website at [Link].

g Throughout this guide, “Sibelius” refers to Sibelius Ultimate for the sake of readability.
Rationale
Providing a plug-in language for Sibelius Ultimate addresses several different issues:
l Music notation is complex and infinitely extensible, so some users sometimes want to add to a music
notation program to expand its possibilities with these new extensions.
l It is useful to allow frequently repeated operations (for example, opening a MIDI file and saving it as a
score) to be automated, using a system of scripts or macros.
Certain more complex techniques used in composing or arranging music can be partly automated, but
there are too many to include as standard features in Sibelius.

There were several conditions that we wanted to meet in deciding what language to use:
l The language had to be simple, as we want normal users (not just seasoned programmers) to be able
to use it.
l We wanted plug-ins to be usable on any computer, as the use of computers running both Windows
and macOS is widespread in the music world.
l We wanted the tools to program in the language to be supplied with Sibelius.
l We wanted musical concepts (pitch, notes, bars) to be easily expressed in the language.
l We wanted programs to be able to talk to Sibelius easily (to insert and retrieve information from
scores).
l We wanted simple dialog boxes and other user interface elements to be easily programmed.
C/C++, the world’s “standard” programming language(s), were unsuitable as they are not easy for the non-
specialist to use, they would need a separate compiler, and you would have to recompile for each different
platform you wanted to support (and thus create multiple versions of each plug-in).

The language Java was more promising as it is relatively simple and can run on any platform without
recompilation. However, we would still need to supply a compiler for people to use, and we could not
express musical concepts in Java as directly as we could with a new language.

So we decided to create our own language that is interpreted so it can run on different platforms,
integrated into Sibelius without any need for separate tools, and can be extended with new musical
concepts at any time.

The ManuScript language that resulted is very simple. The syntax and many of the concepts will be familiar
to programmers of C/C++ or Java. Built into the language are musical concepts (Score, Staff, Bar, Clef,
NoteRest) that are instantly comprehensible.

xiii
 1 Introduction

Technical Support
Since the ManuScript language is more the province of our programmers than our technical support team
(who are not, in the main, programmers), we can’t provide detailed technical help on it, any more than
Oracle will help you with Java programming. This document and the sample plug-ins should give you a
good idea of how to do some simple programming fairly quickly.

Developer Community

There is a growing community of plug-in developers working with ManuScript, and they can be an
invaluable source of help when writing new plug-ins. For more information, visit:
[Link]

System Requirements and Compatibility Information

Avid can only assure compatibility and provide support for hardware and software it has tested and
approved.

For complete system requirements and a list of qualified computers, operating systems, hard drives, and
third-party devices, visit:

[Link]/compatibility

Conventions Used in Sibelius Documentation

Sibelius documentation uses the following conventions to indicate menu choices, keyboard commands, and
mouse commands:

Convention Action

File > Save Choose Save from the File tab

Control+N Hold down the Control key and press the N key
Control-click Hold down the Control key and click the mouse button
Right-click Click with the right mouse button

The names of Commands, Options, and Settings that appear on-screen are in a different font.

The following symbols are used to highlight important information:

g User Tips are helpful hints for getting the most from Sibelius.
c Important Notices include information that could affect data or the performance of Sibelius.
b Shortcuts show you useful keyboard or mouse shortcuts.
n Cross References point to related sections in this guide and other Avid documentation.
Resources
The Avid website ([Link]) is your best online source for information to help you get the most out of
Sibelius.

Account Activation
Create an Avid Master Account at:

xiv
 1 Introduction

t [Link]
Product Registration
Register your purchase online at:
t [Link]/register
Product Downloads
Download software, updates, documentation, and other resources from:
t [Link]/products
Support and Downloads
Contact Avid Customer Success (technical support), download software updates and the latest online
manuals, browse the Compatibility documents for system requirements, search the online Knowledge Base
or join the worldwide Avid user community on the User Conference.
t [Link]/support
Get Started Fast
Visit the Get Started Fast with Sibelius YouTube channel.
t Get Started Fast with Sibelius
Training and Education
Study on your own using courses available online, find out how you can learn in a classroom setting at an
Avid-certified training center, or view video tutorials and webinars.
t [Link]/sibelius/learn-and-support
Products and Developers
Learn about Avid products, download demo software, or learn about our Development Partners and their
plug-ins, applications, and hardware.
t [Link]/products

xv
 2 Sibelius ManuScript Language Tutorial

2 Sibelius ManuScript Language Tutorial

Edit Plug-ins
A Simple Plug-in
Let’s start a simple plug-in. You are assumed to have some basic experience of programming (such as
BASIC or C), so you’re already familiar with ideas like variables, loops, and so on.

To create a new Sibelius plug-in:

1. Start Sibelius and open or create a new score.

2. Choose File > Plug-ins > Edit Plug-ins.

The following dialog appears:

xvi
 2 Sibelius ManuScript Language Tutorial

3. Click New.
Sibelius displays the following window that allows you to enter the internal name of your plug-in
(used as the plug-in’s filename). This name appears on the menu and the name of the category in
which the plug-in should appear, which determines which ribbon tab it appears on.

4. Type Test as the internal name, Test plug-in as the menu name and Tests as the category
name, then click OK.
You’ll see Test (user copy) added to the list in the Edit Plug-ins dialog under a new Tests
branch of the tree view.
5. Click Close.
This shows the folder in which the plug-in is located (Tests, which Sibelius has created for you), the
filename of the plug-in (minus the standard .plg file extension), and (user copy) tells you that
this plug-in is located in your user application data folder, not the Sibelius program folder or
application package itself.
If you look in the Home > Plug-ins gallery again you’ll see a Tests category, with a Test plug-in
underneath it.
6. Choose Home > Plug-ins > Tests > Test and the plug-in runs.

xvii
 2 Sibelius ManuScript Language Tutorial

You may first be prompted that you cannot undo plug-ins, in which case click Yes to continue (and
you may wish to switch on the Don’t say this again option so that you’re not bothered by this
warning in future.) What does our new Test plug-in do? It just pops up a dialog which says Test
(whenever you start a new plug-in, Sibelius automatically generates in a one-line program to do this).
You’ll also notice a window appear with a button that says Stop Plug-in, which appears whenever
you run any plug-in, and which can be useful if you need to get out of a plug-in you’re working on
that is (say) trapped in an infinite loop.
7. Click OK on the dialog and the plug-in stops.

Three Types of Information

Let’s look at what’s in the plug-in so far. Choose File > Plug-ins > Edit Plug-ins again, then
select Tests/TesT (user copy) from the list and click Edit (or simply double-click the plug-in’s name
to edit it). You’ll see a dialog showing the three types of information that can make up a plug-in:

Methods

Similar to procedures, functions, or routines in some other languages.

Dialogs

The layout of any special dialogs you design for your plug-in.

Data

Variables whose value is remembered between running the plug-in. You can only store strings in these
variables, so they’re useful for things like user-visible strings that can be displayed when the plug-in runs.
For a more sophisticated approach to global variables, ManuScript provides custom user properties for all
objects—see "Edit Plug-ins" on page xvi.

Example: Test plug-in

Methods
The actual program consists of the methods. As you can see, plug-ins normally have at least two methods,
which are created automatically for you when you create a new plug-in:

xviii
 2 Sibelius ManuScript Language Tutorial

Initialize

This method is called automatically whenever you start up Sibelius. Normally it does nothing more than add
the name of the plug-in to the Plug-ins menu, although if you look at some of the supplied plug-ins you’ll
notice that it’s sometimes also used to set default values for data variables.

Sibelius 2020.9 (and later) adds new functionality that lets ManuScript treat a single character as a string,
rather than a number, and provides support for quarter-tone accidentals and pitches. Include the following
code example with the Initialize() method to enable this functionality:
if ([Link] > 20200600) {
SetInterpreterOption(TreatSingleCharacterAsString);
SetInterpreterOption(SupportHalfSemitonePitchValues);
}

Plug-ins that use this new functionality are not supported with earlier versions of Sibelius.

Run

This is called when you run the plug-in, you’ll be startled to hear (it’s like main() in C/C++ and Java). In
other words, when you choose Home > Plug-ins > Tests > Test, the plug-in’s Run method is called.
If you write any other methods, you have to call them from the Run method—otherwise how can they ever
do anything?

Click on Run, then click Edit (or you can just double-click Run to edit it). This shows a dialog where you
can edit the Run method:

In the top field you can edit the name; in the next field you can edit the parameters (the variables where
values passed to the method are stored); and below is the code itself:

[Link]("Test");

This calls a method MessageBox which pops up the dialog box that says Test when you run the plug-in.
Notice that the method name is followed by a list of parameters in parentheses. In this case there’s only one
parameter: because it is a string (that is, text) it is in double quotes. Notice also that the statement ends in a
semicolon, as in C/C++ and Java. If you forget to type a semicolon, you’ll get an error when the plug-in
runs.

What is the role of the word Sibelius in [Link]? In fact it’s a variable representing the
Sibelius program; the statement is telling Sibelius to pop up the message box (C++ and Java programmers
will recognize that this variable refers to an “object”). If this hurts your brain, we’ll go into it later.

xix
 2 Sibelius ManuScript Language Tutorial

Editing the Code

Now try amending the code slightly. You can edit the code just like in a word processor, using the mouse
and arrow keys, and you can also use Command+X/C/V (Mac) or Control+X/C/V (Windows) for cut,
copy and paste respectively. If you right-click, you get a menu with these basic editing operations on them
as well.

Change the code to this:

x = 1;
x = x + 1;
[Link]("1 + 1 = " & x);

You can check this makes sense (or, at least, some kind of sense) by clicking the Check Syntax button. If
there are any blatant mistakes (such as missing semicolons) you are notified where they are.

Then close the dialogs by clicking OK, OK again then Close. Run your amended plug-in from the Plug-ins
menu and a message box with the answer 1 + 1 = 2 should appear.

How does it work? The first two lines should be obvious. The last line uses & to stick two strings together. You
cannot use + as this works only for numbers.

One pitfall: try changing the second line to:

x += 1;

Then click Check syntax. You will encounter an error: this syntax (and the syntax x++) is allowed in various
languages but not in ManuScript. You have to do x = x+1;.

Where Plug-ins are Stored

Plug-ins supplied with Sibelius are stored in folders buried deep within the Sibelius program folder on
Windows, and inside the application package (or “bundle”) on Mac. It is not intended that end users should
add extra plug-ins to these locations themselves, as we have provided a per-user location for plug-ins to be
installed instead. When you create a new plug-in or edit an existing one, the new or modified plug-in is
saved into the per-user location (rather than modifying or adding to the plug-ins in the program folder or
bundle):
l On Windows, additional plug-ins are stored at
C:\Users\<username>\AppData\Roaming\Avid\Sibelius\Plugins.
l On Mac, additional plug-ins are stored in subfolders at
/Users/<username>/Library/Application Support/Avid/Sibelius/Plugins.
This is worth knowing if you want to give a plug-in to someone else. The plug-ins appear in subfolders which
correspond to the categories in which they appear in the various Plug-ins galleries. The filename of the
plug-in itself is the plug-in’s internal name plus the .plg extension, such as [Link].

(Sibelius includes an automatic plug-in installer, which you can access using File > Plug-ins >
Install Plug-ins. This makes it easy to download and install plug-ins from the Avid website.)

Line Breaks and Comments

As with C/C++ and Java, you can put new lines wherever you like (except in the middle of words), as long as
you remember to put a semicolon after every statement. You can put several statements on one line, or put
one statement on several lines.

You can add comments to your program, again like C/C++ and Java. Anything after // is ignored to the
end of the line. Anything between /* and */ is ignored, whether just part of a line or several lines:

xx
 2 Sibelius ManuScript Language Tutorial

// comment lasts to the end of the line

/* you can put
several lines of comments here
*/

For instance:
[Link]("Hi!"); // print the active score

or:
Sibelius /* this contains the application */ .MessageBox("Hi!");

Variables
x in the Test plug-in is a variable. In ManuScript a variable can be any sequence of letters, digits or _
(underscore), as long as it does not start with a digit.

A variable can contain an integer (whole number), a floating point number, a string (text) or an object (such
as a note)—more about objects in a moment. Unlike most languages, in ManuScript a variable can contain
any type of data—you do not have to declare what type you want. Thus you can store a number in a
variable, then store some text instead, then an object.

Try this:
x = 56; x = x+1;
[Link](x); // prints '57' in a dialog box
x = "now this is text"; // the number it held is lost
[Link](x); // prints 'now this is text' in a dialog
x = [Link]; // now it contains a score
[Link](x); // prints nothing in a dialog

Variables that are declared within a ManuScript method are local to that method; in other words, they
cannot be used by other methods in the same plug-in. Global Data variables defined using the plug-in
editor can be accessed by all methods in the plug-in, and their values are preserved over successive uses of
the plug-in.

A quick aside about strings in ManuScript is in order at this point. Like many programming languages,
ManuScript strings uses the back-slash \ as an “escape character” to represent certain special things. To
include a single quote character in your strings, use \', and to include a new line you should use \n.
Because of this, to include the backslash itself in a ManuScript string one has to write \\.

Converting Between Numbers, Text, and Objects

Notice that the method MessageBox is expecting to be sent some text to display. If you give it a number
instead (as in the first call to MessageBox above) the number is converted to text. If you give it an object
(such as a score), no text is produced.

Similarly, if a calculation is expecting a number but is given some text, the text is converted to a number:
x = 1 + "1"; // the + means numbers are expected
[Link](x); // displays '2'

If the text doesn’t start with a number (or if the variable contains an object instead of text), it is treated as 0:
x = 1 + "fred";
[Link](x); // displays ‘1’

xxi
 2 Sibelius ManuScript Language Tutorial

Loops
“for” and “while”
ManuScript has a while loop which repeatedly executes a block of code until a certain expression becomes
True. Create a new plug-in called Potato. This is going to amuse one and all by writing the words of the
well-known song “1 potato, 2 potato, 3 potato, 4.” Type in the following for the Run method of the new
plug-in:
x = 1;
while (x<5)
{
text = x & " potato,";
[Link](text);
x = x+1;
}

Run it. It should display “1 potato,” “2 potato,” “3 potato,” “4 potato,” which is a start, though annoyingly
you have to click OK after each message.

The while statement is followed by a condition in ( ) parentheses, then a block of statements in { }

braces (you don’t need a semicolon after the final } brace). While the condition is true, the block is
executed. Unlike some other languages, the braces are compulsory (you can’t omit them if they only
contain one statement). Moreover, each block must contain at least one statement.

In this example you can see that we are testing the value of x at the start of the loop, and increasing the
value at the end. This common construct could be expressed more concisely in ManuScript by using a for
loop. The above example could also be written as follows:
for x = 1 to 5
{
text = x & " potato,";
[Link](text);
}

Here, the variable x is stepped from the first value (1) up to the end value (5), stopping one step before the
final value. By default, the “step” used is 1, but we could have used (say) 2 by using the syntax for x = 1
to 5 step 2, which would then print only “1 potato” and “3 potato”!

Notice the use of & to add strings. Because a string is expected on either side, the value of x is turned into a
string.

Notice also we’ve used the Tab key to indent the statements inside the loop. This is a good habit to get into
as it makes the structure clearer. If you have loops inside loops you should indent the inner loops even more.

The if statement
Now we can add an if statement so that the last phrase is just “4,” not “4 potato”:
x = 1;
while (x<5)
{
if(x=4)
{
text = x & ".";
}
else
{
text = x & " potato,";
}

xxii
 2 Sibelius ManuScript Language Tutorial

[Link](text);
x = x+1;
}

The rule for if takes the form if (condition) {statements}. You can also optionally add else
{statements}, which is executed if the condition is false. As with while, the parentheses and braces are
compulsory, though you can make the program shorter by putting braces on the same line as other
statements:
x = 1;
while (x<5)
{
if(x=4) {
text = x & ".";
} else {
text = x & " potato,";
}
[Link](text);
x = x+1;
}

The position of braces is entirely a matter of taste.

Now let’s make this plug-in really cool. We can build up the four messages in a variable called text, and
only display it at the end, saving valuable wear on your mouse button. We can also switch round the if and
else blocks to show off the use of not. Finally, we return to the for syntax we looked at earlier.
text = ""; // start with no text
for x = 1 to 5
{
if (not(x=4)) {
text = text & x & " potato, "; // add some text
} else {
text = text & x & "."; // add no. 4
}
}
[Link](text); // finally display it

Arithmetic
Here is a complete list of the available arithmetic operators in ManuScript:

a + b add
a – b subtract
a * b multiply
a / b divide
a % b remainder
–a negate
a) evaluate first

ManuScript evaluates operators strictly from left-to-right, unlike many other languages; so 2+3*4
evaluates to 20, not 14 as you might expect. To get the answer 14, you’d have to write 2+(3*4).

ManuScript supports both integers and floating point numbers. Use at least one floating point value in any
arithmetic operation that might result in a floating point number, otherwise the result is rounded to the
nearest integer (unless you are using literal strings). For instance, when calculating division using only

xxiii
 2 Sibelius ManuScript Language Tutorial

integer values, the result is truncated; for example, the result of 3/2 is 1. However, using at least one
floating point value in the calculation results in a floating point number (this is true if any or all of the values
are a floating point number); for example, the result of 3.0/2 is 1.5.

Conversion from floating point numbers to integers can be achieved with the RoundUp(expr), RoundDown
(expr), and Round(expr) functions, which can be applied to any expression.

Objects
Now we come to the neatest aspect of object-oriented languages like ManuScript, C++ or Java, which sets
them apart from traditional languages like BASIC, Fortran and C. Variables in traditional languages can
hold only certain types of data: integers, floating point numbers, strings and so on. Each type of data has
particular operations you can do to it: numbers can be multiplied and divided, for instance; strings can be
added together, converted to and from numbers, searched for in other strings, and so on. But if your
program deals with more complex types of data, such as dates (which in principle you could compare using
=, < and >, convert to and from strings, and even subtract) you are left to fend for yourself.

Object-oriented languages can deal with more complex types of data directly. Thus in the ManuScript
language you can set a variable, let’s say thischord, to be a chord in your score, and (say) add more
notes to it:
[Link](60); // adds middle C (note no. 6
)
[Link](64); // adds E (note no. 64)

If this seems magic, it’s just analogous to the kind of things you can do to strings in BASIC, where there are
very special operations which apply to text only:
A$ = "1"
A$ = A$ + " potato, ": REM add strings
X = ASC(A$): REM get first letter code

In ManuScript you can set a variable to be a chord, a note in a chord, a bar, a staff or even a whole score,
and do things to it. Why would you possibly want to set a variable to be a whole score? So you can save it
or add an instrument to it for instance.

Objects in Action
We’ll have a look at how music is represented in ManuScript in a moment, but for a little taster, let’s plunge
straight in and adapt Potato to create a score:
x = 1;
text = ""; // start with no text
while (x<5)
{
if (not(x=4)) {
text = text & x & " potato, "; // add some text
} else {
text = text & x & "."; // add no. 4
}
x = x+1;
}
[Link](); // create a new score
newscore = [Link]; // put it in a variable
[Link]("Piano");
staff = [Link](1); // get top staff

xxiv
 2 Sibelius ManuScript Language Tutorial

bar = [Link](1); // get bar 1 of this staff

[Link](0,text,"Technique"); // use Technique text style

This creates a score with a Piano, and types our potato text in bar 1 as Technique text.

The code uses the period (.) several times, always in the form [Link] or
[Link](). This shows that the variable before the period has to contain an object.

If there’s a variable name after the period, we’re getting one of the object’s sub-variables (called “fields” or
“member variables” in some languages). For instance, if n is a variable containing a note, then [Link] is
a number representing its MIDI pitch (60 for middle C), and [Link] is a string describing its pitch (“C4” for
middle C). The variables available for each type of object are listed later.

If there’s a method name after the period (followed by () parentheses), one of the methods allowed for this
type of object is called. Typically a method called in this way either changes the object or returns a value.
For instance, if s is a variable containing a score, then [Link]("Flute") adds a flute
(changing the score), but [Link](1) returns a value, namely an object containing the first staff.

Let’s look at the new code in detail. There is a pre-defined variable called Sibelius, which contains an object
representing the Sibelius program itself. We’ve already seen the method [Link](). The
method call [Link]() tells Sibelius to create a new score. Now we want to do something to this
score, so we have to put it in a variable.

Fortunately, when you create a new score it becomes active (for example, its title bar highlights and any
other scores become inactive), so we can just ask Sibelius for the active score and put it in a variable:
newscore = [Link]

Then we can tell the score to create a Piano: [Link]("Piano"). But to add
some text to the score you have to understand how the layout is represented.

Representation of a Score
A score is treated as a hierarchy: each score contains 0 or more staves; each staff contains bars (though
every staff contains the same number of bars); and each bar contains “bar objects.” Clefs, text and chords
are all different types of bar objects.

To add a bar object (for example, an object which belongs to a bar), such as some text, to a score:

1. Specify which staff you want (and put it in a variable): staff = [Link](1).
2. Specify which bar in that staff you want (and put it in a variable): bar = [Link](1);
finally you tell the bar to add the text: [Link](0,text,"Technique").
3. Specify the name (or index number – see Text styles on page 141) of the text style to use (and it has to
be a staff text style, because we’re adding the text to a staff).
Notice that bars and staves are numbered from 1 upwards; in the case of bars, this is irrespective of any bar
number changes that are in the score, so the numbering is always unambiguous. In the case of staves, the
top staff is no.1, and all staves are counted, even if they’re hidden. Thus a particular staff has the same
number wherever it appears in the score.

The AddText method for bars is documented later, but the first parameter it takes is a rhythmic position in
the bar. Each note in a bar has a rhythmic position that indicates where it is (at the start, one quarter after
the start, and so on), but the same is true for all other objects in bars. This shows where the object is
attached to, which in the case of Technique text is also where the left hand side of the text goes. Thus to put
our text at the start of the bar, we used the value 0. To put the text a quarter note after the start of the bar,
use 256 (the units are 1024th notes, so a quarter is 256 units):

xxv
 2 Sibelius ManuScript Language Tutorial

[Link](256,text,"Technique");

To avoid having to use obscure numbers like 256 in your program, there are predefined variables
representing different note values (which are listed later), so you could write:
[Link](Quarter,text,"Technique");

or to be quaint you could use the British equivalent:

[Link](Crotchet,text,"Technique");

For a dotted quarter, instead of using 384 you can use another predefined variable:
[Link](DottedQuarter,text,"Technique");

or add two variables:

[Link](Quarter+Eighth,text,"Technique");

This is much clearer than using numbers.

The System Staff

As you know from using Sibelius, some objects don’t apply to a single staff but to all staves. These include
titles, tempo text, rehearsal marks and special barlines; you can tell they apply to all staves because (for
instance) they get shown in all the instrumental parts.

All these objects are actually stored in a hidden staff, called the system staff. You can think of it as an
invisible staff which is always above the other staves in a system. The system staff is divided into bars in the
same way as the normal staves. So to add the title “Potato” to our score we’d need the following code in our
plug-in:
sys = [Link]; // system staff is a variable
bar = [Link](1);
[Link](0,"POTATO SONG","Subtitle");

As you can see, SystemStaff is a variable you can get directly from the score. Remember that you have to
use a system text style (here Subtitle is used) when putting text in a bar in the system staff. A staff text style
like Technique won’t work. Also, you have to specify a bar and position in the bar; this may seem slightly
superfluous for text centered on the page as titles are (though in reality even this kind of page-aligned text
is always attached to a bar), but for Tempo and Metronome mark text they are obviously required.

Representation of Notes, Rests, Chords, and Other Musical Items

Sibelius represents rests, notes and chords in a consistent way. A rest has no noteheads, a note has 1
notehead and a chord has 2 or more noteheads. This introduces an extra hierarchy: most of the squiggles
you see in a score are actually a special type of Bar object that can contain even smaller things (namely,
noteheads). There’s no overall name for something which can be a rest, note or chord, so we’ve invented the
pretty name NoteRest. A NoteRest with 0, 1 or 2 noteheads is what you normally call a rest, a note or a
chord, respectively.

If n is a variable containing a NoteRest, there is a variable [Link] which contains the number of
notes, and [Link] which is the note-value in 1/256ths of a quarter. You can also get [Link] and
[Link] which contain the highest and lowest notes (assuming [Link] isn’t 0). If you set

xxvi
 2 Sibelius ManuScript Language Tutorial

lownote = [Link], you can then find out things about the lowest note, such as [Link] (a
number) and [Link] (a string). Complete details about all these methods and variables may be
found in "Reference" on page xlv

Other musical objects, such as clefs, lines, lyrics and key signatures have corresponding objects in
ManuScript, which again have various variables and methods available. For example, if you have a Line
variable ln, then [Link] gives the rhythmic position at which the line ends.

The “for each” Loop

It’s a common requirement for a loop to do some operation to every staff in a score, or every bar in a staff,
or every Bar object in a bar, or every note in a NoteRest. There are other more complex requirements which
are still common, such as doing an operation to every Bar object in a score in chronological order, or to
every Bar object in a multiple selection. ManuScript has a for each loop that can achieve each of these in a
single statement.

The simplest form of for each is like this:

thisscore = [Link];
for each s in thisscore // sets s to each staff in turn
{ // ...do something with s
}

Here, since thisscore is a variable containing a score, the variable s is set to be each staff in thisscore
in turn. This is because staves are the type of object at the next hierarchical level of objects (see "Hierarchy
of Objects" on page l).

For each staff in the score, the statements in {} braces are executed.

Score objects contain staves, as we have seen, but they can also contain a Selection object, for
example, if the user has selected a passage of music before running the plug-in. The Selection object is a
special case: it is never returned by a for each loop, because there is only a single Selection object; if
you use the Selection object in a for each loop, by default it will return Bar objects (not Staves, Bars or
anything else!).

Let’s take another example, this time for notes in a NoteRest:

noterest = [Link](1);
for each n in noterest // sets n to each note in turn
{
[Link]("Pitch is " & [Link]);
}

n is set to each note of the chord in turn, and its note name is displayed. This works because Notes are the
next object down the hierarchy after NoteRests. If the NoteRest is, in fact, a rest (rather than a note or
chord), the loop will never be executed—you don’t have to check this separately.

The same form of loop will get the bars from a staff or system staff, and the Bar objects from a bar. These
loops are often nested, so you can, for instance, get several bars from several staves.

This first form of the for each loop got a sequence of objects from an object in the next level of the hierarchy
of objects. The second form of the for each loop lets you skip levels of the hierarchy, by specifying what
type of object you want to get. This saves a lot of nested loops:
thisscore = [Link];
for each NoteRest n in thisscore
{
[Link](60); // add middle C
}

xxvii
 2 Sibelius ManuScript Language Tutorial

By specifying NoteRest after for each, Sibelius knows to produce each NoteRest in each bar in each staff in
the score; otherwise it would just produce each staff in the score, because a Staff object is the type of
object at the next hierarchical level of objects. The NoteRests are produced in a useful order, namely from
the top to the bottom staff, then from left to right through the bars. This is chronological order. If you want
a different order (say, all the NoteRests in the first bar in every staff, then all the NoteRests in the second
bar in every staff, and so on) you’ll have to use nested loops.

So here’s some useful code that doubles every note in the score in octaves:
score = [Link];
for each NoteRest chord in score
{
if(not([Link] = 0)) // ignore rests
{
note = [Link]; // add above the top note
[Link]([Link]+12); // 12 is no. of half-steps (semitones)
}
}

It could easily be amended to double in octaves only in certain bars or staves, only if the notes have a
certain pitch or duration, and so on.

This kind of loop is also very useful in conjunction with the user’s current selection. This selection can be
obtained from a variable containing a Score object as follows:
selection = [Link];

We can then test whether it’s a passage selection, and if so we can look at (say) all the bars in the selection
by means of a for each loop:
if ([Link])
{
for each Bar b in selection
{
// do something with this bar
…
}
}

Be aware that you can not add or remove items from bars during iterating. The example of adding notes to
chords above is fine because you are modifying an existing item (in this case a NoteRest), but it’s not safe to
add or remove entire items, and if you try to do so, your plug-in will abort with an error. However, it’s very
useful to add or remove items from bars, so you need to do that in a separate for loop, after first collecting
the items you want to operate on into a ManuScript array, something like this:
num = 0;
for each obj in selection
{
if (IsObject(obj))
{
n = "obj" & num;
@n = obj;
num = num + 1;
}
}
[Link]();
for i = 0 to num
{
n = "obj" & i;

xxviii
 2 Sibelius ManuScript Language Tutorial

obj = @n; // get an object from the pseudo array

[Link]();
}

The @n in this example is the array.

Indirection, Sparse Arrays, and User Properties

Indirection
If you put the @ character before a string variable name, then the value of the variable is used as the name
of a variable or method. For instance:
var="Name";
x = @var; // sets x to the contents of the variable Name
mymethod="Show";
@mymethod(); // calls the method Show

This has many advanced uses, though if taken to excess it can cause the brain to hurt. For instance, you
can use @ to simulate “unlimited” arrays. If name is a variable containing the string "x1", then @name is
equivalent to using the variable x1 directly. Thus:
i = 10;
name = "x" & i;
@name = 0;

sets variable x10 to 0. The last two lines are equivalent to x[i] = 0; in the C language. This has many
uses; however, you’ll also want to consider using the built-in arrays (and hash tables), which are
documented below.

Sparse Arrays
The method described above can be used to create “fake” arrays through indirection, though this is a little
fiddly. ManuScript also provides Javascript-style sparse arrays, which can store anything that can be
stored in a ManuScript variable, including references to objects. Like a variable, storing a reference to an
object in a sparse array preserves the lifetime of that object (because objects are reference counted), but
the underlying object in Sibelius may be invalid if (say) a Score is modified.

To create a sparse array in ManuScript, use the built-in method CreateSparseArray(a1,a2,a3,a4...an).

You can create an empty array simply by passing in no variables to the CreateSpareArray method.

Sparse arrays provide a read/write variable called Length that returns or sets the length of the array: when
you set Length to a number greater than the present size of the array, the array is padded with null values;
if you set Length to a number smaller than the present size of the array, any values beyond this number are
removed.

To push one or more values to the end of the array, use the method Push(a1, a2, ... an). To remove and
return the last element of an array, use the method Pop().

An example of how to use a sparse array:

array = CreateSparseArray(4,5,6);
array[10] = 19; // creates 11th element of array, intervening elements are null
[Link] = 20; // extends array to 20 elements, new elements are all null

Sparse arrays by their nature may not have values in every array element. To return a new sparse array
containing only the populated indices of the original sparse array (those that are not null), use the array’s
ValidIndices variable. For example, using the above sparse array:
array2 = [Link]; // will contain values 0, 1, 2, 10 and 19
return array[array2[0]]; // returns the first populated element of array

xxix
 2 Sibelius ManuScript Language Tutorial

You can compare two sparse arrays for equality, for example:
if (array = array2) {
// do something
}

To access the end of an array, it’s convenient to use negative indices; for example: array[-1] returns the
last element, array[-2] returns the penultimate element, and so on. It is not possible to access elements
before the start of the array, so, for example, if you do array[-100] on a six element array, array[0] is
returned.

Some things to remember when using sparse arrays:

l Sparse arrays use a zero-based index.
l Elements that have not been initialized are null, and do not cause an error when referenced.
l Assigning to an index beyond the current length increases the Length to one greater than the index is
assigned to.
l If an array contains references to objects, whether the arrays are equal or not depends on the
implementation of equality for those objects.

User Properties
All ManuScript objects other than those listed below, including objects created by Sibelius, can have user
properties attached to them, allowing for convenient storage of extra data, encapsulation of several items
of data within a single object, and returning more than one value from a method, among other things.

To create a new user property, use the following syntax:

object._property:property_name = value;

where object is the name of the object, property_name is the desired user property name, and value is
the value to be assigned to the new user property. User properties are read/write and can be accessed as
object.property_name.

To get a sparse array containing the names of all the user properties belonging to an object:
names = object._propertyNames;

Here is an example of creating a user property:

nr = [Link];
nr._property:original = true;
if ([Link] = true) {
// do something
}

Some things to remember when using user properties:

l If you attempt to get or set a user property that has not yet been created, your plug-in exits with a
run-time error.
l To check whether or not a user property has been created without causing a run-time error, use the
notation object._property:property_name, which is null if no matching user property has been
created yet.
l User properties cannot be created or accessed for normal data types (such as strings, integers, and
so on), the global Sibelius object, old-style ManuScript arrays created by CreateArray(), old-
style hashes created by CreateHash(), and null.

xxx
 2 Sibelius ManuScript Language Tutorial

l User properties that conflict with an existing property name cannot be accessed as
object.property_name (though they can be accessed using the ._property: notation).
l User properties belong to a particular ManuScript object and disappear when that object’s lifetime
ends. To stop an object dying, you can (for example) store it in a sparse array, but be aware that its
contents may become invalid if (say) the underlying score changes.

Dictionary
Dictionary is a programmer extensible object, simply allowing the use of user properties as above with
convenient construction. It also has methods allowing the use of arbitrarily named user properties, and can
also have methods in plug-ins attached to it allowing the creation of encapsulated user objects (for
example, objects with variables and methods attached to them).

To create a dictionary, use the built-in function CreateDictionary(name1, value1, name2, value2, ...
nameN, valueN). This creates a dictionary containing user properties called name1, name2, nameN with
values value1, value2, valueN respectively.

A dictionary can contain named data items (like a struct in languages like C++), or data that is indexed by
string, so that you can use strings to look items up within it.

The values in a dictionary can be accessed using square bracket notation, so you can use a dictionary like a
hash table. For example:
test = CreateDictionary("fruit",apple,"vegetable",potato);
test["fruit"] = banana;
test["meat"] = lamb;

You can even put other objects, such as sparse arrays, inside dictionaries. For example:
test2 = CreateDictionary("fruit",
CreateSparseArray(apple,banana,orange));

You can access the user properties within a dictionary using the ._property: notation. For example:
return test2._property:fruit;

which would return the array specified above. Even more direct, you can access user properties in a
dictionary as if they were variables or methods, like this:
[Link];

which would also return the array specified above. You can also return more than one value from any
ManuScript method using a dictionary, such as:
getChord()
value = CreateDictionary("a", aNote, "b", anotherNote);
return value;
//... in another method somewhere
chord = getChord();
trace(chord.a);
trace(chord.b);

which returns two values, a and b that you can access using chord.a and chord.b, for example.

You can compare two dictionaries for equality. For example:

if (test2 = test3) {
// do something }

Whether or not dictionaries containing objects evaluate as equal depends on the implementation of
equality for those objects.

xxxi
 2 Sibelius ManuScript Language Tutorial

If you’re comfortable with programming in general, you may find it useful to be able to add methods to
dictionaries, particularly if you are writing code designed to act as a library for other methods or plug-ins to
call. Writing code in this way provides a degree of encapsulation and can make it easy for client code to use
your library.

To add a method to a dictionary, call the dictionary’s SetMethod() method. For example:
pluginmethod "(obj,x,y) {
// a method that does something to obj
}"
test4 = CreateDictionary();
[Link]("doSomething",Self,"pluginmethod");
[Link](3,4);
// call pluginmethod within the current plug-in, passing in
// test4 (obj in the method above) and 3 (x in the method
// above) and 4 (y in the method above)

In the example above, doSomething is the name of the method belonging to the dictionary, Self tells the
plug-in that the method is defined in the same plug-in, and pluginmethod is the name of a method
elsewhere in the plug-in (shown at the top of the example).

To return a sparse array containing the names of the methods belonging to a dictionary, use the
dictionary’s GetMethodNames() method. You can also check the existence of a particular method using
the dictionary’s MethodExists() method. Use the dictionary’s CallMethod() method to call a specific
method, where the name of the method is the first parameter, and any parameters to be passed to the
specified method follow.

For example:
array = [Link](); // create sparse array containing method names
first_method_name = array[0]; // sets first_method_name to name of first method
methodfound = [Link]("doSomething"); // returns True in this case;
[Link]("doSomething",5,6);

Everything you put into a dictionary is a user property, so all of the methods outlined in User properties
above can be used on data in dictionaries too.

Using User Properties as Global Variables

You can store SparseArray and Dictionary objects, and indeed any other object, as user properties of
the Plugin object itself. In the example below, Self is the object that corresponds to the running plug-in,
and a user property globalData is assigned to the plug-in, containing a Dictionary:
Self._property:globalData = CreateDictionary(1,2,3,4);
// globalData and [Link] can be used interchangeably
trace(globalData);
trace([Link]);

User properties assigned to the plug-in are persistent between invocations. Take care to ensure that these
user properties are created before you attempt to use them, otherwise your plug-in aborts with a run-time
error. Using the _property:property_name syntax never causes run-time errors, but direct references to
property_name force a runtime error if property_name has not been created yet.

The example below shows how to test the existence of a specific user property, globalCounter, initialize it
to 0 if it is not found, then increment it by 1 every time the plug-in runs:
// Test the persistence of user properties
if (Self._property:globalCounter = null){
Self._property:globalCounter = 0;
}

xxxii
 2 Sibelius ManuScript Language Tutorial

globalCounter = globalCounter + 1;
// this number increases by one every time the plug-in is run
trace(globalCounter);
trace([Link]);

If you store a reference to a musical object in a user property that is assigned to the plug-in, there is an
increased danger of that reference becoming invalid due to the score being closed or edited, for example
Use the IsValid() method to validate such data before using it.

User properties of plug-ins are inaccessible (except by using the _property:property_name syntax) if
there is an existing global variable of the same name.

Watch Out for Recursive Cycles!

Be careful not to create recursive cycles using arrays, user properties and dictionaries. When you use, say,
an array in a dictionary, you are not creating a copy of the array or its values, but a reference to the
original array: dictionaries and arrays are objects, not values. As a result, you could write something where
an array contains a dictionary that itself refers to the original array: this leads to Sibelius quiting
unexpectedly.

Other Things to Look Out For

The Parallel 5ths and 8ves plug-in illustrates having several methods in a plug-in, which we haven’t needed
so far. The Proof-read plug-in illustrates that one plug-in can call another – it doesn’t do much itself except
call the CheckPizzicato, CheckSuspectClefs, CheckRepeats and CheckHarpPedaling plug-ins. Thus you
can build up meta-plug-ins that use libraries of others. Cool!

(You object-oriented programmers should be informed that this works because, of course, each plug-in is
an object with the same powers as the objects in a score, so each one can use the methods and variables of
the others.)

Dialog Editor
For more complicated plug-ins than the ones we’ve been looking at so far, it can be useful to prompt the
user for various settings and options. This may be achieved by using ManuScript’s simple built-in dialog
editor. Dialogs can be created in the same way as methods and data variables in the plug-in editor.

Showing a Dialog in a Plug-In

To show a dialog from a ManuScript method, we use the built-in call
[Link](dialogName, Self);

where dialogName is the name of the dialog we wish to show, and Self is a “special” variable referring to
this plug-in (telling Sibelius to whom the dialog belongs). Control is only returned to the method once the
dialog has been closed by the user.

Creating or Editing a Dialog

To create a new dialog, choose the Dialog radio button at the bottom of the window that lists methods,
data and dialogs, and click Add. To edit an existing dialog, select it from the Dialogs list box at the top
right-hand corner of the window, and click Edit.

The dialog form appears, along with a long thin “palette” of available controls, as follows:

xxxiii
 2 Sibelius ManuScript Language Tutorial

To create a new control, just drag and drop it from the palette onto the dialog.

Dialog Properties
With no controls selected, either double-click on a blank part of the dialog (or right-click, and then choose
Properties) to access the dialog’s Properties dialog, which allows you to specify:
l Name: the value of dialogName for the [Link]() method call (see Showing a
dialog in a plug-in above).
l Title: the name of the dialog as it appears in its title bar.
l Size: the Width and Height (measured in somewhat arbitrary dialog units); you can also set the size of
the dialog by resizing it directly when editing it.
l Position: the X and Y position that the dialog should open at by default.

Laying Out Controls

The dialog editor includes a number of simple options for producing a pleasing layout:
l To select a control, either click it or hit Tab to select the next control in the creation order (Shift-Tab
selects the previous control).
l To nudge a selected control, use the arrow keys.
l To align controls:
– Select them using Command-click (Mac) or Control-click (Windows), then use
Command+Left Arrow (Mac) or Control+Left Arrow (Windows) to align all of the
selected controls with the left-hand edge of the left-most control.
– Use Command+Up Arrow (Mac) or Control+Up Arrow (Windows) to align all of the selected
controls with the top edge of the top-most control.
l To space controls evenly:
– Select them using Command-click (Mac) or Control-click (Windows), then use
Command+Option+Option+Down Arrow (Mac) or Control+Alt+Shift+Down Arrow
(Windows) to space the controls evenly in the distance between the top edge of the top-most

xxxiv
 2 Sibelius ManuScript Language Tutorial

and the bottom edge of the bottom-most controls.

– Use Command+Option+Option+Left Arrow (Mac) or Control+Alt+Shift+Left Arrow
(Windows) to space the controls evenly in the distance between the left-hand edge of the left-
most and the right-hand edge of the right-most controls.
Once controls are spaced evenly, you can increase or decrease the space between them
proportionally by typing Command+Option+Option+Up, Down, Right, Left Arrow keys
(Mac) or Control+Alt+Shift+Up, Down, Right, Left Arrow keys (Windows) as
appropriate.
You can optionally display a grid to aid with alignment. Right-click on a blank part of the dialog and choose
Grid from the context menu to see a dialog with settings for the grid:

Switch on Show grid to show the grid in the editor. Choose between Dots or Lines, and specify the Opacity
of the grid display by adjusting the slider. Switch on Snap to grid to enable control snapping as you drag
them with the mouse. Although a control that you nudge with the keyboard does not snap to the grid, one
side of its selection outlines flash when it comes into alignment with the grid in either the horizontal or
vertical directions.

Undo and Redo

You can undo and redo everything you have done while editing a dialog using Command+Z (Mac) or
Control+Z (Windows) to undo and Command+Y (Mac) or Control+Y (Windows) to redo.

Testing the Dialog

To test the dialog within the editor, right-click a blank part of the dialog and choose Test from the context
menu, or type the shortcut Command+T (Mac) or Control+T (Windows). To finish testing and return to the
editor, press Esc or click any control whose properties are set to close the dialog (such as OK or Cancel, if
you have created one).

Saving Changes
To save the changes to the dialog, click the close button in the dialog’s title bar. If there are any unsaved
changes, Sibelius prompts you to save the changes.

xxxv
 2 Sibelius ManuScript Language Tutorial

Set Creation Order

If you have done any programming in other languages that allow you to edit dialogs, you may be familiar
with the concept of tab order, which refers to the order in which controls are given the focus when the user
repeatedly hits the Tab key to cycle through them. ManuScript has a similar concept called creation order,
so named because the order in which the controls in a dialog are created affects not only the tab order but
also some other subtle things (including radio button grouping—see "Radio Buttons" on page xxxviii).

To set the creation order of controls in your plug-in’s dialog, right-click on a blank part of the dialog and
choose Set Creation Order from the context menu. A special display appears overlaid on the controls
in your dialog, like this:

Plug-in dialog with creation order overlay

To set the creation order, simply click on each control in order. If you make a mistake, press Command
(Mac) or Control (Windows) and click on the last control whose order is correct to restart the sequence from
that point, then release Command (Mac) or Control (Windows) and resume clicking on the remaining
controls. Once you’re done, press Esc to finish editing the creation order.

Control Properties
Every control that you create also has a Properties dialog, which can be accessed by double-clicking a
selected control, by right-clicking and choosing Properties from the context menu, or by pressing
Command+Return (Mac) or Control+Return (Windows). The dialog for a radio button control, for example, is
shown below:

xxxvi
 2 Sibelius ManuScript Language Tutorial

With a control selected, the properties window varies depending on the type of the control, but most of the
options are common to all controls, and these are as follows:
l ID: an internal string that identifies the control; Sibelius generates this for you automatically, but you
can change if you like.
l Text: the text appearing in the control.
l Position (X, Y): where the control appears in the dialog, in coordinates relative to the top left-hand
corner.
l Size (width, height): the size of the control.
l Variable storing control’s value: the ManuScript Data variable that corresponds to the value of this
control when the plug-in is run.
l Method called when clicked: the ManuScript method that should be called whenever the user clicks
on this control (leave blank if you don’t need to know about users clicking on the control).
l Click closes dialog: select this option if you want the dialog to be closed whenever the user clicks on
this control. The additional options Returning True / False specify the value that the
[Link] method should return when the window is closed in this way.
l Give this control focus: select this option if the “input focus” should be given to this control when the
dialog is opened (such as whether this should be the control to which the user’s keyboard applies
when the dialog is opened). This is mainly useful for editable text controls.
Other options vary according to the type of control selected.

xxxvii
 2 Sibelius ManuScript Language Tutorial

Combo Boxes and List Boxes

Combo boxes and list boxes have an additional property; you can set a variable from which the control’s
list of values should be taken. Like the value storing the control’s current value, this should be a global Data
variable. However, in this instance they have a rather special format, to specify a list of strings rather than
simply a single string. Look at the variable _ComboItems in Add String Fingering for an example – it looks
like this:
_ComboItems
{
"1"
"2"
"3"
"4"
"1 and 3"
"2 and 4"
}

List boxes have one further property, which is to determine whether they should allow a single selection or
multiple selections. The return value from a combo box or a single-selection list box is a single string. If a list
box is set to allow multiple selections, the selection is returned as an array of strings.

Radio Buttons
Radio buttons also have an additional property that allows one to specify groups of radio buttons in plug-in
dialogs. When the user clicks on a radio button in a group, only the other radio buttons belonging to that
groups are deselected; any others in the dialog are left as they are. This is extremely useful for more
complicated dialogs.

To specify a radio group, pick one control from each group that represents the first button of the group,
and for these controls ensure that the checkbox Start a new radio group is selected in the control’s
Properties dialog. Then set the creation order of the controls (see "Set Creation Order" on page xxxvi). A
radio button group is defined as being all the radio buttons created between two buttons that have the
Start a new radio group flag set (or between one of these buttons and the end of the dialog). So to make the
radio groups work properly, ensure that each group is created sequentially in order, with the button at the
start of the group created first, and then all the rest of the radios in that group. To finish, click the Set
Creation Order menu item again to deactivate this mode.

Static Text
Static text controls additionally allow you to determine whether the text should be aligned to the Left
(useful for explanatory text) or to the Right (useful for text associated with a specific control to its right,
such as an edit control, checkbox or combo box).

Buttons
In most plug-in dialogs, you want the OK button to be the default button for the dialog, such that if the user
presses Return or Enter on their keyboard, the dialog is confirmed, and closes. Likewise, you want the
Cancel button to respond to the user hitting Esc on their keyboard, closing the dialog without making any
changes.

For OK buttons, or other buttons that should confirm the dialog, switch on the Default button for dialog
checkbox in the button’s Properties dialog. Each dialog should only have one default button. You will also
normally set Click closes dialog, returning to True. Depending on the other controls in your dialog,
you may additionally want to check Give this control focus; if you have one or more edit controls in
the dialog, you should probably set Give this control focus on the first of those controls instead.

Cancel buttons, by contrast, should normally only have Click closes dialog, returning set to False.

xxxviii
 2 Sibelius ManuScript Language Tutorial

Debugging Plug-ins
When developing any computer program, it’s all too easy to introduce minor (and not so minor!) mistakes,
or bugs. ManuScript performs its own internal error checking at all times, and you’ll find that if you try to
access a non-existent method or variable on an object, or make a syntax error, or attempt to add or remove
bars or items from bars while iterating over them, the plug-in throws an error and opens the plug-in editor
window at the line that generated the error.

As ManuScript is a simple, lightweight system, there is no special purpose debugger, but there are a handful
of tools provided to help you debug your plug-ins.

Undo
One good technique for finding problems in your plug-ins is to set Sibelius’s undo buffer to a very small size,
or to disable it altogether (by dragging the slider on the Other page of File > Preferences to its
leftmost position). In the unlikely event that ManuScript does not throw an error when you perform an illegal
operation (such as adding or deleting an object while iterating over a bar), reducing the undo buffer to its
smallest possible size exposes the problem right away – though be warned, the result of such a problem
may be that Sibelius quits unexpectedly.

Plug-in Trace Window

The trace window can be shown by choosing Plug-ins > Plug-in Trace Window. A special
ManuScript command, trace(string), prints the specified string in the trace window. This is useful to keep
an eye on what your plug-in is doing at particular points. These commands can then be removed when
you’ve finished debugging. Another useful feature of the trace window is function call tracing. When this is
turned on, the log shows which functions are being called by plug-ins.

One potential pitfall with the trace(string)approach to debugging is that the built-in hash table and
array objects discussed earlier aren’t strings, and so can’t be output to the trace window. To avoid this
problem, both of these objects have a corresponding method called WriteToString(), which returns a
string representing the whole structure of the array or hash at that point. So we could trace the current
value of an array variable as follows:
trace("array variable = " & [Link]());

Checking the Validity of Objects

One of the common problems that you might encounter when writing complex plug-ins is that the object
you are trying to operate on is no longer valid (it has already been deleted). You can enable error checking
– either for all objects, or for individual objects – that causes your plug-in to throw an error if an object is no
longer valid.

To enable error checking, use the ManuScript command ValidationChecking(enable[, object1[,

object2]...]), and set the Boolean parameter enable to true. If enable is the only parameter, validation
checking is enabled for all types of objects, and all plug-ins. If you supply one or more object parameters
(such as Tuplet, Score, BarObject, and so on), only those objects are checked, and only in the currently
running plug-in. You should ensure ValidationChecking is set to false before you give your plug-ins to
anybody else to use.

You can also use the special method IsValid() to determine whether an object is valid: it returns false if
the object in question no longer exists. GetValidationError(object) returns an empty string if there is
no error, or returns a string if an error has occurred, use trace(GetValidationError(score)); to
trace any validation error returned by a Score object to the trace window.

xxxix
 2 Sibelius ManuScript Language Tutorial

Stopping the Plug-in

If you want to force your plug-in to stop on a particular error condition, use StopPlugin([message]),
which stops your plug-in, display the optional message in an alert box, and open the plug-in editor at the
line of code reached.

You can also use ExitPlugin(), which exits the plug-in cleanly without dropping into the plug-in editor.

Storing and Retrieving Preferences

In Sibelius 4 or later, you can use [Link], contributed by Hans-Christoph Wirth, to store and
retrieve user-set preferences for your plug-ins.

How Does it Work?

[Link] stores its data in a text file in the user’s application data folder. Strings are accessed as
associated pairs of a key (the name of the string) and a value (the contents of the string). The value can also
be an array of strings, if required.

Initializing the Database

errorcode = Open(pluginname,featureset);

Open the library and lock for exclusive access by the calling plug-in. The calling plug-in is identified with
the string pluginname. It is recommended that this string equals the unique Sibelius menu name of the
calling plug-in.

Parameter featureset is the version of the feature set requested by the calling plug-in. The version of the
feature set is currently 020000. Each library release shows in its initial dialog a list of supported feature
sets. The call to Open() fails and shows a user message if you request an unsupported feature set. If you
should want to prevent this user information (and probably setup your own information dialog), use
CheckFeatureSet() first.

After Open() the scope is undefined, such that you can access only global variables until the first call to
SwitchScope().

Return value: Open() returns zero or a positive value on success. A negative result indicates that there was
a fatal error and the database has not been opened.
l -2 other error
l -1 library does not support requested feature set
l 0 no common preferences database found
l 1 no preferences found for current plug-in
l 2 preferences for current plug-in loaded
In case of errors (for example, if the database file is unreadable), Open() offers the user an option to
recover from the error condition. Only if this also fails, an error code is returned to the calling plug-in.
l errorcode = CheckFeatureSet(featureset);
Check silently if the library supports the requested feature set.
Return value: CheckFeatureSet() returns zero or a positive value on success. A negative value
indicates that the requested feature set is not supported by this version.
l errorcode = Close();

xl
 2 Sibelius ManuScript Language Tutorial

Release the exclusive access lock to the library. If there were any changes since the last call to Open
() or Write(), dump the data changes back to disk (probably creating a new score, if there was
none present).
Return value: Close() returns zero or a positive value on success. A negative result indicates that
there was a fatal error and the database has not been written.
l errorcode = CloseWithoutWrite();
Release the exclusive access lock to the library, discarding any changes performed since last call to
Open() or Write().
Return value: CloseWithoutWrite() returns zero or a positive value on success. A negative result
indicates that there was a fatal error, namely that the database was not open at the moment.
l errorcode = Write(dirty);
Force writing the data back to disk immediately. Keep library locked and open. If dirty equals 0, the
write only takes place if the data has been changed. If dirty is positive, the common preferences
score is unconditionally forced to be rewritten from scratch.
Return value: Write() returns zero or a positive value on success. A negative result indicates that
there was a fatal error and the database has not been written.

Accessing Data
l index = SetKey(keyname, value);
Store a string value under the name keyname in the database, overwriting any previously stored keys
or arrays of the same keyname.
If keyname has been declared as a local key, the key is stored within the current scope and does not
affect similar keys in other scopes. It is an error to call SetKey() for local keys if the scope is
undefined.
Return value: SetKey() returns zero or a positive value on success, and a negative value upon error.
l errorcode = SetArray(keyname, array, size);
Store an array of strings under the name keyname in the database, overwriting any previously stored
keys or arrays of the same keyname. size specifies the number of elements in the array. A size of -1 is
replaced with the natural size of the array, for example,, [Link].
If keyname has been declared as a local key, the array is stored within the current scope and does
not affect similar keys in other scopes. It is an error to call SetArray() for local keys if the scope is
undefined.
Return value: SetArray() returns zero or a positive value on success, and a negative value upon
error.
l value = GetKey(keyname);
Retrieve the value of key keyname from the database. It is an error to call GetKey() on an identifier
which had been stored the last time using SetArray(). For local keys, the value is retrieved from the
current scope which must not be undefined.
Return value: The value of the key or [Link] if no key of that name found.
l size = GetArray(keyname, myarray);
Retrieve the string array stored under name keyname from the database. It is an error to call
GetArray() on an identifier which has been stored the last time by SetKey(). For local arrays, the
value is retrieved from the current scope which must not be undefined.
You must ensure before the call that myarray is of ManuScript’s array type (for example,, created
with CreateArray()).

xli
 2 Sibelius ManuScript Language Tutorial

Return value: size equals the number of retrieved elements or -1 if the array was not found. Note that
size might be smaller than [Link], because there is currently no way to reduce the
size of an already defined array.
l size = GetListOfIds(myarray);
Fill the array myarray with a list of all known Ids in the current score (or in the global scope, if
undefined). Before you call this method, ensure that myarray is of ManuScript’s array type (for
example, created with CreateArray()).
Return value: returns the size of the list, which might be smaller than the natural size of the array,
[Link].
l index = UnsetId(keyname);
Erase the contents stored with an identifier (there is no distinction between keys and arrays here). If
the key is declared as local, it is erased only from the local scope which must not be undefined.
Return value: The return value is zero or positive if the key has been unset. A negative return value
means that a key of that name has not been found (which is not an error condition).
l RemoveId(keyname);
Erase all contents stored in the database with an identifier (there is no distinction between keys and
arrays here). If the key is declared as local, it is erased from all local scopes.
Return value: The return value is always zero.
l RemoveAllIds();
Erase everything related to the current plug-in.
Return value: the return value is always zero.

Commands for Local Variables

l errorcode = DeclareIdAsLocal(keyname);
Declare an identifier as a local key. Subsequent calls to Set... and Get... operations are
performed in the scope which is set at that time. The local state is stored in the database and can be
undone by a call to DeclareIdAsGlobal or RemoveId.
Return value: Non-negative on success, negative on error.
l size = GetListOfLocalIds(myarray);
Fill the array myarray with a list of all Ids declared as local. Before you call this method, ensure that
myarray is of ManuScript’s array type (for example, created with CreateArray()).
Return value: Returns the size of the list, which might be smaller than the natural size of the array,
[Link].
l errorcode = SwitchScope(scopename);
Select scope scopename. If scope scopename has never been selected before, it is newly created and
initialized with no local variables. Subsequent Set... and Get... operations for keys declared as
local are performed in scope scopename, while access to global keys is still possible.
The call SwitchScope("") selects the undefined scope which does not allow access of any local
variables.
Return value: Non-negative on success, negative on error.
l errorcode = RemoveScope();
Erase all local keys and arrays from the current scope and delete the current scope from the list of
known scopes. It is an error to call RemoveScope() if the current scope is undefined. After the call,
the database remains in the undefined scope.

xlii
 2 Sibelius ManuScript Language Tutorial

l errorcode = RemoveAllScopes();
Erase all local keys and arrays from all scopes and delete all scopes from the list of known scopes.
After the call, the database remains in the undefined scope. Note that this call does retain the
information which Ids are local (see DeclareIdAsLocal()).
Return value: Non-negative on success.
l string = GetCurrentScope();
Retrieve the name of the currently active scope, or the empty string if the database is in undefined
scope.
Return value: Returns a string.
l size = GetListOfScopes(myarray);
Fill the array myarray with a list of all known scope names. You must ensure before the call that
myarray is of ManuScript’s array type (for example,, created with CreateArray()).
Return value: Returns the size of the list, which might be smaller than the natural size of the array,
[Link].

Miscellaneous
l Trace(tracelevel);
Select level of tracing for the library. Useful levels are: 0 for no trace, 10 for sparse trace, 20 for
medium trace, 30 for full trace.
This command can also be run when the library is not open, to specify the tracing level for the Open
() call itself.
l TraceData();
Writes a full dump of the data stored currently in ThisData array to the trace window. This is the full
data belonging to the current plug-in. TraceData() always traces the data, regardless of the
current trace level selected.
l filename = GetFilename();
Return the full filename of the preferences database (including path).
l Editor();
Invoke the interactive plug-in editor. This method must not be called while the database is open.
Direct calls to Editor() from plug-ins are deprecated.

Basic Example
Suppose you have a plug-in called myplugin and would like to save some dialog settings in a preferences
file such that these settings
are persistent over several Sibelius sessions and computer reboots. Your dialog may contain two
checkboxes and a list box. Let
DialogDontAskAgain and DialogSpeedMode be the global variables holding the status of the
checkboxes, respectively, and let DialogJobList hold the contents of the list box item.

The work with the database can be reduced to four steps:

1. Open the database and retrieve initial data. At begin of your plug-in, right at top of your Run()
method, you have to add some code to initialize the database. You probably also want to initialize
your global keys based on the information currently stored in the database. See below for a detailed
example. (Depending on your program, you might have to define prefOpen as a global variable in
order to prevent trying to access an unopened database in future.)

xliii
 2 Sibelius ManuScript Language Tutorial

// At first define hard coded plug-in defaults, in case that the plug-in
// is called for the first time. If anything else fails, these defaults
// will be in effect.
DialogDontAskAgain = 0;
DialogSpeedMode = 0;
DialogJobList = CreateArray();
DialogJobList[0] = "first job";
DialogJobList[1] = "second job";
// Attempt to open the database
prefOpen = [Link]( "myplugin", "020000" );
if( prefOpen >= 0 ) {
// Database successfully opened. So we can try to load the
// information stored last time.
// It’s a good idea to work with a private version scheme, in order
// to avoid problems in the future when the plug-in is developed
// further, but the database still contains the old keys. In our
// example, we propose that the above mentioned keys are present
// if "version" key is present and has a value of "1".
version = [Link]( "Version" );
switch( version ) {
case( "1" ) {
// Now overwrite the above set defaults with the information stored
// in the database.
DialogDontAskAgain = [Link]( "DontAskAgain" );
DialogSpeedMode = [Link]( "SpeedMode" );
[Link]( "JobList", DialogJobList );
}
default {
// handle other versions/unset version gracefully here ...
}
}
}

2. Work with the data. After the initialization step, you can and should work with global variables
DialogDontAskAgain, DialogSpeedMode, and DialogJobList as you are used to: read from
them to base control flow decisions on their setting, write to them (mostly from within your own
dialogs) to set new user preferences.
3. Write data back to the database. To make any changes persistent, you must tell the database the
new values to be written to the hard disk. See below for a detailed example. According to taste, you
can execute these lines each time the settings are changed, or only once, at the end of your plug-in.
if( prefOpen >= 0 ) {
[Link]( "Version", "1" );
[Link]( "DontAskAgain", DialogDontAskAgain );
[Link]( "SpeedMode", DialogSpeedMode );
[Link]( "JobList", DialogJobList, -1 );
}

4. Close the database. In any case, you must release the lock to the library on exit of your plug-in. This
writes data actually back to disk, and enables other plug-ins to access the shared database later. To
do this, use:
[Link]();

xliv
 3 Reference

3 Reference
Syntax
The following table includes an informal run-down of the syntax of ManuScript.

A method consists of a list of statements of the following kinds:

Block {statements }

For example:

{
a = 4;
}

While while { expression } block

For example:

while (i < 3) {
[Link](i);
i = i + 1;
}

Switch switch (test-expression) {

case (case-expression-1) block
[ case (case-expression-2) block ]
…
[ default block ]

The switch statement consists of a “test” expression, multiple case statements and an
optional default statement. If the value of test-expression matches one of the case-
expressions, then the statement block following the matching case statement is executed. If
none of the case statements match, then the statement block following the default statement
is executed.

For example:

switch ([Link]) {
case (DoubleSharp) {
[Link]("Double sharp");
}
case (DoubleFlat) {
[Link]("Double flat");
}
default {
[Link]("No double");
}
}

if else if (expression) block [ else block ]

For example:

if (found) {
[Link](found);
} else {
[Link]();

xlv
 3 Reference

for each for each variable in expression block

This sets variable to each of the sub-objects within the object given by the expression.

Normally there is only one type of sub-object that the object can contain. For instance, a Note
Rest (such as a chord) can only contain Note objects. However, if more than one type of sub-
object is possible you can specify the type:

for each Type variable in expression

block

For example:

for each NoteRest n in thisstaff {

[Link](60); // add middle C
}

for for variable = value to value [ step value ]

block

The variable is stepped from the first value up to or down to the end value by the step value. It
stops one step before the final value.

So, for example:

for x=1 to [Link] {

...
}

works correctly.
assignment variable = expression;

For example:

value = value + 1;

or

[Link] = expression;

For example:

[Link]=True;

method call [Link](comma-separated expressions);

For example:

[Link](0,"Mozart","[Link]");

self method call identifier(comma-separated expressions);

Calls a method in this plug-in, for example:

CheckIntervals();

return return expression;

Returns a value from a plug-in method, given by the expression. If a method doesn’t contain a
return statement, then a “null” value is returned (either the number zero, an empty string, or
the null object described below).

xlvi
 3 Reference

Expressions
Here are the operators, literals, and other beasts you’re allowed in expressions.

Self This is a keyword referring to the plug-in owning the method. You can pass yourself to other
methods, for example:

[Link](Self);

null This is a literal object meaning “nothing.”

Identifier This is the name of a variable or method (letters, digits or underscore, not starting with a digit)
you can precede the identifier with @ to provide indirection; the identifier is then taken to be a
string variable whose value is used as the name of a variable or method.
member [Link]
variable
This accesses a variable in another object.
integer For example:

1, 100, -1
floating For example:
point
number 1.5, 3.15, -1.8

string Text in double quotes, for example: “some text.” For strings that are rendered by Sibelius as
part of the score, for example, the contents of some text object, there is a small but useful
formatting language allowing one to specify how the text should appear. These “styled strings”
contain commands to control the text style. All commands start and end with a backslash (\) The
full list of available styling commands is as follows:

\n\ New paragraph

\N\ New line
\B\ Bold on
\b\ Bold off
\I\ Italic on
\i\ Italic off
\U\ Underline on
\u\ Underline off
\fArial Black\ Font change to Arial Black (for example)
\[Link]\
Character style change to Music text (for example)
\f_\ Font change to text style’s default font, including removing any
active character styles
\s123\ Size change to 123 (units are 1/32nds of a space, not points)
\v\ Vertical scale in percent
\h\ Horizontal scale in percent
\t\ Tracking (absolute) in 1/32nds of a space
\p\ Baseline adjustment: use normal, subscript, or superscript

xlvii
 3 Reference

\$keyword\ Substitutes a string from the Score Info dialog (see below)

A consequence of this syntax is that backslashes themselves are represented by \\, to avoid
conflicting with the above commands.

The substitution command \$keyword\ supports the following keywords: Title, Composer,
Arranger, Lyricist, MoreInfo, Artist, Copyright, Publisher and PartName.

Each of these correspond to a field in the File > Score Info dialog.
not not expression

Logically negates an expression, for example:

not (x=0)

and expression and expression

Logical and, for example:

FoxFound and BadgerFound

or expression or expression

Logical or, for example:

FoxFound or BadgerFound

equality expression = expression

Equality test, for example:

Name="Clock"

subtract expression - expression

Subtraction, for example:

12-1

add expression + expression

Addition, for example:

12+1

minus -expression

Inversion, for example:

-1

concatenati expression & expression

on
Add two strings, for example:

Name = "Fred" & "Bloggs"; // ‘Fred Bloggs’

You can’t use + as this would attempt to add two numbers, and sometimes succeed (!). For
instance:

x = "2" + "2"; // same as x = 4

subexpressio (expression)
n
For grouping expressions and enforcing precedence, for example:

(4+1)*5

xlviii
 3 Reference

method call [Link](comma-separated expressions);

For example:

x = [Link]();

self method Identifier(comma-separated expressions);

call
Calls a method in this plug-in, for example:

x = CountBananas();

Operators
Condition Operators
You can put any expressions in parentheses after an if or while statement, but typically they contain
conditions such as = and <. The available conditions are very simple:

a = b equals (for numbers, text or objects)

a < b less than (for numbers)
a > b greater than (for numbers)
c and d both are true
c or d either are true
not c inverts a condition, for example: not(x=4)
<= less than or equal to
>= greater than or equal to
!= not equal to

Use = to compare for equality, not == as found in C/C++ and Java.

Arithmetic
a + b add
a - b subtract
a * b multiply
a / b divide
a % b remainder
-a negate
(a) evaluate first

ManuScript evaluates expressions from left to right, so that 2+3*4 is 20, not 14 as you might expect. To
avoid problems with evaluation order, use parentheses to make the order of evaluation explicit. To get the
answer 14, you’d have to write 2+(3*4).

ManuScript also now supports floating point numbers, so whereas in previous versions 3/2 would work out
as 1, it now evaluates to 1.5. Conversion from floating point numbers to integers is achieved with the
RoundUp(expr), RoundDown(expr) and Round(expr)functions, which can be applied to any expression.

xlix
 4 Object Reference

4 Object Reference
Hierarchy of Objects

All Objects
Methods
l AddToPluginsMenu("menu text","function name")

l
 4 Object Reference

Adds a new menu item to the Plug-ins menu. When the menu item is selected the given function is
called. This is normally only used by plug-ins themselves. This method may only be called once per
plug-in (that is each plug-in may only add one item to the Plug-ins menu); subsequent method
calls is ignored.
l Asc(expression)
Returns the ASCII value of a given character (the expression should be a string of length 1).
l CharAt(expression,position)
Returns the character from the expression at the given (zero-based) position, for example CharAt
("Potato",3) would give “a.”
l Chr(expression)
Returns a character (as a string) with the given ASCII value. This can be used for inserting double
quotes (") into strings with Chr(34).
l Cmd(command name)
An alias for the [Link]() function. For example:
l Cmd("ToGGle ReVieW mODe");
Use Cmd() in conjunction with [Link]() to execute commands by name rather than
by CommandID. For example:
l [Link](Cmd("Select All"));
l CreateArray()
Returns a new array object.
l CreateHash()
Returns a new hash-table object.
l GetInterpreterOption(optionName)
Returns a boolean indicating whether the provided interpreter option is enabled or not.
l GetValidationError(object)
Returns the validation error, if any, of the specified object. Useful to pass validation errors to the
plug-in trace window.
l ExitPlugin()
Exits the plug-in cleanly without dropping into the plug-in editor.
l InterpreterOptionExists(optionName)
Returns a boolean indicating whether the interpreter option exists in the running version of Sibelius.
l IsObject(expression)
Returns 1 (or True) if expression evaluates to an object rather than a null, boolean, string, or any
number. (Not to be confused with the IsPassage variable of Selection objects!)
l IsValid(object)
Returns 1 (or True) if the object is valid, returns 0 (or False) if the object no longer exists (that is has
been deleted).
l JoinStrings(expression, delimiter)
Joins together (concatenates) an array of strings into a single string, separated by the string
delimiter.
l Length(expression)
Gives the number of characters in the value of the expression.

li
 4 Object Reference

l Round(expression)
Returns the nearest integer to the value of the expression, for example Round(1.5) would be “2”
and Round(1.3) would be “1.”
l RoundDown(expression)
Returns the nearest integer less than the value of the expression, for example RoundDown(1.5)
would
be “1.”
l RoundUp(expression)
Returns the nearest integer greater than the value of the expression, for example RoundUp(1.5)
would be “2.”
l SetInterpreterOption(optionName,[optionValue])
Allows enabling or disabling a particular interpreter option. By default, if optionValue is not
provided, it is assumed that the option should be enabled. Note that the scope of the options are per
plug-in and that once set, the option value persists as long as the plug-in remains loaded. It should
be called early in the execution of the plug-in (it doesn’t hurt to call it more than once).
l SplitString(expression,[delimiter,][trimEmpty])
Splits a string into an array of strings, using the given delimiter. The delimiter can be a single
character or a string containing several characters—for instance ".," would treat either a comma or
full stop as a delimiter. The default delimiter is the space character. If the trimEmpty parameter is
True then this ignores multiple delimiters (which would otherwise produce some empty strings in the
array). The default value of trimEmpty is False.
s=':a:b:c';
bits=SplitString(s,':', false);
// bits[0] = ''; bits[1] = 'a'; bits[2] = 'b' ...
s='a b c';
bits=SplitString(s,' ', true);
// bits[0] = 'a'; bits[1]='b' ...
l StopPlugin([message])
Stops the plug-in, and shows the optional message in an alert box. Opens the plug-in editor at the
line of code reached.
l StyleCmd (command name)
An alias for the [Link]() function. For example:
l Cmd("ToGGle ReVieW mODe");
l Substring(expression,start,[length])
This returns a substring of the expression starting from the given start position (zero-based) up to the
end of the expression, for example Substring("Potato",2) would give “tato”. When used with
the optional length parameter, Substring returns a substring of the of the expression starting from the
given start position (zero-based) of the given length, for example Substring("Potato",2,2)
would give “ta”.
l Trace(expression)
Sends a piece of text to be shown in the plug-in trace window, for example Trace("Here's a
trace");
l ValidationChecking(enable[, object1[, object2]...])

lii
 4 Object Reference

If enable is the only parameter, validation checking is enabled for all types of objects, and across all
plug-ins. If you supply one or more object parameters (such as Tuplet, Score, BarObject, and so
on), only those objects is checked, and only in the currently running plug-in. You should ensure
ValidationChecking is set to false before you give your plug-ins to anybody else to use.

User Properties
All objects (except for the Sibelius object, old-style ManuScript arrays created using CreateArray(),
old-style ManuScript hashes created using CreateHash(), and null) can also have user properties
assigned to them.

Accessibility
Accessed from the Sibelius object.

Methods
None.

Variables
ScoreDescription

Returns true if Sibelius’s built-in score description functionality is enabled (read/write).

AnnotationItem
Represents an annotation. Has no methods or variables but might be referenced in other functions, such as
for filtering.

Methods
None.

Variables
None.

Bar
A Bar contains BarObject objects.

for each variable in produces the BarObjects in the bar

for each type variable in produces the BarObjects of the specified type in the bar

Methods
l AddBarNumber(new bar number[,format[,extra_text[,prepend[,skip this bar]]]])
Adds a bar number change to the start of this bar. new bar number should be the desired external
bar number. The optional format parameter takes one of the three pre-defined constants that define
the bar number format; see "Global Constants" on page clxxx. The optional extra_text parameter
takes a string that is added after the numeric part of the bar number, unless the optional boolean
parameter prepend is True, in which case the extra_text is added before the numeric part of the bar
number. If the optional skip this bar parameter is True, the bar number change is created with the
Don’t increment bar number option set. Returns the BarNumber object created.
l AddChordSymbolFromPitches(position,pitches[,instrument style])

liii
 4 Object Reference

Adds a chord symbol from the given array of pitches at the specified position. The optional
instrument style parameter operates the same as in the AddGuitarFrame method (see above). If the
method is unable to create a chord symbol, the method returns null; otherwise it returns the
GuitarFrame object created.
l AddClef(pos,concert pitch clef[,transposed pitch clef])
Adds a clef to the staff at the specified position. concert pitch clef determines the clef style when
Notes > Transposing Score is switched off; the optional transposed pitch clef parameter
determines the clef style when this is enabled. Clef styles should be an identifier like “[Link]”; for
a complete list of available clef styles, see "Clef Styles" on page clxxxvii. Alternatively you can give
the name of a clef style, such as “Treble,” but bear in mind that this may not work in non-English
versions of Sibelius. Returns the Clef object created.
l AddComment(sr,text[,color[,maximized]])
Adds a comment at the specified sr position in the current bar, displaying the specified text. The
optional color parameter allows you to specify the color of the comment that is created (if not
specified, the comment is created with its default color), and the optional maximized Boolean
parameter allows you to set the comment to be minimized (if not specified, the comment is created
maximized by default). If you want to specify the maximized parameter without specifying a
particular color, set color to -1.
l AddCommentWithName(sr,text,username[,color[,maximized]])
Adds a comment that displays a given username at the specified sr position in the current bar,
displaying the specified text. The optional color parameter allows you to specify the color of the
comment that is created (if not specified, the comment is created with its default color), and the
optional maximized Boolean parameter allows you to set the comment to be minimized (if not
specified, the comment is created maximized by default). If you want to specify the maximized
parameter without specifying a particular color, set color to -1.
l AddGraphic(file name,pos[,below staff[,x displacement[,y displacement[,size ratio]]]])
Adds a graphic above or below the bar at a given position. If below staff is True, Sibelius positions
the graphic below the staff to which it is attached, otherwise it is placed above (the default). You may
additionally displace the graphic from its default position by specifying x- and y displacements.
These should be expressed in millimeters, the latter defining an offset from the top or bottom line of
the staff, as appropriate. By default, the graphic is created 5mm away from the staff. To adjust the
size of the graphic, you may set a floating point number for its size ratio. When set to 1.0 (the
default), the graphic is created with a height equal to that of the staff to which it is attached. A value
of 0.5 would therefore halve its size, and 2.0 double it. The graphic may be rescaled to a maximum
of five times the height of its parent staff. This function returns True if successful, otherwise False.
l AddGraphicToBlankPage(file name,nth page,x offset,y offset[,size ratio])
Adds a graphic to a blank page belonging to the current bar. nth page specifies the particular blank
page you would like the graphic to, starting from 1. The x offset and y offset parameters are floating
point values relative to the size of the page the graphic is being added to. For example, an x offset of
0.0 would position the graphic at the very left of the page; 0.5 in the center. You may specify the
size of the graphic by specifying a value for size ratio. This defaults to 1.0, which has the same effect
as creating a graphic in Sibelius manually using Create > Graphic. (As with AddGraphic, 0.5
would halve its size, and 2.0 double it.) The graphic may be rescaled to a maximum of five times its
initial size. This function returns True if successful, otherwise False.
l AddGuitarFrame(position,chord name[,instrument style[,fingerings])
Adds a chord symbol for the given chord name to the bar. The optional instrument style parameter
should refer to an existing instrument type that uses tab, and should be specified by identifier; see
"Instrument Types" on page clxxxvii. If instrument style is not specified, Sibelius creates a chord
symbol that optionally displays a chord diagram using the default tab tuning associated with the

liv
 4 Object Reference

instrument type used by the staff to which the chord symbol is attached. The position is in 1/256th
quarters from the start of the bar. The optional fingerings parameter gives the fingerings string to
display above (or below) the guitar frame, if supplied. If the method is unable to create a chord
symbol, the method returns null; otherwise it returns the GuitarFrame object created.
l AddInstrumentChange(pos,styleID[,add_clef[,show_text[,text_label[,show_
warning[,warning_label,[full_instrument_name[,short_instrument_name]]]]]])
Adds an instrument change to the bar at the specified position. styleID is the string representing the
instrument type to change to (see "Instrument Types" on page clxxxvii for a list). The optional boolean
parameter add_clef, True if not specified, determines whether Sibelius adds a clef change at the
same position as the instrument change if required (that is if the clef of the new instrument is
different to that of the existing instrument). show_text is an optional boolean parameter, True if not
specified, determining whether or not the text label attached to the instrument change should be
created shown (the default) or hidden. text_label is an optional string parameter; if specified, Sibelius
uses this string instead of the default string (the new instrument’s long name). show_warning is an
optional boolean parameter, True if not specified, determining whether or not Sibelius should create
a text object (using the Instrument change staff text style) above the last note preceding the
instrument change, announcing the instrument change and giving the player time to pick up the new
instrument. warning_label is an optional string parameter; if specified, Sibelius uses this string
instead of the default string (the word “To” followed by the new instrument’s short name). You can
also override the names Sibelius gives the instruments on subsequent systems. If a null string is
passed to either full_instrument_name or short_instrument_name (or if the arguments are omitted),
the instrument names remains unchanged. Returns the InstrumentChange object created.
l AddKeySignatureFromText(pos,key name,major key[,add double barline[,hidden[,one staff
only]]])
Adds a key signature to the bar. The key signature is specified by text name, such as “Cb” or “C#”.
The third parameter is a Boolean flag indicating if the key is major (or minor). Unless the fourth
parameter is set to False, a double barline is ordinarily created alongside the key signature change.
You may additionally hide the key signature change by setting hidden to True, and make the
change of key appear on the bar’s parent staff only with the one staff only flag. Returns the
KeySignature object created.
l AddKeySignature(pos,num sharps,major key[,add double barline[,hidden[,one staff only]]])
Adds a key signature to the bar. The key signature is specified by number of sharps (+1 to +7), flats (–
1 to –7), no accidentals (0) or atonal (-8). The third parameter is a Boolean flag indicating if the key is
major (or minor). Unless the fourth parameter is set to False, a double barline is ordinarily created
alongside the key signature change. You may additionally hide the key signature change by setting
hidden to True, and make the change of key appear on the bar’s parent staff only with the one staff
only flag. Returns the KeySignature object created.
l AddLine(pos,duration,line style[,dx[,dy[,voicenumber[,hidden]]]])
Adds a line to the bar. The line style can be an identifier such as “[Link]” or a
name, such as “Crescendo”. For a complete list of line style identifiers that can be used in any
Sibelius score, see "Line Styles" on page clxxxiii. Style identifiers are to be preferred to named line
styles as they work across all language versions of Sibelius. Returns the Line object created, which
may be one of a number of types depending on the Line style used.
l AddLiveTempoTapPoint(position)
Adds a Live Tempo tap point at the rhythmic position specified by position, in 1/256th quarters from
the start of the bar.
l AddLyric(position,duration,text[,syllable type [,number of notes,voicenum]]])

lv
 4 Object Reference

This method adds a lyric to the bar. The position is in 1/256th quarters from the start of the bar, and
the duration is in 1/256th quarter units. The two optional parameters allow you to specify whether the
lyric is at the end of a word (value is “1”, and is the normal value) or at the start or middle of a word
(value is “0”), and how many notes the lyric extends beneath (default value 1). You can also
optionally specify the voice in which the lyric should be created; if voicenum is 0 or not specified, the
lyric is created in all voices. Returns the LyricItem object created.
l AddNote(pos,sounding pitch,duration,[tied [,voice[,diatonic pitch[,string number]]]])
Adds a note to staff, adding to an existing NoteRest if already at this position (in which case the
duration is ignored); otherwise creates a new NoteRest. Adds a new bar if necessary at the end of the
staff. The position is in 1/256th quarters from the start of the bar. The optional tied parameter should
be True if you want the note to be tied. Voice 1 is assumed unless the optional voice parameter (with
a value of 1, 2, 3 or 4) is specified. You can also set the diatonic pitch, that is the number of the “note
name” to which this note corresponds, 7 per octave (35 = middle C, 36 = D, 37 = E and so on). If a
diatonic pitch of zero is given, a suitable diatonic pitch is calculated from the MIDI pitch. The optional
string number parameter gives a string number for this note, which is only meaningful if the note is on
a tablature stave. If this parameter is not supplied then a default string number is calculated based
on the current tablature stave type and the guitar tab fingering options (specified on the Notes page
of File > Preferences). Returns the Note object created (to get the NoteRest containing the note,
use [Link]).
l AddPageNumber([blank page offset])
Creates and returns a page number change at the end of the bar. Due to the nature of adding a page
number change, a page break is also created at the end of the bar. Therefore, the page number
change is actually placed at the start of the next bar. The desired properties of the page number
change can be set by calling the appropriate methods on the Page Number Change object
returned.
The blank page offset flag allows you to create page number changes on blank pages. If a
BarObject is followed by one or more blank pages, each blank page may also have a page number
change of its own. If unspecified, the page number change is created on the next available page
(whether it contains music or not) after the bar, otherwise the user may specify a 1-based offset
which refers to the nth blank page after the bar itself.
l AddPageNumberAtStartOfBar()
Creates and returns a page number change at the start of the bar. This is useful for adding a page
number change at the very start of the score, that is to change the initial page number, by using this
method on the first bar of the score. If used on a bar later in the score, it creates the page number
change at the end of the previous bar, but unlike the AddPageNumber method, it does not force a
page break, so in general the AddPageNumber method is recommended.
l AddRehearsalMark([consecutive[,mark[,new prefix and suffix[,prefix[,suffx[,override
defaults]]]]])
Adds a rehearsal mark above the bar. If no parameters have been specified, the rehearsal mark
inherits the properties of the previous rehearsal mark in the score, incrementing accordingly.
Optionally, the appearance of the rehearsal mark may be overridden. If consecutive is False,
Sibelius does not continue the numbering of the new rehearsal marks consecutively, but allow the
user to set a new mark. A mark may be expressed as a number of a string. For example both 5 and
“e” are both valid and equivalent values. If new prefix and suffix is True, the values set for prefix
and suffix is applied to the new rehearsal mark. The final parameter, override defaults, is a Boolean
defaulting to False whose purpose it is to mimic the behavior of the option with the same name in
the Rehearsal Mark dialog in Sibelius.
l AddSpecialBarline(barline type[,pos])

lvi
 4 Object Reference

Adds a special barline to a given position in a bar; see "Global Constants" on page clxxx. If no
position has been specified, start repeat barlines snap to the start of the bar by default. All other
special barline types snap to the end.
l AddSymbol(pos,symbol index or name)
Adds a symbol to the bar at the specified position. If the second parameter is a number, this is taken
to be an index into the global list of symbols, corresponding to the symbol’s position in the Create >
Symbol dialog in Sibelius (counting left-to-right, top-to-bottom from zero in the top-left hand
corner). Some useful symbols have pre-defined constants; see "Global Constants" on page clxxx.
There are also constants defined for the start of each group in the Create > Symbol dialog, so that
to access the 8va symbol, for example, you can use the index OctaveSymbols + 2.
It’s better to use indices rather than names, because the names are different across the various
language versions of Sibelius. Returns the Symbol object created, or null if no symbol can be added
to the score.
l AddText(pos,text,style[,voicenum])
Adds the text at the given position, using the given text style. A staff text style must be used for a
normal staff, and a system text style for a system staff. The styles should be an identifier of the form
“[Link]”; for a complete list of text styles present in all scores, see "Text Styles" on
page clxxxi. Alternatively you can give the name of a text style, such as “Expression”, but be aware
that this may not work in non-English versions of Sibelius. You can also optionally specify the voice in
which the lyric should be created; if voicenum is 0 or not specified, the text object is created in all
voices. Returns the Text object created.
l AddTextToBlankPage(xPos,yPos,text,style,pageOffset)
Adds the text at the given position, using the given text style. A blank page text style must be used;
you cannot add staff text or system text to a blank page. style takes a style ID, using the form
“[Link]”; for a complete list of text styles present in all scores, see "Text Styles" on
page clxxxi. xPos and yPos are the absolute position on the page. pageOffset takes a positive
number for a blank page following a special page break (the first blank page is 1), and negative for a
blank page preceding the first bar of the score (the blank page immediately before the first bar is -1,
the one before that -2, and so on). Returns the Text object created.
To add text to a blank page, first create the special page break using the [Link] variable,
and set the number of blank pages using [Link] or [Link].
Then use [Link].
l AddTimeSignature(top,bottom,allow cautionary,rewrite music[,use symbol])
Returns an error string (which is empty if there was no error) which if not empty should be shown to
the user. The first two parameters are the top and bottom of the new time signature. The third tells
Sibelius whether to display cautionary time signatures from this time signature. If rewrite music is
True then all the bars after the inserted the time signature is rewritten. You can also create common
time and alla breve time signatures. If you’re creating a time signature in 4/4 or 2/2, set use symbol
to True and Sibelius replaces the numbers of the time signature with their symbolic equivalent.
l AddTimeSignatureReturnObject(top,bottom,allow cautionary,rewrite music[,use symbol])
As above, but returns the time signature object created, or null if unsuccessful.
l AddTuplet(pos,voice,left, right, unit[, style[, bracket[, fullDuration]]])
Adds a tuplet to a bar at a given position. The left and right parameters specify the ratio of the tuplet,
for example 3 (left) in the time of 2 (right). The unit parameter specifies the note value (in 1/256th
quarters) on which the tuplet should be based. For example, if you wish to create an eighth note
(quaver) triplet group, you would use the value 128. The optional style and bracket parameters take

lvii
 4 Object Reference

one of the pre-defined constants that affect the visual appearance of the created tuplet; see "Global
Constants" on page clxxx. If fullDuration is true, the bracket of the tuplet spans the entire duration of
the tuplet. Returns the Tuplet object created.
If AddTuplet() has been given illegal parameters, it cannot create a valid Tuplet object.
Therefore, you should test for inequality of the returned Tuplet object with null before attempting to
use it.
l Bar[array element]
Returns the nth item in the bar (counting from 0) for example Bar[0]
l Clear([voice number])
Clears a bar of all its items, leaving only a bar rest. If a particular voice number is specified, only the
items in that voice is removed.
l ClearNotesAndModifiers([voice number])
Clears a bar of all its notes, rests, tuplets and slurs, replacing them with a single bar rest. If a
particular voice number is specified, only the items in that voice is removed.
l Delete()
Deletes and removes an entire bar from a score. This, by definition, affects all the staves in the score.
l DeletePageNumber([blank page offset])
Deletes the page number change at the end of the bar, or if there are one or more blank pages after
the bar, any page number change that occurs on any of those blank pages. If blank page offset is
unspecified, the page number change on the first page after the bar is deleted.
l GetClefAt(pos)
Returns a Clef object corresponding to the current clef at the specified rhythmic position.
l GetKeySignatureAt(pos)
Returns a KeySignature object corresponding to the current clef at the specified rhythmic position.
l GetInstrumentTypeAt(pos)
Returns an InstrumentType object representing the instrument type used by the bar at the
specified rhythmic position.
l GetPageNumber([blank page offset])
Returns the page number change object at the end of the bar, or if the bar contains no page number
change, null. As with AddPageNumber, you may get the page number change from any of the
blank pages that follow the bar by specifying a valid blank page offset.
l InsertBarRest(voice number[,rest type])
Inserts a bar rest into the bar, but only if the bar is void of any NoteRests (or an existing bar rest)
using the same voice number. The optional rest type parameter allows you to specify the type of bar
rest or repeat bar to be created, defined by the constants WholeBarRest (the default if rest type is
not specified), BreveBarRest, OneBarRepeat, TwoBarRepeat and FourBarRepeat. Returns
True if successful.
l NthBarObject(n)
Returns the nth object in the bar, counting from 0.
l RemoveLiveTempoTapPoint(position)
Removes a Live Tempo tap point at the rhythmic position specified by position, in 1/256th quarters
from the start of the bar.
l ResetSpaceAroundBar(above,below)

lviii
 4 Object Reference

Does the equivalent of Layout > Reset Space Above Staff and/or Reset Space Below
Staff for the given bar. Set above to True to reset the space above the staff, and below to True to
reset the space below the staff.
l Respace()
Respaces the notes in this bar.
l RespaceIncludeHiddenNotes
Respace notes in a bar, including hidden notes.
l RespaceIgnoreHiddenNotes
Respace notes in a bar, excluding hidden notes.

Variables
l BarNumber
The bar number of this bar. This is the internal bar number, which always runs consecutively from 1
(read only).
l BarObjectCount
The number of objects in the bar (read only).
l BreakType
The break at the end of this bar, given by the constants MiddleOfSystem, EndOfSystem,
MiddleOfPage, EndOfPage, NotEndOfSystem, EndOfSystemOrPage or SpecialPageBreak.
To learn the correspondence between these constants and the menu in the Bars panel of the
Properties window, see the discussion in "Global Constants" on page clxxx.
When you set the break at the end of a bar to be SpecialPageBreak, Sibelius adds one blank page
after the break. You can then adjust the number of pages by setting the value of either
[Link] or [Link], or tell Sibelius to restart the music on the
next left or right page with [Link].
l ExternalBarNumber
This has been deprecated as of Sibelius 5, because it can only return a number, and bar numbers
that appear in the score may now include text. Use ExternalBarNumberString instead, which
returns the external bar number of this bar, taking into account bar number changes in the score
(read only). Note that you cannot pass this bar number to any of the other ManuScript accessors;
they all operate with the internal bar number instead.
l ExternalBarNumberString
The external bar number of this bar as a string, taking into account bar number changes and bar
number format changes (read only). Note that you cannot pass this bar number to any of the other
ManuScript accessors; they all operate with the internal bar number instead.
l GapAfter
Sets the gap (in spaces) after the bar (read/write)
l GapBefore
Sets the gap (in spaces) before the bar (read/write).
l InMultirest
Returns one of four global constants describing if and/or where the bar falls in a multirest (read only).
The constants are NoMultirest, StartsMultirest, EndsMultirest and MidMultirest; see
"Global Constants" on page clxxx.
l Length

lix
 4 Object Reference

The rhythmic length (read only).

l MusicRestartsOnPage
Tells Sibelius to restart the music on the next left or right page after a special page break, and can
only
be set if BreakType is SpecialPageBreak. This variable may be set to only two of the global
special page break constants:
MusicRestartsOnNextLeftPage or MusicRestartsOnNextRightPage (write only).
l NthBarInSystem
Returns the position of the bar in the system, relative to the first bar on the system (bar 0) (read only).
l NumBlankPages
The number of blank pages following the bar containing a special page break.
l NumBlankPagesBefore
The number of blank pages preceding the bar containing a special page break. This value only has an
effect if a special page break exists in bar 1.
l OnHiddenStave
Returns True if the bar is currently hidden by way of Hide Empty Staves (read only).
l OnNthPage
Returns the zero-based page number on which the bar occurs in the current part (read only).
l OnNthPageExternal
Returns a string containing the external page number (which is the page number displayed in the
score) of the page in which the bar occurs.
l OnNthSystem
Returns the zero-based system number (relative to its parent page) in which the bar occurs (read
only).
l ParentStaff
The staff containing this bar (read only).
l SectionEnd
Corresponds to the Section end checkbox on the Bars panel of Properties (read/write).
l Selected
Returns True if the entire bar is currently selected (read only).
l SpecialPageBreakType
Returns the type of the special page break; see the documentation for the Special page break types
in "Global Constants" on page clxxx (read only).
l SplitMultirest
When True, a multirest intersecting the bar in question is split (read/write).
l Time
The time at which the bar starts in the score in milliseconds (read only).

Barline
Accessed from a Barlines object.

lx
 4 Object Reference

Methods
None.

Variables
l BottomStave
Returns the Staff object at which the barline ends, relative to the current part.
l BottomStaveNum
Returns the number of the bottom staff included in the barline, relative to the current part.
l TopStave
Returns the Staff object at which the barline starts, relative to the current part.
l TopStaveNum
Returns the number of the top staff included in the barline, relative to the current part.

BarObject
BarObjects include Clef, Line, NoteRest, and Text objects. All the methods and variables below apply
to all specific types of BarObject—they are listed here instead of separately for each type. (To object-
oriented programmers, the NoteRest, Clef, and those types are derived from the base class BarObject.)

Methods
l Delete()
Deletes an item from the score. This completely removes text objects, clefs, lines and so on from the
score; however, when a NoteRest is deleted, it is converted into a rest of similar duration. To delete
multiple items from a bar, see "Deleting Multiple Objects from a Bar" on page lxiv.
l Deselect()
Removes the object from the selection list of the parent score. If the selection is currently a passage
selection, it is first changed to a multiple selection before the object is deselected. Returns True if the
object is successfully removed from the selection.
l FreezeMagneticLayoutPositions()
Does the same as selecting an object and choosing Layout > Freeze Magnetic Layout
Positions, that explicitly sets the object’s Dx/Dy to the position produced by Magnetic Layout,
then disables Magnetic Layout for that object.
l GetIsInVoice(voicenum)
Returns True if the object is in the voicenum specified.
l GetPlayedOnNthPass(n)
Returns True if the object is set to play back the nth time.
l NextItem([voice[, item type]])
Returns the next item in the parent bar of the current item, or null if no item exists. If no arguments
have been supplied, the very next item in the bar is returned, regardless of its voice number and item
type. You may additionally specify the voice number of the object you’re looking for (1 to 4, or 0 for
any voice number), and the item’s type. Note that an item is only returned if it exists in the same bar
as the source item. By way of example, to find the next crescendo line in voice 2, you would type
something along the lines of: hairpin = [Link](2, “CrescendoLine”);
l PreviousItem([voice[, item type]])
As above, but searches backwards.

lxi
 4 Object Reference

l RemoveVoice(voicenum)
Removes the object from the specified voicenum, leaving the object in all remaining voices.
l ResetPosition([horizontal[, vertical]])
Performs Layout > Reset Position on the object. If you supply no parameters, this method resets
both the horizontal and vertical position of the object. If either or both of the optional Boolean
parameters horizontal or vertical is set to True, you can reset the position of the object either
horizontally or vertically independently if required.
l ResetDesign()
Performs Layout > Reset Design on the object.
l Select()
Appends the object to the selection list of the parent score. A multiple selection consisting of any
number of individual objects can be built up by repeatedly calling Select on each object you wish to
add to the list. Note that calling Select on a BarObject first clears any existing passage selection.
l SetAllVoices()
Sets the object to be in all voices. This has no effect on some types of object, such as NoteRests.
l SetVoice(voicenum[,clear other voices])
Sets the object to be in voice voicenum, optionally removing the object from all other voices if the
Boolean parameter clear other voices is True.
l ShowInAll()
Shows the object in the full score, and in all relevant parts; equivalent to Edit > Hide or Show >
Show In All.
l ShowInParts()
Hides the object in the full score, and shows it in all relevant parts; equivalent to Edit > Hide or
Show > Show In Parts.
l ShowInScore()
Hides the object in all relevant parts, and shows it in the full score; equivalent to Edit > Hide or
Show > Show In Score.
l SetPlayedOnNthPass(n, do play)
Tells Sibelius whether or not the object should play back the nth time.
l TimeOnNthPass(n)
Returns the time at which the object occurs in the score in milliseconds on the nth pass through the
score, where n is an integer specifying the pass (specify 1 for the first pass through the score), or
returns -1 in the case of an error (because the specified value of n is out of range).

Variables
l CanBeInMultipleVoices
Returns True if the object can be in more than one voice (read-only).
l Color
The color of this BarObject (read/write). The color value is in 24-bit RGB format, with bits 0–7
representing blue, bits 8–15 green, bits 16–23 red and bits 24–31 ignored. Since ManuScript has no
bitwise arithmetic, these values can be a little hard to manipulate; you may find the individual
accessors for the red, green and blue components to be more useful (see below). In order to write a
value to this variable, the object must be selected.
l ColorAlpha

lxii
 4 Object Reference

The alpha channel component of the color of this BarObject, in the range 0–255 (read/write). In
order to write a value to this variable, the object must be selected.
l ColorRed
The red component of the color of this BarObject, in the range 0–255 (read/write). In order to write
a value to this variable, the object must be selected.
l ColorGreen
The green component of the color of this BarObject, in the range 0–255 (read/write). In order to
write a value to this variable, the object must be selected.
l ColorBlue
The blue component of the color of this BarObject, in the range 0–255 (read/write). In order to write
a value to this variable, the object must be selected.
l CueSize
l True if the object is cue-size in the current part or score, and False if the object is normal size
(read/write).
l CurrentTempo
Returns the tempo, in bpm, at the location of the object in the score (read only).
l DrawOrder
Returns the layer at which the object is currently drawn. When used to set the layer of an object,
values from 1 (meaning the bottom layer) to 32 (meaning the highest layer) can be used; 0 is a
special value that tells Sibelius to use the default layer for that type of object (read/write).
l Dx
The horizontal graphic offset of the object from the position implied by the Position field, in units of
1/32 spaces (read/write).
l Dy
The vertical graphic offset of the object from the center staff line, in units of 1/32 spaces, positive
going upwards (read/write).
l HasCustomDrawOrder
Returns True if the object is set to a layer other than its default layer (read only).
l Hidden
l True if the object is hidden in the current part or score, and False if the object is shown
(read/write).
l OnNthBlankPage
Returns 0 if the object occurs on a page of music, otherwise a number from 1 upwards indicating the
nth blank page of the bar on which the object occurs (read only).
l ParentBar
The Bar containing this BarObject (read only).
l Position
Rhythmic position of the object in the bar (read only).
l Selected
Returns True if the object is currently selected (read only).
l Time

lxiii
 4 Object Reference

The time at which the object occurs in the score in milliseconds; if the score contains repeats, this
always returns the time as if for the first pass through the score (read only). Returns -1 in the case of
an error.
l Type
A string describing the type of object, such as “NoteRest,” “Clef.” This is useful when hunting for a
specific type of object in a bar. See "GuitarScaleDiagram" on page lxxxii for the possible values (read
only).
l UsesMagneticLayout
Returns True if the object is positioned by Magnetic Layout. Returns False if the object is set not to
be taken into account by Magnetic Layout. To set whether or not an object should use Magnetic
Layout, use one of the global constants
AlwaysDodge (equivalent to Edit > Magnetic Layout > n), SuppressDodge (Edit >
Magnetic Layout > Off) or DefaultDodge (Edit > Magnetic Layout > Default)
(read/write).
l UsesMagneticLayoutSettingOverridden
Returns True if the object has had its Magnetic Layout settings overridden; otherwise False.
l VoiceNumber
Is 0 if the item belongs to more than one voice (a lot of items belong to more than one voice) and 1 to
4 for items that belong to voices 1 to 4 (read only).
l Voices
Returns or sets Sibelius’s internal bit field that represents the voices to which an object belongs;
useful for copying the voices used by a given object (read/write).

Deleting Multiple Objects from a Bar

If you wish to delete multiple objects from a bar, you should first build up a list of items to delete, then
iterate over the list deleting each object in turn. It is not sufficient to simply delete the objects from the bar
as you iterate over them, as this may cause the iterator to go out of sync.

Therefore, code to delete all tuplets from a bar should look something like this:
counter = 0;
for each Tuplet tup in bar {
name = "tuplet" & counter;
@name = tup;
counter = counter + 1;
}
// Delete objects in reverse order
while(counter > 0) {
counter = counter - 1;
name = "tuplet" & counter;
tup = @name;
[Link]();
}

BarRest
Derived from a BarObject object.

Methods
None.

lxiv
 4 Object Reference

Variables
l PauseType
Returns the type of fermata (pause), if any, on the bar rest. Returns one of the constants
PauseTypeNone (0), PauseTypeSquare (1), PauseTypeRound (2), PauseTypeTriangular (3)
(read/write).
l RestType
Returns the type of bar rest with one of the constants WholeBarRest (0), BreveBarRest (1),
OneBarRepeat (2), TwoBarRepeat (3), FourBarRepeat (4) (read only). To create a bar rest of a
particular type, use [Link]() (see above).

Bracket
Accessed from a BracketsAndBraces object.

Methods
None.

Variables
l BottomStave
Returns the Staff object at which the bracket ends, relative to the current part.
l BottomStaveNum
Returns the number of the bottom staff included in the bracket, relative to the current part.
l BracketType
Returns the type of the bracket: BracketFull, BracketBrace or BracketSub.
l TopStave
Returns the Staff object at which the bracket starts, relative to the current part.
l TopStaveNum
Returns the number of the top staff included in the bracket, relative to the current part.

Barlines
Accessed from a Score Object. Corresponds to the barline groupings in the score.

for each barline in iterates through all the barlines in the list, for example:

s = [Link];
barlines = [Link];
for each barline in barlines {
// do something with barlines here
}

Array access [int n] returns the nth barline in the list, or null if the barline does not exist.

Methods
l AddBarline(top staff number, bottom staff number)
Creates a new bar line inclusively spanning the staff numbers (relative to the current part) supplied.
Returns the new Barline object created, or null if it fails.
l ClearAll()

lxv
 4 Object Reference

Removes all the barlines from the score.

l DeleteNthBarline(index)
Removes a given barline identified by index from the score.

Variables
l NumChildren
Returns the number of unique barlines in the score (read only).

Brackets and Braces

Accessed from a Score object. Describes the brackets (which might be brackets, sub-brackets or braces)
present in the score. for each bracket in iterates through all the brackets in the list. Array access [int n]
returns the nth bracket in the list, or null if the bracket does not exist.

Methods
l AddBracket(type, top staff number, bottom staff number)
Creates a bracket of a given type, spanning the range of staves specified between top staff number
and bottom staff number inclusive, and returns the new Bracket object. The staff numbers are
relative to the current part view. Values for type are BracketFull (0), BracketBrace (1) and
BracketSub (2).
l ClearAll()
Removes all existing brackets, sub-brackets and braces from the current part, and returns the
number of brackets removed.
l DeleteNthBracket(n)
Deletes the nth bracket from the current part, and returns True if successful.

Variables
l NumChildren
Returns the number of child brackets, sub-brackets and braces in the list.

Clef
Derived from a BarObject.

Methods
None.

Variables
l ClefStyle
The name of this clef, which might be different depending on the state of Notes > Transposing
Score (read only).
l ConcertClefStyleId
The concert pitch identifier of the style of this clef (read only).
l ConcertClefStyle
The concert pitch name of this clef (read only).
l StyleId

lxvi
 4 Object Reference

The identifier of the style of this clef, which might be different depending on whether or not Notes >
Transposing Score is enabled. This can be passed to the [Link] method to create a clef
of this style (read only).
l TransposingClefStyle
The transposing score name of this clef (read only).
l TransposingClefStyleId
The transposing score identifier of the style of this clef (read only).

Comment
Derived from a BarObject.

Methods
None; create using BarObject.

Variables
l Maximized
Returns True if the comment is maximized, otherwise returns False (read/write).
l Text
Returns the text of the comment (read/write).
l TextWithFormatting
Returns an array containing the various changes of font or style (if any) within the comment’s text in
a new element (read only). For example, “This text is \B\bold\b\, and this is
\I\italic\i\” would return an array with eight elements containing the following data:
arr[0] = “This text is “
arr[1] = “\B\”
arr[2] = “bold”
arr[3] = “\b\”
arr[4] = “, and this is “
arr[5] = “\I\”
arr[6] = “italic”
arr[7] = “\i\”
l TextWithFormattingAsString
The comment’s text including any changes of font or style (read only).
l TimeStamp
Returns a DateTime object corresponding to the date the comment was created or last edited (read
only).
l UserName
l Returns the username of the user who created or last edited the comment (read only)

ComponentList
An array that is obtained from [Link] or [Link]. It can be
used in a for each loop or as an array with the [n] operator to access each Component object:

Methods
None.

lxvii
 4 Object Reference

Variables
l NumChildren
Number of plug-ins (read only).

Component
This represents a Sibelius “component,” namely a house style or a manuscript paper. Examples:
// Create a new score using the first manuscript paper
papers=[Link];
score=[Link](papers[0]);
// Apply the first house style to the new score
styles=[Link];
[Link](styles[0], "ALLSTYLES");

Methods
None.

Variables
l Name
The name of the component (read only).

DateTime
This object returns information about the current date and time.

Methods
None.

Variables
l Seconds
Returns the number of seconds from the time in a date (read only).
l Minutes
Returns the number of minutes from the time in a date (read only).
l Hours
Returns the number of hours from the time in a date (read only).
l DayOfMonth
Returns the nth day on the month, 1-based (read only).
l Month
Returns the nth month of the year, 1-based (read only).
l Year
Returns the year (read only).
l NthDayOfWeek
Returns the nth day of the week, 0-based (read only).
l NthDayOfYear
Returns the nth day of the year, 0-based (read only).

lxviii
 4 Object Reference

l LongDate
Returns the date in a human-readable format, for example: 1st May 2008 (read only).
l ShortDate
Returns the date in a human-readable format, for example: 01/05/2008 (read only).
l LongDateAndTime
Returns the date and time in a human-readable format, for example: 1st May 2008 14:07 (read
only).
l ShortDateAndTime
Returns the date and time in a human-readable format, for example: 01/05/2008 14:07 (read
only).
l TimeWithSeconds
Returns the time in a human-readable format, for example: 14:07 (read only).
l TimeWithoutSeconds
Returns the time in a human-readable format, for example: 14:07:23 (read only).

Dictionary
To create a dictionary, use the built-in function CreateDictionary(name1, value1, name2, value2, ...
nameN, valueN).
This creates a dictionary containing user properties called name1, name2, nameN with values value1,
value2, valueN respectively.

To iterate over dictionaries:

1. To iterate over element values in Dictionary objects, use for each n in Dictionary or for
each Value n in Dictionary.
2. To iterate over element names in Dictionary objects, use for each Name n in Dictionary.
3. To iterate over [Link] pairs in Dictionary objects, use for each Pair n in Dictionary;
this returns a new Dictionary object: [Link] is the element name, [Link] is the element value.

Methods
l CallMethod(methodname,param1,param2,...paramN)
Calls the specified method methodname in the dictionary, passing in any other values that are
required for the method as further parameters.
l GetMethodNames()
Returns a sparse array containing the names of the methods belonging to a dictionary.
l GetPropertyNames()
Returns a sparse array of the names of all the user properties in the dictionary (same as _
propertyNames).
l MethodExists(methodname)
Returns True if the specified method methodname exists in the dictionary.
l PropertyExists(propertyname)
Returns True if the specified user property propertyname exists in the dictionary.
l SetMethod(methodname,Self,method)

lxix
 4 Object Reference

Binds a method to the dictionary. methodname is the name by which you want to access the method
using the dictionary, Self refers to the plug-in in which the method is found, and method is the name
of the method itself, found elsewhere in the plug-in.

Variables
None.

Converting Old-Style Hash Tables to Dictionaries

The Dictionary object is, among other things, a replacement for the old Hash object, which was a simple
hash table object. You are recommended to use the new Dictionary object instead of the old Hash object
in your plug-ins, but if you have an existing plug-in in which old-style hashes are used, you can convert
them to Dictionaries as follows:
l [Link]()
Returns a new Dictionary object, populated with strings converted from the old-style Hash.

DocumentSetup
Accessed from a Score object, DocumentSetup corresponds to the settings in Layout > Document
Setup.

When you first access the DocumentSetup object, the units default to millimeters; if you want to use
another unit of measurement, set [Link] before you set any of the other values. This
does not, however, change the units displayed in Layout > Document Setup; to do that, set
[Link].

Be careful also that if you set [Link] after setting [Link] or

[Link], the page size specified overrides any custom height/width you may have
just set: so set the page size before you then adjust the width or height of the page.

Methods
None.

Variables
l AboveTopStaveGap
Returns or sets the top staff margin on each page in the units specified by the Units variable
(read/write).
l AboveTopStaveGapAfterFirstPage
Returns or sets the top staff margin on pages after the first page in the units specified by the Units
variable (read/write). To set this, first set FirstPageHasUniqueVerticalStaveMargins to True.
l BelowBottomStaveGap
Returns or sets the bottom staff margin on each page in the units specified by the Units variable
(read/write). To set this, first set FirstPageHasUniqueVerticalStave-Margins to True.
l BelowBottomStaveGapAfterFirstPage
Returns or sets the bottom staff margin on each page after the first page in the units specified by the
Units variable (read/write).
l FirstPageHasUniqueVerticalStaveMargins
Returns True if the After first page checkbox is enabled in Document Setup, specifying that
the first page of the score has different top and bottom staff margins to subsequent pages; otherwise
returns False (read/write).

lxx
 4 Object Reference

l Orientation
Returns or sets the current page orientation. Values are OrientationPortrait (0) and
OrientationLandscape (1). If you change the orientation, this swaps the PageTopMargin and
PageBottomMargin values with the PageLeftMargin and PageRightMargin values, to reflect
the change in orientation (read/write).
l PageHeight
Returns or sets the height of a page in the units specified by the Units variable (read/write).
l PageSize
Returns or sets the current page size. Values are listed in "PageSize Values" on page ccxiii. If you
attempt to set PageSize to PageSizeCustom, Sibelius does nothing; to set a custom page size, set
PageWidth and PageHeight individually. Setting any default PageSize value also changes the
PageWidth and PageHeight values (read/write).
l PageWidth
Returns or sets the width of a page in the units specified by the Units variable (read/write).
l MarginType
Returns or sets the current page margin type. Values are PageMarginsSame (0),
PageMarginsMirrored (1), PageMarginsDifferent (2) (read/write).
l PageBottomMargin
Returns or sets the bottom page margin in the units specified by the Units variable (read/write).
l PageLeftMargin
Returns or sets the left page margin in the units specified by the Units variable (read/write).
l PageRightMargin
Returns or sets the right page margin in the units specified by the Units variable (read/write).
l PageTopMargin
Returns or sets the top page margin in the units specified by the Units variable (read/write).
l RightPageLeftMargin
Returns or sets the left page margin for right-hand pages in the units specified by the Units variable
(read/write). Setting this value automatically sets MarginType to PageMarginsDifferent.
l RightPageRightMargin
Returns or sets the right page margin for right-hand pages in the units specified by the Units
variable (read/write). Setting this value automatically sets MarginType to
PageMarginsDifferent.
l StaffLeftMarginFullNames
Returns or sets the margin to the left of staves showing full instrument names in the units specified by
the Units variable (read/write).
l StaffLeftMarginNoNames
Returns or sets the margin to the left of staves showing no instrument names in the units specified by
the Units variable (read/write).
l StaffLeftMarginShortNames
Returns or sets the margin to the left of staves showing short instrument names in the units specified
by the Units variable (read/write).
l StaffSize

lxxi
 4 Object Reference

Returns or sets the staff size in the units specified by the Units variable (read/write).
l Units
Returns or sets the units of measurement for all of the relevant variables of the DocumentSetup
object. Always returns 0 (millimeters). Values are DocumentSetupUnitsmm (0),
DocumentSetupUnitsInches (1), DocumentSetupUnitsPoints (2) (read/write).
l UnitsInDocumentSetupDialog
Returns or sets the units of measurement currently shown in the Layout > Document Setup dialog.
Values are as for Units.

DynamicPartCollection
Accessed from a Score object. DynamicPartCollection contains DynamicPart objects.

The DynamicPartCollection object always contains the full score as the first entry, whether or not any
dynamic parts exist. The DynamicPart objects are returned in the order in which they were created (the
last part returned is the most-recently created one). For scores in which dynamic parts were generated
automatically, the parts are normally returned in top to bottom score order.

The edit context for ManuScript is stored in the score itself which means that ManuScript can only ever
access one part at a time – the “current” DynamicPart for that Score object. This is irrespective of the
number of score windows open for a score, which dynamic parts are open, and even if the user has
managed to create two different ManuScript Score objects referring to the same Sibelius score.

It is inadvisable to modify Staves, Bars, or any BarObjects that do not exist on Staves in
[Link]. Doing so creates part overrides for part-specific properties of these
objects which are invisible until those Staves are added to the part. [Link]()
can be used to test if a DynamicPart contains a particular Staff object.

Both DynamicPartCollection and DynamicPart refer to an underlying Score and part(s) and
generates errors if the Score and/or part(s) are no longer valid (for example, if a DynamicPart has been
deleted). DynamicPart are never “re-used.” For example, if you delete a DynamicPart and create a new
DynamicPart, the old ManuScript DynamicPart object does not refer to the newly-created
DynamicPart.

for each variable in iterates through all valid DynamicPart objects for the Score, always starting first
with the full score. Adding or deleting parts while iterating will have undefined results, and is not
recommended.

Array access [int n] returns the nth part (0 is always the full score), or null if the part does not exist.

Methods
l CreateDefaultParts()
Creates the default set of dynamic parts, as created automatically by Sibelius when clicking the New
Part button in the Parts window. This method does nothing and returns False if the Score has no
staves.
l CreatePartFromStaff(staff)
Creates a dynamic part from the specified Staff object, if valid. Returns the new DynamicPart
object for success, or null for failure.
l DeletePart(dynamic part)
Deletes the specified part, if it’s valid. Returns True for success, False for failure. This method fails
is the specified dynamic part is the currently active part for the Score, or is the full score, or refers to
a different Score.

lxxii
 4 Object Reference

Variables
l NumChildren
Returns the number of DynamicPart objects for the Score returned by iteration (read only).

DynamicPart
Accessed from a DynamicPartCollection object.

for each variable in returns the Staff objects in the dynamic part, in top to bottom order.

c This can return a Staff that is not included in [Link].

Methods
l AddStaffToPart(staff)
Adds the specified staff to the bottom of the dynamic part. Returns False for failure. This method
causes an error if it is called on the full score, or if attempting to add a staff that is already present in
the part or a staff from a different score.
l DeleteStaffFromPart(staff)
Deletes the specified staff from the dynamic part. Returns False for failure. This method causes an
error if called on the full score, or if attempting to delete a staff that is not present in the part, or if
deleting the last staff in a part, or attempting to delete a part from a different score.
l IncludesStaff(staff)
Returns True if the specified staff is contained in this dynamic part.

Variables
l IsFullScore
Returns True for the full score only, but not for score subsets (read only).
l IsScoreSubset
Returns True if the current Dynamic Part is a score subset (read only). The collection may or may not
include score subsets, depending on how the
IncludeScoreSubsetsInDynamicPartCollection interpreter option is set.
l IsSelectedInPartsWindow
Returns True if the part is selected in the Parts window (read only).
l StaveCount
Returns the number of staves in the part (read only).
l ParentScore
Returns the Score object containing this dynamic part (read only).

EngravingRules
Accessed using the Score object. Corresponds to selected settings in the House Style > Engraving
Rules dialog.

lxxiii
 4 Object Reference

Methods
l BarNumberFrequency(BarNumberFrequencyCategory, [customFrequency)
Equivalent to setting the Bar Number Frequency setting in the Engraving Rules Dialog. Valid
BarNumberFrequencyCategory values include: EverySystem (0), NoBarNumbers (1),
EveryNthBar (2). The optional customFrequency argument is used in conjunction with the
EveryNthBar (2) BarNumberFrequencyCategory, and sets how often (in bars) Bar Numbers
appear in the score.

Variables
l AdjustTranspositionIfKeySigWraps
Returns True if Sibelius adjusts the note spelling for transposing instruments in extreme keys, False
otherwise; corresponds to the Adjust note spelling in transposing instruments in
remote keys option on the Clefs and Key Signatures page (read/write).
l BarlineJoinSystemEnd
Returns True if Sibelius draws complete barlines at the end of a system regardless of the barline
breaks within a system; False otherwise, corresponding to the option Join barlines at end of
systems on the Barlines page (read/write).
l BarlineSingleStaves
Returns True if Sibelius draws barlines on a single staff; False otherwise, corresponding to the option
Barline at start of single staves on the Barlines page (read/write).
l BeamThickness
Returns or sets the thickness of beams in spaces, from the Beams and Stems page (read/write).
l BarlineWidth
Returns or sets the width of normal barlines in spaces, from the Barlines page (read/write).
l CautionaryNaturalsInKeySignatures
Returns True if key changes show cautionary naturals; False otherwise, from the Clefs and Key
Signatures page (read/write).
l CueNoteScale
Returns or sets the percentage by which cue-sized notes are scaled relative to normal-sized notes,
from the Notes and Tremolos page (read/write).
l DashedBarlineGap
Returns or sets the gap between dashes of dashed barlines in spaces, from the Barlines page
(read/write).
l DashedBarlineLength
Returns or sets the length of the dashes of dashed barlines in spaces, from the Barlines page
(read/write).
l DashedBarlineWidth
Returns or sets the width of dashed barlines in spaces, from the Barlines page (read/write).
l DottedBarlineGap
Returns or sets the gap between dots of dotted barlines in spaces, from the Barlines page
(read/write).
l DottedBarlineWidth
Returns or sets the width of dotted barlines in spaces, from the Barlines page (read/write).

lxxiv
 4 Object Reference

l DoubleBarlineSeparation
Returns or sets the distance between the lines in double or triple barlines in spaces, from the
Barlines page (read/write).
l DoubleBarlineWidth
Returns or sets the width of the lines in double or triple barlines in spaces, from the Barlines page
(read/write).
l DoubleTremoloStyle
Returns or sets the style used for double tremolos in the score, from the Notes and Tremolos
page. Values are:
– DoubleTremolosTouchingStems (0), DoubleTremolosBetweenStems (1)
– DoubleTremolosOuterTremoloTouchingStems (2) (read/write).
l ExtraSpacesAboveForSystemObjectPositions
Returns or sets the n extra spaces above for System Object Positions value on the
Staves page (read/write).
l ExtraSpacesBelowVocalStaves
Returns or sets the n extra spaces below vocal staves (for lyrics) value on the
Staves page (read/write).
l ExtraSpaceBetweenGroupsOfStaves
Returns or sets the n extra spaces between groups of staves value on the Staves page
(read/write).
l FinalBarlineSeparation
Returns or sets the distance between the two lines in final or repeat barlines in spaces, from the
Barlines page (read/write).
l FinalBarlineThinWidth
Returns or sets the width of the thin line in final or repeat barlines in spaces, from the Barlines page
(read/write).
l FinalBarlineWidth
Returns or sets the width of the thick line in final or repeat barlines in spaces, from the Barlines
page (read/write).
l GraceNoteScale
Returns or sets the percentage by which grace notes are scaled relative to normal notes, from the
Notes and Tremolos page (read/write).
l InstrumentNamesFirstSystem
Corresponding to the option for instrument names on the first system on the Instruments page;
values are InstrumentNamesFull (0), InstrumentNamesShort (1), InstrumentNamesNone (2)
(read/write).
l InstrumentNamesNewSections
Corresponding to the option for instrument names at the start of new sections on the Instruments
page; values are InstrumentNamesFull (0), InstrumentNamesShort (1),
InstrumentNamesNone (2) (read/write).
l InstrumentNamesSubsequentSystems

lxxv
 4 Object Reference

Corresponding to the option for instrument names on subsequent systems on the Instruments
page; values are InstrumentNamesFull (0), InstrumentNamesShort (1),
InstrumentNamesNone (2) (read/write).
l JustifyGrandStaveInstruments
Returns True if Justify both staves of grand staff instruments on the Staves page is
enabled, otherwise False (read/write).
l JustifyMultiStaveInstruments
Returns True if Justify all staves of multi-staff instruments on the Staves page is
enabled, otherwise False (read/write).
l LegerLineThickness
Returns or sets the thickness of leger lines in spaces, from the Notes and Tremolos page
(read/write).
l RepeatBarlineAllDots
Returns True if Sibelius draws dots in repeat barlines on in every staff space; False otherwise,
corresponding to the option Repeats with dots in all staff spaces on the Barlines page
(read/write).
l RepeatBarlineDoubleThick
Returns True if Sibelius draws coincident repeat barlines as two thick lines rather than a three thin,
thick, thin lines; False otherwise, corresponding to the option Double thick lines for
coincident repeats on the Barlines page (read/write).
l RepeatBarlineWings
Returns True if Sibelius draws wings on repeat barlines; False otherwise, corresponding to the option
Wings on repeat barlines on the Barlines page (read/write).
l RespellRemoteKeysInTransposingScore
Returns True if Sibelius chooses the equivalent key signature with one fewer flat or sharp for
transposing instruments; False otherwise, corresponding to the option Respell remote key
signatures in transposing score on the Clefs and Key Signatures page (read/write).
l ShowNameOfPrevailingInstrumentChangeAtStartOfSystems
Returns True if Sibelius updates the instrument name at the start of each system to reflect the
current instrument change, False otherwise; corresponds to the Change instrument names at
start of system after instrument changes option on the Instruments page
(read/write).
l SlurMiddleThickness
Returns or sets the default thickness of the middle of slurs in spaces, from the Slurs page
(read/write).
l SlurOutlineWidth
Returns or sets the thickness of slur ends in spaces, from the Slurs page (read/write).
l SmallStaffSizeScale
Returns or sets the percentage by which small staves are scaled relative to normal-sized staves, from
the Staves page (read/write).
l SpacesBetweenStaves
Returns or sets the n spaces between staves value on the Staves page (read/write).
l SpacesBetweenSystems
Returns or sets the n spaces between systems value on the Staves page (read/write).

lxxvi
 4 Object Reference

l StaffJustificationPercentage
Returns or sets the Justify staves when page is at least n% full value on the Staves
page (read/write).
l StaffLineWidth
Returns or sets the width of a staff line in spaces, from the Staves page (read/write).
l StemThickness
Returns or sets the thickness of stems in spaces, from the Beams and Stems page (read/write).
l ThickBarlineWidth
Returns or sets the width of thick barlines in spaces, from the Barlines page (read/write).
l TieMiddleThickness
Returns or sets the thickness of the middle of ties in spaces, from the Ties 1 page (read/write).
l TieOutlineWidth
Returns or sets the thickness of tie ends in spaces, from the Ties 1 page (read/write).

File
Retrievable using for each on a folder.

Methods
l Delete()
Deletes a file, returning True if successful.
l Rename(newFileName)
Renames a file, returning True if successful.

Variables
l CreationDate
Returns the file’s creation date and time as a DateTime object, in local time (read only).
l CreationDateAndTime
A string giving the date and time the file was last modified in GMT (read only).
l ModificationDate
Returns the file’s modification date and time as a DateTime object, in local time (read only).
l Name
The complete pathname of the file, no extension (read only).
l NameWithExt
The complete pathname of the file, with extension (read only).
l NameNoPath
Just the name of the file, no extension (read only).
l Path
Returns just the path to the file (read only).
l Type
A string giving the name of the type of the object; File for file objects (read only).

lxxvii
 4 Object Reference

Folder
Retrievable from methods of the Sibelius object.

for each variable in produces the Sibelius files in the folder, as File objects

for each type variable in produces the files of type in the folder, where type is a Windows extension.

Useful values are SIB (Sibelius files), MID (MIDI files) or OPT (PhotoScore files), because they can all be
opened directly by Sibelius. On the Macintosh files of the corresponding macOS Type are also returned (so,
for example, for each MID f returns all files whose names end in .MID, and all files of type “Midi”).

Both these statements return subfolders recursively.

Methods
l FileCount(Type)
Returns the number of files of type Type in the folder. As above, useful values are SIB, MID, or OPT.

Variables
l FileCount
The number of Sibelius files in the folder (read only).
l FileCountAllTypes
The number of files of all types in the folder (read only).
l Name
The name of the folder (read only).
l Type
A string giving the name of the type of the object; Folder for folder objects (read only).

GuitarFrame
Derived from a BarObject. This refers to chord symbols as created by Create > Chord Symbol, whether
or not they show a guitar chord diagram (guitar frame), but is called GuitarFrame in ManuScript for
historical reasons.

Methods
l CopyOutSuffixes()
Returns an array containing a list of the suffix elements present in the chord. If the chord symbol is an
unrecognised chord type, the array returned is empty. The values that can be returned in the array
are as follows:
halfdim dim
add6/9 6/9
sus2/4 aug
omit5 alt
omit3 b13
maj13 #11

lxxviii
 4 Object Reference

add13 13
maj11 11
dim13 #9
dim11 b9
maj9 b6
add9 #5
maj7 b5
dim9 #4
dim7 nc
sus9 9
sus4 7
add4 6
sus2 5
add2 m
maj /

l GetChromaticPitchesOfChordInClosePosition(consider root)
Returns an array containing the chromatic pitches of the notes in the chord, assuming a voicing in
close position. If consider root is True (it defaults to False), the pitches returned are offset
according to the chromatic value of the root note on which the chord is based.
l GetEndStringForNthBarre(barreNum)
Returns the string number on which the nth barré ends.
l GetPitchOfNthString(stringNum)]
Returns the pitch of the given (open) string stringNum, as a MIDI pitch.
l GetPositionOfFingerForNthBarre(barreNum)
Returns the fret position that the nth barré occupies.
l GetPositionOfFingerOnNthString(stringNum)
Returns the position of the black dot representing the finger position on a given string stringNum,
relative to the top of the frame. A return value of 0 means the string is open (that is a hollow circle
appears at the top of the diagram), and -1 means that the string is not played (that is an X appears
at the top of the diagram). Used in conjunction with GetPitchOfNthString(), you can calculate
the resulting pitch of each string.
l GetStartStringForNthBarre(barreNum)
Returns the string number from which the nth barré begins.
l IsNthStringPartOfBarre(stringNum)
Returns True if the given string is part of a barré.
l NthStringHasClosedMarkingAtNut(nth string)
Returns True if there’s an X marking at the top or left of the specified string.
l NthStringHasOpenMarkingAtNut(nth string)
Returns True if there’s an O marking at the top or left of the specified string.

lxxix
 4 Object Reference

Variables
l BassAsString
The note name of the chord symbol’s altered bass note (for example: “F”).
l ChordNameAsStyledString
The name of the chord represented by this chord symbol as it appears in the score, for example:
“Cm7” (read only).
l ChordNameAsPlainText
The name of the chord represented by this chord symbol as it appears when editing the chord
symbol, so that in its plain text representation, for example: “Cmmaj7” (read only).
l ChromaticRoot
The chromatic pitch (C = 0, B = 11) of the chord symbol’s root note (read only).
l ChromaticBass
The chromatic pitch (C = 0, B = 11) of the chord symbol’s altered bass note (read only).
l DiatonicRoot
The diatonic pitch, that is the number of the “note name” to which this note corresponds, 7 per
octave (0 = C, 1 = D, 2 = E and so on), of the chord symbol’s root note (read only).
l DiatonicBass
The diatonic pitch, that is the number of the “note name” to which this note corresponds, 7 per
octave (0 = C, 1 = D, 2 = E and so on), of the chord symbol’s altered bass note (read only).
l Fingerings
The fingerings string for this chord. This is a textual string with as many characters as the guitar
frame has strings (for example, six for standard guitars). Each character corresponds to a guitar
string. Use to denote that a string has no fingering.
l FrameIsVisible
True if the chord symbol is currently showing a guitar chord diagram (read only).
l Horizontal
True if the guitar chord diagram is horizontally orientated, False if it is vertically orientated
(read/write).
l LowestVisibleFret
The number of the top fret shown in the guitar chord diagram; setting the special value -1 resets the
lowest visible fret to the default for that chord diagram (read/write).
l NumBarresInChord
The number of unique barrés in the guitar chord diagram (read only).
l NumberOfFrets
The number of frets in the guitar chord diagram, that is the number of horizontal lines; setting the
special value -1 resets the number of frets to the default for that chord diagram (read/write).
l NumberOfStrings
The number of strings in the guitar chord diagram, for example,. the number of vertical lines (read
only).
l NumPitchesInClosePosition
The number of unique pitches in the chord, assuming a voicing in close position with no duplicates.

lxxx
 4 Object Reference

l Recognized
Returns True if the chord symbol is a specific recognized chord type, and False otherwise, that is if
the chord symbol is shown in red in the score because Sibelius is unable to parse the user’s input
(read only).
l RootAsString
The note name of the chord symbol’s root (for example, “C#”).
l ScaleFactor
The scale factor of the guitar chord diagram (as adjustable by the Scale parameter on the General
panel of Properties), expressed as a percentage (read/write).
l ShowFingerings
Set to True if the fingerings string should be displayed, False otherwise (read only).
l SuffixText
The suffix part of the chord symbol as it appears in the score, or an empty string if the chord isn’t
recognized (read only).
l TextIsVisible
True if the chord symbol is currently showing a text chord symbol (read only).
l TransposingChromaticRoot
Returns the chromatic pitch of the root note for the specified chord symbol as if the score is shown at
transposed pitch, but regardless of whether or not Notes > Transposing Score is enabled.
l TransposingChromaticBass
Returns the chromatic pitch of the altered bass note for the specified chord symbol, if present, as if
the score is shown at transposed pitch, but regardless of whether or not Notes > Transposing
Score is enabled.
l TransposingDiatonicRoot
Returns the diatonic pitch of the root note for the specified chord symbol as if the score is shown at
transposed pitch, but regardless of whether or not Notes > Transposing Score is enabled.
l TransposingDiatonicBass
Returns the diatonic pitch of the altered bass note for the specified chord symbol, if present, as if the
score is shown at transposed pitch, but regardless of whether or not Notes > Transposing
Score is enabled.
l TransposingRootAsString
Returns a string representing the pitch of the root note for the specified chord symbol as if the score
is shown at transposed pitch, but regardless of whether or not Notes > Transposing Score is
enabled.
l TransposingBassAsString
Returns a string representing the pitch of the altered bass note for the specified chord symbol, if
present, as if the score is shown at transposed pitch, but regardless of whether or not Notes >
Transposing Score is enabled.
l VisibleComponents
The visible parts of the chord symbol, that is whether it displays a text chord symbol only
(TextOnly), a guitar chord diagram only (FrameOnly), both a text chord symbol and a guitar chord
diagram (FrameAndText), or whether or not the chord symbol shows a guitar chord diagram based
on the type of instrument to which it is attached (InstrumentDependent) (read/write).

lxxxi
 4 Object Reference

GuitarScaleDiagram
Derived from a BarObject. This refers to guitar scale diagrams as created by Create > Guitar Scale
Diagram.

Methods
l GetDotFingeringsOnNthString(nth string)
Returns an array of strings containing the text that has been entered on the dots on a given string.
l GetDotSymbolsOnNthString(nth string)
Returns an array of values describing the appearance of each of the dots on a given string. The
possible values are DotStyleCircle, DotStyleFilledCircle, DotStyleSquare,
DotStyleFilledSquare, DotStyleDiamond, and DotStyleFilledDiamond.
l GetPitchesOfDotsOnNthString(nth string)
Returns an array containing the pitches of all the dots on a given string, in ascending order of pitch.
l GetPitchOfNthString(stringNum)
Returns the pitch of the given (open) string stringNum, as a MIDI pitch.

Variables
l Fingerings
The fingerings string for this scale diagram. This is a textual string with as many characters as the
scale diagram has strings (for example, six for standard guitars). Each character corresponds to a
guitar string. Use – to denote that a string has no fingering.
l Horizontal
True if the guitar scale diagram is horizontally orientated, False if it is vertically orientated
(read/write).
l LowestVisibleFret
The number of the top fret shown in the guitar scale diagram; setting the special value -1 resets the
lowest visible fret to the default for that scale diagram (read/write).
l NumberOfFrets
The number of frets in the guitar scale diagram, for example, the number of horizontal lines; setting
the special value -1 resets the number of frets to the default for that scale diagram (read/write).
l NumberOfStrings
The number of strings in the guitar scale diagram, for example, the number of vertical lines (read
only).
l Root
Returns the chromatic pitch (C = 0) of the scale’s root note (read only).
l ScaleFactor
The scale factor of the guitar scale diagram (as adjustable by the Scale parameter on the General
panel of Properties), expressed as a percentage (read/write).
l ScaleType
Returns the type of the guitar scale diagram, as specified in the list of "GuitarScaleDiagram Type
Values" on page ccxi (read only).
l ShowFingerings
Set to True if the fingerings string should be displayed, False otherwise (read only).

lxxxii
 4 Object Reference

HitPointList
Retrievable as the HitPoints variable of a score. It can be used in a for each loop or as an array with
the [n] operator—this gives access to a HitPoint object. The HitPoint objects are stored in time order,
so be careful if you remove or modify the time of the objects inside a loop. If you want to change the times
of all the hit points by the same value then use the ShiftTimes function.

Methods
l Clear()
Removes all hit points from the score.
l CreateHitPoint(timeMs,label)
Creates a hit point in the score at the given time (specified in milliseconds) with a specified string
label. Returns the index in the HitPointList at which the new hit point was created.
l Remove(index)
Removes the given hit point number.
l ShiftTimes(timeMs)
Adds the given time (in milliseconds) onto all the hit points. If the time is negative then this is
subtracted from all the hit points.

Variables
l NumChildren
Number of hit points (read only).

HitPoint
Individual element of the HitPointList object.

Methods
None.

Variables
l Bar
The bar in which this hit point occurs (read only).
l Label
The name of the hit point (read/write).
l Position
The position within the bar at which this hit point occurs (read only).
l Time
The time of the hit point in milliseconds. Note that changing this value may change the position of the
hit point in the HitPointList (read/write).

InstrumentChange
Derived from a BarObject. Provides information about any instrument changes that may exist in the
score.

lxxxiii
 4 Object Reference

Methods
None.

Variables
l FullInstrumentName
Returns the full instrument name associated with this instrument change (read/write).
l FullInstrumentNameWithFormatting
Returns the full instrument name associated with this instrument change including any changes of
font or style, if any (read/write).
l FullStaffName
Returns the full staff name associated with this instrument change (read/write).
l FullStaffNameWithFormatting
Returns the full staff name associated with this instrument change including any changes of font or
style, if any (read/write).
l ShortInstrumentName
Returns the short instrument name associated with this instrument change (read/write).
l ShortInstrumentNameWithFormatting
Returns the short instrument name associated with this instrument change including any changes of
font or style, if any (read/write).
l ShortStaffName
Returns the short staff name associated with this instrument change (read/write).
l ShortStaffNameWithFormatting
Returns the short staff name associated with this instrument change including any changes of font or
style, if any (read/write).
l StyleIdword
Returns the style ID of the new instrument; see "Instrument Types" on page clxxxvii (read only).
l TextLabel
Returns the text that appears above the staff containing the instrument change in the score (read
only).

InstrumentTypeList
Contains a list of InstrumentType objects common to a given score.

for each type variable in returns each instrument type in the list, in alphabetical order by the instrument
type’s style ID.

Array access [int n] returns the nth instrument type, in the same order as using a for each iterator, or null
if the instrument type does not exist.

Methods
None.

lxxxiv
 4 Object Reference

Variables
l NumChildren
Returns the number of unique instrument types in the list (read only).

InstrumentType
Provides information about an individual instrument type.

Methods
l Clone()
Makes an exact copy of an existing instrument type.
l PitchOfNthString(string num)
Returns the pitch of a given string in a tablature staff, with string number 0 being the lowest string on
the instrument.

Variables
l Balance
Returns the instrument’s default balance, in the range 0–100 (read only).
l Category
Returns an index representing the category of the staff type belonging to this instrument type; 0 =
pitched; 1 = percussion; 2 = tablature (read only).
l ChromaticTransposition
Returns the number of half-steps (semitones) describing the transposition of transposing instruments;
such as for B-flat Clarinet, this returns -2 (read/write).
l ChromaticTranspositionInScore
Returns the number of half-steps (semitones) describing the transposition of transposing instruments
in a score shown at concert pitch. Typically this is only used by instruments that transpose by
octaves, so this returns, for example, 12 for piccolo or –12 for guitars (read only).
l ComfortableRangeHigh
Returns the highest comfortable note (MIDI pitch) of the instrument (read only).
l ComfortableRangeLow
Returns the lowest comfortable note (MIDI pitch) of the instrument (read only).
l ConcertClefStyleId
Returns the style ID of the normal clef style of the instrument (read only).
l DefaultSoundId
Returns the default sound ID used by the instrument (read only).
l DiatonicTransposition
Returns the number of diatonic steps describing the transposition of transposing instruments; such as
for B-flat Clarinet, this returns -1 (read/write).
l DiatonicTranspositionInScore
Returns the number of diatonic steps describing the transposition of transposing instruments in a
score shown at concert pitch (read only).
l DialogName

lxxxv
 4 Object Reference

Returns the name of the instrument as displayed in the Create > Instruments dialog in Sibelius
(read/write).
l FullName
Returns the name of the instrument as visible on systems showing full instrument names (read only).
l HasBracket
Returns True if the instrument has a bracket (read only).
l HasKeySignatureOrTuning
Returns True if the instrument type has the Key signature / Tuning checkbox switched on in
the Edit Staff Type dialog.
l InstrumentTypeForChordDiagrams
Returns the style ID of the tab instrument type that determines the tuning used for chord diagrams
shown for this instrument, that is corresponding to the Tab instrument to use for string
tunings in the New/Edit Instrument dialogs.
l IsVocal
Returns True if the instrument type used has the Vocal staff option switched on, meaning that,
for example, the default positions of dynamics should be above the staff rather than below (read
only).
l NumStaveLines
Returns the number of staff lines in the staff (read only).
l NumStrings
Returns the number of strings in a tablature staff (read only).
l OtherClefStyleId
Returns the style ID of the clef style of the second staff of grand staff instruments, piano for example
(read only).
l Pan
Returns the instrument’s default pan setting, in the range –127 (hard left) to 127 (hard right) (read
only).
l ProfessionalRangeHigh
Returns the highest playable note (MIDI pitch) of the instrument for a professional player (read only).
l ProfessionalRangeLow
Returns the lowest playable note (MIDI pitch) of the instrument for a professional player (read only).
l ShortName
Returns the name of the instrument as visible on systems showing short instrument names (read
only).
l StyleId
Returns the style ID of the instrument; see "Global Constants" on page clxxx (read only).
l TransposingClefStyleId
Returns the style ID of the clef to be used when Notes > Transposing Score is enabled (read only).

KeySignature
Derived from a BarObject.

lxxxvi
 4 Object Reference

Methods
None.

Variables
l AsText
The name of the key signature as a string (read only).
l IsOneStaffOnly
True if this key signature belongs to one staff only (read only).
l Major
True if this key signature is a major key (read only).
l Sharps
The number of sharps (positive) or flats (negative) in this key signature (read only).

Line
Anything you can create from the Create > Line dialog is a Line object, such as CrescendoLine,
DiminuendoLine, and so on. These objects are derived from a BarObject.

Methods
None.

Variables
l Duration
The total duration of the line, in 1/256th quarters (read/write).
l EndBarNumber
The bar number in which the line ends (read only).
l EndPosition
The position within the final bar at which the line ends (read only).
l RhDx
The horizontal graphic offset of the right-hand side of the line, in units of 1/32 spaces (read/write).
l RhDy
The vertical graphic offset of the right-hand side of the line from the center staff line, in units of 1/32
spaces, positive going upwards (read/write).
l StyleId
The identifier of the line style associated with this line (read only).
l StyleAsText
The name of the line style associated with this line (read only).

LyricItem
Derived from a BarObject

Methods
None.

lxxxvii
 4 Object Reference

Variables
l Duration
The total duration of the lyric line, in 1/256th quarters (see "Line" on the previous page) (read/write).
l NumNotes
Gives the number of notes occupied by this lyric item (read/write). Note that changing this value does
not automatically change the length of the lyric line; you also need to set the lyric line’s
Duration variable to the correct length.
l StyleAsText
The text style name (read/write).
l StyleId
The identifier of the text style of this lyric (read/write).
l SyllableType
An integer indicating whether the lyric is the end of a word (EndOfWord) or the start or middle of one
(MiddleOfWord) (read/write). This affects how the lyric is jusitifed, and the appearance of hyphens
that follow it. EndOfWord and MiddleOfWord are global constants; see "SyllableTypes for
LyricItems" on page ccvii.
l Text
The text as a string (read/write).

NoteRest
Derived from a BarObject. A NoteRest contains Note objects, stored in order of increasing diatonic
pitch. For each variable it returns the notes in the NoteRest.

Methods
l AddAcciaccaturaBefore(sounding pitch,[duration[,tied [,voice [,diatonic pitch[,string number
[,force stem dir]]]]]])
Adds a grace note with a slash on its stem (acciaccatura) before a given NoteRest. The duration
should be specified as normal, for example, 128 would create a grace note with one beam/flag. The
optional tied parameter should be True if you want the note to be tied. Voice 1 is assumed unless the
optional voice parameter (with a value of 1, 2, 3 or 4) is specified. If force stem dir is set to True (the
default), stems of graces notes in voices 1 and 3 always point upwards, and stems of notes in voices 2
and 4, downwards. You can also set the diatonic pitch, that is the number of the “note name” to
which this note corresponds, 7 per octave (35 = middle C, 36 = D, 37 = E and so on). If a diatonic pitch
of zero is given then a suitable diatonic pitch is calculated from the MIDI pitch. The optional string
number parameter gives a string number for this note, which is only meaningful if the note is on a
tablature stave. If this parameter is not supplied then a default string number is calculated based on
the current tablature stave type and the guitar tab fingering options (specified on the Note Input
page of File > Preferences). Returns the Note object created (to get the NoteRest containing
the note, use [Link]).
Note that adding a grace note before a NoteRest always creates an additional grace note, just to the
left of the note/rest to which it is attached. If you wish to create grace notes with more than one
pitch, you should call AddNote on the object returned.
l AddAppoggiaturaBefore(sounding pitch,[duration[,tied [,voice [,diatonic pitch[,string number
[,force stem dir]]]]]])
Identical to AddAcciaccaturaBefore, only no slash is added to the note’s stem.
l AddNote(pitch[,tied[,diatonic pitch[,string number]]])

lxxxviii
 4 Object Reference

Adds a note with the given MIDI pitch (60 = middle C), for example to create a chord. The optional
second parameter specifies whether or not this note is tied (True or False). The optional third
parameter gives a diatonic pitch, which is the number of the ‘note name’ to which this note
corresponds, 7 per octave (35 = middle C, 36 = D, 37 = E and so on). If this parameter is 0 then a
default diatonic pitch is calculated from the MIDI pitch. The optional fourth parameter gives a string
number for this note, which is only meaningful if the note is on a tablature stave. If this parameter is
not supplied then a default string number is calculated based on the current tablature stave type and
the guitar tab fingering options (specified on the Notes page of File > Preferences). Returns
the Note object created.
l Delete()
Deletes all the notes in the NoteRest, converting the entire chord into a rest of similar duration.
l FlipStem()
Flips the stem of this NoteRest—this acts as a toggle.
l GetArticulation(articulation number)
Returns True or False depending on whether the given articulation is currently set on this note. The
valid articulation numbers are defined in "Articulations" on page ccvii.
l NoteRest[array element]
Returns the nth note in the chord, in order of increasing diatonic pitch (counting from 0). For
example,
NoteRest[0] returns the lowest note (in terms of diatonic pitch—see AddNote below).
l RemoveNote(note)
Removes the specified Note object.
l SetArticulation(articulation number,set)
If set is True, turns on the given articulation; otherwise turns it off. The valid articulation numbers are
defined in "Articulations" on page ccvii.
l Transpose(degree, interval type[,keep double accs])
Transposes the entire NoteRest up or down by a specified degree and interval type. To transpose up,
use positive values for degree; to transpose down, use negative values. Note that degrees are 0-
based, so 0 is equal to a unison, 1 to a second and so on. For descriptions of the various available
interval types, see "Global Constants" on page clxxx. By default, Sibelius transposes using double
sharps and flats where necessary, but this behavior may be suppressed by setting the keep double
accs flag to False.
For help in calculating the interval and degree required for a particular transposition, see the
documentation for the [Link] and [Link]
methods.

Variables
l ArpeggioDx
The horizontal offset of the arpeggio line on the NoteRest (read/write), in units of 1/32nd of a space
(the distance between two adjacent staff lines).
l ArpeggioType
The type of note-attached arpeggio line present on the NoteRest. Values are ArpeggioTypeNone,
ArpeggioTypeNormal, ArpeggioTypeUp, ArpeggioTypeDown (read/write).
l ArpeggioTopDy
The vertical offset of the top of the note-attached arpeggio line on the NoteRest (read/write), in units
of 1/32nd of a space.

lxxxix
 4 Object Reference

l ArpeggioBottomDy
The vertical offset of the bottom of the note-attached arpeggio line on the NoteRest (read/write), in
units of 1/32nd of a space.
l ArpeggioHidden
Returns True if the note-attached arpeggio line on the NoteRest is hidden (read/write).
l Articulations
Lets you copy a set of articulations from one NoteRest to another (read/write), for example:
l [Link] = [Link];
l Beam
Takes values StartBeam, ContinueBeam, NoBeam and SingleBeam. (see "Global Constants" on
page clxxx for details). These correspond to the keys 7, 8, * (/ on Mac) and / (* on Mac) on the third
(F9) Keypad layout.
l CrossStaff
Returns the following values pertaining to cross-staff beaming: 0 (Not Crossed), 1 (Crossed Above), 2
(Crossed Below). If cross-staff beaming has been applied to a note, but there is no staff available
above or below the original staff, CrossStaff returns –1 (Crossed Above, No Upper Staff) or –2
(Crossed Below, No Lower Staff).
l DoubleTremolos
Gives the number of double tremolo strokes starting at this note, in the range 0–7. Means nothing for
rests. To create a double tremolo between two successive notes, ensure they have the same duration
and set the DoubleTremolos of the first one (read/write).
l Duration
The duration of the note rest (read only).
l FallDx
The horizontal offset of a fall, if present on the NoteRest (read/write), in units of 1/32nd of a space.
l FallType
The type of note-attached fall present on the NoteRest. Values are FallTypeNone,
FallTypeNormal and FallTypeDoit (read/write)
l FeatheredBeamType
Returns one of three values, based on whether a note is set to produce a feathered beam. Values are
FeatheredBeamNone (0), FeatheredBeamAccel (1) and FeatheredBeamRit (2) (read/write).
l GraceNote
l True if it’s a grace note (read only).
l HasStemlet
Returns True if the note is showing a stemlet, according either to the state of the Use stemlets
on beamed rests option on the Beams and Stems page of Engraving Rules or the stemlet
button on the Keypad (read only).
l Highest
The highest Note object in the chord (read only).
l IsAcciaccatura
l True if it’s an acciaccatura, that is. a grace note with a slash through its stem (read only).
l IsAppoggiatura

xc
 4 Object Reference

l True if it’s an appoggiatura, that is a grace note without a slash through its stem (read only).
l Lowest
The lowest Note object in the chord (read only).
l NoteCount
The number of notes in the chord (read only).
l ParentTupletIfAny
If the NoteRest intersects a tuplet, the innermost Tuplet object at that point in the score is returned.
Otherwise, null is returned (read only).
l PositionInTuplet
Returns the position of the NoteRest relative to the duration and scale-factor of its parent tuplet. If
the NoteRest does not intersect a tuplet, its position within the parent Bar is returned as usual (read
only).
l RestPosition
The vertical position of a rest (read/write).
l ScoopDx
The horizontal offset of a scoop or plop, if present on the NoteRest (read/write), in units of 1/32nd of a
space.
l ScoopType
The type of note-attached scoop present on the NoteRest. Values are ScoopTypeNone,
ScoopTypeNormal, ScoopTypePlop (read/write).
l StemFlipped
l True if the stem is flipped (read only).
l StemletType
Provides information about whether the NoteRest is set to display a stemlet using the options on the
Keypad. Returns either StemletCustomOff (in which case the NoteRest definitely does not show a
stemlet), StemletCustomOn (in which case the NoteRest definitely does show a stemlet), or
StemletUseDefault (in which case you should use the read-only variable HasStemlet to
determine whether the NoteRest currently shows a stemlet) (read/write).
l Stemweight
Returns the stem weight of a note, taking beams into account (read only). For an unbeamed note,
this is the sum of the stave positions of all the notes in the NoteRest, where the stave position of the
middle line is zero and the position increases as you move up the stave and decreases as you move
downwards. For a beamed note, it is the sum of all the stem weights of the NoteRests under the beam
(treated as though they were unbeamed).
There are some special cases. If a note has its stem direction forced due to voicing, then the stem
weight is one of the global constants StemweightUp or StemweightDown. If a note has its stem
direction forced due to the “flip” flag being set, the stem weight is either StemweightFlipUp or
StemweightFlipDown.
If the stem weight is less than zero, the stem points up, otherwise it points down.
l SingleTremolos
Gives the number of tremolo strokes on the stem of this note, in the range –1 (for “z on stem”) to 7.
Means nothing for rests (read/write).

xci
 4 Object Reference

Note
Only found in NoteRests. Correspond to individual noteheads.

Methods
l Delete()
Removes a single note from a chord.
l Transpose(degree, interval type[,keep double accs])
Transposes and returns a single Note object up or down by a specified degree and interval type*. To
transpose up, use positive values for degree; to transpose down, use negative values. Note that
degrees are 0-based, so 0 is equal to a unison, 1 to a second and so on. For descriptions of the
various available interval types, see "Global Constants" on page clxxx. By default, Sibelius
transposes using double sharps and flats where necessary, but this behavior may be suppressed by
setting the keep double accs flag to False. For help in calculating the interval and degree required
for a particular transposition, see the documentation for the [Link] and
[Link] methods.

g Individual note objects cannot be transposed diatonically.

Variables
l Accidental
The accidental, for which global constants such as Sharp, Flat and so on are defined; see "Global
Constants" on page clxxx (read only).
l AccidentalStyle
The style of the accidental (read/write). This can be any of following four global constants:
NormalAcc,
HiddenAcc, CautionaryAcc (which forces an accidental to appear always) and BracketedAcc
(which forces the accidental to
be drawn inside brackets).
l Bracketed
The bracketed state of the note, as shown on the F9 layout of the Keypad (read/write).
l Color
The color of this Note (read/write). The color value is in 24-bit RGB format, with bits 0–7 representing
blue, bits 8–15 green, bits 16–23 red and bits 24–31 ignored. Since ManuScript has no bitwise
arithmetic, these values can be a little hard to manipulate; you may find the individual accessors for
the red, green and blue components to be more useful (see below).

g When all Notes in a given NoteRest are the same color, then that color is also promoted to the
parent NoteRest itself. This allows backwards compatibility with versions of Sibelius prior to 8.3
that did not support the individual coloring of Notes. Coloring of NoteRest-attached objects,
such as articulations and rhythm dots is not supported.
l ColorAlpha
The alpha channel component of the color of this Note, in the range 0–255 (read/write).
l ColorRed
The red component of the color of this Note, in the range 0–255 (read/write).
l ColorGreen
The green component of the color of this Note, in the range 0–255 (read/write).

xcii
 4 Object Reference

l ColorBlue
The blue component of the color of this Note, in the range 0–255 (read/write).
l DiatonicPitch
The diatonic pitch of the note, that is the number of the “note name” to which this note corresponds,
7 per octave (35 = middle C, 36 = D, 37 = E and so on). (read/write)

g If [Link] is changed from the full score (not a dynamic part), the written pitch and
spelling of any accidental is changed in both the full score and the part (where there is no
difference in spelling). If changed from a part, Sibelius respells any accidental in the part only,
leaving the full score unchanged. In both cases, while there might be a difference in written
pitch, Sibelius guarantees that there is never a difference in the sounding pitch of a note
between a part and the full score.
l IsAccidentalVisible
Returns True if the accidental on the note is visible, which is the equivalent of whether or not the
corresponding button on the Keypad is illuminated for that note (read only).
l Hidden
Returns True if the individual note is hidden (read/write).
l LvTie
Is True if the note has an L.V. tie (read/write).
l Name
The pitch of the note as a string (read only).
l NoteStyle
The index of the notehead style of this Note (read/write). The styles correspond to those accessible
from the Notes panel of the Properties window in Sibelius; see "Note Style Names" on page ccvi for a
complete list of the defined NoteStyles.
l NoteStyleName
The name of the notehead style of this Note (read/write). If an attempt is made to apply a non-
existent style name, the note in question retains its current notehead.
l OriginalDeltaSr
The Live start position of this notehead (in 1/256th quarters), as shown in the Playback
panel of Properties (read/write). This value can be positive or negative, indicating that the note is
moved forwards or backwards.
l OriginalDuration
The Live duration of this notehead (in 1/256th quarters), as shown in the Playback panel of
Properties (read/write).
l OriginalVelocity
The Live velocity of this notehead (in MIDI volume units, 0–127), as shown in the Playback
panel of Properties (read/write). Note that the word “original” refers to the fact that this data is
preserved from the original performance if the score was imported from a MIDI file or input using
Flexi-time. For further details on this value, and the ones following below, see "Live Playback" in the
Avid Sibelius Reference Guide.
l ParentNoteRest
The NoteRest object that holds this note (read only).
l Pitch

xciii
 4 Object Reference

The MIDI pitch of the note, in semitones, 60 = middle C (read only).

l Slide
Is True if the note has a slide, False otherwise (read/write).
l SlideStyleId
The slide line style state of the note, allowing you to attach/detach glissandi and other lines to a note
(read/write).
The following Line styles are available by default (as seen in the Inspector):
[Link]
[Link]
[Link]
[Link]

You can define and assign additional custom Line styles not based on the available default Line
styles. For example:
// Add/set a note slide style
[Link] = "[Link]";
// Log a note slide style to the plug-in trace window
Trace([Link]);
// Using a custom line style
[Link] = "[Link].0000001";
l StringNum
The string number of this note, only defined if the note is on a tablature stave. If no string is specified,
reading this value gives –1. Strings are numbered starting at 0 for the bottom string and increasing
upwards (read only).
l Tied
Is True if the note is tied to the following note (read/write).
l TiedInto
Is True if the note has a tie-into object attached to the left-hand side of the note (read/write).
l TieIntoStyle
The name of the tie-into object’s style for this Note (read/write). Valid tie-into style names include:
Solid, Dashed, Dotted. If an attempt is made to apply a non-existent style name, the tie-into object in
question retains its current style.
l TieStyle
The name of the tie style for this Note (read/write). Valid tie style names include: Solid, Dashed,
Dotted. If an attempt is made to apply a non-existent style name, the tie in question retains its
current style.
l WrittenAccidental
The accidental, taking transposition into account (read only).
l WrittenDiatonicPitch
The written diatonic pitch of the note, taking transposition into account if
[Link] is True (35 = middle C).
l WrittenName
The written pitch of the note as a string (taking transposition into account) (read only).
l WrittenPitch

xciv
 4 Object Reference

The written MIDI pitch of the note, taking transposition into account if [Link]
is True (60 = middle C) (read only).
l UseOriginalDeltaSrForPlayback
Is True if the Live start position of this Note should be used for Live Playback. Corresponds to
the Live start position checkbox in the Playback panel of the Properties window.
l UseOriginalDurationForPlayback
Is True if the Live duration of this Note should be used for Live Playback. Corresponds to the
Live duration checkbox in the Playback panel of the Properties window.
l UseOriginalVelocityForPlayback
Is True if the Live velocity of this Note should be used for Live Playback. Corresponds to the
Live velocity checkbox in the Playback panel of the Properties window.

PageNumberChange
Provides access to get and set the attributes of a page number change at the end of a bar or on a blank
page.

Methods
l SetFormatChangeOnly(format change only)
If format change only is True, this has the same effect as switching off the New page number
check box on the Page Number Change dialog in Sibelius. The page numbering continues counting
consecutively, but it is possible to (for example) hide a group of page numbers and restore visibility at
a later point on the score without having to keep track of the previous page numbers.
l SetHideOrShow(page number visibility)
Takes one of the three Page number visibility global constants to determine the visibility of
the initial page number change and its subsequent pages; see "Global Constants" on page clxxx.
l SetPageNumber(page number)
Takes an integral number specifying the new number you wish to assign to the page.
l SetPageNumberFormat(format)
Takes one of the four Page number format global constants to change the format used to display
the page number change; see "Global Constants" on page clxxx.

Variables
l BarNumber
Returns the bar number expressed as an integer (read only).
l HideOrShow
Returns one of the three Page number visibility global constants; see "Global Constants" on
page clxxx (read only).
l PageNumber
Returns the page number expressed as an integer. For example, page x when using Roman numerals
would be 10, or 24 with alphabetics (read only).
l PageNumberAsString
Returns the page number change as visible on the corresponding page in Sibelius (read only).
l PageNumberBlankPageOffset

xcv
 4 Object Reference

Returns the blank page offset of the page number change, or 0 if there are no blank pages following
the bar containing the page number change (read only).
l PageNumberFormat
Returns one of four Page number format global constants describing the format of the page
number change; see "Global Constants" on page clxxx (read only).

PluginList
An array that is obtained from [Link]. It can be used in a for each loop or as an array with
the [n] operator to access each Plugin object.

Methods
l Contains(pluginName)
Returns True if a plug-in with the given name is installed. This can be used to query whether a plug-
in is installed before you try to call it.

Variables
l NumChildren
Number of plug-ins (read only).

Plugin
This represents an installed plug-in. Typical usage:

for each p in [Link]

{
trace("Plugin: " & [Link]);
}

Methods
The following methods are intended to allow you to check the existence of specific methods, data and
dialogs in plug-ins, which allows you to check in advance that calling a method in another plug-in succeed,
and fail gracefully if the method is not found:
l MethodExists(method)
Returns True if the specified method exists in the current Plugin object.
l DataExists(data)
Returns
l True if the specified data exists in the current Plugin object.
l DialogExists(dialog)
Returns True if the specified dialog exists in the current Plugin object.

Variables
l File
The File object corresponding to the file that the plug-in was loaded from (read only).
l Name
The name of the plug-in (read only).

xcvi
 4 Object Reference

RehearsalMark
Derived from a BarObject and found in the system staff only. RehearsalMarks have an internal numbering
and a visible text representation, both of which can be read from ManuScript.

Methods
None.

Variables
l Mark
The internal number of this rehearsal mark. By default rehearsal marks are consecutive (with the first
one numbered zero), but the user can also create marks with specific numbers.
l MarkAsText
The textual representation of this rehearsal mark as drawn in the score. This is determined by the
House Style > Engraving Rules options, and can take various forms (numerical or
alphabetical).

Score
You can obtain the Score object by way of the Sibelius object, for example:

score = [Link];

A Score contains one System Staff and one or more Staff objects.

for each variable in returns each staff in the score or the current dynamic part in turn (not the system
staff).

for each type variable in returns the objects in the score in chronological order, from the top staff to the
bottom staff (for simultaneous objects) and then from left to right (again, not including the system staff).

Methods
l AddBars(n)
Adds n bars to the end of the score.
l ApplyStyle(style file,"style",["style"])
Imports named styles from the given house style file (.lib) into the score. The style file parameter
can either be a full path to the file, or just the name of one of the styles that appears in the House
Style > Import House Style dialog. You can import as many “style” elements as you like in the
same method. Style names are as follows:
ENGRAVING RULES, DOCSETUP, HOUSE, TEXT, SYMBOLS, LINES, NOTEHEADS, CLEFS,
DICTIONARY, SPACINGRULE, DEFAULTPARTAPPEARANCE, INSTRUMENTSANDENSEMBLES,
MAGNETICLAYOUTOPTIONS or
ALLSTYLES.
For instance:
[Link]("C:\[Link]", "HOUSE", "TEXT");

To import engraving rules for a a house style, but not the document settings, use the
ENGRAVINGRULES constant. To import document settings for a house style, but not the engraving
rules, use the DOCSETUP constant. To import both the engraving rules and document setup of a
house style, use the HOUSE constant. Note that the constant HOUSE refers, for historical reasons, only

xcvii
 4 Object Reference

to those options in the House Style > Engraving Rules and Layout > Document Setup
dialogs, not the entire house style. To import the entire House Style, use the ALLSTYLES constant.
The constants: ENGRAVINGRULES, DOCSETUP, HOUSE, and ALLSTYLES are mutually exclusive and
should not be used in combination.
When importing Text Styles from a House Style, ApplyStyles() lets you import the “Music Text
Font” using the TEXT Style name (or any Style name that depends on TEXT).
l ClefStyleId(clef style name)
Returns the identifier of the clef style with the given name, or the empty string if there is no such clef
style.
l CreateInstrument(style ID[,change names,["full name",["short name"]]])
Creates a new instrument, given the style ID of the instrument type required (see "Instrument Types"
on page clxxxvii). If you want to supply the instrument names to be used in the score, set the optional
change names parameter to True, then supply strings for the full name and short name. Returns
True if the instrument was created successfully and False if the instrument type could not be
found.
l CreateInstrumentAtBottom(style ID[,change names,["full name",["short name"]]])
Behaves the same way as CreateInstrument, only the new instrument is always created below all
other instruments that currently exist in the score. This can be useful when programmatically copying
a list of staves/instruments from one score to another, as you can guarantee the ordering of the
staves are the same in both scores.
l CreateInstrumentAtBottomReturnStave(style ID[,change names,["full name",["short
name"]]])
As above, but returns the Staff object created, or null if unsuccessful.
l CreateInstrumentAtTop(style ID[,change names,["full name",["short name"]]])
Behaves in exactly the same way as CreateInstrumentAtBottom, only the new instrument is
always created above all other instruments that currently exist in the score.
l CreateInstrumentAtTopReturnStave(style ID[,change names,["full name",["short
name"]]])
As above, but returns the Staff object created, or null if unsuccessful.
l CreateInstrumentReturnStave(style ID[,change names,["full name",["short name"]]])
Like CreateInstrument, but returns the Staff object created, or null if unsuccessful. Note that if
the instrument being created contains more than one staff (such as piano or harp), the top stave of
the instrument in question is returned.
l ExportHouseStyle(filename)
Exports the house style of the score to either the default “House Style” folder (if the argument is a
filename), or to a user-specified path (if the argument is a valid file path).
l ExportPartsAsPDF(filename[,single file[,part IDs[,include score]]])
Exports one dynamic part, a selection of dynamic parts, or all dynamic parts in PDF format, either
concatenated into a single file, or as separate files. The filename parameter should be a complete
path. It may contain the following tokens, which Sibelius expands automatically to generate a
complete filename:
%f = Score filename
%t = Score title (as specified in the Title field in File > Info)
%p = Part name (as specified in the Part name field in File > Info)
%n = Part number

xcviii
 4 Object Reference

%o = Total number of parts

%d = Date (format YYYY-MM-DD)
%h = Time (format HHMM)
The Boolean parameter single file specifies whether the chosen parts should be extracted into
separate PDF files or concatenated into a single PDF file. This parameter defaults to True if not
specified.
To specify which parts to export, create a sparse array of part IDs, and pass this in as the third
parameter, part IDs. For example:
s = [Link];
partsToExport = CreateSparseArray();
parts = [Link];
firstNPartsToExport = 2;
i = 0;
for each part in parts {
if (i <= firstNPartsToExport) { // <= because the first "part" in the
//DynamicPartsCollection is the full score.
[Link](part);
}
i = i + 1;
}
[Link]("c:\\%f - %[Link]", true, partsToExport);

To export all parts, pass in 0 instead of a sparse array.

The final optional Boolean parameter, include score, defaults to False. If set to True, the full score is
also be exported along with the parts.
l ExportScoreAsPDF(filename)
Exports the full score as a PDF, with the specified filename, which should be a complete path. The
filename parameter may use the same tokens as the ExportPartsAsPDF() method—see above.
l ExtractParts([show_dialogs[,parts path[,open parts]]])
Extracts parts from the score. The first optional Boolean parameter can be False, in which case the
parts are extracted without showing an options dialog. The second optional parameter specifies a
folder into which to extract the parts (must end with a trailing folder separator). The third optional
Boolean parameter, which defaults to True, specifies whether the extracted parts should be opened
immediately, or simply saved.
l FreezeMagneticLayoutPositions()
Does the same as selecting the whole score and choosing Layout > Magnetic Layout > Freeze
Positions, which explicitly sets the Dx/Dy of every object to the position produced by Magnetic
Layout, then disables Magnetic Layout for each object.
l GetLocationTime(bar number[,position[,pass]])
Returns the time of a given bar (by passing in its bar number) and optional position within that bar in
the score in milliseconds. If the score contains repeats, the value returned is always the time on the
first pass through the score, but you can supply the optional pass parameter to specify a particular
pass in the repeat structure. If the bar and position are not valid, the return value is -1.
l GetVersions()
Returns the score’s VersionHistory object (see "VersionHistory" on page cxxxvii).
l HideEmptyStaves(startStaveNum,endStaveNum,startBarNum,endBarNum)
Hides any empty staves between startStaveNum and endStaveNum, from startBarNum to
endBarNum. Both the staff numbers and bar numbers are 1-based, and refer to the active part.

xcix
 4 Object Reference

l GetVersions()
Returns the score’s VersionHistory object (see "VersionHistory" on page cxxxvii).
l InsertBars(n,barNum[,length])
Inserts n bars before bar number barNum. If no length has been specified, the bar is created with the
correct length according to the current time signature. However, irregular bars may also be created
by specifying a value for length.
l InternalPageNumToExternalPageNum(pagenum)
Returns a string containing the external page number of the given internal page number pagenum.
l IsScoreSubset()
Returns True if the current active score view is a score subset (read only).
l LineStyleId(line style name)
Returns the identifier of the line style with the given name, or the empty string if there is no such line
style.
l NoteStyleIndex(notehead style name)
Returns the index of the note style with the given name, or –1 if there is no such note style.
l NthStaff(staff index from 1)
Returns the nth staff of the score or the current dynamic part.
l OptimizeStaffSpacing (from staff number[, to staff number[,from bar[,to bar]]])
Does the equivalent of Layout > Optimize Staff Spacing for the given range of staves or a
whole score. from staff number must be specified; if to staff number is not specified, Sibelius
optimizes the distances between from staff number and the bottom staff in the score; if from bar is
not specified, Sibelius sets it to 1; if to bar is not specified, Sibelius sets it to the last bar of the score.
l PlayLiveTempo(play)
Switches Play > Live Tempo on or off; set play to True to switch it on, or False to switch it off.
l RemoveAllHighlights()
Removes all highlights in this score.
l RemoveVideo()
Removes an attached video from the score.
l RenameTextStyle("old name","new name")
Renames a text style to a new name.
l Save(filename)
Saves the score, overwriting any previous file with the same name.
l SaveAs(filename,type[,use_defaults,foldername])
Saves the score in a specified format, overwriting any previous file with the same name. The optional
argument use_defaults only applies to graphics files, and specifies whether or not the default
settings are to be used. When set to False, the Export Graphics dialog appears and allows the
user to make any necessary adjustments. The optional foldername specifies the folder in which the
file is to be saved, and creates the specified folder if it does not exist. The folder name parameter
must not end with a path separator (which is “\\” on Windows).
The possible values for type are:
SIBL Sibelius format (current version)
EMF EMF
BMP Windows bitmap

c
 4 Object Reference

PICT PICT format

PDF PDF format
PNG PNG format
Midi MIDI format
TIFF TIFF format
MUSICXML Uncompressed MusicXML
MXL Compressed MusicXML

g The file type value for Uncompressed musicXML files was formerly “XML" rather than
"MUSICXML." XML still represents a valid file type, but the file is saved with a .musicxml
extension.

So, to save a file using the current Sibelius file format, you would write [Link]
(“[Link]”, “SIBL”);
l SaveAsAudio(filename[,include all staves[,play from start[,bit depth[,sample rate]]]])
Creates a WAV file (PC) or AIFF file (Mac) of the score, using File > Export > Audio.
SaveAsAudio supports all available bit depths and sample rates. If include all staves is True (the
default), Sibelius clears any existing selection from the score so every instrument is recorded,
otherwise only selected staves are exported. If play from start is True (the default), Sibelius records
the entire score from beginning to end, otherwise from the current position of the playback line. Note
that these functions only have an effect if your current playback configuration consists of solely VST
or AU devices. The functions returns True if successful, otherwise False (including if you Cancel
during export).
l SaveAsCompressedAudio(filename[,include all staves[,play from start[,bit rate[,sample rate]]]])
Creates an MP3 file of the score, using File > Export > Audio. SaveAsCompressedAudio
supports all available MP3 bit rates and sample rates. If include all staves is True (the default),
Sibelius clears any existing selection from the score so every instrument is recorded, otherwise only
selected staves are exported. If play from start is True (the default), Sibelius records the entire score
from beginning to end, otherwise from the current position of the playback line. Note that these
functions only have an effect if your current playback configuration consists of solely VST or AU
devices. The functions returns True if successful, otherwise False (including if you Cancel during
export).
l SaveAsEarlierVersion(versionIdentifier, filename[, foldername])
Saves the score in the format of an earlier version of Sibelius, overwriting any previous file with the
same name. The optional foldername specifies the folder in which the file is to be saved. Note that the
folder, if provided, must already exist for this method to be successful. For more information on how
to obtain the version identifier argument, also see [Link] and
[Link].
l SaveAsSibelius2(filename[,foldername])
Saves the score in Sibelius 2 format, overwriting any previous file with the same name. The optional
foldername specifies the folder in which the file is to be saved. Note that saving as Sibelius 2 may
alter some aspects of the score; see Sibelius Reference for full details.
l SaveAsSibelius3(filename[,foldername])
Saves the score in Sibelius 3 format. See documentation for SaveAsSibelius2 above.
l SaveAsSibelius4(filename[,foldername])
Saves the score in Sibelius 4 format. See documentation for SaveAsSibelius2 above.
l SaveAsSibelius5(filename[,foldername])
Saves the score in Sibelius 5 format. See documentation for SaveAsSibelius2 above.

ci
 4 Object Reference

l SaveAsSibelius6(filename[,foldername])
Saves the score in Sibelius 6 format. See documentation for SaveAsSibelius2 above.
l SaveAsSibelius7(filename[,foldername])
Saves the score in Sibelius 7 format. See documentation for SaveAsSibelius2 above.
l SaveAsSibelius7_5(filename[,foldername])
Saves the score in Sibelius 7.5 format. See documentation for SaveAsSibelius2 above.
l SaveAsSibelius8(filename[,foldername])
Saves the score in Sibelius 8 format. See documentation for SaveAsSibelius2 above.
l SaveAsSibelius8_5(filename[,foldername])
Saves the score in Sibelius 8.1 format. See documentation for SaveAsSibelius2 above.
l SaveAsSibelius8_6(filename[,foldername])
Saves the score in Sibelius 8.6 format. See documentation for SaveAsSibelius2 above.
l SaveAsSibelius2020_1(filename[,foldername])
Saves the score in Sibelius 2020.1 format. See documentation for SaveAsSibelius2 above.
l SaveAsSibelius2020_1(filename[,foldername])
Saves the score in Sibelius 2020.1 format. See documentation for SaveAsSibelius2 above.
l SaveCopyAs(filename[,foldername])
Saves a copy of the score in the current version’s format without updating the existing score’s file
name in Sibelius.
l SetPlaybackPos(bar number,sr)
Sets the position of the playback line to a given bar number and rhythmic (sr) position.
l ShowEmptyStaves(startStaveNum,endStaveNum,startBarNum,endBarNum)
Shows any empty staves currently hidden using Layout > Hiding Staves > Hide Empty
Staves between startStaveNum and endStaveNum, from startBarNum to endBarNum. Both the staff
numbers and bar numbers are 1-based, and refer to the active part.
l [Link];
l StaveTypeId(stave type name)
Returns the identifier of the stave type with the given name, or the empty string if there is no such
stave type.
l SystemCount(page num)
The number of systems on a page (the first page of the score is page 1).
l SymbolExists(symbol)
Returns True if the symbol index or name symbol is found in the score, otherwise False.
l SymbolIndex(symbol name)
Returns the index of the symbol with the given name, or –1 if there is no such symbol.
l TextStyleId(text style name)
Returns the identifier of the text style with the given name, or the empty string if there is no such text
style.
l ViewLiveTempo(view)
Switches View > Live Tempo on or off; set view to True to switch it on, or False to switch it off.

cii
 4 Object Reference

Variables
l Arranger
Arranger of score from File > Score Info (read/write).
l Artist
Artist of score from File > Score Info (read/write)
l AutoOptimizeEnabled
Activates the Auto-Optimize Staff Spacing layout option (read/write)
l Barlines
Returns a Barlines object containing information about the barline groupings in the score (read
only).
l BarPlaybackOrder
Returns a sparse array containing a list of integers that describes the order in which the bars are
played, according to the repeat structure of the score or the settings in Play > Interpretation
> Repeats. To set the order in which bars should be played, pass in a sparse array containing a list
of integers describing the order in which bars should be played back. To return to the score’s
automatically-determined playback order, pass in null (read/write).
l BarPlaybackOrderString
Returns a string describing the order in which the bars are played, according to the repeat structure
of the score. The string uses the same format as the read-out in Play > Interpretation >
Repeats, for example, “1–8,
1–5,9–12”. To set the order in which bars should be played, pass in a string of the appropriate format.
To return the score’s automatically-determined playback order, pass in null (read/write).
l BracketsAndBraces
Returns a BracketsAndBraces object containing information about the brackets and braces in the
score (read only).
l Composer
Composer of score from File > Score Info (read/write).
l ComposerDates
Value of Composer’s dates from File > Score Info (read/write).
l Copyist
Copyist of score from File > Score Info (read/write).
l Copyright
Copyright of score from File > Score Info (read/write).
l CurrentDynamicPart
Returns or sets the current DynamicPart object for the Score (read/write). Sibelius does not
automatically display the new part: use [Link]() to change the displayed
part.
l CurrentPlaybackPosBar
Returns the bar number in which the playback line is currently located.
l CurrentPlaybackPosSr
Returns the rhythmic position within the bar at which the playback line is currently located.
l Dedication

ciii
 4 Object Reference

Dedication of score from File > Score Info (read/write).

l DocumentSetup
Returns a DocumentSetup object representing the settings in Layout > Document Setup (read
only).
l DynamicParts
Returns a DynamicPartCollection object representing the dynamic parts present in the Score.
This object always stays up to date, even if parts are added or deleted (read only).
l EditingLocked
True when the score is locked, preventing unintentional edits (read/write).
l EnableScorchPrinting
Corresponds to the Allow printing and saving checkbox in the Export Scorch Web Page
dialog (read/write).
l EngravingRules
Returns an EngravingRules object corresponding to selected settings in the House Style>
Engraving Rules dialog (read only).
l FileName
The filename for the score (read only).
l FocusOnStaves
Is True if View > Focus on Staves is enabled (read/write). See also
[Link].
l HitPoints
The HitPointList object for the score (read/write).
l InstrumentChanges
Value of Instrument changes from File > Score Info (read/write).
l InstrumentTypes
Returns an InstrumentTypeList containing the score’s instrument types, on which one may
execute a for each loop to get information about each instrument type within the score.
l IsDynamicPart
Returns True if the current active score view is a part (read only).
l LiveMode
Is True (1) if Play > Live Playback is on (read/write).
l Lyricist
Lyricist of score from File > Score Info (read/write).
l MagneticLayoutEnabled
Returns True if the current score has Layout > Magnetic Layout switched on (read/write).
l MainMusicFontName
Returns the name of the font specified as the Main music font (such as “Opus” or “Reprise”) in
House Style >Edit All Fonts (read/write).
l MainTextFontName
Returns the name of the font specified as the Main text font (such as “Times New Roman” or
“Arial”) in House Style > Edit All Fonts (read/write).

civ
 4 Object Reference

l MusicTextFontName
Returns the name of the font specified as the Music text font (such as “Opus Text” or “Reprise
Text”) in House Style > Edit All Fonts (read/write).
l NumberOfPrintCopies
The number of copies to be printed (read/write).
l OpusNumber
Opus number of score from File > Score Info (read/write).
l OriginalProgramVersion
The version of Sibelius in which this score was originally created, as an integer in the following
format:
(major version) * 1000 + (minor version) * 100 + (revision) * 10. So Sibelius at the time of this writing
would be 8.3.1 would be returned as 8310.
l OtherInformation
More information concerning the score from File > Score Info (read/write).
l PageCount
The number of pages in the score (read only).
l PartName
Value of Part Name from File > Score Info (read/write).
l Publisher
Publisher of score from File > Score Info (read/write).
l Redraw
Set this to True (1) to make the score redraw after each change to it, False (0) to disallow
redrawing (read/write).
l ScoreDuration
The duration of the score in milliseconds (read only).
l ScoreEndTime
The duration of the score, plus the score start time (see above), in milliseconds (read only).
l ScoreHeight
Height of a page in the score, in millimeters (read only).
l ScoreStartTime
The value of Timecode of first bar, from Play > Video and Time > Timecode and
Duration, in milliseconds (read only).
l ScoreWidth
Width of a page in the score, in millimeters (read only).
l Selection
The Selection object for the score, which is a list of selected objects (read only).
l ShowMultiRests
Is True (1) if Layout > Show Multirests is on (read/write).
l StaffCount
The number of staves in the score (read only).

cv
 4 Object Reference

l StaffHeight
Staff height, in millimeters (read only).
l Subtitle
Subtitle of score (read/write).
l SystemCount
The number of systems in the score (read only).
l SystemObjectPositions
Returns a SystemObjectPositions object corresponding to the settings in House Style >
System
Object Positions for the score (read only).
l SystemStaff
The SystemStaff object for the score (read only).
l Title
Title of score from File > Score Info (read/write).
l TransposingScore
Is True (1) if Notes > Transposing Score is on (read/write).
l UsingManualBarPlayOrder
Returns True if Manual repeats playback is chosen in Play > Interpretation >
Repeats, otherwise False (read only).
l YearOfComposition
Value of Year of composition from File > Score Info (read/write).

Selection
for each variable in returns every BarObject (which is an object within a bar) in the selection.

for each type variable in produces each object of type in the selection. Note that if the selection is a
system selection (which is surrounded by a double purple box in Sibelius) then objects in the system staff
are returned in such a loop.

Methods
l Clear()
Removes any existing selection(s) from the current active score.
l ClipboardContainsData([clipboard Id])
Returns True if the given clipboard contains data. As with the Copy and Paste methods, 0 (or no
arguments) refers to Sibelius’s internal clipboard, and all other numeric values interrogate the
temporary clipboard with the matching ID.
l Copy([clipboard Id])
Copies the music within the current selection to Sibelius’s internal clipboard or a ManuScript-specific
temporary clipboard, which goes out of scope along with the Selection object itself. If no clipboard
Id is specified, or if it is set to 0, the selection is copied to Sibelius’s internal clipboard. Any other
numeric value you pass in stores the data in a temporary clipboard adopting the ID you specify. Used
in conjunction with Paste or PasteToPosition (see below).
l Delete([remove staves])

cvi
 4 Object Reference

Deletes the music currently selected in the active score. Akin to making a selection manually in
Sibelius and hitting Delete. If remove staves is omitted or set to True, Sibelius completely removes
any wholly selected staves from the score. If you wish Sibelius to simply hide such staves instead, set
this flag to False.
l ExcludeStaff(staff number)
If a passage selection already exists in the current active score, an individual stave may be removed
from the selection using this method.
l HideSelectedEmptyStaves()
If the current selection contains staves that are empty, they are hidden (equivalent to selecting a
passage and choosing Layout > Hiding Staves > Hide Empty Staves).
l IncludeStaff(staff number)
If a passage selection already exists in the current active score, a non-consecutive stave may be
added to the selection using this method.
l Paste([clipboard Id[,reset positions]])
Pastes the music from a given clipboard to the start of the selection in the current active score. If no
clipboard Id is specified, or if it is set to 0, the data is pasted from Sibelius’s internal clipboard. Any
other numeric value you pass in takes the data from a temporary clipboard you must have previously
created with a call to Copy (see above). Returns True if successful.
If reset positions is False, the positions of any objects that have been moved by the user in the
source selection is retained in the copy. This is the default behavior. If you wish Sibelius to reset
objects to their default positions, set this flag to True. This can be useful when copying one or more
single objects (which is a non-passage selection).
Note that pasting into a score using this method overwrites any existing music. Only one copy of the
music is made, so if your selection happens to span more bars or staves than is necessary, the data is
not be duplicated to fill the entire selection area.
l PasteToPosition(stave num, bar num, position[, clipboard Id[,reset positions]])
Pastes the music from a given clipboard to a specific location in the current active score. The optional
parameters and pasting behavior works in the same way as calls to Paste.
l RestoreSelection()
Restores the selection previously recorded with a call to StoreCurrentSelection. Usefully called
at the end of a plug-in to restore the initial selection.
l Respace
Respace all notes in the current selection.
l RespaceIncludeHiddenNotes
Respace all notes in the current selection, including hidden notes.
l RespaceIgnoreHiddenNotes
Respace all notes in the current selection, excluding hidden notes.
l SelectPassage(start barNum[,end barNum[,top staveNum[,bottom staveNum[,start pos[,end
pos]]]]])
Programmatically makes a passage selection around a given area of the current active score. When
no end barNum is given, only the start barNum is selected. If neither a top- nor bottom staveNum has
been specified, every stave in the score is selected, whereas if only a top staveNum has been
supplied, only that one staff is selected. Sibelius begins the selection from the start of the first bar if
no start pos has been given, similarly completing the selection at the end of the final bar if no end pos
has been supplied.

cvii
 4 Object Reference

g The start pos and end pos you supply may be altered by ManuScript: Sibelius requires a
passage selection to begin and end at a NoteRest if it doesn’t encompass the entire bar.
l SelectSystemPassage(start barNum[,end barNum[,start pos[,end pos]]])
Programmatically makes a system selection around a given area of the current active score. When no
end barNum is given, only the start barNum is selected. Sibelius begins the selection from the start of
the first bar if no start pos has been given, similarly completing the selection at the end of the final
bar if no end pos has been supplied.

g The start pos and end pos you supply may be altered by ManuScript: Sibelius requires a
passage selection to begin and end at a NoteRest if it doesn’t encompass the entire bar.
l StoreCurrentSelection()
Stores the current selection in the active score internally. Can be retrieved with a call to
RestoreSelection (see below). Usefully called at the start of a plug-in to store the initial selection.
l Transpose(degree, interval type[,keep double accs[,transpose keys]])
Transposes the currently selected music up or down by a specified degree and interval type. To
transpose up, use positive values for degree; to transpose down, use negative values. Note that
degrees are 0-based, so 0 is equal to a unison, 1 to a second and so on. For descriptions of the
various available interval types, see "Global Constants" on page clxxx. By default, Sibelius
transposes using double sharps and flats where necessary, but this behavior may be suppressed by
setting the keep double accs flag to False. Sibelius also transposes any key signatures within the
selection by default, but can be overridden by setting the fourth parameter to False.
For help in calculating the interval and degree required for a particular transposition, see the
documentation for the [Link] and [Link]
methods.

Variables
l BottomStaff
The number of the bottom staff of a passage (read only).
l FirstBarNumber
The internal bar number of the first bar of a passage (read only).
l FirstBarNumberString
The external bar number (including any bar number format changes) of the first bar of a passage
(read only).
l FirstBarSr
The position of the start of the passage selection in the first bar (read only).
l IsPassage
True if the selection represents a passage, as opposed to a multiple selection (read only).
l IsSystemPassage
True if the selection includes the system staff (read only).
l LastBarNumber
The internal bar number of the last bar of a passage (read only).
l LastBarNumberString
The external bar number (including any bar number format changes) of the last bar of a passage
(read only).

cviii
 4 Object Reference

l LastBarSr
The position of the end of the passage selection in the last bar (read only).
l TopStaff
The number of the top staff of a passage (read only).
Copying Entire Bars
Copying passages from one location in a score to another—or even from one score to another—is very
simple. Here is an example function demonstrating how one might go about achieving this:
CopyBar(scoreSrc, barFirstSrc, barLastSrc, scoreDest, barFirstDest,
barLastDest) // This is the function signature
{
sel = [Link];
[Link]([Link], [Link],
[Link],
[Link]);
[Link](0);
selDest = [Link];
[Link]([Link], [Link],
barFirstD [Link],
[Link]);
[Link](0);
}

Note that you may use any temporary clipboard or Sibelius’s own internal clipboard if the source and
destination locations are in the same score, however you can only use Sibelius’s internal clipboard if the
data is being transfered between two individual scores. This is because the temporary clipboards belong to
the Selection object itself.

Copying Multiple Selections from One Bar to Another

Using a combination of the BarObject’s Select method and the Selection object’s Copy and
PasteToPosition methods, it is possible to copy an individual or multiple selection from one location in a
score to another. Bear in mind that Paste always pastes the material to the very start of the selection, so if
you’re copying a selection that doesn’t start at the very beginning of a bar, you’ll have to store the position
of the first item and pass it to PasteToPosition when you later come to paste the music to another bar.

This example code below copies all items from position 256 or later from one bar to another. It is assumed
that sourceBar is a valid BarObject, and destStaffNum and destBarNum contain the destination
staff number and bar number respectively:
sel = [Link]; // Get a Selection object for this score
[Link](); // Clear the current selection
clipboardToUse = 1; // This clipboard ID we’re going to use
copyFromPos = 256; // Copy all objects from this point in the source bar
posToCopyTo = 0; // Variable used to store the position of the first object copied
for each obj in sourceBar { // Iterate over all objects in the bar
if ([Link] >= copyFromPos) { // Ignore objects before the start threshold
[Link](); // Select each relevant object in turn
if (posToCopyTo = 0) {
posToCopyTo = [Link]; // Remember the position of the first item
{
}
}
[Link](clipboardToUse); // Copy the objects we’ve selected to the clipboard

cix
 4 Object Reference

[Link](destStaffNum, destBarNum, posToCopyTo, clipboardToUse); //

And paste them to the destination bar at the relevant offset

Sibelius
There is a predefined variable that represents the Sibelius program. You can use the Sibelius object to open
scores, close scores, display dialogs or (most commonly) to get currently open Score objects.

for each variable in returns each open score.

Methods
l AppendLineToFile(filename,text[,use_unicode])
Appends a line of text to the file specified (adds line feed). See comment for AppendTextFile above
for explanation of the use_unicode parameter. Returns True if successful.
l AppendLineToRTFFile(filename,text)
Appends a line of text to the file specified. Times New Roman 12pt is used, unless you specify a
change of formatting. To change formatting, use the following backslash expressions:
– \B\ bold on
– \I\ italic on
– \U\ underline on
– \n\ new line
– \b\ bold off
– \i\ italic off
– \u\ underline off
– \ffontname\ change to given font name (for example \fArial\ to switch to Arial)
– \spoints\ set the font size to a specific point size (for example \s16\ to set the font to 16pts).
Note the difference in meaning of \s in the context of adding data to an RTF file, versus its use in the
context of styling text directly within Sibelius (see "Syntax" on page xlv following).
l AppendTextFile(filename,text[,use_unicode])
Appends text to the file specified. If the optional Boolean parameter use_unicode is True, then the
string specified are exported in Unicode format; if this parameter is False then it is converted to 8-
bit Latin-1 before being added to the text file. This parameter is True by default. Returns True if
successful.
l CalculateDegree(source pitch, dest pitch, upward interval)
Takes two note names in the form of a string (for example C, G#, Bb, Fx or Ebb) and a boolean that
should be True if the interval you’re wishing to calculate is upward. Returns a 0-based number
describing the degree between the two notes.
For example, CalculateDegree(“C#”, “G”, False) would return 3.
l CalculateInterval(source pitch, dest pitch, upward interval)
Takes two note names in the form of a string (for example C, G#, Bb, Fx or Ebb) and a boolean that
should be True if the interval you’re wishing to calculate is upward. Returns a number representing
an Interval Type (see "Global Constants" on page clxxx). You can use the value returned in calls
to [Link] and [Link].
For example, CalculateInterval(“Bb”, “G#”, True) would return IntervalAugmented.
l Close(show dialogs)

cx
 4 Object Reference

Closes the current score or part view; if the current view is the last tab in the current window, the
window closes. If the optional Boolean parameter is True then warning dialogs may be shown about
saving the active score, and if it is False then no warnings are shown (and the score is not saved).
l CloseAllWindows(show dialogs)
Closes all open document windows. If the optional Boolean parameter is True then warning dialogs
may be shown about saving any unsaved scores, and if it is False then no warnings are shown (and
the scores are not saved).
l CloseAllWindowsForScore(score, showDialogs)
Closes all of the windows associated with the specified score. The second parameter, showDialogs, is
an optional Boolean.
l CloseDialog(dialogName,pluginName,returnValue)
Closes the dialog dialogName belonging to the plug-in pluginName (normally this should be set to
self), returning the Boolean value returnValue, which can be set to True (1) or False (0). Normally
you do not need to use this method to close a dialog, as you can set buttons (typically with labels like
OK or Cancel) to close the dialog and return a value, but if you want greater control over when a
dialog is closed, this method provides it.
l CloseWindow(show dialogs)
Closes the current window (that closes all of the open tabs in the current window). If the optional
Boolean parameter is True then warning dialogs may be shown about saving the score, and if it is
False then no warnings are shown (and the score is not saved).
l CommandExists(CommandID)
Returns a boolean to reflect if a given CommandID is available for execution. For example:
if ([Link](toggle_review_mode)) {}
l CreateFolder(foldername)
Creates the folder of specified foldername; returns the Folder object created if successful, or null if
it fails.
l CreateProgressDialog(caption,min value,max value)
Creates the progress dialog, which shows a slider during a long operation.
l CreateRTFFile(filename)
Creates the Rich Text Format (RTF) file specified. Any existing file with the same name is destroyed.
Returns True if successful.
l CreateTextFile(filename)
Creates the plain text file specified. Any existing file with the same name is destroyed. Returns True
if successful.
l DestroyProgressDialog()
Destroys the progress dialog.
l EarlierVersionIdFromName(versionName)
Returns an internal version identifier that can be used as input to [Link]
method. The method expects one of the names that the [Link]
variable contains.
l EnableControlById(plugin,dialog,controlID,enable)

cxi
 4 Object Reference

Dynamically enables or disables a given control on a plug-in dialog: plug-in is a Plugin object, for
example Self; dialog is a Dialog object, and therefore should not be passed in quotation marks;
controlID is the string corresponding to the control to be enabled or disabled; and enable is a Boolean
parameter, which enables the control when set to True and disables the control when set to False.
l EnableNthControl(nth control, enable)
Dynamically enables or disables a given control on a plug-in dialog. Can be called either before a
dialog has been displayed (in which case the operation applies to the next dialog you show), or while
a dialog is already visible (in which case the operation affects the top-most currently visible dialog).
Note that, using this method, controls can only be identified according to their order upon creation;
for this reason, you are strongly recommended to use EnableControlById() instead. To find out
the creation order, open the appropriate dialog in the plug-in editor, right click on the dialog’s client
area and choose Set Creation Order from the contextual menu that appears. Note that nth
control expects a 0-based number, unlike the display given by Set Creation Order. By default,
all controls are enabled; to disable any given control, set enable to false.
l Execute(CommandID)
Executes the specified command. This lets you create scriptable plug-ins that can execute any
number of commands one after the other. Using [Link]() you can create plug-ins to
speed up workflows that include multi-step repetitive tasks and then execute them all in one step.
Any command listed in the Commands list on the Home tab can be used with
[Link]().
Use Cmd() in conjunction with [Link]() to execute commands by name rather than
by CommandID. For example:
[Link](Cmd("Select All"));

Of course, you can use other ManuScript methods for features not in the Commands list in
combination with [Link]() to create plug-ins for almost any workflow.

g You can further speed up your workflow by assigning a keyboard shortcut to your plug-in.
l FileExists(filename)
Returns True if a file exists or False if it doesn’t.
l FolderExists(foldername)
Returns True if a folder exists or False if it doesn’t.
l FindCommandId(Command Name)
Translates the name of a command (as shown in Sibelius) into a CommandId, and returns that
CommandId as a string. The Command Name argument is case-insensitive. It is also specific to the
current language set in Sibelius. If no match is found, an empty string is returned. For example:
l [Link]("ToGGle ReVieW mODe");
l FindCommandName(Id)
Translates a CommandId or a StyleId to the corresponding Command Name or Style Name in
the current language set in Sibelius and returns that Name as a string. If no match is found, an empty
string is returned. For example:
l [Link]("toggle_review_mode"); //CommandId
l [Link]("[Link]"); //StyleId
l FindStyleId(Style Name)

cxii
 4 Object Reference

Translates the name of a Style (as shown in Sibelius) into a StyleId, and returns that StyleId as a
string. The Style Name argument is case-insensitive. It is also specific to the current language set
inside Sibelius. If no match is found, an empty string is returned. For example:
l [Link]("Crescendo");
l GetDocumentsFolder()
Returns the user’s My Documents (Windows) or Documents (Mac) folder.
l GetElapsedCentiSeconds(timer number)
Returns the time since ResetStopWatch was called for the given stop watch, in 100ths of a second.
l GetElapsedMilliSeconds(timer number)
Returns the time since ResetStopWatch was called for the given stop watch, in 1000ths of a
second.
l GetElapsedSeconds(timer number)
Returns the time since ResetStopWatch was called for the given stop watch in seconds.
l GetFile(file path)
Returns a new File object representing a file path for example file=[Link]
("c:\\onion\\[Link]");
l GetFolder(file path)
Returns a new Folder object representing a file path for example folder=[Link]
("c:\");
l GetListOfCommandNamesInCategory(Localized Command Category Name)
Returns a sparse array of all External Localized Command Names (in alphabetical order). For
example:
fileTabCommands = [Link]("File Tab")
l GetNotesForChord(chord name)
Returns a ManuScript array giving the MIDI pitches corresponding to the named chord symbol.
l GetNotesForGuitarChord(chord name)
Returns a ManuScript array giving the MIDI pitches and string numbers corresponding to the named
guitar chord, using the most suitable fingering according to the user’s preferences. Strings are
numbered starting at 0 for the bottom string and increasing upwards. The array returned has twice
as many entries as the number of notes in the chord, because the pitches and string numbers are
interleaved thus:
array[0] = MIDI pitch for note 0
array[1] = string number for note 0
array[2] = MIDI pitch for note 1
array[3] = string number for note 1
...
l GetScoresFolder()
Returns a new Folder object representing the default Scores folder (as defined on the Files page
of File > Preferences).
l GetSyllabifier()
Returns a new Syllabifier object, providing access to Sibelius’s internal syllabification engine.
l GetUserApplicationDataFolder()
Returns the user’s Application Data (Windows) or Application Support (Mac) folder.

cxiii
 4 Object Reference

l GetUserSibeliusFolder()
Returns the path to the Sibelius folder inside the user Documents folder by default (this value may be
overridden in File > Preferences > Saving and Exporting > Saving scores). For
example:
– On Windows: C:\Users\<your user name>\Documents\Scores
– On Mac: /Users/<your user name>/Documents/Scores
l GoToEnd()
Moves the playback line to the end of the score.
l GoToStart()
Moves the playback line to the start of the score.
l IsDynamicPartOpen(dynamic part)
Returns True if the specified part and its corresponding Score is valid and is visible in a Score window
within Sibelius.
l IsFontFamilyInstalled(font name)
Returns True if a font with the name font name exists on the system, otherwise False.
l LaunchApplication(path[,parameters[,hide]])
Launches an external application specified by its path, which must be a complete path to the
application to be launched. You can optionally pass in a sparse array of parameters (or a string if
you want to pass in only a single parameter); omit this or set it to null to pass no parameters to the
launched application. To prevent the launched application from gaining the focus once it is launched,
set the optional hide parameter to True; if unspecified, this defaults to False, so the launched
application gains the focus.
l LiveTempoTap()
Equivalent to tapping a beat during Live Tempo recording.
l MakeSafeFileName(filename)
Returns a “safe” version of filename. The function removes characters that are illegal on Windows or
Unix, and truncates the name to 31 characters so it can be viewable on Mac OS 9.
l MessageBox(string)
Shows a message box with the string and an OK button.
l MoveActiveViewToBar(bar number[,position])
Brings a given internal bar number into view. Has the same effect as Go to Bar in Sibelius. An
optional position within the bar may also be specified, but if omitted, the very start of the bar is
brought into view.
l MoveActiveViewToSelection([start of selection])
Brings the object(s) currently selected into view. If start of selection is False, the end of the selection
is brought into view. If the optional argument is True or omitted, the start of the selection is visible.
Has the same effect as Shift + Home/End in Sibelius.
l New([manuscript paper])
Creates and shows a new score. If the optional parameter manuscript paper is not supplied, Sibelius
creates a blank score; manuscript paper should be the filename of the manuscript paper you want to
create, minus its .sib file extension, optionally including the name of the category (subfolder) in
which it is located, for example both "String orchestra" and "Orchestral/String
orchestra" work. Returns the score object corresponding to the new score.
l NthScore(score index from 0)

cxiv
 4 Object Reference

Returns the nth open score (zero-based), or null if the specified index is not valid.
l Open(filename [,quiet])
Opens and displays the given file. Filename must include its extension, for example [Link]. If the
optional boolean parameter quiet is set to True, then no error messages or dialogs are displayed,
even if the file could not be opened for some reason. Returns True if the file is opened successfully,
False otherwise.
l Play()
Plays the current score, from the current position of the playback line.
l PlayFromSelection()
Plays from the current selection.
l PlayFromStart()
Plays from the start of the score.
l PrependScreenreaderText(string)
Prepends string to the default screen reader description.
l Print(number of copies[, dynamic part[, showdialog]])
Prints the specified number of copies of the current score or dynamic part using default settings. If
number of copies is missing or a negative number, then the default number of copies for the score or
part is printed, and if set to 0 no printing occurs. The optional dynamic part parameter must be a
valid object of the active Score (this does not affect or use [Link] for the
Score printed); if it is not supplied, the active Score is printed instead. Returns True for success,
False for failure. The second optional parameter, showdialog, is a Boolean: if set to True, Sibelius
shows the Print dialog, and if not specified or set to False, Sibelius does not show the dialog. The
showdialog argument has been deprecated as of Sibelius 7.
l PrintAllDynamicParts([score])
Prints the default number of copies of all dynamic parts, but does not print the full score. Prints the
currently-active Score if the optional score parameter is not passed in. Returns True for success,
False for failure.
l RandomNumber()
Returns a random number between 0 and 32,767.
l RandomSeed(start number)
Restarts the random number sequence from the given number.
l RandomSeedTime()
Restarts the random number sequence based on the current time.
l RefreshDialog()
Refreshes the data being displayed by any controls on the currently active plug-in dialog. For
example, if a text object gets its string from a global variable and the value stored in this global
variable has changed whilst the dialog is visible, calling RefreshDialog updates the text object on
the dialog accordingly. Returns True if successful.
l ResetStopWatch(timer number)
Resets the given stop watch. timer number must be an integer greater than 0.
l ReadTextFile(filename)

cxv
 4 Object Reference

Reads the given filename into an array of strings, one per line. The file is treated as ANSI (that is 8-bit)
text by default, unless it starts with a valid UTF-16 byte-order marker (BOM), in which case it is
treated as Unicode.
The resulting array can be used in two ways:
lines = [Link]("[Link]");
for each l in lines {
trace(l);
}

or:
lines = [Link]("[Link]");
for i=0 to [Link] {
trace(lines[i]);
}
l ScreenreaderText(string)
Replaces Sibelius’s default screen reader description with string.
l SelectFileToOpen(caption,file,initial_dir,default extension,default type,default type
description)
Shows a dialog prompting the user to select a file to open. All parameters are optional. The method
returns a file object describing the selection. For example:
file=[Link]("Save
Score","*.sib","c:\","sib","SIBE","Sibelius File");

Note that the initial_dir parameter has no effect on Mac, because it is unsupported by
macOSSelectFileToSave(caption,file,initial_dir,default extension,default type,default type
description)
Shows a dialog prompting the user to select a file to save to. All parameters are optional. The method
returns a File object describing the selection. File types and extensions:

Description Type Extension

EMF graphics "EMF" emf

Windows bitmap "BMP" bmp

Macintosh PICT bitmap "PICT" pict

Sibelius score "SIBE" sib

MIDI file "Midi" mid

House style file "SIBS" lib

PhotoScore file "SCMS" opt

Web page "TEXT html

TIFF graphics "TIFF" tif

PNG graphics "PNG" tif

Note that the initial_dir parameter has no effect on Mac, because it is unsupported by macOS.
l SelectFolder([caption])
Allows the user to select a folder and returns a Folder object. The optional string parameter caption
sets the caption of the dialog that appears.

cxvi
 4 Object Reference

l SetCurrentScoreViewType(view type)
Allows plug-ins to switch between Panorama and normal view; values are ViewTypePage (0) and
ViewTypePanorama (1).
l SetFocusToControl(pluginName,dialogName,controlID)
Sets the focus on a specific control in a plug-in dialog. pluginName normally set to self, dialogName
is the name of the dialog in which the control is found, and controlID is the ID of the control to receive
the focus, which must be specified in quotation marks.
l ShowDialog(dialogName,pluginName)
Shows a dialog dialogName from a dialog description and sends messages and values to the given
Plugin object pluginName (normally set to Self). Returns the value True (1) or False (0)
depending on which button you clicked to close the dialog (typically OK or Cancel).
l ShowDynamicPart(dynamic part[, newWindow])
Shows the specified dynamic part. The second optional Boolean parameter newWindow allows you
to specify whether the part should open in a new tab (specify False, the default) or a new window
(specify True). Returns True if the specified part can be shown, False otherwise. Can be used to
bring a Score to the front by way of [Link]
([Link]).
l ShowTraceWindow()
Shows the Plug-in Trace Window, or forces it to the front if it is already shown but currently
behind another window.
l StartLiveTempoRecording()
Starts recording Live Tempo; equivalent to choosing Play > Record Live Tempo
l StopLiveTempoRecording()
Stops recording Live Tempo.
l Stop()
Stops the current score from playing.
l UpdateProgressDialog(progress pos,status message)
Returns 0 if the user clicked Cancel.
l YesNoMessageBox(string)
Shows a message box with Yes and No buttons. Returns True if Yes is chosen, else False.

Variables
l ActiveScore
Is the active Score object (read/write). Setting [Link] makes active the current
dynamic part (which may be the full score rather than a part) of the score. If that window is not
currently shown, a new window may be created according to the user’s preferences. Returns null if it
fails to make the specified score or part active.
l ApplicationLanguage
Returns the language of the version of [Link] currently running, always in English—such as
English, German, French and so on. (read only)
l ApplicationLanguageIsoString
Returns the two-letter ISO 3166 identifier of the language in which Sibelius is currently running, such
as en, de, fr, and so on (read only).
l AvailableCommands

cxvii
 4 Object Reference

Returns a sparse array of all available CommandIDs in alphabetical order.

l CommandCategories
Returns a sparse array of all Command Categories in the local language (in system order).
l CurrentTime
Returns a string containing the current time in the format hh:mm:ss, based on your own computer’s
locale (read only).
l CurrentDateShort
Returns a string containing the current date in the format dd/mm/yyyy, based on your own
computer’s locale (read only).
l CurrentDateLong
Returns a string containing the current date in the format dd MM yyyy, based on your own
computer’s locale (read only).
l CurrentDate
Returns the current date and time as a DateTime object in local time (read only).
l EarlierVersionNames
Returns a sparse array of strings containing the names of all the earlier versions of Sibelius that a
score can be exported to using the SaveAsEarlierVersion method.
l FontFamilies
Returns a sparse array of strings containing the names of all the available font families on the system
(read only).
l HouseStyles
The list of house styles available, as a ComponentList.
l LocalizedApplicationLanguage
Returns the language in which Sibelius is currently running, in the localized language, for example it
returns Deutsch when running in German (read only).
l ManuscriptPapers
The list of manuscript papers available, as a ComponentList.
l OSVersionString
The current operating system in which the plug-in is running, as one of the following strings:

Windows 10 macOS Mojave

Windows 11 macOS Catalina
macOS Sonoma
macOS Sequoia

If the operating system is unrecognized, the variable returns Unknown system version.
l PathSeparator
Returns the current path separator character (which is “\” on Windows, “/” on Mac).

cxviii
 4 Object Reference

l Plugins
The list of plug-ins installed. See the documentation for the Plugin object
l Playing
Is True if a score is currently being played (read only).
l ProgramVersion
The current version of Sibelius in which the plug-in is running, as an integer in the following format:
(major version) * 1000 + (minor version) * 100 + (revision) * 10

So Sibelius 3.1.3 would be returned as 3130.

l ScoreCount
Is the number of scores being edited (read only).
l SuppressDefaultScreenreaderText
Set to True to suppress the default score description for screen readers for blind and visually
impaired users (read/write).
l ViewAnnotations
Is True if View > Invisibles > Annotations is enabled (read/write).
l ViewAttachmentLines
Is True if View > Invisibles > Attachment Lines is enabled (read/write).
l ViewBarNumbers
Is True if View > Invisibles > Bar Numbers is enabled (read/write).
l ViewComments
Is True if View > Invisibles > Comments is enabled (read/write).
l ViewHandles
Is True if View > Invisibles > Handles is enabled (read/write).
l ViewHiddenObjects
Is True if View > Invisibles > Hidden Objects is enabled (read/write).
l ViewHighlights
Is True if View > Invisibles > Highlights is enabled (read/write).
l ViewLayoutMarks
Is True if View > Invisibles > Layout Marks is enabled (read/write).
l ViewNoteVelocities
Is True if View > Live Playback Velocities is enabled (read/write).
l ViewNoteColors
The current View > Note Colors setting used (read/write).

Description Value

None 0

Notes out of Range 1

Pitch Spectrum 2

Voice Colors 3

cxix
 4 Object Reference

l ViewPageMargins
Is True if View > Invisibles > Page Margins is enabled (read/write).
l ViewPlaybackLine
Is True if View > Invisibles > Playback Line is enabled (read/write).
l ViewReplayMarker
Is True if View > Invisibles > Replay Line is enabled (read/write).

SoundInfo
The SoundInfo object contains information about the playback of a given staff.

To get the SoundInfo object for a staff, use for example:

staff = [Link](1);
soundinfo = [Link](1,0,0);

The SoundInfo object can be moved around the staff once you have created it, and it returns information
about the sound IDs in use throughout the staff.

Methods
l Clone()
Returns a new SoundInfo object using the same credentials as the object on which the method is
called.
l CreateAt([barNumber,[position,[nthRepeat]]])
Returns a new SoundInfo object at the specified bar number, at the specified rhythmic position in
the bar (for example 256 for the second quarter note position), as if played through at the nth repeat
(for example 2 for the second repeat). If no bar number is specified, the information returned refers to
bar 1. If no position is specified, the information refers to the start of the bar. If nth repeat is not
specified, the information returned refers to the first pass through the score.
l MoveTo([barNumber,[position,[nthRepeat]]])
Uses the same parameters as CreateAt(). Allows the caller to move the existing SoundInfo object
to an entirely new location on the current staff.
l MoveToNext()
Moves to the next sound change event. If there are no more changes, it returns false and doesn’t
move.
l MoveToPrevious()
Moves to the previous sound change event. If there are no changes before, it returns false and
doesn’t move.

Variables
l ActualSoundId
The actual sound ID at the current location (read only).
l BarNum
Returns the current location's bar number (read only).
l IsDrumStave
Returns true if the current location is on a drum staff (read only).
l NthRepeat

cxx
 4 Object Reference

Returns or sets the nth repeat (or pass) of the current location’s bar (read/write).
l NumTimesBarPlayed
The number of times the bar at the current location is played (read only).
l PatchName
The name of the patch in use at the current location (read only).
l Position
Returns or sets the current location’s position within the bar (read/write).
l RequestedSoundId
The requested sound ID at the current location (read only).
l SoundChangeIndex
The current index in the bar play sequence. This allows differentiation between different identical
sound changes (read only).
l SoundSetName
Returns the name of the sound set in use at the current location (read only).
l StaveNum
Returns the 1-based stave number (read only)

SparseArray
To create a sparse array, use the built-in method CreateSparseArray(a1,a2,a3,a4...an).

for each allows you to iterate over the contents of a sparse array.

Methods
l Concat(array1, array2 ... arrayN)
Concatenate zero or more sparse arrays to this one, and return it as a one-level deep copy (so if a
sparse array contains other arrays, for example, then the new sparse array contains references to
those arrays, not copies of them). This method does not modify the original sparse array.
l Join([separator])
Returns the array as a string, with each populated element separated by the optional separator. If
you don’t specify separator, the default separator is a comma.
l Push(value1, value2, value3 ... valueN)
Pushes one or more values to the end of the array.
l Pop()
Returns the last element of the array, and removes it from the array.
l Reverse()
Reverses the sparse array in place, modifying the sparse array being operated on. The reversed array
only populates the elements needed to create the reversed array.
l Slice(start[,end])
Returns a new sparse array of the elements starting from start and up to, but not including, the
optional end. start and end can be negative indices referring to offsets from the end of the array.

cxxi
 4 Object Reference

Variables
l Length
Returns or sets the length of the array (read/write).
l ValidIndices
Returns a sparse array containing only the populated indices of the original sparse array, that is
those that are not null.

Converting Old-style Arrays to New Sparse Arrays

The SparseArray object is a replacement for the old Array object, which was a more limited kind of array
that could only hold strings and integers, but no other kind of objects. You are recommended to use the new
SparseArray object for all arrays in your plug-ins, but if you have an existing plug-in in which old-style
Arrays are used, you can convert them to SparseArrays as follows:
l [Link]()
Returns a new SparseArray object, populated with strings converted from the old-style Array.

SpecialBarline
Derived from a Bar object, these can only be found in system staves.

Methods
None.

Variables
l BarlineType
The name of the type of special barline, expressed as a string.
l BarlineInternalType
The type of the barline, expressed as a numeric ID which maps to one of the SpecialBarline
global constants (see "Global Constants" on page clxxx).

Staff
These can be normal staves or the system staff. The system staff contains objects that apply to all staves,
such as SpecialBarlines and text using a system text style.

A Staff contains Bar objects.

for each variable in returns each object in the staff.

for each type variable in returns each item of type in the staff in chronological order (that is in order of
rhythmic position in each bar).

Methods
l AddClef(pos,concert pitch clef[,transposed pitch clef])
Adds a clef to the staff at the specified position. concert pitch clef determines the clef style when
Notes > Transposing Score is switched off; the optional transposed pitch clef parameter
determines the clef style when this is enabled. Clef styles should be an identifier like “[Link]”; for
a complete list of available clef styles, see "Clef Styles" on page clxxxvii. Alternatively you can give
the name of a clef style, such as “Treble,” but bear in mind that this may not work in non-English
versions of Sibelius.

cxxii
 4 Object Reference

l AddLine(pos,duration,line style,[dx,[dy,[voicenumber,[hidden]]]])
Adds a line to staff (please see the documentation in Bar object below).
l AddNote(pos,sounding pitch,duration,[tied [,voice [,diatonic pitch[,string number]]]])
Adds a note to staff, adding to an existing NoteRest if already at this position (in which case the
duration is ignored); otherwise creates a new NoteRest. Adds a new bar if necessary at the end of the
staff. The position is in 1/256th quarters from the start of the score. The optional tied parameter
should be True if you want the note to be tied. Voice 1 is assumed unless the optional voice
parameter (with a value of 1, 2, 3 or 4) is specified. You can also set the diatonic pitch, that is the
number of the “note name” to which this note corresponds, 7 per octave (35 = middle C, 36 = D, 37 =
E and so on). If a diatonic pitch of zero is given then a suitable diatonic pitch is calculated from the
MIDI pitch. The optional string number parameter gives a string number for this note, which is only
meaningful if the note is on a tablature stave. If this parameter is not supplied then a default string
number is calculated based on the current tablature stave type and the guitar tab fingering options
(specified on the Note Input page of File > Preferences). Returns the Note object created (to
get the NoteRest containing the note, use [Link]).
When adding very short notes to tuplets, Sibelius may be unable to find a legal place for the note in
the bar. Should this happen, Sibelius returns null. You should therefore check for a valid object if
there is any likelihood that this situation may arise in your code.

g If you add a note to a score that intersects an existing tuplet, Sibelius tries to snap the note to
the closest sensible place within that tuplet. However, you are advised to use [Link]()
for this purpose as it is void of any ambiguity.
l AddStaffAbove(ossia,[start bar number[,end bar number[,start pos[,end pos]]]])
Adds a new staff above the staff. Set ossia to True to create an ossia (small) staff. The other,
optional parameters determine where the staff should be visible: if you do not specify a start bar
number, the staff is visible from the start of the score; if you do not specify an end bar number, the
staff is visible to the end of the score. If you specify a start and/or end bar number, the staff is hidden
outside that range by way of an instrument change to the No instrument (hidden) instrument
type. start pos and end pos represent the rhythmic position within the start bar number and end bar
number respectively, and if not specified, start pos defaults to the start of the bar, and end pos
defaults to the end of the bar. Returns the staff created, or null if the call fails.
l AddStaffBelow(ossia,[start bar number[,end bar number[,start pos[,end pos]]]])
Adds a new staff below the staff. See AddStaffAbove() above for details.
l AddSymbol(pos,symbol index or name)
Adds a symbol to staff (please see the documentation in Bar object below).
l CurrentKeySignature(bar number)
Returns a KeySignature valid at the bar number passed.
l NthBar(n)
Returns the nth bar in the staff, counting from 1.
l ResetSpaceAroundStaff(above,below[,from bar[,to bar]])
Does the equivalent of Layout > Reset Space Above Staff and/or Reset Space Below
Staff for the given range of bars in a staff. Set above to True to reset the space above the staff,
and below to True to reset the space below the staff. If from bar is not specified, Sibelius sets it to 1;
if to bar is not specified, Sibelius sets it to the last bar of the score.
l ScaleFactorChange(StaveScaleFactor, startBarNum, endBarNum)

cxxiii
 4 Object Reference

Equivalent to setting the Staff Size property within the Inspector. Valid StaveScaleFactor types
include:
– NormalSize (0)
– MediumSize (1)
– SmallSize (2)
– ExtraSmallSize (3)
It requires a valid range specified by startBarNum and endBarNum.
l SetSound(styleID[,set SoundStage])
Changes the initial playback sound of this staff to be the default sound for the given default
instrument styleID. For a complete list of default instrument style IDs in Sibelius, see "Instrument
Types" on page clxxxvii. If the optional Boolean parameter is set to False, then the SoundStage
information (volume, pan and distance) for this staff is unchanged. If it is omitted or set to True, then
the SoundStage information is set to the default for the new sound.
l SetSoundID(soundID)
Changes the initial playback sound of this staff to the given soundID.
l SoundIDAtPosition([bar number,[position,[nth repeat]]])
Returns a new SoundInfo object at the specified bar number, at the specified rhythmic position in
the bar (for example 256 for the second quarter note position), as if played through at the nth repeat
(for example 2 for the second repeat). If no bar number is specified, the information returned refers to
bar 1. If no position is specified, the information refers to the start of the bar. If nth repeat is not
specified, the information returned refers to the first pass through the score.
l Staff[array element]
Returns the nth bar (counting from 1) for example Staff[1].

Variables
l BankHigh
Controls MIDI controller 0, used to select the “coarse” bank number for this stave, and corresponding
to the Mixer control of the same name. The range is 0–127, or –1 if you don’t want to send this
controller message at the start of playback. Note that not all MIDI devices support multiple banks
(read/write).
l BankLow
Controls MIDI controller 32, used to select the “fine” bank number for this stave, and corresponding
to the Mixer control of the same name. The range is 0–127, or –1 if you don’t want to send this
controller message at the start of playback. Note that not all MIDI devices support multiple banks
(read/write).
l BarCount
Number of bars in the staff (read only).
l BarNumber
The bar number of this bar. This is the internal bar number, which always runs consecutively from 1
(read only).
l Channel
The MIDI channel number of this staff, numbered 1–16 (read/write).
l Distance

cxxiv
 4 Object Reference

The reverb “distance” of this staff, corresponding to the control of the same name in the Mixer. This is
a percentage, used to scale the overall reverb settings from the Performance dialog (read/write).
l FullInstrumentName
Gives the full instrument name of the staff, empty for an unnamed staff (read/write).
l FullInstrumentNameWithFormatting
Gives the full instrument name of the staff including any changes of font or style, if any (read/write).
l FullStaffName
Returns the initial full staff name (read/write).
l FullStaffNameWithFormatting
Returns the initial full staff name including any changes of font or style, if any (read/write).
l NumStavesInSameInstrument
The number of staves belonging to the default instrument from which this staff was created (read
only).
l InitialClefStyle
The name of the initial clef on a staff, depending on the state of Notes > Transposing Score
(read only).
l InitialClefStyleId
The style identifier of the initial clef on a staff, depending on the state of Notes > Transposing
Score (read only).
l InitialInstrumentType
Returns an InstrumentType object for the instrument type at the start of the staff.
l InitialKeySignature
Returns the KeySignature object at the start of this staff (read only).
l InitialStyleId
Returns the style identifier of the staff (read only). To create an instrument from such an ID, pass the
style as the first argument to [Link]. For a complete list of all the default
instrument names in Sibelius, see "Instrument Types" on page clxxxvii.
l InstrumentName
Gives the full instrument name of the staff in the form that is displayed on the Instruments and
Staves dialog in Sibelius (read only). For an unnamed stave, this will be “[Piano]” for example, where
Piano is the default instrument name of the stave (see below). To get the internal name (which is
empty for unnamed staves), use the read/write variables FullInstrumentName or
ShortInstrumentName instead.
l IsSystemStaff
True or False depending on whether this staff is a system staff or not (read only).
l IsVocalStaff
Returns True if the instrument type used by the staff has the Vocal staff option switched on,
meaning that the default positions of dynamics should be above the staff rather than below (read
only).
l MuteMode
Specifies whether or not this stave plays back. Corresponds to the mute button in the Mixer. The
supported values are defined as global constants (see "Global Constants" on page clxxx) and are
Muted, HalfMuted and NotMuted (read/write).

cxxv
 4 Object Reference

l Pan
The MIDI stereo panning position of this staff (corresponding to the pan control in the Mixer).
Permissible values are –100 to 100, with positive values being to the right and negative to the left
(read/write).
l ParentScore
Returns the staff’s parent Score object (read only).
l ShortInstrumentName
Gives the short instrument name of the staff, empty for an unnamed staff (read/write).
l ShortInstrumentNameWithFormatting
Gives the short instrument name of the staff including any changes of font or style, if any
(read/write).
l ShortStaffName
Returns the initial short staff name (read/write).
l ShortStaffNameWithFormatting
Returns the initial short staff name including any changes of font or style, if any (read/write).
l ShowInFocusOnStaves
If True then this staff is shown when Layout > Focus on Staves is enabled (see also
[Link]). This variable cannot be set to False unless it is also True for at least one
other staff in the score (read/write).
l Solo
True or False depending on whether this staff plays back in “solo” mode, corresponding to the
Mixer button of the same name (read/write).
l SoundIdOverrideIfAny
Returns a string containing the sound ID override set in the mixer for the staff. If no override has been
set, an empty string is returned (read only).
l Small
True if the staff is small (such as an ossia staff), False if it is normal sized (read/write).
l StaffNum
Returns the number of this stave, counting from 1 at the top of the currently-viewed part. Returns 0
for SystemStaff objects (read only).
l Volume
The overall MIDI volume of this staff, corresponding to its fader in the Mixer. Permissible values are 0–
127 (read/write).

Syllabifier
Acts as a wrapper around Sibelius’s internal Syllabification engine, exposing its functionality to ManuScript.

Methods
l AbbreviateUsingApostrophe(useApostrophe)
When the abbreviate flag is set to True when calling Syllabify, Sibelius replaces vowels that
have been combined with the previous syllable with an apostrophe if this option is enabled—for
example Vege-ta-bles vs Veg’-ta-bles. Calling this method causes the syllabification engine to
recalculate its result if necessary.

cxxvi
 4 Object Reference

l GetNthSyllable(n)
Once a string has been syllabified by calling the Syllabify method, you can use this method to
return each individual syllable as a string
l NthSyllableEndsWord(n)
Once a string has been syllabified by calling the Syllabify method, you can use this method to
find out whether each syllable occurs at the end of a word
l Syllabify(textToSyllabify[, language[, abbreviate = False]])
Breaks a string down into its syllabic components, returning the number of syllables in the resultant
syllabification, or 0 if an error has occurred. The rules of the specified language are used, and you
may legally supply either a language ID, or the localized language name. To get the individual
syllables, you should call the GetNthSyllable and NthSyllableEndsWord methods documented
below.
If the language argument is omitted, Sibelius attempts to automatically identify the language of the
text. If this is not possible, or if an unrecognised language ID or name has been supplied, 0 is
returned.
When abbreviate is True, each ambiguous word in the string is syllabified using the minimal
number of syllables. For example, syllabifying “Everybody likes vegetables” would return “Eve-ry-
bod-y likes vege-ta-bles” with this flag set to True, otherwise “E-ve-ry-bod-y likes veg-e-ta-bles”.

Variables
l AbbreviateUsingApostrophe
Returns True/False depending on whether the syllabification engine is set to abbreviate combined
syllables with an apostrophe (read only – call method with same name for write access).
l AvailableLanguageIds
Returns an array containing a list of the available syllabification languages as three-letter non-
translatable IDs – such as ENG (English), GER (German), LAT (Latin). These IDs are identical in all
localized versions of Sibelius (read only).
l AvailableLanguages
Returns an array containing a list of the available syllabification languages as localized strings (read
only).
l NumberOfSyllables
Returns the number of syllables in the hyphenated string generated by calling the Syllabify
method (read only).
l SyllabifiedString
Returns the resultant hyphenated string generated by calling the Syllabify method (read only).

SymbolItem and SystemSymbolItem

Derived from a BarObject. For system symbols (such as symbols belonging to the system staff, retrieved
with for each on the SystemStaff object), the type of symbol objects is SystemSymbolItem, not
SymbolItem.

Methods
None.

cxxvii
 4 Object Reference

Variables
l Index
The index of this symbol in the list of symbols. This corresponds to its position in the Create >
Symbol dialog, counting from zero left-to-right and top-to-bottom (read only).
l Name
The name of this symbol. May be translated in non-English language versions of Sibelius (read only).
l Size
The draw size of the symbol, corresponding to the four available options in the Symbols dialog in
Sibelius. The four available values are NormalSize, CueSize, GraceNoteSize and
CueGraceNoteSize, all defined as global constants (read/write).

SystemObjectPositions
Accessed from a Score object. Corresponds to the settings in House Style > System Object
Positions.

Methods
l GetNthStaffShowsSystemObjects(staffNum)
Returns True if the given staff number staffNum (relative to the current part) is showing system
objects above it, otherwise False.
l SetNthStaffShowsSystemObjects(staffNum, show)
Tells the staff with the given staff number staffNum (relative to the current part) either to show or not
show system objects above it. This has no effect if you pass in the top staff in the part, or if the
maximum number of staves allowed to show system objects has already been met.
l Clear([removeBelowBottomStaff])
Allows you to clear all the system object positions (apart from the compulsory one above the top
staff) in a single operation; set the optional Boolean parameter removeBelowBottomStaff to True to
also clear the Below bottom staff system object position.

Variables
l NumStavesShowingSystemObjects
Returns the current number of staves showing system object positions (read only).
l ShowSystemObjectsBelowBottomStaff
Returns True if system objects should show below the bottom staff, otherwise False (read/write).

SystemStaff, Staff, Selection, Bar and, all BarObject-derived

Objects
Variables
l IsALine
Returns true if the object is a line object. (Note that this is a variable, not a method, unlike the
IsObject()method for all objects.)
l Type

cxxviii
 4 Object Reference

A string giving the name of the type of an object. The strings for the first 4 types above are
"SystemStave", "Stave", "MusicSelectionList", and "Bar". Note that this variable is also a
member of all objects that occur in bars.

SystemStaff
There is one SystemStaff object per score. The SystemStaff contains objects which apply to all staves,
such as Special Barlines and text using a system text style. Unlike normal staves, the SystemStaff does
not appear in the score itself. As such, most of the variables and methods supported for Staff objects are
not available on a SystemStaff. Those that are supported by SystemStaff are as follows.

Methods
l CurrentKeySignature(bar number)
Returns a KeySignature valid at the bar number passed.
l CurrentTimeSignature(bar number)
Returns a TimeSignature valid at the bar number passed.
l NthBar(n)
Returns the nth bar in the staff, counting from 1.
l SystemStaff[array element]
Returns the nth bar (counting from 1) for example SystemStaff[1].

Variables
l BarCount
Number of bars in the staff (read only).
l InitialKeySignature
Returns the KeySignature object at the start of this staff (read only).
l IsSystemStaff
Returns True for a SystemStaff (read only).

Text and SystemTextItem

Derived from a BarObject. For system text (such as text belonging to the system staff, retrieved with for
each on the SystemStaff object), the type of text objects is SystemTextItem, not Text.

Methods
None.

Variables
l EraseBackground
Returns True when the background of this item is erased, otherwise it returns False. Writing True
or False to this variable creates an override, so that the item ignores the value from its text style and
uses the provided value instead, as if the you had set it using the Inspector (read/write).
l EraseBackgroundOverridden
Returns True when the item has an override of the style’s EraseBackground value, if not it returns
False. Setting this variable to False clears the override so that the value specied by the style gets
used. Setting this variable to True has no effect (read/write).

cxxix
 4 Object Reference

l InitialFontName
Returns the font name used at the start of a styled string (read only).
l InitialFontSize
Returns the font size in SUs (1/32nd space) if the text object is of a single size, or –1 if the text object
uses multiple font sizes (read only).
l JumpAtEndOfBar
Returns True if the system text object has Jump at bar end (in the Playback panel of the Inspector)
set, otherwise False. Always returns False for staff text objects (read/write).
l StyleAsText
The text style name (read/write).
l StyleId
The identifier of the text style of this piece of text (read/write).
l Text
The text as a string (read/write).
l TextWithFormatting
Returns an array containing the various changes of font or style (if any) within the string in a new
element (read only). For example, “This text is \B\bold\b\, and this is
\I\italic\i\” would return an array with eight elements containing the following data:
arr[0] = “This text is “
arr[1] = “\B\”
arr[2] = “bold”
arr[3] = “\b\”
arr[4] = “, and this is “
arr[5] = “\I\”
arr[6] = “italic”
arr[7] = “\i\”
l TextWithFormattingAsString
The text including any changes of font or style (read only).

TimeSignature
Derived from a BarObject.

Methods
None.

Variables
l AllowCautionary
Returns True if the time signature is set to show a cautionary at the end of the previous system, if it
occurs at the start of a system (read/write).
l Denominator
The time signature’s bottom number (read only).
l Numerator
The time signature’s top number (read only).

cxxx
 4 Object Reference

l Text
The time signature as text. You can use this to detect common time and alla breve time signatures by
comparing it to the global constants CommonTimeString and AllaBreveTimeString, which
define the Unicode characters used by these symbols. Other time signatures are of the form “4\n4”
(read only).

TreeNode
These are used internally by ManuScript to implement arrays and hashes (returned with the CreateArray
and CreateHash methods), and to represent global data (defined in the plug-in editor). Each TreeNode
can contain a label, a piece of data and a list of “children,” which are also TreeNodes. Normally, any
access to a TreeNode object accesses the data that is held, so that you don’t need to know anything about
them, but there are also some extra variables and methods that may be useful in some circumstances.
These can be called on any array, hash or global variable, and on any member of such a structure.

Methods
l WriteToString
Returns a string that represents the structure of this TreeNode object. In this representation, the
data of a TreeNode is surrounded by double quotes and the label is not. Note that a label need not
be defined. Any children of the TreeNode (also TreeNode objects themselves) are contained within
curly braces { and }. To obtain child TreeNodes, use the normal array operator, as described in the
documentation for arrays and hashes.

Variables
l Label
The label of this TreeNode.
l NumChildren
The number of child TreeNodes belonging to this TreeNode object.

Tuplet
Derived from a BarObject.

Methods
l AddNestedTuplet(posInTuplet, left, right, unit[, style[, bracket[,fullDuration]]]])
Nests a new tuplet bracket within an existing tuplet at a position relative to the duration and scale-
factor of the existing tuplet. The left and right parameters specify the ratio of the new tuplet, for
example 3 (left) in the time of 2 (right). The unit parameter specifies the note value (in 1/256th
quarters) on which the tuplet should be based. For example, if you wish to create an eighth note
(quaver) triplet group, you would use the value 128. The optional style and bracket parameters take
one of the pre-defined constants that affect the visual appearance of the created tuplet; see "Global
Constants" on page clxxx. If fullDuration is true, the bracket of the tuplet spans the entire duration of
the tuplet. Returns the Tuplet object created.

g If AddNestedTuplet() has been given illegal parameters, it does not create a valid Tuplet object.
Therefore, you should test for inequality of the returned Tuplet object with null before
attempting to use it.
l AddNote(posInTuplet, pitch, duration[, tied[, diatonic pitch[, string number]]]])

cxxxi
 4 Object Reference

Adds a note to an existing tuplet, adopting the same voice number as used by the tuplet itself. Please
note that posInTuplet is relative to the duration and scale-factor of the tuplet bracket itself.
Therefore, if you wanted to add a quarter note/crotchet to the second beat of a quarter
note/crotchet triplet, you would simply use the value 256, not 341!
l [Link](tuplet,splitpoint)
Split the Tuplet object tuplet at the specified splitpoint, which is a number in relation to the tuplet’s
parent bar. It then splits a nest of tuplets at that point in the bar. This method is provided by the
[Link]—see "Utils" below.

Variables
l Bracket
The bracket type of the tuplet (such as. none, auto; see "Global Constants" on page clxxx).
l FullDuration
True if the bracket of the tuplet spans its entire duration.
l Left
The left side of the tuplet, for example 3 in 3:2 (read only).
l ParentTupletIfAny
If the tuplet intersects a tuplet, the innermost Tuplet object at that point in the score is returned.
Otherwise, null is returned (read only).
l PlayedDuration
The true rhythmic duration of the tuplet, for example for quarter-note (crotchet) triplet this would be
the duration of a minim (read only).
l PositionInTuplet
Returns the position of the tuplet relative to the duration and scale-factor of its parent tuplet. If the
tuplet does not intersect a tuplet, its position within the parent Bar is returned as usual (read only).
l Right
The right side of the tuplet, for example 2 in 3:2 (read only).
l Style
The style of the tuplet (for example, number, ratio, ratio + note; see "Global Constants" on
page clxxx).
l Text
The text shown above the tuplet (read only).
l Unit
The unit used for the tuplet, for example 256 for a triplet of quarter notes (read only).

Utils
Sibelius installs a plug-in called [Link] that contains a set of useful and common methods that can be
called
directly by other plug-ins. It is not intended to be run as a plug-in in its own right, so does not appear in the
Plug-ins menu.

Methods
The methods available using [Link] are as follows:

cxxxii
 4 Object Reference

l [Link](value)
Returns the absolute value of a number, that is its numerical value without regard to its sign.
l [Link](x,y)
Adds two fractions x and y, passed in as ManuScript arrays. Returns an array with the result of the
addition.
l [Link](x)
Returns a binary string (such as “101010”) equivalent to the number x.
l [Link](x, y)
Equivalent to the C++ bitwise AND (&) operator. For example, [Link](129,1) is equal to 1.
l [Link](x, y)
Equivalent to the C++ bitwise inclusive OR (|) operator. For example, [Link](64,4) is equal to
68.
l [Link](x, y)
Equivalent to the C++ bitwise exclusive XOR (^) operator. For example, [Link](4,6) is equal
to 2.
l [Link]()
Returns True if the object can be deleted using Delete(), which is determined by checking
Sibelius’s version number.
l [Link](s1, s2)
Returns True if the two strings s1 and s2 match, ignoring case.
l [Link](x)
Returns the variable x explicitly cast as a Boolean.
l [Link](x)
Returns the variable x explicitly cast as an integer.
l [Link](x)
Returns the variable x explicitly cast as a string.
l [Link](arr1, arr2)
Concatenates two arrays containing Boolean values and returns the result.
l [Link](arr1, arr2)
Concatenates two arrays containing integral values and returns the result.
l [Link](arr1, arr2)
Concatenates two arrays containing string values and returns the result.
l [Link](source, dest)
Copies an existing text file from one location to another, returning True if successful.
l [Link](value, size)
Returns an array with size elements, each containing a blanket value specified by the first parameter.
l [Link](score, nth staff, retain selection)
Deletes an entire staff and its content from a given score, returning True if successful. If retain
selection is True, Sibelius ensures that any item(s) that was selected prior to the staff’s deletion are
still selected.

cxxxiii
 4 Object Reference

l [Link](x)
Returns a number in base 10 equivalent to binary number x, which must be provided as a string.
l [Link](x,y)
Divides fraction x by fraction y, passed in as ManuScript arrays. Returns an array with the result of
the division.
l [Link](filename)
Returns just the filename portion of a string filename containing both a path and a filename.
l [Link](str, [val1,val2,val3 ...])
Provides a simple means of replacing human-readable data types in a string. Each successive
instance of %s in str is replaced with the value of the next remaining unused argument. for example s
= [Link]("The %s brown %s jumps %s the lazy %s", "quick", "fox",
"over", "dog");
l [Link](ms)
Formats a time, given in milliseconds, to a human-readable string using the format mm’ss.z (where z
is centiseconds).
l [Link](x)
Returns the decimal equivalent of the fraction x, which is passed in as an array.
l [Link](x)
Returns the denominator of fraction x, which is passed in as an array.
l [Link](x)
Returns the numerator of fraction x, which is passed in as an array.
l [Link]()
Returns the path of the Sibelius executable as a string.
l [Link](arr, value)
Returns the index of value in the array arr, or -1 if it doesn’t exist in the array.
l [Link](x)
Returns an array containing the list of powers of two whose cumulative sum equates to the value of x.
l [Link]()
Returns the path of the system’s global application data area as a string.
l [Link](score, barNum, position)
Returns the precise time (in milliseconds) of a given location in a score. The position should be local to
the start of the bar number you have supplied. Use the utils library to achieve this if your plug-in
needs to be backwards compatible with Sibelius 4; otherwise call the Score object’s function with
the same name.
l [Link](time)
If you pass in a time expressed in milliseconds (one minute being 60,000), this function returns the
milliseconds portion of the number (in this case 60,000 modulus 1000 = 0).
l [Link](time)
If you pass in a time expressed in milliseconds, this function returns the minutes portion of the number
(for example if time = 120,262 milliseconds, this function returns 2).
l [Link](score,obj)

cxxxiv
 4 Object Reference

Returns the precise time (in milliseconds) that the object obj occurs from the start of a given score,
taking into account tempo changes, performance markings and any other events in the score that
have an effect on playback. Use this method to achieve this if your plug-in needs to be backwards
compatible with Sibelius 4; otherwise use the Time property of the BarObject object whose time
you wish to determine.
l [Link](plug-in)
This enables you to identify a plug-in by entering the line of code PluginUniqueID =
"someUniqueId"; in a plug-in’s Initialize method. When you pass a Plugin object to this
function, it scans the plug-in’s code and returns its unique ID if it has one, otherwise an empty string.
l [Link]()
This is a wrapper around the deprecated GetPluginsFolder() function, and returns the path of
the Plugins folder.
l [Link]()
Returns the major version number of Sibelius.
l [Link](m,n)
Returns the greatest common divisor of two non-zero integers, that is the largest positive integer that
divides both numbers without remainder.
l [Link](arr, value)
Returns True if value exists in the array arr.
l [Link](str[, integer only])
Returns True if the string str is numeric. Set the optional Boolean parameter integer only to True if
you want the method to only return True if str is an integer (so that you can disallow floating point
numbers).
l [Link](str)
Returns the ANSI string str in lowercase.
l [Link](x,y)
Creates a fraction with x as the numerator and y as the denominator. The fraction is returned as a
normal ManuScript array. (Manipulating fractions means you never have to worry about rounding
errors.)
l [Link](x,y)
Returns the greater of two numbers.
l [Link](x,y)
Returns the lesser of two numbers.
l [Link](x,y)
Multiplies fraction y by fraction x, passed in as ManuScript arrays. Returns an array with the result of
the multiplication.
l [Link](pattern,str)
Returns the number of times the substring pattern exists in str.
l [Link](subStr,str)
Returns the zero-based position of the first instance of the sub-string subStr in str, or -1 if it isn’t
found.
l [Link](subStr,str)

cxxxv
 4 Object Reference

Returns the zero-based position of the last instance of the sub-string subStr in str, or -1 if it isn’t
found.
l [Link](x,y)
Raises x to the yth power, where y is a positive integer.
l [Link](inStr,toFind,replaceWith,replaceAll)
Replaces a sub-string in a string with a new value. It looks for toFind in the string inStr, and if it finds
it, replaces it with replaceWith. If the Boolean replaceAll is False, it only changes the first instance
found; if it’s True, it replaces all instances.
l [Link](arr)
Reverses the order of the elements in an array of Booleans.
l [Link](arr)
Reverses the order of the elements in an array of integers.
l [Link](arr)
Reverses the order of the elements in an array of strings.
l [Link](number,precision)
Returns a string containing the number rounded to precision decimal places. The method handles the
input as a string, in order to avoid rounding errors which would otherwise spoil results beyond the
tenth decimal place or so.
l [Link](value, arr, DefaultIndex)
Scans the array arr for the value specified by the first parameter. Value is returned if it exists in the
array, otherwise, arr[DefaultIndex].
l [Link](x,y)
Bitwise left-shift. Shifts the value x left by y bits. Equivalent to C++ << operator.
l [Link](x,y)
Bitwise right-shift. Shifts the value x right by y bits. Equivalent to C++ >> operator.
l [Link](arr,show progress)
Sorts the array arr using a case-insensitive alphabetic sort. Set show progress to True to see a
progress bar while the sort is carried out, or set it to False if you don’t want to see a progress bar.
l [Link](arr,show progress,plug-in name,method)
Sorts the array arr using a custom sort order routine method, which must be passed into this method.
plug-in name is the name of the plug-in that contains the sort order routine method. You can write
your own sort order routine: it must be a method that takes two strings (strA and strB) and returns 1
or 0 based on the results of the comparison.
l [Link](arr,show progress)
Sorts the array arr in ascending numeric order. Set show progress to True to see a progress bar while
the sort is carried out, or set it to False if you don’t want to see a progress bar.
l [Link](tuplet,splitpoint)
Split the Tuplet object tuplet at the specified splitpoint, which is a number in relation to the tuplet’s
parent bar. It then splits a nest of tuplets at that point in the bar.
l [Link](componentName,callbackFunc)

cxxxvi
 4 Object Reference

Returns an array of filenames (strings) found on the system inside a folder with a given name,
following the same rules of precedence as Sibelius’s internal component manager. Files in the user’s
application data area take priority over those in the global application data area, followed lastly by
those in the Sibelius’s application directory itself.
callbackFunc should point to a function in the calling script that scans a supplied directory for files
with a specific extension.
Such a function might look something like this:
GetFooFiles(dir) { // This is the function signature
components = CreateArray();
for each FOO file in dir {
components[[Link]] = [Link];
}
return(components);
}

In the scenario above, the call to start the component manager would look like this (where “Foo Files”
is the name of the directory containing your files):
files = [Link]("Foo Files",
"[Link]");
l [Link](x,y)
Subtracts fraction y from fraction x, passed in as ManuScript arrays. Returns an array with the result
of the subtraction.
l [Link](str)
Returns the ANSI string str in uppercase.

VersionHistory
Each Score object has a VersionHistory object (obtained by way of the [Link]()
method), which in turn provides a list of Version objects. Each Version object represents a specific
version, and also provides a list of VersionComment objects, which represent the per-version comments
(as opposed to bar-attached comments, which are represented to ManuScript as Comment objects, derived
from BarObject objects).

Methods
l AddVersion([name[,comment]])
Adds a new Version object and returns it if successful (or null if not), with an optional name and
comment for the version.
l DeleteNthVersion(n)
Deletes the nth Version object, returning True if successful.
l GetNthVersion(n)
Returns the nth Version object.

Variables
l NumChildren
Returns the number of versions in the score’s VersionHistory object.

Version
Accessed using a Score object’s VersionHistory object.

cxxxvii
 4 Object Reference

Methods
l AddComment(text)
Adds a new comment with the specified text, and returns the VersionComment object created.
l Close()
Closes all views of the version that are currently open in Sibelius, returning True if it has actually
closed anything.
l GetNthComment(n)
Gets the nth comment as a VersionComment object, or returns null if the index is out of range.
l DeleteNthComment(n)
Deletes the nth comment, returning True if successful, or null if the index is out of range.
l OpenAndReturnScore()
Opens the specified version in Sibelius (if it’s not already open) and returns its Score object.

Variables
l EndDate
Returns a DateTime object representing the version’s end date (read only). IsOpen returns True if
the version is currently open in Sibelius (read only).
l Name
Returns the name of the version (read/write).
l NumComments
Returns the number of comments in the version (read only).
l StartDate
Returns a DateTime object representing the version’s start date (read only).

VersionComment
Accessed using Version objects.

Methods
None.

Variables
l Text
Returns or changes the text of the comment, and this cannot be undone (read/write).
l TimeStamp
Returns a DateTime object representing the time at which the comment was created.
l UserName
Returns the name of the user who created the comment (read only).

cxxxviii
 5 Command IDs

5 Command IDs
The following is a complete list of Command IDs that can be passed to the [Link]() method.

CommandID

Command Name

128th_note

128th note

16_tremolos

16 tremolos

16th_note

16th note (semiquaver)

256th_note

256th note

2_tremolos

2 tremolos

32_tremolos

32 tremolos

32nd_note

32nd note (demisemiquaver)

4_tremolos

4 tremolos

512th_note

512th note

64th_note

64th note (hemidemisemiquaver)

8_tremolos

8 tremolos

8th_note

Eighth note (quaver)

accent

Accent

accessibility_preferences

Accessibility Settings

cxxxix
 5 Command IDs

acciacatura

Acciaccatura

activate_deactivate_staff_filter

Activate or Deactivate Staff Filter

add_2nd_above

Add interval 2nd above

add_3rd_above

Add interval 3rd above

add_4th_above

Add interval 4th above

add_5th_above

Add interval 5th above

add_6th_above

Add interval 6th above

add_7th_above

Add interval 7th above

add_9th_above

Add interval 9th above

add_dynamic_guitar_staff

Add dynamic guitar staves

add_bar_at_end

Bar at End

add_multiple_bars

Other Bar

add_octave_above

Add interval an octave above

add_ossia_above

Add Ossia Above

add_ossia_below

Add Ossia Below

add_single_bar

Single Bar

add_stave_above

Add Staff Above

cxl
 5 Command IDs

add_stave_below

Add Staff Below

staff_filter_voice_1

Add Staff Filter: Show Voice 1

staff_filter_voice_2

Add Staff Filter: Show Voice 2

staff_filter_voice_3

Add Staff Filter: Show Voice 3

staff_filter_voice_4

Add Staff Filter: Show Voice 4

staff_filter_player_1

Add Staff Filter: Show Player 1

staff_filter_player_2

Add Staff Filter: Show Player 2

add_unison

Add unison

add_video

Add Video

advance_caret

Advance Caret

advanced_filter

Advanced Filter

align_horizontally

Align in a Column

align_staves

Align Staves

align_vertically

Align in a Row

annotate

Annotate

append_score

Append Score

appoggiatura

Appoggiatura

cxli
 5 Command IDs

arpeggio

Arpeggio

arpeggio_down

Arpeggio Down

arpeggio_up

Arpeggio Up

arrange

Arrange

auto_breaks

Auto Breaks

bar_number_change

Bar Number Change

bar_rest

Bar Rest

barline_between_staves

Between Staves Barline

barline_dashed

Dashed Barline

barline_double

Double Barline

barline_end_repeat

End Repeat Barline

barline_final

Final Barline

barline_invisible

Invisible Barline

barline_normal

Normal Barline

barline_short

Short Barline

barline_start_repeat

Start Repeat Barline

barline_ticks

Tick Barline

cxlii
 5 Command IDs

brace

Brace

bracket

Bracket

bracket_accidental

Bracket accidental

bracket_notehead

Bracket notehead

buzz_roll

Buzz roll (Z on stem)

calibrate_live_tempo

Calibrate Live Tempo

cancel_stop_selectnone

Cancel/Stop/Select None

cascade

Cascade

change_appearance_current_part

Change Current Part Appearance

change_appearance_of_all_parts

Change Appearance of All Parts

change_appearance_of_open_parts

Change Appearance of Open Parts

change_tie_style

Next tie style

chord_diagram_toggle

Add/Remove Chord Diagram

chord_symbols

Chord Symbol

chord_text_root_toggle

Add/Remove Chord Text Root

chord_text_toggle

Add/Remove Chord Text

clear_live_tempo

Clear Live Tempo

cxliii
 5 Command IDs

clef_dialog

Show Clef dialog

clefs

Clef

close_all

Close All

close_tab

Close Tab

close_window

Close Window

color

Color

color_note_none

Note Colors None

color_note_voices

Voice Colors

color_out_of_range_notes

Notes out of Range

command_search

Activate Command Search

comment

Comment

compare_window

Compare

configure_live_tempo

Configure Live Tempo

consecutive_rehearsal_mark

Rehearsal Mark (consecutive)

copy

Copy

copy_and_change_instrument_in_part

Copy and Change Instrument

copy_as_idea

Capture Idea

cxliv
 5 Command IDs

copy_part_layout

Copy Part Layout

create_highlight

Highlight

create_hitpoint

Create Hit Point

create_live_tempo_tap_point

Create Live Tempo Tap Point

create_new_part

Create New Part

create_pitch_a

Create A

create_pitch_b

Create B

create_pitch_c

Create C

create_pitch_d

Create D

create_pitch_e

Create E

create_pitch_f

Create F

create_pitch_g

Create G

create_title_page

Title Page

cross_stave_move_down

Move Down a Staff

cross_stave_move_up

Move Up a Staff

cross_stave_reset

Move to Original Staff

custom_articulation1

Custom Articulation 1

cxlv
 5 Command IDs

custom_articulation2

Custom Articulation 2

custom_articulation3

Custom Articulation 3

cut

Cut

decrease_instrument_stave_size

Decrease Instrument Staff Size

decrease_spacing

Decrease Spacing

decrease_spacing_a_lot

Decrease Spacing a Lot

default_positions

Default Positions

delete

Delete

delete_bar

Delete Bar

delete_current_part_or_subset

Delete current part or subset

delete_part

Delete Part

document_setup

Document Setup

doit

Doit

double_dot

Double dot

double_flat

Double flat

double_sharp

Double sharp

double_whole_note

Double whole note (breve)

cxlvi
 5 Command IDs

downbow

Downbow

duplet

Duplet

edit_noteheads

Notehead type gallery

edit_all_fonts

Edit All Fonts

edit_arrange_styles

Edit Arrange Styles

edit_chord_diagram

Edit Chord Diagram

edit_chord_symbols

Edit Chord Symbols

edit_hitpoints

Hit points

edit_instruments

Edit Instruments

edit_lines

Edit Lines

edit_plugins

Edit Plug-ins

edit_staves_in_part

Edit Staves in Part

edit_symbols

Edit Symbols

edit_text

Edit Text

edit_text_styles

Edit Text Styles

edit_worksheets

Edit Worksheets

end_beam

End beam

cxlvii
 5 Command IDs

end_line

End line

end_slur

End slur

engraving_rules

Engraving Rules

equivalent_chord_text

Equivalent Chord Text

exit_program

Exit

export_as_audio

Export Audio

export_as_graphic

Export Graphics

export_as_manuscript_paper

Export Manuscript Paper

export_as_midi

Export MIDI File

export_as_musicxml

Export MusicXML

export_as_older_version

Export Previous Sibelius Version

export_as_pdf

Export PDF

export_as_sib_student

Export Sibelius Student file

export_as_video

Export Video File

export_house_style

Export House Style

extend_selection_down

Extend Selection Down

extend_selection_left

Extend Selection Left

cxlviii
 5 Command IDs

extend_selection_right

Extend Selection Right

extend_selection_to_bottom_staff

Extend Selection to Bottom Staff

extend_selection_to_end_of_bar

Extend Selection to End of Bar

extend_selection_to_start_of_bar

Extend Selection to Start of Bar

extend_selection_up

Extend Selection Up

extend_selection_to_top_of_staff

Extend Selection to Top of Staff

extract_parts

Extract Parts

fall

Fall

fast_forward

Fast-forward

feathered_beam_accel

Feathered beam accel.

feathered_beam_rit

Feathered beam rit.

filter_2nd_note

2nd from Top

filter_2nd_note_for_deletion

Filter 2nd from Top (For Deletion)

filter_2nd_or_single_note_for_deletion

Filter 2nd Note or Single Notes (For Deletion)

filter_2nd_pr_single_note

Filter 2nd Note or Single Notes (For Copying)

filter_3rd_note

3rd from Top

filter_3rd_note_for_deletion

Filter 3rd from Top (For Deletion)

cxlix
 5 Command IDs

filter_3rd_or_single_note

Filter 3rd Note or Single Notes (For Copying)

filter_3rd_or_single_note_for_deletion

Filter 3rd Note or Single Notes (For Deletion)

filter_all_barlines

Filter All Barlines

filter_bar_numbers

Filter Bar Numbers

filter_bottom_note

Bottom Note

filter_bottom_note_for_deletion

Filter Bottom Note (For Deletion)

filter_bottom_or_single_note

Filter Bottom Note or Single Notes (For Copying)

filter_bottom_or_single_note_for_deletion

Filter Bottom Note or Single Notes (For Deletion)

filter_chord_symbols

Filter Chord Symbols

filter_comments

Filter Comment items

filter_dynamics

Filter Dynamics

filter_expression_text

Filter Expression Text

filter_grace_notes

Filter Grace Notes

filter_hairpins

Filter Hairpins

filter_hidden_objects

Filter Hidden Objects

filter_instrument_changes

Filter Instrument Changes

filter_lyrics

Filter Lyrics

cl
 5 Command IDs

filter_nonspecial_barlines

Filter Non-Special Barlines

filter_non_tied_notes

Filter notes that are not tied or that start a tie

filter_notes_and_chords

Filter Notes and Chords

filter_page_numbers

Filter Page Numbers

filter_pedal_lines

Filter Pedal Lines

filter_player1

Filter Player 1 (For Deletion)

filter_player2

Filter Player 2 (For Deletion)

filter_rehearsal_marks

Filter Rehearsal Marks

filter_repeat_bars

Filter Repeat Bars

filter_rests

Filter Rests

filter_slurs

Filter Slurs

filter_special_barlines

Filter Special Barlines

filter_staff_text

Filter Staff Text

filter_symbols

Filter Symbols

filter_system_text

Filter System Text

filter_technique_text

Filter Technique Text

filter_top_note

Top Note

cli
 5 Command IDs

filter_top_note_for_deletion

Filter Top Note (For Deletion)

filter_top_or_single_note

Filter Top Note or Single Notes (For Copying)

filter_top_or_single_note_for_deletion

Filter Top Note or Single Notes (For Deletion)

filter_tuplets

Filter Tuplets

filter_voice1

Filter Voice 1

filter_voice1_only

Filter Voice 1 Only

filter_voice2

Filter Voice 2

filter_voice2_only

Filter Voice 2 Only

filter_voice3

Filter Voice 3

filter_voice3_only

Filter Voice 3 Only

filter_voice4

Filter Voice 4

filter_voice4_only

Filter Voice 4 Only

find

Find

find_next

Find Next

find_next_collision

Find Next Collision

find_next_comment

Find Next Comment

find_previous_collision

Find Previous Collision

clii
 5 Command IDs

find_previous_comment

Find Previous Comment

flat

Flat

flexitime_input

Flexi-time Input

flexitime_options

Flexi-time Options

flip

Flip

focus_on_staves

Focus on Staves

freeze_magnetic_layout_positions

Freeze Magnetic Layout Positions

fretboard_window

Fretboard

full_screen

Full Screen

goto_bar

Go to Bar

goto_page

Go to Page

goto_playback_line

Go to Playback Line

goto_selection_end

Go to selection end

goto_selection_start

Go to selection start

graphic_adjust_color

Adjust Colours

graphic_change_link_source

Change Link Source

graphic_flip_horizontal

Flip Horizontal

cliii
 5 Command IDs

graphic_flip_vertical

Flip Vertical

graphic_rotate_180

Rotate 180 degrees

graphic_rotate_270

Rotate 90 degrees CCW

graphic_rotate_90

Rotate 90 degrees CW

graphics

Graphic

guitar_scale_diagram

Guitar Scale Diagram

half_note

Half note (minim)

harmonic_circle

Harmonic/Open

hide_all_invisibles

Hide All Invisibles

hide_all_panels

Hide Tool Windows

hide_empty_staves

Hide Empty Staves

hide_show_accidentals_toggle

Hide or show accidentals

hide_show_toggle

Hide or Show

ideas_window

Ideas

import_file

Import

import_house_style

Import House Style

import_lyrics

Create Lyrics From Text File

cliv
 5 Command IDs

increase_instrument_stave_size

Increase Instrument Staff Size

increase_spacing

Increase Spacing

increase_spacing_a_lot

Increase Spacing a Lot

input_notes

Input Notes

install_plugins

Install Plug-ins

instrument_and_stave_dialog

Instruments and Staves

instrument_change

Instrument Change

keep_bars_together

Keep Bars Together

key_signature_dialog

Show Key Signature dialog

key_signatures

Key Signature

keyboard_window

Keyboard

keypad

Keypad

keypad0

0 on keypad

keypad1

1 on keypad

keypad2

2 on keypad

keypad3

3 on keypad

keypad4

4 on keypad

clv
 5 Command IDs

keypad5

5 on keypad

keypad6

6 on keypad

keypad7

7 on keypad

keypad8

8 on keypad

keypad9

9 on keypad

keypad_*(Windows)_/(Mac)

keypad_+

'+' on keypad

keypad_-(Mac)

keypad_-(Windows)_*(Mac)

keypad_.

.' on keypad

keypad_/(Windows)_=(Mac)

keypad_default_size

Reset keypad size

keypad_enter

Enter on keypad

keypad_first_layout

First keypad layout

keypad_larger

Make keypad larger

keypad_next_layout

Next keypad layout

keypad_palette1

Common notes

clvi
 5 Command IDs

keypad_palette2

More notes

keypad_palette3

Beams/tremolos

keypad_palette4

Articulations

keypad_palette5

Jazz Articulations

keypad_palette6

Accidentals

keypad_smaller

Make keypad smaller

lines

Line

lines_dialog

Show Lines dialog

live_playback

Live Playback

live_playback_velocities

Live Playback Velocities

live_tempo_tap_points

Live Tempo Tap Points

lock_format

Lock Format

long

Long

magnetic_layout_off

Turn off Magnetic Layout for item

magnetic_layout_on

Turn on Magnetic Layout for item

magnetic_layout_options

Magnetic Layout Options

make_into_bar

Make Into Bar

clvii
 5 Command IDs

make_into_page

Make Into Page

make_into_score_subset

Make into score subset

make_into_system

Make Into System

manuscript_language_reference

ManuScript Language Reference

marcato

Marcato

mid_beam

Middle of beam

minimize_expand_ribbon

Minimize/Expand Ribbon

minimize_window

Minimize Window

mixer

Mixer

move_down_chromatically

Move Down Chromatically

move_instruments_down

Move Instruments Down

move_instruments_up

Move Instruments Up

move_object_down

Move Object Down

move_object_down_a_lot

Move Object Down a Lot

move_object_left

Move Object Left

move_object_left_a_lot

Move Object Left a Lot

move_object_right

Move Object Right

clviii
 5 Command IDs

move_object_right_a_lot

Move Object Right a Lot

move_object_up

Move Object Up

move_object_up_a_lot

Move Object Up a Lot

move_playback_to_selection

Move Playback Line to Selection

move_screen_left_a_bit

Move Screen Left a Bit

move_screen_right_a_bit

Move Screen Right a Bit

move_selection_to_playback

Move Selection to Playback Line

move_staff_down_a_lot

Move Staff Down a Lot (absolute)

move_staff_down_select_note_next_voice

Move Staff Down (absolute) and Select Note in Next Voice

move_staff_down_relative

Move Staff Down (relative)

move_staff_down_relative_a_lot

Move Staff Down a Lot (relative) and Select Note in Staff Below

move_staff_up_a_lot

Move Staff Up a Lot (absolute)

move_staff_up_select_note_previous_voice

Move Staff Up (absolute) and Select Note in Previous Voice

move_staff_up_relative

Move Staff Up (relative)

move_staff_up_relative_a_lot

Move Staff Up a Lot (relative) and Select Note in Staff Above

move_up_chromatically

Move Up Chromatically

natural

Natural

clix
 5 Command IDs

natural_flat

Natural flat

natural_sharp

Natural sharp

nav_down

Move stave down (relative) and Select part of object below

nav_up

Move stave up (relative) / Select part of object above

navigator

Navigator

new_file

New

new_window

New Window

next_part

Next Part

next_window_tab

Select Next Tab

no_beam

No beam

nonuplet

Nonuplet

notate_glissando_diatonic

Notate Glissando Diatonic

notate_glissando_chromatic

Notate Glissando Chromatic

note_spacing_rules

Note Spacing Rule

notehead_0

Notehead 0

notehead_1

Notehead 1

notehead_2

Notehead 2

clx
 5 Command IDs

notehead_3

Notehead 3

notehead_4

Notehead 4

notehead_5

Notehead 5

notehead_6

Notehead 6

notehead_7

Notehead 7

notehead_8

Notehead 8

notehead_9

Notehead 9

noteheads

Edit Noteheads

object_rulers

Object Rulers

octuplet

Octopus

open_file

Open

optimize_staff_spacing

Optimize Staff Spacing

ordering_move_back

Send Back

ordering_move_forward

Bring Forward

ordering_move_to_back

Send to Back

ordering_move_to_front

Bring to Front

ordering_reset_to_default

Reset to Default Order

clxi
 5 Command IDs

override_pitch_before_duration

Override pitch before duration

page_bottom

Move bottom of page

page_break

Page Break

page_down

Move down full screen

page_down_a_bit

Move page down a bit

page_first

Move to first page

page_last

Move to last page

page_left

Move left full screen

page_number_change

Page Number Change

page_right

Move right full screen

page_top

Move to top of page

page_up

Move up full screen

page_up_a_bit

Move page up a bit

panorama_view

Panorama

paste

Paste

paste_as_cue

Paste as Cue

pause

Fermata (pause)

clxii
 5 Command IDs

performance_interpretation

Performance

play/stop

Play/Stop

play/stop_or_extend_line

Play/Stop or snap line/lyric to next note

play_from_selection

Play From Selection

play_half_speed_extend_lines

Play at half-speed or snap line/lyric to previous note

play_live_tempo

Live Tempo

playback_all_notes_off

All Notes Off

playback_backward_one_frame

Move backward a single frame

playback_devices

Playback Devices

playback_dictionary

Playback Dictionary

playback_forward_one_frame

Move forward a single frame

playback_line_to_end

Move Playback Line to End

playback_line_to_start

Move Playback Line to Start

playback_stop

Stop

plop

Plop

plus

Plus/Closed

prebend_note

Pre-bend note

clxiii
 5 Command IDs

preferences

Preferences

previous_part

Previous Part

previous_window_tab

Select Previous Tab

print

Print

print_all_parts

Print All Parts

print_copies_of_parts

Print Copies of Parts

print_dialog

OS Print Dialog

publish_to_score_exchange

Publish to Score Exchange

quadruplet

Quadruplet

quarter_flat

Quarter flat

quarter_note

Quarter note (crotchet)

quarter_sharp

Quarter sharp

quick_start

Quick Start

quintuplet

Quintuplet

reapply_color

Reapply Color

rebeam

Re-beam

record_live_tempo

Record Live Tempo

clxiv
 5 Command IDs

record_with_audioscore

Record with AudioScore

redo

Redo

redo_dialog

Redo History

remove_accidental

Remove accidentals

remove_articulation

Remove articulations

remove_staves

Remove Staves

repeat

Repeat

repeat_2_bars

2 bar Repeat Bar

repeat_4_bars

4 bar Repeat Bar

repeat_bar

Repeat Bar

repeat_interpretation

Repeats

repitch

Re-input Pitches

replay

Replay

reset_beam_groups

Reset Beam Groups

reset_design

Reset Design

reset_magnetic_layout

Use default Magnetic Layout settings

reset_note_spacing

Reset Note Spacing

clxv
 5 Command IDs

reset_position

Reset Position

reset_space_above_staff

Reset Space Above Staff

reset_space_below_staff

Reset Space Below Staff

reset_stems_and_beam_positions

Reset Stems and Beam Positions

reset_tab_fingering

Reset Guitar Tab Fingering

reset_to_score_design

Reset to Score Design

reset_to_score_position

Reset to Score Position

respell

Respell Accidental/Edit Text

respell_chord_text

Respell Chord Text

rest

Rest

restart_rehearsal_marks

Restart Rehearsal Marks

revoice_chord_diagram

Revoice Chord Diagram

rewind

Rewind

rhythm_dot

Rhythm dot

save

Save

save_all

Save All

save_as

Save As

clxvi
 5 Command IDs

save_as_worksheet

Add to Worksheet Creator

scan_with_photoscore

Scan with PhotoScore

scoop

Scoop

score_info

Score Info

scrub_backwards

Scrub Backward

scrub_forward

Scrub Forward

select_all

Select All

select_bars

Select Bars

select_graphic

Select Graphic

select_more

Select More

select_next_fragment

Select Next Part of Object

select_next_note

Move Object Right/Select Next Note

select_next_object

Select Next Object

select_next_system_object

Select Next System Object

select_none

Select None

select_previous_fragment

Select Previous Part of Object

select_previous_note

Move Object Left/Select Previous Note

clxvii
 5 Command IDs

select_previous_object

Select Previous Object

select_previous_system_object

Select Previous System Object

select_system_passage

Select System Passage

section_end

Section End

selection_rulers

Selection Rulers

septuplet

Septuplet

sextuplet

Sextuplet

sharp

Sharp

show_annotations

View Annotations

show_attachment_lines

Attachment Lines

show_bar_numbers

Staff Names and Bar Numbers

show_comments

View Comments

show_differences_between_versions

View Differences Between Versions

show_differences_in_parts

Differences In Parts

show_empty_staves

Show Empty Staves

show_handles

Handles

show_hidden_objects

Hidden Objects

clxviii
 5 Command IDs

show_highlights

Highlights

show_in_all

Show in All

show_in_parts

Show in Parts

show_in_score

Show in Score

show_inspector

Inspector

show_layout_marks

Layout Marks

show_magnetic_layout_collisions

Magnetic Layout Collisions

show_magnetic_layout_groups

View Magnetic Layout Groups

show_magnetic_layout_original_positions

View Magnetic Layout Original Positions

show_page_margins

Page Margins

show_playback_line

Playback Line

show_plugin_trace

Show Plugin Trace Window

show_replay_marker

Replay Line

sibelius_help

Sibelius Help

sibelius_tutorials

Sibelius Tutorials

single_pages_horizontally

Single Pages Horizontally

single_pages_vertically

Single Pages Vertically

clxix
 5 Command IDs

slide

Slide

slide_notes_or_rests_left

Slide notes or rests left

slide_notes_or_rests_right

Slide notes or rests right

snap_line_next_note

Snap line/lyric to next note

special_page_break

Special Page Break

split_multirest

Split Multirest

split_system

Split System

spreads_horizontally

Spreads Horizontally

spreads_vertically

Spreads Vertically

squarepause

Long fermata

staccatissimo

Staccatissimo

staccato

Staccato

staff_rulers

Staff Rulers

start_beam

Start beam

start_sub_beam

Start secondary beam

stemlet

Stemlet

subbracket

Sub-bracket

clxx
 5 Command IDs

suppress_auto_cautionary_accidental

Suppress auto cautionary accidental

swap_voices_1_and_2

Swap Voices 1 and 2

swap_voices_1_and_3

Swap Voices 1 and 3

swap_voices_1_and_4

Swap Voices 1 and 4

swap_voices_2_and_3

Swap Voices 2 and 3

swap_voices_2_and_4

Swap Voices 2 and 4

swap_voices_3_and_4

Swap Voices 3 and 4

switch_between_full_score_and_parts

Switch Between Full Score and Part

symbols

Symbol

symbols_dialog

Show symbols dialog

system_break

System Break

system_break_respell_edit_text

System Break/Respell Accidental/Edit Text

system_object_positions

System Object Positions

tab_fret_number0

Fret number 0 on tab

tenuto

Tenuto

text_styles

Text Style

three_quarter_flat

Three quarter flat

clxxi
 5 Command IDs

three_quarter_sharp

Three quarter sharp

tie

Tie

tie_into

Tie Into

tile_horizontally

Tile Horizontally

tile_vertically

Tile Vertically

time_signature_dialog

Show Time Signature dialog

time_signatures

Time Signature

timecode_and_duration

Timecode and Duration

timeline

Timeline

toggle_auto_optimize

Switch Auto-Optimize on / off

toggle_cue_size

Cue size (on/off)

toggle_loop_mode

Loop

toggle_lv_tie

Toggle L.V. tie

toggle_magnetic_layout

Switch magnetic layout on / off

toggle_notes/rests

Toggle Notes/Rests

toggle_review_mode

Toggle Review Mode

toggle_sticky_tuplet

Toggle sticky tuplet

clxxii
 5 Command IDs

tranposing_score

Transposing Score

transform_live_playback

Transform Live Playback

transport

Transport

transpose

Transpose

tremolo_with_next_note

Tremolo with next note

tripause

Short fermata

triple_dot

Triple dot

triplet

Triplet

tuplet

Tuplet

turn_note_into_grace_note

Turn note into gracenote

undo

Undo

undo_dialog

Undo History

unlock_format

Unlock Format

upbow

Upbow

use_multirests

Use Multirests

versions_edit

Edit Versions

versions_export_current

Export Current Version

clxxiii
 5 Command IDs

versions_export_log

Export Version Log

versions_make_current

Make Current Version

versions_save

Save Version

versions_show_next

Show Next Version

versions_show_previous

Show Previous Version

video_double_size

Double Size

video_fullscreen

Full Screen

video_half_size

Half Size

video_normal_size

Full Size

video_window

Video

view_live_tempo

View Live Tempo

voice1

Voice 1

voice2

Voice 2

voice3

Voice 3

voice4

Voice 4

voice_all

Voice All

wedge

Wedge

clxxiv
 5 Command IDs

whats_new

What's New

whole_note

Whole note (semibreve)

worksheet_creator

Worksheet Creator

zoom_100%

Zoom 100%

zoom_12.5%

Zoom 12.5%

zoom_125%

Zoom 125%

zoom_150%

Zoom 150%

zoom_200%

Zoom 200%

zoom_25%

Zoom 25%

zoom_300%

Zoom 300%

zoom_37.5%

Zoom 37.5%

zoom_400%

Zoom 400%

zoom_50%

Zoom 50%

zoom_62.5%

Zoom 62.5%

zoom_75%

Zoom 75%

zoom_800%

Zoom 800%

zoom_87.5%

Zoom 87.5%

clxxv
 5 Command IDs

zoom_actual_size

Zoom to actual size

zoom_edit

Zoom

zoom_in

Zoom In

zoom_out

Zoom Out

zoom_to_fit

Zoom to fit page

zoom_to_fit_page

Zoom Window

zoom_to_fit_two_pages

Zoom to fit 2 pages

zoom_to_page_height

Zoom to page height

zoom_to_page_width

Zoom to fit page width

zoom_to_system_width

Zoom to system width

clxxvi
 6 Sibelius Connect

6 Sibelius Connect
Using Sibelius Connect, you can remotely control Sibelius by using apps running locally or from a mobile
device or tablet. Sibelius Connect lets third-party developers create apps to control Sibelius over localhost
using ManuScript command IDs.

User Interface
You can enable (or disable) the remote control feature by going to the Input Devices page of the
Preferences dialog. The network port used for the websocket connection is 1898 by default, but can be
overridden with any value between 1025 and 65535.

Websocket Connection
The websocket connection URL is [Link] (by default) and is left unsecure. You can test it using
a simple web browser. The PieSocket Websocket tester Chrome extension has been found to work for this.
Sibelius only accepts a connection originating from an application running on the same host (such as the
Stream Deck application).

Initial Handshake
Sibelius expects the first message to contain connection details, but if not it immediately closes the
connection. The connection message must contain the file name without extension of every plug-in, if any,
that you intend to invoke remotely.

The first message from the remote control application must be the "connect" message.

Here is some sample code.

const sibsocket = new WebSocket('[Link]

[Link] = function(event) {

var connectMsg = {
"message": "connect",

"clientName": "NameOfYourApplication",

"handshakeVersion": "1.0",

"plugins": [ "plugin1", "plugin2", "plugin3" ], // optional

// or

"sessionToken": "{token-from-previous-connection}" // optional

};

[Link]([Link](connectMsg));

[Link] = function(event){

var jsonObj = [Link]([Link]);

[Link](jsonObj);

clxxvii
 6 Sibelius Connect

In response to the connection message, Sibelius responds:

{ "sessionToken" : "SESSION_TOKEN" }

The sessionToken can be provided to re-establish a connection. In that case, the user won't be prompted.
It is valid as long as Sibelius runs. Note that the plug-in list cannot be changed when re-connecting with a
token.

Commands
Sibelius commands are invoked using the "invokeCommands", which expects to receive a JSON array of
command IDs, like so:

{ "message" : "invokeCommands", "commands": [ "command_id_1", "command_id_2",

"command_id_3", ... ] }

For example: {"message" : "invokeCommands", "commands" : [ "select_all", "delete"

]}

At this time, the invokeCommands message always returns "success" to the caller.

Calling "invokeCommands" causes Sibelius to respond with a message like so:

{"message":"invokeCommandsResponse","result":true}

ManuScript Plug-ins
To call into a ManuScript plug-in, the "invokePlugin" message is used. It has a mandatory "name"
argument that contains the file name without extension of the plug-in to call. The other two arguments
(method and arguments) are optional.

It can take one of the following forms:

l Call [Link]() (default)
{ "message" : "invokePlugin", "name": "pluginX" }
l Call [Link]() without arguments:
{ "message" : "invokePlugin", "name": "pluginX", "method": "Method" }
l Call [Link]() with the arguments provided
{ "message" : "invokePlugin", "name": "pluginX", "method": "Method",
"args": [ true, 42, 3.14159, "hello" ] }
l Call [Link]() with the arguments provided—2nd argument is a Dictionary:
{"message":"invokePlugin", "name" : "testme", "method": "Method1", "args":
[ 42, { "key1" : 1, "key2" : "key2 is a string"} ]}
l Call [Link]() with the arguments provided—2nd argument is a nested Array:
{"message":"invokePlugin", "name" : "testme", "method": "Method1", "args":
[ 42, ["v1", "v2", 37] ]}
Note that "args" is an array of arguments passed to the method. Each argument can be a string, boolean
value, a number, an array or a dictionary. Arrays and dictionaries are represented as an embedded JSON
array and object, respectively.

Also note that even though the JSON array is mapped to a ManuScript sparse array, the array is not really
"sparse". Indices start at 0 and are consecutive.)

clxxviii
 6 Sibelius Connect

l Calling "invokePlugin" causes Sibelius to respond with a message like:

{"message":"invokePluginResponse","result":true,"return_value":""}
Result indicates whether the plug-in and method were successfully found and called. When the call is
successful, "returnValue" is the value returned by plug-in’s method, if any. If the method doesn’t return a
value, it contains an empty string. As for arguments, strings, booleans, numbers, arrays and dictionaries
are supported, with the latter 2 represented as a JSON array and object.

If the method returns an object that cannot be translated to JSON, the response message contains a JSON
null value.

clxxix
 7 Global Constants

7 Global Constants
These are useful variables held internally within ManuScript and are accessible from any plug-in. They are
called "constants" because you are encouraged not to change them.

Many of the constants are the names of note values, which you can use to specify a position in a bar. For
example, instead of writing 320 you can write Quarter+Sixteenth or equally Crotchet+Semiquaver.

Truth Values
True 1
False 0

Measurements
Space 32
StaffHeight 128

Positions and Durations

Long 4096
Breve 2048
DottedBreve 3072
Whole or Semibreve 1024
DottedWhole 1536
Half or Minim 512
DottedHalf or DottedMinim 768
Quarter or Crotchet 256
DottedQuarter or DottedCrotchet 384
Eighth or Quaver 128
DottedEighth or DottedQuaver 192
Sixteenth or Semiquaver 64
DottedSixteenth or DottedSemiquaver 96
ThirtySecond or Demisemiquaver 32
DottedThirtySecond or DottedDemisemiquaver 48
SixtyFourth or Hemidemisemiquaver 16
DottedSixtyFourth or DottedHemidemisemiquaver 24
OneHundredTwentyEighth or Semihemidemisemiquaver 8
DottedOneHundredTwentyEighth or DottedSemihemidemisemiquaver 12

clxxx
 7 Global Constants

Style Names
For the ApplyStyle() method of Score objects. Instead of the capitalized strings in quotes, you can use
the equivalent variables in mixed upper and lower case. Note again that the constant HOUSE refers to the
options in House Style > Engraving Rules and Layout > Document Setup only; to apply the
entire House Style, use the ALLSTYLES constant.

Engraving "ENGRAVINGRULES" Document Setup "DOCSETUP"

Rules
House "HOUSE" Dictionary "DICTIONARY"
Text "TEXT" SpacingRule "SPACINGRULE"
Symbols "SYMBOLS" CustomChordNames "CUSTOMCHORDNAMES"
Lines "LINES" DefaultPartAppearance "DEFAULTPARTAPPEARANCE"
Noteheads "NOTEHEADS" InstrumentsAndEnsembles "INSTRUMENTSANDENSEMBLES"
Clefs "CLEFS" AllStyles "ALLSTYLES"

Bar Number Formats

These constants can be used for the format argument of the AddBarNumber method.

BarNumberFormatNormal 0
BarNumberFormatNumberLetterLower 1
BarNumberFormatNumberLetterUpper 2

Text Styles
Here is a list of all the text style identifiers which are guaranteed to be present in any score in Sibelius. In
previous versions of ManuScript text styles were identified by a numeric index; this usage has been
deprecated but will continue to work for old plug-ins. New plug-ins should use the identifiers given below.
For each style we first give the English name of the style and then the identifier.

Instrument "[Link]" Time "[Link]"

names signatures
(one staff
only)
1st and 2nd "[Link].1st_n_2nd_endings" Tuplets "[Link]"
endings
Auto page "[Link]" Bar numbers "[Link]"
break
warnings
Boxed text "[Link]" Metronome "[Link]"
mark
Expression "[Link]" Multirests "[Link]"
(numbers)
Chord "[Link].chord_diagrams" Composer "[Link].page_
diagram [Link]"
fingering
Footnote "[Link]" Composer "[Link].page_

clxxxi
 7 Global Constants

(on title page) [Link]"

Block lyrics "[Link]" Copyright "[Link].page_
[Link]"
Multirests "[Link]" Dedication "[Link].page_
(tacet) [Link]"
Plain text "[Link]" Footer (inside "[Link].page_
edge) [Link]"
Small text "[Link]" Footer "[Link].page_
(outside [Link]"
edge)
Chord symbol "[Link]" Worksheet "[Link].page_
footer [Link]"
(first page, l)
Figured bass "[Link]" Header "[Link].page_
[Link]"
Fingering "[Link]" Worksheet "[Link].page_
header [Link]"
(first page, l)
Chord "[Link]" Worksheet "[Link].page_
diagram fret header [Link]"
(first page, r)
Lyrics above "[Link]" Header "[Link].page_
staff (after first aligned.header_notp1"
page)
Lyrics "[Link]" Header "[Link].page_
(chorus) (after first aligned.header_notp1.inside"
page, inside
edge)
Lyrics line 1 "[Link].verse1" Instrument "[Link].page_
name at top [Link]"
left
Lyrics line 2 "[Link].verse2" Lyricist "[Link].page_
[Link]"
Lyrics line 3 "[Link].verse3" Page "[Link].page_
numbers [Link]"
Lyrics line 4 "[Link].verse4" Subtitle "[Link].page_
[Link]"
Lyrics line 5 "[Link].verse5" Title "[Link].page_aligned.title"
Nashville "[Link]" Title "[Link].page_
chord (on title page) [Link]"
numbers
Common "[Link]" Rehearsal "[Link]"
symbols mark
Figured bass "[Link] Repeat (D.C./ "[Link]"
(extras) s" D.S./To
Coda)

clxxxii
 7 Global Constants

Note tails "[Link]" Tempo "[Link]"

Special "[Link]" Timecode "[Link]"
noteheads
Percussion "[Link]" Duration at "[Link]"
instruments end of score
Special "[Link]" Hit points "[Link]"
symbols
Tablature "[Link]" Time "[Link]"
letters signatures
(huge)
Tablature "[Link]" Time "[Link]"
numbers signatures
(large)
Technique "[Link]" Time "[Link]"
signatures
Boxed text (on "[Link]" Composer "[Link]"
blank page (on blank
page
Dedication "[Link]" Instrument "[Link]"
(on blank name at top
page) left (on blank
page)
Plain text (on "[Link]" Plain text, "[Link]"
blank page) centered (on
blank page)
Plain text, "[Link]" Subtitle (on "[Link]"
right (on blank page)
blank page)
Title (on blank "[Link]"
page)

Line Styles
Arpeggio "[Link]" Bracketed "[Link]"
slur below
Arpeggio "[Link]" Dashed "[Link]"
down slur below
Arpeggio up "[Link]" Dotted slur "[Link]"
below
Unused 2 "[Link]" Slur above "[Link]"
Arrow "[Link]" Bracketed "[Link]"
slur above
Dashed arrow "[Link]" Dashed "[Link]"
slur above
Double arrow "[Link]" Dotted slur "[Link]"
above

clxxxiii
 7 Global Constants

Vertical arrow "[Link]" String "[Link].1"

(2) indicator
above (1)
White arrow "[Link]" String "[Link].2"
indicator
above (2)
Dashed white "[Link]" String "[Link].3"
arrow indicator
above (3)
Double white "[Link]" String "[Link].4"
arrow indicator
above (4)
Vertical arrow "[Link]" String "[Link].5"
indicator
above (5)
Beam "[Link]" String "[Link].6"
indicator
above (6)
Guitar Bend "[Link]" String "[Link].7"
indicator
above (7)
Guitar hold "[Link]" String "[Link].8"
bend indicator
above (8)
Box "[Link]" String "[Link].1"
indicator
below (1)
Bracket above "[Link]" String "[Link].2"
indicator
below (2)
Bracket above "[Link]" String "[Link].3"
(end) indicator
below (3)
Bracket above "[Link]" String "[Link].4"
(start) indicator
below (4)
Bracket below "[Link]" String "[Link].5"
indicator
below (5)
Bracket below "[Link]" String "[Link].6"
(end) indicator
below (6)
Bracket below "[Link]" String "[Link].7"
(start) indicator
below (7)
Vertical "[Link]" String "[Link].8"
bracket indicator

clxxxiv
 7 Global Constants

below (8)
Vertical "[Link].2" Tie "[Link]"
bracket 2
Dashed line "[Link]" Trill "[Link]"
Vertical "[Link]" Tuplet "[Link]"
dashed line
Dotted line "[Link]" Vertical "[Link]"
line
Glissando "[Link]" Vibrato "[Link]"
(straight)
Glissando "[Link]" Guitar "[Link]"
(wavy) vibrato bar
Guitar effect "[Link]" Wide "[Link]"
vibrato
Crescendo "[Link]" Dashed "[Link]"
system line
Bracketed "[Link] Wide "[Link]"
crescendo ed" dashed
system line
Dashed "[Link]" 1st ending "[Link].1st"
crescendo
Dotted "[Link]" 1st and 2nd "[Link].1st_n_2nd"
crescendo ending
Crescendo "[Link] 2nd ending "[Link].2nd"
from silence nce"
Diminuendo "[Link]" 2nd ending "[Link]"
(closed)
Bracketed "[Link] 3rd ending "[Link].3rd"
diminuendo ted"
Dashed "[Link] Repeat "[Link]"
diminuendo d" ending
(closed)
Dotted "[Link] Repeat "[Link]"
diminuendo d" ending
(open)
Diminuendo "[Link] Accel. "[Link]"
to silence ce"
Guitar "[Link]" Accel. "[Link]"
artificial (italic)
harmonic
Guitar harp "[Link]" Accel. "[Link]
harmonic (italic, text nly"
only)
Guitar pinch "[Link]" Molto "[Link]"
harmonic accel.

clxxxv
 7 Global Constants

Guitar touch "[Link]" Molto "[Link]

harmonic accel. nly"
(text only)
Guitar "[Link]" Poco accel. "[Link]"
harmonics
Hauptstimme "[Link]" Poco accel. "[Link]
(text only) nly"
Guitar let ring "[Link]" Accel. (text "[Link]"
only)
Lyric line "[Link]" Tempo "[Link]"
change
(arrow
right)
Guitar palm "[Link]" Rall. "[Link]"
mute
Nebenstimme "[Link]" Rall. (italic) "[Link]"
2 octaves "[Link].minus15" Rall. "[Link]
down (italic, text y"
only)
Octave down "[Link].minus8" Molto rall. "[Link]"
2 octaves up "[Link].plus15" Molto rall. "[Link]
(text only) y"
Octave up "[Link].plus8" Poco rall. "[Link]"
Pedal "[Link]" Poco rall. "[Link]
(text only) y"
Pedal lift "[Link]" Rall. (text "[Link]"
only)
Pedal lift "[Link]" Rit. "[Link]"
again
Pedal lift "[Link]" Rit. (italic) "[Link]"
finally
Pedal (no line) "[Link]" Rit. (italic, "[Link]"
text only)
Guitar pick "[Link]" Molto rit. "[Link]"
scrape
Line "[Link]" Molto rit. "[Link]
(text only) y"
Portamento "[Link]" Poco rit. "[Link]"
Guitar rake "[Link]" Poco rit. "[Link]"
(text only)
Guitar slide "[Link]" Rit. (text "[Link]"
only)
Slur below "[Link]"

clxxxvi
 7 Global Constants

Clef Styles
Here is a list of all the clef style identifiers that are guaranteed to be present in any score in Sibelius, for use
with the [Link] method. For each style we first give the English name of the style, and then the
identifier.

Alto "[Link]" Small tab "[Link]"

Baritone C "[Link].c" Small tab (taller) "[Link]"
Baritone F "[Link].f" Tab (taller) "[Link]"
Bass "[Link]" Tenor "[Link]"
Bass down 8 "[Link].8" Tenor down 8 "[Link].8"
Bass up 15 "[Link].15" Treble "[Link]"
Bass up 8 "[Link].8" Treble down 8 "[Link].8"
Null "[Link]" Treble (down 8) "[Link]"
Percussion "[Link]" Treble down 8 (old) "[Link]"
Percussion 2 "clef.percussion_2" Treble up 15 "[Link].15"
Soprano "[Link]" Treble up 8 "[Link].8"
Mezzo-soprano "[Link]" French violin "[Link]"
Tab "[Link]" Sub-bass F "[Link]-bass.f"

Instrument Types
Here is a list of all the instrument type identifiers that are guaranteed to be present in any score in Sibelius.
For each style we first give the English name of the style and then the identifier. Note that only the tablature
stave types can be used with guitar frames; the rest are included for completeness.

Alp-Horn in F [Link]-horn.f
Alp-Horn in G [Link]-horn.g
Baritone Bugle in G [Link].g
Contrabass Bugle in G [Link].g
Euphonium Bugle in G [Link].g
Mellophone Bugle in G [Link].g
Soprano Bugle in G [Link].g
Cimbasso in Bb [Link]
Cimbasso in Eb [Link]
Cimbasso in F [Link].f
Cornet in A [Link].a
Cornet in Bb [Link]
Soprano Cornet in Eb [Link]
Euphonium in Bb [treble clef] [Link]
Euphonium in Bb [bass clef, treble transp.] [Link]
Euphonium in C [bass clef] [Link]

clxxxvii
 7 Global Constants

Euphonium in Bb [bass clef] [Link]

Flugelhorn [Link]
Horn in A [no key] [Link]
Horn in Ab alto [no key] [Link]
Alto Horn in Eb [Link]
Alto Horn in F [Link].f
Horn in B [no key] [Link]
Baritone in Bb [treble clef] [Link]
Baritone in C [treble clef] [Link].2
Baritone in Bb [bass clef, treble transp.] [Link]
Baritone in C [bass clef] [Link]
Bass in Bb [Link]
Bass in Bb [bass clef, treble transp.] [Link]
Bass in C [Link].c
Bass in Eb [Link]
Bass in Eb [bass clef, treble transp.] [Link]
A Basso Horn [no key] [Link]
Bb Basso Horn [no key] [Link]
C Basso Horn [no key] [Link]
Horn in Bb [no key] [Link]
Horn in C [no key] [Link]
Horn in D [no key] [Link]
Horn in Db [no key] [Link]
Horn in E [no key] [Link]
Horn in Eb [Link]
Horn in Eb [no key] [Link]
Horn in F [Link].f
Horn in F [bass clef] [Link]
Horn in F [no key] [Link]
Horn in F# [no key] [Link]
Horn in G [no key] [Link]
Tenor Horn [Link]
Mellophone in Eb [Link]
Mellophone in F [Link].f
Mellophonium in Eb [Link]
Mellophonium in F [Link].f

clxxxviii
 7 Global Constants

Ophicleide [Link]
Brass [Link]
Serpent [Link]
Sousaphone in Bb [Link]
Sousaphone in Eb [Link]
Trombone [Link]
Alto Trombone [Link]
Bass Trombone [Link]
Trombone in Bb [bass clef, treble transp.] [Link]
Contrabass Trombone [Link]
Tenor Trombone [Link]
Trombone in Bb [treble clef] [Link]
Trumpet in A [Link].a
Trumpet in B [no key] [Link]
Bass Trumpet in Bb [Link]
Bass Trumpet in Eb [Link]
Trumpet in Bb [Link]
Trumpet in Bb [no key] [Link]
Trumpet in C [Link].c
Trumpet in D [Link].d
Trumpet in Db [Link]
Trumpet in E [no key] [Link]
Trumpet in Eb [Link]
Trumpet in F [Link].f
Trumpet in G [no key] [Link]
Piccolo Trumpet in A [Link].a
Piccolo Trumpet in Bb [Link]
Tenor Trumpet in Eb [Link]
Tuba [Link]
Tuba in F [Link].f
Tenor Tuba (Wagner, in Bb) [Link]
Tenor Tuba [bass clef] [Link]
Wagner Tuba in Bb [Link]
Wagner Tuba in F [Link].f
Applause [Link]
Birdsong [Link]

clxxxix
 7 Global Constants

Helicopter [Link]
Ondes Martenot [Link]-martenot
Sampler [Link]
Seashore [Link]
Tape [Link]
Telephone [Link]
Theremin [Link]
Bajo [notation] [Link].5lines
Bajo, 6-string [tab] [Link]
Bajo, 4-string [tab] [Link].4lines
Bajo, 5-string [tab] [Link].5lines
Alto Balalaika [notation] [Link].5lines
Alto Balalaika [tab] [Link]
Bass Balalaika [notation] [Link].5lines
Bass Balalaika [tab] [Link]
Contrabass Balalaika [notation] [Link].5lines
Contrabass Balalaika [tab] [Link]
Prima Balalaika [notation] [Link].5lines
Prima Balalaika [tab] [Link]
Second Balalaika [notation] [Link].5lines
Second Balalaika [tab] [Link]
Bandola [notation] [Link].5lines
Bandola [tab] [Link]
Bandolón [notation] [Link].5lines
Bandolón [tab] [Link]
Bandurria [notation] [Link].5lines
Bandurria [tab] [Link]
Banjo [notation] [Link].5lines
Banjo (aDADE tuning) [tab] [Link]
Banjo (aEADE tuning) [tab] [Link]
Banjo (gCGBD tuning) [tab] [Link]
Banjo (gCGCD tuning) [tab] [Link]
Banjo (gDF#AD tuning) [tab] [Link]
Banjo (gDGBD tuning) [tab] [Link]
Banjo (gDGCD tuning) [tab] [Link]
Tenor Banjo [notation] [Link].5lines

cxc
 7 Global Constants

Tenor Banjo [tab] [Link]

Bordonúa [notation] [Link].5lines
Bordonúa [tab] [Link]
Cavaquinho [notation] [Link].5lines
Cavaquinho [tab] [Link]
Charango [notation] [Link].5lines
Charango [tab] [Link]
Cuatro [notation] [Link].5lines
Cuatro, Puerto Rico [tab] [Link]
Cuatro, Venezuela [tab] [Link]
Resonator guitar [notation] [Link].5lines
Resonator Guitar, A6 tuning [tab] [Link]
Resonator Guitar, B11 tuning [tab] [Link]
Resonator Guitar, C#m tuning [tab] [Link].c#[Link]
Resonator Guitar, C6+A7 tuning [tab] [Link]
Resonator Guitar, C6 + high G tuning [tab] [Link]
Resonator Guitar, standard tuning [tab] [Link]
Resonator Guitar, C#m7 tuning [tab] [Link]
Resonator Guitar, E13 Hawaiian tuning [tab] [Link]
Resonator Guitar, E13 Western tuning [tab] [Link]
Resonator Guitar, open A tuning [tab] [Link]
Resonator Guitar, open G tuning [tab] [Link]
Dulcimer [Link]
Dulcimer [notation] [Link].5lines
Dulcimer (DAA tuning) [tab] [Link]
Dulcimer (DAD tuning) [tab] [Link]
Gamba [notation] [Link].5lines
Gamba [tab] [Link]
12-string Acoustic Guitar [notation] [Link].12-string.5lines
12-string Acoustic Guitar, DADGAD tuning [tab] [Link]
12-string Acoustic Guitar, double D tuning [tab] [Link]
12-string Acoustic Guitar, dropped D tuning [tab] [Link]
12-string Acoustic Guitar, open D tuning [tab] [Link]
12-string Acoustic Guitar, open E tuning [tab] [Link]
12-string Acoustic Guitar, open G tuning [tab] [Link]
12-string Acoustic Guitar, standard tuning (no [Link]
rhythms) [tab]

cxci
 7 Global Constants

12-string Acoustic Guitar, standard tuning [tab] [Link]

Acoustic Guitar [notation] [Link].5lines
Acoustic Guitar, DADGAD tuning [tab] [Link]
Acoustic Guitar, double D tuning [tab] [Link]
Acoustic Guitar, dropped D tuning [tab] [Link]
Acoustic Guitar, modal D tuning [tab] [Link]
Acoustic Guitar, Nashville tuning [tab] [Link]
Acoustic Guitar, open A tuning [tab] [Link]
Acoustic Guitar, open C tuning [tab] [Link]
Acoustic Guitar, open D tuning [tab] [Link]
Acoustic Guitar, open Dm cross-note tuning [Link]
[tab]
Acoustic Guitar, open E tuning [tab] [Link]
Acoustic Guitar, open G tuning [tab] [Link]
Acoustic Guitar, standard tuning (no rhythms) [Link]
[tab]
Acoustic Guitar, standard tuning [tab] [Link]
4-string Bass Guitar [notation] [Link].4-string.5lines
4-string Bass Guitar [tab] [Link]
5-string Bass Guitar [notation] [Link].5-string.5lines
5-string Bass Guitar [tab] [Link]
Bass Guitar [notation] [Link].5lines
6-string Bass Guitar [notation] [Link].6-string.5lines
6-string Bass Guitar [tab] [Link]
Acoustic Bass [notation] [Link].5lines
Acoustic Bass [tab] [Link]
5-string Electric Bass [notation] [Link].5-string.5lines
5-string Electric Bass [tab] [Link]
Electric Bass [notation] [Link].5lines
6-string Electric Bass [notation] [Link].6-string.5lines
6-string Electric Bass [tab] [Link]
5-string Fretless Electric Bass [Link].5-string.5lines
5-string Fretless Electric Bass [tab] [Link]
Fretless Electric Bass [notation] [Link].5lines
6-string Fretless Electric Bass [Link].6-string.5lines
6-string Fretless Electric Bass [tab] [Link]
Fretless Electric Bass [tab] [Link]
Electric Bass [tab] [Link]

cxcii
 7 Global Constants

5-string Fretless Bass Guitar [notation] [Link].5-string.5lines

5-string Fretless Bass Guitar [tab] [Link]
Fretless Bass Guitar [notation] [Link].5lines
6-string Fretless Bass Guitar [notation] [Link].6-string.5lines
6-string Fretless Bass Guitar [tab] [Link]
Fretless Bass Guitar [tab] [Link]
Semi-Acoustic Bass [notation] [Link]-acoustic.5lines
Semi-Acoustic Bass [tab] [Link]
Bass Guitar [tab] [Link]
Bass Guitar [tab, with rhythms] [Link]
Classical Guitar [notation] [Link].5lines
Classical Guitar, DADGAD tuning [tab] [Link]
Classical Guitar, double D tuning [tab] [Link]
Classical Guitar, dropped D tuning [tab] [Link]
Classical Guitar, open D tuning [tab] [Link]
Classical Guitar, open E tuning [tab] [Link]
Classical Guitar, open G tuning [tab] [Link]
Classical Guitar, standard tuning (no rhythms) [Link]
[tab]
Classical Guitar, standard tuning [tab] [Link]
Electric Guitar [notation] [Link].5lines
7-string Electric Guitar, low A tuning [tab] [Link]
7-string Electric Guitar, low B tuning [tab] [Link]
Electric Guitar, DADGAD tuning [tab] [Link]
Electric Guitar, double D tuning [tab] [Link]
Electric Guitar, dropped D tuning [tab] [Link]
Electric Guitar, open D tuning [tab] [Link]
Electric Guitar, open E tuning [tab] [Link]
Electric Guitar, open G tuning [tab] [Link]
Electric Guitar, standard tuning (no rhythms) [Link]
[tab]
Electric Guitar, standard tuning [tab] [Link]
Kora [Link]
Semi-acoustic Guitar [notation] [Link]-acoustic.5lines
Semi-acoustic Guitar, DADGAD tuning [tab] [Link]
Semi-acoustic Guitar, double D tuning [tab] [Link]
Semi-acoustic Guitar, dropped D tuning [tab] [Link]
Semi-acoustic Guitar, open D tuning [tab] [Link]

cxciii
 7 Global Constants

Semi-acoustic Guitar, open E tuning [tab] [Link]

Semi-acoustic Guitar, open G tuning [tab] [Link]
Semi-acoustic Guitar, standard tuning (no [Link]
rhythms) [tab]
Semi-acoustic Guitar, standard tuning [tab] [Link]
10-string Hawaiian Steel Guitar [tab] [Link]
Hawaiian Steel Guitar [notation] [Link].5lines
6-string Hawaiian Steel Guitar, standard tuning [Link]
[tab]
6-string Hawaiian Steel Guitar, alternate tuning [Link].6-
[tab] [Link]
6-string Hawaiian Steel Guitar, slack key [Link].6-
Bb Mauna Loa tuning [tab] [Link]
6-string Hawaiian Steel Guitar, slack key [Link].6-
C Mauna Loa tuning [tab] [Link]
6-string Hawaiian Steel Guitar, slack key [Link].6-
Wahine CGDGBD tuning [tab] [Link]
6-string Hawaiian Steel Guitar, slack key [Link].6-
Wahine CGDGBE tuning [tab] [Link]
6-string Hawaiian Steel Guitar, slack key [Link].6-
Wahine DGDF#BD tuning [tab] [Link]
6-string Hawaiian Steel Guitar, slack key [Link].6-
G Mauna Loa tuning [tab] [Link]
6-string Hawaiian Steel Guitar, slack key [Link].6-
G Taro Patch tuning [tab] [Link]
6-string Hawaiian Steel Guitar, slack key [Link].6-
Wahine GCDGBE tuning [tab] [Link]
8-string Hawaiian Steel Guitar [tab] [Link]
8-string Hawaiian Steel Guitar, alternate tuning [Link].8-
[tab] [Link]
Hawaiian Steel Guitar [tab] [Link]
Pedal Steel Guitar [notation] [Link].5lines
Pedal Steel Guitar [tab] [Link]
Guitarra [notation] [Link].5lines
Guitarra, Coimbra [tab] [Link]
Guitarra, Lisboa [tab] [Link]
Guitarra, Portuguesa [tab] [Link]
Guitarrón [notation] [Link].5lines
Guitarrón [tab] [Link]
Laúd [notation] [Link].5lines

cxciv
 7 Global Constants

Laúd [tab] [Link]

Tenor Lute [notation] [Link].5lines
Bass Lute [notation] [Link].5lines
Bass Lute, D tuning, French/English [tab] [Link]
Bass Lute, D tuning, Italian [tab] [Link]
Bass Lute, D tuning, Spanish [tab] [Link]
Tenor Lute, G tuning, Italian [tab] [Link]
Tenor Lute, G tuning, Spanish [tab] [Link]
Tenor Lute, G tuning, French/English [tab] [Link]
Tenor Lute, A tuning, French/English [tab] [Link]
Tenor Lute, A tuning, Italian [tab] [Link]
Tenor Lute, A tuning, Spanish [tab] [Link]
Treble Lute [notation] [Link].5lines
Treble Lute, D tuning, French/English [tab] [Link]
Treble Lute, D tuning, Italian [tab] [Link]
Treble Lute, D tuning, Spanish [tab] [Link]
Mandolin [notation] [Link].5lines
Mandolin [tab] [Link]
Oud [notation] [Link].5lines
Oud [tab] [Link]
Qanoon [Link].5lines
Requinto [notation] [Link].5lines
Requinto [tab] [Link]
Santoor [Link].5lines
Sitar [notation] [Link].5lines
Sitar (Ravi Shankar) [tab] [Link]
Sitar (Vilayat Khan) [tab] [Link]
Tambura (Female) [notation] [Link]
Tambura (Male) [notation] [Link]
Tiple [notation] [Link].5lines
Tiple, Argentina [tab] [Link]
Tiple, Colombia ADF#B tuning [tab] [Link]
Tiple, Colombia DGBE tuning [tab] [Link]
Tiple, Cuba [tab] [Link]
Tiple, Peru [tab] [Link]
Tiple, Santo Domingo [tab] [Link]

cxcv
 7 Global Constants

Tiple, Uruguay [tab] [Link]

Tres [notation] [Link].5lines
Tres, GCE tuning [tab] [Link]
Tres, ADF# tuning [tab] [Link]
Tres, GBE tuning [tab] [Link]
Ukulele [notation] [Link].5lines
Ukulele [tab] [Link]
Vihuela [notation] [Link].5lines
Vihuela [tab] [Link]
Zither [Link]
Keyboard [Link]
Accordion [Link]
Bandoneon [Link]
Celesta [Link]
Clavichord [Link]
Harmonium [Link]
Harpsichord [Link]
Keyboards [Link]
Tape Sampler Keyboard [Brass] [Link] [Link]
Tape Sampler Keyboard [Choir] [Link] [Link]
Tape Sampler Keyboard [Flute] [Link] [Link]
Tape Sampler Keyboard [Strings] [Link] sampler
Melodeon [Link]
Electric Organ [Link]
Organ [manuals] [Link]
Manual [solo organ manuals] [Link]
Ped. [Organ pedals] [Link]
Pedal [solo organ pedals] [Link]
Piano [Link]
Electric Piano [Link]
Electric Clavichord [Link]
Electric Stage Piano [Link]
Overdriven Electric Piano [Link]
Honky-tonk Piano [Link]-tonk
Synthesizer [Link]
Unnamed (2 lines) [Link].2lines

cxcvi
 7 Global Constants

Unnamed (3 lines) [Link].3lines

Unnamed (4 lines) [Link].4lines
Unnamed (bass staff) [Link]
No instrument (barlines shown) [Link]
No instrument (bar rests shown) [Link]
No instrument (hidden) [Link]
Solo [Link]
Unnamed (treble staff) [Link]
Almglocken [Link]
Antique Cymbals [Link]
Chimes [Link]
Chimes [no key] [Link]
Bell lyre [marching band] [Link]
Orchestral Bells [Link]
Tubular Bells [Link]
Cimbalom [Link]
Crotales [Link]
Steel Drums [Link]
Steel Drums [bass clef, treble transp.] [Link]
Gamelan Kengong [Link]
Gamelan Slentam [Link]
Glockenspiel [Link]
Alto Glockenspiel [Link]
Soprano Glockenspiel [Link]
Handbells [Link]
Harp [Link]
Lever Harp [Link]
Kalimba [Link]
Marimba [grand staff] [Link]
Marimba [treble staff] [Link]
Alto Metallophone [Link]
Bass Metallophone [Link]
Soprano Metallophone [Link]
Roto-toms [Link]-toms
Temple Blocks [Link]
Timpani [with key] [Link]

cxcvii
 7 Global Constants

Timpani [no key] [Link]

Vibraphone [Link]
Wood Blocks [5 lines] [Link]
Xylophone [Link]
Alto Xylophone [Link]
Bass Xylophone [Link]
Contra Bass Bar [Link]
Gyil [Link]
Soprano Xylophone [Link]
Xylorimba [Link]
Alto [Link]
Solo Alto [Link]
Altus [Link]
Baritone [Link]
Solo Baritone [Link]
Bass [Link]
Solo Bass [Link]
Bassus [Link]
Cantus [Link]
Choir [Link]
Contralto [Link]
Countertenor [Link]-tenor
Mean [Link]
Mezzo-soprano [Link]-soprano
Quintus [Link]
Secundus [Link]
Soprano [Link]
Solo Soprano [Link]
Tenor [Link]
Solo Tenor [Link]
Treble [Link]
Solo Treble [Link]
Voice [Link]
Voice [male] [Link]
Contrabass [Link]
Bass [Double] [Link]

cxcviii
 7 Global Constants

Double Bass [Link]-bass

Solo Contrabass [Link]
String Bass [Link]
Upright Bass [Link]
Hurdy-gurdy [Link]-gurdy
Sarangi [Link]
Strings [Link]
Strings [reduction] [Link]
Bass Viol [Link]
Tenor Viol [Link]
Treble Viol [Link]
Viola [Link]
Solo Viola [Link]
Violin 1 [Link].1
Violin 2 [Link].2
Violin I [Link].I
Violin II [Link]
Solo Violin [Link]
Violoncello [Link]
Solo Violoncello [Link]
Anvil [Link]
Cha-cha bell [1 line] [Link]-cha
Mambo bell [1 line] [Link]
Sleigh Bells [Link]
Brake Drum [1 line] [Link]-drum.1line
Cabasa [1 line] [Link]
Cabasa [2 lines] [Link].2lines
Castanets [Link]
Shaker, Caxixi [1 line] [Link].1line
Claves [1 line] [Link]
Shaker, Cocoa Bean Rattle [1 line] [Link] bean.1line
Finger Cymbals [1 line] [Link].1line
Percussion [1 line] [Link].1line
Percussion [2 lines] [Link].2lines
Berimbau [Link]
Percussion [3 lines] [Link].3lines

cxcix
 7 Global Constants

Percussion [4 lines] [Link].4lines

Percussion [5 lines] [Link].5lines
Agogos [2 lines] [Link]
Bass Drum [Link]
Bass Drum [5 lines] [Link].5lines
Marching Bass Drum [3 lines] [Link].3lines
Marching Bass Drum [5 lines] [Link].5lines
Itótele [Batá Drum] [Link]
Iyá [Batá Drum] [Link]
Okónkolo [Batá Drum] [Link]
Bongos [2 lines] [Link]
Bongo Bell [High] [Link]
Bongo Bell [Low] [Link]
Box [Link].3lines
Cajon [2 lines] [Link]
Congas [2 lines] [Link]
Congas [1 line] [Link].1line
Congas [3 lines] [Link].3lines
Congas [4 lines] [Link].4lines
Cuíca [3 lines] [Link].3lines
Cymbals [Link]
Marching Cymbals [5 lines] [Link].5lines
Djembe [3 lines] [Link].3lines
Drum Set (Rock) [Link]
Drum Set (Alternative) [Link]
Drum Set (Brushes) [Link]
Drum Set (Dance) [Link]
Drum Set (Disco) [Link]
Drum Set (Electronica) [Link]
Drum Set (Fusion) [Link]
Drum Set (Garage) [Link]
Drum Set (Hip-hop) [Link]-hop
Drum Set (Industrial) [Link]
Drum Set (Jazz) [Link]
Drum Set (Lo-Fi) [Link]-fi
Drum Set (Metal) [Link]

cc
 7 Global Constants

Drum Set (Motown) [Link]

Drum Set (New Age) [Link] age
Drum Set (Pop) [Link]
Drum Set (Reggae) [Link]
Drum Set (Stadium Rock) [Link]
Drum Set (Rods) [Link]
Drum Set (Drum Machine) [Link]-808
Dumbek [3 lines] [Link].3lines
Kidi [Ewe Drum] [Link]
Sogo [Ewe Drum] [Link]
Gankokwe (Bell) [Link]
Jam Blocks [2 lines] [Link]
Jawbone [1 line] [Link].1line
Pandeiro [2 lines] [Link]
Rain Stick (High) [1 line] [Link].1line
Rain Stick (Low) [1 line] [Link].1line
Egg Shaker (High) [1 line] [Link].1line
Egg Shaker (Low) [1 line] [Link].1line
Egg Shaker (Medium) [1 line] [Link].1line
Side Drum [Link]
Snare Drum [Link]
Marching Snare Drums [5 lines] [Link].5lines
Surdo [2 lines] [Link]
Tabla [Link]
Taiko Drum [Link]
Tenor Drum [Link]
Marching Tenor Drums [5 lines] [Link]
Quads [5 lines] [Link]
Tom-toms [5 lines] [Link]-toms
Tom-toms [4 lines] [Link]-toms.4lines
Udu [Link]
Shaker, Egg Shaker [1 line] [Link] shaker.1line
Finger Click [1 line] [Link]
Gamelan Gong Ageng (High) [1 line] [Link]
Gamelan Gong Ageng (Low) [1 line] [Link]
Gamelan Kempyang and Ketuk [2 lines] [Link]-ketuk

cci
 7 Global Constants

Gamelan Khendang Ageng [1 line] [Link]-ageng

Gamelan Khendang Ciblon [1 line] [Link]-ciblon
Large Gong [1 line] [Link].1line
Medium Gong [1 line] [Link].1line
Gourd [1 line] [Link]
Guira [1 line] [Link]
Guiro (High) [1 line] [Link]
Guiro (Medium) [1 line] [Link]
Handclap [1 line] [Link]
Shaker, Kayamba [1 line] [Link].1line
Maracas [Link]
Shaker, Gourd Maracas [1 line] [Link].1line
Maracas [High] [Link]
Maracas [Medium] [Link]
Mark tree [1 line] [Link]
Shaker, Nsak Rattle [1 line] [Link].1line
Finger Snaps [Link]
Hand Claps [Link]
Patsch [Link]
Stamp [Link]
Salsa bell [1 line] [Link]
Shaker [1 line] [Link]
Shaker, Shekere [1 line] [Link].1line
Tam-tam [Link]-tam
Tambourine [Link]
Timbales [2 lines] [Link].2lines
Timbales [5 lines] [Link].5lines
Triangle [Link]
Shaker, Wasembe Rattle (High) [1 line] [Link].1line
Shaker, Wasembe Rattle (Low) [1 line] [Link].1line
Shaker, Wasembe Rattle (Medium) [1 line] [Link].1line
Whip [Link]
Whistle [Link]
Wind Chimes [1 line] [Link]-chimes.1line
Wood Block [1 line] [Link].1line
Bagpipes [Link]

ccii
 7 Global Constants

Basset Horn [Link]-horn

Bassoon [Link]
Contrabassoon [Link]
Quart Bassoon [Link]
Quint Bassoon [Link]
Clarinet in A [Link].a
Clarinet in Ab [Link]
Alto Clarinet in Eb [Link]
Alto Clarinet in Eb [bass clef, treble transp.] [Link]
Bass Clarinet in Bb [Link]
Bass Clarinet in Bb [score sounds 8vb] [Link].8vb-score
Bass Clarinet in Bb [bass clef, treble transp.] [Link]
Clarinet in Bb [Link]
Clarinet in C [Link].c
Contra Alto Clarinet in Eb [Link]
Contra Alto Clarinet in Eb [score sounds 8vb] [Link].8vb-score
Contra Alto Clarinet in Eb [bass clef, treble [Link]
transp.]
Contrabass Clarinet in Bb [Link]
Contrabass Clarinet in Bb [score sounds 15mb] [Link].15mb-score
Contrabass Clarinet in Bb [bass clef, treble [Link]
transp.]
Clarinet in D [Link].d
Clarinet in Eb [Link]
Clarinet in G [Link].g
Cor Anglais [Link]
Didgeridoo [Link]
Duduk [Link]
English Horn [Link]
Flageolet [Link]
Flute [Link]
Alto Flute [Link]
Bansuri [Link]
Bass Flute [Link]
Eb Flute [Link]
G Flute [Link].g
Harmonica [Link]
Heckelphone [Link]

cciii
 7 Global Constants

Mey [Link]
Nai [Link]
Oboe [Link]
Baritone Oboe [Link]
Bass Oboe [Link]
Oboe d'Amore [Link]
Ocarina [Link]
Panpipes [Link]
Piccolo [Link]
Military Piccolo in Db [Link]
Alto Recorder [Link]
Bass Recorder [Link]
Great Bass Recorder [Link]
Contrabass Recorder [Link]
Descant Recorder [Link]
Sopranino Recorder [Link]
Soprano Recorder [Link]
Tenor Recorder [Link]
Treble Recorder [Link]
Alto Saxophone [Link]
Baritone Saxophone [Link]
Baritone Saxophone [score sounds 8vb] [Link].8vb-score
Baritone Saxophone [bass clef, treble transp.] [Link]
Bass Saxophone [Link]
Bass Saxophone [score sounds 15mb] [Link].15mb-score
Bass Saxophone [bass clef, treble transp.] [Link]
C Melody Saxophone [Link].c-melody
Contrabass (Tubax) Saxophone [Link]
Contrabass (Tubax) Saxophone [score sounds [Link].15mb-score
15mb]
Contrabass (Tubax) Sax [bass clef, treble [Link]
transp.]
F Mezzo Soprano Saxophone [Link]-soprano.f
Sopranino Saxophone [Link]
Piccolo Saxophone in Bb [Soprillo] [Link]
Soprano Saxophone [Link]
C Soprano Saxophone [Link].c
Subcontrabass (Tubax) Saxophone [Link]

cciv
 7 Global Constants

Subcontrabass (Tubax) Saxophone [score [Link].15mb-score

sounds 15mb]
Subcontrabass (Tubax) Sax [bass clef, treble [Link]
transp.]
Tenor Saxophone [Link]
Tenor Saxophone [score sounds 8vb] [Link].8vb-score
Tenor Saxophone [bass clef, treble transp.] [Link]
Woodwind [Link]
Shakuhachi [Link]
Tin Whistle [Link]

Beam Options
For the Beam variable of NoteRest objects.

NoBeam 1
StartBeam 2
ContinueBeam 3
SingleBeam 4

Bracket Types
For the AddBracket() method of BracketList objects, and the BracketType variable of Bracket
objects.

BracketFull 0
BracketBrace 1
BracketSub 2

Breaks
These constants are used by the SetBreakType() method of Score objects.

MiddleOfSystem 1
EndOfSystem 2
MiddleOfPage 3
EndOfPage 4
NotEndOfSystem 5
EndOfSystemOrPage 6
Default 7
SpecialPageBreak 8

These constants correspond to the menu entries in the Bars panel of the Properties window in the following
way:

ccv
 7 Global Constants

l MiddleOfSystem
Middle of system. The bar can only appear in the middle of a system, not at the end.
l EndOfSystem
No menu entry; created by Layout > Lock Format. The bar can only appear at the end of a mid-page
system,
not the middle of a system or the end of a page.
l MiddleOfPage
Middle of page. The bar can appear anywhere except at the end of a page.
l EndOfPage
Page break. The bar can only appear at the end of a page.
l NotEndOfSystem
No menu entry. The bar can appear anywhere except the end of a mid-page system.
l EndOfSystemOrPage
System break. The bar can only appear at the end of a mid-page system or the end of a page.
l Default
No break. The bar can appear anywhere.
Note that in older versions of ManuScript the constant MiddleOfSystem was called NoBreak and
the constant EndOfSystem was called SystemBreak. These older names were confusing, because
they implied a correlation with the similarly-named menu items in the Properties window that was not
accurate. The old names are still supported for old plug-ins, but should not be used for new plug-ins.
For consistency, the old constant PageBreak has also been renamed EndOfPage, even though this
did correlate correctly with the Properties window.

Accidentals
For the Accidental variable of Note objects.

DoubleSharp 2
Sharp 1
Natural 0
Flat –1
DoubleFlat –2
QuarterSharp 0.5
ThreeQuarterSharp 1.5
QuarterFlat –0.5
ThreeQuarterFlat –1.5

Note Style Names

For the NoteStyle variable of Note objects; these correspond to the noteheads available from the Notes
panel of the Properties window in the manuscript papers that are supplied with Sibelius.

NormalNoteStyle 0 BackSlashedNoteStyle 12
CrossNoteStyle 1 ArrowDownNoteStyle 13

ccvi
 7 Global Constants

DiamondNoteStyle 2 ArrowUpNoteStyle 14
BeatWithoutStemNoteStyle 3 InvertedTriangleNoteStyle 15
BeatNoteStyle 4 ShapedNote1NoteStyle 16
CrossOrDiamondNoteStyle 5 ShapedNote2NoteStyle 17
BlackAndWhiteDiamondNoteStyle 6 ShapedNote3NoteStyle 18
HeadlessNoteStyle 7 ShapedNote4StemUpNoteStyle 19
StemlessNoteStyle 8 ShapedNote4StemDownNoteStyle 23
SilentNoteStyle 9 ShapedNote5NoteStyle 20
CueNoteStyle 10 ShapedNote6NoteStyle 21
SlashedNoteStyle 11 ShapedNote7NoteStyle 22

MuteMode Constants
These are the possible values of [Link]:

Muted 0
HalfMuted 1
NotMuted 2

Articulations
Used with [Link] and [Link].

Custom3Artic 15
TriPauseArtic 14
PauseArtic 13
SquarePauseArtic 12
Custom2Artic 11
DownBowArtic 10
UpBowArtic 9
PlusArtic 8
HarmonicArtic 7
MarcatoArtic 6
AccentArtic 5
TenutoArtic 4
WedgeArtic 3
StaccatissimoArtic 2
StaccatoArtic 1
Custom1Artic 0

SyllableTypes for LyricItems

Used in LyricItem.

ccvii
 7 Global Constants

MiddleOfWord 0
EndOfWord 1

Accidental Styles
As used by [Link].

NormalAcc "0"
HiddenAcc "1"
CautionaryAcc "2"
BracketedAcc "3"

Time Signature Strings

These define the unicode characters used to draw common time and alla breve time signatures, so that you
can recognize these by comparison with [Link].

CommonTimeString

AllaBreveTimeString

Symbols
There are a lot of symbols in Sibelius. We’ve defined named constants for the indices of some of the most
frequently used symbols, which can be passed to [Link]. For other symbols, you can work out
the required index by "counting along" in the Create > Symbol dialog of Sibelius, or by using the method
[Link]. To help with the "counting along," we’ve defined a constant for the start of every
group of symbols in the Create > Symbol dialog, and these are also given below. Then for example you can
access the 8va symbol as OctaveSymbols + 2.

Common Symbol Indices

SegnoSymbol "1"
CodaSymbol "2"
RepeatBeatSymbol "5"
RepeatBarSymbol "6"
RepeatTwoBarsSymbol "7"
TrillSymbol "32"
BracketedTrillSymbol "33"
MordentSymbol "36"
InvertedMordentSymbol "37"
TurnSymbol "38"
InvertedTurnSymbol "39"
ReversedTurnSymbol "40"
TripleMordentSymbol "41"
InvertedTripleMordentSymbol "42"
PedalSymbol "48"

ccviii
 7 Global Constants

PedalPSymbol "49"
PedalUpSymbol "50"
LiftPedalSymbol "51"
HeelOneSymbol "52"
HeelTwoSymbol "53"
ToeOneSymbol "54"
ToeTwoSymbol "55"
CommaSymbol "247"
TickSymbol "248"
CaesuraSymbol "249"
ThickCaesuraSymbol "250"
Indices at the Start of Each Group of Symbols
RepeatSymbols "0"
GeneralSymbols "16"
OrnamentSymbols "32"
KeyboardSymbols "48"
ChromaticPercussionSymbols "64"
DrumPercussionSymbols "80"
MetallicPercussionSymbols "96"
OtherPercussionSymbols "112"
BeaterPercussionSymbols "128"
PercussionTechniqueSymbols "160"
GuitarSymbols "176"
ArticulationSymbols "208"
AccidentalSymbols "256"
NoteSymbols "288"
NoteheadSymbols "320"
RestSymbols "368"
ConductorSymbols "400"
ClefSymbols "416"
OctaveSymbols "448"
BreakSymbols "464"
TechniqueSymbols "480"
AccordionSymbols "496"
HandbellSymbols "528"
MiscellaneousSymbols "544"

ccix
 7 Global Constants

Symbol Size Constants

NormalSize "0"
CueSize "1"
GraceNoteSize "2"
CueGraceNoteSize "3"

Special Page Break Types

NoPageBreak "0"
MusicRestartsAfterXPages "1"
MusicRestartsOnNextLeftPage "2"
MusicRestartsOnNextRightPage "3"

Interval Types
IntervalDiatonic "–1"
Interval5xDiminished "0"
Interval4xDiminished "1"
Interval3xDiminished "2"
Interval2xDiminished "3"
IntervalDiminished "4"
IntervalMinor "4"
IntervalMajor "5"
IntervalPerfect "5"
IntervalAugmented "6"
Interval2xAugmented "7"
Interval3xAugmented "8"
Interval4xAugmented "9"
Interval5xAugmented "10"

InMultirest Values
NoMultirest "0"
StartsMultirest "1"
EndsMultirest "2"
MidMultirest "3"

Page Number Visibility Values

PageNumberShowAll "0"
PageNumberHideFirst "1"
PageNumberHideAll "2"

ccx
 7 Global Constants

Page Number Format Values

PageNumberFormatNormal "0"
PageNumberFormatRomanUpper "1"
PageNumberFormatRomanLower "2"
PageNumberFormatLetterLower "3"

Special Barlines
SpecialBarlineStartRepeat "0"
SpecialBarlineEndRepeat "1"
SpecialBarlineDashed "2"
SpecialBarlineDouble "3"
SpecialBarlineFinal "4"
SpecialBarlineInvisible "5"
SpecialBarlineBetweenStaves "6"
SpecialBarlineNormal "7"
SpecialBarlineTick "8"
SpecialBarlineShort "9"
SpecialBarlineDotted "10"
SpecialBarlineTriple "11"
SpecialBarlineThick "12"

Bar Rest Type Values

WholeBarRest "0"
BreveBarRest "1"
OneBarRepeat "2"
TwoBarRepeat "3"
FourBarRepeat "4"

GuitarScaleDiagram Type Values

ScaleTypeMajor "0"
ScaleTypeMinor "1"
ScaleTypeHarmonicMinor "2"
ScaleTypeMelodicMinor "3"
ScaleTypeDorian "4"
ScaleTypePhrygian "5"
ScaleTypeLydian "6"
ScaleTypeMixolydian "7"

ccxi
 7 Global Constants

ScaleTypeLocrian "8"
ScaleTypeWholeTone "9"
ScalrTypeDiminishedHalfWhole "10"
ScaleTypeDiminishedWholeHalf "11"
ScaleTypeAlteredDominant "12"
ScaleTypeLocrianSharp2 "13"
ScaleTypeLydianFlat7 "14"
ScaleTypeMajorBebop "15"
ScaleTypeDominantBebop "16"
ScaleTypeLydianSharp5 "17"
ScaleTypePhrygianDominant "18"
ScaleTypeAugmentedArpeggio "19"
ScaleTypeMajor7thArpeggio "20"
ScaleType7thArpeggio "21"
ScaleTypeMin7Flat5Arpeggio "22"
ScaleTypeDiminished7thArpeggio "23"
ScaleTypeMajorPentatonic "24"
ScaleTypeMinorPentatonic "25"
ScaleTypeOther "26"

FeatheredBeamType Values
For the FeatheredBeamType variable of NoteRest objects.

FeatheredBeamNone "0"
FeatheredBeamAccel "1"
FeatheredBeamRit "2"

Units Values
For the DocumentSetup object.

DocumentSetupUnitsmm "0"
DocumentSetupUnitsInches "1"
DocumentSetupUnitsPoints "2"

Orientation Values
For the Orientation variable of DocumentSetup objects.

OrientationPortrait "0"
OrientationLandscape "1"

ccxii
 7 Global Constants

PageSize Values
For the PageSize variable of DocumentSetup objects.

PageSizeLetter "0"
PageSizeTabloid "1"
PageSizeA5 "2"
PageSizeB5 "3"
PageSizeA4 "4"
PageSizeB4 "5"
PageSizeA3 "6"
PageSizeUSBand "7"
PageSizeStatement "8"
PageSizeHymn "9"
PageSizeOctavo "10"
PageSizeExecutive "11"
PageSizeQuarto "12"
PageSizeConcert "13"
PageSizeFolio "14"
PageSizeLegal "15"
PageSize9_5x12_5 "16"
PageSize10x13 "17"
PageSizeCustom "18"

MarginType Values
For the MarginType variable of DocumentSetup objects.

PageMarginsSame "0"
PageMarginsMirrored "1"
PageMarginsDifferent "2"

StaffScaleFactor Values
For the StaffScaleFactor variable of Staff objects.

NormalSize "0"
MediumSize "1"
SmallSize "2"
ExtraSmallSize "3"

Tuplets
These define the constants that can be passed as a style parameter to [Link]() and
[Link]().

ccxiii
 7 Global Constants

TupletNoNumber "0"
TupletLeft "1"
TupletLeftRight "2"
TupletLeftRightNote "3"

These define the constants that can be passed as a bracket parameter:

TupletBracketOff "0"
TupletBracketOn "1"
TupletBracketAuto "2"

SingleTremolos
For the SingleTremolos variable of NoteRest objects, the constants are numbers in the range 0 to 7,
representing the number of tremolo beams on the stem of the note or chord. For a "z on stem" (for buzz
rolls), use the value –1 or the constant ZOnStem.

DoubleTremolo Values
For the double tremolo style variables of EngravingRules objects.

DoubleTremolosTouchingStems "0"
DoubleTremolosBetweenStems "1"
DoubleTremolosOuterTremoloTouchingStems "2"

BarNumberFrequencyCategory Values
For the BarNumberFrequencyCategory variable of EngravingRules objects.

EverySystem "0"
NoBarNumbers "1"
EveryNthBar "2"

Instrument Name Values

For the instrument name variables of EngravingRules objects.

InstrumentNamesFull "0"
InstrumentNamesShort "1"
InstrumentNamesNone "2"

Types of Objects in a Bar

The Type field for objects in a bar can return one of the following values:
l Clef, SpecialBarline, TimeSignature, KeySignature
l Line, ArpeggioLine, Bend, CrescendoLine, DiminuendoLine, GlissandoLine,
OctavaLine, PedalLine, RepeatTimeLine, Slur, Trill, Box, BeamLine, Tuplet,
RitardLine, HighLight

ccxiv
 7 Global Constants

l LyricItem, Text, SystemTextItem, GuitarFrame, GuitarScaleDiagram, RehearsalMark,

InstrumentChange
l BarRest, NoteRest, Graphic, Comment, Bracket, BarNumber
l SymbolItem, SystemSymbolItem

Interpreter Options
IncludeScoreSubsetsInDynamicPartCollection When enabled, score subsets are included in the
DynamicPartCollection obtained using Score’s
“DynamicParts” variable. As of Sibelius 2024.3, score
subsets are no longer included by default.
TreatSingleCharacterAsString When enabled, literals such as “1” are considered as
strings, not characters. That has several consequences:

l When consisting of a single digit, these have the

value of the digit, not the value of the ASCII
character
l In the case of non-digit values, like “a”, they are
converted to 0, as documented elsewhere. (Not as
97 as was the case before. If the ASCII value is
required, one has to use the “Asc” method
explicitly.)
l Result of comparison like “ManuScript” = “M” is now
be false.
SupportHalfSemitonePitchValues When enabled, floating-point values are accepted as
“Pitch” so that scripts can add and manipulate quarter-
tone values. Pitch is still specified and returned as a
semitone, but 0.5 semitone is a quartertone. The same goes
for Accidentals.

The following methods accept floating-point pitches:

l [Link]
l [Link]
l [Link]
The following methods return pitches or accidentals in
floating-point values:

l [Link]
l [Link]
l [Link]
l [Link]

ccxv
Index
C
compatibility xiv

217