6 LilyPond is a program to print sheet music. If you have used notation
7 programs before, then the way to use this program might be surprising
8 at first sight. To print music with lilypond, you have to enter
9 musical codes in a file. Then you run LilyPond on the file, and the
10 music is produced without any further intervention. For example,
13 @lilypond[fragment,verbatim, relative 1, intertext="produces this
16 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
19 @cindex encoding music
21 Encoding music using letters and digits may appear strange,
22 intimidating or even clumsy at first. Nevertheless, when you take the
23 effort to learn the codes and the program you will find that it is
24 easier than it seems. Entering music can be done quickly, and you
25 never have to remember how you made the program do something
26 complicated: it is all in the input code, and you only have to read
27 the file to see how it works. Moreover, when you use LilyPond, you are
28 rewarded with very nicely looking output.
30 In this chapter, we will explain the reasoning behind this unusual
31 design, and how this approach affects you as a user.
36 * Music representation::
38 * Example applications::
42 @node Batch processing
43 @section Batch processing
49 When we started developing LilyPond, we were still studying at the
50 university. We were interested in music notation, not as publishers
51 or musicians, but as students and scientists. We wanted to figure to
52 what extent formatting sheet music could be automated. Back then GUIs
53 were not as ubiquitous as they are today, and we were immersed in the
54 UNIX operating system, where it is very common to use compilers to
55 achieve computing tasks, so our computerized music engraving
56 experiment took on the form of a compiler.
61 @cindex sharing software
63 You can freely use, modify and redistribute LilyPond. This choice was
64 also motivated by our academic background. In the scientific community
65 it has always been a tradition to share knowledge, also if that
66 knowledge was packaged as software. One of the most visible groups
67 that stimulated this philosophy, was the Free Software Foundation,
68 whose popular GNU project aimed to replace closed and proprietary
69 computing solutions with free (as in ``Libre'') variants. We jumped on
70 that bandwagon, and released LilyPond as free software. That is the
71 reason that you can get LilyPond at no cost and without any strings
77 @section Music engraving
84 Making sheet music may seem trivial at first (``you print 5 lines, and
85 then put in the notes at different heights''), @emph{music engraving},
86 i.e. professional music typography, is in another ballpark. The term
87 `music engraving' derives from the traditional process of music
88 printing. Only a few decades ago, sheet music was made by cutting and
89 stamping the music into zinc or pewter plates, mirrored. The plate
90 would be inked, and the depressions caused by the cutting and stamping
91 would hold ink. A positive image was formed by pressing paper to the
92 plate. Stamping and cutting was completely done by hand. Making
93 corrections was cumbersome, so engraving had to be done correctly in
94 one go. As you can imagine this was a highly specialized skill, much
95 more so than the traditional process of printing books.
98 In the traditional German craftsmanship six years of full-time
99 training, more than any other craft, were required before a student
100 could call himself a master of the art. After that many more years of
101 practical experience were needed to become an established music
102 engraver. Even today, with the use of high-speed computers and
103 advanced software, music requires lots of manual fine tuning before it
104 acceptable to be published.
106 When we wanted to write a computer program to do create music
107 typography, we encountered the first problem: there were no sets of
108 musical symbols available: either they were not available freely, or
109 they did not look well to our taste. Not let down, we decided to try
110 font design ourselves. We created a font of musical symbols, relying
111 on nice printouts of hand-engraved music. The experience helped
112 develop a typographical taste, and it made us appreciate subtle design
113 details. Without that experience, we would not have realized how ugly
114 the fonts were that we admired at first.
118 #(define magfact 3.0)
119 \score { \notes { as'2 r4 }
124 AccidentalPlacement \override #'right-padding = #3.0
125 StaffSymbol \override #'transparent = ##t
126 Clef \override #'transparent = ##t
127 TimeSignature \override #'transparent = ##t
128 Accidental \override #'font-magnification = #magfact
129 Rest \override #'font-magnification = #magfact
130 NoteHead \override #'font-magnification = #magfact
131 Stem \override #'transparent = ##t
135 @cindex musical symbols
140 The figure above shows a few notable glyphs. For example, the
141 half-notehead is not elliptic but slightly diamond shaped. The
142 vertical stem of a flat symbol should be slightly brushed,
143 i.e. becoming wider at the top. Fine endings, such as the one on the
144 bottom of the quarter rest, should not end in sharp points, but rather
145 in rounded shapes. Taken together, the blackness of the font must be
146 carefully tuned together with the thickness of lines, beams and slurs
147 to give a strong yet balanced overall impression.
149 Producing a strong and balanced look is the real challenge of music
150 engraving. It is a recurring theme with many variations. In spacing,
151 the balance is in a distribution that reflects the character of the
152 music. The spacing should not lead to unnatural clusters of black and
153 big gaps with white space. The distances between notes should reflect
154 the durations between notes, but adhering with mathematical precision
155 to the duration will lead to a poor result. Shown here is an example
156 of a motive, printed twice. It is printed using both exact,
157 mathematical spacing, and with some corrections. Can you spot which is
161 @cindex optical spacing
164 \property Staff.NoteSpacing \set #'stem-spacing-correction
167 \stemDown b'4 e''4 a'4 e''4| \stemBoth
168 \property Staff.NoteSpacing \override #'stem-spacing-correction
170 \property Staff.StaffSpacing \override #'stem-spacing-correction
173 \stemDown b'4 e''4 a'4 e''4|
175 \paper { raggedright = ##t } }
178 @cindex regular rhythms
179 @cindex regular spacing
181 The fragment that was printed uses only quarter notes: notes that are
182 played in a constant rhythm. The spacing should reflect
183 that. Unfortunately, the eye deceives us a little: the eye not only
184 notices the distance between note heads, but also between consecutive
185 stems. The notes of a up-stem/down-stem combination should be put
186 farther apart, and the notes of a down-up combination should be put
187 closer together, all depending on the combined vertical positions of
188 the notes. The first two measures are printed with this correction,
189 the last two measures without. The notes in the last two measures form
190 downstem/upstems clumps of notes.
192 We hope that these examples show that music typography is a subtle
193 business, and that it requires skill and knowledge to produce good
194 engraving. It was our challenge to see if we could put such knowledge
195 into a computer program.
198 @node Music representation
199 @section Music representation
202 One of the big questions when making programs, is what kind of input
203 the program should expect. Many music notation programs offer a
204 graphical interface that shows notation, and allow you to enter the
205 music by placing notes on a staff. From our point of view, this design
206 is a form of cheating. After all, the core message of a piece of music
207 notation simply is the music itself. If you start by offering notation
208 to the user, you have already skipped one conversion, even if it is
209 implicit. If we want to generate music notation from something else,
210 then the obvious candidate for the source is the music itself.
212 On paper this theory sounds very good. In practice, it opens a can of
213 worms. What really @emph{is} music? Many philosophical treatises must
214 have been written on the subject. Instead of losing ourselves in
215 philosophical arguments over the essence of music, we have reversed
216 the question to yield a more practical approach. Our assumption is
217 that the printed score contains all of the music of piece. We build a
218 program that uses some input format to produce such a score. Over the
219 course of time, the program evolves. While this happens, we can remove
220 more and more elements of the input format: as the program improves,
221 it can fill in irrelevant details of the input by itself. At some
222 (hypothetical) point, the program is finished: there is no possibility
223 to remove any more elements from the syntax. What we have left is by
224 definition exactly the musical meaning of the score.
226 There are also more practical concerns. Our users have to key in the
227 music into the file directly, so the input format should have a
228 friendly syntax. As programmers and scientists, we want a
229 clean formal definition. After all, producing music notation is a
230 difficult problem, and in the scientific world, problems can only be
231 solved if they are well-specified. Moreover, formally defined formats
232 are easier to write programs for.
234 These ideas shaped our music representation: it is a compact format
235 that can easily be typed by hand. It complex musical constructs from
236 simple entities like notes and rests, in much the same way that one
237 builds complex formulas from simple expressions such as numbers and
238 mathematical operators.
240 @node Example applications
241 @section Example applications
243 As programmers and hedonists enjoy beautifully written code, and
244 beautifully printed music, but this program can applied to
245 do useful things. In this section, we show a few small examples of
248 [todo: show examples]
251 The following example combines some more exotic uses of notation
253 @lilypondfile{screech-boink.ly}
257 @node About this manual
258 @section About this manual
260 The manual is divided into the following chapters
263 Gives a gentle introduction into typesetting music.
264 Start here if you have never used lilypond before.
265 @item Reference manual
266 Here, each aspect of typesetting music is discussed.
268 This chapter discusses how it works from the inside, and how you can
271 This chapter explains how to runn LilyPond and its helper programs.
274 Once you are experienced with, you can simply use the manual as
275 reference: there is an extensive index@footnote{If you are looking for
276 something, and you cannot find it by using the index, that is
277 considered a bug. In that case, please file a bug report}, but the
278 document is also available in
283 @uref{One Big Page,../lilypond.html}
285 which is is available for text search using your browser's search
287 @cindex search in manual
288 @cindex using the manual
291 If you are familiar with music notation, and music terminology
292 (especially if you are a foreigner), then it is advisable to consult
293 the glossary as well. This documents explains many terms, and includes
294 translations to various languages. It is a
296 @uref{separate document,../glossary.html}
299 separate document, and can be printed as well.
304 @cindex foreign languages
308 This manual is not complete without a number of other documents. They
309 are not available in print, but should be included with the
310 documentation package for your platform
314 Generated internal documentation.
316 available @uref{here,../lilypond-internals/lilypond-internals.html}
319 Almost all formatting functionality that is used internally, is
320 available directly to the user. For example, all variables that
321 control thicknesses, distances, etc, can be changed from input
322 files. There are a huge number of formatting options, and it would be
323 impossible to describe them all in a hand-written manual. The
324 generated internal documentation is a heavily crosslinked HTML
325 document, produced directly from the formatting definitions used. It
326 the nit-gritty details of each and every LilyPond class, object and
329 Each section of the reference manual has a @b{See also}
330 subsection, with links (in the HTML document, at least) to the
331 generated documentation.
336 available @uref{here,../../../input/templates/out-www/collated-files.html}
339 When you have gone through the tutorial, you theoretically should be
340 able to start writing input files. However, this turns out to be a
341 little intimidating. To give you a headstart, we have collected a
342 number of often-used formats in example files. You can take one of
343 these example files, and add notes in the appropriate places to
347 Various input examples
349 available @uref{here,../../../input/test/out-www/collated-files.html}
353 These small files show various applications of lilypond, and are
354 available as a big HTML document, with pictures and explanatory texts
361 available @uref{here,../../../input/regression/out-www/collated-files.html}
364 We strive to test each feature in a collection of input snippets. This
365 is primarily to help us debug the program, but it can be instructive
366 to see how we excercise the program. The format is like the input
371 @cindex adjusting output
374 @cindex lilypond-internals
375 @cindex internal documentation
377 @cindex extending lilypond