AsciiDoc
Text based document generation
»Home
»Man Page
»User Guide
»Installation
»FAQ
»a2x
»API
»Cheatsheet
»Tests
»ChangeLog
»Support

The AsciiDoc distribution includes a Music Block filter that translates music in LilyPond or ABC notation to standard classical notation in the form of a trimmed PNG image which is automatically inserted into the AsciiDoc output document (see the examples below).

Actually the filter (./filters/music/music2png.py) can be used outside AsciiDoc to convert LilyPond or ABC music files to PNG images. Execute the following command to see how to use it:

$ ./filters/music/music2png.py --help

The Music Filter can be used as a model for filters that convert a block of text into a file that is linked or embedded into the AsciiDoc output document.

Example 1: Music Block containing ABC notation

This Music Block:

 ["music","music1.png",scaledwidth="100%"]
 ---------------------------------------------------------------------
 T:The Butterfly
 R:slip jig
 C:Tommy Potts
 H:Fiddle player Tommy Potts made this tune from two older slip jigs,
 H:one of which is called "Skin the Peelers" in Roche's collection.
 H:This version by Peter Cooper.
 D:Bothy Band: 1975.
 M:9/8
 K:Em
 vB2(E G2)(E F3)|B2(E G2)(E F)ED|vB2(E G2)(E F3)|(B2d) d2(uB A)FD:|
 |:(vB2c) (e2f) g3|(uB2d) (g2e) (dBA)|(B2c) (e2f) g2(ua|b2a) (g2e) (dBA):|
 |:~B3 (B2A) G2A|~B3 BA(uB d)BA|~B3 (B2A) G2(A|B2d) (g2e) (dBA):|
 ---------------------------------------------------------------------

Renders:

music1.png
Example 2: Music Block containing LilyPond notation

This example contains LilyPond musical markup, it uses the link attribute so you can click on the music image to display the source notation. The music2.ly source file is automatically created and retained by the music2png.py filter when the -m option is used.

 ["music", "music2.png", "ly", link="music2.ly"]
 ---------------------------------------------------------------------
 \version "2.10.0"
 \paper {
   ragged-right = ##t
 }
 {
   \time 3/4
   \clef bass
   c2 e4 g2. f4 e d c2 r4
 }
 ---------------------------------------------------------------------

Renders:

Note If you get an error processing the above example it may be that it is not compatible with your version of LilyPond. Use the LilyPond convert-ly(1) utility to update the source to the version that you are using.

Using the Filter

Insert a delimited Music Block containing valid ABC notation into your AsciiDoc document:

  • The Music Block delimiter is the word music followed by four or more tilde characters.

  • The Music Block attribute list must contain a file name for the PNG output image file followed by the input format (either abc for ABC or ly for LilyPond). If the format is omitted ABC notation is assumed.

  • The filter invokes music2png with the -m option so that music images will only be regenerated if the block content has changed.

  • The optional named block attributes link, width and height are also available (see Image macro attributes in the AsciiDoc User Guide).

Limitations

  • The asciidoc(1) output file cannot be - (stdout), you must output to a named file.

  • If the music image file is linked to the output document then the image file name in the Music Block attribute list should be a relative path name relative to the AsciiDoc output file.

Installation

In addition to AsciiDoc you will need to have installed:

  • LilyPond (most Linux distributions include this package).

  • ImageMagick (most Linux distributions include this package).

Test the music filter it by converting the test file to HTML with AsciiDoc:

$ asciidoc -v ./filters/music/music-filter-test.txt
$ firefox ./filters/music/music-filter-test.html &

The filter was developed and tested on Xubuntu Linux using LilyPond 2.10.5 and ImageMagick 6.2.4.

Note The filter does not work with LilyPond 2.2.6 because it did not generate the requested output file name correctly (2.6.3 does not have a problem).