Plugins API design for MuseScore 3

My main concern about 3.0 plugins is that curently it isn't possible to create a plugin that works in 2.x and 3.x, i.e. there is nothing in a plugin to determin whether it is using one or the other version.
Between 1.x and 2.x this was possible in a way, as you could maintain a .js and a .qml version in the same package and MuseSore would pick the right one automagically, but between 2.x and 3.x it would both be .qml, so such a branching would need to be done inside the plugin code. The check for MuseScore version would only come after the #import statements, but those already depend on what MuseScore version we're on, nice catch-22 :-(
So how would we make it possible to have 1.x, 2.x and 3.x plugins (for the same job, obviously) to be maintained in a single package, a single GutHub branch?
Having said that, I don't have any strong opinion on any of your points, but would rather stay as compatible as we possibly can, to ease the porting as much as possible

Have you had the chance to review submissions related to plugins in the issue tracker?
( https://musescore.org/en/project/issues/musescore?text=&tags=&status=Al… )

I just realize that I probably should have chosen "Plugins" as my issue type, as my plugin API request could be easily missed. #281536: Make staff properties "change instrument" and "change channel" available in plugin API.

Thanks,
Sam

Hi,
I have made a couple of plugins for old version of Musescore. I don't mind if they don't work in 3.0 or later versions. The only wish from my side is the plugin API to have all (or almost all) functions a user has in the UI. So that it is possible to fully automate some processes.
Use cases for my plugins were:
* Chord detection. I don't want to enter chord names manually, especially if one of the staves, the accompaniment, has chords written in sheet music/note notation. So I did a plugin. The main issue in the old API found while writing the plugin was:
- not possible to know the key signature (stave key), had to workaround it by blind guessing stave key based on notes used in N last measures and the Circle of fifth/ fourth.
* Auto accompaniment based on entered chords. I want to prototype my song and for writing melody I want to enter some simple accompaniment automatically. The plugin never saw a release, but I still have this idea. Would be great to write melody while I hear the harmony.

To sum it up and quoting myself: "plugin API to have all (or almost all) functions a user has in the UI". The rest is not that important. Of course I don't want the API to be ugly android-like, but what I see in the topic start, get/set functions are fine for me.

P.S. I am a professional programmer, and an amateur musician/ guitar player.

Properties of elements

Your analysis is spot on. I don't have a good solution. As a plugin developer, I don't like get/set... As a C++ developer I understand very well that it's a lot easier to implement...

Note that get/set is currently working for "pure MuseScore properties" only and so for example it's not possible to get the list of notes of a chord or the list of grace note chords of a given chord. If we do provide chord.notes() it doesn't really make sense to have chord.notes()[0].get("color") right ? So what do we do ? chord.getList("notes")[0].get("color")... it's even more ugly, and the plugin developer inside me doesn't like it...

newElement

I don't think it's a great idea to keep this function as it... One of the main challenge when designing the plugin API is to make sure that we don't leak memory and that a plugin cannot crash MuseScore. By providing newElement() I don't see how we can do that... Who is the owner of the new Element, JS or C++ ? Who will delete it ? I'm afraid a better API will need to be specialized. Something like cursor.addText(string, style), chord.addNote(pitch), segment.addChord(pitch, pitch1, pitch3) etc... the actual Element would be C++ owned and would be inserted in the score tree. If needed, these functions could send back and ElementW owned by JS and acting as a proxy to modify the properties of the element.

More features ?

Right now, it's only possible to run a plugin on a click of a button. It could be convenient to have a way to run a plugin after each layout, or after any command or a given command is run... For example, the color notes plugin is great, but you need to run it every time you add a note or change a pitch or the color is not updated...

Please do not get rid of enumerations in favor of strings. Enumerations are discoverable - I can look up the enumeration definition and know what values I can expect. If you return a string, the I have no decent way to find out what I can expect.

Strings instead of enumerations may be "more javascript like." That doesn't make it a good idea.

I don't have a strong opinion on the mentioned items one way or the other, but please, please, please, have the API well documented such that developers don't have to go digging in the different libraries or rely on trial and error to get something working.

Back in 2012, when Werner presented the QML framework he wrote: "The most important point is that the needed bindings to MuseScore internals are much easier. It is possible to expose the original class hierarchy of MuseScore to the scripting engine." And indeed, the plugin API in MuseScore v2 seemed to mostly expose C++ methods and types to the plugin engine. This means, that "simple" things were often not easy to do, because MuseScore's core did not have an exposable method for them. One example would be creating a chord, containing several notes.
Solving the "find the selection" problem has been discussed several times but never lead to an agreement, because different solutions fitted different needs, and finding a universal easy-to-use solution to the problem turned out to be quite challenging. Still, I think I'd like the plugin API to be more functionality-oriented (e.g. by extending the Cursor class) and I like lasconic's ideas to add methods like addText, addNote and addChord.

1) Properties
I am strongly against textual strings used as identifiers: they are prone to typos ("text"? "Text"? even "test"?...) particularly in a multi-native-lingual environment as MuseScore users are and no compiler / interpreter / lint can catch them. So, please abstain from things like "myText.get("text")". If you really, really, really have to do something like that, please, please, please use somethign along the line of "myText.get(MYCUTEENUMERATION.Text)".

The fact that they are (or might be taken as) more "JavaScript oriented" is totally irrelevant to me.

