blob: 1daa70b861cee4474c742f422e4e49109eca8dba (
plain) (
blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
|
Music Filter
============
The AsciiDoc distribution includes a Music Block filter that
translates music in http://lilypond.org/[LilyPond] or
http://abcnotation.org.uk/[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
.Music Block containing ABC notation
=====================================================================
This Music Block:
[listing]
.....................................................................
["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:
["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):|
---------------------------------------------------------------------
=====================================================================
.Music Block containing LilyPond notation
=====================================================================
This example contains LilyPond musical markup.
[listing]
.....................................................................
[music]
---------------------------------------------------------------------
\version "2.14.2"
\paper {
ragged-right = ##t
}
{
\time 3/4
\clef bass
c2 e4 g2. f4 e d c2 r4
}
---------------------------------------------------------------------
.....................................................................
Renders:
[music]
---------------------------------------------------------------------
\version "2.14.2"
\paper {
ragged-right = ##t
}
{
\time 3/4
\clef bass
c2 e4 g2. f4 e d c2 r4
}
---------------------------------------------------------------------
=====================================================================
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
----------------
- The Music filter is invoked by setting the Listing block or
Paragraph style (the first positional block attribute) to 'music'.
- The second positional attribute (named 'target' is optional, it sets
the name of the generated PNG image file. If this is not supplied a
file name like `{docname}__{target-number}.png` is synthesised
(where `{docname}` is the document file name and `{target-number}`
is an integer number.
- The third positional attribute ('format') specifies the music input
format: either 'abc' for ABC or 'ly' for LilyPond. If the format is
omitted ABC notation is assumed unless the text starts with a
backslash character, in which case the format is set to 'ly'.
Because the LaTeX images are rendered using the image block templates
you can also use the optional named image block attributes (see
link:userguide.html#X55[Image macro attributes] in the AsciiDoc User
Guide).
Limitations
-----------
- The `asciidoc(1)` input and output files cannot both be `-` (stdin
and stdout), either the input or output files (or both) must be a
named file.
Installation
------------
In addition to AsciiDoc you will need to have installed:
- http://lilypond.org/web/[LilyPond] (most Linux distributions include
this package).
- http://www.imagemagick.org[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).
|
