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 section covers the overall goals and architecture of
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
26 @c Incorrect beaming in the Sarabande is a known bug.
29 * The LilyPond story::
31 * Automated engraving::
32 * What symbols to engrave?::
33 * Music representation::
34 * Example applications::
38 @node The LilyPond story
39 @unnumberedsec The LilyPond story
41 Before LilyPond had a community of users around the world, before it had
42 been used to produce university course notes or world-premier opera
43 performance scores, before there was an essay on music engraving or any
44 computer code or even an organized team of developers, LilyPond began
48 Why does most computer output fail to achieve the beauty and balance of
49 a hand-engraved score?
53 Some of the answers can be found by examining the two scores
58 on the following pages.
60 The first score is a beautiful hand-engraved score from 1950 and the
61 second is a modern, computer-engraved edition.
65 Bärenreiter BA 320, @copyright{}1950:
67 @sourceimage{baer-suite1-fullpage,,,png}
70 Henle no. 666, @copyright{}2000:
72 @sourceimage{henle-suite1-fullpage,,,png}
75 The notes here are identical, taken from Bach's first Suite for solo
76 cello, but the appearance is different, especially if you print them out
77 and view them from a distance.
79 (The PDF version of this manual has high-resolution images suitable for
82 Try reading or playing from each of the scores and you will find that
83 the hand-engraved score is more enjoyable to use. It has flowing lines
84 and movement, and it feels like a living, breathing piece of music,
85 while the newer edition seems cold and mechanical.
87 It is kind of hard to immediately see what makes the difference with the
88 newer edition. Everything looks neat and tiny, possibly even @qq{better}
89 because it looks more computerized and uniform. This really puzzled us
90 for quite a while. We wanted to improve computer notation, but we first
91 had to figure out what was wrong with it.
93 The answer lies in the precise, mathematical uniformity of the newer
94 edition. Find the bar line in the middle of each line: in the
95 hand-engraved score the position of these bar lines has some
96 natural variation, while in the newer version they line up almost
97 perfectly. This is shown in these simplified page layout diagrams,
98 traced from the hand-engraved (left) and computer-generated music
103 @sourceimage{pdf/page-layout-comparison,,,}
106 @sourceimage{page-layout-comparison,,,png}
111 In the computer-generated output, even the individual note heads are
112 aligned in vertical columns, making the contour of the melody disappear
113 into a rigid grid of musical markings.
115 There are other differences as well: in the hand-engraved edition the
116 vertical lines are all stronger, the slurs lie closer to the note heads,
117 and there is more visual variety in the placement of the beams. Although
118 such details may seem like nitpicking, the result is a score that is
119 easier to read. In the computer-generated output, each line is nearly
120 identical and if the musician looks away for a moment, she will be lost
123 LilyPond was designed to solve the problems we found in existing
124 software and to create beautiful music that mimics the finest
125 hand-engraved scores. Along the way, we have learned a great deal about
126 the work that goes into a well-engraved score. In this essay we describe
127 several of those aspects that we have tried to imitate in LilyPond.
132 Bärenreiter BA 320, @copyright{}1950:
134 @sourceimage{baer-suite1-fullpage,16cm,,}
137 Henle no. 666, @copyright{}2000:
139 @sourceimage{henle-suite1-fullpage,16cm,,}
143 @node Engraving details
144 @unnumberedsec Engraving details
147 @cindex typography, music
148 @cindex music typography
149 @cindex plate engraving
150 @cindex music engraving
152 The art of music typography is called @emph{(plate) engraving}, a term
153 that derives from the manual process of music printing@footnote{Early
154 European printers explored several processes, including hand-carved
155 wooden blocks, movable type, and engraved sheets of thin metal.
156 Typesetting had the advantage of being more easily corrected and
157 facilitating the inclusion of text and lyrics, but only engraving
158 offered the ability to do unimpeded layout and unanticipated notation.
159 In the end, hand-engraved scores became the standard for all printed
160 music, with the exception of some hymnals and songbooks where
161 typesetting was justified by its ease and economy, even into the
162 twentieth century.}. Just a few decades ago, sheet music was made by
163 cutting and stamping the music into a zinc or pewter plate in mirror
164 image. The plate would be inked, and the depressions caused by the
165 cutting and stamping would hold ink. An image was formed by pressing
166 paper to the plate. The stamping and cutting was done completely by hand
167 and making a correction was cumbersome, so the engraving had to be
168 nearly perfect in one go. Engraving was a highly specialized skill; a
169 craftsman had to complete around five years of training before earning
170 the title of master engraver, and another five years of experience were
171 necessary to become truly skilled.
175 @sourceimage{hader-slaan,,7cm,}
178 @sourceimage{hader-slaan,,,jpg}
182 LilyPond is inspired by traditional manual engravings published by
183 European music publishers in and towards the end of the first half of
184 the twentieth century, including Bärenreiter, Duhem, Durand,
185 Hofmeister, Peters, and Schott. This is sometimes regarded as the peak
186 of traditional musical engraving practice.
188 @c Now all newly printed music is produced with computers. This has
189 @c obvious advantages: prints are cheaper to make, editorial work can be
190 @c delivered by email, and the original data can be easily stored.
191 @c Unfortunately, computer-generated scores rarely match the quality of
192 @c hand-engraved scores. Instead, computer printouts have a bland,
193 @c mechanical look, which makes them unpleasant to play from.
200 * Why work so hard?::
204 @unnumberedsubsec Music fonts
206 The images below illustrate some differences between traditional
207 engraving and typical computer output. The left picture shows a scan of
208 a flat symbol from a hand-engraved Bärenreiter edition, while the right
209 picture depicts a symbol from an edition of the same music published in
210 2000. Although both images are printed in the same shade of ink, the
211 earlier version looks darker: the staff lines are heavier, and the
212 Bärenreiter flat has a bold, almost voluptuous rounded look. The right
213 scan, on the other hand, has thinner lines and a straight layout with
216 @multitable @columnfractions .25 .25 .25 .25
220 @sourceimage{baer-flat-gray,,4cm,}
223 @sourceimage{baer-flat-gray,,,png}
228 @sourceimage{henle-flat-gray,,4cm,}
231 @sourceimage{henle-flat-gray,,,png}
236 @sourceimage{henle-flat-bw,,,png}
237 @sourceimage{baer-flat-bw,,,png}
238 @sourceimage{lily-flat-bw,,,png}
249 @cindex musical symbols
254 When we wanted to write a computer program to create music typography,
255 there were no musical fonts freely available that could match the
256 elegance of our favorite scores. Undeterred, we created a font of
257 musical symbols, relying on nice printouts of hand-engraved music. The
258 experience helped develop a typographical taste, and it made us
259 appreciate subtle design details. Without that experience, we would not
260 have realized how ugly the fonts were that we admired at first.
262 Below is a sample of two music fonts: the upper set is the default font
263 in the Sibelius software (the @emph{Opus} font), and the lower set is
264 our own LilyPond font.
268 @sourceimage{pdf/OpusAndFeta,,,}
271 @sourceimage{OpusAndFeta,,,png}
275 The LilyPond symbols are heavier and their weight is more consistent,
276 which makes them easier to read. Fine endings, such as the ones on the
277 sides of the quarter rest, should not end in sharp points, but rather
278 in rounded shapes. This is because sharp corners of the punching dies
279 are fragile and quickly wear out when stamping in metal. Taken together,
280 the blackness of the font must be carefully tuned together with the
281 thickness of lines, beams and slurs to give a strong yet balanced
284 Also, notice that our half-note head is not elliptic but slightly diamond
285 shaped. The vertical stem of a flat symbol is slightly brushed, becoming
286 wider at the top. The sharp and the natural are easier to distinguish
287 from a distance because their angled lines have different slopes and the
288 vertical strokes are heavier.
290 @node Optical spacing
291 @unnumberedsubsec Optical spacing
293 In spacing, the distribution of space should reflect the durations
294 between notes. However, as we saw in the Bach Suite above, many modern
295 scores adhere to the durations with mathematical precision, which leads
296 to poor results. In the next example a motive is printed twice: the
297 first time using exact mathematical spacing, and the second with
298 corrections. Which do you prefer?
300 @cindex optical spacing
321 \override NoteSpacing #'stem-spacing-correction = #0.0
322 \override NoteSpacing #'same-direction-correction = #0.0
323 \override StaffSpacing #'stem-spacing-correction = #0.0
349 \override NoteSpacing #'stem-spacing-correction = #0.6
355 @cindex regular rhythms
356 @cindex regular spacing
357 @cindex spacing, regular
359 Each bar in the fragment only uses notes that are played in a constant
360 rhythm. The spacing should reflect that. Unfortunately, the eye deceives
361 us a little; not only does it notice the distance between note heads, it
362 also takes into account the distance between consecutive stems. As a
363 result, the notes of an up-stem/@/down-stem combination should be put
364 farther apart, and the notes of a down-stem/@/up-stem combination should
365 be put closer together, all depending on the combined vertical positions
366 of the notes. The lower two measures are printed with this correction,
367 the upper two measures, however, form down-stem/@/up-stem clumps of
368 notes. A master engraver would adjust the spacing as needed to please
371 Another example of optical spacing is the visual interplay between the
372 stems and the bar lines. When an up-stem precedes the bar line, a little
373 more space is needed to keep it from feeling crowded:
382 c''8 c'' c'' c'' c'' c'' c'' c'' \break
383 a' a' a' a' a' a' a' a'
388 \remove "Time_signature_engraver"
389 \override NoteSpacing #'stem-spacing-correction = #0.7
393 \remove "Bar_number_engraver"
400 @unnumberedsubsec Ledger lines
405 Ledger lines present a typographical challenge: they make it more
406 difficult to space musical symbols close together and they must be clear
407 enough to identify the pitch at a glance. In the example below, we see
408 that ledger lines should be thicker than normal staff lines and that an
409 expert engraver will shorten a ledger line to allow closer spacing with
410 accidentals. We have included this feature in LilyPond's engraving.
412 @multitable @columnfractions .25 .25 .25 .25
416 @sourceimage{baer-ledger,3cm,,}
419 @sourceimage{baer-ledger,,,png}
425 @sourceimage{lily-ledger,3cm,,}
428 @sourceimage{lily-ledger,,,png}
435 @unnumberedsubsec Optical sizing
437 Music may need to be printed in a range of sizes. Originally, this was
438 accomplished by creating punching dies in each of the required sizes,
439 which meant that each die was designed to look its best at that size.
440 With the advent of digital fonts, a single outline can be mathematically
441 scaled to any size, which is very convenient, but at the smaller sizes
442 the glyphs will appear very light.
444 In LilyPond, we have created fonts in a range of weights, corresponding
445 to a range of music sizes. This is a LilyPond engraving at staff size
450 @sourceimage{pdf/size26,,23mm,}
453 @sourceimage{size26,,,png}
458 and this is the same engraving set at staff size 11, then
459 magnified by 236% to print at the same size as the previous example:
463 @sourceimage{pdf/size11,,23mm,}
466 @sourceimage{size11,,,png}
471 At smaller sizes, LilyPond uses proportionally heavier lines so the
472 music will still read well.
475 This also allows staves of different sizes to coexist peacefully when
476 used together on the same page:
478 @c TODO: are the stems in this example the right thickness? How should
479 @c line weights be scaled for small staves?
481 @c Grieg's Violin Sonata Op. 45
482 @lilypond[indent=1.5cm]
491 \override StaffSymbol #'staff-space = #(magstep -4)
492 \override StaffSymbol #'thickness = #(magstep -3)
496 \set Staff.instrumentName = #"Violin"
497 c8.(\f^> b16 c d) ees8.(^> d16 c b)
498 g8.(^> b16 c ees) g8-.^> r r
502 \set PianoStaff.instrumentName = #"Piano"
503 \new Staff \relative c' {
506 s4. s8 r8 r16 <c f aes c>
507 <c f aes c>4.^> <c ees g>8 r r
509 \new Staff \relative c {
513 \once \override DynamicText #'X-offset = #-3
515 <ees g c>4.~ <ees g c>8
518 <c g c,>4.~ <c g c,>8
520 r8 r16 <f, c' aes'>16
521 <f c' aes'>4.-> <c' g'>8 r r
528 @node Why work so hard?
529 @unnumberedsubsec Why work so hard?
531 Musicians are usually more absorbed with performing than with studying
532 the looks of a piece of music, so nitpicking typographical details may
533 seem academic. But it is not. Sheet music is performance material:
534 everything is done to aid the musician in letting her perform better,
535 and anything that is unclear or unpleasant to read is a hindrance.
537 Traditionally engraved music uses bold symbols on heavy staff to create
538 a strong, well-balanced look that stands out well when the music is far
539 away from the reader: for example, if it is on a music stand. A careful
540 distribution of white space allows music to be set very tightly without
541 crowding symbols together. The result minimizes the number of page
542 turns, which is a great advantage.
544 This is a common characteristic of typography. Layout should be pretty,
545 not only for its own sake, but especially because it helps the reader in
546 his task. For sheet music this is of double importance because musicians
547 have a limited amount of attention. The less attention they need for
548 reading, the more they can focus on playing the music. In other words,
549 better typography translates to better performances.
551 These examples demonstrate that music typography is an art that is
552 subtle and complex, and that producing it requires considerable
553 expertise, which musicians usually do not have. LilyPond is our
554 effort to bring the graphical excellence of hand-engraved music to
555 the computer age, and make it available to normal musicians. We
556 have tuned our algorithms, font-designs, and program settings to
557 produce prints that match the quality of the old editions we love
558 to see and love to play from.
561 @node Automated engraving
562 @unnumberedsec Automated engraving
564 @cindex engraving, automated
565 @cindex automated engraving
567 This section describes what is required to create software that can
568 mimic the layout of engraved scores: a method of explaining good
569 layouts to the computer, detailed comparisons with real engravings,
570 and enough flexibility to deal with the wide range of challenges
571 that printed music can present.
575 * Improvement by benchmarking::
576 * Getting things right::
577 * Flexible architecture::
580 @node Beauty contests
581 @unnumberedsubsec Beauty contests
583 How do we actually make formatting decisions? In other words, which
584 of the three configurations should we choose for the following slur?
589 \once \override Slur #'positions = #'(1.5 . 1)
590 e8[( f] g[ a b d,)] r4
591 \once \override Slur #'positions = #'(2 . 3)
592 e8[( f] g[ a b d,)] r4
593 e8[( f] g[ a b d,)] r4
597 There are a few books on the art of music engraving
598 available. Unfortunately, they contain rules of simple thumbs and some
599 examples. Such rules can be instructive, but they are a far cry from
600 an algorithm that we could readily implement in a computer. Following
601 the instructions from literature leads to algorithms with lots of
602 hand coded exceptions. Doing all this case analysis is a lot of work,
603 and often not all cases are covered completely:
607 @sourceimage{ross-beam-scan,7cm,,}
610 @sourceimage{ross-beam-scan,,,.jpg}
614 (Image source: Ted Ross, @emph{The Art of Music Engraving})
616 Rather than trying to write detailed layout rules for every possible
617 scenario, we only have to describe the objectives well enough that
618 LilyPond can judge the attractiveness of several alternatives. Then,
619 for each possible configuration we compute an ugliness score and we
620 choose the least ugly configuration.
622 For example, here are three possible slur configurations, and LilyPond
623 has given each one a score in @q{ugly points}. The first example gets 15.39
624 points for grazing one of the notes:
629 \once \override Slur #'positions = #'(1.5 . 1)
630 e8[(_"15.39" f] g[ a b d,)] r4
635 second one is nicer, but the slur doesn't start or end on the note heads.
636 It gets 1.71 points for the left side and 9.37 points for the right
637 side, plus another 2 points because the slur ascends while the melody
638 descends for a total of 13.08 ugly points:
643 \once \override Slur #'positions = #'(2 . 3)
644 e8[(_"13.08" f] g[ a b d,)] r4
648 The final slur gets 10.04
649 points for the gap on the right and 2 points for the upward slope, but
650 it is the most attractive of the three configurations, so LilyPond
656 e8[(_"12.04" f] g[ a b d,)] r4
660 This technique is quite general, and is used to make optimal decisions
661 for beam configurations, ties and dots in chords, line breaks, and page
662 breaks. The results of these decisions can be judged by comparison to
665 @node Improvement by benchmarking
666 @unnumberedsubsec Improvement by benchmarking
668 LilyPond's output has improved gradually over time, and it continues to
669 improve by comparing its output to hand-engraved scores.
671 For example, here is one line of a benchmark piece from a
672 hand-engraved edition (Bärenreiter BA320):
675 @sourceimage{baer-sarabande-hires,16cm,,}
678 @sourceimage{baer-sarabande,,,png}
682 and the same quotation as engraved by a very old version of LilyPond
683 (version 1.4, May 2001):
686 @sourceimage{pdf/lily14-sarabande,16cm,,}
689 @sourceimage{lily14-sarabande,,,png}
692 @noindent The LilyPond 1.4 output is certainly readable, but close
693 comparison with the hand-engraved score showed a lot of errors in the
697 @sourceimage{lily14-sarabande-annotated-hires,16cm,,}
700 @sourceimage{lily14-sarabande-annotated,,,png}
704 @item there is too much space before the time signature
705 @item the stems of the beamed notes are too long
706 @item the second and fourth measures are too narrow
707 @item the slur is awkward-looking
708 @item the trill marks are too big
709 @item the stems are too thin
713 (There were also two missing note heads, several missing editorial
714 annotations, and an incorrect pitch!)
716 By adjusting the layout rules and font design, the output has improved
717 considerably. Compare the same reference score and the output
718 from the current version of LilyPond (@version{}):
721 @sourceimage{baer-sarabande-hires,16cm,,}
724 @sourceimage{baer-sarabande,,,png}
727 @lilypond[staffsize=17.5,line-width=15.9\cm]
732 \mergeDifferentlyDottedOn
733 << {\slurDashed d8.-\flageolet( e16) e4.-\trill( d16 e)}
737 <f' a, d,>4. e8( d c)
739 bes g' f e16( f g_1 a_2 bes_3 d,_2)
741 cis4.-\trill b8_3( a g)
742 << {\slurDashed d'8.( e16) e4.-\trill( d16 e)}
749 The current output is not a clone of the reference edition, but it is
750 much closer to publication quality that the earlier output.
752 @node Getting things right
753 @unnumberedsubsec Getting things right
755 We can also measure LilyPond's ability to make music engraving decisions
756 automatically by comparing LilyPond's output to the output of a
757 commercial software product. In this case we have chosen Finale 2008,
758 which is one of the most popular commercial score writers, particularly
759 in North America. Sibelius is their major rival and they appear to be
760 especially strong in the European market.
762 For our comparison we chose Bach's Fugue in G minor from the
763 Well-Tempered Clavier, Book I, BWV 861, whose opening subject is
770 r8 a16 bes c8 bes16 a bes8
776 We made our comparison by engraving the last seven measures of the piece
777 (28--34) in Finale and LilyPond. This is the point in the piece where
778 the subject returns in a three-part stretto and leads into the closing
779 section. In the Finale version, we have resisted the temptation to make
780 any adjustments to the default output because we are trying to show the
781 things that each software package gets right without assistance.
783 Many of the differences between the two engravings are visible in
784 measures 28--29, as shown here with Finale first and LilyPond second:
787 @sourceimage{pdf/bwv861mm28-29,14cm,,}
790 @sourceimage{bwv861mm28-29,,,png}
793 @lilypond[staffsize=19.5,line-width=14\cm]
794 global = {\key g \minor}
796 partI = \relative c' {
798 fis8 d' ees g, fis4 g
799 r8 a16 bes c8 bes16 a d8 r r4
802 partII = \relative c' {
804 d4 r4 r8 d'16 c bes8 c16 d
807 partIII = \relative c' {
809 r2 r8 d ees g, fis4 g r8 a16 bes c8 bes16 a
811 partIV = \relative c {
819 % \set Score.barNumberVisibility = #all-bar-numbers-visible
821 \set Score.currentBarNumber = #28
826 \new Voice = "voiceI" { \partI }
827 \new Voice = "voiceII" { \partII }
833 \new Voice = "voiceIII" { \partIII }
834 \new Voice = "voiceIV" { \partIV }
841 \remove "Time_signature_engraver"
845 \override StaffGrouper #'between-staff-spacing #'padding = #1
851 Some shortcomings in the unedited Finale output include:
853 @item Most of the beams extend too far off the staff. A beam that points
854 towards the center of the staff should have a length of about one
855 octave, but engravers shorten this when the beam points away from the
856 staff in multi-voice music. The Finale beaming can be easily improved
857 with the Patterson Beams plug-in, but we elected to skip that step for
859 @item Finale doesn't adjust the positions of interlocking note heads,
860 which makes the music extremely difficult to read when the upper and
861 lower voices exchange positions temporarily:
864 collide = \once \override NoteColumn #'force-hshift = #0
866 \new Voice = "sample" \relative c''{
869 {\voiceOne g4 \collide g4}
870 \new Voice {\voiceTwo bes \collide bes}
873 \new Lyrics \lyricsto "sample" \lyricmode { "good " " bad" }
877 @item Finale has placed all of the rests at fixed heights on the staff.
878 The user is free to adjust them as needed, but the software makes no
879 attempt to consider the content of the other voice. As luck would have
880 it, there are no true collisions between notes and rests in this example,
881 but that has more to do with the positions of the notes than the rest.
882 In other words, Bach deserves more credit for avoiding a complete
883 collision than Finale does.
887 This example is not intended to suggest that Finale cannot be used to
888 produce beautiful output. On the contrary, in the hands of a skilled
889 user it can and does, but it requires skill and time. One of the
890 fundamental differences between LilyPond and commercial score writers is
891 that LilyPond hopes to reduce the amount of human intervention to an
892 absolute minimum, while other packages try to provide an attractive
893 interface in which to make these types of edits.
895 One particularly glaring omission we found in the Finale sample is a
896 missing flat in measure 33:
900 @sourceimage{pdf/bwv861mm33-34-annotate,7.93cm,,}
903 @sourceimage{bwv861mm33-34-annotate,,,png}
908 The flat symbol is required to cancel out the natural in the same
909 measure, but Finale misses it because it occurred in a different voice.
910 The user must not only remember to run a beaming plug-in and respace the
911 note heads and rests, she must also check each measure for cross-voice
912 accidentals if she is to avoid interrupting a rehearsal for an engraving
915 If you are interested in examining these examples in more detail, the
916 full seven-measure excerpt can be found at the end of this essay in
917 engravings by Finale and LilyPond along with four different published
918 engravings. Close examination reveals that there is some acceptable
919 variation among the hand-engravings, but that LilyPond compares
920 reasonably well to that acceptable range. There are still some
921 shortcomings in the LilyPond output, for example, it appears a bit too
922 aggressive in shortening some of the stems, so there is room for further
923 development and fine-tuning.
925 Of course, typography relies on human judgment of appearance, so people
926 cannot be replaced completely. However, much of the dull work can be
927 automated. If LilyPond solves most of the common situations correctly,
928 this will be a huge improvement over existing software. Over the course
929 of years, the software can be refined to do more and more things
930 automatically, so manual overrides are less and less necessary. Where
931 manual adjustments are needed, LilyPond's structure has been designed
932 with that flexibility in mind.
934 @node Flexible architecture
935 @unnumberedsubsec Flexible architecture
937 When we started, we wrote the LilyPond program entirely in the C++
938 programming language; the program's functionality was set in stone
939 by the developers. That proved to be unsatisfactory for a number
944 @item When LilyPond makes mistakes, users need to override
945 formatting decisions. Therefore, the user must have access to the
946 formatting engine. Hence, rules and settings cannot be fixed by
947 us at compile-time but must be accessible for users at run-time.
949 @item Engraving is a matter of visual judgment, and therefore a
950 matter of taste. As knowledgeable as we are, users can disagree
951 with our personal decisions. Therefore, the definitions of
952 typographical style must also be accessible to the user.
954 @item Finally, we continually refine the formatting algorithms, so
955 we need a flexible approach to rules. The C++ language forces a
956 certain method of grouping rules that cannot readily be applied to
957 formatting music notation.
961 @cindex Scheme programming language
963 These problems have been addressed by integrating an interpreter
964 for the Scheme programming language and rewriting parts of
965 LilyPond in Scheme. The current formatting architecture is built
966 around the notion of graphical objects, described by Scheme
967 variables and functions. This architecture encompasses formatting
968 rules, typographical style and individual formatting decisions.
969 The user has direct access to most of these controls.
971 Scheme variables control layout decisions. For example, many
972 graphical objects have a direction variable that encodes the
973 choice between up and down (or left and right). Here you see two
974 chords, with accents and arpeggios. In the first chord, the
975 graphical objects have all directions down (or left). The second
976 chord has all directions up (right).
978 @lilypond[quote,ragged-right]
980 \override SpacingSpanner #'spacing-increment = #3
981 \override TimeSignature #'transparent = ##t
983 \stemDown <e g b>4_>-\arpeggio
984 \override Arpeggio #'direction = #RIGHT
985 \stemUp <e g b>4^>-\arpeggio
989 @cindex score formatting
990 @cindex formatting a score
991 @cindex formatting rules
994 The process of formatting a score consists of reading and writing
995 the variables of graphical objects. Some variables have a preset
996 value. For example, the thickness of many lines -- a
997 characteristic of typographical style -- is a variable with a
998 preset value. You are free to alter this value, giving your score
999 a different typographical impression.
1001 @lilypond[quote,ragged-right]
1004 c'4-~ c'16 as g f e16 g bes c' des'4
1007 \new Staff \fragment
1009 \override Beam #'beam-thickness = #0.3
1010 \override Stem #'thickness = #0.5
1011 \override Bar #'thickness = #3.6
1012 \override Tie #'thickness = #2.2
1013 \override StaffSymbol #'thickness = #3.0
1014 \override Tie #'extra-offset = #'(0 . 0.3)
1020 Formatting rules are also preset variables: each object has
1021 variables containing procedures. These procedures perform the
1022 actual formatting, and by substituting different ones, we can
1023 change the appearance of objects. In the following example, the
1024 rule governing which note head objects are used to produce the
1025 note head symbol is changed during the music fragment.
1027 @lilypond[quote,ragged-right]
1028 #(set-global-staff-size 30)
1030 #(define (mc-squared grob orig current)
1031 (let* ((interfaces (ly:grob-interfaces grob))
1032 (pos (ly:grob-property grob 'staff-position)))
1033 (if (memq 'note-head-interface interfaces)
1035 (ly:grob-set-property! grob 'stencil
1036 (grob-interpret-markup grob
1037 (make-lower-markup 0.5
1041 ((-2) (make-smaller-markup (make-bold-markup "2")))
1042 (else "bla")))))))))
1044 \new Voice \relative c' {
1046 \set autoBeaming = ##f
1049 \once \override NoteHead #'stencil = #note-head::brew-ez-stencil
1050 \once \override NoteHead #'font-size = #-7
1051 \once \override NoteHead #'font-family = #'sans
1052 \once \override NoteHead #'font-series = #'bold
1054 \once \override NoteHead #'style = #'cross
1056 \applyOutput #'Voice #mc-squared
1059 { d8[ es-( fis^^ g] fis2-) }
1060 \repeat unfold 5 { \applyOutput #'Voice #mc-squared s8 }
1066 @node What symbols to engrave?
1067 @unnumberedsec What symbols to engrave?
1074 The formatting process decides where to place symbols. However,
1075 this can only be done once it is decided @emph{what} symbols
1076 should be printed -- in other words, what notation to use.
1078 Common music notation is a system of recording music that has
1079 evolved over the past 1000 years. The form that is now in common
1080 use dates from the early Renaissance. Although the basic form
1081 (i.e., note heads on a 5-line staff) has not changed, the details
1082 still evolve to express the innovations of contemporary notation.
1083 Hence, common music notation encompasses some 500 years of music.
1084 Its applications range from monophonic melodies to monstrous
1085 counterpoints for a large orchestra.
1087 How can we get a grip on such a seven-headed beast, and force it
1088 into the confines of a computer program? Our solution is to break
1089 up the problem of notation (as opposed to engraving, i.e.,
1090 typography) into digestible and programmable chunks: every type of
1091 symbol is handled by a separate module, a so-called plug-in. Each
1092 plug-in is completely modular and independent, so each can be
1093 developed and improved separately. Such plug-ins are called
1094 @code{engraver}s, by analogy with craftsmen who translate musical
1095 ideas to graphic symbols.
1097 In the following example, we start out with a plug-in for note
1098 heads, the @code{Note_heads_engraver}.
1100 @lilypond[quote,ragged-right]
1101 \include "engraver-example.ily"
1108 \remove "Stem_engraver"
1109 \remove "Phrasing_slur_engraver"
1110 \remove "Slur_engraver"
1111 \remove "Script_engraver"
1112 \remove "Beam_engraver"
1113 \remove "Auto_beam_engraver"
1117 \remove "Accidental_engraver"
1118 \remove "Key_engraver"
1119 \remove "Clef_engraver"
1120 \remove "Bar_engraver"
1121 \remove "Time_signature_engraver"
1122 \remove "Staff_symbol_engraver"
1123 \consists "Pitch_squash_engraver"
1130 Then a @code{Staff_symbol_engraver} adds the staff,
1132 @lilypond[quote,ragged-right]
1133 \include "engraver-example.ily"
1140 \remove "Stem_engraver"
1141 \remove "Phrasing_slur_engraver"
1142 \remove "Slur_engraver"
1143 \remove "Script_engraver"
1144 \remove "Beam_engraver"
1145 \remove "Auto_beam_engraver"
1149 \remove "Accidental_engraver"
1150 \remove "Key_engraver"
1151 \remove "Clef_engraver"
1152 \remove "Bar_engraver"
1153 \consists "Pitch_squash_engraver"
1154 \remove "Time_signature_engraver"
1161 the @code{Clef_engraver} defines a reference point for the staff,
1163 @lilypond[quote,ragged-right]
1164 \include "engraver-example.ily"
1171 \remove "Stem_engraver"
1172 \remove "Phrasing_slur_engraver"
1173 \remove "Slur_engraver"
1174 \remove "Script_engraver"
1175 \remove "Beam_engraver"
1176 \remove "Auto_beam_engraver"
1180 \remove "Accidental_engraver"
1181 \remove "Key_engraver"
1182 \remove "Bar_engraver"
1183 \remove "Time_signature_engraver"
1190 and the @code{Stem_engraver} adds stems.
1192 @lilypond[quote,ragged-right]
1193 \include "engraver-example.ily"
1200 \remove "Phrasing_slur_engraver"
1201 \remove "Slur_engraver"
1202 \remove "Script_engraver"
1203 \remove "Beam_engraver"
1204 \remove "Auto_beam_engraver"
1208 \remove "Accidental_engraver"
1209 \remove "Key_engraver"
1210 \remove "Bar_engraver"
1211 \remove "Time_signature_engraver"
1218 The @code{Stem_engraver} is notified of any note head coming
1219 along. Every time one (or more, for a chord) note head is seen, a
1220 stem object is created and connected to the note head. By adding
1221 engravers for beams, slurs, accents, accidentals, bar lines, time
1222 signature, and key signature, we get a complete piece of notation.
1224 @lilypond[quote,ragged-right]
1225 \include "engraver-example.ily"
1226 \score { \topVoice }
1230 @cindex engraving multiple voices
1233 This system works well for monophonic music, but what about
1234 polyphony? In polyphonic notation, many voices can share a staff.
1236 @lilypond[quote,ragged-right]
1237 \include "engraver-example.ily"
1238 \new Staff << \topVoice \\ \botVoice >>
1241 In this situation, the accidentals and staff are shared, but the
1242 stems, slurs, beams, etc., are private to each voice. Hence,
1243 engravers should be grouped. The engravers for note heads, stems,
1244 slurs, etc., go into a group called @q{Voice context}, while the
1245 engravers for key, accidental, bar, etc., go into a group called
1246 @q{Staff context}. In the case of polyphony, a single Staff
1247 context contains more than one Voice context. Similarly, multiple
1248 Staff contexts can be put into a single Score context. The Score
1249 context is the top level notation context.
1253 Internals Reference: @rinternals{Contexts}.
1256 @lilypond[quote,ragged-right]
1257 \include "engraver-example.ily"
1260 \new Staff << \topVoice \\ \botVoice >>
1261 \new Staff << \pah \\ \hoom >>
1267 @node Music representation
1268 @unnumberedsec Music representation
1271 @cindex recursive structures
1273 Ideally, the input format for any high-level formatting system is
1274 an abstract description of the content. In this case, that would
1275 be the music itself. This poses a formidable problem: how can we
1276 define what music really is? Instead of trying to find an answer,
1277 we have reversed the question. We write a program capable of
1278 producing sheet music, and adjust the format to be as lean as
1279 possible. When the format can no longer be trimmed down, by
1280 definition we are left with content itself. Our program serves as
1281 a formal definition of a music document.
1283 The syntax is also the user-interface for LilyPond, hence it is
1293 to create a quarter note on middle C (C1) and an eighth note on
1294 the D above middle C (D1).
1302 On a microscopic scale, such syntax is easy to use. On a larger
1303 scale, syntax also needs structure. How else can you enter
1304 complex pieces like symphonies and operas? The structure is
1305 formed by the concept of music expressions: by combining small
1306 fragments of music into larger ones, more complex music can be
1307 expressed. For example
1309 @lilypond[quote,verbatim,fragment,relative=1]
1314 Simultaneous notes can be constructed by enclosing them with
1315 @code{<<} and @code{>>}:
1321 @lilypond[quote,fragment,relative=1]
1322 \new Voice { <<c4 d4 e>> }
1326 This expression is put in sequence by enclosing it in curly braces
1327 @code{@{@tie{}@dots{}@tie{}@}}:
1330 @{ f4 <<c4 d4 e4>> @}
1333 @lilypond[quote,relative=1,fragment]
1338 The above is also an expression, and so it may be combined again
1339 with another simultaneous expression (a half note) using
1340 @code{<<}, @code{\\}, and @code{>>}:
1343 << g2 \\ @{ f4 <<c4 d4 e4>> @} >>
1346 @lilypond[quote,fragment,relative=2]
1347 \new Voice { << g2 \\ { f4 <<c d e>> } >> }
1350 Such recursive structures can be specified neatly and formally in
1351 a context-free grammar. The parsing code is also generated from
1352 this grammar. In other words, the syntax of LilyPond is clearly
1353 and unambiguously defined.
1355 User-interfaces and syntax are what people see and deal with most.
1356 They are partly a matter of taste, and also the subject of much
1357 discussion. Although discussions on taste do have their merit,
1358 they are not very productive. In the larger picture of LilyPond,
1359 the importance of input syntax is small: inventing neat syntax is
1360 easy, while writing decent formatting code is much harder. This
1361 is also illustrated by the line-counts for the respective
1362 components: parsing and representation take up less than 10% of
1366 @node Example applications
1367 @unnumberedsec Example applications
1369 @cindex simple examples
1370 @cindex examples, simple
1372 We have written LilyPond as an experiment of how to condense the
1373 art of music engraving into a computer program. Thanks to all
1374 that hard work, the program can now be used to perform useful
1375 tasks. The simplest application is printing notes.
1377 @lilypond[quote,relative=1]
1385 By adding chord names and lyrics we obtain a lead sheet.
1387 @lilypond[quote,ragged-right]
1389 \chords { c2 c f2 c }
1395 \addlyrics { twin -- kle twin -- kle lit -- tle star }
1399 Polyphonic notation and piano music can also be printed. The
1400 following example combines some more exotic constructs.
1404 title = "Screech and boink"
1405 subtitle = "Random complex notation"
1406 composer = "Han-Wen Nienhuys"
1410 \context PianoStaff <<
1415 \revert Stem #'direction
1416 \change Staff = down
1417 \set subdivideBeams = ##t
1421 \change Staff = down
1425 \change Staff = down
1429 \set followVoice = ##t
1430 c'''32([ b''16 a''16 gis''16 g''32)]
1432 s4 \times 2/3 { d'16[ f' g'] } as'32[ b''32 e'' d'']
1434 s4 \autoBeamOff d''8.. f''32
1440 \new Staff = "down" {
1443 \set subdivideBeams = ##f
1444 \override Stem #'french-beaming = ##t
1445 \override Beam #'beam-thickness = #0.3
1446 \override Stem #'thickness = #4.0
1447 g'16[ b16 fis16 g16]
1453 \override Staff.Arpeggio #'arpeggio-direction =#down
1454 <cis, e, gis, b, cis>4\arpeggio
1461 tempoWholesPerMinute = #(ly:make-moment 60 8)
1467 \consists Horizontal_bracket_engraver
1473 The fragments shown above have all been written by hand, but that
1474 is not a requirement. Since the formatting engine is mostly
1475 automatic, it can serve as an output means for other programs that
1476 manipulate music. For example, it can also be used to convert
1477 databases of musical fragments to images for use on websites and
1478 multimedia presentations.
1480 This manual also shows an application: the input format is text,
1481 and can therefore be easily embedded in other text-based formats
1482 such as @LaTeX{}, HTML, or in the case of this manual, Texinfo.
1483 By means of a special program, the input fragments can be replaced
1484 by music images in the resulting PDF or HTML output files. This
1485 makes it easy to mix music and text in documents.
1488 TODO: add extra chapter for computer aesthetics?
1492 @unnumberedsec Appendix
1494 This appendix contains four reference engravings and two
1495 software-engraved versions of Bach's Fugue in G minor from the
1496 Well-Tempered Clavier, Book I, BWV 861 (the last seven measures).
1499 Bärenreiter BA5070 (Neue Ausgabe Sämtlicher Werke, Serie V, Band 6.1,
1503 @sourceimage{bwv861-baer,16cm,,}
1506 @sourceimage{bwv861-baer-small,,,png}
1510 Bärenreiter BA5070 (Neue Ausgabe Sämtlicher Werke, Serie V, Band 6.1,
1511 1989), an alternate musical source. Aside from the textual differences,
1512 this demonstrates slight variations in the engraving decisions, even
1513 from the same publisher and edition:
1516 @sourceimage{bwv861-baer-alt,16cm,,}
1519 @sourceimage{bwv861-baer-alt-small,,,png}
1523 Breitkopf & Härtel, edited by Ferruccio Busoni (Wiesbaden, 1894), also
1524 available from the Petrucci Music Library (IMSLP #22081). The editorial
1525 markings (fingerings, articulations, etc.) have been removed for clearer
1526 comparison with the other editions here:
1529 @sourceimage{bwv861-breitkopf,16cm,,}
1532 @sourceimage{bwv861-breitkopf-small,,,png}
1536 Bach-Gesellschaft edition (Leipzig, 1866), available from the Petrucci
1537 Music Library (IMSPL #02221):
1540 @sourceimage{bwv861-gessellschaft,16cm,,}
1543 @sourceimage{bwv861-gessellschaft-small,,,png}
1550 @sourceimage{pdf/bwv861-finale2008a,,,}
1553 @sourceimage{bwv861-finale2008a,,,png}
1558 LilyPond, version @version{}:
1560 @lilypond[staffsize=14.3,line-width=15.9\cm]
1561 global = {\key g \minor}
1563 partI = \relative c' {
1565 fis8 d' ees g, fis4 g
1566 r8 a16 bes c8 bes16 a d8 r r4
1567 r2 r8 d16 ees f8 ees16 d
1568 ees4 ~ ees16 d c bes a4 r8 ees'16 d
1569 c8 d16 ees d8 e16 fis g8 fis16 g a4 ~
1570 a8 d, g f ees d c bes
1571 a2 g\fermata \bar "|."
1574 partII = \relative c' {
1576 d4 r4 r8 d'16 c bes8 c16 d
1577 ees8 d c ees a, r r4
1578 r8 fis16 g a8 g16 fis g2 ~
1580 fis4 g r8 a16 bes c8 bes16 a
1581 bes4. <g b>8 <a c> r <d, g> r
1584 partIII = \relative c' {
1586 r2 r8 d ees g, fis4 g r8 a16 bes c8 bes16 a
1587 bes2 ~ bes8 b16 a g8 a16 b
1591 r8 a16 bes c8 bes16 a b2
1593 partIV = \relative c {
1597 d,8 d'16 c bes8 c16 d ees2 ~
1598 ees8 ees16 d c8 d16 ees fis,8 a16 g fis8 g16 a
1599 d,8 d'16 c bes8 c16 d ees8 c a fis'
1606 % \set Score.barNumberVisibility = #all-bar-numbers-visible
1608 \set Score.currentBarNumber = #28
1611 \new Staff = "RH" <<
1613 \new Voice = "voiceI" { \partI }
1614 \new Voice = "voiceII" { \partII }
1617 \new Staff = "LH" <<
1620 \new Voice = "voiceIII" { \partIII }
1621 \new Voice = "voiceIV" { \partIV }
1628 \remove "Time_signature_engraver"
1632 \override StaffGrouper #'between-staff-spacing #'padding = #1