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 @image{pictures/hader-slaan,,,jpg}
57 @image{lilypond/pictures/hader-slaan,,,,jpg}
60 Nowadays, all newly printed music is produced with computers. This has
61 obvious advantages: prints are cheaper to make, editorial work can be
62 delivered by email, and the original data can be easily stored.
63 Unfortunately, computer-generated scores rarely match the quality of
64 hand-engraved scores. Instead, computer printouts have a bland,
65 mechanical look, which makes them unpleasant to play from.
67 From the beginning, we designed LilyPond to mimic the beauty of
68 traditional music engraving. Along the way, we have learned a great deal
69 about the work that goes into a well-engraved score. Below we describe
70 several of those aspects that we have tried to imitate in LilyPond.
81 @unnumberedsubsec Music Fonts
83 The images below illustrate the difference between traditional engraving
84 and typical computer output. The left picture shows a scan of a flat
85 symbol from a hand-engraved Bärenreiter edition, while the right picture
86 depicts a symbol from an edition of the same music published in 2000.
87 Although both images are printed in the shame shade of ink, the earlier
88 version looks darker: the staff lines are heavier, and the Bärenreiter
89 flat has a bold, almost voluptuous rounded look. The right scan, on the
90 other hand, has thinner lines and a straight layout with sharp corners.
92 @multitable @columnfractions .25 .25 .25 .25
96 @image{pictures/baer-flat-gray,,4cm}
99 @image{pictures/baer-flat-gray,,,png}
104 @image{pictures/henle-flat-gray,,4cm}
107 @image{pictures/henle-flat-gray,,,png}
112 @image{lilypond/pictures/henle-flat-bw,,,,png}
113 @image{lilypond/pictures/baer-flat-bw,,,,png}
114 @image{lilypond/pictures/lily-flat-bw,,,,png}
125 @cindex musical symbols
130 When we wanted to write a computer program to create music typography,
131 there were no musical fonts freely available that could match the
132 elegance of our favorite scores. Not let down, we created a font of
133 musical symbols, relying on nice printouts of hand-engraved music. The
134 experience helped develop a typographical taste, and it made us
135 appreciate subtle design details. Without that experience, we would not
136 have realized how ugly the fonts were that we admired at first.
138 Below is a sample of two music fonts: the upper set is the default font
139 in the Sibelius software (the @emph{Opus} font), and the lower set is
140 our own LilyPond font.
144 @image{pictures/pdf/OpusAndFeta,,,}
147 @image{pictures/OpusAndFeta,,,png}
151 @image{lilypond/pictures/OpusAndFeta,,,,png}
154 The LilyPond symbols are heavier and their weight is more consistent,
155 which makes them easier to read. Fine endings, such as the one on the
156 bottom of the quarter rest, should not end in sharp points, but rather
157 in rounded shapes. This is because sharp corners of the punching dies
158 are fragile and quickly wear out when stamping in metal. Taken together,
159 the blackness of the font must be carefully tuned together with the
160 thickness of lines, beams and slurs to give a strong yet balanced
163 Also, notice that our half-notehead is not elliptic but slightly diamond
164 shaped. The vertical stem of a flat symbol is slightly brushed, becoming
165 wider at the top. The sharp and the natural are easier to distinguish
166 from a distance because their angled lines have different slopes and the
167 vertical strokes are heavier.
169 @node Optical Spacing
170 @unnumberedsubsec Optical Spacing
172 In spacing, the distribution of space should reflect the durations
173 between notes. However, many modern scores adhere to the
174 durations with mathematical precision, which leads to poor
175 results. In the next example a motive is printed twice: the first time
176 using exact mathematical spacing, and the second with corrections.
179 @cindex optical spacing
200 \override NoteSpacing #'stem-spacing-correction = #0.0
201 \override NoteSpacing #'same-direction-correction = #0.0
202 \override StaffSpacing #'stem-spacing-correction = #0.0
228 \override NoteSpacing #'stem-spacing-correction = #0.6
234 @cindex regular rhythms
235 @cindex regular spacing
236 @cindex spacing, regular
238 Each bar in the fragment only uses notes that are played in a
239 constant rhythm. The spacing should reflect that. Unfortunately,
240 the eye deceives us a little; not only does it notice the distance
241 between note heads, it also takes into account the distance
242 between consecutive stems. As a result, the notes of an
243 up-stem/@/down-stem combination should be put farther apart, and
244 the notes of a down-stem/@/up-stem combination should be put
245 closer together, all depending on the combined vertical positions
246 of the notes. The upper two measures are printed with this
247 correction, the lower two measures, however, form down-stem/@/up-stem
248 clumps of notes. A master engraver would adjust the spacing as needed to
251 Another example of optical spacing is the visual interplay between the
252 stems and the bar lines. When an up-stem precedes the bar line, a little
253 more space is needed to keep it from feeling crowded:
262 c''8 c'' c'' c'' c'' c'' c'' c'' \break
263 a' a' a' a' a' a' a' a'
268 \remove "Time_signature_engraver"
269 \override NoteSpacing #'stem-spacing-correction = #0.7
276 @unnumberedsubsec Ledger Lines
280 @image{pictures/baer-ledger,4cm}
283 @image{pictures/baer-ledger,,,png}
287 @image{lilypond/pictures/baer-ledger,,,,png}
291 @unnumberedsubsec Slurs
293 @node Why work so hard?
294 @unnumberedsubsec Why work so hard?
296 Musicians are usually more absorbed with performing than with
297 studying the looks of a piece of music, so nitpicking
298 typographical details may seem academic. But it is not. In
299 larger pieces with monotonous rhythms, spacing corrections lead to
300 subtle variations in the layout of every line, giving each one a
301 distinct visual signature. Without this signature all lines would
302 look the same, and they become like a labyrinth. A distinct visual
303 signature helps to keep musicians from losing their place on the
304 page when they look away or have a lapse in concentration.
306 Similarly, the strong visual look of bold symbols on heavy staff
307 lines stands out better when the music is far away from the
308 reader: for example, if it is on a music stand. A careful
309 distribution of white space allows music to be set very tightly
310 without crowding symbols together. The result minimizes the
311 number of page turns, which is a great advantage.
313 This is a common characteristic of typography. Layout should be
314 pretty, not only for its own sake, but especially because it helps
315 the reader in her task. For performance material like sheet
316 music, this is of double importance: musicians have a limited
317 amount of attention. The less attention they need for reading,
318 the more they can focus on playing the music. In other words,
319 better typography translates to better performances.
321 These examples demonstrate that music typography is an art that is
322 subtle and complex, and that producing it requires considerable
323 expertise, which musicians usually do not have. LilyPond is our
324 effort to bring the graphical excellence of hand-engraved music to
325 the computer age, and make it available to normal musicians. We
326 have tuned our algorithms, font-designs, and program settings to
327 produce prints that match the quality of the old editions we love
328 to see and love to play from.
331 @node Automated engraving
332 @unnumberedsec Automated engraving
334 @cindex engraving, automated
335 @cindex automated engraving
339 * Notation benchmarking::
340 * Flexible architecture::
343 @node Beauty contests
344 @unnumberedsubsec Beauty contests
346 @node Notation benchmarking
347 @unnumberedsubsec Notation benchmarking
353 @image{pictures/baer-sarabande,16cm}
356 @image{pictures/baer-sarabande,,,png}
360 @image{lilypond/pictures/baer-sarabande,,,,png}
367 @image{pictures/lily14-sarabande,16cm}
370 @image{pictures/lily14-sarabande,,,png}
374 @image{lilypond/pictures/lily14-sarabande,,,,png}
377 LilyPond 2.13.x (can this number be generated?):
379 @lilypond[relative=0,staffsize=19,line-width=16\cm]
384 \mergeDifferentlyDottedOn
385 << {d8. e16 e4. d16 e} \\ {d4 a2} >>
387 bes g' f e16( f g a bes d,)
389 << {d'8. e16 e4. d16 e} \\ {<f, a>4 a2} >>
393 [LilyPond snippet above not finished]
395 [a few bars of LilyPond vs. Finale can go here]
397 @node Flexible architecture
398 @unnumberedsubsec Flexible architecture
400 How do we go about implementing typography? If craftsmen need
401 over ten years to become true masters, how could we simple hackers
402 ever write a program to take over their jobs?
404 The answer is: we cannot. Typography relies on human judgment of
405 appearance, so people cannot be replaced completely. However,
406 much of the dull work can be automated. If LilyPond solves most
407 of the common situations correctly, this will be a huge
408 improvement over existing software. The remaining cases can be
409 tuned by hand. Over the course of years, the software can be
410 refined to do more and more things automatically, so manual
411 overrides are less and less necessary.
413 When we started, we wrote the LilyPond program entirely in the C++
414 programming language; the program's functionality was set in stone
415 by the developers. That proved to be unsatisfactory for a number
420 @item When LilyPond makes mistakes, users need to override
421 formatting decisions. Therefore, the user must have access to the
422 formatting engine. Hence, rules and settings cannot be fixed by
423 us at compile-time but must be accessible for users at run-time.
425 @item Engraving is a matter of visual judgment, and therefore a
426 matter of taste. As knowledgeable as we are, users can disagree
427 with our personal decisions. Therefore, the definitions of
428 typographical style must also be accessible to the user.
430 @item Finally, we continually refine the formatting algorithms, so
431 we need a flexible approach to rules. The C++ language forces a
432 certain method of grouping rules that cannot readily be applied to
433 formatting music notation.
437 @cindex Scheme programming language
439 These problems have been addressed by integrating an interpreter
440 for the Scheme programming language and rewriting parts of
441 LilyPond in Scheme. The current formatting architecture is built
442 around the notion of graphical objects, described by Scheme
443 variables and functions. This architecture encompasses formatting
444 rules, typographical style and individual formatting decisions.
445 The user has direct access to most of these controls.
447 Scheme variables control layout decisions. For example, many
448 graphical objects have a direction variable that encodes the
449 choice between up and down (or left and right). Here you see two
450 chords, with accents and arpeggios. In the first chord, the
451 graphical objects have all directions down (or left). The second
452 chord has all directions up (right).
454 @lilypond[quote,ragged-right]
456 \override SpacingSpanner #'spacing-increment = #3
457 \override TimeSignature #'transparent = ##t
459 \stemDown <e g b>4_>-\arpeggio
460 \override Arpeggio #'direction = #RIGHT
461 \stemUp <e g b>4^>-\arpeggio
465 @cindex score formatting
466 @cindex formatting a score
467 @cindex formatting rules
470 The process of formatting a score consists of reading and writing
471 the variables of graphical objects. Some variables have a preset
472 value. For example, the thickness of many lines -- a
473 characteristic of typographical style -- is a variable with a
474 preset value. You are free to alter this value, giving your score
475 a different typographical impression.
477 @lilypond[quote,ragged-right]
480 c'4-~ c'16 as g f e16 g bes c' des'4
485 \override Beam #'beam-thickness = #0.3
486 \override Stem #'thickness = #0.5
487 \override Bar #'thickness = #3.6
488 \override Tie #'thickness = #2.2
489 \override StaffSymbol #'thickness = #3.0
490 \override Tie #'extra-offset = #'(0 . 0.3)
496 Formatting rules are also preset variables: each object has
497 variables containing procedures. These procedures perform the
498 actual formatting, and by substituting different ones, we can
499 change the appearance of objects. In the following example, the
500 rule governing which note head objects are used to produce the
501 note head symbol is changed during the music fragment.
503 @lilypond[quote,ragged-right]
504 #(set-global-staff-size 30)
506 #(define (mc-squared grob orig current)
507 (let* ((interfaces (ly:grob-interfaces grob))
508 (pos (ly:grob-property grob 'staff-position)))
509 (if (memq 'note-head-interface interfaces)
511 (ly:grob-set-property! grob 'stencil
512 (grob-interpret-markup grob
513 (make-lower-markup 0.5
517 ((-2) (make-smaller-markup (make-bold-markup "2")))
520 \new Voice \relative c' {
522 \set autoBeaming = ##f
525 \once \override NoteHead #'stencil = #note-head::brew-ez-stencil
526 \once \override NoteHead #'font-size = #-7
527 \once \override NoteHead #'font-family = #'sans
528 \once \override NoteHead #'font-series = #'bold
530 \once \override NoteHead #'style = #'cross
532 \applyOutput #'Voice #mc-squared
535 { d8[ es-( fis^^ g] fis2-) }
536 \repeat unfold 5 { \applyOutput #'Voice #mc-squared s8 }
542 @node What symbols to engrave?
543 @unnumberedsec What symbols to engrave?
550 The formatting process decides where to place symbols. However,
551 this can only be done once it is decided @emph{what} symbols
552 should be printed -- in other words, what notation to use.
554 Common music notation is a system of recording music that has
555 evolved over the past 1000 years. The form that is now in common
556 use dates from the early Renaissance. Although the basic form
557 (i.e., note heads on a 5-line staff) has not changed, the details
558 still evolve to express the innovations of contemporary notation.
559 Hence, common music notation encompasses some 500 years of music.
560 Its applications range from monophonic melodies to monstrous
561 counterpoints for a large orchestra.
563 How can we get a grip on such a seven-headed beast, and force it
564 into the confines of a computer program? Our solution is to break
565 up the problem of notation (as opposed to engraving, i.e.,
566 typography) into digestible and programmable chunks: every type of
567 symbol is handled by a separate module, a so-called plug-in. Each
568 plug-in is completely modular and independent, so each can be
569 developed and improved separately. Such plug-ins are called
570 @code{engraver}s, by analogy with craftsmen who translate musical
571 ideas to graphic symbols.
573 In the following example, we start out with a plug-in for note
574 heads, the @code{Note_heads_engraver}.
576 @lilypond[quote,ragged-right]
577 \include "engraver-example.ily"
584 \remove "Stem_engraver"
585 \remove "Phrasing_slur_engraver"
586 \remove "Slur_engraver"
587 \remove "Script_engraver"
588 \remove "Beam_engraver"
589 \remove "Auto_beam_engraver"
593 \remove "Accidental_engraver"
594 \remove "Key_engraver"
595 \remove "Clef_engraver"
596 \remove "Bar_engraver"
597 \remove "Time_signature_engraver"
598 \remove "Staff_symbol_engraver"
599 \consists "Pitch_squash_engraver"
606 Then a @code{Staff_symbol_engraver} adds the staff,
608 @lilypond[quote,ragged-right]
609 \include "engraver-example.ily"
616 \remove "Stem_engraver"
617 \remove "Phrasing_slur_engraver"
618 \remove "Slur_engraver"
619 \remove "Script_engraver"
620 \remove "Beam_engraver"
621 \remove "Auto_beam_engraver"
625 \remove "Accidental_engraver"
626 \remove "Key_engraver"
627 \remove "Clef_engraver"
628 \remove "Bar_engraver"
629 \consists "Pitch_squash_engraver"
630 \remove "Time_signature_engraver"
637 the @code{Clef_engraver} defines a reference point for the staff,
639 @lilypond[quote,ragged-right]
640 \include "engraver-example.ily"
647 \remove "Stem_engraver"
648 \remove "Phrasing_slur_engraver"
649 \remove "Slur_engraver"
650 \remove "Script_engraver"
651 \remove "Beam_engraver"
652 \remove "Auto_beam_engraver"
656 \remove "Accidental_engraver"
657 \remove "Key_engraver"
658 \remove "Bar_engraver"
659 \remove "Time_signature_engraver"
666 and the @code{Stem_engraver} adds stems.
668 @lilypond[quote,ragged-right]
669 \include "engraver-example.ily"
676 \remove "Phrasing_slur_engraver"
677 \remove "Slur_engraver"
678 \remove "Script_engraver"
679 \remove "Beam_engraver"
680 \remove "Auto_beam_engraver"
684 \remove "Accidental_engraver"
685 \remove "Key_engraver"
686 \remove "Bar_engraver"
687 \remove "Time_signature_engraver"
694 The @code{Stem_engraver} is notified of any note head coming
695 along. Every time one (or more, for a chord) note head is seen, a
696 stem object is created and connected to the note head. By adding
697 engravers for beams, slurs, accents, accidentals, bar lines, time
698 signature, and key signature, we get a complete piece of notation.
700 @lilypond[quote,ragged-right]
701 \include "engraver-example.ily"
706 @cindex engraving multiple voices
709 This system works well for monophonic music, but what about
710 polyphony? In polyphonic notation, many voices can share a staff.
712 @lilypond[quote,ragged-right]
713 \include "engraver-example.ily"
714 \new Staff << \topVoice \\ \botVoice >>
717 In this situation, the accidentals and staff are shared, but the
718 stems, slurs, beams, etc., are private to each voice. Hence,
719 engravers should be grouped. The engravers for note heads, stems,
720 slurs, etc., go into a group called @q{Voice context,} while the
721 engravers for key, accidental, bar, etc., go into a group called
722 @q{Staff context.} In the case of polyphony, a single Staff
723 context contains more than one Voice context. Similarly, multiple
724 Staff contexts can be put into a single Score context. The Score
725 context is the top level notation context.
729 Internals Reference: @rinternals{Contexts}.
732 @lilypond[quote,ragged-right]
733 \include "engraver-example.ily"
736 \new Staff << \topVoice \\ \botVoice >>
737 \new Staff << \pah \\ \hoom >>
743 @node Music representation
744 @unnumberedsec Music representation
747 @cindex recursive structures
749 Ideally, the input format for any high-level formatting system is
750 an abstract description of the content. In this case, that would
751 be the music itself. This poses a formidable problem: how can we
752 define what music really is? Instead of trying to find an answer,
753 we have reversed the question. We write a program capable of
754 producing sheet music, and adjust the format to be as lean as
755 possible. When the format can no longer be trimmed down, by
756 definition we are left with content itself. Our program serves as
757 a formal definition of a music document.
759 The syntax is also the user-interface for LilyPond, hence it is
769 to create a quarter note on middle C (C1) and an eighth note on
770 the D above middle C (D1).
778 On a microscopic scale, such syntax is easy to use. On a larger
779 scale, syntax also needs structure. How else can you enter
780 complex pieces like symphonies and operas? The structure is
781 formed by the concept of music expressions: by combining small
782 fragments of music into larger ones, more complex music can be
783 expressed. For example
785 @lilypond[quote,verbatim,fragment,relative=1]
790 Simultaneous notes can be constructed by enclosing them with
791 @code{<<} and @code{>>}:
797 @lilypond[quote,fragment,relative=1]
798 \new Voice { <<c4 d4 e>> }
802 This expression is put in sequence by enclosing it in curly braces
803 @code{@{@tie{}@dots{}@tie{}@}}:
806 @{ f4 <<c4 d4 e4>> @}
809 @lilypond[quote,relative=1,fragment]
814 The above is also an expression, and so it may be combined again
815 with another simultaneous expression (a half note) using
816 @code{<<}, @code{\\}, and @code{>>}:
819 << g2 \\ @{ f4 <<c4 d4 e4>> @} >>
822 @lilypond[quote,fragment,relative=2]
823 \new Voice { << g2 \\ { f4 <<c d e>> } >> }
826 Such recursive structures can be specified neatly and formally in
827 a context-free grammar. The parsing code is also generated from
828 this grammar. In other words, the syntax of LilyPond is clearly
829 and unambiguously defined.
831 User-interfaces and syntax are what people see and deal with most.
832 They are partly a matter of taste, and also the subject of much
833 discussion. Although discussions on taste do have their merit,
834 they are not very productive. In the larger picture of LilyPond,
835 the importance of input syntax is small: inventing neat syntax is
836 easy, while writing decent formatting code is much harder. This
837 is also illustrated by the line-counts for the respective
838 components: parsing and representation take up less than 10% of
842 @node Example applications
843 @unnumberedsec Example applications
845 @cindex simple examples
846 @cindex examples, simple
848 We have written LilyPond as an experiment of how to condense the
849 art of music engraving into a computer program. Thanks to all
850 that hard work, the program can now be used to perform useful
851 tasks. The simplest application is printing notes.
853 @lilypond[quote,relative=1]
861 By adding chord names and lyrics we obtain a lead sheet.
863 @lilypond[quote,ragged-right]
865 \chords { c2 c f2 c }
871 \addlyrics { twin -- kle twin -- kle lit -- tle star }
875 Polyphonic notation and piano music can also be printed. The
876 following example combines some more exotic constructs.
880 title = "Screech and boink"
881 subtitle = "Random complex notation"
882 composer = "Han-Wen Nienhuys"
886 \context PianoStaff <<
891 \revert Stem #'direction
893 \set subdivideBeams = ##t
905 \set followVoice = ##t
906 c'''32([ b''16 a''16 gis''16 g''32)]
908 s4 \times 2/3 { d'16[ f' g'] } as'32[ b''32 e'' d'']
910 s4 \autoBeamOff d''8.. f''32
916 \new Staff = "down" {
919 \set subdivideBeams = ##f
920 \override Stem #'french-beaming = ##t
921 \override Beam #'beam-thickness = #0.3
922 \override Stem #'thickness = #4.0
929 \override Staff.Arpeggio #'arpeggio-direction =#down
930 <cis, e, gis, b, cis>4\arpeggio
937 tempoWholesPerMinute = #(ly:make-moment 60 8)
943 \consists Horizontal_bracket_engraver
949 The fragments shown above have all been written by hand, but that
950 is not a requirement. Since the formatting engine is mostly
951 automatic, it can serve as an output means for other programs that
952 manipulate music. For example, it can also be used to convert
953 databases of musical fragments to images for use on websites and
954 multimedia presentations.
956 This manual also shows an application: the input format is text,
957 and can therefore be easily embedded in other text-based formats
958 such as @LaTeX{}, HTML, or in the case of this manual, Texinfo.
959 By means of a special program, the input fragments can be replaced
960 by music images in the resulting PDF or HTML output files. This
961 makes it easy to mix music and text in documents.
964 TODO: add extra chapter for computer aesthetics?