Plugins for 4.x

Updated 2 weeks ago

This chapter is for MuseScore 4 plugin developers. To fork the main program, visit the main sections in Developers' handbook.
For info on what plugins are, how to install and use them, visit Musescore 4 handbook plugin chapter.

Porting 3.x plugins to Musescore 4

Plugin system change coming up in 4.x, see github issue and graffesmusic's comment .

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)

Some plugins have been ported to or created for Mu4.4 (Qt6):

Tips for adapting plugins for 4.x

Volatile: prone to become outdated as the plugin API changes
Last updated: 31st Aug 2024

  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, for MuseScore 4.0-4.3 and these comments, for MuseScore 4.4, like this, to have the plugin work for MuseScore 3.x, 4.0-4.3 and 4.4:

    //4.4 title: "Some Title"
    //4.4 thumbnailName: "some_thumbnail.png"
    //4.4 categoryCode: "some_category"
    Component.onCompleted: {
        if (mscoreMajorVersion >= 4 && mscoreMinorVersion <= 3) {
            title: "Some Title";
            thumbnailName = "some_thumbnail.png";
            categoryCode = "some_category";
        }
    }
 

If you need it for MuseScore 4 only, use:

    title: "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", "playback" and "lyrics").

  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. Changing it to pluginType: "dialog" might work. Even using the methods from step 2 should work, only for Mu4, while keeping "dock" for Mu3

  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)
    The first call to SymID can take upto 5 seconds!! (some compilation going on?)
    see: https://musescore.org/en/node/364096?page=1#comment-1247486

  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

  5. In MU4.4, Qt.labs.settings has been integrated in the Musescore module. The explicit import Qt.labs.settings 1.0 must be removed (it leads to an "Module "Qt.labs.settings" is not installed" error) and is not required for the Settings module to work.

REMARKS: