Manuscript

Jonathan Finn

ManuScript is a simple, music-based programming language developed to write plug-ins for the Sibelius music processor.

It is based on Simkin, an embedded scripting language developed by Simon Whiteside (www.larts.co.uk/simkin.html), and has been extended by him and Graham Westlake. (Simkin is a spooky pet name for Simon sometimes found in Victorian novels.)

Rationale

In adding a plug-in language to Sibelius we were trying to address several different issues:

Music notation is complex and infinitely extensible, so some users will sometimes want to add to a music notation program to make it cope with these new extensions.

It is useful to allow frequently repeated operations (e.g. 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:

The language had to be simple, as we want normal users (not just seasoned programmers) to be able to use it.

We wanted plug-ins to be usable on any computer, as the use of PC?s, Macs and other platforms is widespread in the music world.

We wanted the tools to program in the language to be supplied with Sibelius.

We wanted musical concepts (pitch, notes, bars) to be easily expressed in the language.

We wanted programs to be able to talk to Sibelius easily (to insert and retrieve information from scores).

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 which is interpreted so it can run on different platforms; is 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) which are instantly comprehensible.

Do we have to use ManuScript?

No: if you don?t want to write in ManuScript you can write a plug-in in any other language, provided you supply as a dynamically linked library (dll) in Sibelius?s Plugins folder. This is useful for writing complex plug-ins, which may need features not in ManuScript: for instance, the PhotoScore scanning plug-in is written in C. However, people who aren?t professional programmers will probably want to use ManuScript.

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 Sun 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. We would welcome any useful plug-ins you write (email them to help@sibelius.com and we may put them on our website).

Although only a subset of the notations Sibelius supports are available from ManuScript, we will extend it as time goes on with the features people need for the type of plug-ins they need to write. For instance, Sibelius itself has many more ways to insert notes than ManuScript currently provides; for instance, ManuScript does not allow you to insert tuplets or notes in subsidiary voices. This is mostly to sidestep delicate issues (What if you insert a tuplet that would cross a barline? How do you specify the position of a note in a tuplet?) that we may tackle when it becomes clearer what types of plug-in people actually need. Many plug-ins won?t need to touch the notes in a score at all. Your comments and any ideas for plug-ins that could be made possible by adding new features to ManuScript will be welcome.

A simple plug-in

Let?s start a simple plug-in. You are assumed to have some basic experience of programming (e.g. in BASIC or C), so you?re already familiar with ideas like variables, loops and so on.

Start Sibelius. In the Plug-ins menu, click on Edit plug-ins?, then click New. You are asked to type the internal name of your plug-in and the name that should appear on the menu. These are often different because the plug-in?s internal name isn?t allowed spaces or punctuation; in fact it can only consist of letters and digits (as long as it doesn?t start with a digit). The name that appears on the menu can be anything (as long as it doesn?t contain single or double quotes).

Type Test as the internal name and Test plug-in as the menu name, then click OK. You?ll see Test added to the list in the Edit plug-ins dialog. Click Close. If you look in the Plug-ins menu again you?ll see Test plug-in at the bottom. Click on Test plug-in and the plug-in will run. What does it do? It just pops up a dialog which says ?Test? (whenever you start a new plug-in, Sibelius fills in a 1-line program to do this). Click OK on the dialog and the plug-in stops.

Let?s look at what?s in the plug-in so far. Click Edit plug-ins again, then in the dialog box click on Test and click Edit (alternatively you can just double-click on Test to edit it). You?ll see a dialog box showing the 3 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 dialog boxes you design for your plug-in.

Data: variables whose value is remembered between running the plug-in. These are quite like global

...