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.
37 * Computerized typography ::
38 * Music representation::
39 * Example applications::
43 @node Batch processing
44 @section Batch processing
50 LilyPond is a @emph{batch} program. To use, one enters commands in a
51 file, and the program is run on that file. The output is produced
52 without requiring any user-interaction.
54 When we started developing LilyPond, we were still studying at the
55 university. We were interested in music notation, not as publishers
56 or musicians, but as programmers and scientists. We wanted to figure
57 to what extent formatting sheet music could be automated. Back then
58 GUIs were not as ubiquitous as they are today, and we were immersed in
59 the UNIX operating system, where it is very common to use compilers to
60 achieve computing tasks. So, our computerized music engraving
61 experiment took on the form of a compiler.
66 @cindex sharing software
68 You can freely use, modify and redistribute LilyPond. This choice was
69 also motivated by our academic background. In the scientific community
70 it has always been a tradition to share knowledge, also if that
71 knowledge was packaged as software. One of the most visible groups
72 that stimulated this philosophy, was the Free Software Foundation,
73 whose popular GNU project aimed to replace closed and proprietary
74 computing solutions with free (as in ``Libre'') variants. We jumped on
75 that bandwagon, and released LilyPond as free software. That is the
76 reason that you can get LilyPond at no cost and without any strings
82 @section Music engraving
89 Making sheet music may seem trivial at first (``you print 5 lines, and
90 then put in the notes at different heights''), @emph{music engraving},
91 i.e. professional music typography, is in another ballpark. The term
92 `music engraving' derives from the traditional process of music
93 printing. Only a few decades ago, sheet music was made by cutting and
94 stamping the music into zinc or pewter plates, mirrored. The plate
95 would be inked, and the depressions caused by the cutting and stamping
96 would hold ink. An image was formed by pressing paper to the
97 plate. Stamping and cutting was completely done by hand. Making
98 corrections was cumbersome, so engraving had to be done correctly in
99 one go. As you can imagine this was a highly specialized skill, much
100 more so than the traditional process of printing books.
101 @cindex craftsmanship
103 In the traditional German craftsmanship six years of full-time
104 training, more than any other craft, were required before a student
105 could call himself a master of the art. After that many more years of
106 practical experience were needed to become an established music
107 engraver. Even today, with the use of high-speed computers and
108 advanced software, music requires lots of manual fine tuning before it
109 is acceptable for publication.
111 When we wanted to write a computer program to create music typography,
112 we encountered the first problem: there were no sets of musical
113 symbols available: either they were not available freely, or they did
114 not look well to our taste. Not let down, we decided to try font
115 design ourselves. We created a font of musical symbols, relying on
116 nice printouts of hand-engraved music. The experience helped develop
117 a typographical taste, and it made us appreciate subtle design
118 details. Without that experience, we would not have realized the
119 shortcomings of the fonts were that we admired at first.
123 #(define magfact 3.0)
124 \score { \notes { as'2 r4 }
129 AccidentalPlacement \override #'right-padding = #3.0
130 StaffSymbol \override #'transparent = ##t
131 Clef \override #'transparent = ##t
132 TimeSignature \override #'transparent = ##t
133 Accidental \override #'font-magnification = #magfact
134 Rest \override #'font-magnification = #magfact
135 NoteHead \override #'font-magnification = #magfact
136 Stem \override #'transparent = ##t
140 @cindex musical symbols
146 The figure above shows a few notable glyphs. For example, the
147 vertical stem of the flat symbol should be brushed slightly,
148 i.e. becoming wider at the top. the half-notehead is not elliptic but
149 slightly diamond shaped. Fine endings, such as the one on the bottom
150 of the quarter rest, should not end in sharp points, but rather in
151 rounded shapes. Taken together, the blackness of the font must be
152 carefully tuned together with the thickness of lines, beams and slurs
153 to give a strong yet balanced overall impression.
155 Producing a strong and balanced look is the real challenge of music
156 engraving. It is a recurring theme with many variations. In spacing,
157 strength and balance are in layout that is `heavy' enough---without
158 big gaps of space--- and without big clusters of black. The
159 distribution of space should reflect the character of the music.
161 Spacing is an example of a subtlety of formatting music. The distances
162 between notes should reflect the durations between notes, but adhering
163 with mathematical precision to the duration will lead to a poor
164 result. Shown here is an example of a motive, printed twice. It is
165 printed using exact mathematical spacing, and with some
166 corrections. Can you spot which fragment is which?
169 @cindex optical spacing
172 \property Staff.NoteSpacing \set #'stem-spacing-correction
175 \stemDown b'4 e''4 a'4 e''4| \stemBoth
176 \property Staff.NoteSpacing \override #'stem-spacing-correction
178 \property Staff.StaffSpacing \override #'stem-spacing-correction
181 \stemDown b'4 e''4 a'4 e''4|
183 \paper { raggedright = ##t } }
186 @cindex regular rhythms
187 @cindex regular spacing
189 The fragment that was printed uses only quarter notes: notes that are
190 played in a constant rhythm. The spacing should reflect
191 that. Unfortunately, the eye deceives us a little: the eye not only
192 notices the distance between note heads, but also between consecutive
193 stems. As a result, the notes of a up-stem/down-stem combination
194 should be put farther apart, and the notes of a down-up combination
195 should be put closer together, all depending on the combined vertical
196 positions of the notes. The first two measures are printed with this
197 correction, the last two measures without. The notes in the last two
198 measures form down-stem/up-stems clumps of notes.
200 @node Computerized typography
201 @section Computerized typography
203 The example in the previous section is one illustration of how subtle
204 music engraving can be is a subtle. Producing good engraving requires
208 It was our challenge to see if we could put typographical knowledge
209 into a computer program. Capturing that knowledge has two aspects:
210 first, it has to be acquired. Then, it has to be encoded in
211 data-structures and algorithms. As the previous example shows, there
212 is a lot of subtlety involved in music engraving, and unfortunately,
213 only a small fraction of these tiny details are documented.
215 One reason for the time that it takes to become a master engraver, is
216 that all these details must be learned either from experience or from
217 other engravers: as an engraver gets older and wiser, he will be able
218 to produce better and more complex pieces. A similar situation is
219 present when putting typography into computer programs. It is not
220 possible to come up with a final solution for a problem at the first
221 try. Instead, we start out with simple solution that might cover 75%
222 of the cases, and gradually refine that solution over the course of
223 months or years, so that 90 or 95 % of the cases are handled.
225 This has an important implication for the design of the
226 program. During development, almost every piece of formatting code
227 must be considered as temporary. When the need arises, is to be
228 replaced a solution that will cover even more cases. A clean way to
229 accomplish this, is a ``plug-in'' architecture: an architecture where
230 new pieces of code can be inserted in the program dynamically. In
231 such a program, a new solution can be developed along-side the
232 existing code. It can be perfected separately until it is better than
233 the existing solution, at which point, the new solution is switched on
234 by default, and the old one is removed.
236 Until that time, users must have a way to deal with imperfections:
237 these 25%, 10% or 5% of the cases that are not handled
238 automatically. In these cases, a user must be able to override
239 formatting decisions. A way to accomplish this, is to store decisions
240 in generic variables, and let the user manipulate these variables.
241 For example, consider the following fragment of notation.
247 \paper { raggedright = ##t }
252 The position of the forte symbol is slightly awkward, because it is
253 next to the low note, whereas dynamics should be below notes in
254 general. This may be remedied by inserting extra space between the
255 high note and the `f', as shown in this example
259 \once\property Voice. DynamicLineSpanner \override #'padding = #4.0
262 \paper { raggedright = ##t }
266 This was achieved with the input statement
268 \property Voice. DynamicLineSpanner \override #'padding = #4.0
270 which increases the amount of space (@code{padding}) between the note
271 and the dynamic symbol to 4.0 (which is measured in staff space, so
272 4.0 equals the height of a staff).
274 Both design aspects, a plug-in architecture, and formatting variables,
275 are built on top of GUILE, an interpreter for the programming language
276 Scheme, which is a member of the LISP family. Variables are stored as
277 Scheme objects, and attached to graphical objects such as note heads
278 and stems. The variables are a means to adjust formatting details in
279 individual cases, but they are used in a more general manner.
281 Consider the case of a publisher that is not satisfied with the in the
282 default layout, and wants heavier stems. Normally, they are @code{1.3}
283 times the thickness of staff lines, but suppose that their editions
284 require them to be twice the thickness of the staff lines. The same
285 mechanism can be used to adjust a setting globally. By issuing
287 \property Score.Stem \override #'thickness = #2.0
289 the entire piece is formatted with thick stems:
292 \once\property Voice. DynamicLineSpanner \override #'padding = #4.0
295 \paper { raggedright = ##t }
300 In effect, by setting these variables, users can define their own
303 ``Plug-ins'' are also implemented using Scheme. A formatting
304 ``plug-in'' takes the form of a function written in Scheme (or a C++
305 function made available as a Scheme function), and it is also stored
306 in a variable. For example, the placement of the forte symbol in the
307 example above is calculated by the function
308 @code{Side_position_interface::aligned_side}. If we want to replace
309 this function by a more advanced one, we could issue
311 \property Voice.DynamicLineSpanner \override #'Y-offset-callbacks
312 = #`(,gee-whiz-gadget)
316 Now, the formatting process will trigger a call to our new
317 @code{gee-whiz-gadget} function when the position of the f symbol has
320 The full scope of this functionality certainly is intimidating, but
321 there is no need to fear: normally, it is not necessary to define
322 style-sheets or rewrite formatting functions. In fact, LilyPond gets a
323 lot of formatting right automatically, so adjusting individual layout
324 situations is not needed very often.
327 @node Music representation
328 @section Music representation
331 One of the big questions when writing batch programs, is what kind of
332 input the program should expect. Many music notation programs offer a
333 graphical interface that shows notation, and allow you to enter the
334 music by placing notes on a staff. From our point of view, this design
335 is a form of cheating. After all, the core message of a piece of music
336 notation simply is the music itself. If you start by offering notation
337 to the user, you have already skipped one conversion, even if it is
338 implicit. If we want to generate music notation from something else,
339 then the obvious candidate for the source is the music itself.
341 On paper this theory sounds very good. In practice, it opens a can of
342 worms. What really @emph{is} music? Many philosophical treatises must
343 have been written on the subject. Instead of losing ourselves in
344 philosophical arguments over the essence of music, we have reversed
345 the question to yield a more practical approach. Our assumption is
346 that the printed score contains all of the music of piece. We build a
347 program that uses some input format to produce such a score. Over the
348 course of time, the program evolves. While this happens, we can remove
349 more and more elements of the input format: as the program improves,
350 it can fill in irrelevant details of the input by itself. At some
351 (hypothetical) point, the program is finished: there is no possibility
352 to remove any more elements from the syntax. What we have left is by
353 definition exactly the musical meaning of the score.
355 There are also more practical concerns. Our users have to key in the
356 music into the file directly, so the input format should have a
357 friendly syntax. As programmers and scientists, we want a
358 clean formal definition. After all, producing music notation is a
359 difficult problem, and in the scientific world, problems can only be
360 solved if they are well-specified. Moreover, formally defined formats
361 are easier to write programs for.
363 These ideas shaped our music representation: it is a compact format
364 that can easily be typed by hand. It complex musical constructs from
365 simple entities like notes and rests, in much the same way that one
366 builds complex formulas from simple expressions such as numbers and
367 mathematical operators.
369 @node Example applications
370 @section Example applications
372 As programmers and hedonists we enjoy beauty in code, and code that
373 produces beautiful typeset music, but nevertheless this program can
374 applied to do useful things. In this section, we show a few small
375 examples of what is possible.
377 The simplest application is printing notes.
379 @lilypond[relative=1]
380 \time 2/4 c4 c g'4 g a4 a g2
383 To these notes, chord names and lyrics may be added, yielding
386 @lilypond[raggedright]
388 \context ChordNames \chords { c2 c f2 c }
389 \notes \relative c' { \time 2/4 c4 c g'4 g a4 a g2 }
390 \context Lyrics \lyrics { twin4 kle twin kle lit tle star2 } > }
393 The following example combines some more exotic uses of notation
395 @lilypondfile{screech-boink.ly}
400 @node About this manual
401 @section About this manual
403 The manual is divided into the following chapters
408 @emph{@ref{Tutorial}}
409 gives a gentle introduction into typesetting music.
410 First time users should start here.
415 @emph{@ref{Notation manual}}
416 discusses topics grouped by notation construct.
421 @emph{@ref{Technical manual}}
423 discusses the general design of the program, and how to extend
429 @emph{@ref{Invoking LilyPond}} explains how to run LilyPond and its helper
433 Once you are experienced, you can simply use the manual as reference:
434 there is an extensive index@footnote{If you are looking for something,
435 and you cannot find it by using the index, that is considered a bug.
436 In that case, please file a bug report}, but the document is also
442 @uref{../lilypond.html, a big HTML page}
444 which can be searched easily using the search facility of a web
446 @cindex search in manual
447 @cindex using the manual
450 If you are not familiar with music notation, or music terminology
451 (especially if you are a foreigner), then it is advisable to consult
452 the glossary as well. The glossary explains musical terms, and
453 includes translations to various languages. It is a
455 @uref{../glossary.html,separate document}
458 separate document, available in HTML and PDF and can be printed as
464 @cindex foreign languages
468 This manual is not complete without a number of other documents. They
469 are not available in print, but should be included with the
470 documentation package for your platform
474 Generated internal documentation.
476 available @uref{../lilypond-internals/lilypond-internals.html,here}
479 Almost all formatting functionality that is used internally, is
480 available directly to the user. For example, all variables that
481 control thicknesses, distances, etc, can be changed in input
482 files. There are a huge number of formatting options, and it would be
483 impossible to describe them all in a hand-written manual. The
484 generated internal documentation is a heavily crosslinked HTML
485 document, produced directly from the formatting definitions used. It
486 documents the nit-gritty details of each and every LilyPond class, object and
489 Each section of the reference manual has a @b{See also}
490 subsection, with links (in the HTML document, at least) to the
491 generated documentation.
496 (available @uref{../../../input/templates/out-www/collated-files.html,here})
499 When you have gone through the tutorial, in theory you are able to
500 start writing input files. In practice, writing files from scratch
501 turns out to be intimidating. To give a headstart, we have collected
502 a number of often-used formats in example files. These files can be
503 used as a start, by copying the template, and adding notes in the
507 Various input examples
509 available @uref{../../../input/test/out-www/collated-files.html,here}
513 These small files show various tips and tricks, and are available as a
514 big HTML document, with pictures and explanatory texts included.
520 available @uref{../../../input/regression/out-www/collated-files.html,here}
523 We strive to test each feature in one test file. This collection of is
524 primarily to help us debug problems, but it can be instructive to see
525 how we excercise the program. The format is like the input examples.
530 The location of the documentation files that are mentioned here can
531 vary from system to system. On occasion, this manual refers to
532 initialization and example files. Throughout this manual, we refer to
533 input files relative to the top-directory of the source archive. For
534 example, @file{input/test/bla.ly} may refer to the file
535 @file{lilypond-1.7.19/input/test/bla.ly}. On binary packages for the
536 Unix platform, the documentation and examples can typically be found
537 somewhere below @file{/usr/share/doc/lilypond/}. Initialization files,
538 for example @file{scm/lily.scm}, or @file{ly/engraver-init.ly}, are
539 usually found in the directory @file{/usr/share/lilypond/}.
541 @cindex adjusting output
544 @cindex lilypond-internals
545 @cindex internal documentation
547 @cindex extending lilypond
551 Finally, this and all other manuals, are available online both as PDF
552 files for print and HTML files for browsing. They are available from
553 the web site, which can be found at @uref{http://www.lilypond.org/}.