6 LilyPond is a system for formatting music prettily. This chapter
7 discusses the backgrounds of LilyPond. It explains the problem of
8 printing music with computers, and our approach to solving those
14 * Automated engraving::
15 * What symbols to engrave?::
16 * Music representation::
17 * Example applications::
25 The art of music typography is called @emph{(plate) engraving}. The
26 term derives from the traditional process of music printing. Only a
27 few decades ago, sheet music was made by cutting and stamping the
28 music into zinc or pewter plates in mirror image. The plate would be
29 inked, and the depressions caused by the cutting and stamping would
30 hold ink. An image was formed by pressing paper to the plate. The
31 stamping and cutting was completely done by hand. Making corrections
32 was cumbersome, so engraving had to be done correctly in one go. Of
33 course, this was a highly specialized skill, and a craftsman had to
34 complete around 10 years of practical training before he could be a
38 Nowadays, all newly printed music is produced on computers. This has
39 obvious advantages: prints are cheaper to make, and editorial work can
40 be done over e-mail. Unfortunately, the pervasive use of computers has
41 also decreased the graphical quality of scores. Computer printouts
42 have a bland, mechanical look, which makes them unpleasant to play
45 The images below illustrate the difference between traditional
46 engraving and typical computer output, and the third picture shows how
47 LilyPond mimics the traditional look. The left picture shows a scan
48 of a flat symbol from a Henle edition published in 2000. In the center
49 show symbol from a hand engraved B@"{a}renreiter edition of the same
50 music. The left scan illustrates typical flaws of computer print: the
51 staff line are thin, the weight of the symbol matches the light lines,
52 and the glyph has a straight layout with sharp corners. By contrast,
53 the B@"{a}renreiter has a bold and almost voluptuous rounded look.
54 Our flat symbol is designed after, among others, this one. It is
55 rounded, and its weight harmonizes with the thickness of our staff
56 lines, which are also much thicker than Henle's lines.
58 @multitable @columnfractions .1 .3 .3 .3
62 @image{henle-flat-bw,4cm}
65 @image{henle-flat-bw,,,png}
70 @image{baer-flat-bw,4cm}
73 @image{baer-flat-bw,,,png}
78 @image{lily-flat-bw,4cm}
81 @image{lily-flat-bw,,,png}
85 @c workaround for makeinfo-4.6: line breaks and multi-column cookies
86 @image{henle-flat-bw,,,png} @image{baer-flat-bw,,,png} @image{lily-flat-bw,,,png}
92 B@"{a}renreiter (1950)
94 LilyPond Feta font (2003)
99 @cindex musical symbols
104 In spacing, the distribution of space should reflect the durations
105 between notes. However, many modern scores adhere to the durations
106 with mathematical precision, and that leads to a poor result. In the
107 next example, a motive is printed twice. It is printed using exact
108 mathematical spacing, and with some corrections. Can you spot which
111 @cindex optical spacing
114 \override Staff.NoteSpacing #'stem-spacing-correction
117 \stemDown b'4 e''4 a'4 e''4| \stemBoth
119 \override Staff.NoteSpacing #'stem-spacing-correction
121 \override Staff.StaffSpacing #'stem-spacing-correction
124 \stemDown b'4 e''4 a'4 e''4|
126 \paper { raggedright = ##t } }
129 @cindex regular rhythms
130 @cindex regular spacing
132 The fragment only uses quarter notes: notes that are played in a
133 constant rhythm. The spacing should reflect that. Unfortunately, the
134 eye deceives us a little: not only does it notice the distance between
135 note heads, it also takes into account the distance between
136 consecutive stems. As a result, the notes of an up-stem/down-stem
137 combination should be put farther apart, and the notes of a down-up
138 combination should be put closer together, all depending on the
139 combined vertical positions of the notes. The first two measures are
140 printed with this correction, the last two measures without. The notes
141 in the last two measures form down-stem/up-stem clumps of notes.
145 Musicians are usually more absorbed with performing the music than
146 with studying its looks, so this nitpicking about typographical
147 details may seem academical. That is not justified. In larger pieces
148 with monotonous rhythms, spacing corrections lead to subtle variations
149 in the layout of every line, giving each one a distinct visual
150 signature. Without this signature, all lines would look the same, they
151 become like a labyrinth. If the musician looks away once or has a
152 lapse in his concentration, he will be lost on the page.
154 Similarly, the strong visual look of bold symbols on heavy staff lines
155 stands out better when music is far away from reader, for example, if
156 it is on a music stand. A careful distribution of white space allows
157 music to be set very tightly without cluttering symbols together. The
158 result minimizes the number of page turns,
160 This is a common characteristic of typography. Layout should be
161 pretty, not only for its own sake, but especially because it helps the
162 reader in his task. For performance material like sheet music, this is
163 doubly important: musicians have a limited amount of attention. The
164 less attention they need for reading, the more they can focus on
165 playing itself. In other words, better typography translates to better
168 Hopefully, these examples also demonstrate that music typography is an
169 art that is subtle and complex, and to produce it requires
170 considerable expertise, which musicians usually do not have. LilyPond
171 is our effort to bring the graphical excellence of hand-engraved music
172 to the computer age, and make it available to normal musicians. We
173 have tuned our algorithms, font-designs, and program settings to
174 produce prints that match the quality of the old editions we love to
175 see and love to play from.
180 @node Automated engraving
181 @section Automated engraving
183 How do we go about implementing typography? If craftsmen need over
184 ten years to become true masters, how could we simple hackers ever
185 write a program to take over their jobs?
187 The answer is: we cannot. Typography relies on human judgment of
188 appearance, so people cannot be replaced ultimately. However, much of
189 the dull work can be automated. If LilyPond solves most of the common
190 situations correctly, then this will be a huge improvement over
191 existing software. The remaining cases can be tuned by hand. Over the
192 course of years, the software can be refined to do more and more
193 automatically, so manual overrides are less and less necessary.
195 When we started, we wrote the program in C++. With this design, the
196 program functionality was set in stone stone by us developers. That
197 proved to be unsatisfactory:
201 @item When LilyPond makes mistakes,
202 users need to override formatting decisions. Therefore, the user
203 must access to the formatting engine. Hence, rules and settings cannot
204 be fixed by us at compile time, but they must be accessible for users
207 @item Engraving is a matter of visual judgment, and therefore a matter of
208 taste. As knowledgeable as we are, users can disagree with our
209 personal decisions. Therefore, the definitions of typographical style
210 must also be accessible to the user.
212 @item Finally, we continually refine the formatting algorithms, so we
213 need a flexible approach to rules. The C++ language forces a certain
214 method of grouping rules that do not match well with how music
219 The formatting architecture of LilyPond addresses these needs. It is
220 built around the notion graphical objects, carrying variables. The
221 architecture encompasses formatting rules, typographical style and
222 individual formatting decisions.
224 Variables control layout decisions. For example, many objects have a
225 direction variable that encodes the choice between up and down (or
226 left and right). Here you see two chords, with accents and
227 arpeggio. In the first chord, the objects have all directions down (or
228 left). The second chord has all directions up (right).
230 @lilypond[raggedright,relative=1]
232 \override SpacingSpanner #'spacing-increment = #3
233 \override TimeSignature #'transparent = ##t
238 \override Arpeggio #'direction = #RIGHT
244 The process of formatting a score consists of reading and
245 writing object variables.
247 Some variables have a preset value. For example, the thickness of many
248 lines ---a characteristic of typographical style--are preset
249 variables. Changing them gives a different typographical impression:
254 c'4-~ c'16 as g f e16 g bes c' des'4
256 \paper { raggedright = ##t }
261 \override Beam #'thickness = #0.3
262 \override Stem #'thickness = #0.5
263 \override Bar #'thickness = #3.6
264 \override Tie #'thickness = #2.2
265 \override StaffSymbol #'thickness = #3.0
266 \override Tie #'extra-offset = #'(0 . 0.3)
272 Formatting rules are also preset variables: each object has variables
273 containing procedures. These procedure perform the actual formatting,
274 and by substituting different ones, we can change behavior. In the
275 following example, the rule that note head objects use to produce
276 their symbol is changed during the music fragment:
279 @lilypond[raggedright]
280 #(define (mc-squared gr org cur)
282 ((ifs (ly:grob-property gr 'interfaces))
283 (sp (ly:grob-property gr 'staff-position)) )
284 (if (and (memq 'note-head-interface ifs)
285 (memq sp '(-2 -3 -5)))
287 (ly:grob-set-property! gr 'print-function brew-new-markup-stencil)
288 (ly:grob-set-property! gr 'font-family 'roman)
289 (ly:grob-set-property!
291 (make-raise-markup -0.5
293 ((-5) (make-simple-markup "m"))
294 ((-3) (make-simple-markup "c "))
295 ((-2) (make-smaller-markup (make-bold-markup "2")))
296 (else (make-simple-markup "bla"))
301 \notes \context Voice \relative c'
304 \set autoBeaming = ##f
307 \once \override NoteHead #'print-function
308 = #Note_head::brew_ez_stencil
310 \once \override NoteHead #'style
313 \applyoutput #mc-squared
315 << { d8[ es-( fis^^ g] fis2-) }
316 \repeat unfold 5 { \applyoutput #mc-squared s8 } >>
326 @node What symbols to engrave?
327 @section What symbols to engrave?
332 The formatting process in LilyPond decides where to place
333 symbols. However, this can only be done once it is decided @emph{what}
334 symbols should be printed, in other words what notation to use.
336 Common music notation is a system of recording music that has evolved
337 over the past 1000 years. The form that is now in common use, dates
338 from the early renaissance. Although, the basic form (i.e. note heads on a
339 5-line staff) has not changed, the details still change to express the
340 innovations of contemporary notation. Hence, it encompasses some 500
341 years of music. Its applications range from monophonic melodies to
342 monstrous counterpoint for large orchestras.
344 How can we get a grip on such a many-headed beast, and force it into
345 the confines of a computer program? We have broken up the problem of
346 notation (as opposed to engraving, i.e. typography) into digestible
347 and programmable chunks: every type of symbol is handled by a separate
348 module, a so-called plug-in. Each plug-in is completely modular and
349 independent, so each can be developed and improved separately. People
350 that translate musical ideas to graphic symbols are called copyists or
351 engravers, so by analogy, each plug-in is called @code{engraver}.
353 In the following example, we see how we start out with a plug-in for
354 note heads, the @code{Note_heads_engraver}.
357 \include "engraver-example.lyinc"
361 \context { \VoiceContext
362 \remove "Stem_engraver"
363 \remove "Phrasing_slur_engraver"
364 \remove "Slur_engraver"
365 \remove "Script_engraver"
366 \remove "Beam_engraver"
367 \remove "Auto_beam_engraver"
370 \context { \StaffContext
371 \remove "Accidental_engraver"
372 \remove "Key_engraver"
373 \remove "Clef_engraver"
374 \remove "Bar_engraver"
375 \remove "Time_signature_engraver"
376 \remove "Staff_symbol_engraver"
377 \consists "Pitch_squash_engraver"
384 Then a @code{Staff_symbol_engraver} adds the staff:
387 \include "engraver-example.lyinc"
391 \context { \VoiceContext
392 \remove "Stem_engraver"
393 \remove "Phrasing_slur_engraver"
394 \remove "Slur_engraver"
395 \remove "Script_engraver"
396 \remove "Beam_engraver"
397 \remove "Auto_beam_engraver"
400 \context { \StaffContext
401 \remove "Accidental_engraver"
402 \remove "Key_engraver"
403 \remove "Clef_engraver"
404 \remove "Bar_engraver"
405 \consists "Pitch_squash_engraver"
406 \remove "Time_signature_engraver"
413 The @code{Clef_engraver} defines a reference point for the staff:
416 \include "engraver-example.lyinc"
420 \context { \VoiceContext
421 \remove "Stem_engraver"
422 \remove "Phrasing_slur_engraver"
423 \remove "Slur_engraver"
424 \remove "Script_engraver"
425 \remove "Beam_engraver"
426 \remove "Auto_beam_engraver"
428 \context { \StaffContext
429 \remove "Accidental_engraver"
430 \remove "Key_engraver"
431 \remove "Bar_engraver"
432 \remove "Time_signature_engraver"
439 And the @code{Stem_engraver} adds stems:
442 \include "engraver-example.lyinc"
446 \context { \VoiceContext
447 \remove "Phrasing_slur_engraver"
448 \remove "Slur_engraver"
449 \remove "Script_engraver"
450 \remove "Beam_engraver"
451 \remove "Auto_beam_engraver"
453 \context { \StaffContext
454 \remove "Accidental_engraver"
455 \remove "Key_engraver"
456 \remove "Bar_engraver"
457 \remove "Time_signature_engraver"
463 The @code{Stem_engraver} is notified of any note head coming along.
464 Every time one (or more, for a chord) note head is seen, a stem
465 object is created and connected to the note head.
467 By adding engravers for beams, slurs, accents, accidentals, bar lines,
468 time signature, and key signature, we get a complete piece of
472 \include "engraver-example.lyinc"
479 This system works well for monophonic music, but what about
480 polyphony? In polyphonic notation, many voices can share a staff.
483 \include "engraver-example.lyinc"
484 \score { \context Staff << \topVoice \\ \botVoice >> }
487 In this situation, the accidentals and staff are shared, but the
488 stems, slurs, beams, etc. are private to each voice. Hence, engravers
489 should be grouped. The engravers for note heads, stems, slurs, etc. go
490 into a group called ``Voice context,'' while the engravers for key,
491 accidental, bar, etc. go into a group called ``Staff context.'' In the
492 case of polyphony, a single Staff context contains more than one Voice
493 context. In polyphonic notation, many voices can share a staff:
494 Similarly, more Staff contexts can be put into a single Score context.
497 \include "engraver-example.lyinc"
499 << \new Staff << \topVoice \\ \botVoice >>
500 \new Staff << \pah \\ \hoom >>
505 @node Music representation
506 @section Music representation
508 Ideally, the input format for any high-level formatting system is an
509 abstract description of the content. In this case, that would be the
510 music itself. This poses a formidable problem: how can we define what
511 music really is? Instead of trying to find an answer, we have reversed
512 the question. We write a program capable of producing sheet music,
513 and adjust the format to be as lean as possible. When the format can
514 no longer be trimmed down, by definition we are left with content
515 itself. Our program serves as a formal definition of a music
519 The syntax is also the user-interface for LilyPond, hence it is easily typable, e.g.,
523 Are a quarter note C (middle C) and eighth note D1 (D above middle C),
530 On a microscopic scale, such syntax is easy to use. On a larger scale,
531 syntax also needs structure. How else can you enter complex pieces
532 like symphonies and operas? The structure is formed by the concept of
533 music expressions: by combining small fragments of music into larger
534 ones, more complex music can be expressed. For example,
536 @lilypond[verbatim,fragment,relative=1]
540 Combine this simultaneously with two other notes by enclosing in << and >>.
543 @lilypond[verbatim,fragment,relative=1]
549 This expression is put in sequence by enclosing it in braces, i.e.,
555 @lilypond[relative=1]
556 \new Voice { <<c4 d4 e4>> f4 }
559 The above is another expression, and therefore, it many combined again
560 with a simultaneous expression (in this case, a half note).
563 << { <<c4 d4 e4>> f4 } g2 >>
565 @lilypond[fragment,relative=1]
566 << g2 \\ { <c d e>4 f4 } >>
570 Such recursive structures can be specified neatly and formally in a
571 context-free grammar. The parsing code is also generated from this
572 grammar. In other words, the syntax of LilyPond is clearly and
573 unambiguously defined.
575 User-interfaces and syntax are what people see and deal with
576 most. They are partly a matter of taste, and also subject of much
577 discussion. Although discussions on taste do have their merit, they
578 are not very productive. In the larger picture of LilyPond, the
579 importance of input syntax is small: inventing neat syntax is easy,
580 writing decent formatting code is much harder. This is also
581 illustrated by the line-counts for the respective components: parsing
582 and representation take up less than 10% of the code.
585 @node Example applications
586 @section Example applications
588 We have written LilyPond as an experiment of how to condense the art
589 of music engraving into a computer program. Thanks to all that hard
590 work, the program can now be used to perform useful tasks. The
591 simplest application is printing notes:
593 @lilypond[relative=1]
594 \time 2/4 c4 c g'4 g a4 a g2
597 By adding chord names and lyrics we obtain a lead sheet:
599 @lilypond[raggedright]
601 \context ChordNames \chords { c2 c f2 c }
602 \new Staff \notes \relative c' { \time 2/4 c4 c g'4 g a4 a g2 }
603 \context Lyrics \lyrics { twin4 kle twin kle lit tle star2 } >> }
606 Polyphonic notation and piano music can also be printed. The following
607 example combines some more exotic constructs:
609 @lilypondfile{screech-boink.ly}
611 The fragments shown above have all been written by hand, but that is
612 not a requirement. Since the formatting engine is mostly automatic, it
613 can serve as an output means for other programs that manipulate
614 music. For example, it can also be used to convert databases of
615 musical fragments to images for use on websites and multimedia
618 This manual also shows an application: the input format is plain text,
619 and can therefore be easily embedded in other text-based formats, such
620 as La@TeX{}, HTML or in the case of this manual, Texinfo. By means of a
621 special program, the input fragments can be replaced by music images in
622 the resulting PostScript or HTML output files. This makes it easy to
623 mix music and text in documents.
627 @node About this manual
628 @section About this manual
630 The manual is divided into the following chapters:
635 @emph{@ref{Tutorial}}
636 gives a gentle introduction to typesetting music.
637 First time users should start here.
642 @emph{@ref{Notation manual}}
643 discusses topics grouped by notation construct. Once you master the
644 basics, this is the place to look up details.
649 @emph{@ref{Literature list}}
650 contains a set of useful reference books, for those who wish to know
651 more on notation and engraving.
656 @emph{@ref{Changing defaults}}
658 Explains how to fine tune layout.
663 @emph{@ref{Invoking LilyPond}} explains how to run LilyPond and its helper
670 @emph{@ref{lilypond-book manual}}
671 explains the details behind creating documents with in-line music
672 examples (like this manual).
679 @emph{@ref{Converting from other formats}}
680 explains how to run the conversion programs. These programs
681 are supplied with the LilyPond package, and convert a variety of music
682 formats to the @code{.ly} format. In addition, this section explains
683 how to upgrade input files from previous versions of LilyPond.
687 Once you are an experienced user, you can use the manual as reference:
688 there is an extensive index@footnote{If you are looking for something,
689 and you cannot find it in the manual, that is considered a bug. In
690 that case, please file a bug report.}, but the document is also
696 @uref{../lilypond.html, a big HTML page}
698 which can be searched easily using the search facility of a web
700 @cindex search in manual
701 @cindex using the manual
704 If you are not familiar with music notation or music terminology
705 (especially if you are a non-native English speaker), then it is
706 advisable to consult the glossary as well. The glossary explains
707 musical terms, and includes translations to various languages. It is a
709 @uref{../music-glossary.html,separate document}.
712 separate document, available in HTML and PDF.
717 @cindex foreign languages
721 This manual is not complete without a number of other documents. They
722 are not available in print, but should be included with the
723 documentation package for your platform:
729 (available @uref{../lilypond-internals/lilypond-internals.html,here})
732 The program reference is a set of heavily cross linked HTML pages,
733 which documents the nit-gritty details of each and every LilyPond
734 class, object and function. It is produced directly from the
735 formatting definitions used.
737 Almost all formatting functionality that is used internally, is
738 available directly to the user. For example, all variables that
739 control thicknesses, distances, etc, can be changed in input
740 files. There are a huge number of formatting options, and all of them
741 are described in the generated documentation. Each section of the
742 notation manual has a @b{See also} subsection, which refers to the
743 the generated documentation. In the HTML document, these subsections
744 have clickable links.
749 (available @uref{../../../input/template/out-www/collated-files.html,here})
752 After you have gone through the tutorial, you should be able to write
753 input files. In practice, writing files from scratch turns out to be
754 intimidating. To give you a head start, we have collected a number of
755 often-used formats in example files. These files can be used as a
756 start: simply copy the template, and add notes in the appropriate
760 Various input examples
762 (available @uref{../../../../input/test/out-www/collated-files.html,here})
766 These small files show various tips and tricks, and are available as a
767 big HTML document, with pictures and explanatory texts included.
773 (available @uref{../../../input/regression/out-www/collated-files.html,here})
776 This collection of files tests each notation and engraving feature of
777 LilyPond in one file. The collection is primarily there to help us
778 debug problems, but it can be instructive to see how we exercise the
779 program. The format is like the tips and tricks document.
784 In all HTML documents that have music fragments embedded, the LilyPond
785 input that was used to produce that image can be viewed by clicking
788 The location of the documentation files that are mentioned here can
789 vary from system to system. On occasion, this manual refers to
790 initialization and example files. Throughout this manual, we refer to
791 input files relative to the top-directory of the source archive. For
792 example, @file{input/test/bla.ly} may refer to the file
793 @file{lilypond-1.7.19/input/test/bla.ly}. On binary packages for the
794 Unix platform, the documentation and examples can typically be found
795 somewhere below @file{/usr/share/doc/lilypond/}. Initialization files,
796 for example @file{scm/lily.scm}, or @file{ly/engraver-init.ly}, are
797 usually found in the directory @file{/usr/share/lilypond/}.
799 @cindex adjusting output
802 @cindex lilypond-internals
803 @cindex internal documentation
805 @cindex extending lilypond
809 Finally, this and all other manuals, are available online both as PDF
810 files and HTML from the web site, which can be found at
811 @uref{http://www.lilypond.org/}.