README

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

Prerequisites
=============

This extension uses LilyPond to render score images, so you need a working
LilyPond installation. If you want the extension to trim the score files for
you, you will also need ImageMagick.

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

https://www.mediawiki.org/wiki/Extension:OggHandler

for more information.

This extension was tested with MediaWiki 1.19alpha from SVN and LilyPond 2.12.3.


Setup
=====

1. Change to the "extensions" directory of your MediaWiki installation.
2. Create a new subdirectory named "Score".
3. Copy the files Score.php, Score.body.php and Score.i18n.php into the new
   subdirectory. Make sure they are readable by your webserver.
4. Create a subdirectory named "lilypond" in your $wgUploadDirectory (usually
   the directory named "images" in 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.
5. Add the lines

   require_once("$IP/extensions/Score/Score.php");
   $wgScoreLilyPond = '/path/to/your/lilypond/executable'; /* required */
   $wgScoreAbc2Ly = '/path/to/your/abc2ly/executable'; /* if you want ABC to
                                                          LilyPond conversion */
   $wgScoreTimidty = '/path/to/your/timidty/executable'; /* if you want MIDI to
                                                            Vorbis conversion */
   $wgScoreTrim = true; /* Set to false if you don't want score trimming */

   to your LocalSettings.php file. If you get unexpected out-of-memory errors,
   you may also have to increase $wgMaxShellMemory (see

   https://www.mediawiki.org/wiki/Manual:$wgMaxShellMemory

   for more information.


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

          <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: midi
  Allowed values: 0 (default), 1
  Effect: If set to 1, the rendered image(s) will be embedded into a hyperlink
          to an appropriate MIDI file.

* Attribute: override_ogg
  Allowed values: Known file name, that is, if override_ogg="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). It can, for example, be useful if you have a suitable
          Ogg/Vorbis file of superior quality compared with the auto-generated
          Ogg/Vorbis file the vorbis 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: raw
  Allowed valued: 0 (default), 1
  Effect: 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.

* Attribute: vorbis
  Allowed values: 0 (default), 1
  Effect: If set to 1, an Ogg/Vorbis file will be generated for the score,
          provided you installed and configured the OggHandler extension.
          An Ogg/Vorbis player will be embedded in the HTML below the score
          image(s).