Plugins for 3.x

Updated 7 hours ago

    Not to be confused with Musescore 4's VST and VSTi feature. Other plugin versions see Plugin development.

    Introduction

    Edit this page to share Musescore 3 plugin programming knowledge. Discussion thread.

    Writing and running plugins requires,

    • Musescore Studio installed,
    • Javascript knowledge, and
    • QML knowledge.

    You own what you create.

    QML

    Written with just enough jargon inaccurately, like "the sun rises in the east"..

    Qt company invented QML,

    1. rules to write .qml files, including
      • QML Types
        • Data, eg a Point has a X and a Y
        • UI, eg a Rectangle has width, height, color etc
    2. extended rules to write .qml files, by adding import statements
    3. rules to write C++ (.cpp, .h etc) files including separated copies share similar naming of some items above,
      • Qt Widget, fine-control UI programming.
      • QML Widget (Qt Quick Widget), abstract UI programming.

    Note that item 3 is for Musescore main app devs only. Things with similar names use different rules, don't read the wrong doc.

    //https://doc.qt.io/archives/qt-5.9/qtqml-documents-topic.html
import QtQuick 2.0
Rectangle {
    width: 100; height: 100
    color: "red"
    MouseArea {
        anchors.fill: parent
        onClicked: console.log("Button clicked!")
    }
}

    Any of these work,

    onClicked: console.log("Button clicked!") 
onClicked: function(){ console.log("Button clicked!") }

    Use javascript / ECMAScript 7th edition function. Unsupported are arrow function, spread syntax, array.fill etc.

    Musescore plugin qml

    Musescore plugin qml uses,

    1. all rules of .qml files,
    2. functions made available by the Musescore dev team.

    Capability and limitation

    This non-exclusive list contains observations reported by coders.

    • Examples of basic functionality
      • Change a note's property such as pitch, color
      • Add or remove score elements such as notes, rests, symbol, text
      • Read or save tags in File > Score Properties
      • Play the audio of a score or part of score
      • Create a new staff (Cannot change its name afterwards)
      • Create/update text and symbols eg dynamics, lyrics etc
      • Create/update tempo
      • Change playback speed (cmd('playback-speed-increase'))
      • Mute or change volume of an instrument
      • Create/update MIDI Play Event
      • Conversion of a different score format to and from MuseScore
      • Send and receive score data through internet
      • Opens a local or online webpage inside MuseScore
      • Save or load a score or any file
      • Start another program on your Windows/iOS outside MuseScore
    • Seems unachievable (please share if you find workaround, for example a suitable cmd() command )

    See also https://musescore.org/en/node/372023

    Alternatives to QML plugin

    Workflow and external editors

    Edit plugin with,

    Plugin scripts are cached at program startup. To run a script updated afterwards in external editor,

    • Restart Musescore and then run from the plugin menu; or
    • Load the script inside Plugin Creator
      • Inside the Plugin Creator, open an existing .qml file
      • Press run
      • After subsequent edits in external editor, it is required to press Refresh in the Plugin Creator.
      • It is not required to restart Musescore when using this method.

    Code examples

    copycat200.jpg

    Copy and paste. Share yours.

    Common tasks

    Changing menu name, window behavior

    Get elements

    • Read Score elements, internal score structure.
    • curScore.newCursor() to create a Cursor, transverse and find. For more info, open and study walk.qml
    • curScore.newCursor() to create a Cursor, sync with current mouse selection example
    • select with mouse click then get curScore.selection.elements[ ]
    • listen to state.selectionChanged, get curScore.selection example
    • select with curScore.selection.selectRange() , get curScore.selection example

    Read meaningful info of element type

    • Print .name property.

    Match and compare element types

    enum2.png

    Match and compare reliably with .type property eg  Accidental.FLAT . See enumeration / enum. These pages are useful,

    Try log type enum string snippet and Makeshift REPL plugin function tester plugin for enum and keyword autocompletion.

    Note starting time, ending time, duration (note value)

    Note pitch

    Placement of objects, cursor track and tick

    cursor.rewindToTick(x) will only work correctly if there is a segment at x. Otherwise it will put the cursor at the next available segment (in the current track) after x, see https://musescore.org/en/node/345409#comment-1206211

    Save settings to score, tagging

    Save settings to OS

    eg registry in windows

    File saving and loading

    Instrument / staff info eg instrument name, and channel audio status

    Create/update MIDI Play Event

    Fetching webpage

    Starting another program, command line and parameters

    Get UI theme status

    Not engraving style

    Browsing help sites

    QML help sites

    doc.qt.io

    When browsing https://doc.qt.io, note that

    • "C++ classes" pages are not useful in qml.
    • Check qt version on URL. Musescore 3.6.2 requires Qt 5.9.9 syntax. Some pages can be auto redirected by changing "6" in URL to "5.9". eg changing https://doc.qt.io/qt-6/qml-qtquick-wheelevent.html to https://doc.qt.io/qt-5.9/qml-qtquick-wheelevent.html and refreshing jumps to https://doc.qt.io/archives/qt-5.9/qml-qtquick-wheelevent.html.

    • Use a matching the import module version number on pages returned from site search. eg site search "button" returns QtQuick 1 Button but not QtQuick 2 Button.

      url6.png
      url59.png
      text_cpp.png
      text_qml.png

    musescore.org

    plugin help sites

    musescore.github.io

    The cmd ( ) method

    Unstable. Backup QML. Use cmd() to run internal program actions.

    musescore.org

    Useful Resource

    The Plugin Base Component Musescore { }

    • Api doc
    • Component.onCompleted
      Run once, right after the plugin component is created, before console.log() is functional
    • You should not use Qt.quit() in your plugins, see this post on why, and possible different approaches. Qt.quit() crashes Musescore 4.0 plugins.
    • Set pluginType: "dock" for normal behavior eg stay on top; "dialog" is quite outdated.
    • Create plugin as an action instead of a persistent object with prop and methods, because when the user close and reopen the plugin window, it may cause unwanted behavior.
      • This post explains the nature of onRun() and Qt.quit(). The code Qt.quit() may not work the way you expect.
      • The plugin window onClosing Event is not accessable from QML. The [Plugin API base] is in a QQuickView in a QWidget window docked inside a QDockWidget , see code.
      • No way to detect plugin's open or closed.
      • After plugin window is closed, listeners will continue to run, eg experimental onScoreStateChanged Handler
      • Workaround palette-like plugin
      • use Qt Labs Settings to save data across sessions
      • other tips also check out the snippets and notes page

    Score elements, internal score structure

    Bundled resource (qrc protocol)

    Searchable museScore 3.6.2 source code

    Translation

    Troubleshooting with help from community

    Share your plugin

    Licensing

    • Writing in QML language is unlikely to be the ground on which plugin script subjects to Qt licensing.
    • Opening in Musescore is unlikely to be the ground on which plugin script subjects to MuseScore 3 GPL licensing.

    Credits