7 There are a lot of programs that let you print sheet music with a
8 computer. Unfortunately, most of them do not do good job. Most
9 computer printouts have a bland, mechanical look, and are unpleasant
10 to play from. If you agree with us on that, then you will like
11 LilyPond: we have tried to capture the original look of hand-engraved
12 music in a program: we have tuned our algorithms, font-designs, and
13 program settings to make the output match that of the old editions
14 that we love to see and love to play from.
18 * Music notation and engraving::
19 * Notation and engraving in LilyPond::
20 * Typography and program architecture::
21 * Music representation::
22 * Example applications::
26 @node Music notation and engraving
27 @section Music notation and engraving
34 @c eerste zin beetje deur in huis
35 Making sheet music may seem trivial, ``you print 5 lines, and then put
36 in the notes at different heights'', but as you learn more of it, the
37 opposite turns out to be true. One has to master two difficult
38 tasks. First, one has to master music notation: the science of knowing
39 which symbols to use when what. Second, one has to master music
40 engraving: the art of placing symbols such that the result looks
43 Common music notation has its roots in the medieval time. In this
44 time, monks started to write down hints that indicated how their
45 sacred music was sung. These hints, neumes, gradually became simpler,
46 and at some point became the note heads. Lines were added to the
47 neumes, to indicate a reference pitch, which later became the staff.
48 Over many centuries, improvements and extensions were added, while
49 other concepts disappeared. For example, the neume notation did not
50 have an explicit notion of rhythm, but it did have @emph{custodes},
51 symbols at the end of the line to indicate the starting pitch of the
52 next line. Mensural notation, a notation where each note head takes a
53 fixed amount of time, came into being together with the rise of
54 counterpoint in the early renaissance. The graphic language of
55 notation is still under development; the innovations of contemporary
56 music require still newer and more complex notations.
58 The term music engraving derives from the traditional process of music
59 printing. Only a few decades ago, sheet music was made by cutting and
60 stamping the music into zinc or pewter plates, in mirror image. The plate
61 would be inked, and the depressions caused by the cutting and stamping
62 would hold ink. An image was formed by pressing paper to the
63 plate. The stamping and cutting was completely done by hand. Making
64 corrections was cumbersome, so engraving had to be done correctly in
65 one go. Of course, this was a highly specialized skill, much more so
66 than the traditional process of printing books.
69 In the traditional German system of craftsmanship six years of full-time
70 training, more than any other craft, were required before a student
71 could call himself a master of the art. After that many more years of
72 practical experience were needed to become an established music
73 engraver. Even today, with the use of high-speed computers and
74 advanced software, music requires lots of manual fine tuning before it
75 is acceptable for publication.
77 Sheet music is performance material: everything is done to aid the
78 musician in letting him perform better. Music often is far away from
79 its reader---it might be on a music stand. To make it clearly
80 readable, traditionally printed sheet music always uses bold symbols,
81 on heavy staff lines, and is printed on large sheets of paper. This
82 ``strong'' look is also present in the horizontal spacing. To
83 minimize the number of page breaks, (hand-engraved) sheet music is
84 spaced very tightly. Yet, by a careful distribution of white space,
85 the feeling of balance is retained, and a clutter of symbols is
89 @node Notation and engraving in LilyPond
90 @section Notation and engraving in LilyPond
92 Common music notation encompasses such a wide scope of music, and
93 therefore inherently is complex: there are many rules, and for every
94 rule there are exceptional situations where they do not apply. The
95 result is that LilyPond cannot support each and every form of notation
96 in existence. Rather, we focus on a specific style and idiom: we take
97 inspiration from late-romantic music printed at the beginning of the
98 20th century. Most of the contemporary music after that, and most of
99 the music going back to 17th century can be written in this
100 idiom. That is not a fundamental limit, though. There is support for
101 some modern notation like clusters, and older notation, such as white
102 mensural and gregorian notation, is being worked on.
104 We have used these observations in designing LilyPond. The images
105 below show the flat symbol. On the left, a scan from a Henle edition,
106 which was made by a computer, and in the center is the flat from a
107 hand engraved B@"{a}renreiter edition of the same music. The left scan
108 illustrates typical flaws of computer print: the symbol is much
109 lighter, the staff lines are thinner, and the glyph has a straight
110 layout with sharp corners. By contrast, the B@"{a}renreiter has a bold
111 and almost voluptuous rounded look. Our flat symbol is designed
112 after, among others, this one. It is tuned it to harmonize with the
113 thickness of our staff lines, which are also much thicker than Henle's
116 @multitable @columnfractions .1 .3 .3 .3
119 @image{henle-flat-bw,4cm}
122 <img src=henle-flat-bw.png>
127 @image{baer-flat-bw,4cm}
130 <img src=baer-flat-bw.png>
135 @image{lily-flat-bw,4cm}
138 <img src=lily-flat-bw.png>
144 B@"{a}renreiter (1950)
146 LilyPond Feta font (2003)
151 @cindex musical symbols
156 In spacing, the distribution of space should reflect the durations
157 between notes. However, adhering with mathematical precision to the
158 duration will lead to a poor result. Shown here is an example of a
159 motive, printed twice. It is printed using exact mathematical spacing,
160 and with some corrections. Can you spot which fragment is which?
162 @cindex optical spacing
165 \property Staff.NoteSpacing \set #'stem-spacing-correction
168 \stemDown b'4 e''4 a'4 e''4| \stemBoth
170 \property Staff.NoteSpacing \override #'stem-spacing-correction
172 \property Staff.StaffSpacing \override #'stem-spacing-correction
175 \stemDown b'4 e''4 a'4 e''4|
177 \paper { raggedright = ##t } }
180 @cindex regular rhythms
181 @cindex regular spacing
183 The fragment only uses quarter notes: notes that are played in a
184 constant rhythm. The spacing should reflect that. Unfortunately, the
185 eye deceives us a little: not only does it notice the distance between
186 note heads, it also takes into account the distance between
187 consecutive stems. As a result, the notes of an up-stem/down-stem
188 combination should be put farther apart, and the notes of a down-up
189 combination should be put closer together, all depending on the
190 combined vertical positions of the notes. The first two measures are
191 printed with this correction, the last two measures without. The notes
192 in the last two measures form down-stem/up-stems clumps of notes.
194 @node Typography and program architecture
195 @section Typography and program architecture
197 Producing good engraving requires skill and knowledge. As the
198 previous examples show, there is a lot of subtlety involved in music
199 engraving, and unfortunately, only a small fraction of these details
200 are documented. Master engraver must learn all these details from
201 experience or from other engravers, which is why it takes so long to
202 become a master. As an engraver gets older and wiser, he will be able
203 to produce better and more complex pieces. A similar situation is
204 present when putting typographical knowledge into a computer program.
205 It is not possible to come up with a definitive solution for a problem
206 at the first try. Instead, we start out with simple solution that
207 might cover 75% of the cases, and gradually refine that solution over
208 the course of months or years, so 90 or 95 % of the cases are
211 This has an important implication for the design of the program: at
212 any time, almost every piece of formatting code must be considered as
213 temporary. When the need arises, it is to be replaced a solution that
214 will cover even more cases. is A ``plug-in'' architecture is a clean
215 way to accomplish this. This is an architecture where new pieces of
216 code can be inserted in the program dynamically. In such a program, a
217 new solution can be developed along-side the existing code. For
218 testing, it is plugged in, but for production use, the old solution is
219 used. The new module can be perfected separately until it is better
220 than the existing solution, at which point it replaces the old one.
222 Until that time, users must have a way to deal with imperfections:
223 these 25%, 10% or 5% of the cases that are not handled
224 automatically. In these cases, a user must be able to override
225 formatting decisions. A way to accomplish this, is to store decisions
226 in generic variables, and let the user manipulate these variables.
227 For example, consider the following fragment of notation.
230 \score { \notes \relative c'' {
234 \paper { raggedright = ##t }
239 The position of the forte symbol is slightly awkward, because it is
240 next to the low note, whereas dynamics should be below notes in
241 general. This may be remedied by inserting extra space between the
242 high note and the `f', as shown in this example
245 \score { \notes \relative c'' {
247 \once\property Voice. DynamicLineSpanner \override #'padding = #4.0
250 \paper { raggedright = ##t }
254 This was achieved with the following input statement.
256 \once \property Voice. DynamicLineSpanner \override #'padding = #4.0
258 It increases the amount of space (@code{padding}) between the note and
259 the dynamic symbol to 4.0 (which is measured in staff space, so 4.0
260 equals the height of a staff). The keyword @code{\once} indicates that
261 this is a tweak: it is only done one time.
263 Both design aspects, a plug-in architecture, and formatting variables,
264 are built on top of GUILE, an interpreter for the programming language
265 Scheme, which is a member of the LISP family. Variables are stored as
266 Scheme objects, and attached to graphical objects such as note heads
267 and stems. The variables are a means to adjust formatting details in
268 individual cases, but they are used in a more general manner.
270 Consider the case of a publisher that is not satisfied with the in the
271 default layout, and wants heavier stems. Normally, they are @code{1.3}
272 times the thickness of staff lines, but suppose that their editions
273 require them to be twice the thickness of the staff lines. The same
274 mechanism can be used to adjust a setting globally. By issuing the
275 following command, the entire piece is now formatted with thicker stems:
277 \property Score.Stem \override #'thickness = #2.0
282 \property Score.Stem \override #'thickness = #2.0
283 \once\property Voice. DynamicLineSpanner \override #'padding = #4.0
286 \paper { raggedright = ##t }
291 In effect, by setting these variables, users can define their own
294 ``Plug-ins'' are also implemented using Scheme. A formatting
295 ``plug-in'' takes the form of a function written in Scheme (or a C++
296 function made available as a Scheme function), and it is also stored
297 in a variable. For example, the placement of the forte symbol in the
298 example above is calculated by the function
299 @code{Side_position_interface::aligned_side}. If we want to replace
300 this function by a more advanced one, we could issue
302 \property Voice.DynamicLineSpanner \override #'Y-offset-callbacks
303 = #`(,gee-whiz-gadget)
307 Now, the formatting process will trigger a call to our new
308 @code{gee-whiz-gadget} function when the position of the f symbol has
311 The full scope of this functionality certainly is intimidating, but
312 there is no need to fear: normally, it is not necessary to define
313 style-sheets or rewrite formatting functions. In fact, LilyPond gets a
314 lot of formatting right automatically, so adjusting individual layout
315 situations is not needed often at all.
318 @node Music representation
319 @section Music representation
322 Our premise is that LilyPond is a system that does music formatting
323 completely automatically. Under this assumption, the output does not
324 have to be touched up. Consequently, an interactive display of the
325 output, where it is possible to reposition notation elements, is
326 superfluous. This implies that the program should be a batch program:
327 the input is entered in a file, which is @emph{compiled}, i.e. then
328 put through the program. The final output is produced as a file ready
329 to view or print. The compiler fills in all the details of the
330 notation, those details should be left out of the input file. In other
331 words, the input should mirror the content as closely as possible. In
332 the case of music notation the content is the music itself, so that is
333 what the input should consist of.
335 On paper this theory sounds very good. In practice, it opens a can of
336 worms. What really @emph{is} music? Many philosophical treatises must
337 have been written on the subject. Instead of losing ourselves in
338 philosophical arguments over the essence of music, we have reversed
339 the question to yield a more practical approach. Our assumption is
340 that the printed score contains all of the music of piece. We build a
341 program that uses some input format to produce such a score. Over the
342 course of time, the program evolves. While this happens, we can remove
343 more and more elements of the input format: as the program improves,
344 it can fill in irrelevant details of the input by itself. At some
345 (hypothetical) point, the program is finished: there is no possibility
346 to remove any more elements from the syntax. What we have left is by
347 definition exactly the musical meaning of the score.
349 There are also more practical concerns. Our users have to key in the
350 music into the file directly, so the input format should have a
351 friendly syntax: a quarter note C is entered as @code{c4}, the code
352 @code{r8.} signifies a dotted eighth rest. Notes and rests form the
353 simplest musical expressions in the input syntax. More complex
354 constructs are produced by combining them into compound
355 structures. This is done s in much the same way that complex
356 mathematical formulas are built from simple expressions such as
357 numbers and operators.
359 In effect, the input format is a language, and the rules of that
360 language can be specified succinctly with a so-called context-free
361 grammar. The grammar formally specificies what types of input form
362 valid `sentences.' Reading such languages, and splitting them into
363 grammatical structures is a problem with standard solutions.
364 Moreover, they make the format easier to understand: a a concise
365 formal definition permits a simple informal description.
367 The user-interface of LilyPond is its syntax. That part is what users
368 see most. As a results, some users think that music representation is
369 a very important or interesting problem. In reality, less than 10% of
370 the source code of the program handles reading and representing the
371 input, and they form the easy bits of the program. In our opinion,
372 producing music notation, and formatting it prettily are the
373 interesting and important parts: they take up most of the bulk of the
374 code, and are the most difficult things to get right.
376 @node Example applications
377 @section Example applications
379 We have written LilyPond as an experiment of how to condense the art
380 of music engraving into a computer program. Thanks to all that hard
381 work, the program can now be used to perform useful tasks. The
382 simplest application is printing notes.
384 @lilypond[relative=1]
385 \time 2/4 c4 c g'4 g a4 a g2
388 By adding chord names and lyrics we obtain a lead sheet:
390 @lilypond[raggedright]
392 \context ChordNames \chords { c2 c f2 c }
393 \notes \relative c' { \time 2/4 c4 c g'4 g a4 a g2 }
394 \context Lyrics \lyrics { twin4 kle twin kle lit tle star2 } > }
397 Polyphonic notation and piano music can also be printed. The following
398 example combines some more exotic constructs.
400 @lilypondfile{screech-boink.ly}
402 The fragments shown above have all been written by hand, but that is
403 not a requirement. Since the formatting engine is mostly automatic, it
404 can serve as an output means for other programs that manipulate
405 music. For example, it can also be used to convert databases of
406 musical fragments to images for use on websites and multimedia
409 This manual also shows an application: the input format is plain text,
410 and can therefore be easily embedded in other text-based formats, such
411 as La@TeX{}, HTML or in the case of this manual, Texinfo. By means of a
412 special program, the input fragments can be replaced by music images in
413 the resulting PostScript or HTML output files. This makes it easy to
414 mix music and text in documents.
418 @node About this manual
419 @section About this manual
421 The manual is divided into the following chapters
426 @emph{@ref{Tutorial}}
427 gives a gentle introduction into typesetting music.
428 First time users should start here.
433 @emph{@ref{Notation manual}}
434 discusses topics grouped by notation construct. Once you master the
435 basics, this is the place to lookup details.
440 @emph{@ref{Literature}}
441 chapter lists useful reference books on notation and engraving.
446 @emph{@ref{Technical manual}}
448 discusses the general design of the program, and how to extend its
454 @emph{@ref{Invoking LilyPond}} explains how to run LilyPond and its helper
458 Once you are an experienced user, you can use the manual as reference:
459 there is an extensive index@footnote{If you are looking for something,
460 and you cannot find it by using the index, that is considered a bug.
461 In that case, please file a bug report.}, but the document is also
467 @uref{../lilypond.html, a big HTML page}
469 which can be searched easily using the search facility of a web
471 @cindex search in manual
472 @cindex using the manual
475 If you are not familiar with music notation, or music terminology
476 (especially if you are a non-native English speaker), then it is
477 advisable to consult the glossary as well. The glossary explains
478 musical terms, and includes translations to various languages. It is a
480 @uref{../glossary.html,separate document}
483 separate document, available in HTML and PDF.
488 @cindex foreign languages
492 This manual is not complete without a number of other documents. They
493 are not available in print, but should be included with the
494 documentation package for your platform
498 Generated internal documentation.
500 available @uref{../lilypond-internals/lilypond-internals.html,here}
503 The generated internal documentation is a set of heavily crosslinked
504 HTML pages, which documents the nit-gritty details of each and every
505 LilyPond class, object and function. It is produced directly from the
506 formatting definitions used.
508 Almost all formatting functionality that is used internally, is
509 available directly to the user. For example, all variables that
510 control thicknesses, distances, etc, can be changed in input
511 files. There are a huge number of formatting options, and all of them
512 are described in the generated documentation. Each section of the
513 notation manual has a @b{See also} subsection, which refers to the
514 the generated documentation. In the HTML document, these subsections
515 have clickable links.
520 (available @uref{../../../input/templates/out-www/collated-files.html,here})
523 After you have gone through the tutorial, in theory you should be able
524 to write input files. In practice, writing files from scratch turns
525 out to be intimidating. To give you a headstart, we have collected a
526 number of often-used formats in example files. These files can be
527 used as a start, by copying the template, and adding notes in the
531 Various input examples
533 available @uref{../../../input/test/out-www/collated-files.html,here}
537 These small files show various tips and tricks, and are available as a
538 big HTML document, with pictures and explanatory texts included.
544 available @uref{../../../input/regression/out-www/collated-files.html,here}
547 This collection of files tests each notation and engraving feature of
548 LilyPond in one file. The collection is primarily there to help us
549 debug problems, but it can be instructive to see how we excercise the
550 program. The format is like the tips and tricks document.
555 In all HTML documents that have music fragments embedded, the LilyPond
556 input that was used to produce that image can be viewed by clicking
559 The location of the documentation files that are mentioned here can
560 vary from system to system. On occasion, this manual refers to
561 initialization and example files. Throughout this manual, we refer to
562 input files relative to the top-directory of the source archive. For
563 example, @file{input/test/bla.ly} may refer to the file
564 @file{lilypond-1.7.19/input/test/bla.ly}. On binary packages for the
565 Unix platform, the documentation and examples can typically be found
566 somewhere below @file{/usr/share/doc/lilypond/}. Initialization files,
567 for example @file{scm/lily.scm}, or @file{ly/engraver-init.ly}, are
568 usually found in the directory @file{/usr/share/lilypond/}.
570 @cindex adjusting output
573 @cindex lilypond-internals
574 @cindex internal documentation
576 @cindex extending lilypond
580 Finally, this and all other manuals, are available online both as PDF
581 files and HTML from the web site, which can be found at
582 @uref{http://www.lilypond.org/}.