2) Properties vs Function
True, I am an old C/C++ addict (and not much fond of latest C++ "improvements" either), but I never understood the need for the distinction between properties and functions in the first place, so I do not see any need for extending the use of properties in the plug-in API; actually I would prefer to get rid of them entirely and using only functions, which are clearer and simpler, but I understand the importance of not changing too much of the old API.

3) Element types
The same confutation of textual string identifiers as in point 1) applies here too; in addition, as
Joseph Eoff notes, enumerations are discoverable, strings are not.

4) Expansions: to my perspective, by far the most useful expansion quoted is the Styles API. The other would be nice to have but would mostly make easier something which is already possible.

Properties V Functions:
As an experienced Java programmer, I much prefer the object-oriented style of using get() and set().

Element Types:
It is much better to use:
var text = newElement(Element.STAFF_TEXT);
as this avoids pitfalls due to spelling mistakes when passing strings.
Perhaps in future there will be a MuseScore IDE that can immediately (and generically) indicate an error when the enumeration syntax is used, but cannot generically do a spelling check on the valid values for a parameter. The IDE could suggest valid values after the programmer has typed in "Element.", just like Eclipse or IntelliJ.

Possible API Expansions:
Better features to read/write files.
Better windowing and layout features. I tried to create a dialog box a couple of years back & it looked dire.
Access to the MIDI events received by MuseScore e.g. when you have a MIDI keyboard plugged in.

In general it is easier to write programs in a strongly-typed language, as the compiler does lots of checks before the code is run.
Weakly typed languages take so much longer to debug, as many errors are only manifested at run time.

There are a few comments above about JavaScript. JavaScript is easily one of the worst languages invented, so I would suggest avoiding anything that works like JavaScript. The earlier versions of Java had a very clean syntax, although modern Java is now getting more complex with the addition of Lambda functions.

I am a music theorist/composer by profession, although now retired. I have limited experience programming tools for algorithmic composition (in Lisp, mainly). I couldn't realistically hope to work productively with the C++ source code of MuseScore itself. But I've been able to teach myself enough QML/Javascript to create a handful of plugins for MuseScore 2. I'd like to update them for v3, as well as developing new tools.

To (mostly) echo what others have said, my priorities for the plugin API are:

• Straightforward programmatic access to more of the actions that can performed from the UI in normal use, particularly regarding creation and manipulation of rhythmic/time-based features such as ties, tuplets and time-signatures.

• Better documentation of objects and methods, possibly using a "wiki" model to which we could all contribute. Ideally this should be presented in a way that doesn't require knowledge of the source code itself.

• Access to score information that seems out-of-reach to v2 plugins, such as Instrument names and staff assignments, octave transpositions (unless I've missed it, there's no way to write a note at a particular octave in a transposed score/part), and so on.

Bonjour,

As I created a plugin, I received an email which proposes me to participate to this discussion.
I created a plugin for getting key numbers for a diatonic accordion tablature by modifying an existing plugin for concertinas, I understood it enough to modify it for my diatonic accordion.
When MuseScore 2 was released, lasconic (I thank you once again lasconic) modified the plugin for being compatible with MS 2 : I am still using it very much.
Today I am anxious (!!): what is happening for "my" diatonic accordion plugin when I use MS 3 ?????

Sorry, even I developed some software (50 - 20 years ago !) I am unable to participate.

Pierre

I forward @dmitrio95's message:
"From those plugins that are shipped with MuseScore at least the following work:

• ABC import (worked in 3.0 as well)
• Color notes
• Create score
• Note names
• Panel
• Random
• Random2
• Walk (this one is not indented to produce any user-visible results).

Jojo also ported and checked some plugins to 3.0 which are listed in the common plugins page:
https://musescore.org/en/plugins

Concerning Chord Identifier, it can be ported to 3.0 but as it is not shipped with MuseScore its publicly available versions will not work with MuseScore 3.0.2 right away. I could make a patch to that plugin though and send it to the plugin's author as I tested MuseScore with the altered version of this plugin.

I should also note that some plugins may work not fully as some parts of API are missing but a large part of them should be able to be ported to the available API."

It would be great if the plugin framework would allow me to set the playback cursor - that shaded bar that moves along the score, showing what notes are being played.
Would this also set the position of the page, so that the playback cursor is always visible?

Although it seems this thread has been hijacked a little I'll try to get back to the original topic of the plugin API in Musescore 3:

There are a few things we need for our Musescore plugins (where "element" is a cursor.element), some of which haven't made the jump yet:

element.tick (it's there, no brainer)
element.pagePos <--- missing (this is vital - but can/should be read only)
element.bbox <-- seems to be missing in 3.0. we're mostly interested in the width/height here
(it'd be really great if the units used in bbox and pagePos were interchangeable, I still don't know how they relate to one another in Musescore 2 - we're just ignoring bbox .x and .y)

element.(ghost)notes:
element.tpc <-- I still don't really get why there are three of these. the API could make the use cases clearer
element.ppitch <--- missing (!) we need to know the actual (sounded) pitch, not element.pitch which is the staff position
(and all the generic element properties above)

element.tieBack (but only so we can ignore that element)

It'd also be (emphatically!) great if the elements had a proper .toString() conversion so we could console.log them. Dancing around with console.log(Object.keys(element)) or for loops and checks for undefined etc make the barrier of entry pretty high for plugin development. JSON.stringify(element) also crashes every time- it'd be a dream if this "just worked".