MuseScore 1.x Plugin File Structure

Updated 5 years ago

Plugin file

To be recognized as a plugin by MuseScore, a file must:

  1. have a file name ending with the ".js" extension;
  2. be placed in the plugins folder. A plugin with many files should use a sub-folder within the plugins folder to avoid cluttering the main plugin directory and to simplify uninstallation.
    • The Linux plugin directories are usually located at $install-path$/museScore/plugins (system-wide) and ~/.local/share/data/MusE/MuseScore/plugins (personal).
    • On Windows, it is usually located at <install-path>\MuseScore\plugins (system-wide) and in %LOCALAPPDATA%\MusE\MuseScore\plugins on Vista and Seven or C:\Documents and Settings\USERNAME\Local Settings\Application Data\MusE\MuseScore\plugins (personal, adjusted to your language version) on XP.
    • On Mac, it's located at /Applications/MuseScore.app/Contents/Resources/plugins or ~/Library/Application Support/MusE/MuseScore/plugins
  3. the filename needs to be unique (accross the different directories, the personal ones are searched first and 'shadow' later plugins with the same filename)

The plugin file is re-read on every execution, so during plugin development you do not need to restart MuseScore after every edit in the plugin file.

Plugin file structure

The JavaScript source code of a MuseScore plugin has to contain at least three members:

  • mscorePlugin variable: defines the plugin entry points and the expected interface level. It is an associative array with the following 6 elements:
    • majorVersion integer: the API major version the plugin is made for (optional, currently 1)
    • minorVersion integer: the API minor version the plugin is made for (optional, currently 1)
    • menu string: the MuseScore menu item where to place the plugin command; this string has the format 'Plugins.<plugin name>', where <plugin name> is the command name which will appear in the MuseScore menu.
    • init identifier: the name of the plugin function to call when the plugin is initially loaded. Usually this function is also called init().
    • run identifier: the name of the plugin function to call when the plugin menu item is selected. Usually this function is also called run().
    • onClose identifier: the name of the plugin function to call when the plugin is unloaded. Usually this function is called close().
  • <init>() function: called by MuseScore when the plugin is initially loaded (currently when the programme starts). <init> is a place-holder: the actual function name is declared in the mscorePlugin variable. Mandatory.
  • <run>() function: called by MuseScore when the plugin is selected in the "Plugins" menu. This is the actual starting point of the plugin. <run> is a place-holder: the actual function name is declared in the mscorePlugin variable. Mandatory.
  • <close>() function: called by MuseScore when the plugin is closed down (unloaded). <close> is a place-holder: the actual function name is declared in the mscorePlugin variable. Optional.

This is an example of a "no-operation" but complete plugin:

function init() {};
function run() {};
function close() {};
 
var mscorePlugin = 
{
   majorVersion:  1,
   minorVersion:  1,
   menu: 'Plugins.test',
   init: init,
   run: run,
   onClose: close
};
 
mscorePlugin;