6 LilyPond is a program to print sheet music. If you have used notation
7 programs before, then the way to use this program might be surprising
8 at first sight: in order to print music you have to enter musical
9 codes in a file. Then you run the program on the file, and the music
10 is produced without any further intervention. For example, something
14 @lilypond[fragment,verbatim, relative 1, intertext="produces this:
17 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
20 @cindex encoding music
22 Encoding music using letters and digits may appear strange,
23 intimidating or even clumsy at first. Nevertheless, when you take the
24 effort to learn the codes and the program you will find that it is
25 easier than it seems. Entering music can be done quickly, and you
26 never have to remember how you made the program do something
27 complicated: it is all in the input code, and you only have to read
28 the file to see how it works. Moreover, you are rewarded with very
29 nicely looking output.
31 In this chapter, we will explain the reasoning behind this unusual
32 design, and how this approach affects you as a user.
39 * Computerized typography ::
40 * Music representation::
41 * Example applications::
45 @node Batch processing
46 @section Batch processing
52 LilyPond is a @emph{batch} program. To use it, one enters commands in a
53 file, and runs the program on that file. The output is produced without
54 requiring any further interaction.
56 When we started developing LilyPond, we were still studying at the
57 university. We were interested in music notation, not as publishers
58 or musicians, but as programmers and scientists. We wanted to figure
59 to what extent formatting sheet music could be automated. Back then
60 GUIs were not as ubiquitous as they are today, and we were immersed in
61 the UNIX operating system, where it is very common to use compilers to
62 achieve computing tasks. So, our computerized music engraving
63 experiment took on the form of a compiler.
68 @cindex sharing software
70 You can freely use, modify and redistribute LilyPond. This choice was
71 also motivated by our academic background. In the scientific community
72 it has always been a tradition to share knowledge, also if that
73 knowledge was packaged as software. One of the most visible groups
74 that stimulated this philosophy, was the Free Software Foundation,
75 whose popular GNU project aimed to replace closed and proprietary
76 computing solutions with free (as in ``Libre'') variants. We jumped on
77 that bandwagon, and released LilyPond as free software. That is the
78 reason that you can get LilyPond at no cost and without any strings
84 @section Music engraving
91 Making sheet music may seem trivial at first (``you print 5 lines, and
92 then put in the notes at different heights''), @emph{music engraving},
93 i.e. professional music typography, is in another ballpark. The term
94 `music engraving' derives from the traditional process of music
95 printing. Only a few decades ago, sheet music was made by cutting and
96 stamping the music into zinc or pewter plates, mirrored. The plate
97 would be inked, and the depressions caused by the cutting and stamping
98 would hold ink. An image was formed by pressing paper to the
99 plate. Stamping and cutting was completely done by hand. Making
100 corrections was cumbersome, so engraving had to be done correctly in
101 one go. As you can imagine this was a highly specialized skill, much
102 more so than the traditional process of printing books.
103 @cindex craftsmanship
105 In the traditional German craftsmanship six years of full-time
106 training, more than any other craft, were required before a student
107 could call himself a master of the art. After that many more years of
108 practical experience were needed to become an established music
109 engraver. Even today, with the use of high-speed computers and
110 advanced software, music requires lots of manual fine tuning before it
111 is acceptable for publication.
113 When we wanted to write a computer program to create music typography,
114 we encountered the first problem: there were no sets of musical
115 symbols available: either they were not available freely, or they did
116 not look well to our taste. Not let down, we decided to try font
117 design ourselves. We created a font of musical symbols, relying on
118 nice printouts of hand-engraved music. The experience helped develop
119 a typographical taste, and it made us appreciate subtle design
120 details. Without that experience, we would not have realized the
121 shortcomings of the fonts were that we admired at first.
125 #(define magfact 3.0)
126 \score { \notes { as'2 r4 }
131 AccidentalPlacement \override #'right-padding = #3.0
132 StaffSymbol \override #'transparent = ##t
133 Clef \override #'transparent = ##t
134 TimeSignature \override #'transparent = ##t
135 Accidental \override #'font-magnification = #magfact
136 Rest \override #'font-magnification = #magfact
137 NoteHead \override #'font-magnification = #magfact
138 Stem \override #'transparent = ##t
142 @cindex musical symbols
148 The figure above shows a few notable glyphs. For example, the
149 vertical stem of the flat symbol should be brushed slightly,
150 i.e. becoming wider at the top. the half-notehead is not elliptic but
151 slightly diamond shaped. Fine endings, such as the one on the bottom
152 of the quarter rest, should not end in sharp points, but rather in
153 rounded shapes. Taken together, the blackness of the font must be
154 carefully tuned together with the thickness of lines, beams and slurs
155 to give a strong yet balanced overall impression.
157 Producing a strong and balanced look is the real challenge of music
158 engraving. It is a recurring theme with many variations. In spacing,
159 strength and balance are in layout that is `heavy' enough---without
160 big gaps of space--- and without big clusters of black. The
161 distribution of space should reflect the character of the music.
163 Spacing is an example of a subtlety of formatting music. The distances
164 between notes should reflect the durations between notes, but adhering
165 with mathematical precision to the duration will lead to a poor
166 result. Shown here is an example of a motive, printed twice. It is
167 printed using exact mathematical spacing, and with some
168 corrections. Can you spot which fragment is which?
171 @cindex optical spacing
174 \property Staff.NoteSpacing \set #'stem-spacing-correction
177 \stemDown b'4 e''4 a'4 e''4| \stemBoth
178 \property Staff.NoteSpacing \override #'stem-spacing-correction
180 \property Staff.StaffSpacing \override #'stem-spacing-correction
183 \stemDown b'4 e''4 a'4 e''4|
185 \paper { raggedright = ##t } }
188 @cindex regular rhythms
189 @cindex regular spacing
191 The fragment that was printed uses only quarter notes: notes that are
192 played in a constant rhythm. The spacing should reflect
193 that. Unfortunately, the eye deceives us a little: the eye not only
194 notices the distance between note heads, but also between consecutive
195 stems. As a result, the notes of a up-stem/down-stem combination
196 should be put farther apart, and the notes of a down-up combination
197 should be put closer together, all depending on the combined vertical
198 positions of the notes. The first two measures are printed with this
199 correction, the last two measures without. The notes in the last two
200 measures form down-stem/up-stems clumps of notes.
202 @node Computerized typography
203 @section Computerized typography
205 The example in the previous section is one illustration of how subtle
206 music engraving can be is a subtle. Producing good engraving requires
210 It was our challenge to see if we could put typographical knowledge
211 into a computer program. Capturing that knowledge has two aspects:
212 first, it has to be acquired. Then, it has to be encoded in
213 data-structures and algorithms. As the previous example shows, there
214 is a lot of subtlety involved in music engraving, and unfortunately,
215 only a small fraction of these tiny details are documented.
217 One reason for the time that it takes to become a master engraver, is
218 that all these details must be learned either from experience or from
219 other engravers: as an engraver gets older and wiser, he will be able
220 to produce better and more complex pieces. A similar situation is
221 present when putting typography into computer programs. It is not
222 possible to come up with a final solution for a problem at the first
223 try. Instead, we start out with simple solution that might cover 75%
224 of the cases, and gradually refine that solution over the course of
225 months or years, so that 90 or 95 % of the cases are handled.
227 This has an important implication for the design of the
228 program. During development, almost every piece of formatting code
229 must be considered as temporary. When the need arises, is to be
230 replaced a solution that will cover even more cases. A clean way to
231 accomplish this, is a ``plug-in'' architecture: an architecture where
232 new pieces of code can be inserted in the program dynamically. In
233 such a program, a new solution can be developed along-side the
234 existing code. It can be perfected separately until it is better than
235 the existing solution, at which point, the new solution is switched on
236 by default, and the old one is removed.
238 Until that time, users must have a way to deal with imperfections:
239 these 25%, 10% or 5% of the cases that are not handled
240 automatically. In these cases, a user must be able to override
241 formatting decisions. A way to accomplish this, is to store decisions
242 in generic variables, and let the user manipulate these variables.
243 For example, consider the following fragment of notation.
249 \paper { raggedright = ##t }
254 The position of the forte symbol is slightly awkward, because it is
255 next to the low note, whereas dynamics should be below notes in
256 general. This may be remedied by inserting extra space between the
257 high note and the `f', as shown in this example
261 \once\property Voice. DynamicLineSpanner \override #'padding = #4.0
264 \paper { raggedright = ##t }
268 This was achieved with the input statement
270 \property Voice. DynamicLineSpanner \override #'padding = #4.0
272 which increases the amount of space (@code{padding}) between the note
273 and the dynamic symbol to 4.0 (which is measured in staff space, so
274 4.0 equals the height of a staff).
276 Both design aspects, a plug-in architecture, and formatting variables,
277 are built on top of GUILE, an interpreter for the programming language
278 Scheme, which is a member of the LISP family. Variables are stored as
279 Scheme objects, and attached to graphical objects such as note heads
280 and stems. The variables are a means to adjust formatting details in
281 individual cases, but they are used in a more general manner.
283 Consider the case of a publisher that is not satisfied with the in the
284 default layout, and wants heavier stems. Normally, they are @code{1.3}
285 times the thickness of staff lines, but suppose that their editions
286 require them to be twice the thickness of the staff lines. The same
287 mechanism can be used to adjust a setting globally. By issuing
289 \property Score.Stem \override #'thickness = #2.0
291 the entire piece is formatted with thick stems:
294 \property Score.Stem \override #'thickness = #2.0
295 \once\property Voice. DynamicLineSpanner \override #'padding = #4.0
298 \paper { raggedright = ##t }
303 In effect, by setting these variables, users can define their own
306 ``Plug-ins'' are also implemented using Scheme. A formatting
307 ``plug-in'' takes the form of a function written in Scheme (or a C++
308 function made available as a Scheme function), and it is also stored
309 in a variable. For example, the placement of the forte symbol in the
310 example above is calculated by the function
311 @code{Side_position_interface::aligned_side}. If we want to replace
312 this function by a more advanced one, we could issue
314 \property Voice.DynamicLineSpanner \override #'Y-offset-callbacks
315 = #`(,gee-whiz-gadget)
319 Now, the formatting process will trigger a call to our new
320 @code{gee-whiz-gadget} function when the position of the f symbol has
323 The full scope of this functionality certainly is intimidating, but
324 there is no need to fear: normally, it is not necessary to define
325 style-sheets or rewrite formatting functions. In fact, LilyPond gets a
326 lot of formatting right automatically, so adjusting individual layout
327 situations is not needed very often at all.
330 @node Music representation
331 @section Music representation
334 One of the big questions when writing batch programs, is what kind of
335 input the program should expect. Many music notation programs offer a
336 graphical interface that shows notation, and allow you to enter the
337 music by placing notes on a staff. From our point of view, this design
338 is a form of cheating. After all, the core message of a piece of music
339 notation simply is the music itself. If you start by offering notation
340 to the user, you have already skipped one conversion, even if it is
341 implicit. If we want to generate music notation from something else,
342 then the obvious candidate for the source is the music itself.
344 On paper this theory sounds very good. In practice, it opens a can of
345 worms. What really @emph{is} music? Many philosophical treatises must
346 have been written on the subject. Instead of losing ourselves in
347 philosophical arguments over the essence of music, we have reversed
348 the question to yield a more practical approach. Our assumption is
349 that the printed score contains all of the music of piece. We build a
350 program that uses some input format to produce such a score. Over the
351 course of time, the program evolves. While this happens, we can remove
352 more and more elements of the input format: as the program improves,
353 it can fill in irrelevant details of the input by itself. At some
354 (hypothetical) point, the program is finished: there is no possibility
355 to remove any more elements from the syntax. What we have left is by
356 definition exactly the musical meaning of the score.
358 There are also more practical concerns. Our users have to key in the
359 music into the file directly, so the input format should have a
360 friendly syntax. As programmers and scientists, we want a
361 clean formal definition. After all, producing music notation is a
362 difficult problem, and in the scientific world, problems can only be
363 solved if they are well-specified. Moreover, formally defined formats
364 are easier to write programs for.
366 These ideas shaped our music representation: it is a compact format
367 that can easily be typed by hand. It complex musical constructs from
368 simple entities like notes and rests, in much the same way that one
369 builds complex formulas from simple expressions such as numbers and
370 mathematical operators.
372 @node Example applications
373 @section Example applications
375 As programmers and hedonists we enjoy beauty in code, and code that
376 produces beautiful typeset music, but nevertheless this program can
377 applied to do useful things. In this section, we show a few small
378 examples of what is possible.
380 The simplest application is printing notes.
382 @lilypond[relative=1]
383 \time 2/4 c4 c g'4 g a4 a g2
386 To these notes, chord names and lyrics may be added, yielding
389 @lilypond[raggedright]
391 \context ChordNames \chords { c2 c f2 c }
392 \notes \relative c' { \time 2/4 c4 c g'4 g a4 a g2 }
393 \context Lyrics \lyrics { twin4 kle twin kle lit tle star2 } > }
396 The following example combines some more exotic uses of notation
398 @lilypondfile{screech-boink.ly}
400 The fragments shown above have all been written by hand, but that is not
401 a requirement. Since the formatting engine is mostly automatic, it can
402 serve as an output means for other programs that manipulate music. It
403 can also be used to convert databases of musical fragments to images for
404 use on websites on multimedia presentations.
406 This manual also shows an application: the input format is plain text,
407 and can therefore be easily embedded in other text-based formats, such
408 as La@TeX{}, HTML or in the case of this manual, Texinfo. By means of a
409 special program, the input fragments can be replaced by music images in
410 the resulting PostScript or HTML output files. This makes it easy to
411 mix music and text in documents.
415 @node About this manual
416 @section About this manual
418 The manual is divided into the following chapters
423 @emph{@ref{Tutorial}}
424 gives a gentle introduction into typesetting music.
425 First time users should start here.
430 @emph{@ref{Notation manual}}
431 discusses topics grouped by notation construct.
436 @emph{@ref{Technical manual}}
438 discusses the general design of the program, and how to extend
444 @emph{@ref{Invoking LilyPond}} explains how to run LilyPond and its helper
448 Once you are experienced, you can simply use the manual as reference:
449 there is an extensive index@footnote{If you are looking for something,
450 and you cannot find it by using the index, that is considered a bug.
451 In that case, please file a bug report.}, but the document is also
457 @uref{../lilypond.html, a big HTML page}
459 which can be searched easily using the search facility of a web
461 @cindex search in manual
462 @cindex using the manual
464 @c TODO: advise to buy a book on notation?
466 If you are not familiar with music notation, or music terminology
467 (especially if you are a foreigner), then it is advisable to consult
468 the glossary as well. The glossary explains musical terms, and
469 includes translations to various languages. It is a
471 @uref{../glossary.html,separate document}
474 separate document, available in HTML and PDF and can be printed as
480 @cindex foreign languages
484 This manual is not complete without a number of other documents. They
485 are not available in print, but should be included with the
486 documentation package for your platform
490 Generated internal documentation.
492 available @uref{../lilypond-internals/lilypond-internals.html,here}
495 Almost all formatting functionality that is used internally, is
496 available directly to the user. For example, all variables that
497 control thicknesses, distances, etc, can be changed in input
498 files. There are a huge number of formatting options, and it would be
499 impossible to describe them all in a hand-written manual. The
500 generated internal documentation is a heavily crosslinked HTML
501 document, produced directly from the formatting definitions used. It
502 documents the nit-gritty details of each and every LilyPond class, object and
505 Each section of the reference manual has a @b{See also}
506 subsection, with links (in the HTML document, at least) to the
507 generated documentation.
512 (available @uref{../../../input/templates/out-www/collated-files.html,here})
515 When you have gone through the tutorial, in theory you are able to
516 start writing input files. In practice, writing files from scratch
517 turns out to be intimidating. To give a headstart, we have collected
518 a number of often-used formats in example files. These files can be
519 used as a start, by copying the template, and adding notes in the
523 Various input examples
525 available @uref{../../../input/test/out-www/collated-files.html,here}
529 These small files show various tips and tricks, and are available as a
530 big HTML document, with pictures and explanatory texts included.
536 available @uref{../../../input/regression/out-www/collated-files.html,here}
539 We strive to test each feature in one test file. This collection of is
540 primarily to help us debug problems, but it can be instructive to see
541 how we excercise the program. The format is like the input examples.
546 The location of the documentation files that are mentioned here can
547 vary from system to system. On occasion, this manual refers to
548 initialization and example files. Throughout this manual, we refer to
549 input files relative to the top-directory of the source archive. For
550 example, @file{input/test/bla.ly} may refer to the file
551 @file{lilypond-1.7.19/input/test/bla.ly}. On binary packages for the
552 Unix platform, the documentation and examples can typically be found
553 somewhere below @file{/usr/share/doc/lilypond/}. Initialization files,
554 for example @file{scm/lily.scm}, or @file{ly/engraver-init.ly}, are
555 usually found in the directory @file{/usr/share/lilypond/}.
557 @cindex adjusting output
560 @cindex lilypond-internals
561 @cindex internal documentation
563 @cindex extending lilypond
567 Finally, this and all other manuals, are available online both as PDF
568 files for print and HTML files for browsing. They are available from
569 the web site, which can be found at @uref{http://www.lilypond.org/}.