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. If you
9 regularly from both recent and old music, you can probably agree with
10 us on that. Most computer printouts have a bland, mechanical look,
11 and are unpleasant to play from. Musicians are usually more absorbed
12 with performing the music than with studying its looks, so they
13 usually cannot pinpoint what exactly is so disconcerting about
16 However, it only takes a little attention to see for yourself what is
17 what the differences are. The procedure is easy. Find two editions of
18 the same piece, an old edition a reputable publishing house, and one
19 which is formatted with a computer. If you are unsure, both can be
20 told apart easily. Traditional hand-work has slight variations in
21 symbol placements, while computer programs repeat all their errors in
22 placement with iron rigidity. To illustrate this, we show two scanned
23 fragments of the same piece, the first Cello Suite by Johann Sebastian
24 Bach. The top one was hand made (published in 1950 by
25 B@"{a}renreiter), while the bottom one was computer made (published in
30 @image{baer-suite1-line,15cm}
32 @image{henle-suite1-line,15.3cm}
37 <img src="baer-suite1-line.png">
39 <img src="henle-suite1-line.png">
46 The fragments come from different editions, so there are some
47 editorial differences regarding the slurs. However, we want to compare
48 the typography of both. We can see that the Henle edition looks
49 mechanical. This is caused by lack of variation in the spacing: the
50 note heads in both systems are on the same horizontal positions, as is
51 the bar line. A second difference is in the blackness of the page: the
52 B@"{a}renreiter has a stronger look, simply because it uses a heavier
53 font, and thicker staff lines. In the printed editions, the Henle
54 version is 7 mm wider (approximately 4 %). Often, this difference is
55 larger: computer scores tend to be spaced very widely, thus putting
56 less information on a page, on average. Besides these global
57 characteristics, software also make errors in the details. Beams
58 should normally completely cover staff lines. In this case, the
59 programmers have tried to do so, but forgot to take into account the
60 thickness of the staff lines. The result is that the endings of all
61 sloped beams are wedge-formed. The effect is subtle, it may not show
62 up in this reproduction due to limits of the resolution, but it is
63 certainly noticeable in the original.
65 Looking at such detail to the formatting of a score certainly is
66 nitpicky. However, all these details serve a purpose, and that is to
67 help the musician perform better: variation in spacing give each line
68 a unique, which helps you remember where you are when you look
69 away. Boldly print notes stand out more clearly when viewed from a
70 distance. Tightly spaced scores take up less pages, which reduces the
71 frequency of page turns. Correctly formatted beams and slurs indicate
72 the direction of music, and without distracting the reader with
73 unnecessary clusters of ink. Clearly, good music typography is
76 What is wrong with other computer printed scores?
80 Music notation vs. Engraving. (vs. composing)
82 Why do you care about engraving?
84 Why would I care about engraving?
86 You say your program is special; you must be trying to sell it?
90 Preserving/reinventing the art of engraving
92 Typography in LilyPond.
94 Input format. Issue is overrated.
102 LilyPond is a program to print sheet music. If you have used notation
103 programs before, then the way to use this program might be surprising
104 at first sight: in order to print music you have to enter musical
105 codes in a file. Then you run the program on the file, and the music
106 is produced without any further intervention. For example, something
110 @lilypond[fragment,verbatim, relative 1, intertext="produces this:
113 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
116 @cindex encoding music
118 Encoding music using letters and digits may appear strange,
119 intimidating or even clumsy at first. Nevertheless, when you take the
120 effort to learn the codes and the program you will find that it is
121 easier than it seems. Entering music can be done quickly, and you
122 never have to remember how you made the program do something
123 complicated: it is all in the input code, and you only have to read
124 the file to see how it works. Moreover, you are rewarded with very
125 nicely looking output.
127 In this chapter, we will explain the reasoning behind this unusual
128 design, and how this approach affects you as a user.
134 * Computerized typography::
135 * Music representation::
136 * Example applications::
137 * About this manual::
140 @node Music engraving
141 @section Music engraving
148 Making sheet music may seem trivial at first (``you print 5 lines, and
149 then put in the notes at different heights''),
154 @emph{music engraving}, i.e. professional music typography, is in
155 another ballpark. The term `music engraving' derives from the
156 traditional process of music printing. Only a few decades ago, sheet
157 music was made by cutting and stamping the music into zinc or pewter
158 plates, mirrored. The plate would be inked, and the depressions caused
159 by the cutting and stamping would hold ink. An image was formed by
160 pressing paper to the plate. Stamping and cutting was completely done
161 by hand. Making corrections was cumbersome, so engraving had to be
162 done correctly in one go. As you can imagine this was a highly
163 specialized skill, much more so than the traditional process of
165 @cindex craftsmanship
167 In the traditional German craftsmanship six years of full-time
168 training, more than any other craft, were required before a student
169 could call himself a master of the art. After that many more years of
170 practical experience were needed to become an established music
171 engraver. Even today, with the use of high-speed computers and
172 advanced software, music requires lots of manual fine tuning before it
173 is acceptable for publication.
175 When we wanted to write a computer program to create music typography,
176 we encountered the first problem: there were no sets of musical
177 symbols available: either they were not available freely, or they did
178 not look well to our taste. Not let down, we decided to try font
179 design ourselves. We created a font of musical symbols, relying on
180 nice printouts of hand-engraved music. The experience helped develop
181 a typographical taste, and it made us appreciate subtle design
182 details. Without that experience, we would not have realized the
183 shortcomings of the fonts were that we admired at first.
187 #(define magfact 3.0)
188 \score { \notes { as'2 r4 }
193 AccidentalPlacement \override #'right-padding = #3.0
194 StaffSymbol \override #'transparent = ##t
195 Clef \override #'transparent = ##t
196 TimeSignature \override #'transparent = ##t
197 Accidental \override #'font-magnification = #magfact
198 Rest \override #'font-magnification = #magfact
199 NoteHead \override #'font-magnification = #magfact
200 Stem \override #'transparent = ##t
204 @cindex musical symbols
210 The figure above shows a few notable glyphs. For example, the
211 vertical stem of the flat symbol should be brushed slightly,
212 i.e. becoming wider at the top. the half-notehead is not elliptic but
213 slightly diamond shaped. Fine endings, such as the one on the bottom
214 of the quarter rest, should not end in sharp points, but rather in
215 rounded shapes. Taken together, the blackness of the font must be
216 carefully tuned together with the thickness of lines, beams and slurs
217 to give a strong yet balanced overall impression.
219 Producing a strong and balanced look is the real challenge of music
220 engraving. It is a recurring theme with many variations. In spacing,
221 strength and balance are in layout that is `heavy' enough---without
222 big gaps of space--- and without big clusters of black. The
223 distribution of space should reflect the character of the music.
225 Spacing is an example of a subtlety of formatting music. The distances
226 between notes should reflect the durations between notes, but adhering
227 with mathematical precision to the duration will lead to a poor
228 result. Shown here is an example of a motive, printed twice. It is
229 printed using exact mathematical spacing, and with some
230 corrections. Can you spot which fragment is which?
233 @cindex optical spacing
236 \property Staff.NoteSpacing \set #'stem-spacing-correction
239 \stemDown b'4 e''4 a'4 e''4| \stemBoth
240 \property Staff.NoteSpacing \override #'stem-spacing-correction
242 \property Staff.StaffSpacing \override #'stem-spacing-correction
245 \stemDown b'4 e''4 a'4 e''4|
247 \paper { raggedright = ##t } }
250 @cindex regular rhythms
251 @cindex regular spacing
253 The fragment that was printed uses only quarter notes: notes that are
254 played in a constant rhythm. The spacing should reflect
255 that. Unfortunately, the eye deceives us a little: the eye not only
256 notices the distance between note heads, but also between consecutive
257 stems. As a result, the notes of a up-stem/down-stem combination
258 should be put farther apart, and the notes of a down-up combination
259 should be put closer together, all depending on the combined vertical
260 positions of the notes. The first two measures are printed with this
261 correction, the last two measures without. The notes in the last two
262 measures form down-stem/up-stems clumps of notes.
264 @node Computerized typography
265 @section Computerized typography
267 The example in the previous section is one illustration of how subtle
268 music engraving can be is a subtle. Producing good engraving requires
272 It was our challenge to see if we could put typographical knowledge
273 into a computer program. Capturing that knowledge has two aspects:
274 first, it has to be acquired. Then, it has to be encoded in
275 data-structures and algorithms. As the previous example shows, there
276 is a lot of subtlety involved in music engraving, and unfortunately,
277 only a small fraction of these tiny details are documented.
279 One reason for the time that it takes to become a master engraver, is
280 that all these details must be learned either from experience or from
281 other engravers: as an engraver gets older and wiser, he will be able
282 to produce better and more complex pieces. A similar situation is
283 present when putting typography into computer programs. It is not
284 possible to come up with a final solution for a problem at the first
285 try. Instead, we start out with simple solution that might cover 75%
286 of the cases, and gradually refine that solution over the course of
287 months or years, so that 90 or 95 % of the cases are handled.
289 This has an important implication for the design of the
290 program. During development, almost every piece of formatting code
291 must be considered as temporary. When the need arises, is to be
292 replaced a solution that will cover even more cases. A clean way to
293 accomplish this, is a ``plug-in'' architecture: an architecture where
294 new pieces of code can be inserted in the program dynamically. In
295 such a program, a new solution can be developed along-side the
296 existing code. It can be perfected separately until it is better than
297 the existing solution, at which point, the new solution is switched on
298 by default, and the old one is removed.
300 Until that time, users must have a way to deal with imperfections:
301 these 25%, 10% or 5% of the cases that are not handled
302 automatically. In these cases, a user must be able to override
303 formatting decisions. A way to accomplish this, is to store decisions
304 in generic variables, and let the user manipulate these variables.
305 For example, consider the following fragment of notation.
311 \paper { raggedright = ##t }
316 The position of the forte symbol is slightly awkward, because it is
317 next to the low note, whereas dynamics should be below notes in
318 general. This may be remedied by inserting extra space between the
319 high note and the `f', as shown in this example
323 \once\property Voice. DynamicLineSpanner \override #'padding = #4.0
326 \paper { raggedright = ##t }
330 This was achieved with the input statement
332 \property Voice. DynamicLineSpanner \override #'padding = #4.0
334 which increases the amount of space (@code{padding}) between the note
335 and the dynamic symbol to 4.0 (which is measured in staff space, so
336 4.0 equals the height of a staff).
338 Both design aspects, a plug-in architecture, and formatting variables,
339 are built on top of GUILE, an interpreter for the programming language
340 Scheme, which is a member of the LISP family. Variables are stored as
341 Scheme objects, and attached to graphical objects such as note heads
342 and stems. The variables are a means to adjust formatting details in
343 individual cases, but they are used in a more general manner.
345 Consider the case of a publisher that is not satisfied with the in the
346 default layout, and wants heavier stems. Normally, they are @code{1.3}
347 times the thickness of staff lines, but suppose that their editions
348 require them to be twice the thickness of the staff lines. The same
349 mechanism can be used to adjust a setting globally. By issuing
351 \property Score.Stem \override #'thickness = #2.0
353 the entire piece is formatted with thick stems:
356 \property Score.Stem \override #'thickness = #2.0
357 \once\property Voice. DynamicLineSpanner \override #'padding = #4.0
360 \paper { raggedright = ##t }
365 In effect, by setting these variables, users can define their own
368 ``Plug-ins'' are also implemented using Scheme. A formatting
369 ``plug-in'' takes the form of a function written in Scheme (or a C++
370 function made available as a Scheme function), and it is also stored
371 in a variable. For example, the placement of the forte symbol in the
372 example above is calculated by the function
373 @code{Side_position_interface::aligned_side}. If we want to replace
374 this function by a more advanced one, we could issue
376 \property Voice.DynamicLineSpanner \override #'Y-offset-callbacks
377 = #`(,gee-whiz-gadget)
381 Now, the formatting process will trigger a call to our new
382 @code{gee-whiz-gadget} function when the position of the f symbol has
385 The full scope of this functionality certainly is intimidating, but
386 there is no need to fear: normally, it is not necessary to define
387 style-sheets or rewrite formatting functions. In fact, LilyPond gets a
388 lot of formatting right automatically, so adjusting individual layout
389 situations is not needed very often at all.
392 @node Music representation
393 @section Music representation
396 One of the big questions when writing batch programs, is what kind of
397 input the program should expect. Many music notation programs offer a
398 graphical interface that shows notation, and allow you to enter the
399 music by placing notes on a staff. From our point of view, this design
400 is a form of cheating. After all, the core message of a piece of music
401 notation simply is the music itself. If you start by offering notation
402 to the user, you have already skipped one conversion, even if it is
403 implicit. If we want to generate music notation from something else,
404 then the obvious candidate for the source is the music itself.
406 On paper this theory sounds very good. In practice, it opens a can of
407 worms. What really @emph{is} music? Many philosophical treatises must
408 have been written on the subject. Instead of losing ourselves in
409 philosophical arguments over the essence of music, we have reversed
410 the question to yield a more practical approach. Our assumption is
411 that the printed score contains all of the music of piece. We build a
412 program that uses some input format to produce such a score. Over the
413 course of time, the program evolves. While this happens, we can remove
414 more and more elements of the input format: as the program improves,
415 it can fill in irrelevant details of the input by itself. At some
416 (hypothetical) point, the program is finished: there is no possibility
417 to remove any more elements from the syntax. What we have left is by
418 definition exactly the musical meaning of the score.
420 There are also more practical concerns. Our users have to key in the
421 music into the file directly, so the input format should have a
422 friendly syntax. As programmers and scientists, we want a
423 clean formal definition. After all, producing music notation is a
424 difficult problem, and in the scientific world, problems can only be
425 solved if they are well-specified. Moreover, formally defined formats
426 are easier to write programs for.
428 These ideas shaped our music representation: it is a compact format
429 that can easily be typed by hand. It complex musical constructs from
430 simple entities like notes and rests, in much the same way that one
431 builds complex formulas from simple expressions such as numbers and
432 mathematical operators.
434 @node Example applications
435 @section Example applications
437 As programmers and hedonists we enjoy beauty in code, and code that
438 produces beautiful typeset music, but nevertheless this program can
439 applied to do useful things. In this section, we show a few small
440 examples of what is possible.
442 The simplest application is printing notes.
444 @lilypond[relative=1]
445 \time 2/4 c4 c g'4 g a4 a g2
448 To these notes, chord names and lyrics may be added, yielding
451 @lilypond[raggedright]
453 \context ChordNames \chords { c2 c f2 c }
454 \notes \relative c' { \time 2/4 c4 c g'4 g a4 a g2 }
455 \context Lyrics \lyrics { twin4 kle twin kle lit tle star2 } > }
458 The following example combines some more exotic uses of notation
460 @lilypondfile{screech-boink.ly}
462 The fragments shown above have all been written by hand, but that is not
463 a requirement. Since the formatting engine is mostly automatic, it can
464 serve as an output means for other programs that manipulate music. It
465 can also be used to convert databases of musical fragments to images for
466 use on websites on multimedia presentations.
468 This manual also shows an application: the input format is plain text,
469 and can therefore be easily embedded in other text-based formats, such
470 as La@TeX{}, HTML or in the case of this manual, Texinfo. By means of a
471 special program, the input fragments can be replaced by music images in
472 the resulting PostScript or HTML output files. This makes it easy to
473 mix music and text in documents.
477 @node About this manual
478 @section About this manual
480 The manual is divided into the following chapters
485 @emph{@ref{Tutorial}}
486 gives a gentle introduction into typesetting music.
487 First time users should start here.
492 @emph{@ref{Notation manual}}
493 discusses topics grouped by notation construct.
498 @emph{@ref{Technical manual}}
500 discusses the general design of the program, and how to extend
506 @emph{@ref{Invoking LilyPond}} explains how to run LilyPond and its helper
510 Once you are experienced, you can simply use the manual as reference:
511 there is an extensive index@footnote{If you are looking for something,
512 and you cannot find it by using the index, that is considered a bug.
513 In that case, please file a bug report.}, but the document is also
519 @uref{../lilypond.html, a big HTML page}
521 which can be searched easily using the search facility of a web
523 @cindex search in manual
524 @cindex using the manual
526 @c TODO: advise to buy a book on notation?
528 If you are not familiar with music notation, or music terminology
529 (especially if you are a foreigner), then it is advisable to consult
530 the glossary as well. The glossary explains musical terms, and
531 includes translations to various languages. It is a
533 @uref{../glossary.html,separate document}
536 separate document, available in HTML and PDF and can be printed as
542 @cindex foreign languages
546 This manual is not complete without a number of other documents. They
547 are not available in print, but should be included with the
548 documentation package for your platform
552 Generated internal documentation.
554 available @uref{../lilypond-internals/lilypond-internals.html,here}
557 Almost all formatting functionality that is used internally, is
558 available directly to the user. For example, all variables that
559 control thicknesses, distances, etc, can be changed in input
560 files. There are a huge number of formatting options, and it would be
561 impossible to describe them all in a hand-written manual. The
562 generated internal documentation is a heavily crosslinked HTML
563 document, produced directly from the formatting definitions used. It
564 documents the nit-gritty details of each and every LilyPond class, object and
567 Each section of the reference manual has a @b{See also}
568 subsection, with links (in the HTML document, at least) to the
569 generated documentation.
574 (available @uref{../../../input/templates/out-www/collated-files.html,here})
577 When you have gone through the tutorial, in theory you are able to
578 start writing input files. In practice, writing files from scratch
579 turns out to be intimidating. To give a headstart, we have collected
580 a number of often-used formats in example files. These files can be
581 used as a start, by copying the template, and adding notes in the
585 Various input examples
587 available @uref{../../../input/test/out-www/collated-files.html,here}
591 These small files show various tips and tricks, and are available as a
592 big HTML document, with pictures and explanatory texts included.
598 available @uref{../../../input/regression/out-www/collated-files.html,here}
601 We strive to test each feature in one test file. This collection of is
602 primarily to help us debug problems, but it can be instructive to see
603 how we excercise the program. The format is like the input examples.
608 The location of the documentation files that are mentioned here can
609 vary from system to system. On occasion, this manual refers to
610 initialization and example files. Throughout this manual, we refer to
611 input files relative to the top-directory of the source archive. For
612 example, @file{input/test/bla.ly} may refer to the file
613 @file{lilypond-1.7.19/input/test/bla.ly}. On binary packages for the
614 Unix platform, the documentation and examples can typically be found
615 somewhere below @file{/usr/share/doc/lilypond/}. Initialization files,
616 for example @file{scm/lily.scm}, or @file{ly/engraver-init.ly}, are
617 usually found in the directory @file{/usr/share/lilypond/}.
619 @cindex adjusting output
622 @cindex lilypond-internals
623 @cindex internal documentation
625 @cindex extending lilypond
629 Finally, this and all other manuals, are available online both as PDF
630 files for print and HTML files for browsing. They are available from
631 the web site, which can be found at @uref{http://www.lilypond.org/}.