1 @c -*- coding: utf-8; mode: texinfo; -*-
4 Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
6 When revising a translation, copy the HEAD committish of the
7 version that you are working on. For details, see the Contributors'
8 Guide, node Updating translation committishes..
14 @chapter Music engraving
16 This essay describes why LilyPond was created and how it can produce
17 such beautiful sheet music.
20 @c remove 3mm eps bounding box left padding for Sarabande (This will
21 @c require adding a new snippet option to lilypond-book.py
22 @c check formatting of HTML output
25 @c Incorrect beaming in the Sarabande is a known bug.
28 * The LilyPond story::
30 * Automated engraving::
31 * What symbols to engrave?::
32 * Music representation::
33 * Example applications::
37 @node The LilyPond story
38 @unnumberedsec The LilyPond story
40 Long before LilyPond had been used to engrave beautiful performance
41 scores, before it could create university course notes or even simple
42 melodies, before there was a community of users around the world or even
43 an essay on music engraving, LilyPond began with a question:
46 Why does most computer output fail to achieve the beauty and balance of
47 a hand-engraved score?
51 Some of the answers can be found by examining the two scores
56 on the following pages.
58 The first score is a beautiful hand-engraved score from 1950 and the
59 second is a modern, computer-engraved edition.
64 Bärenreiter BA 320, @copyright{}1950:
66 @sourceimage{baer-suite1-fullpage,,,png}
71 Henle no. 666, @copyright{}2000:
73 @sourceimage{henle-suite1-fullpage,,,png}
77 The notes here are identical, taken from Bach's first Suite for solo
78 cello, but the appearance is different, especially if you print them out
79 and view them from a distance.
81 (The PDF version of this manual has high-resolution images suitable for
84 Try reading or playing from each of the scores and you will find that
85 the hand-engraved score is more enjoyable to use. It has flowing lines
86 and movement, and it feels like a living, breathing piece of music,
87 while the newer edition seems cold and mechanical.
89 It is kind of hard to immediately see what makes the difference with the
90 newer edition. Everything looks neat and tiny, possibly even @qq{better}
91 because it looks more computerized and uniform. This really puzzled us
92 for quite a while. We wanted to improve computer notation, but we first
93 had to figure out what was wrong with it.
95 The answer lies in the precise, mathematical uniformity of the newer
96 edition. Find the bar line in the middle of each line: in the
97 hand-engraved score the position of these bar lines has some
98 natural variation, while in the newer version they line up almost
99 perfectly. This is shown in these simplified page layout diagrams,
100 traced from the hand-engraved (left) and computer-generated music
105 @sourceimage{pdf/page-layout-comparison,,,}
108 @sourceimage{page-layout-comparison,,,png}
113 In the computer-generated output, even the individual note heads are
114 aligned in vertical columns, making the contour of the melody disappear
115 into a rigid grid of musical markings.
117 There are other differences as well: in the hand-engraved edition the
118 vertical lines are all stronger, the slurs lie closer to the note heads,
119 and there is more visual variety in the placement of the beams. Although
120 such details may seem like nitpicking, the result is a score that is
121 easier to read. In the computer-generated output, each line is nearly
122 identical and if the musician looks away for a moment, she will be lost
125 LilyPond was designed to solve the problems we found in existing
126 software and to create beautiful music that mimics the finest
127 hand-engraved scores. Along the way, we have learned a great deal about
128 the work that goes into a well-engraved score. In this essay we describe
129 several of those aspects that we have tried to imitate in LilyPond.
134 Bärenreiter BA 320, @copyright{}1950:
136 @sourceimage{baer-suite1-fullpage-hires,16cm,,}
139 Henle no. 666, @copyright{}2000:
141 @sourceimage{henle-suite1-fullpage-hires,16cm,,}
145 @node Engraving details
146 @unnumberedsec Engraving details
149 @cindex typography, music
150 @cindex music typography
151 @cindex plate engraving
152 @cindex music engraving
154 The art of music typography is called @emph{(plate) engraving}, a term
155 that derives from the manual process of music printing@footnote{Early
156 European printers explored several processes, including hand-carved
157 wooden blocks, movable type, and engraved sheets of thin metal.
158 Typesetting had the advantage of being more easily corrected and
159 facilitating the inclusion of text and lyrics, but only engraving
160 offered the ability to do unimpeded layout and unanticipated notation.
161 In the end, hand-engraved scores became the standard for all printed
162 music, with the exception of some hymnals and songbooks where
163 typesetting was justified by its ease and economy, even into the
164 twentieth century.}. Just a few decades ago, sheet music was made by
165 cutting and stamping the music into a zinc or pewter plate in mirror
166 image. The plate would be inked, and the depressions caused by the
167 cutting and stamping would hold ink. An image was formed by pressing
168 paper to the plate. The stamping and cutting was done completely by hand
169 and making a correction was cumbersome, so the engraving had to be
170 nearly perfect in one go. Engraving was a highly specialized skill; a
171 craftsman had to complete around five years of training before earning
172 the title of master engraver, and another five years of experience were
173 necessary to become truly skilled.
177 @sourceimage{hader-slaan,,7cm,}
180 @sourceimage{hader-slaan,,,jpg}
184 LilyPond is inspired by traditional manual engravings published by
185 European music publishers in and towards the end of the first half of
186 the twentieth century, including Bärenreiter, Duhem, Durand,
187 Hofmeister, Peters, and Schott. This is sometimes regarded as the peak
188 of traditional musical engraving practice.
190 @c Now all newly printed music is produced with computers. This has
191 @c obvious advantages: prints are cheaper to make, editorial work can be
192 @c delivered by email, and the original data can be easily stored.
193 @c Unfortunately, computer-generated scores rarely match the quality of
194 @c hand-engraved scores. Instead, computer printouts have a bland,
195 @c mechanical look, which makes them unpleasant to play from.
202 * Why work so hard?::
206 @unnumberedsubsec Music fonts
208 The images below illustrate some differences between traditional
209 engraving and typical computer output. The left picture shows a scan of
210 a flat symbol from a hand-engraved Bärenreiter edition, while the right
211 picture depicts a symbol from an edition of the same music published in
212 2000. Although both images are printed in the same shade of ink, the
213 earlier version looks darker: the staff lines are heavier, and the
214 Bärenreiter flat has a bold, almost voluptuous rounded look. The right
215 scan, on the other hand, has thinner lines and a straight layout with
218 @multitable @columnfractions .25 .25 .25 .25
222 @sourceimage{baer-flat-gray,,4cm,}
225 @sourceimage{baer-flat-gray,,,png}
230 @sourceimage{henle-flat-gray,,4cm,}
233 @sourceimage{henle-flat-gray,,,png}
238 @sourceimage{henle-flat-bw,,,png}
239 @sourceimage{baer-flat-bw,,,png}
240 @sourceimage{lily-flat-bw,,,png}
251 @cindex musical symbols
256 When we wanted to write a computer program to create music typography,
257 there were no musical fonts freely available that could match the
258 elegance of our favorite scores. Undeterred, we created a font of
259 musical symbols, relying on nice printouts of hand-engraved music. The
260 experience helped develop a typographical taste, and it made us
261 appreciate subtle design details. Without that experience, we would not
262 have realized how ugly the fonts were that we admired at first.
264 Below is a sample of two music fonts: the upper set is the default font
265 in the Sibelius software (the @emph{Opus} font), and the lower set is
266 our own LilyPond font.
270 @sourceimage{pdf/OpusAndFeta,,,}
273 @sourceimage{OpusAndFeta,,,png}
277 The LilyPond symbols are heavier and their weight is more consistent,
278 which makes them easier to read. Fine endings, such as the ones on the
279 sides of the quarter rest, should not end in sharp points, but rather
280 in rounded shapes. This is because sharp corners of the punching dies
281 are fragile and quickly wear out when stamping in metal. Taken together,
282 the blackness of the font must be carefully tuned together with the
283 thickness of lines, beams and slurs to give a strong yet balanced
286 Also, notice that our half-note head is not elliptic but slightly diamond
287 shaped. The vertical stem of a flat symbol is slightly brushed, becoming
288 wider at the top. The sharp and the natural are easier to distinguish
289 from a distance because their angled lines have different slopes and the
290 vertical strokes are heavier.
292 @node Optical spacing
293 @unnumberedsubsec Optical spacing
295 In spacing, the distribution of space should reflect the durations
296 between notes. However, as we saw in the Bach Suite above, many modern
297 scores adhere to the durations with mathematical precision, which leads
298 to poor results. In the next example a motive is printed twice: the
299 first time using exact mathematical spacing, and the second with
300 corrections. Which do you prefer?
302 @cindex optical spacing
323 \override NoteSpacing #'stem-spacing-correction = #0.0
324 \override NoteSpacing #'same-direction-correction = #0.0
325 \override StaffSpacing #'stem-spacing-correction = #0.0
351 \override NoteSpacing #'stem-spacing-correction = #0.6
357 @cindex regular rhythms
358 @cindex regular spacing
359 @cindex spacing, regular
361 Each bar in the fragment only uses notes that are played in a constant
362 rhythm. The spacing should reflect that. Unfortunately, the eye deceives
363 us a little; not only does it notice the distance between note heads, it
364 also takes into account the distance between consecutive stems. As a
365 result, the notes of an up-stem/@/down-stem combination should be put
366 farther apart, and the notes of a down-stem/@/up-stem combination should
367 be put closer together, all depending on the combined vertical positions
368 of the notes. The lower two measures are printed with this correction,
369 the upper two measures, however, form down-stem/@/up-stem clumps of
370 notes. A master engraver would adjust the spacing as needed to please
373 The spacing algorthims in LilyPond even take the barlines into account,
374 which is why the final up-stem in the properly spaced example has been
375 given a little more space before the barline to keep it from looking
376 crowded. A down-stem would not need this adjustment.
379 @unnumberedsubsec Ledger lines
384 Ledger lines present a typographical challenge: they make it more
385 difficult to space musical symbols close together and they must be clear
386 enough to identify the pitch at a glance. In the example below, we see
387 that ledger lines should be thicker than normal staff lines and that an
388 expert engraver will shorten a ledger line to allow closer spacing with
389 accidentals. We have included this feature in LilyPond's engraving.
391 @multitable @columnfractions .25 .25 .25 .25
395 @sourceimage{baer-ledger,3cm,,}
398 @sourceimage{baer-ledger,,,png}
404 @sourceimage{lily-ledger,3cm,,}
407 @sourceimage{lily-ledger,,,png}
414 @unnumberedsubsec Optical sizing
416 Music may need to be printed in a range of sizes. Originally, this was
417 accomplished by creating punching dies in each of the required sizes,
418 which meant that each die was designed to look its best at that size.
419 With the advent of digital fonts, a single outline can be mathematically
420 scaled to any size, which is very convenient, but at the smaller sizes
421 the glyphs will appear very light.
423 In LilyPond, we have created fonts in a range of weights, corresponding
424 to a range of music sizes. This is a LilyPond engraving at staff size
429 @sourceimage{pdf/size26,,23mm,}
432 @sourceimage{size26,,,png}
437 and this is the same engraving set at staff size 11, then
438 magnified by 236% to print at the same size as the previous example:
442 @sourceimage{pdf/size11,,23mm,}
445 @sourceimage{size11,,,png}
450 At smaller sizes, LilyPond uses proportionally heavier lines so the
451 music will still read well.
454 This also allows staves of different sizes to coexist peacefully when
455 used together on the same page:
457 @c TODO: are the stems in this example the right thickness? How should
458 @c line weights be scaled for small staves?
460 @c Grieg's Violin Sonata Op. 45
461 @lilypond[indent=1.5cm]
470 \override StaffSymbol #'staff-space = #(magstep -4)
471 \override StaffSymbol #'thickness = #(magstep -3)
475 \set Staff.instrumentName = #"Violin"
476 c8.(\f^> b16 c d) ees8.(^> d16 c b)
477 g8.(^> b16 c ees) g8-.^> r r
481 \set PianoStaff.instrumentName = #"Piano"
482 \new Staff \relative c' {
485 s4. s8 r8 r16 <c f aes c>
486 <c f aes c>4.^> <c ees g>8 r r
488 \new Staff \relative c {
492 \once \override DynamicText #'X-offset = #-3
494 <ees g c>4.~ <ees g c>8
497 <c g c,>4.~ <c g c,>8
499 r8 r16 <f, c' aes'>16
500 <f c' aes'>4.-> <c' g'>8 r r
507 @node Why work so hard?
508 @unnumberedsubsec Why work so hard?
510 Musicians are usually more absorbed with performing than with studying
511 the looks of a piece of music, so nitpicking typographical details may
512 seem academic. But it is not. Sheet music is performance material:
513 everything is done to aid the musician in letting her perform better,
514 and anything that is unclear or unpleasant to read is a hindrance.
516 Traditionally engraved music uses bold symbols on heavy staff to create
517 a strong, well-balanced look that stands out well when the music is far
518 away from the reader: for example, if it is on a music stand. A careful
519 distribution of white space allows music to be set very tightly without
520 crowding symbols together. The result minimizes the number of page
521 turns, which is a great advantage.
523 This is a common characteristic of typography. Layout should be pretty,
524 not only for its own sake, but especially because it helps the reader in
525 his task. For sheet music this is of double importance because musicians
526 have a limited amount of attention. The less attention they need for
527 reading, the more they can focus on playing the music. In other words,
528 better typography translates to better performances.
530 These examples demonstrate that music typography is an art that is
531 subtle and complex, and that producing it requires considerable
532 expertise, which musicians usually do not have. LilyPond is our
533 effort to bring the graphical excellence of hand-engraved music to
534 the computer age, and make it available to normal musicians. We
535 have tuned our algorithms, font-designs, and program settings to
536 produce prints that match the quality of the old editions we love
537 to see and love to play from.
540 @node Automated engraving
541 @unnumberedsec Automated engraving
543 @cindex engraving, automated
544 @cindex automated engraving
546 Here we describe what is required to create software that can
547 mimic the layout of engraved scores: a method of explaining good
548 layouts to the computer, detailed comparisons with real engravings,
549 and enough flexibility to deal with the wide range of challenges
550 that printed music can present.
554 * Improvement by benchmarking::
555 * Getting things right::
556 * Flexible architecture::
559 @node Beauty contests
560 @unnumberedsubsec Beauty contests
562 How do we actually make formatting decisions? In other words, which
563 of the three configurations should we choose for the following slur?
568 \once \override Slur #'positions = #'(1.5 . 1)
569 e8[( f] g[ a b d,)] r4
570 \once \override Slur #'positions = #'(2 . 3)
571 e8[( f] g[ a b d,)] r4
572 e8[( f] g[ a b d,)] r4
576 There are a few books on the art of music engraving
577 available. Unfortunately, they contain simple rules of thumb and some
578 examples. Such rules can be instructive, but they are a far cry from
579 an algorithm that we could readily implement in a computer. Following
580 the instructions from literature leads to algorithms with lots of
581 hand-coded exceptions. Doing all this case analysis is a lot of work,
582 and often not all cases are covered completely:
586 @sourceimage{ross-beam-scan,7cm,,}
589 @sourceimage{ross-beam-scan,,,.jpg}
593 (Image source: Ted Ross, @emph{The Art of Music Engraving})
595 Rather than trying to write detailed layout rules for every possible
596 scenario, we only have to describe the objectives well enough that
597 LilyPond can judge the attractiveness of several alternatives. Then,
598 for each possible configuration we compute an ugliness score and we
599 choose the least ugly configuration.
601 For example, here are three possible slur configurations, and LilyPond
602 has given each one a score in @q{ugly points}. The first example gets 15.39
603 points for grazing one of the notes:
608 \once \override Slur #'positions = #'(1.5 . 1)
609 e8[(_"15.39" f] g[ a b d,)] r4
614 second one is nicer, but the slur doesn't start or end on the note heads.
615 It gets 1.71 points for the left side and 9.37 points for the right
616 side, plus another 2 points because the slur ascends while the melody
617 descends for a total of 13.08 ugly points:
622 \once \override Slur #'positions = #'(2 . 3)
623 e8[(_"13.08" f] g[ a b d,)] r4
627 The final slur gets 10.04
628 points for the gap on the right and 2 points for the upward slope, but
629 it is the most attractive of the three configurations, so LilyPond
635 e8[(_"12.04" f] g[ a b d,)] r4
639 This technique is quite general, and is used to make optimal decisions
640 for beam configurations, ties and dots in chords, line breaks, and page
641 breaks. The results of these decisions can be judged by comparison to
644 @node Improvement by benchmarking
645 @unnumberedsubsec Improvement by benchmarking
647 LilyPond's output has improved gradually over time, and it continues to
648 improve by comparing its output to hand-engraved scores.
650 For example, here is one line of a benchmark piece from a
651 hand-engraved edition (Bärenreiter BA320):
654 @sourceimage{baer-sarabande-hires,16cm,,}
657 @sourceimage{baer-sarabande,,,png}
661 and the same quotation as engraved by a very old version of LilyPond
662 (version 1.4, May 2001):
665 @sourceimage{pdf/lily14-sarabande,16cm,,}
668 @sourceimage{lily14-sarabande,,,png}
671 @noindent The LilyPond 1.4 output is certainly readable, but close
672 comparison with the hand-engraved score showed a lot of errors in the
676 @sourceimage{lily14-sarabande-annotated-hires,16cm,,}
679 @sourceimage{lily14-sarabande-annotated,,,png}
683 @item there is too much space before the time signature
684 @item the stems of the beamed notes are too long
685 @item the second and fourth measures are too narrow
686 @item the slur is awkward-looking
687 @item the trill marks are too big
688 @item the stems are too thin
692 (There were also two missing note heads, several missing editorial
693 annotations, and an incorrect pitch!)
695 By adjusting the layout rules and font design, the output has improved
696 considerably. Compare the same reference score and the output
697 from the current version of LilyPond (@version{}):
700 @sourceimage{baer-sarabande-hires,16cm,,}
703 @sourceimage{baer-sarabande,,,png}
706 @lilypond[staffsize=17.5,line-width=15.9\cm]
711 \mergeDifferentlyDottedOn
712 << {\slurDashed d8.-\flageolet( e16) e4.-\trill( d16 e)}
716 <f' a, d,>4. e8( d c)
718 bes g' f e16( f g_1 a_2 bes_3 d,_2)
720 cis4.-\trill b8_3( a g)
721 << {\slurDashed d'8.( e16) e4.-\trill( d16 e)}
728 The current output is not a clone of the reference edition, but it is
729 much closer to publication quality that the earlier output.
731 @node Getting things right
732 @unnumberedsubsec Getting things right
734 We can also measure LilyPond's ability to make music engraving decisions
735 automatically by comparing LilyPond's output to the output of a
736 commercial software product. In this case we have chosen Finale 2008,
737 which is one of the most popular commercial score writers, particularly
738 in North America. Sibelius is their major rival and they appear to be
739 especially strong in the European market.
741 For our comparison we selected Bach's Fugue in G minor from the
742 Well-Tempered Clavier, Book I, BWV 861, whose opening subject is
749 r8 a16 bes c8 bes16 a bes8
755 We made our comparison by engraving the last seven measures of the piece
756 (28--34) in Finale and LilyPond. This is the point in the piece where
757 the subject returns in a three-part stretto and leads into the closing
758 section. In the Finale version, we have resisted the temptation to make
759 any adjustments to the default output because we are trying to show the
760 things that each software package gets right without assistance. The
761 only major edits that we made were adjusting the page size to match this
762 essay and forcing the music onto two systems to make the comparison
763 easier. By default Finale would have engraved two systems of three
764 measures each and a final, full-width system containing a single
767 Many of the differences between the two engravings are visible in
768 measures 28--29, as shown here with Finale first and LilyPond second:
771 @sourceimage{pdf/bwv861mm28-29,14cm,,}
774 @sourceimage{bwv861mm28-29,,,png}
777 @lilypond[staffsize=19.5,line-width=14\cm]
778 global = {\key g \minor}
780 partI = \relative c' {
782 fis8 d' ees g, fis4 g
783 r8 a16 bes c8 bes16 a d8 r r4
786 partII = \relative c' {
788 d4 r4 r8 d'16 c bes8 c16 d
791 partIII = \relative c' {
793 r2 r8 d ees g, fis4 g r8 a16 bes c8 bes16 a
795 partIV = \relative c {
803 % \set Score.barNumberVisibility = #all-bar-numbers-visible
805 \set Score.currentBarNumber = #28
810 \new Voice = "voiceI" { \partI }
811 \new Voice = "voiceII" { \partII }
817 \new Voice = "voiceIII" { \partIII }
818 \new Voice = "voiceIV" { \partIV }
825 \remove "Time_signature_engraver"
829 \override StaffGrouper #'between-staff-spacing #'padding = #1
835 Some shortcomings in the unedited Finale output include:
837 @item Most of the beams extend too far off the staff. A beam that points
838 towards the center of the staff should have a length of about one
839 octave, but engravers shorten this when the beam points away from the
840 staff in multi-voice music. The Finale beaming can be easily improved
841 with the Patterson Beams plug-in, but we elected to skip that step for
843 @item Finale doesn't adjust the positions of interlocking note heads,
844 which makes the music extremely difficult to read when the upper and
845 lower voices exchange positions temporarily:
848 collide = \once \override NoteColumn #'force-hshift = #0
850 \new Voice = "sample" \relative c''{
853 {\voiceOne g4 \collide g4}
854 \new Voice {\voiceTwo bes \collide bes}
857 \new Lyrics \lyricsto "sample" \lyricmode { "good " " bad" }
861 @item Finale has placed all of the rests at fixed heights on the staff.
862 The user is free to adjust them as needed, but the software makes no
863 attempt to consider the content of the other voice. As luck would have
864 it, there are no true collisions between notes and rests in this example,
865 but that has more to do with the positions of the notes than the rest.
866 In other words, Bach deserves more credit for avoiding a complete
867 collision than Finale does.
871 This example is not intended to suggest that Finale cannot be used to
872 produce publication-quality output. On the contrary, in the hands of a
873 skilled user it can and does, but it requires skill and time. One of the
874 fundamental differences between LilyPond and commercial scorewriters is
875 that LilyPond hopes to reduce the amount of human intervention to an
876 absolute minimum, while other packages try to provide an attractive
877 interface in which to make these types of edits.
879 One particularly glaring omission we found from Finale is a missing flat
884 @sourceimage{pdf/bwv861mm33-34-annotate,7.93cm,,}
887 @sourceimage{bwv861mm33-34-annotate,,,png}
892 The flat symbol is required to cancel out the natural in the same
893 measure, but Finale misses it because it occurred in a different voice.
894 So in addition to running a beaming plug-in and checking the spacing on
895 the noteheads and rests, the user must also check each measure for
896 cross-voice accidentals to avoid interrupting a rehearsal over an
899 If you are interested in examining these examples in more detail, the
900 full seven-measure excerpt can be found at the end of this essay along
901 with four different published engravings. Close examination reveals that
902 there is some acceptible variation among the hand-engravings, but that
903 LilyPond compares reasonably well to that acceptible range. There are
904 still some shortcomings in the LilyPond output, for example, it appears
905 a bit too agressive in shortening some of the stems, so there is room
906 for further development and fine-tuning.
908 Of course, typography relies on human judgment of appearance, so people
909 cannot be replaced completely. However, much of the dull work can be
910 automated. If LilyPond solves most of the common situations correctly,
911 this will be a huge improvement over existing software. Over the course
912 of years, the software can be refined to do more and more things
913 automatically, so manual overrides are less and less necessary. Where
914 manual adjustments are needed, LilyPond's structure has been designed
915 with that flexibility in mind.
917 @node Flexible architecture
918 @unnumberedsubsec Flexible architecture
920 When we started, we wrote the LilyPond program entirely in the C++
921 programming language; the program's functionality was set in stone
922 by the developers. That proved to be unsatisfactory for a number
927 @item When LilyPond makes mistakes, users need to override
928 formatting decisions. Therefore, the user must have access to the
929 formatting engine. Hence, rules and settings cannot be fixed by
930 us at compile-time but must be accessible for users at run-time.
932 @item Engraving is a matter of visual judgment, and therefore a
933 matter of taste. As knowledgeable as we are, users can disagree
934 with our personal decisions. Therefore, the definitions of
935 typographical style must also be accessible to the user.
937 @item Finally, we continually refine the formatting algorithms, so
938 we need a flexible approach to rules. The C++ language forces a
939 certain method of grouping rules that cannot readily be applied to
940 formatting music notation.
944 @cindex Scheme programming language
946 These problems have been addressed by integrating an interpreter
947 for the Scheme programming language and rewriting parts of
948 LilyPond in Scheme. The current formatting architecture is built
949 around the notion of graphical objects, described by Scheme
950 variables and functions. This architecture encompasses formatting
951 rules, typographical style and individual formatting decisions.
952 The user has direct access to most of these controls.
954 Scheme variables control layout decisions. For example, many
955 graphical objects have a direction variable that encodes the
956 choice between up and down (or left and right). Here you see two
957 chords, with accents and arpeggios. In the first chord, the
958 graphical objects have all directions down (or left). The second
959 chord has all directions up (right).
961 @lilypond[quote,ragged-right]
963 \override SpacingSpanner #'spacing-increment = #3
964 \override TimeSignature #'transparent = ##t
966 \stemDown <e g b>4_>-\arpeggio
967 \override Arpeggio #'direction = #RIGHT
968 \stemUp <e g b>4^>-\arpeggio
972 @cindex score formatting
973 @cindex formatting a score
974 @cindex formatting rules
977 The process of formatting a score consists of reading and writing
978 the variables of graphical objects. Some variables have a preset
979 value. For example, the thickness of many lines -- a
980 characteristic of typographical style -- is a variable with a
981 preset value. You are free to alter this value, giving your score
982 a different typographical impression.
984 @lilypond[quote,ragged-right]
987 c'4-~ c'16 as g f e16 g bes c' des'4
992 \override Beam #'beam-thickness = #0.3
993 \override Stem #'thickness = #0.5
994 \override Bar #'thickness = #3.6
995 \override Tie #'thickness = #2.2
996 \override StaffSymbol #'thickness = #3.0
997 \override Tie #'extra-offset = #'(0 . 0.3)
1003 Formatting rules are also preset variables: each object has
1004 variables containing procedures. These procedures perform the
1005 actual formatting, and by substituting different ones, we can
1006 change the appearance of objects. In the following example, the
1007 rule governing which note head objects are used to produce the
1008 note head symbol is changed during the music fragment.
1010 @lilypond[quote,ragged-right]
1011 #(set-global-staff-size 30)
1013 #(define (mc-squared grob orig current)
1014 (let* ((interfaces (ly:grob-interfaces grob))
1015 (pos (ly:grob-property grob 'staff-position)))
1016 (if (memq 'note-head-interface interfaces)
1018 (ly:grob-set-property! grob 'stencil
1019 (grob-interpret-markup grob
1020 (make-lower-markup 0.5
1024 ((-2) (make-smaller-markup (make-bold-markup "2")))
1025 (else "bla")))))))))
1027 \new Voice \relative c' {
1029 \set autoBeaming = ##f
1032 \once \override NoteHead #'stencil = #note-head::brew-ez-stencil
1033 \once \override NoteHead #'font-size = #-7
1034 \once \override NoteHead #'font-family = #'sans
1035 \once \override NoteHead #'font-series = #'bold
1037 \once \override NoteHead #'style = #'cross
1039 \applyOutput #'Voice #mc-squared
1042 { d8[ es-( fis^^ g] fis2-) }
1043 \repeat unfold 5 { \applyOutput #'Voice #mc-squared s8 }
1049 @node What symbols to engrave?
1050 @unnumberedsec What symbols to engrave?
1057 The formatting process decides where to place symbols. However,
1058 this can only be done once it is decided @emph{what} symbols
1059 should be printed -- in other words, what notation to use.
1061 Common music notation is a system of recording music that has
1062 evolved over the past 1000 years. The form that is now in common
1063 use dates from the early Renaissance. Although the basic form
1064 (i.e., note heads on a 5-line staff) has not changed, the details
1065 still evolve to express the innovations of contemporary notation.
1066 Hence, common music notation encompasses some 500 years of music.
1067 Its applications range from monophonic melodies to monstrous
1068 counterpoints for a large orchestra.
1070 How can we get a grip on such a seven-headed beast, and force it
1071 into the confines of a computer program? Our solution is to break
1072 up the problem of notation (as opposed to engraving, i.e.,
1073 typography) into digestible and programmable chunks: every type of
1074 symbol is handled by a separate module, a so-called plug-in. Each
1075 plug-in is completely modular and independent, so each can be
1076 developed and improved separately. Such plug-ins are called
1077 @code{engraver}s, by analogy with craftsmen who translate musical
1078 ideas to graphic symbols.
1080 In the following example, we start out with a plug-in for note
1081 heads, the @code{Note_heads_engraver}.
1083 @lilypond[quote,ragged-right]
1084 \include "engraver-example.ily"
1091 \remove "Stem_engraver"
1092 \remove "Phrasing_slur_engraver"
1093 \remove "Slur_engraver"
1094 \remove "Script_engraver"
1095 \remove "Beam_engraver"
1096 \remove "Auto_beam_engraver"
1100 \remove "Accidental_engraver"
1101 \remove "Key_engraver"
1102 \remove "Clef_engraver"
1103 \remove "Bar_engraver"
1104 \remove "Time_signature_engraver"
1105 \remove "Staff_symbol_engraver"
1106 \consists "Pitch_squash_engraver"
1113 Then a @code{Staff_symbol_engraver} adds the staff,
1115 @lilypond[quote,ragged-right]
1116 \include "engraver-example.ily"
1123 \remove "Stem_engraver"
1124 \remove "Phrasing_slur_engraver"
1125 \remove "Slur_engraver"
1126 \remove "Script_engraver"
1127 \remove "Beam_engraver"
1128 \remove "Auto_beam_engraver"
1132 \remove "Accidental_engraver"
1133 \remove "Key_engraver"
1134 \remove "Clef_engraver"
1135 \remove "Bar_engraver"
1136 \consists "Pitch_squash_engraver"
1137 \remove "Time_signature_engraver"
1144 the @code{Clef_engraver} defines a reference point for the staff,
1146 @lilypond[quote,ragged-right]
1147 \include "engraver-example.ily"
1154 \remove "Stem_engraver"
1155 \remove "Phrasing_slur_engraver"
1156 \remove "Slur_engraver"
1157 \remove "Script_engraver"
1158 \remove "Beam_engraver"
1159 \remove "Auto_beam_engraver"
1163 \remove "Accidental_engraver"
1164 \remove "Key_engraver"
1165 \remove "Bar_engraver"
1166 \remove "Time_signature_engraver"
1173 and the @code{Stem_engraver} adds stems.
1175 @lilypond[quote,ragged-right]
1176 \include "engraver-example.ily"
1183 \remove "Phrasing_slur_engraver"
1184 \remove "Slur_engraver"
1185 \remove "Script_engraver"
1186 \remove "Beam_engraver"
1187 \remove "Auto_beam_engraver"
1191 \remove "Accidental_engraver"
1192 \remove "Key_engraver"
1193 \remove "Bar_engraver"
1194 \remove "Time_signature_engraver"
1201 The @code{Stem_engraver} is notified of any note head coming
1202 along. Every time one (or more, for a chord) note head is seen, a
1203 stem object is created and connected to the note head. By adding
1204 engravers for beams, slurs, accents, accidentals, bar lines, time
1205 signature, and key signature, we get a complete piece of notation.
1207 @lilypond[quote,ragged-right]
1208 \include "engraver-example.ily"
1209 \score { \topVoice }
1213 @cindex engraving multiple voices
1216 This system works well for monophonic music, but what about
1217 polyphony? In polyphonic notation, many voices can share a staff.
1219 @lilypond[quote,ragged-right]
1220 \include "engraver-example.ily"
1221 \new Staff << \topVoice \\ \botVoice >>
1224 In this situation, the accidentals and staff are shared, but the
1225 stems, slurs, beams, etc., are private to each voice. Hence,
1226 engravers should be grouped. The engravers for note heads, stems,
1227 slurs, etc., go into a group called @q{Voice context}, while the
1228 engravers for key, accidental, bar, etc., go into a group called
1229 @q{Staff context}. In the case of polyphony, a single Staff
1230 context contains more than one Voice context. Similarly, multiple
1231 Staff contexts can be put into a single Score context. The Score
1232 context is the top level notation context.
1236 Internals Reference: @rinternals{Contexts}.
1239 @lilypond[quote,ragged-right]
1240 \include "engraver-example.ily"
1243 \new Staff << \topVoice \\ \botVoice >>
1244 \new Staff << \pah \\ \hoom >>
1250 @node Music representation
1251 @unnumberedsec Music representation
1254 @cindex recursive structures
1256 Ideally, the input format for any high-level formatting system is
1257 an abstract description of the content. In this case, that would
1258 be the music itself. This poses a formidable problem: how can we
1259 define what music really is? Instead of trying to find an answer,
1260 we have reversed the question. We write a program capable of
1261 producing sheet music, and adjust the format to be as lean as
1262 possible. When the format can no longer be trimmed down, by
1263 definition we are left with content itself. Our program serves as
1264 a formal definition of a music document.
1266 The syntax is also the user-interface for LilyPond, hence it is
1276 to create a quarter note on middle C (C1) and an eighth note on
1277 the D above middle C (D1).
1285 On a microscopic scale, such syntax is easy to use. On a larger
1286 scale, syntax also needs structure. How else can you enter
1287 complex pieces like symphonies and operas? The structure is
1288 formed by the concept of music expressions: by combining small
1289 fragments of music into larger ones, more complex music can be
1290 expressed. For example
1292 @lilypond[quote,verbatim,fragment,relative=1]
1297 Simultaneous notes can be constructed by enclosing them with
1298 @code{<<} and @code{>>}:
1304 @lilypond[quote,fragment,relative=1]
1305 \new Voice { <<c4 d4 e>> }
1309 This expression is put in sequence by enclosing it in curly braces
1310 @code{@{@tie{}@dots{}@tie{}@}}:
1313 @{ f4 <<c4 d4 e4>> @}
1316 @lilypond[quote,relative=1,fragment]
1321 The above is also an expression, and so it may be combined again
1322 with another simultaneous expression (a half note) using
1323 @code{<<}, @code{\\}, and @code{>>}:
1326 << g2 \\ @{ f4 <<c4 d4 e4>> @} >>
1329 @lilypond[quote,fragment,relative=2]
1330 \new Voice { << g2 \\ { f4 <<c d e>> } >> }
1333 Such recursive structures can be specified neatly and formally in
1334 a context-free grammar. The parsing code is also generated from
1335 this grammar. In other words, the syntax of LilyPond is clearly
1336 and unambiguously defined.
1338 User-interfaces and syntax are what people see and deal with most.
1339 They are partly a matter of taste, and also the subject of much
1340 discussion. Although discussions on taste do have their merit,
1341 they are not very productive. In the larger picture of LilyPond,
1342 the importance of input syntax is small: inventing neat syntax is
1343 easy, while writing decent formatting code is much harder. This
1344 is also illustrated by the line-counts for the respective
1345 components: parsing and representation take up less than 10% of
1349 @node Example applications
1350 @unnumberedsec Example applications
1352 @cindex simple examples
1353 @cindex examples, simple
1355 We have written LilyPond as an experiment of how to condense the
1356 art of music engraving into a computer program. Thanks to all
1357 that hard work, the program can now be used to perform useful
1358 tasks. The simplest application is printing notes.
1360 @lilypond[quote,relative=1]
1368 By adding chord names and lyrics we obtain a lead sheet.
1370 @lilypond[quote,ragged-right]
1372 \chords { c2 c f2 c }
1378 \addlyrics { twin -- kle twin -- kle lit -- tle star }
1382 Polyphonic notation and piano music can also be printed. The
1383 following example combines some more exotic constructs.
1387 title = "Screech and boink"
1388 subtitle = "Random complex notation"
1389 composer = "Han-Wen Nienhuys"
1393 \context PianoStaff <<
1398 \revert Stem #'direction
1399 \change Staff = down
1400 \set subdivideBeams = ##t
1404 \change Staff = down
1408 \change Staff = down
1412 \set followVoice = ##t
1413 c'''32([ b''16 a''16 gis''16 g''32)]
1415 s4 \times 2/3 { d'16[ f' g'] } as'32[ b''32 e'' d'']
1417 s4 \autoBeamOff d''8.. f''32
1423 \new Staff = "down" {
1426 \set subdivideBeams = ##f
1427 \override Stem #'french-beaming = ##t
1428 \override Beam #'beam-thickness = #0.3
1429 \override Stem #'thickness = #4.0
1430 g'16[ b16 fis16 g16]
1436 \override Staff.Arpeggio #'arpeggio-direction =#down
1437 <cis, e, gis, b, cis>4\arpeggio
1444 tempoWholesPerMinute = #(ly:make-moment 60 8)
1450 \consists Horizontal_bracket_engraver
1456 The fragments shown above have all been written by hand, but that
1457 is not a requirement. Since the formatting engine is mostly
1458 automatic, it can serve as an output means for other programs that
1459 manipulate music. For example, it can also be used to convert
1460 databases of musical fragments to images for use on websites and
1461 multimedia presentations.
1463 This manual also shows an application: the input format is text,
1464 and can therefore be easily embedded in other text-based formats
1465 such as @LaTeX{}, HTML, or in the case of this manual, Texinfo.
1466 By means of a special program, the input fragments can be replaced
1467 by music images in the resulting PDF or HTML output files. This
1468 makes it easy to mix music and text in documents.
1471 TODO: add extra chapter for computer aesthetics?
1475 @unnumberedsec Appendix
1477 This appendix contains four reference engravings and two
1478 software-engraved versions of Bach's Fugue in G minor from the
1479 Well-Tempered Clavier, Book I, BWV 861 (the last seven measures).
1482 Bärenreiter BA5070 (Neue Ausgabe Sämtlicher Werke, Serie V, Band 6.1,
1486 @sourceimage{bwv861-baer,16cm,,}
1489 @sourceimage{bwv861-baer-small,,,png}
1493 Bärenreiter BA5070 (Neue Ausgabe Sämtlicher Werke, Serie V, Band 6.1,
1494 1989), an alternate musical source. Aside from the textual differences,
1495 this demonstrates slight variations in the engraving decisions, even
1496 from the same publisher and edition:
1499 @sourceimage{bwv861-baer-alt,16cm,,}
1502 @sourceimage{bwv861-baer-alt-small,,,png}
1506 Breitkopf & Härtel, edited by Ferruccio Busoni (Wiesbaden, 1894), also
1507 available from the Petrucci Music Library (IMSLP #22081). The editorial
1508 markings (fingerings, articulations, etc.) have been removed for clearer
1509 comparison with the other editions here:
1512 @sourceimage{bwv861-breitkopf,16cm,,}
1515 @sourceimage{bwv861-breitkopf-small,,,png}
1519 Bach-Gesellschaft edition (Leipzig, 1866), available from the Petrucci
1520 Music Library (IMSPL #02221):
1523 @sourceimage{bwv861-gessellschaft,16cm,,}
1526 @sourceimage{bwv861-gessellschaft-small,,,png}
1533 @sourceimage{pdf/bwv861-finale2008a,,,}
1536 @sourceimage{bwv861-finale2008a,,,png}
1541 LilyPond, version @version{}:
1543 @lilypond[staffsize=14.3,line-width=15.9\cm]
1544 global = {\key g \minor}
1546 partI = \relative c' {
1548 fis8 d' ees g, fis4 g
1549 r8 a16 bes c8 bes16 a d8 r r4
1550 r2 r8 d16 ees f8 ees16 d
1551 ees4 ~ ees16 d c bes a4 r8 ees'16 d
1552 c8 d16 ees d8 e16 fis g8 fis16 g a4 ~
1553 a8 d, g f ees d c bes
1554 a2 g\fermata \bar "|."
1557 partII = \relative c' {
1559 d4 r4 r8 d'16 c bes8 c16 d
1560 ees8 d c ees a, r r4
1561 r8 fis16 g a8 g16 fis g2 ~
1563 fis4 g r8 a16 bes c8 bes16 a
1564 bes4. <g b>8 <a c> r <d, g> r
1567 partIII = \relative c' {
1569 r2 r8 d ees g, fis4 g r8 a16 bes c8 bes16 a
1570 bes2 ~ bes8 b16 a g8 a16 b
1574 r8 a16 bes c8 bes16 a b2
1576 partIV = \relative c {
1580 d,8 d'16 c bes8 c16 d ees2 ~
1581 ees8 ees16 d c8 d16 ees fis,8 a16 g fis8 g16 a
1582 d,8 d'16 c bes8 c16 d ees8 c a fis'
1589 % \set Score.barNumberVisibility = #all-bar-numbers-visible
1591 \set Score.currentBarNumber = #28
1594 \new Staff = "RH" <<
1596 \new Voice = "voiceI" { \partI }
1597 \new Voice = "voiceII" { \partII }
1600 \new Staff = "LH" <<
1603 \new Voice = "voiceIII" { \partIII }
1604 \new Voice = "voiceIV" { \partIV }
1611 \remove "Time_signature_engraver"
1615 \override StaffGrouper #'between-staff-spacing #'padding = #1