Extension:Score - MediaWiki
Jump to content
From mediawiki.org
Translate this page
Languages:
Tiếng Việt
Türkçe
Yorùbá
italiano
polski
português
português do Brasil
svenska
čeština
русский
українська
हिन्दी
বাংলা
中文
한국어
This code base is maintained by the
Reader Experience team
Code review only for UBNs or security fixes.
The Score extension requires setting up an external service,
Shellbox
, to securely process musical scores via LilyPond. Please review the information in
#Security concerns
and the
2021 security advisory
before installing this extension.
MediaWiki extensions manual
Score
Release status:
stable
Implementation
Tag
Description
Allows rendering of musical scores with
LilyPond
Author(s)
Alexander Klauer
Étienne Beaulé
Latest version
0.3.0 (2019-03-23)
MediaWiki
1.36+
PHP
5.3+
Parameters
$wgScorePath
$wgScoreSoundfont
$wgScoreFluidsynth
$wgScoreLame
$wgScoreSafeMode
$wgScoreLilyPond
$wgWikibaseMusicalNotationLineWidthInches
$wgScoreImageMagickConvert
$wgScoreLilyPondFakeVersion
$wgScoreFileBackend
$wgScoreDirectory
$wgScoreTrim
$wgScoreGhostscript
$wgMusicalNotationEnableWikibaseDataType
$wgScoreOfferSourceDownload
$wgScoreMaxLength
$wgScoreDebugOutput
$wgScoreUseSvg
$wgScoreAbc2Ly
$wgScoreDisableExec
$wgScoreEnvironment
Tags
score
Hooks used
ParserFirstCallInit
ResourceLoaderRegisterModules
SoftwareInfo
WikibaseClientDataTypes
WikibaseRepoDataTypes
WikibaseRepoWbui2025InitResourceDependenciesHook
Licence
GNU General Public License 3.0 or later
Download extension
Git
Browse repository
GitHub
Gerrit code review
Git commit log
Download source tarball
README.md
Translate the Score extension
if it is available at translatewiki.net
Issues
Open tasks
Report a bug
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
Extension:LilyPond
was written by Johannes E. Schindelin.
This extension is based on a
code review
of
Extension:LilyPond
by Tim Starling.
The original
Extension:ABC
was written by River Tarnell.
Usage
After
setup
, you can embed simple
LilyPond notation
into your wikitext inside a
<
score
...
score
tag. For example:
"lilypond"
\relative
c'
cis
cis
yields:
You may also specify attributes to the score tags in the general form
"value1"
attribute2=
"value2"
For example:
score
sound
"1"
lang
"lilypond"
\relative
c'
\set
Staff
midiInstrument
"tenor sax"
cis
cis
}score
yields:
Audio playback is not supported in your browser. You can
download the audio file
The following attributes are available:
Attribute
Allowed values
Effect
lang
ABC, lilypond
(default)
Sets the score language. For example, to provide a score in
ABC notation
, you might use:
"ABC"
X:1
M:C
L:1/4
K:C
C,
D,
E,
F,|G,
A,
B,
C|D
G|A
d|
a|b
c'
d'
e'|f'
g'
a'
b'|]
midi
(removed)
This used to control whether the rendered score image linked to a MIDI file.
override_midi
Known file name, that is, if
override_midi="name"
is given,
[[File:name]]
does not yield a red link
(deprecated)
Instead you can add a
[[File:
superior midi filename
.mid]]
wikilink after the closing
score
tag.
Uses the specified MIDI file instead of generating one with LilyPond. Use this attribute together with the midi attribute (see before) or the sound attribute (see later). This attribute is useful if you already have a MIDI file whose quality is superior to what would be generated by LilyPond.
override_audio
Known file name, that is, if
override_audio="name"
is given,
[[File:Name]]
does not yield a red link
(deprecated)
Instead you can add a
[[File:
superior audio filename
.oga]]
wikilink after the closing
score
tag.
Embeds the media specified by the file name in the
HTML
after the score image(s). This is an alternative to the sound attribute (see further). It can, for example, be useful if you have a suitable audio file of superior quality compared with the auto-generated audio file. Of course, you can still omit both attributes in this case and add the file manually to the page, if you prefer.
override_ogg
(deprecated)
Doubly-deprecated alias for
override_audio
raw
(default)
, 1
If set to 1, 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. By default (when
raw=0
), provided code is wrapped in a
\score{...}
block, along with default
\layout{...}
and
\midi{...}
blocks, if not already provided.
sound
(default)
, 1
If set to 1, an audio file will be generated for the score, provided you installed and configured
Extension:TimedMediaHandler
. An audio player will be embedded in the HTML after the score image(s).
vorbis
(default)
, 1
(deprecated)
Alias for
sound
The LilyPond language
Lyrics may be added like this:
score
lang
"lilypond"
sound
"1"
\relative
c''
\time
4/4
\key
\major
^>
^>
\bar
"|."
\addlyrics
Shave
and
hair
--
cut
two
bits
score
Audio playback is not supported in your browser. You can
download the audio file
For advanced users, the
\set
Staff.midiInstrument
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
Extension:TimedMediaHandler
installed.
FluidSynth is the preferred method to convert MIDI files to audio files, however TiMidity++ is also supported.
Security concerns
Use Shellbox to secure LilyPond to protect your wiki!
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
README.md
for detailed installation instructions.
and move the extracted
Score
folder to your
extensions/
directory.
Developers and code contributors should install the extension
from Git
instead, using:
cd
extensions/
git
clone
Add the following code at the bottom of your
LocalSettings.php
file:
wfLoadExtension
'Score'
);
$wgScoreTrim
true
$wgImageMagickConvertCommand
'/usr/bin/convert'
$wgShellboxUrl
'... address to Shellbox ...'
$wgShellboxSecretKey
'... your secret key ...'
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 Web server.
Done
– Navigate to
Special:Version
on your wiki to verify that the extension is successfully installed.
Configuration
Here are some of the extension's global configuration parameters.
$wgScoreLilyPond
Set
$wgScoreLilyPond
to the path to your LilyPond executable (typically
/usr/bin/lilypond
or
/usr/local/bin/lilypond
).
$wgScoreTrim
The
$wgScoreTrim
is a boolean which defaults to the value of
$wgUseImageMagick
. If
true
, the resulting score PNG images are trimmed with ImageMagick. If you don't want trimming, or don't want to install ImageMagick, set
$wgScoreTrim
to
false
$wgScoreAbc2Ly
Set
$wgScoreAbc2Ly
to the path of your ABC to LilyPond converter executable (typically
/usr/bin/abc2ly
or
/usr/local/bin/abc2ly
).
$wgScoreFluidsynth
Set
$wgScoreFluidsynth
to the path of your
Fluidsynth
executable (typically
/usr/bin/fluidsynth
or
/usr/local/bin/fluidsynth
).
$wgScoreSoundfont
Set
$wgScoreSoundfont
to the path of your
soundfont
file (typically
/usr/share/sounds/sf2/FluidR3_GM.sf2
or
/usr/share/sounds/sf2/FluidR3_GS.sf2
).
$wgScoreLame
Set
$wgScoreLame
to the path of your
Lame
executable (typically
/usr/bin/lame
or
/usr/local/bin/lame
). 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
$wgMaxShellMemory
if you get "out of memory" errors.
Finding scores
Pages containing
<
score
tags are in the
tracking category
with message name 'score-use-category'.
Visit
Special:TrackingCategories
to find the localized title of this category on your wiki and show the pages in it, for example
w:Category:Pages using the Score extension
on the English Wikipedia.
See also
Help:Score
on English Wikipedia and
Help:Sheet music
on Wikisource have more examples of LilyPond syntax.
LilyPond notation
ABC notation
This extension is being used on one or more
Wikimedia projects
. This probably means that the extension is stable and works well enough to be used by such high-traffic websites. Look for this extension's name in Wikimedia's
CommonSettings.php
and
InitialiseSettings.php
configuration files to see where it's installed. A full list of the extensions installed on a particular wiki can be seen on the wiki's
Special:Version
page.
Retrieved from "
Categories
Stable extensions
Tag extensions
ParserFirstCallInit extensions
ResourceLoaderRegisterModules extensions
SoftwareInfo extensions
WikibaseClientDataTypes extensions
WikibaseRepoDataTypes extensions
WikibaseRepoWbui2025InitResourceDependenciesHook extensions
GPL licensed extensions
Extensions in Wikimedia version control
All extensions
Extensions used on Wikimedia
Music editor extensions
Extensions with VisualEditor support
Hidden categories:
Pages using the Score extension
Extensions without a compatibility policy
Extensions with manual MediaWiki version
Extension
Score
Add topic
US