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: in order to print music you have to enter musical
9 codes in a file. Then you run the program on the file, and the music
10 is produced without any further intervention. For example, something
14 @lilypond[fragment,verbatim, relative 1, intertext="produces this:
17 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
20 @cindex encoding music
22 Encoding music using letters and digits may appear strange,
23 intimidating or even clumsy at first. Nevertheless, when you take the
24 effort to learn the codes and the program you will find that it is
25 easier than it seems. Entering music can be done quickly, and you
26 never have to remember how you made the program do something
27 complicated: it is all in the input code, and you only have to read
28 the file to see how it works. Moreover, you are rewarded with very
29 nicely looking output.
31 In this chapter, we will explain the reasoning behind this unusual
32 design, and how this approach affects you as a user.
37 * 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 programmers and scientists. We wanted to figure
52 to what extent formatting sheet music could be automated. Back then
53 GUIs were not as ubiquitous as they are today, and we were immersed in
54 the 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
141 The figure above shows a few notable glyphs. For example, the
142 vertical stem of a flat symbol should be slightly brushed,
143 i.e. becoming wider at the top. the half-notehead is not elliptic but
144 slightly diamond shaped. Fine endings, such as the one on the bottom
145 of the quarter rest, should not end in sharp points, but rather in
146 rounded shapes. Taken together, the blackness of the font must be
147 carefully tuned together with the thickness of lines, beams and slurs
148 to give a strong yet balanced overall impression.
150 Producing a strong and balanced look is the real challenge of music
151 engraving. It is a recurring theme with many variations. In spacing,
152 the balance is in a distribution that reflects the character of the
153 music. The spacing should not lead to unnatural clusters of black and
154 big gaps with white space. The distances between notes should reflect
155 the durations between notes, but adhering with mathematical precision
156 to the duration will lead to a poor result. Shown here is an example
157 of a motive, printed twice. It is printed using both exact
158 mathematical spacing, and with some corrections. Can you spot which is
162 @cindex optical spacing
165 \property Staff.NoteSpacing \set #'stem-spacing-correction
168 \stemDown b'4 e''4 a'4 e''4| \stemBoth
169 \property Staff.NoteSpacing \override #'stem-spacing-correction
171 \property Staff.StaffSpacing \override #'stem-spacing-correction
174 \stemDown b'4 e''4 a'4 e''4|
176 \paper { raggedright = ##t } }
179 @cindex regular rhythms
180 @cindex regular spacing
182 The fragment that was printed uses only quarter notes: notes that are
183 played in a constant rhythm. The spacing should reflect
184 that. Unfortunately, the eye deceives us a little: the eye not only
185 notices the distance between note heads, but also between consecutive
186 stems. As a result, the notes of a up-stem/down-stem combination
187 should be put farther apart, and the notes of a down-up combination
188 should be put closer together, all depending on the combined vertical
189 positions of the notes. The first two measures are printed with this
190 correction, the last two measures without. The notes in the last two
191 measures form downstem/upstems clumps of notes.
193 We hope that these examples show that music typography is a subtle
194 business, and that it requires skill and knowledge to produce good
195 engraving. It was our challenge to see if we could put such knowledge
196 into a computer program.
199 @node Music representation
200 @section Music representation
203 One of the big questions when making programs, is what kind of input
204 the program should expect. Many music notation programs offer a
205 graphical interface that shows notation, and allow you to enter the
206 music by placing notes on a staff. From our point of view, this design
207 is a form of cheating. After all, the core message of a piece of music
208 notation simply is the music itself. If you start by offering notation
209 to the user, you have already skipped one conversion, even if it is
210 implicit. If we want to generate music notation from something else,
211 then the obvious candidate for the source is the music itself.
213 On paper this theory sounds very good. In practice, it opens a can of
214 worms. What really @emph{is} music? Many philosophical treatises must
215 have been written on the subject. Instead of losing ourselves in
216 philosophical arguments over the essence of music, we have reversed
217 the question to yield a more practical approach. Our assumption is
218 that the printed score contains all of the music of piece. We build a
219 program that uses some input format to produce such a score. Over the
220 course of time, the program evolves. While this happens, we can remove
221 more and more elements of the input format: as the program improves,
222 it can fill in irrelevant details of the input by itself. At some
223 (hypothetical) point, the program is finished: there is no possibility
224 to remove any more elements from the syntax. What we have left is by
225 definition exactly the musical meaning of the score.
227 There are also more practical concerns. Our users have to key in the
228 music into the file directly, so the input format should have a
229 friendly syntax. As programmers and scientists, we want a
230 clean formal definition. After all, producing music notation is a
231 difficult problem, and in the scientific world, problems can only be
232 solved if they are well-specified. Moreover, formally defined formats
233 are easier to write programs for.
235 These ideas shaped our music representation: it is a compact format
236 that can easily be typed by hand. It complex musical constructs from
237 simple entities like notes and rests, in much the same way that one
238 builds complex formulas from simple expressions such as numbers and
239 mathematical operators.
241 @node Example applications
242 @section Example applications
244 As programmers and hedonists we enjoy beauty in code, and code that
245 produces beautiful typeset music, but nevertheless this program can
246 applied to do useful things. In this section, we show a few small
247 examples of what is possible.
249 The simplest application, is printing just notes.
251 @lilypond[relative=1]
252 \time 2/4 c4 c g'4 g a4 a g2
255 To these notes, chord names and lyrics may be added
257 @lilypond[raggedright]
259 \context ChordNames \chords { c2 c f2 c }
260 \notes \relative c' { \time 2/4 c4 c g'4 g a4 a g2 }
261 \context Lyrics \lyrics { twin kle twin kle lit tle star } > }
265 [TODO: need piano and tab example]
267 The following example combines some more exotic uses of notation
269 @lilypondfile{screech-boink.ly}
273 @node About this manual
274 @section About this manual
276 The manual is divided into the following chapters
278 @item The @emph{tutorial}
279 (@ref{Tutorial}) gives a gentle introduction into typesetting music.
280 First time users should start here.
281 @item The @emph{notation manual} (@ref{Notation manual}),
282 is a user manual that discusses topics grouped by notation construct.
283 @item The @emph{technical manual} (@ref{Advanced topics})
284 discusses the general design of the program, and how to extend the
287 on @emph{Invoking} (@ref{Invoking LilyPond}) explains how to run LilyPond and its helper
291 Once you are experienced, you can simply use the manual as reference:
292 there is an extensive index@footnote{If you are looking for something,
293 and you cannot find it by using the index, that is considered a bug.
294 In that case, please file a bug report}, but the document is also
300 @uref{One Big Page,../lilypond.html}
302 which is is available for text search using your browser's search
304 @cindex search in manual
305 @cindex using the manual
308 If you are familiar with music notation, and music terminology
309 (especially if you are a foreigner), then it is advisable to consult
310 the glossary as well. This documents explains many terms, and includes
311 translations to various languages. It is a
313 @uref{../glossary.html,separate document}
316 separate document, and can be printed as well.
321 @cindex foreign languages
325 This manual is not complete without a number of other documents. They
326 are not available in print, but should be included with the
327 documentation package for your platform
331 Generated internal documentation.
333 available @uref{../lilypond-internals/lilypond-internals.html,here}
336 Almost all formatting functionality that is used internally, is
337 available directly to the user. For example, all variables that
338 control thicknesses, distances, etc, can be changed in input
339 files. There are a huge number of formatting options, and it would be
340 impossible to describe them all in a hand-written manual. The
341 generated internal documentation is a heavily crosslinked HTML
342 document, produced directly from the formatting definitions used. It
343 documents the nit-gritty details of each and every LilyPond class, object and
346 Each section of the reference manual has a @b{See also}
347 subsection, with links (in the HTML document, at least) to the
348 generated documentation.
353 (available @uref{../../../input/templates/out-www/collated-files.html,here})
356 When you have gone through the tutorial, you theoretically should be
357 able to start writing input files. However, this turns out to be a
358 little intimidating. To give you a headstart, we have collected a
359 number of often-used formats in example files. You can take one of
360 these example files, and add notes in the appropriate places to
364 Various input examples
366 available @uref{../../../input/test/out-www/collated-files.html,here}
370 These small files show various applications of lilypond, and are
371 available as a big HTML document, with pictures and explanatory texts
378 available @uref{../../../input/regression/out-www/collated-files.html,here}
381 We strive to test each feature in one test file. This collection of is
382 primarily to help us debug problems, but it can be instructive to see
383 how we excercise the program. The format is like the input examples.
387 The location of the documentation files that are mentioned here can
388 vary from system to system. Throughout this manual, we refer to input
389 files relative to the top-directory of the source archive. For
390 example, @file{input/test/bla.ly} may refer to the file
391 @file{lilypond-1.7.19/input/test/bla.ly}. On binary packages for the
392 Unix platform, these can typically be found somewhere below
393 @file{/usr/share/doc/lilypond/}. Initialization files, for example
394 @file{scm/lily.scm}, or @file{ly/engraver-init.ly}, are usually found
395 in the directory @file{/usr/share/lilypond/}.
397 @cindex adjusting output
400 @cindex lilypond-internals
401 @cindex internal documentation
403 @cindex extending lilypond