Extension:Score

The Score extension allows the rendering of musical scores as PNG images using LilyPond and can also transform them into audio and MIDI files.

Acknowledgements

 * The original was written by Johannes E. Schindelin.


 * This extension is based on a code review of by Tim Starling.


 * The original was written by River Tarnell.

Usage
After setup, you can embed simple [ http://lilypond.org/doc/Documentation/learning-big-page#common-notation LilyPond notation] into your wikitext inside a  tag. For example:

yields:

You may also specify attributes to the score tags in the general form

.

For example:

yields:

The following attributes are available:

The LilyPond language
Lyrics may be added like this:

For advanced users, the [ http://lilypond.org/doc/Documentation/notation/using-midi-instruments  ] command can be used to change the MIDI instrument for the sound.

Prerequisites
The following packages are recommended:


 * LilyPond
 * Ghostscript
 * ImageMagick
 * FluidSynth
 * Firejail

This extension uses LilyPond to render score images, so you need a working LilyPond installation ( Special:Version displays the LilyPond version). If you install LilyPond from a package, Ghostscript will also be installed, since LilyPond depends on Ghostscript. ImageMagick should be installed to trim the images, otherwise they will contain an excessive amount of whitespace.

For security reasons, it is highly recommended to install firejail to further restrict what LilyPond and Ghostscript can do if untrusted users are allowed to edit your wiki.

The extension is also capable of creating audio files from the MIDI files generated by LilyPond. If you want to make use of this functionality, you need to have installed.

FluidSynth is the preferred method to convert MIDI files to audio files, however TiMidity++ is also supported.

== Security concerns == Score uses LilyPond in safe mode, however there are known unfixed safe mode escape vulnerabilities leading to arbitrary execution.

If you don't absolutely trust everyone who has editing privileges on your wiki, it is strongly recommended to set up containment of lilypond using Shellbox. See Shellbox#Server setup for details on how to set up the contained server, and below for configuring MediaWiki to use it. Also, ensure you're using a recent version of LilyPond (2.22.0+) or a distribution package (e.g. from Debian) that has security fixes. Keep safe mode enabled, even with containment as an extra layer of defense. Certain functionality will not work in safe mode, the fix for that is to modify LilyPond to allow that functionality in safe mode.

Installation

 * See the extension's  for detailed installation instructions.

Configuration
Here are some of the extension's global configuration parameters.

$wgScoreLilyPond
Set  to the path to your LilyPond executable (typically   or  ).

$wgScoreTrim
The  is a boolean which defaults to the value of. If, the resulting score PNG images are trimmed with ImageMagick. If you don't want trimming, or don't want to install ImageMagick, set  to.

$wgScoreAbc2Ly
Set  to the path of your ABC to LilyPond converter executable (typically   or  ).

$wgScoreFluidsynth
Set  to the path of your Fluidsynth executable (typically   or  ).

$wgScoreSoundfont
Set  to the path of your soundfont file (typically   or  ).

$wgScoreLame
Set  to the path of your Lame executable (typically   or  ). Required if the generated audio file should be a MP3.

Remarks
This extension runs various binaries in a Shellbox to provide some security. You may have to increase if you get out of memory errors.

Finding scores
Pages with scores on them will have the "score" page property set. Using Special:PagesWithProp, you can find pages that have scores. ([ //en.wikipedia.org/wiki/Special:PagesWithProp?propname=score&propname-other= Example query for the English Wikipedia].)