1 | Music Filter |
---|
2 | ============ |
---|
3 | |
---|
4 | The AsciiDoc distribution includes a Music Block filter that |
---|
5 | translates music in http://lilypond.org/[LilyPond] or |
---|
6 | http://abcnotation.org.uk/[ABC] notation to standard classical |
---|
7 | notation in the form of a trimmed PNG image which is automatically |
---|
8 | inserted into the AsciiDoc output document (see the examples below). |
---|
9 | |
---|
10 | Actually the filter (`./filters/music/music2png.py`) can be used outside |
---|
11 | AsciiDoc to convert LilyPond or ABC music files to PNG images. |
---|
12 | Execute the following command to see how to use it: |
---|
13 | |
---|
14 | $ ./filters/music/music2png.py --help |
---|
15 | |
---|
16 | .Music Block containing ABC notation |
---|
17 | ===================================================================== |
---|
18 | |
---|
19 | This Music Block: |
---|
20 | |
---|
21 | [listing] |
---|
22 | ..................................................................... |
---|
23 | ["music","music1.png",scaledwidth="100%"] |
---|
24 | --------------------------------------------------------------------- |
---|
25 | T:The Butterfly |
---|
26 | R:slip jig |
---|
27 | C:Tommy Potts |
---|
28 | H:Fiddle player Tommy Potts made this tune from two older slip jigs, |
---|
29 | H:one of which is called "Skin the Peelers" in Roche's collection. |
---|
30 | H:This version by Peter Cooper. |
---|
31 | D:Bothy Band: 1975. |
---|
32 | M:9/8 |
---|
33 | K:Em |
---|
34 | vB2(E G2)(E F3)|B2(E G2)(E F)ED|vB2(E G2)(E F3)|(B2d) d2(uB A)FD:| |
---|
35 | |:(vB2c) (e2f) g3|(uB2d) (g2e) (dBA)|(B2c) (e2f) g2(ua|b2a) (g2e) (dBA):| |
---|
36 | |:~B3 (B2A) G2A|~B3 BA(uB d)BA|~B3 (B2A) G2(A|B2d) (g2e) (dBA):| |
---|
37 | --------------------------------------------------------------------- |
---|
38 | ..................................................................... |
---|
39 | |
---|
40 | Renders: |
---|
41 | |
---|
42 | ["music","music1.png",scaledwidth="100%"] |
---|
43 | --------------------------------------------------------------------- |
---|
44 | T:The Butterfly |
---|
45 | R:slip jig |
---|
46 | C:Tommy Potts |
---|
47 | H:Fiddle player Tommy Potts made this tune from two older slip jigs, |
---|
48 | H:one of which is called "Skin the Peelers" in Roche's collection. |
---|
49 | H:This version by Peter Cooper. |
---|
50 | D:Bothy Band: 1975. |
---|
51 | M:9/8 |
---|
52 | K:Em |
---|
53 | vB2(E G2)(E F3)|B2(E G2)(E F)ED|vB2(E G2)(E F3)|(B2d) d2(uB A)FD:| |
---|
54 | |:(vB2c) (e2f) g3|(uB2d) (g2e) (dBA)|(B2c) (e2f) g2(ua|b2a) (g2e) (dBA):| |
---|
55 | |:~B3 (B2A) G2A|~B3 BA(uB d)BA|~B3 (B2A) G2(A|B2d) (g2e) (dBA):| |
---|
56 | --------------------------------------------------------------------- |
---|
57 | ===================================================================== |
---|
58 | |
---|
59 | |
---|
60 | .Music Block containing LilyPond notation |
---|
61 | ===================================================================== |
---|
62 | This example contains LilyPond musical markup. |
---|
63 | |
---|
64 | [listing] |
---|
65 | ..................................................................... |
---|
66 | [music] |
---|
67 | --------------------------------------------------------------------- |
---|
68 | \version "2.14.2" |
---|
69 | \paper { |
---|
70 | ragged-right = ##t |
---|
71 | } |
---|
72 | { |
---|
73 | \time 3/4 |
---|
74 | \clef bass |
---|
75 | c2 e4 g2. f4 e d c2 r4 |
---|
76 | } |
---|
77 | --------------------------------------------------------------------- |
---|
78 | ..................................................................... |
---|
79 | |
---|
80 | Renders: |
---|
81 | |
---|
82 | [music] |
---|
83 | --------------------------------------------------------------------- |
---|
84 | \version "2.14.2" |
---|
85 | \paper { |
---|
86 | ragged-right = ##t |
---|
87 | } |
---|
88 | { |
---|
89 | \time 3/4 |
---|
90 | \clef bass |
---|
91 | c2 e4 g2. f4 e d c2 r4 |
---|
92 | } |
---|
93 | --------------------------------------------------------------------- |
---|
94 | ===================================================================== |
---|
95 | |
---|
96 | NOTE: If you get an error processing the above example it may be that |
---|
97 | it is not compatible with your version of LilyPond. Use the LilyPond |
---|
98 | `convert-ly(1)` utility to update the source to the version that you |
---|
99 | are using. |
---|
100 | |
---|
101 | |
---|
102 | Using the Filter |
---|
103 | ---------------- |
---|
104 | - The Music filter is invoked by setting the Listing block or |
---|
105 | Paragraph style (the first positional block attribute) to 'music'. |
---|
106 | - The second positional attribute (named 'target' is optional, it sets |
---|
107 | the name of the generated PNG image file. If this is not supplied a |
---|
108 | file name like `{docname}__{target-number}.png` is synthesised |
---|
109 | (where `{docname}` is the document file name and `{target-number}` |
---|
110 | is an integer number. |
---|
111 | - The third positional attribute ('format') specifies the music input |
---|
112 | format: either 'abc' for ABC or 'ly' for LilyPond. If the format is |
---|
113 | omitted ABC notation is assumed unless the text starts with a |
---|
114 | backslash character, in which case the format is set to 'ly'. |
---|
115 | |
---|
116 | Because the LaTeX images are rendered using the image block templates |
---|
117 | you can also use the optional named image block attributes (see |
---|
118 | link:userguide.html#X55[Image macro attributes] in the AsciiDoc User |
---|
119 | Guide). |
---|
120 | |
---|
121 | |
---|
122 | Limitations |
---|
123 | ----------- |
---|
124 | - The `asciidoc(1)` input and output files cannot both be `-` (stdin |
---|
125 | and stdout), either the input or output files (or both) must be a |
---|
126 | named file. |
---|
127 | |
---|
128 | |
---|
129 | Installation |
---|
130 | ------------ |
---|
131 | In addition to AsciiDoc you will need to have installed: |
---|
132 | |
---|
133 | - http://lilypond.org/web/[LilyPond] (most Linux distributions include |
---|
134 | this package). |
---|
135 | - http://www.imagemagick.org[ImageMagick] (most Linux distributions |
---|
136 | include this package). |
---|
137 | |
---|
138 | Test the music filter it by converting the test file to HTML with AsciiDoc: |
---|
139 | |
---|
140 | $ asciidoc -v ./filters/music/music-filter-test.txt |
---|
141 | $ firefox ./filters/music/music-filter-test.html & |
---|
142 | |
---|
143 | The filter was developed and tested on Xubuntu Linux using LilyPond |
---|
144 | 2.10.5 and ImageMagick 6.2.4. |
---|
145 | |
---|
146 | NOTE: The filter does not work with LilyPond 2.2.6 because it did not |
---|
147 | generate the requested output file name correctly (2.6.3 does not have |
---|
148 | a problem). |
---|