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. See TRANSLATION for details.
13 @chapter Music engraving
15 This section covers the overall goals and architecture of
19 @c update LP 1.4 example with PDF
20 @c annotate typography errors in old LilyPond
22 @c add 'tweaked' versions of LP & Finale BWV 861
23 @c find a good value for #'between-staff-spacing #'padding
24 @c remove 3mm eps bounding box left padding for Sarabande (This will
25 @c require adding a new snippet option to lilypond-book.py
28 @c Incorrect beaming in the Sarabande is a known bug.
32 * Automated engraving::
33 * What symbols to engrave?::
34 * Music representation::
35 * Example applications::
39 @node The LilyPond story
40 @unnumberedsec The LilyPond story
42 Before LilyPond had a community of users around the world, before it had
43 been used to produce university course notes or world-premier opera
44 performance scores, before there was an essay on music engraving or any
45 computer code or even an organized team of developers, LilyPond began
49 Why does most computer output fail to achieve the beauty and balance of
50 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 veiw 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 ``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 barline in the middle of each line: in the
95 hand-engraved score the position of these barlines has some natural
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 noteheads 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 noteheads,
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 @c Now all newly printed music is produced with computers. This has
183 @c obvious advantages: prints are cheaper to make, editorial work can be
184 @c delivered by email, and the original data can be easily stored.
185 @c Unfortunately, computer-generated scores rarely match the quality of
186 @c hand-engraved scores. Instead, computer printouts have a bland,
187 @c mechanical look, which makes them unpleasant to play from.
194 * Why work so hard?::
198 @unnumberedsubsec Music fonts
200 The images below illustrate some differences between traditional
201 engraving and typical computer output. The left picture shows a scan of
202 a flat symbol from a hand-engraved Bärenreiter edition, while the right
203 picture depicts a symbol from an edition of the same music published in
204 2000. Although both images are printed in the same shade of ink, the
205 earlier version looks darker: the staff lines are heavier, and the
206 Bärenreiter flat has a bold, almost voluptuous rounded look. The right
207 scan, on the other hand, has thinner lines and a straight layout with
210 @multitable @columnfractions .25 .25 .25 .25
214 @sourceimage{baer-flat-gray,,4cm,}
217 @sourceimage{baer-flat-gray,,,png}
222 @sourceimage{henle-flat-gray,,4cm,}
225 @sourceimage{henle-flat-gray,,,png}
230 @sourceimage{henle-flat-bw,,,png}
231 @sourceimage{baer-flat-bw,,,png}
232 @sourceimage{lily-flat-bw,,,png}
243 @cindex musical symbols
248 When we wanted to write a computer program to create music typography,
249 there were no musical fonts freely available that could match the
250 elegance of our favorite scores. Undeterred, we created a font of
251 musical symbols, relying on nice printouts of hand-engraved music. The
252 experience helped develop a typographical taste, and it made us
253 appreciate subtle design details. Without that experience, we would not
254 have realized how ugly the fonts were that we admired at first.
256 Below is a sample of two music fonts: the upper set is the default font
257 in the Sibelius software (the @emph{Opus} font), and the lower set is
258 our own LilyPond font.
262 @sourceimage{pdf/OpusAndFeta,,,}
265 @sourceimage{OpusAndFeta,,,png}
269 The LilyPond symbols are heavier and their weight is more consistent,
270 which makes them easier to read. Fine endings, such as the ones on the
271 sides of the quarter rest, should not end in sharp points, but rather
272 in rounded shapes. This is because sharp corners of the punching dies
273 are fragile and quickly wear out when stamping in metal. Taken together,
274 the blackness of the font must be carefully tuned together with the
275 thickness of lines, beams and slurs to give a strong yet balanced
278 Also, notice that our half-notehead is not elliptic but slightly diamond
279 shaped. The vertical stem of a flat symbol is slightly brushed, becoming
280 wider at the top. The sharp and the natural are easier to distinguish
281 from a distance because their angled lines have different slopes and the
282 vertical strokes are heavier.
284 @node Optical spacing
285 @unnumberedsubsec Optical spacing
287 In spacing, the distribution of space should reflect the durations
288 between notes. However, as we saw in the Bach Suite above, many modern
289 scores adhere to the durations with mathematical precision, which leads
290 to poor results. In the next example a motive is printed twice: the
291 first time using exact mathematical spacing, and the second with
292 corrections. Which do you prefer?
294 @cindex optical spacing
315 \override NoteSpacing #'stem-spacing-correction = #0.0
316 \override NoteSpacing #'same-direction-correction = #0.0
317 \override StaffSpacing #'stem-spacing-correction = #0.0
343 \override NoteSpacing #'stem-spacing-correction = #0.6
349 @cindex regular rhythms
350 @cindex regular spacing
351 @cindex spacing, regular
353 Each bar in the fragment only uses notes that are played in a constant
354 rhythm. The spacing should reflect that. Unfortunately, the eye deceives
355 us a little; not only does it notice the distance between note heads, it
356 also takes into account the distance between consecutive stems. As a
357 result, the notes of an up-stem/@/down-stem combination should be put
358 farther apart, and the notes of a down-stem/@/up-stem combination should
359 be put closer together, all depending on the combined vertical positions
360 of the notes. The lower two measures are printed with this correction,
361 the upper two measures, however, form down-stem/@/up-stem clumps of
362 notes. A master engraver would adjust the spacing as needed to please
365 Another example of optical spacing is the visual interplay between the
366 stems and the bar lines. When an up-stem precedes the bar line, a little
367 more space is needed to keep it from feeling crowded:
376 c''8 c'' c'' c'' c'' c'' c'' c'' \break
377 a' a' a' a' a' a' a' a'
382 \remove "Time_signature_engraver"
383 \override NoteSpacing #'stem-spacing-correction = #0.7
387 \remove "Bar_number_engraver"
394 @unnumberedsubsec Ledger lines
399 Ledger lines present a typographical challenge: they make it more
400 difficult to space musical symbols close together and they must be clear
401 enough to identify the pitch at a glance. In the example below, we see
402 that ledger lines should be thicker than normal staff lines and that an
403 expert engraver will shorten a ledger line to allow closer spacing with
404 accidentals. We have included this feature in LilyPond's engraving.
406 @multitable @columnfractions .25 .25 .25 .25
410 @sourceimage{baer-ledger,3cm,,}
413 @sourceimage{baer-ledger,,,png}
419 @sourceimage{lily-ledger,3cm,,}
422 @sourceimage{lily-ledger,,,png}
429 @unnumberedsubsec Optical sizing
431 Music may need to be printed in a range of sizes. Originally, this was
432 accomplished by creating punching dies in each of the required sizes,
433 which meant that each die was designed to look its best at that size.
434 With the advent of digital fonts, a single outline can be mathematically
435 scaled to any size, which is very convenient, but at the smaller sizes
436 the glyphs will appear very light.
438 In LilyPond, we have created fonts in a range of weights, corresponding
439 to a range of music sizes. This is a LilyPond engraving at staff size
444 @sourceimage{pdf/size26,,23mm,}
447 @sourceimage{size26,,,png}
452 and this is the same engraving set at staff size 11, then
453 magnified by 236% to print at the same size as the previous example:
457 @sourceimage{pdf/size11,,23mm,}
460 @sourceimage{size11,,,png}
464 At smaller sizes, LilyPond uses proportionally heavier lines and so the
465 music will still read well. This also allows staves of different
466 sizes to coexist peacefully when used together on the same page:
468 @c Grieg's Violin Sonata Op. 45
469 @lilypond[indent=1.5cm]
478 \override StaffSymbol #'staff-space = #(magstep -4)
479 \override StaffSymbol #'thickness = #(magstep -3)
483 \set Staff.instrumentName = #"Violin"
484 c8.(\f^> b16 c d) ees8.(^> d16 c b)
485 g8.(^> b16 c ees) g8-.^> r r
489 \set PianoStaff.instrumentName = #"Piano"
490 \new Staff \relative c' {
493 s4. s8 r8 r16 <c f aes c>
494 <c f aes c>4.^> <c ees g>8 r r
496 \new Staff \relative c {
500 \once \override DynamicText #'X-offset = #-3
502 <ees g c>4.~ <ees g c>8
505 <c g c,>4.~ <c g c,>8
507 r8 r16 <f, c' aes'>16
508 <f c' aes'>4.-> <c' g'>8 r r
514 @node Why work so hard?
515 @unnumberedsubsec Why work so hard?
517 Musicians are usually more absorbed with performing than with studying
518 the looks of a piece of music, so nitpicking typographical details may
519 seem academic. But it is not. Sheet music is performance material:
520 everything is done to aid the musician in letting her perform better,
521 and anything that is unclear or unpleasant to read is a hinderance.
523 Traditionally engraved music uses bold symbols on heavy staff to create
524 a strong, well-balanced look that stands out well when the music is far
525 away from the reader: for example, if it is on a music stand. A careful
526 distribution of white space allows music to be set very tightly without
527 crowding symbols together. The result minimizes the number of page
528 turns, which is a great advantage.
530 This is a common characteristic of typography. Layout should be pretty,
531 not only for its own sake, but especially because it helps the reader in
532 his task. For sheet music this is of double importance because musicians
533 have a limited amount of attention. The less attention they need for
534 reading, the more they can focus on playing the music. In other words,
535 better typography translates to better performances.
537 These examples demonstrate that music typography is an art that is
538 subtle and complex, and that producing it requires considerable
539 expertise, which musicians usually do not have. LilyPond is our
540 effort to bring the graphical excellence of hand-engraved music to
541 the computer age, and make it available to normal musicians. We
542 have tuned our algorithms, font-designs, and program settings to
543 produce prints that match the quality of the old editions we love
544 to see and love to play from.
547 @node Automated engraving
548 @unnumberedsec Automated engraving
550 @cindex engraving, automated
551 @cindex automated engraving
555 * Notation benchmarking::
556 * Flexible architecture::
559 @node Beauty contests
560 @unnumberedsubsec Beauty contests
562 Rather than trying to write rules that describe how to draw an
563 attractive slur for every possible scenario, we have written rules that
564 describe an attractive slur and LilyPond finds the nicest possibility.
565 For example, here are three possible slur configurations, and LilyPond
566 has given each one a score in `ugly points':
569 %\layout { #(define debug-slur-scoring #t) }
573 \once \override Slur #'positions = #'(1.5 . 1)
574 e8[(_"15.39" f] g[ a b d,)] r4
575 \once \override Slur #'positions = #'(2 . 3)
576 e8[(_"13.08" f] g[ a b d,)] r4
577 e8[(_"12.04" f] g[ a b d,)] r4
583 The first example gets 15.39 points for grazing one of the notes. The
584 second one is nicer, but the slur doesn't start or end on the noteheads.
585 It gets 1.71 points for the left side and 9.37 points for the right
586 side, plus another 2 points because the slur ascends while the melody
587 descends for a total of 13.08 ulgy points. The final slur gets 10.04
588 points for the gap on the right and 2 points for the upward slope, but
589 it is the most attractive of the three configurations, so LilyPond
592 This technique is quite general, and is used to select beam
593 configurations, ties and dots in chords, line breaks, and page breaks.
595 @node Notation benchmarking
596 @unnumberedsubsec Notation benchmarking
598 We have tuned LilyPond's layout rules by comparing its output to
599 hand-engraved scores. Here is one line of a benchmark piece from a
600 hand-engraved edition (Bärenreiter BA320), and as engraved by an old
601 version of LilyPond (version 1.4, released May 2001):
604 @sourceimage{baer-sarabande-hires,16cm,,}
607 @sourceimage{baer-sarabande,,,png}
611 @sourceimage{lily14-sarabande,16cm,,}
614 @sourceimage{lily14-sarabande,,,png}
617 @noindent The LilyPond 1.4 output is certainly readable, but close
618 comparison with the hand-engraved score showed a lot of errors in the
622 @item most of the stems are too long
623 @item the trill marks are too big
624 @item the second and fourth measures are too narrow
625 @item the slur is awkward-looking
626 @item the stems are too thin
627 @item there was too much space before the time signature
631 (There were also two missing notes, and one wrong one!)
633 By adjusting the layout rules and font design, the output has improved
634 considerably. This is the same musical quotation compared to the output
635 from the current version of LilyPond (@version{}):
638 @sourceimage{baer-sarabande-hires,16cm,,}
641 @sourceimage{baer-sarabande,,,png}
644 @lilypond[staffsize=17.5,line-width=15.9\cm]
649 \mergeDifferentlyDottedOn
650 << {\slurDashed d8.-\flageolet( e16) e4.-\trill( d16 e)}
654 <f' a, d,>4. e8( d c)
656 bes g' f e16( f g_1 a_2 bes_3 d,_2)
658 cis4.-\trill b8_3( a g)
659 << {\slurDashed d'8.( e16) e4.-\trill( d16 e)}
666 The current output is not a clone of the reference edition, but it is
667 much closer to publication quality that the earlier output.
669 [@strong{Andrew H:} This comparison is not finished. I promise not to
670 leave it in such a mess!]
672 Another valuable form of benchmarking is comparing LilyPond's output to
673 the output of a commercial software product. In this case we have chosen
674 Finale 2008, which is one of the most popular commercial scorewriters,
675 particularly in North America. Sibelius is their major rival and they
676 appear to be especially strong in the European market.
678 We have selected the last seven measures of Bach's Fugue in G minor from
679 the Well-Tempered Clavier, Book I, BWV 861. In the final draft there
680 will be pitcures here, but for now please consult the appendix
681 (currently pp. 12--14) for the output from both programs and images from
682 four reference engravings.
687 @item Finale rests are always at the same heights (in v1/v2 situations).
688 @item Finale doesn't interlock notes nicely (mm. 28--29).
689 @item Finale misses the B-flat in mm. 33!
690 @item Finale's beamed stems are almost always too long when they extend
692 @item LilyPond 2.13.5 has a vertical spacing problem (no padding).
693 @item LilyPond could use a little more space before the first note of
695 @item LilyPond's ties to beat 1 of mm. 31 are shorter than any of the
696 reference scores, and Finale's are even worse.
697 @item LilyPond's stems are often shorter than any of the references,
698 especially RH mm. 31.
699 @item In some locations, the Bärenreiter engraver(s) place rests
700 further from the staff than strictly necessary in order to keep them
701 vertically close to the subsequent element in that voice (e.g. mm. 28).
702 @item There is some acceptable variation within the reference scores,
703 although some scores are more attractive than others.
706 @c Han-Wen said once:
707 @c A lot of readers misinterpret the Finale example. Finale is a
708 @c powerful package, and in the hands of a good engraver — which is
709 @c something different from a good musician — it can produce very good
710 @c scores. However, the friendly GUI is misleading: you need a lot of
711 @c time and expertise to get decent scores from Finale.
713 @c How do we go about implementing typography? If craftsmen need
714 @c over ten years to become true masters, how could we simple hackers
715 @c ever write a program to take over their jobs?
717 @c The answer is: we cannot.
719 The last two points lead into this concluding/transition paragraph:
721 Typography relies on human judgment of
722 appearance, so people cannot be replaced completely. However,
723 much of the dull work can be automated. If LilyPond solves most
724 of the common situations correctly, this will be a huge
725 improvement over existing software. The remaining cases can be
726 tuned by hand. Over the course of years, the software can be
727 refined to do more and more things automatically, so manual
728 overrides are less and less necessary. Where manual adjustments are
729 needed, LilyPond's structure must be ...
731 @node Flexible architecture
732 @unnumberedsubsec Flexible architecture
734 When we started, we wrote the LilyPond program entirely in the C++
735 programming language; the program's functionality was set in stone
736 by the developers. That proved to be unsatisfactory for a number
741 @item When LilyPond makes mistakes, users need to override
742 formatting decisions. Therefore, the user must have access to the
743 formatting engine. Hence, rules and settings cannot be fixed by
744 us at compile-time but must be accessible for users at run-time.
746 @item Engraving is a matter of visual judgment, and therefore a
747 matter of taste. As knowledgeable as we are, users can disagree
748 with our personal decisions. Therefore, the definitions of
749 typographical style must also be accessible to the user.
751 @item Finally, we continually refine the formatting algorithms, so
752 we need a flexible approach to rules. The C++ language forces a
753 certain method of grouping rules that cannot readily be applied to
754 formatting music notation.
758 @cindex Scheme programming language
760 These problems have been addressed by integrating an interpreter
761 for the Scheme programming language and rewriting parts of
762 LilyPond in Scheme. The current formatting architecture is built
763 around the notion of graphical objects, described by Scheme
764 variables and functions. This architecture encompasses formatting
765 rules, typographical style and individual formatting decisions.
766 The user has direct access to most of these controls.
768 Scheme variables control layout decisions. For example, many
769 graphical objects have a direction variable that encodes the
770 choice between up and down (or left and right). Here you see two
771 chords, with accents and arpeggios. In the first chord, the
772 graphical objects have all directions down (or left). The second
773 chord has all directions up (right).
775 @lilypond[quote,ragged-right]
777 \override SpacingSpanner #'spacing-increment = #3
778 \override TimeSignature #'transparent = ##t
780 \stemDown <e g b>4_>-\arpeggio
781 \override Arpeggio #'direction = #RIGHT
782 \stemUp <e g b>4^>-\arpeggio
786 @cindex score formatting
787 @cindex formatting a score
788 @cindex formatting rules
791 The process of formatting a score consists of reading and writing
792 the variables of graphical objects. Some variables have a preset
793 value. For example, the thickness of many lines -- a
794 characteristic of typographical style -- is a variable with a
795 preset value. You are free to alter this value, giving your score
796 a different typographical impression.
798 @lilypond[quote,ragged-right]
801 c'4-~ c'16 as g f e16 g bes c' des'4
806 \override Beam #'beam-thickness = #0.3
807 \override Stem #'thickness = #0.5
808 \override Bar #'thickness = #3.6
809 \override Tie #'thickness = #2.2
810 \override StaffSymbol #'thickness = #3.0
811 \override Tie #'extra-offset = #'(0 . 0.3)
817 Formatting rules are also preset variables: each object has
818 variables containing procedures. These procedures perform the
819 actual formatting, and by substituting different ones, we can
820 change the appearance of objects. In the following example, the
821 rule governing which note head objects are used to produce the
822 note head symbol is changed during the music fragment.
824 @lilypond[quote,ragged-right]
825 #(set-global-staff-size 30)
827 #(define (mc-squared grob orig current)
828 (let* ((interfaces (ly:grob-interfaces grob))
829 (pos (ly:grob-property grob 'staff-position)))
830 (if (memq 'note-head-interface interfaces)
832 (ly:grob-set-property! grob 'stencil
833 (grob-interpret-markup grob
834 (make-lower-markup 0.5
838 ((-2) (make-smaller-markup (make-bold-markup "2")))
841 \new Voice \relative c' {
843 \set autoBeaming = ##f
846 \once \override NoteHead #'stencil = #note-head::brew-ez-stencil
847 \once \override NoteHead #'font-size = #-7
848 \once \override NoteHead #'font-family = #'sans
849 \once \override NoteHead #'font-series = #'bold
851 \once \override NoteHead #'style = #'cross
853 \applyOutput #'Voice #mc-squared
856 { d8[ es-( fis^^ g] fis2-) }
857 \repeat unfold 5 { \applyOutput #'Voice #mc-squared s8 }
863 @node What symbols to engrave?
864 @unnumberedsec What symbols to engrave?
871 The formatting process decides where to place symbols. However,
872 this can only be done once it is decided @emph{what} symbols
873 should be printed -- in other words, what notation to use.
875 Common music notation is a system of recording music that has
876 evolved over the past 1000 years. The form that is now in common
877 use dates from the early Renaissance. Although the basic form
878 (i.e., note heads on a 5-line staff) has not changed, the details
879 still evolve to express the innovations of contemporary notation.
880 Hence, common music notation encompasses some 500 years of music.
881 Its applications range from monophonic melodies to monstrous
882 counterpoints for a large orchestra.
884 How can we get a grip on such a seven-headed beast, and force it
885 into the confines of a computer program? Our solution is to break
886 up the problem of notation (as opposed to engraving, i.e.,
887 typography) into digestible and programmable chunks: every type of
888 symbol is handled by a separate module, a so-called plug-in. Each
889 plug-in is completely modular and independent, so each can be
890 developed and improved separately. Such plug-ins are called
891 @code{engraver}s, by analogy with craftsmen who translate musical
892 ideas to graphic symbols.
894 In the following example, we start out with a plug-in for note
895 heads, the @code{Note_heads_engraver}.
897 @lilypond[quote,ragged-right]
898 \include "engraver-example.ily"
905 \remove "Stem_engraver"
906 \remove "Phrasing_slur_engraver"
907 \remove "Slur_engraver"
908 \remove "Script_engraver"
909 \remove "Beam_engraver"
910 \remove "Auto_beam_engraver"
914 \remove "Accidental_engraver"
915 \remove "Key_engraver"
916 \remove "Clef_engraver"
917 \remove "Bar_engraver"
918 \remove "Time_signature_engraver"
919 \remove "Staff_symbol_engraver"
920 \consists "Pitch_squash_engraver"
927 Then a @code{Staff_symbol_engraver} adds the staff,
929 @lilypond[quote,ragged-right]
930 \include "engraver-example.ily"
937 \remove "Stem_engraver"
938 \remove "Phrasing_slur_engraver"
939 \remove "Slur_engraver"
940 \remove "Script_engraver"
941 \remove "Beam_engraver"
942 \remove "Auto_beam_engraver"
946 \remove "Accidental_engraver"
947 \remove "Key_engraver"
948 \remove "Clef_engraver"
949 \remove "Bar_engraver"
950 \consists "Pitch_squash_engraver"
951 \remove "Time_signature_engraver"
958 the @code{Clef_engraver} defines a reference point for the staff,
960 @lilypond[quote,ragged-right]
961 \include "engraver-example.ily"
968 \remove "Stem_engraver"
969 \remove "Phrasing_slur_engraver"
970 \remove "Slur_engraver"
971 \remove "Script_engraver"
972 \remove "Beam_engraver"
973 \remove "Auto_beam_engraver"
977 \remove "Accidental_engraver"
978 \remove "Key_engraver"
979 \remove "Bar_engraver"
980 \remove "Time_signature_engraver"
987 and the @code{Stem_engraver} adds stems.
989 @lilypond[quote,ragged-right]
990 \include "engraver-example.ily"
997 \remove "Phrasing_slur_engraver"
998 \remove "Slur_engraver"
999 \remove "Script_engraver"
1000 \remove "Beam_engraver"
1001 \remove "Auto_beam_engraver"
1005 \remove "Accidental_engraver"
1006 \remove "Key_engraver"
1007 \remove "Bar_engraver"
1008 \remove "Time_signature_engraver"
1015 The @code{Stem_engraver} is notified of any note head coming
1016 along. Every time one (or more, for a chord) note head is seen, a
1017 stem object is created and connected to the note head. By adding
1018 engravers for beams, slurs, accents, accidentals, bar lines, time
1019 signature, and key signature, we get a complete piece of notation.
1021 @lilypond[quote,ragged-right]
1022 \include "engraver-example.ily"
1023 \score { \topVoice }
1027 @cindex engraving multiple voices
1030 This system works well for monophonic music, but what about
1031 polyphony? In polyphonic notation, many voices can share a staff.
1033 @lilypond[quote,ragged-right]
1034 \include "engraver-example.ily"
1035 \new Staff << \topVoice \\ \botVoice >>
1038 In this situation, the accidentals and staff are shared, but the
1039 stems, slurs, beams, etc., are private to each voice. Hence,
1040 engravers should be grouped. The engravers for note heads, stems,
1041 slurs, etc., go into a group called @q{Voice context,} while the
1042 engravers for key, accidental, bar, etc., go into a group called
1043 @q{Staff context.} In the case of polyphony, a single Staff
1044 context contains more than one Voice context. Similarly, multiple
1045 Staff contexts can be put into a single Score context. The Score
1046 context is the top level notation context.
1050 Internals Reference: @rinternals{Contexts}.
1053 @lilypond[quote,ragged-right]
1054 \include "engraver-example.ily"
1057 \new Staff << \topVoice \\ \botVoice >>
1058 \new Staff << \pah \\ \hoom >>
1064 @node Music representation
1065 @unnumberedsec Music representation
1068 @cindex recursive structures
1070 Ideally, the input format for any high-level formatting system is
1071 an abstract description of the content. In this case, that would
1072 be the music itself. This poses a formidable problem: how can we
1073 define what music really is? Instead of trying to find an answer,
1074 we have reversed the question. We write a program capable of
1075 producing sheet music, and adjust the format to be as lean as
1076 possible. When the format can no longer be trimmed down, by
1077 definition we are left with content itself. Our program serves as
1078 a formal definition of a music document.
1080 The syntax is also the user-interface for LilyPond, hence it is
1090 to create a quarter note on middle C (C1) and an eighth note on
1091 the D above middle C (D1).
1099 On a microscopic scale, such syntax is easy to use. On a larger
1100 scale, syntax also needs structure. How else can you enter
1101 complex pieces like symphonies and operas? The structure is
1102 formed by the concept of music expressions: by combining small
1103 fragments of music into larger ones, more complex music can be
1104 expressed. For example
1106 @lilypond[quote,verbatim,fragment,relative=1]
1111 Simultaneous notes can be constructed by enclosing them with
1112 @code{<<} and @code{>>}:
1118 @lilypond[quote,fragment,relative=1]
1119 \new Voice { <<c4 d4 e>> }
1123 This expression is put in sequence by enclosing it in curly braces
1124 @code{@{@tie{}@dots{}@tie{}@}}:
1127 @{ f4 <<c4 d4 e4>> @}
1130 @lilypond[quote,relative=1,fragment]
1135 The above is also an expression, and so it may be combined again
1136 with another simultaneous expression (a half note) using
1137 @code{<<}, @code{\\}, and @code{>>}:
1140 << g2 \\ @{ f4 <<c4 d4 e4>> @} >>
1143 @lilypond[quote,fragment,relative=2]
1144 \new Voice { << g2 \\ { f4 <<c d e>> } >> }
1147 Such recursive structures can be specified neatly and formally in
1148 a context-free grammar. The parsing code is also generated from
1149 this grammar. In other words, the syntax of LilyPond is clearly
1150 and unambiguously defined.
1152 User-interfaces and syntax are what people see and deal with most.
1153 They are partly a matter of taste, and also the subject of much
1154 discussion. Although discussions on taste do have their merit,
1155 they are not very productive. In the larger picture of LilyPond,
1156 the importance of input syntax is small: inventing neat syntax is
1157 easy, while writing decent formatting code is much harder. This
1158 is also illustrated by the line-counts for the respective
1159 components: parsing and representation take up less than 10% of
1163 @node Example applications
1164 @unnumberedsec Example applications
1166 @cindex simple examples
1167 @cindex examples, simple
1169 We have written LilyPond as an experiment of how to condense the
1170 art of music engraving into a computer program. Thanks to all
1171 that hard work, the program can now be used to perform useful
1172 tasks. The simplest application is printing notes.
1174 @lilypond[quote,relative=1]
1182 By adding chord names and lyrics we obtain a lead sheet.
1184 @lilypond[quote,ragged-right]
1186 \chords { c2 c f2 c }
1192 \addlyrics { twin -- kle twin -- kle lit -- tle star }
1196 Polyphonic notation and piano music can also be printed. The
1197 following example combines some more exotic constructs.
1201 title = "Screech and boink"
1202 subtitle = "Random complex notation"
1203 composer = "Han-Wen Nienhuys"
1207 \context PianoStaff <<
1212 \revert Stem #'direction
1213 \change Staff = down
1214 \set subdivideBeams = ##t
1218 \change Staff = down
1222 \change Staff = down
1226 \set followVoice = ##t
1227 c'''32([ b''16 a''16 gis''16 g''32)]
1229 s4 \times 2/3 { d'16[ f' g'] } as'32[ b''32 e'' d'']
1231 s4 \autoBeamOff d''8.. f''32
1237 \new Staff = "down" {
1240 \set subdivideBeams = ##f
1241 \override Stem #'french-beaming = ##t
1242 \override Beam #'beam-thickness = #0.3
1243 \override Stem #'thickness = #4.0
1244 g'16[ b16 fis16 g16]
1250 \override Staff.Arpeggio #'arpeggio-direction =#down
1251 <cis, e, gis, b, cis>4\arpeggio
1258 tempoWholesPerMinute = #(ly:make-moment 60 8)
1264 \consists Horizontal_bracket_engraver
1270 The fragments shown above have all been written by hand, but that
1271 is not a requirement. Since the formatting engine is mostly
1272 automatic, it can serve as an output means for other programs that
1273 manipulate music. For example, it can also be used to convert
1274 databases of musical fragments to images for use on websites and
1275 multimedia presentations.
1277 This manual also shows an application: the input format is text,
1278 and can therefore be easily embedded in other text-based formats
1279 such as @LaTeX{}, HTML, or in the case of this manual, Texinfo.
1280 By means of a special program, the input fragments can be replaced
1281 by music images in the resulting PDF or HTML output files. This
1282 makes it easy to mix music and text in documents.
1285 TODO: add extra chapter for computer aesthetics?
1289 @unnumberedsec Appendix
1291 This appendix contaions four reference engravings and two
1292 software-engraved versions of Bach's Fugue in G minor from the
1293 Well-Tempered Clavier, Book I, BWV 861 (the last seven measures).
1296 Bärenreiter BA5070 (Neue Ausgabe Sämtlicher Werke, Serie V, Band 6.1,
1300 @sourceimage{bwv861-baer,16cm,,}
1303 @sourceimage{bwv861-baer-small,,,png}
1307 Bärenreiter BA5070 (Neue Ausgabe Sämtlicher Werke, Serie V, Band 6.1,
1308 1989), an alternate musical source. Aside from the textual differences,
1309 this demsontrates slight variations in the engraving decisions, even
1310 from the same publisher and edition:
1313 @sourceimage{bwv861-baer-alt,16cm,,}
1316 @sourceimage{bwv861-baer-alt-small,,,png}
1320 Breitkopf & Härtel, edited by Ferruccio Busoni (Wiesbaden, 1894), also
1321 available from the Petrucci Music Library (IMSLP #22081). The editorial
1322 markings (fingerings, articulations, etc.) have been removed for clearer
1323 comparison with the other editions here:
1326 @sourceimage{bwv861-breitkopf,16cm,,}
1329 @sourceimage{bwv861-breitkopf-small,,,png}
1333 Bach-Gessellschaft edition (Leipzig, 1866), available from the Petrucci
1334 Music Library (IMSPL #02221):
1337 @sourceimage{bwv861-gessellschaft,16cm,,}
1340 @sourceimage{bwv861-gessellschaft-small,,,png}
1347 @sourceimage{pdf/bwv861-finale2008a,,,}
1350 @sourceimage{bwv861-finale2008a,,,png}
1354 LilyPond, version @version{}:
1356 @lilypond[staffsize=14.3,line-width=15.9\cm]
1357 global = {\key g \minor}
1359 partI = \relative c' {
1361 fis8 d' ees g, fis4 g
1362 r8 a16 bes c8 bes16 a d8 r r4
1363 r2 r8 d16 ees f8 ees16 d
1364 ees4 ~ ees16 d c bes a4 r8 ees'16 d
1365 c8 d16 ees d8 e16 fis g8 fis16 g a4 ~
1366 a8 d, g f ees d c bes
1367 a2 g\fermata \bar "|."
1370 partII = \relative c' {
1372 d4 r4 r8 d'16 c bes8 c16 d
1373 ees8 d c ees a, r r4
1374 r8 fis16 g a8 g16 fis g2 ~
1376 fis4 g r8 a16 bes c8 bes16 a
1377 bes4. <g b>8 <a c> r <d, g> r
1380 partIII = \relative c' {
1382 r2 r8 d ees g, fis4 g r8 a16 bes c8 bes16 a
1383 bes2 ~ bes8 b16 a g8 a16 b
1387 r8 a16 bes c8 bes16 a b2
1389 partIV = \relative c {
1393 d,8 d'16 c bes8 c16 d ees2 ~
1394 ees8 ees16 d c8 d16 ees fis,8 a16 g fis8 g16 a
1395 d,8 d'16 c bes8 c16 d ees8 c a fis'
1402 % \set Score.barNumberVisibility = #all-bar-numbers-visible
1404 \set Score.currentBarNumber = #28
1407 \new Staff = "RH" <<
1409 \new Voice = "voiceI" { \partI }
1410 \new Voice = "voiceII" { \partII }
1413 \new Staff = "LH" <<
1416 \new Voice = "voiceIII" { \partIII }
1417 \new Voice = "voiceIV" { \partIV }
1424 \remove "Time_signature_engraver"