Plugins for 4.x

Updated 1 month ago
This page shows old instructions for MuseScore 1.
For MuseScore 4 users, see Plugins for 4.x.

Handbook plugin chapter

Porting 3.x plugins to Musescore 4

Plugin system change coming up in 4.x, it'd be wise to wait, see github issue.
Discuss with other dev in this forum thread, tips navigating github Mu4 repo
Some plugins have been ported to or created for Mu4:

  • This list (Plugins in the repository marked as being available for 4.x)
  • Batch Convert (not really working though, except for the UI)

Tips for adapting plugins for 4.x

Volatile: prone to become outdated as the plugin API changes
Last updated: 25th Dec 2023

  1. Have your plugin and all its dependencies (if any) in its own subfolder (example)

  2. In the plugin file itself, add the new MuseScore 4 Properties conditionally (all are optional), like so:

    Component.onCompleted: {
        if (mscoreMajorVersion >= 4) {
            title = qsTr("Some Title")
            thumbnailName = "some_thumbnail.png"
            categoryCode = "some_category"
        }
    }
 
  • title is displayed in the Plugin Manager window (Home/Plugins), and makes the plugin easy to find.
  • thumbnailName is the file path to any Plugin logo, also displayed in the Plugin Manager.
    If you add a thumbnail, place it in the plugin subfolder. If no file is provided, a default image will be used in its place.
  • categoryCode assigns the plugin to a specific sub-menu in the plugins tab (Currently available are: "composing-arranging-tools", "color-notes" and "playback").
  1. Place your translations files (if any) in a "translations" folder placed the plugin subfolder.

  2. Remove all occurences of Qt.quit(), else the plugin will crash MuseScore 4!

    • If you don't intend to use the plugin with Mu3, you can replace the Qt.quit() with quit().
      The latter is not supported by Mu3, and will result in an (ignorable) error.
    • If you want to avoid that message and change the Mu3 version as little as possible, use this:
      (typeof(quit) === 'undefined' ? Qt.quit : quit)()
    • Alternatively you could use return, which should work in all MuseScore versions.
  3. The APIs readScore() and writeScore() are not functional in Mu4 (yet).

  4. If your plugin modifies a score, those modifications need to be enclosed by

    curScore.startCmd()
    ...
    curScore.endCmd()
 

This should be done for Mu3 too, but there is optional, for Mu4 it is mandatory though.

  1. pluginType: "dock" is not working.

  2. The filePath property isn't working. You could use Qt.resolvedUrl(".").replace("file://", "") instead.

  3. Many of the enums have elements relocated, most notably Sid (style settings, the new Mu4 settings aren't yet exposed), SymId (there are new symbols, and old ones have different locations) and chordRest.beamMode (values have new locations)

  4. TextField component from QtQuick.Controls 1.0, must be replaced with the TextEdit component from QtQuick.Controls 2.15 (or from QtQuick.Controls 2.2 if you require compatibility with MuseScore 3). See github issue #19326 for details, source https://musescore.org/en/node/357135

REMARKS:

  • These tips are meant to have the plugins working for both MuseScore 3.x and 4.x
  • Even if you follow those steps, the adapted plugins might not even showing up in Mu4's plugins list. If so check the logs for hints (on Windows: "%LOCALAPPDATA%\MuseScore\MuseScore4\logs\").
  • The UI are not always rendering nicely. A lot of text elements shorten to 'somethi...' unreasonably soon, and there is less control over UI styling. Additionally, plugins cannot retain navigation focus, meaning keyboard use is less snappy.