mediawiki-extensions-Score

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

mediawiki-extensions-Score

(★ 8)

Github mirror of MediaWiki extension Score - our actual code is hosted with Gerrit (please see https://www.mediawiki.org/wiki/Developer_access for contributing)

mediawiki-extensions-Score Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 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](https://gitlab.com/lilypond/lilypond/-/releases) 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

1. Change to the "extensions" directory of your MediaWiki installation.
2. Clone this repository.
3. 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.
4. Add the following lines to the `LocalSettings.php` file:
```php
   wfLoadExtension( 'Score' );
   $wgScoreTrim = true;
```
5. If you want to use SVG output, add:
```php
   $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:
```php
   $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](https://www.mediawiki.org/wiki/Manual:$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:

```php
$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 <score>…</score> 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

* 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: line_width_inches
  - Allowed values: positive number, can have decimal places
  - Effect: set the width of the lines in the generated score, by setting the
          `line-width` directive in the LilyPond paper settings.

* 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:**
   ```bash
   # 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
   ```

mediawiki-extensions-Score

mediawiki-extensions-Score Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

mediawiki-extensions-Score

mediawiki-extensions-Score Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README