Plugins for 3.x

Updated 3 weeks ago

This is a guide for the MuseScore 3.0 plugin implementation.

Documentation

Full featured documentation is available in Doxygen format.

Converting MuseScore 2 plugins

This section describes changes between MuseScore 2.X and MuseScore 3 plugins API.

Almost all of the needed changes can also be made automatically with this converter script (Python is needed to run it).

Import statement

Replace import MuseScore 1.0 with import MuseScore 3.0 to start porting a 2.X plugin.
This is needed to distinguish between plugins for different MuseScore versions.

Properties assignments

Most of properties should remain the same as in MuseScore 2.X. Most notable differences:

  • TimeSig doesn't have setSig() function anymore.
    Replace ts.setSig(numerator, denominator) with ts.timesig = fraction(numerator, denominator).

  • No pos property available
    Autoplacement engine makes it not necessary to adjust elements position in most cases.
    If this is still needed, use offset or offsetX and offsetY properties to adjust position offset:
    element.offset = Qt.point(x, y);
    or
    element.offsetX = x;
    element.offsetY = y;
    where x, y are arbitrary numbers (in spatium units).

Enumerations

Most of enumerations exposed to QML plugins remain the same but some were renamed compared to MuseScore 2.X API. The renamed enumerations include:

  • Placement — element placement above or below staff
    Element.ABOVE, Element.BELOWPlacement.ABOVE, Placement.BELOW

  • Direction — vertical direction
    MScore.UP, MScore.DOWN, MScore.AUTODirection.UP, Direction.DOWN, Direction.AUTO

  • DirectionH — horizontal direction
    MScore.LEFT, MScore.RIGHT, MScore.AUTODirectionH.LEFT, DirectionH.RIGHT, DirectionH.AUTO

  • OrnamentStyle
    MScore.DEFAULT, MScore.BAROQUEOrnamentStyle.DEFAULT, OrnamentStyle.BAROQUE

  • GlissandoStyle
    MScore.CHROMATIC, MScore.WHITE_KEYS, MScore.BLACK_KEYS, MScore.DIATONIC

    GlissandoStyle.CHROMATIC etc.

  • TextStyleTypeTid

  • NoteHeadType
    HEAD_AUTO, HEAD_WHOLE, HEAD_HALF, HEAD_QUARTER, HEAD_BREVIS, HEAD_TYPES are now in NoteHeadType enumeration.

  • NoteHeadGroup
    Other HEAD_* values are in NoteHeadGroup enumeration.

  • NoteValueType
    Note.OFFSET_VAL, Note.USER_VALNoteValueType.OFFSET_VAL, NoteValueType.USER_VAL

Properties

This is a partial list of properties available for elements. An automatic documentation is not available currently and will be finished later. You can also find out all available elements' properties using
console.log(Object.keys(element));
which will print a list of properties names if launched in Plugin Creator window.

name type details
pitch int MIDI pitch of this note
tpc int Tonal pitch class, as per concert pitch setting
tpc1 int Tonal pitch class, non-transposed
tpc2 int Tonal pitch class, transposed
small bool Small notehead, chord or rest
mirrorHead bool Mirror notehead on x-axis
line int Notehead position
color color Color of element
track int Track the elment belongs to
selected bool Element is selected
generated bool True, if the element has been generated by layout
offset point Offset from normal layout position
placement int Placement in staff: Placement.ABOVE, Placement.BELOW

This is a work in progress.