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
20 * Automated engraving::
21 * What symbols to engrave?::
22 * Music representation::
23 * Example applications::
28 @unnumberedsec Engraving
31 @cindex typography, music
32 @cindex music typography
33 @cindex plate engraving
34 @cindex music engraving
36 The art of music typography is called @emph{(plate) engraving}. The term
37 derives from the traditional process of music printing. Just a few
38 decades ago, sheet music was made by cutting and stamping the music into
39 a zinc or pewter plate in mirror image. The plate would be inked, and
40 the depressions caused by the cutting and stamping would hold ink. An
41 image was formed by pressing paper to the plate. The stamping and
42 cutting was done completely by hand. Making a correction was cumbersome,
43 so the engraving had to be nearly perfect in one go. Engraving was a
44 highly specialized skill; a craftsman had to complete around five years
45 of training before earning the title of master engraver, and another
46 five years of experience were necessary to become truly skilled.
50 @image{pictures/hader-slaan,,7cm}
53 @sourceimage{hader-slaan,,,jpg}
57 Nowadays, all newly printed music is produced with computers. This has
58 obvious advantages: prints are cheaper to make, editorial work can be
59 delivered by email, and the original data can be easily stored.
60 Unfortunately, computer-generated scores rarely match the quality of
61 hand-engraved scores. Instead, computer printouts have a bland,
62 mechanical look, which makes them unpleasant to play from.
64 From the beginning, we designed LilyPond to mimic the beauty of
65 traditional music engraving. Along the way, we have learned a great deal
66 about the work that goes into a well-engraved score. Below we describe
67 several of those aspects that we have tried to imitate in LilyPond.
78 @unnumberedsubsec Music Fonts
80 The images below illustrate some differences between traditional
81 engraving and typical computer output. The left picture shows a scan of
82 a flat symbol from a hand-engraved Bärenreiter edition, while the right
83 picture depicts a symbol from an edition of the same music published in
84 2000. Although both images are printed in the shame shade of ink, the
85 earlier version looks darker: the staff lines are heavier, and the
86 Bärenreiter flat has a bold, almost voluptuous rounded look. The right
87 scan, on the other hand, has thinner lines and a straight layout with
90 @multitable @columnfractions .25 .25 .25 .25
94 @image{pictures/baer-flat-gray,,4cm}
97 @image{pictures/baer-flat-gray,,,png}
102 @image{pictures/henle-flat-gray,,4cm}
105 @image{pictures/henle-flat-gray,,,png}
110 @image{lilypond/pictures/henle-flat-bw,,,,png}
111 @image{lilypond/pictures/baer-flat-bw,,,,png}
112 @image{lilypond/pictures/lily-flat-bw,,,,png}
123 @cindex musical symbols
128 When we wanted to write a computer program to create music typography,
129 there were no musical fonts freely available that could match the
130 elegance of our favorite scores. Not let down, we created a font of
131 musical symbols, relying on nice printouts of hand-engraved music. The
132 experience helped develop a typographical taste, and it made us
133 appreciate subtle design details. Without that experience, we would not
134 have realized how ugly the fonts were that we admired at first.
136 Below is a sample of two music fonts: the upper set is the default font
137 in the Sibelius software (the @emph{Opus} font), and the lower set is
138 our own LilyPond font.
142 @image{pictures/pdf/OpusAndFeta,,,}
145 @sourceimage{OpusAndFeta,,,png}
149 The LilyPond symbols are heavier and their weight is more consistent,
150 which makes them easier to read. Fine endings, such as the one on the
151 bottom of the quarter rest, should not end in sharp points, but rather
152 in rounded shapes. This is because sharp corners of the punching dies
153 are fragile and quickly wear out when stamping in metal. Taken together,
154 the blackness of the font must be carefully tuned together with the
155 thickness of lines, beams and slurs to give a strong yet balanced
158 Also, notice that our half-notehead is not elliptic but slightly diamond
159 shaped. The vertical stem of a flat symbol is slightly brushed, becoming
160 wider at the top. The sharp and the natural are easier to distinguish
161 from a distance because their angled lines have different slopes and the
162 vertical strokes are heavier.
164 @node Optical Spacing
165 @unnumberedsubsec Optical Spacing
167 In spacing, the distribution of space should reflect the durations
168 between notes. However, many modern scores adhere to the
169 durations with mathematical precision, which leads to poor
170 results. In the next example a motive is printed twice: the first time
171 using exact mathematical spacing, and the second with corrections.
174 @cindex optical spacing
195 \override NoteSpacing #'stem-spacing-correction = #0.0
196 \override NoteSpacing #'same-direction-correction = #0.0
197 \override StaffSpacing #'stem-spacing-correction = #0.0
223 \override NoteSpacing #'stem-spacing-correction = #0.6
229 @cindex regular rhythms
230 @cindex regular spacing
231 @cindex spacing, regular
233 Each bar in the fragment only uses notes that are played in a
234 constant rhythm. The spacing should reflect that. Unfortunately,
235 the eye deceives us a little; not only does it notice the distance
236 between note heads, it also takes into account the distance
237 between consecutive stems. As a result, the notes of an
238 up-stem/@/down-stem combination should be put farther apart, and
239 the notes of a down-stem/@/up-stem combination should be put
240 closer together, all depending on the combined vertical positions
241 of the notes. The upper two measures are printed with this
242 correction, the lower two measures, however, form down-stem/@/up-stem
243 clumps of notes. A master engraver would adjust the spacing as needed to
246 Another example of optical spacing is the visual interplay between the
247 stems and the bar lines. When an up-stem precedes the bar line, a little
248 more space is needed to keep it from feeling crowded:
257 c''8 c'' c'' c'' c'' c'' c'' c'' \break
258 a' a' a' a' a' a' a' a'
263 \remove "Time_signature_engraver"
264 \override NoteSpacing #'stem-spacing-correction = #0.7
271 @unnumberedsubsec Ledger Lines
276 Ledger lines present a typographical challenge: they make it more
277 difficult to space musical symbols close together and they must be clear
278 enough to identify the pitch at a glance. In the example below, we see
279 that ledger lines should be thicker than normal staff lines and that an
280 expert engraver will shorten a ledger line to allow closer spacing with
281 accidentals. We have included this feature in LilyPond's engraving.
283 @multitable @columnfractions .25 .25 .25 .25
287 @image{pictures/baer-ledger,3cm}
290 @sourceimage{baer-ledger,,,png}
296 @image{pictures/lily-ledger,3cm}
299 @sourceimage{lily-ledger,,,png}
305 @unnumberedsubsec Slurs
309 @node Why work so hard?
310 @unnumberedsubsec Why work so hard?
312 Musicians are usually more absorbed with performing than with
313 studying the looks of a piece of music, so nitpicking
314 typographical details may seem academic. But it is not.
316 Sheet music is performance material: everything is done to aid the
317 musician in letting him perform better. Music often is far away from its
318 reader--it might be on a music stand. To make it clearly readable,
319 traditionally printed sheet music always uses bold symbols, on heavy
320 staff lines, and is printed on large sheets of paper. This "strong" look
321 is also present in the horizontal spacing. To minimize the number of
322 page breaks, (hand-engraved) sheet music is spaced very tightly. Yet, by
323 a careful distribution of white space, the feeling of balance is
324 retained, and a clutter of symbols is avoided. (1.8)
327 larger pieces with monotonous rhythms, spacing corrections lead to
328 subtle variations in the layout of every line, giving each one a
329 distinct visual signature. Without this signature all lines would
330 look the same, and they become like a labyrinth. A distinct visual
331 signature helps to keep musicians from losing their place on the
332 page when they look away or have a lapse in concentration.
334 Similarly, the strong visual look of bold symbols on heavy staff
335 lines stands out better when the music is far away from the
336 reader: for example, if it is on a music stand. A careful
337 distribution of white space allows music to be set very tightly
338 without crowding symbols together. The result minimizes the
339 number of page turns, which is a great advantage.
341 This is a common characteristic of typography. Layout should be
342 pretty, not only for its own sake, but especially because it helps
343 the reader in her task. For performance material like sheet
344 music, this is of double importance: musicians have a limited
345 amount of attention. The less attention they need for reading,
346 the more they can focus on playing the music. In other words,
347 better typography translates to better performances.
349 These examples demonstrate that music typography is an art that is
350 subtle and complex, and that producing it requires considerable
351 expertise, which musicians usually do not have. LilyPond is our
352 effort to bring the graphical excellence of hand-engraved music to
353 the computer age, and make it available to normal musicians. We
354 have tuned our algorithms, font-designs, and program settings to
355 produce prints that match the quality of the old editions we love
356 to see and love to play from.
359 @node Automated engraving
360 @unnumberedsec Automated engraving
362 @cindex engraving, automated
363 @cindex automated engraving
367 * Notation benchmarking::
368 * Flexible architecture::
371 @node Beauty contests
372 @unnumberedsubsec Beauty contests
374 @node Notation benchmarking
375 @unnumberedsubsec Notation benchmarking
380 @image{pictures/baer-sarabande-hires,16cm}
383 @sourceimage{baer-sarabande,,,png}
389 @image{pictures/lily14-sarabande,16cm}
392 @sourceimage{lily14-sarabande,,,png}
397 @lilypond[relative=0,staffsize=19,line-width=16\cm]
402 \mergeDifferentlyDottedOn
403 << {d8. e16 e4. d16 e} \\ {d4 a2} >>
405 bes g' f e16( f g a bes d,)
407 << {d'8. e16 e4. d16 e} \\ {<f, a>4 a2} >>
411 [LilyPond snippet above not finished]
413 [a few bars of LilyPond vs. Finale can go here]
415 @node Flexible architecture
416 @unnumberedsubsec Flexible architecture
418 How do we go about implementing typography? If craftsmen need
419 over ten years to become true masters, how could we simple hackers
420 ever write a program to take over their jobs?
422 The answer is: we cannot. Typography relies on human judgment of
423 appearance, so people cannot be replaced completely. However,
424 much of the dull work can be automated. If LilyPond solves most
425 of the common situations correctly, this will be a huge
426 improvement over existing software. The remaining cases can be
427 tuned by hand. Over the course of years, the software can be
428 refined to do more and more things automatically, so manual
429 overrides are less and less necessary.
431 When we started, we wrote the LilyPond program entirely in the C++
432 programming language; the program's functionality was set in stone
433 by the developers. That proved to be unsatisfactory for a number
438 @item When LilyPond makes mistakes, users need to override
439 formatting decisions. Therefore, the user must have access to the
440 formatting engine. Hence, rules and settings cannot be fixed by
441 us at compile-time but must be accessible for users at run-time.
443 @item Engraving is a matter of visual judgment, and therefore a
444 matter of taste. As knowledgeable as we are, users can disagree
445 with our personal decisions. Therefore, the definitions of
446 typographical style must also be accessible to the user.
448 @item Finally, we continually refine the formatting algorithms, so
449 we need a flexible approach to rules. The C++ language forces a
450 certain method of grouping rules that cannot readily be applied to
451 formatting music notation.
455 @cindex Scheme programming language
457 These problems have been addressed by integrating an interpreter
458 for the Scheme programming language and rewriting parts of
459 LilyPond in Scheme. The current formatting architecture is built
460 around the notion of graphical objects, described by Scheme
461 variables and functions. This architecture encompasses formatting
462 rules, typographical style and individual formatting decisions.
463 The user has direct access to most of these controls.
465 Scheme variables control layout decisions. For example, many
466 graphical objects have a direction variable that encodes the
467 choice between up and down (or left and right). Here you see two
468 chords, with accents and arpeggios. In the first chord, the
469 graphical objects have all directions down (or left). The second
470 chord has all directions up (right).
472 @lilypond[quote,ragged-right]
474 \override SpacingSpanner #'spacing-increment = #3
475 \override TimeSignature #'transparent = ##t
477 \stemDown <e g b>4_>-\arpeggio
478 \override Arpeggio #'direction = #RIGHT
479 \stemUp <e g b>4^>-\arpeggio
483 @cindex score formatting
484 @cindex formatting a score
485 @cindex formatting rules
488 The process of formatting a score consists of reading and writing
489 the variables of graphical objects. Some variables have a preset
490 value. For example, the thickness of many lines -- a
491 characteristic of typographical style -- is a variable with a
492 preset value. You are free to alter this value, giving your score
493 a different typographical impression.
495 @lilypond[quote,ragged-right]
498 c'4-~ c'16 as g f e16 g bes c' des'4
503 \override Beam #'beam-thickness = #0.3
504 \override Stem #'thickness = #0.5
505 \override Bar #'thickness = #3.6
506 \override Tie #'thickness = #2.2
507 \override StaffSymbol #'thickness = #3.0
508 \override Tie #'extra-offset = #'(0 . 0.3)
514 Formatting rules are also preset variables: each object has
515 variables containing procedures. These procedures perform the
516 actual formatting, and by substituting different ones, we can
517 change the appearance of objects. In the following example, the
518 rule governing which note head objects are used to produce the
519 note head symbol is changed during the music fragment.
521 @lilypond[quote,ragged-right]
522 #(set-global-staff-size 30)
524 #(define (mc-squared grob orig current)
525 (let* ((interfaces (ly:grob-interfaces grob))
526 (pos (ly:grob-property grob 'staff-position)))
527 (if (memq 'note-head-interface interfaces)
529 (ly:grob-set-property! grob 'stencil
530 (grob-interpret-markup grob
531 (make-lower-markup 0.5
535 ((-2) (make-smaller-markup (make-bold-markup "2")))
538 \new Voice \relative c' {
540 \set autoBeaming = ##f
543 \once \override NoteHead #'stencil = #note-head::brew-ez-stencil
544 \once \override NoteHead #'font-size = #-7
545 \once \override NoteHead #'font-family = #'sans
546 \once \override NoteHead #'font-series = #'bold
548 \once \override NoteHead #'style = #'cross
550 \applyOutput #'Voice #mc-squared
553 { d8[ es-( fis^^ g] fis2-) }
554 \repeat unfold 5 { \applyOutput #'Voice #mc-squared s8 }
560 @node What symbols to engrave?
561 @unnumberedsec What symbols to engrave?
568 The formatting process decides where to place symbols. However,
569 this can only be done once it is decided @emph{what} symbols
570 should be printed -- in other words, what notation to use.
572 Common music notation is a system of recording music that has
573 evolved over the past 1000 years. The form that is now in common
574 use dates from the early Renaissance. Although the basic form
575 (i.e., note heads on a 5-line staff) has not changed, the details
576 still evolve to express the innovations of contemporary notation.
577 Hence, common music notation encompasses some 500 years of music.
578 Its applications range from monophonic melodies to monstrous
579 counterpoints for a large orchestra.
581 How can we get a grip on such a seven-headed beast, and force it
582 into the confines of a computer program? Our solution is to break
583 up the problem of notation (as opposed to engraving, i.e.,
584 typography) into digestible and programmable chunks: every type of
585 symbol is handled by a separate module, a so-called plug-in. Each
586 plug-in is completely modular and independent, so each can be
587 developed and improved separately. Such plug-ins are called
588 @code{engraver}s, by analogy with craftsmen who translate musical
589 ideas to graphic symbols.
591 In the following example, we start out with a plug-in for note
592 heads, the @code{Note_heads_engraver}.
594 @lilypond[quote,ragged-right]
595 \include "engraver-example.ily"
602 \remove "Stem_engraver"
603 \remove "Phrasing_slur_engraver"
604 \remove "Slur_engraver"
605 \remove "Script_engraver"
606 \remove "Beam_engraver"
607 \remove "Auto_beam_engraver"
611 \remove "Accidental_engraver"
612 \remove "Key_engraver"
613 \remove "Clef_engraver"
614 \remove "Bar_engraver"
615 \remove "Time_signature_engraver"
616 \remove "Staff_symbol_engraver"
617 \consists "Pitch_squash_engraver"
624 Then a @code{Staff_symbol_engraver} adds the staff,
626 @lilypond[quote,ragged-right]
627 \include "engraver-example.ily"
634 \remove "Stem_engraver"
635 \remove "Phrasing_slur_engraver"
636 \remove "Slur_engraver"
637 \remove "Script_engraver"
638 \remove "Beam_engraver"
639 \remove "Auto_beam_engraver"
643 \remove "Accidental_engraver"
644 \remove "Key_engraver"
645 \remove "Clef_engraver"
646 \remove "Bar_engraver"
647 \consists "Pitch_squash_engraver"
648 \remove "Time_signature_engraver"
655 the @code{Clef_engraver} defines a reference point for the staff,
657 @lilypond[quote,ragged-right]
658 \include "engraver-example.ily"
665 \remove "Stem_engraver"
666 \remove "Phrasing_slur_engraver"
667 \remove "Slur_engraver"
668 \remove "Script_engraver"
669 \remove "Beam_engraver"
670 \remove "Auto_beam_engraver"
674 \remove "Accidental_engraver"
675 \remove "Key_engraver"
676 \remove "Bar_engraver"
677 \remove "Time_signature_engraver"
684 and the @code{Stem_engraver} adds stems.
686 @lilypond[quote,ragged-right]
687 \include "engraver-example.ily"
694 \remove "Phrasing_slur_engraver"
695 \remove "Slur_engraver"
696 \remove "Script_engraver"
697 \remove "Beam_engraver"
698 \remove "Auto_beam_engraver"
702 \remove "Accidental_engraver"
703 \remove "Key_engraver"
704 \remove "Bar_engraver"
705 \remove "Time_signature_engraver"
712 The @code{Stem_engraver} is notified of any note head coming
713 along. Every time one (or more, for a chord) note head is seen, a
714 stem object is created and connected to the note head. By adding
715 engravers for beams, slurs, accents, accidentals, bar lines, time
716 signature, and key signature, we get a complete piece of notation.
718 @lilypond[quote,ragged-right]
719 \include "engraver-example.ily"
724 @cindex engraving multiple voices
727 This system works well for monophonic music, but what about
728 polyphony? In polyphonic notation, many voices can share a staff.
730 @lilypond[quote,ragged-right]
731 \include "engraver-example.ily"
732 \new Staff << \topVoice \\ \botVoice >>
735 In this situation, the accidentals and staff are shared, but the
736 stems, slurs, beams, etc., are private to each voice. Hence,
737 engravers should be grouped. The engravers for note heads, stems,
738 slurs, etc., go into a group called @q{Voice context,} while the
739 engravers for key, accidental, bar, etc., go into a group called
740 @q{Staff context.} In the case of polyphony, a single Staff
741 context contains more than one Voice context. Similarly, multiple
742 Staff contexts can be put into a single Score context. The Score
743 context is the top level notation context.
747 Internals Reference: @rinternals{Contexts}.
750 @lilypond[quote,ragged-right]
751 \include "engraver-example.ily"
754 \new Staff << \topVoice \\ \botVoice >>
755 \new Staff << \pah \\ \hoom >>
761 @node Music representation
762 @unnumberedsec Music representation
765 @cindex recursive structures
767 Ideally, the input format for any high-level formatting system is
768 an abstract description of the content. In this case, that would
769 be the music itself. This poses a formidable problem: how can we
770 define what music really is? Instead of trying to find an answer,
771 we have reversed the question. We write a program capable of
772 producing sheet music, and adjust the format to be as lean as
773 possible. When the format can no longer be trimmed down, by
774 definition we are left with content itself. Our program serves as
775 a formal definition of a music document.
777 The syntax is also the user-interface for LilyPond, hence it is
787 to create a quarter note on middle C (C1) and an eighth note on
788 the D above middle C (D1).
796 On a microscopic scale, such syntax is easy to use. On a larger
797 scale, syntax also needs structure. How else can you enter
798 complex pieces like symphonies and operas? The structure is
799 formed by the concept of music expressions: by combining small
800 fragments of music into larger ones, more complex music can be
801 expressed. For example
803 @lilypond[quote,verbatim,fragment,relative=1]
808 Simultaneous notes can be constructed by enclosing them with
809 @code{<<} and @code{>>}:
815 @lilypond[quote,fragment,relative=1]
816 \new Voice { <<c4 d4 e>> }
820 This expression is put in sequence by enclosing it in curly braces
821 @code{@{@tie{}@dots{}@tie{}@}}:
824 @{ f4 <<c4 d4 e4>> @}
827 @lilypond[quote,relative=1,fragment]
832 The above is also an expression, and so it may be combined again
833 with another simultaneous expression (a half note) using
834 @code{<<}, @code{\\}, and @code{>>}:
837 << g2 \\ @{ f4 <<c4 d4 e4>> @} >>
840 @lilypond[quote,fragment,relative=2]
841 \new Voice { << g2 \\ { f4 <<c d e>> } >> }
844 Such recursive structures can be specified neatly and formally in
845 a context-free grammar. The parsing code is also generated from
846 this grammar. In other words, the syntax of LilyPond is clearly
847 and unambiguously defined.
849 User-interfaces and syntax are what people see and deal with most.
850 They are partly a matter of taste, and also the subject of much
851 discussion. Although discussions on taste do have their merit,
852 they are not very productive. In the larger picture of LilyPond,
853 the importance of input syntax is small: inventing neat syntax is
854 easy, while writing decent formatting code is much harder. This
855 is also illustrated by the line-counts for the respective
856 components: parsing and representation take up less than 10% of
860 @node Example applications
861 @unnumberedsec Example applications
863 @cindex simple examples
864 @cindex examples, simple
866 We have written LilyPond as an experiment of how to condense the
867 art of music engraving into a computer program. Thanks to all
868 that hard work, the program can now be used to perform useful
869 tasks. The simplest application is printing notes.
871 @lilypond[quote,relative=1]
879 By adding chord names and lyrics we obtain a lead sheet.
881 @lilypond[quote,ragged-right]
883 \chords { c2 c f2 c }
889 \addlyrics { twin -- kle twin -- kle lit -- tle star }
893 Polyphonic notation and piano music can also be printed. The
894 following example combines some more exotic constructs.
898 title = "Screech and boink"
899 subtitle = "Random complex notation"
900 composer = "Han-Wen Nienhuys"
904 \context PianoStaff <<
909 \revert Stem #'direction
911 \set subdivideBeams = ##t
923 \set followVoice = ##t
924 c'''32([ b''16 a''16 gis''16 g''32)]
926 s4 \times 2/3 { d'16[ f' g'] } as'32[ b''32 e'' d'']
928 s4 \autoBeamOff d''8.. f''32
934 \new Staff = "down" {
937 \set subdivideBeams = ##f
938 \override Stem #'french-beaming = ##t
939 \override Beam #'beam-thickness = #0.3
940 \override Stem #'thickness = #4.0
947 \override Staff.Arpeggio #'arpeggio-direction =#down
948 <cis, e, gis, b, cis>4\arpeggio
955 tempoWholesPerMinute = #(ly:make-moment 60 8)
961 \consists Horizontal_bracket_engraver
967 The fragments shown above have all been written by hand, but that
968 is not a requirement. Since the formatting engine is mostly
969 automatic, it can serve as an output means for other programs that
970 manipulate music. For example, it can also be used to convert
971 databases of musical fragments to images for use on websites and
972 multimedia presentations.
974 This manual also shows an application: the input format is text,
975 and can therefore be easily embedded in other text-based formats
976 such as @LaTeX{}, HTML, or in the case of this manual, Texinfo.
977 By means of a special program, the input fragments can be replaced
978 by music images in the resulting PDF or HTML output files. This
979 makes it easy to mix music and text in documents.
982 TODO: add extra chapter for computer aesthetics?