7 There are a lot of programs that let you print sheet music with a
8 computer, but most of them do not do a good job. Most computer
9 printouts have a bland, mechanical look, and are unpleasant to play
10 from. If you agree with us on that, then you will like LilyPond: we
11 have tried to capture the original look of hand-engraved music. We
12 have tuned our algorithms, font-designs, and program settings to make
13 the program produce prints that match the quality of the old editions
14 we love to see and love to play from.
18 * Notation in LilyPond ::
19 * Engraving in LilyPond::
20 * Typography and program architecture::
21 * Music representation::
22 * Example applications::
27 @node Notation in LilyPond
28 @section Notation in LilyPond
35 Printing sheet music consists of two non-trivial tasks. First, one has
36 to master music notation: the science of knowing which symbols to use
37 for what. Second, one has to master music engraving: the art of
38 placing symbols such that the result looks pleasing.
40 Common music notation is a system of recording music that has evolved
41 over the past 1000 years. The form that is now in common use, dates
42 from the early renaissance. Although, the basic form (i.e. note heads on a
43 5-line staff) has not changed, the details still change to express the
44 innovations of contemporary notation. Hence, it encompasses some 500
45 years of music. Its applications range from monophonic melodies to
46 monstrous counterpoint for large orchestras.
48 How can we get a grip on such a many-headed beast, and force it into
49 the confines of a computer program? Our solution is to make a strict
50 distinction between notation, @emph{what} symbols to use, and
51 engraving, @emph{where} to put them. Anything related to the second
52 question is considered ``engraving'' (i.e. typography).
54 For tackling the first problem, notation, we have broken up the
55 problem into digestible (and programmable) chunks: every type of
56 symbol is handled by a separate program module, a so-called plug-in.
57 Each plug-in is completely modular and independent, so each can be
58 developed and improved separately. When put together, the plug-ins
59 can solve the music notation problem in cooperation. People that translate
60 musical ideas to graphic symbols are called copyists or engravers, so by
61 analogy, each plug-in is also called @code{engraver}.
63 In the following example, we see how we start out with a note head
67 \include "engraver-example.lyinc"
71 \translator { \VoiceContext
72 \remove "Stem_engraver"
73 \remove "Phrasing_slur_engraver"
74 \remove "Slur_engraver"
75 \remove "Script_engraver"
76 \remove "Beam_engraver"
77 \remove "Auto_beam_engraver"
80 \translator { \StaffContext
81 \remove "Accidental_engraver"
82 \remove "Key_engraver"
83 \remove "Clef_engraver"
84 \remove "Bar_engraver"
85 \remove "Time_signature_engraver"
86 \remove "Staff_symbol_engraver"
87 \consists "Pitch_squash_engraver"
94 Then a @code{Staff_symbol_engraver} adds the staff:
97 \include "engraver-example.lyinc"
101 \translator { \VoiceContext
102 \remove "Stem_engraver"
103 \remove "Phrasing_slur_engraver"
104 \remove "Slur_engraver"
105 \remove "Script_engraver"
106 \remove "Beam_engraver"
107 \remove "Auto_beam_engraver"
110 \translator { \StaffContext
111 \remove "Accidental_engraver"
112 \remove "Key_engraver"
113 \remove "Clef_engraver"
114 \remove "Bar_engraver"
115 \consists "Pitch_squash_engraver"
116 \remove "Time_signature_engraver"
123 The @code{Clef_engraver} defines a reference point for the staff:
126 \include "engraver-example.lyinc"
130 \translator { \VoiceContext
131 \remove "Stem_engraver"
132 \remove "Phrasing_slur_engraver"
133 \remove "Slur_engraver"
134 \remove "Script_engraver"
135 \remove "Beam_engraver"
136 \remove "Auto_beam_engraver"
138 \translator { \StaffContext
139 \remove "Accidental_engraver"
140 \remove "Key_engraver"
141 \remove "Bar_engraver"
142 \remove "Time_signature_engraver"
149 And the @code{Stem_engraver} adds stems:
152 \include "engraver-example.lyinc"
156 \translator { \VoiceContext
157 \remove "Phrasing_slur_engraver"
158 \remove "Slur_engraver"
159 \remove "Script_engraver"
160 \remove "Beam_engraver"
161 \remove "Auto_beam_engraver"
163 \translator { \StaffContext
164 \remove "Accidental_engraver"
165 \remove "Key_engraver"
166 \remove "Bar_engraver"
167 \remove "Time_signature_engraver"
173 The @code{Stem_engraver} is notified of any note head coming along.
174 Every time one (or more, for a chord) note head(s) is seen, a stem
175 object is created, and attached to the note head.
177 By adding engravers for beams, slurs, accents, accidentals, bar lines,
178 time signature, and key signature, we get a complete piece of
182 \include "engraver-example.lyinc"
189 This system works well for monophonic music, but what about
190 polyphony? In polyphonic notation, many voices can share a staff.
193 \include "engraver-example.lyinc"
194 \score { \context Staff << \topVoice \\ \botVoice >> }
197 In this situation, the accidentals and staff are shared, but the
198 stems, slurs, beams, etc. are private to each voice. Hence, engravers
199 should be grouped. The engravers for note heads, stems, slurs, etc. go
200 into a group called ``Voice context,'' while the engravers for key,
201 accidental, bar, etc. go into a group called ``Staff context.'' In the
202 case of polyphony, a single Staff context contains more than one Voice
203 context. In polyphonic notation, many voices can share a staff:
204 Similarly, more Staff contexts can be put into a single Score context.
207 \include "engraver-example.lyinc"
209 << \new Staff << \topVoice \\ \botVoice >>
210 \new Staff << \pah \\ \hoom >>
217 @node Engraving in LilyPond
218 @section Engraving in LilyPond
221 The term music engraving derives from the traditional process of music
222 printing. Only a few decades ago, sheet music was made by cutting and
223 stamping the music into zinc or pewter plates, in mirror image. The plate
224 would be inked, and the depressions caused by the cutting and stamping
225 would hold ink. An image was formed by pressing paper to the
226 plate. The stamping and cutting was done completely by hand. Making
227 corrections was cumbersome, so engraving had to be done correctly in
228 one go. Of course, this was a highly specialized skill, much more so
229 than the traditional process of printing books.
230 @cindex craftsmanship
232 In the traditional German system of craftsmanship six years of full-time
233 training, more than any other craft, were required before a student
234 could call himself a master of the art. After that many more years of
235 practical experience were needed to become an established music
236 engraver. Even today, with the use of high-speed computers and
237 advanced software, music requires lots of manual fine tuning before it
238 is acceptable for publication.
241 Sheet music is performance material: everything is done to aid the
242 musician in letting him perform better. Music is often far away from
243 its reader---it might be on a music stand. To make it clearly
244 readable, traditionally printed sheet music always uses bold symbols,
245 on heavy staff lines, and is printed on large sheets of paper. This
246 ``strong'' look is also present in the horizontal spacing. To
247 minimize the number of page breaks, (hand-engraved) sheet music is
248 spaced very tightly. Yet, by a careful distribution of white space,
249 the feeling of balance is retained, and a clutter of symbols is
253 We have used these observations in designing LilyPond. The images
254 below show the flat symbol. On the left, a scan from a Henle edition,
255 which was made by a computer, and in the center is the flat from a
256 hand engraved B@"{a}renreiter edition of the same music. The left scan
257 illustrates typical flaws of computer print: the symbol is much
258 lighter, the staff lines are thinner, and the glyph has a straight
259 layout with sharp corners. By contrast, the B@"{a}renreiter has a bold
260 and almost voluptuous rounded look. Our flat symbol is designed
261 after, among others, this one. It is tuned it to harmonize with the
262 thickness of our staff lines, which are also much thicker than Henle's
265 @multitable @columnfractions .1 .3 .3 .3
268 @image{henle-flat-bw,4cm}
271 <img src=henle-flat-bw.png>
276 @image{baer-flat-bw,4cm}
279 <img src=baer-flat-bw.png>
284 @image{lily-flat-bw,4cm}
287 <img src=lily-flat-bw.png>
293 B@"{a}renreiter (1950)
295 LilyPond Feta font (2003)
300 @cindex musical symbols
305 In spacing, the distribution of space should reflect the durations
306 between notes. However, adhering with mathematical precision to the
307 duration will lead to a poor result. Shown here is an example of a
308 motive, printed twice. It is printed using exact mathematical spacing,
309 and with some corrections. Can you spot which fragment is which?
311 @cindex optical spacing
314 \override Staff.NoteSpacing #'stem-spacing-correction
317 \stemDown b'4 e''4 a'4 e''4| \stemBoth
319 \override Staff.NoteSpacing #'stem-spacing-correction
321 \override Staff.StaffSpacing #'stem-spacing-correction
324 \stemDown b'4 e''4 a'4 e''4|
326 \paper { raggedright = ##t } }
329 @cindex regular rhythms
330 @cindex regular spacing
332 The fragment only uses quarter notes: notes that are played in a
333 constant rhythm. The spacing should reflect that. Unfortunately, the
334 eye deceives us a little: not only does it notice the distance between
335 note heads, it also takes into account the distance between
336 consecutive stems. As a result, the notes of an up-stem/down-stem
337 combination should be put farther apart, and the notes of a down-up
338 combination should be put closer together, all depending on the
339 combined vertical positions of the notes. The first two measures are
340 printed with this correction, the last two measures without. The notes
341 in the last two measures form down-stem/up-stem clumps of notes.
343 @node Typography and program architecture
344 @section Typography and program architecture
346 Producing good engraving requires skill and knowledge. As the
347 previous examples show, there is a lot of subtlety involved in music
348 engraving, and unfortunately, only a small fraction of these details
349 are documented. Master engravers must learn all these details from
350 experience or from other engravers, which is why it takes so long to
351 become a master. As an engraver gets older and wiser, he will be able
352 to produce better and more complex pieces. A similar situation is
353 present when putting typographical knowledge into a computer program.
354 It is not possible to come up with a definitive solution for a problem
355 on the first try. Instead, we start out with a simple solution that
356 might cover 75% of the cases, and gradually refine that solution over
357 the course of months or years, so that 90 or 95 % of the cases are
360 This has an important implication for the design of the program: at
361 any time, almost every piece of formatting code must be considered as
362 temporary. When the need arises, it is to be replaced a solution that
363 will cover even more cases. A ``plug-in'' architecture is a clean
364 way to accomplish this. This is an architecture where new pieces of
365 code can be inserted in the program dynamically. In such a program, a
366 new solution can be developed along-side the existing code. For
367 testing, it is plugged in, but for production use, the old solution is
368 used. The new module can be perfected separately until it is better
369 than the existing solution, at which point it replaces the old one.
371 Until that time, users must have a way to deal with imperfections:
372 these 25%, 10% or 5% of the cases that are not handled
373 automatically. In these cases, a user must be able to override
374 formatting decisions. To accomplish this we store decisions in generic
375 variables, and let the user manipulate those. For example, consider
376 the following fragment of notation:
379 \score { \notes \relative c'' {
383 \paper { raggedright = ##t }
388 The position of the forte symbol is slightly awkward, because it is
389 next to the low note, whereas dynamics should be below notes in
390 general. This may be remedied by inserting extra space between the
391 high note and the `f', as shown in this example:
394 \score { \notes \relative c'' {
396 \once\override DynamicLineSpanner #'padding = #4.0
399 \paper { raggedright = ##t }
403 This was achieved with the following input statement:
405 \once \override DynamicLineSpanner #'padding = #4.0
407 It increases the amount of space (@code{padding}) between the note and
408 the dynamic symbol to 4.0 (which is measured in staff spaces, so 4.0
409 equals the height of a staff). The keyword @code{\once} indicates that
410 this is a tweak: it is only done one time.
412 Both design aspects, a plug-in architecture, and formatting variables,
413 are built on top of GUILE, an interpreter for the programming language
414 Scheme, which is a member of the LISP family. Variables are stored as
415 Scheme objects, and attached to graphical objects such as note heads
416 and stems. The variables are a means to adjust formatting details in
417 individual cases, but they are used in a more general manner.
419 Consider the case of a publisher that is not satisfied with the
420 default layout, and wants heavier stems. Normally, they are @code{1.3}
421 times the thickness of staff lines, but suppose that their editions
422 require them to be twice the thickness of the staff lines. The same
423 mechanism can be used to adjust a setting globally. By issuing the
424 following command, the entire piece is now formatted with thicker
427 \override Score.Stem #'thickness = #3.0
431 \score { \notes \relative c'' {
432 \override Score.Stem #'thickness = #3.0
433 \once\override DynamicLineSpanner #'padding = #4.0
437 \paper { raggedright = ##t }
442 In effect, by setting these variables, users can define their own
445 ``Plug-ins'' are also implemented using Scheme. A formatting
446 ``plug-in'' takes the form of a function written in Scheme (or a C++
447 function made available as a Scheme function), and it is also stored
448 in a variable. For example, the placement of the forte symbol in the
449 example above is calculated by the function
450 @code{Side_position_interface::aligned_side}. If we want to replace
451 this function by a more advanced one, we could issue
453 \override DynamicLineSpanner #'Y-offset-callbacks
454 = #(list gee-whiz-gadget)
458 Now, the formatting process will trigger a call to our new
459 @code{gee-whiz-gadget} function when the position of the f symbol has
462 The full scope of this functionality certainly is intimidating, but
463 there is no need to fear: normally, it is not necessary to define
464 style-sheets or rewrite formatting functions. In fact, LilyPond gets a
465 lot of formatting right automatically, so adjusting individual layout
466 situations is often not needed at all.
469 @node Music representation
470 @section Music representation
473 Our premise is that LilyPond is a system that does music formatting
474 completely automatically. Under this assumption, the output does not
475 have to be touched up. Consequently, an interactive display of the
476 output, where it is possible to reposition notation elements, is
477 superfluous. This implies that the program should be a batch program:
478 the input is entered in a file, which then is @emph{compiled}, i.e.
479 put through the program. The final output is produced as a file ready
480 to view or print. The compiler fills in all the details of the
481 notation, those details should be left out of the input file. In other
482 words, the input should mirror the content as closely as possible. In
483 the case of music notation the content is the music itself, so that is
484 what the input should consist of.
486 On paper this theory sounds very good. In practice, it opens a can of
487 worms. What really @emph{is} music? Many philosophical treatises must
488 have been written on the subject. Instead of losing ourselves in
489 philosophical arguments over the essence of music, we have reversed
490 the question to yield a more practical approach. Our assumption is
491 that the printed score contains all of the music of piece. We build a
492 program that uses some input format to produce such a score. Over the
493 course of time, the program evolves. While this happens, we can remove
494 more and more elements of the input format: as the program improves,
495 it can fill in irrelevant details of the input by itself. At some
496 (hypothetical) point, the program is finished: there is no possibility
497 to remove any more elements from the syntax. What we have left is by
498 definition exactly the musical meaning of the score.
500 There are also more practical concerns. Our users have to key in the
501 music into the file directly, so the input format should have a
502 friendly syntax: a quarter note C is entered as @code{c4}, the code
503 @code{r8.} signifies a dotted eighth rest.
505 Notes and rests form the simplest musical expressions in the input
506 syntax. More complex constructs are produced by combining them into
507 compound structures. This is done in much the same way that complex
508 mathematical formulas are built from simple expressions such as
509 numbers and operators.
511 In effect, the input format is a language, and the rules of that
512 language can be specified succinctly with a so-called context-free
513 grammar. The grammar formally specificies what types of input form
514 valid `sentences'. Reading such languages, and splitting them into
515 grammatical structures is a problem with standard solutions.
516 Moreover, rigid definitions make the format easier to understand: a
517 concise formal definition permits a simple informal description.
519 The user-interface of LilyPond is its syntax. That part is what users
520 see most. As a results, some users think that music representation is
521 a very important or interesting problem. In reality, less than 10% of
522 the source code of the program handles reading and representing the
523 input, and they form the easy bits of the program. In our opinion,
524 producing music notation, and formatting it prettily are much more
525 interesting and important than music representation: solving
526 these problems takes up most of the bulk of the code, and they are the
527 most difficult things to get right.
529 @node Example applications
530 @section Example applications
532 We have written LilyPond as an experiment of how to condense the art
533 of music engraving into a computer program. Thanks to all that hard
534 work, the program can now be used to perform useful tasks. The
535 simplest application is printing notes:
537 @lilypond[relative=1]
538 \time 2/4 c4 c g'4 g a4 a g2
541 By adding chord names and lyrics we obtain a lead sheet:
543 @lilypond[raggedright]
545 \context ChordNames \chords { c2 c f2 c }
546 \notes \relative c' { \time 2/4 c4 c g'4 g a4 a g2 }
547 \context Lyrics \lyrics { twin4 kle twin kle lit tle star2 } >> }
550 Polyphonic notation and piano music can also be printed. The following
551 example combines some more exotic constructs:
553 @lilypondfile{screech-boink.ly}
555 The fragments shown above have all been written by hand, but that is
556 not a requirement. Since the formatting engine is mostly automatic, it
557 can serve as an output means for other programs that manipulate
558 music. For example, it can also be used to convert databases of
559 musical fragments to images for use on websites and multimedia
562 This manual also shows an application: the input format is plain text,
563 and can therefore be easily embedded in other text-based formats, such
564 as La@TeX{}, HTML or in the case of this manual, Texinfo. By means of a
565 special program, the input fragments can be replaced by music images in
566 the resulting PostScript or HTML output files. This makes it easy to
567 mix music and text in documents.
571 @node About this manual
572 @section About this manual
574 The manual is divided into the following chapters:
579 @emph{@ref{Tutorial}}
580 gives a gentle introduction to typesetting music.
581 First time users should start here.
586 @emph{@ref{Notation manual}}
587 discusses topics grouped by notation construct. Once you master the
588 basics, this is the place to look up details.
593 @emph{@ref{Literature list}}
594 contains a set of useful reference books, for those who wish to know
595 more on notation and engraving.
600 @emph{@ref{Technical manual}}
602 discusses the general design of the program, and how to extend its
608 @emph{@ref{Invoking LilyPond}} explains how to run LilyPond and its helper
615 @emph{@ref{lilypond-book manual}}
616 explains the details behind creating documents with in-line music
617 examples (like this manual).
624 @emph{@ref{Converting from other formats}}
625 explains how to run the conversion programs. These programs
626 are supplied with the LilyPond package, and convert a variety of music
627 formats to the @code{.ly} format. In addition, this section explains
628 how to upgrade input files from previous versions of LilyPond.
632 Once you are an experienced user, you can use the manual as reference:
633 there is an extensive index@footnote{If you are looking for something,
634 and you cannot find it in the manual, that is considered a bug. In
635 that case, please file a bug report.}, but the document is also
641 @uref{../lilypond.html, a big HTML page}
643 which can be searched easily using the search facility of a web
645 @cindex search in manual
646 @cindex using the manual
649 If you are not familiar with music notation or music terminology
650 (especially if you are a non-native English speaker), then it is
651 advisable to consult the glossary as well. The glossary explains
652 musical terms, and includes translations to various languages. It is a
654 @uref{../music-glossary.html,separate document}.
657 separate document, available in HTML and PDF.
662 @cindex foreign languages
666 This manual is not complete without a number of other documents. They
667 are not available in print, but should be included with the
668 documentation package for your platform:
674 (available @uref{../lilypond-internals/lilypond-internals.html,here})
677 The program reference is a set of heavily crosslinked HTML pages,
678 which documents the nit-gritty details of each and every LilyPond
679 class, object and function. It is produced directly from the
680 formatting definitions used.
682 Almost all formatting functionality that is used internally, is
683 available directly to the user. For example, all variables that
684 control thicknesses, distances, etc, can be changed in input
685 files. There are a huge number of formatting options, and all of them
686 are described in the generated documentation. Each section of the
687 notation manual has a @b{See also} subsection, which refers to the
688 the generated documentation. In the HTML document, these subsections
689 have clickable links.
694 (available @uref{../../../input/template/out-www/collated-files.html,here})
697 After you have gone through the tutorial, you should be able to write
698 input files. In practice, writing files from scratch turns out to be
699 intimidating. To give you a headstart, we have collected a number of
700 often-used formats in example files. These files can be used as a
701 start: simply copy the template, and add notes in the appropriate
705 Various input examples
707 (available @uref{../../../../input/test/out-www/collated-files.html,here})
711 These small files show various tips and tricks, and are available as a
712 big HTML document, with pictures and explanatory texts included.
718 (available @uref{../../../input/regression/out-www/collated-files.html,here})
721 This collection of files tests each notation and engraving feature of
722 LilyPond in one file. The collection is primarily there to help us
723 debug problems, but it can be instructive to see how we excercise the
724 program. The format is like the tips and tricks document.
729 In all HTML documents that have music fragments embedded, the LilyPond
730 input that was used to produce that image can be viewed by clicking
733 The location of the documentation files that are mentioned here can
734 vary from system to system. On occasion, this manual refers to
735 initialization and example files. Throughout this manual, we refer to
736 input files relative to the top-directory of the source archive. For
737 example, @file{input/test/bla.ly} may refer to the file
738 @file{lilypond-1.7.19/input/test/bla.ly}. On binary packages for the
739 Unix platform, the documentation and examples can typically be found
740 somewhere below @file{/usr/share/doc/lilypond/}. Initialization files,
741 for example @file{scm/lily.scm}, or @file{ly/engraver-init.ly}, are
742 usually found in the directory @file{/usr/share/lilypond/}.
744 @cindex adjusting output
747 @cindex lilypond-internals
748 @cindex internal documentation
750 @cindex extending lilypond
754 Finally, this and all other manuals, are available online both as PDF
755 files and HTML from the web site, which can be found at
756 @uref{http://www.lilypond.org/}.