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