Music Notation

Summary: Display music scores from various ascii notations (abc, abctab, asciitab, tab)
Version: 1.3 2008-03-07
Prerequisites: abcm2ps|abctab2ps, [tab2abc], [ascii2abctab], [abc2midi], [timidity], [lame|toolame], [flac], [oggenc], ghostscript, ppmtogif, pmcrop, content.php, markupsamepass.php
Status: Stable
Maintainer: Martin Fick
Categories: Markup
Discussion: Music-Talk

Questions answered by this recipe

  • Can I use PmWiki to display music in ascii notations (abc, abctab, asciitab, tab?)
  • Can I generate sound files (midi, wav, mp2/mp3, flac, vorbis) from abc notation?


This recipe converts music files in various ascii notations into other music notations and PostScript scores, gif images, and midi/wav/mp2/mp3/flac/vorbis files. Once configured (see below), this script enables markups of the form:

The gif image will display the notation as a musical score, and links underneath it will open the associated other available format files. See this recipe in action here.

The list of output types is configurable via the types, list and embed options which can be specified with all of the above directives. The formats for these options are:


The types= and list= options allow you to customize which of the available type-links to create links to or to embed. The list= determines what types will be available before the types= option is processed. The default list for every input type in this recipe is '-ppm,-ps' (every type except for ppm and ps), which means that the following types are likely to actually be output:

abcm:abcm, midi, wav, mp2, mp3, flac, vorbis, pdf, gif
abctab:abctab, midi, wav, mp2, mp3, flac, vorbis, pdf, gif
asciitab:asciitab, abctab, pdf, gif
tab:tab, abctab, midi, wav, mp2, mp3, flac, vorbis, pdf, gif

This list can then be added to or deleted from with the types= option. If a type in the types= option does not contain a '+' or a '-', the types list will be assumed to be an absolute list and the list= option will be ignored entirely.

The embed=false option can be used to disable image embedding in favor of a link.

If you want to modify the default list to be something other than '-ppm,-ps' follow the instructions below in the configuration section.


Download music.phpΔ, content.phpΔ and markupsamepass.phpΔ, copy them to cookbook directory and install them by adding to config.php:


Depending on the outputs you wish to produce, your system will also need some or all of the following external commands (executable programs):

You will need at least one of these two to get anything to work:
* abcm2psconverts abcm notation to postscript
* abctab2psconverts abctab notation to postscript
You will need the following to get any graphical outputs (ps, gif):
* gsGhostscript
* pnmcrop and ppmtogifConvert .ppm files to .gif
The following will allow you to support more music notations:
* ascii2abctabconverts asciitab to abctab
* tab2abcconverts tab notation to abctab
And finally, for sound file generation (midi, wav, mp2, mp3, flac, ogg):
* abc2midi or abcMIDIconverts abc notation to .mid file
* timidityconverts .mid files to .wav files
* lame or toolameconverts .wav files to .mp3 or .mp2 files
* flacconverts .wav files to .flac files
* oggenc (vorbis tools)converts .wav files to .ogg (vorbis) files

It is OK if you do no have all of the above executables on your system, the output for the particular missing converter will simply be omitted. On the other hand, if you have some of these executables, but do not want to support a specific converter with this recipe, simply comment the converter registration out in the music.php file!

If any of the converters are not in your web server's path you will need to edit the music.php script with the appropriate path. For example the ascii2abctab converter is defined like this:

  ContentRegFSConverter("asciitab", "abctab", 'ascii2abctab < ${i} > ${o}');

You could add an absolute path to this converter like this:

  ContentRegFSConverter("asciitab", "abctab", '/usr/local/bin/ascii2abctab < ${i} > ${o}');

The default path for temporary and cache files is set to /var/tmp/content. If you would like to change this, do so with the $ContentCfgCacheDir variable in your config.php.

If you want to secure your converters from data entered by non authorized authors, you can set a preview key with $ContentCfgPreviewKey.

Depending on which converters you use and the size of some of your songs, you may need to boost several php parameters to prevent php timeouts or out-of-memory errors. Some specific php parameters of interest defined in your php.ini are:

  max_execution_time = 30     ; Maximum execution time of each script, in seconds
  memory_limit = 8M           ; Maximum amount of memory a script may consume (8MB)

If you do not like the default list of output types, you may override it easily in your config.php by setting the $MUSIC_LIST variable to the list of types that you want by default.

For example, if you want wav and mp3 to not be output by default, set

  $MUSIC_LIST='-ppm,-ps,-wav,-mp3';   # all types except for ppm, ps, wav, and mp3

and then when you want to add them to certain songs, simply use types=+wav,+mp3, i.e.:

  (:abcm types=+wav,+mp3:)

Be sure to assign this variable in your config.php script before calling the music recipe!


Recipe sample pages.

This recipe uses the Content recipe. As such, it is very easy to add support for new formats if either of the following are already available to handle the format: some php code or an executable.

Since I do not own any windows machines, this recipe does not support that OS yet. If someone would like it to work on windows, I will gladly help them get it to work if they are willing to test it. As a prerequisite, make sure that any converters needed are supported on windows. Please feel free to post any success/failure attempts to port this to windows here and to the mailing list!

This recipe is a complete rewrite of Pm's AbcMusic recipe using the Content recipe. It supports two new formats, asciitab and tab, additionally it supports multi-page outputs and wav/mp3/flac/vorbis generation.

Release Notes

If the recipe has multiple releases, then release notes can be placed here. Note that it's often easier for people to work with "release dates" instead of "version numbers".

  • Version: 1.3 - 2008-03-07 - Added pdf support (suggested by Patrick Ogay), removed ps as a default link in favor of pdf.
  • Version: 1.2 - 2008-03-02 - Added flac and ogg-vorbis support (suggested by George De Bruin).
  • Version: 1.1 - 2008-02-29 - Added wav, mp2 and mp3 support (suggested by Patrick Ogay). (Really fixed midi MIME type
  • Version: 1.0.1 - 2007-09-00 - Fixed midi MIME type
  • Version: 1.0 - 2007-06-03 - Initial Release

See Also


  • Pm wrote the AbcMusic recipe which inspired this recipe


See discussion at Music-Talk

User notes? : If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.