commit	492b1a768d216772bfac655f21ea234a8355e9e3	[log] [tgz]
author	Sam Reed <sam@reedyboy.net>	Fri Jul 17 16:52:02 2026 +0100
committer	Sam Reed <sam@reedyboy.net>	Fri Jul 17 16:52:02 2026 +0100
tree	81249c496fe846fc9ade3de44b51a1ca432cf01c
parent	d8dc03ccc6b9153dcc674e2054e04339e3a62f6a [diff]

tree: 81249c496fe846fc9ade3de44b51a1ca432cf01c

README.md

Score extension

Score, a MediaWiki extension for rendering musical scores with LilyPond.

Security

In earlier versions of this extension, LilyPond ran in safe mode.

However, it is unsafe to rely on safe mode due to unfixed vulnerabilities, and indeed safe mode was removed in LilyPond version 2.23.12.

Score no longer attempts to run LilyPond in safe mode.

It is recommended that LilyPond is run as an unprivileged user inside an isolated container with no external network access.

MediaWiki's system for remote execution of shell commands is called Shellbox. Instructions to set up a Shellbox server can be found at: https://www.mediawiki.org/wiki/Shellbox.

Installing LilyPond and prerequisites

Ensure the following additional packages are installed in your Shellbox container:

LilyPond (version 2.23.82 or later is required)
FluidSynth
A SoundFont for FluidSynth, for example, Fluid (R3) General MIDI SoundFont (GM)
LAME

If you are not using SVG output, you will also need to install:

Ghostscript
ImageMagick

You'll also want fonts for whatever characters are used in lyrics. The Noto font family may be a good choice as it aims to cover all scripts.

Note that upstream packaging changed for versions 2.23 and later; a tarball can be downloaded directly from the GitLab releases page and extracted into /usr/local/lilypond (for example). In this case, the binary locations for the extension setup (see below) will be:

/usr/local/lilypond/bin/lilypond
/usr/local/lilypond/bin/abc2ly

Running on Windows

Running the Score extension on Windows is possible, although inadvisable.

Shellbox cannot do cross-platform requests, so if MediaWiki runs on Windows, it would be necessary to run LilyPond on Windows as well. Proper security isolation in such a setup would be difficult. Consider instead running MediaWiki inside a Linux container.

Score uses POSIX shell scripts and so requires a Bash or a similar shell to be installed, for example, the MinGW shell that is distributed with Git for Windows. Configure its location with $wgShellboxShell, typically:

$wgShellboxShell = 'C:\Program Files\Git\bin\bash.exe';

GhostScript is distributed with LilyPond, however this GhostScript cannot find its library directory unless an environment variable is set, e.g.:

$wgScoreEnvironment = [
	'GS_LIB' => 'C:\Program Files (x86)\LilyPond\usr\share\ghostscript\9.21\Resource\Init'
];

Extension setup

Change to the "extensions" directory of your MediaWiki installation.
Clone this repository.
Create a subdirectory named "lilypond" in your $wgUploadDirectory (usually the directory named "images" in your MediaWiki directory). Make sure the directory is writable by your webserver. If you do not create this directory, the Score extension will attempt to create it for you with the rights available to it.
Add the following lines to the LocalSettings.php file:

   wfLoadExtension( 'Score' );
   $wgScoreTrim = true;

If you want to use SVG output, add:

   $wgScoreUseSvg = true;

If you are not using SVG, you will need to ensure Score knows where to find Ghostscript and ImageMagick binaries (see below). 6. If you are using Shellbox to sandbox your lilypond processes, add:

   $wgShellboxUrls['score'] = 'http://shellbox.internal/shellbox';
   $wgShellboxSecretKey = '... your secret key ...';

If you get unexpected out-of-memory errors, you may also have to increase $wgMaxShellMemory.

By default, Score will look for binaries by their usual names in /usr/bin. If you need to customise the locations of any of the binaries, you can copy the lines below and change them as necessary:

$wgImageMagickConvertCommand = '/usr/bin/convert';
$wgScoreLilyPond = '/usr/bin/lilypond';
$wgScoreAbc2Ly = '/usr/bin/abc2ly'; /* part of LilyPond */
$wgScoreFluidsynth = '/usr/bin/fluidsynth';
$wgScoreSoundfont = '/usr/share/sounds/sf2/FluidR3_GM.sf2'; /* for FluidSynth */
$wgScoreGhostScript = '/usr/bin/gs';

Usage

After setup, you can use the … tags in your wiki markup. For a simple score, use e.g.

<score>\relative c' { f d f a d f e d cis a cis e a g f e }</score>

This will render the appropriate score as a PNG image.

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

<score attribute1="value1" attribute2="value2">…</score>.

The following attributes are available:

Attribute: lang
- Allowed values: ABC, lilypond (default)
- Effect: Sets the score language. For example, to provide a score in ABC notation, you might use
```
  <score lang="ABC">
  X:1
  M:C
  L:1/4
  K:C
  C, D, E, F,|G, A, B, C|D E F G|A B c d|
  e f g a|b c' d' e'|f' g' a' b'|]
  </score>.
```
Attribute: override_midi
- Allowed values: Known file name, that is, if override_midi="name" is given, [[File:name]] is not a redlink.
- Effect: Embeds the score image(s) into a hyperlink to a specified MIDI file. This is an alternative to the midi attribute (see above). It can, for example, be useful if you have a suitable MIDI file of superior quality compared with the auto-generated MIDI file the midi attribute yields. Of course, you can still omit both attributes in this case and add the file manually to the page, if you prefer.
Attribute: override_audio
- Alias: override_ogg
- Allowed values: Known file name, that is, if override_audio="name" is given, [[File:name]] is not a redlink.
- Effect: Embeds the media specified by the file name in the HTML below the score image(s). This is an alternative to the vorbis attribute (see below). Its use is similar to the use of the override_midi attribute (see above).
Attribute: raw
- Effect: If included in the tag, the score code is interpreted as a complete LilyPond file. Use this option if you want to create more complex scores. If the score language (lang attribute) is not set to lilypond, this attribute is ignored.
Attribute: sound
- Alias: vorbis
- Effect: If included in the tag, an audio file will be generated for the score. An audio player will be embedded in the HTML below the score image(s).

Unit Testing

The Score extension includes unit tests for the musical-notation datatype functionality.

Running Tests

Run tests from MediaWiki core:

# From the MediaWiki core directory
composer phpunit -- extensions/Score/tests/phpunit/includes
# or run a specific test file
composer phpunit -- extensions/Score/tests/phpunit/includes/ScoreFormatterTest.php