=====================================================
MuseScore Scripting Interface
=====================================================
Full documentation : http://musescore.org/en/node/4497
MuseScore supports plugin extensions in ECMAScript code (ECMA-262 aka
"Java Script").
A plugin extension is a file with the file extension ".js".
All extensions in the plugins directory are registered by MuseScore on
startup.
The linux plugin directory is usually located at
$install-path$/museScore-0.9/plugins.
On Windows you can find the plugins at ""install-path"\MuseScore 0.9\plugins".
A MuseScore plugin script has access to the whole Qt Library, so it is possible
to create complete guis.
=====================================================
Compatibility
=====================================================
The script interface is defined by two numbers, the majorVersion and the
minorVersion. A script written for a different majorVersion than the current MuseScore
script version may not run at all. Higher minor versions are supposed to be
backward compatible.
The majorVersion will be increased if the script interface changes in an incompatible
way. The minorVersion will be increased if the interface is only extended.
=====================================================
Debugging
=====================================================
A script debugger can be enabled in Menu "Help".
=====================================================
Overall structure of a MuseScore scripting
plugin.
=====================================================
Example of a "no operation" plugin:
----------------begin code-----------------------
function init() {}
function run() {}
function close() {}
var mscorePlugin = {
majorVersion: 1,
minorVersion: 1,
menu: 'Plugins.test',
init: init,
run: run,
onClose: close
};
----------------end code-----------------------
The global object "mscorePlugin" defines the environment of the plugin.
The variable "menu" creates a menu entry in MuseScore which triggers
execution of the plugin. The test plugin above creates an entry "test"
in the menu "Plugins". The syntax "entry:test" puts the new menu entry
"test" before the existing entry "entry". Not existing submenus are
automatically created. Dots are used as separators and must escaped with
"\" if they are part of a string.
"init" defines a function, which is called on MuseScore startup, when
the plugins are registered. The "run" function is executed, when the user
activates the "test" menu entry. The "onClose" is executed when MuseScore quits.
The majorVersion and minorVersion properties are optional. If present, MuseScore
checks against the current used interface version and warns of any
incompatibility.
=====================================================
Bindings to internal MuseScore data
=====================================================
Note: (ro) stands for read-only.
Objects
=====================================
MuseScore
this is the main application window
Functions:
QMenu* fileMenu() returns the file menu entry
registerPlugin(QAction*) Registers the current plugin with
QAction. Has to be called in the
init() function of a plugin if no
"menu" is defined.
Score
represents a complete score
A new score can be created with:
var a = new Score();
The new score is appended to mscores list of scores.
Properties:
name string file name
title string title text on score
subtitle string subtitle text on score
composer string composer text on score
poet string poet text on score
staves integer number of staves (ro)
duration integer total score duration in seconds (ro)
pages integer number of pages (ro)
measures integer number of actual measures (ro)
parts integer number of parts (ro)
hasLyrics bool true if a lyric element is found in the core (ro)
hasHarmonies bool true if a valid chordname is found (ro)
keysig integer key signature at the beginning (ro)
-7 to 7 or undefined for custom signature
pageFormat PageFormat the page format associated to this score
Functions:
bool save(string path, string type)
Write score into file 'path'. "type" is the file extension and
determines the type of file:
"mscz", "mscx", "xml", "mxl", "mid", "pdf",
"ps", "png", "svg", "ly", "wav", "flac", "ogg"
Note all types may be available.
bool save(string path, string type, string soundfontPath)
For soundfile output ("wav", "flac", "ogg") the soundfont to be used can
be specified as an additional parameter.
bool save(string path, "png", boolean screenshot, boolean transparent, double dpi,
boolean grayscale)
Saving into a PNG file can have additional parameters
setExpandRepeat(bool)
appendPart(string partname)
Append a new part to the score.
"partname" refers to an instrument name in the file instruments.xml.
The part will be initialized from the named instrument in this file.
If "partname" is empty, a default part will be appended.
appendMeasure(integer n) append "n" measure to score
startUndo() start undoable operations
endUndo() end undoable operations
Part part(int i) part object at index i
Cursor
create: var a = new Cursor(Score score);
var a = new Cursor(Score score, bool expandRepeat);
Properties:
staff integer
voice integer
pageNumber integer (ro)
Fuctions:
rewind() position cursor to staff/voice
goToSelectionStart() position to start of selection, voice will be 0
goToSelectionEnd() position to end of selection, voice will be 0
next() goto next chord/rest
nextMeasure() goto first chord/rest in next measure
isChord() return true if cursor points to a chord
chord() return chord at current position
isRest() return true if cursor points to a rest
rest() return rest at current position
measure() return measure at current position
putStaffText(Text) add staff text at cursor position
eos() return true if at end of score
add(Chord)
add(Rest)
measure() return the current measure
next() go to next chord/rest
nextMeasure() go to first chord/rest of next measure
time() double current score time in ms
tick() integer current score tick
pos() QPointF position
Chord
create:
var a = new Chord()
var a = new Chord(Score)
Properties:
tickLen integer
notes integer (ro) number of notes in chord
type integer (ro) Note type
0 - NORMAL
1 - ACCIACCATURA
2 - APPOGGIATURA
3 - GRACE4
4 - GRACE16
5 - GRACE32
Functions:
topNote()
note(integer n) return note at index n; notes are sorted to pitch
addNote(Note)
removeNote(integer n) remove note at index n
addHarmony(Harmony)
Rest
create:
var a = new Rest()
var a = new Rest(Score)
Properties:
tickLen integer
Functions:
addHarmony(Harmony)
Note
create:
var a = new Note()
var a = new Note(Score)
Properties:
pitch integer midi pitch value of note
name string name of note tpc value (read only)
color QColor notehead color
tuning double note tuning
tpc integer tonal pitch class
visible boolean
tied enum 0 no tie, 1 forward, 2 backward, 3 forw.+backw.
userAccidental integer
Text
create:
var a = new Text(score);
Properties:
text string the displayed text
defaultFont QFont
color QColor text foreground color
Harmony
create:
var a = new Harmony();
Properties:
id integer chord id
root integer tonal pitch class of root
base integer tonal pitch class of base
Style
HarmonyInfo
Measure
Properties:
lineBreak bool break the system after this measure
pageNumber integer number of the page where the measure is drawn (ro)
Functions:
QRectF boundingRect() bounding box (ro)
QPointF pos() position (ro)
Part
Properties:
longName string long name of the part (ro)
shortName string short name of the part (ro)
midiProgram integer midi program of the part (ro)
midiChannel integer midi channel of the part (ro)
staves integer number of staves in the part (ro)
PageFormat
Properties:
landscape bool true if the score is in landscape orientation (ro)
twosided bool true if the score is two sided (ro)
width double page width in mm (ro)
height double page height in mm (ro)
Global Variables
=====================================
mscore MuseScore This is the main application window
pluginPath string path of current active plugin
This path can be used find additional data associated with this
plugin.
curScore Score current active Score
curCursor Cursor
division integer number of midi ticks for 1/4 note
mscoreVersion integer complete version number: MMmmuu (major/minor/update)
mscoreMajorVersion integer
mscoreMinorVersion integer
mscoreUpdateVersion integer
majorVersion integer interface major version of the currently running interpreter
minorVersion integer interface minor version number
=====================================================
Translation
=====================================================
See: http://doc.trolltech.com/4.6/scripting.html#internationalization
To translate a plugin, you need to use :
qsTr() for all your "quoted text"
For the menu item use : QT_TR_NOOP("Plugins.MyMenuItem")
Then create a directory "translations" in the plugin directory.
You need to put locale_XX.qm files in it.
How to obtain a qm file for your plugin?
Run :(replace XX by the targetted language)
lupdate <your plugins file> translations/locale_XX.ts
Use Qt Linguist or an xml editor to put the translation in local_XX.ts. Once done run :
lrelease locale_XX.ts
You will obtain a qm file. Now run MuseScore in your language and your plugin should be translated!
=====================================================
Example "run" scripts
=====================================================
1. Create a "hello world" message box
var mb = new QMessageBox();
mb.setWindowTitle("MuseScore: Hello");
mb.text = "Hello World!";
mb.exec();
if no "menu" is defined in the mscorePlugin structure, the plugin must
be registered in the init() function:
function init()
{
// create action
var action = new QAction("mops", mscore);
// put action into menu
var menu = mscore.fileMenu();
var actionList = menu.actions();
menu.insertAction(actionList[5], action);
// register plugin
mscore.registerPlugin(action);
}
2. Create a new Score "Test-Score"
var score = new Score();
score.name = "Test-Score";
score.appendPart("Piano"); // create two staff piano part
score.appendMeasures(5); // append five empty measures
3. Put note name above each chord
var cursor = new Cursor(curScore);
cursor.staff = 0;
cursor.voice = 0;
cursor.rewind();
while (!cursor.eos()) {
if (cursor.isChord()) {
var text = new Text(curScore);
text.text = cursor.chord().topNote().name();
cursor.putStaffText(text);
}
cursor.next();
}
4. Remove middle note in all three note chords
var cursor = new Cursor(curScore);
cursor.staff = 0;
cursor.voice = 0;
cursor.rewind();
while (!cursor.eos()) {
if (cursor.isChord()) {
var chord = cursor.chord();
if (chord.notes() == 3) {
chord.removeNote(1);
}
}
cursor.next();
}
=====================================================
Useful functions
=====================================================
1. Apply the given function "func" to all notes in selection on all voices
function applyToNotesInSelection(func)
{
var cursor = new Cursor(curScore);
var selectionEnd = new Cursor(curScore);
cursor.goToSelectionStart();
selectionEnd.goToSelectionEnd();
var startStaff = cursor.staff;
var endStaff = selectionEnd.staff;
for (var staff = startStaff; staff < endStaff; ++staff) {
cursor.goToSelectionStart();
for (var v = 0; v < 4; v++) {
cursor.goToSelectionStart(); // set voice to 0
cursor.voice = v; //voice has to be set after goTo
cursor.staff = staff;
while (cursor.tick() < selectionEnd.tick()) {
if (cursor.isChord()) {
var chord = cursor.chord();
var n = chord.notes;
for (var i = 0; i < n; i++) {
var note = chord.note(i);
func(note);
}
}
cursor.next();
}
}
}
}
distrib
>
Mageia
>
5
>
x86_64
>
media
>
core-release
>
by-pkgid
>
8f1e7733e3578c88b69de9ce07b14672
>
files
>
17
