MuseScoreExampleManager

LibreOffice / OpenOffice extension to manage MuseScore sheet music examples within text documents.

The extension runs equally well on LibreOffice (LO) and Apache OpenOffice (AOO). Where you see OpenOffice (OO) written in this guide you may assume it applies to both.

• Instructions, and the latest stable version, are available from the LibreOffice Extension Centre, along with past releases.
• Development is done through GitHub. Code contributions are welcome via Pull Requests.

For the extension to function, MuseScore must be present on the system. The extension works by running MuseScore in the background to generate PNG images from sheet music (.mscz) files. It is easy to update the images later if the original score is modified.

Usage: inserting and updating sheet music images

From within OpenOffice, put the cursor where you want a sheet music example to appear. Click the MuseScore icon on the toolbar or go to "Insert -> MuseScore Example" and select an MSCZ file. A graphic representation of the example (with excess whitespace automatically trimmed) will be generated and inserted into your document with a link to the original MSCZ file. Ctrl-click the example to edit it further in MuseScore. After editing and saving the example in MuseScore, you can select the graphic in OpenOffice and press the MuseScore button again to update it.

Installation: adding the extension to LibreOffice / Apache OpenOffice

Before commencing, ensure you have a working copy of MuseScore on your computer.

1. Download the MuseScoreExampleManager extension package (.oxt file) onto your computer. It will be called "musescore-X.Y.Z.oxt" where X.Y.Z corresponds to the extension version.
2. Save and close any open OpenOffice documents.
3. Open a new Writer document.
4. Go to Tools -> Extension Manager... -> Add... and locate the .oxt file.
5. Restart OpenOffice.

First Run: locating dependencies

The MuseScoreExampleManager extension relies on other programs to process the sheet music and images in the background. The first time you run the extension you will be asked for the location of these programs in the form of a file path. The file path must include both the filename of the executable and the installation directory.

Locating MuseScore

The first time you run the extension within OpenOffice, you will be prompted for the file path to the MuseScore excecuteable. The default paths are:

• Windows: "C:\Program Files (x86)\MuseScore X\bin\MuseScore.exe" (X is version number).
• Mac: "/Applications/MuseScore X.app/Contents/MacOS/mscore" (X is version number).
• Linux: "/usr/bin/mscore" (or the output of the Terminal command $ which mscore).

If the extension detects a copy of MuseScore in the default location, you can simply confirm the location that is already entered for you.

Note: if you have multiple copies of MuseScore installed then make sure you give the path to the correct version.

Development: adding new features to the MuseScoreExampleManager extension

Source code

You can open up the extension package OXT file in any regular archival program (e.g. WinZip) to view the source code and make small changes to your personal copy. If you are making larger changes, or if you want to share your changes with the world, then you must use GitHub (see below).

Compiling and Packaging

The file "musescore.odt" contains OpenOffice macros that perform the whole packaging process for you (it's a copy of the OpenOffice Extension Compiler). It analyses the code and generates some XML manifest documents which are packaged up with the source code inside a ZIP archive. The archive is given the OXT extension and it is this that is added to OpenOffice.

To "compile" (package) the source code into an OXT extension file:

1. Delete any temporary autosave files in the package directory (they may be hidden) to avoid including them in the final package. (If using Git this can be done with the command $ git clean -fXd).
2. Open the Writer document "musescore.odt" and run the macro on page 8.

You may have to give permission for the macro to run. It will also require a copy of the Java Runtime Environment (JRE) to be installed on your computer. Alternatively, the OpenJDK is perfectly adequate, and can be found in the default repository of many Linux distributions.

Contributing via GitHub

Code contributions are welcome and should be submitted in the form of Pull Requests. Detailed instructions are available elsewhere.

Unlike most projects on GitHub, this one contains a copy of the compiled program as well as the raw source code. Make sure you recompile (having first rebased) before you submit the Pull Request.