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 the difference between traditional engraving
81 and typical computer output. The left picture shows a scan of a flat
82 symbol from a hand-engraved Bärenreiter edition, while the right picture
83 depicts a symbol from an edition of the same music published in 2000.
84 Although both images are printed in the shame shade of ink, the earlier
85 version looks darker: the staff lines are heavier, and the Bärenreiter
86 flat has a bold, almost voluptuous rounded look. The right scan, on the
87 other hand, has thinner lines and a straight layout with sharp corners.
89 @multitable @columnfractions .25 .25 .25 .25
93 @image{pictures/baer-flat-gray,,4cm}
96 @image{pictures/baer-flat-gray,,,png}
101 @image{pictures/henle-flat-gray,,4cm}
104 @image{pictures/henle-flat-gray,,,png}
109 @image{lilypond/pictures/henle-flat-bw,,,,png}
110 @image{lilypond/pictures/baer-flat-bw,,,,png}
111 @image{lilypond/pictures/lily-flat-bw,,,,png}
122 @cindex musical symbols
127 When we wanted to write a computer program to create music typography,
128 there were no musical fonts freely available that could match the
129 elegance of our favorite scores. Not let down, we created a font of
130 musical symbols, relying on nice printouts of hand-engraved music. The
131 experience helped develop a typographical taste, and it made us
132 appreciate subtle design details. Without that experience, we would not
133 have realized how ugly the fonts were that we admired at first.
135 Below is a sample of two music fonts: the upper set is the default font
136 in the Sibelius software (the @emph{Opus} font), and the lower set is
137 our own LilyPond font.
141 @image{pictures/pdf/OpusAndFeta,,,}
144 @sourceimage{OpusAndFeta,,,png}
148 The LilyPond symbols are heavier and their weight is more consistent,
149 which makes them easier to read. Fine endings, such as the one on the
150 bottom of the quarter rest, should not end in sharp points, but rather
151 in rounded shapes. This is because sharp corners of the punching dies
152 are fragile and quickly wear out when stamping in metal. Taken together,
153 the blackness of the font must be carefully tuned together with the
154 thickness of lines, beams and slurs to give a strong yet balanced
157 Also, notice that our half-notehead is not elliptic but slightly diamond
158 shaped. The vertical stem of a flat symbol is slightly brushed, becoming
159 wider at the top. The sharp and the natural are easier to distinguish
160 from a distance because their angled lines have different slopes and the
161 vertical strokes are heavier.
163 @node Optical Spacing
164 @unnumberedsubsec Optical Spacing
166 In spacing, the distribution of space should reflect the durations
167 between notes. However, many modern scores adhere to the
168 durations with mathematical precision, which leads to poor
169 results. In the next example a motive is printed twice: the first time
170 using exact mathematical spacing, and the second with corrections.
173 @cindex optical spacing
194 \override NoteSpacing #'stem-spacing-correction = #0.0
195 \override NoteSpacing #'same-direction-correction = #0.0
196 \override StaffSpacing #'stem-spacing-correction = #0.0
222 \override NoteSpacing #'stem-spacing-correction = #0.6
228 @cindex regular rhythms
229 @cindex regular spacing
230 @cindex spacing, regular
232 Each bar in the fragment only uses notes that are played in a
233 constant rhythm. The spacing should reflect that. Unfortunately,
234 the eye deceives us a little; not only does it notice the distance
235 between note heads, it also takes into account the distance
236 between consecutive stems. As a result, the notes of an
237 up-stem/@/down-stem combination should be put farther apart, and
238 the notes of a down-stem/@/up-stem combination should be put
239 closer together, all depending on the combined vertical positions
240 of the notes. The upper two measures are printed with this
241 correction, the lower two measures, however, form down-stem/@/up-stem
242 clumps of notes. A master engraver would adjust the spacing as needed to
245 Another example of optical spacing is the visual interplay between the
246 stems and the bar lines. When an up-stem precedes the bar line, a little
247 more space is needed to keep it from feeling crowded:
256 c''8 c'' c'' c'' c'' c'' c'' c'' \break
257 a' a' a' a' a' a' a' a'
262 \remove "Time_signature_engraver"
263 \override NoteSpacing #'stem-spacing-correction = #0.7
270 @unnumberedsubsec Ledger Lines
274 @image{pictures/baer-ledger,4cm}
277 @image{pictures/baer-ledger,,,png}
281 @image{lilypond/pictures/baer-ledger,,,,png}
285 @unnumberedsubsec Slurs
287 @node Why work so hard?
288 @unnumberedsubsec Why work so hard?
290 Musicians are usually more absorbed with performing than with
291 studying the looks of a piece of music, so nitpicking
292 typographical details may seem academic. But it is not. In
293 larger pieces with monotonous rhythms, spacing corrections lead to
294 subtle variations in the layout of every line, giving each one a
295 distinct visual signature. Without this signature all lines would
296 look the same, and they become like a labyrinth. A distinct visual
297 signature helps to keep musicians from losing their place on the
298 page when they look away or have a lapse in concentration.
300 Similarly, the strong visual look of bold symbols on heavy staff
301 lines stands out better when the music is far away from the
302 reader: for example, if it is on a music stand. A careful
303 distribution of white space allows music to be set very tightly
304 without crowding symbols together. The result minimizes the
305 number of page turns, which is a great advantage.
307 This is a common characteristic of typography. Layout should be
308 pretty, not only for its own sake, but especially because it helps
309 the reader in her task. For performance material like sheet
310 music, this is of double importance: musicians have a limited
311 amount of attention. The less attention they need for reading,
312 the more they can focus on playing the music. In other words,
313 better typography translates to better performances.
315 These examples demonstrate that music typography is an art that is
316 subtle and complex, and that producing it requires considerable
317 expertise, which musicians usually do not have. LilyPond is our
318 effort to bring the graphical excellence of hand-engraved music to
319 the computer age, and make it available to normal musicians. We
320 have tuned our algorithms, font-designs, and program settings to
321 produce prints that match the quality of the old editions we love
322 to see and love to play from.
325 @node Automated engraving
326 @unnumberedsec Automated engraving
328 @cindex engraving, automated
329 @cindex automated engraving
333 * Notation benchmarking::
334 * Flexible architecture::
337 @node Beauty contests
338 @unnumberedsubsec Beauty contests
340 @node Notation benchmarking
341 @unnumberedsubsec Notation benchmarking
347 @image{pictures/baer-sarabande,16cm}
350 @image{pictures/baer-sarabande,,,png}
354 @image{lilypond/pictures/baer-sarabande,,,,png}
361 @image{pictures/lily14-sarabande,16cm}
364 @image{pictures/lily14-sarabande,,,png}
368 @image{lilypond/pictures/lily14-sarabande,,,,png}
373 @lilypond[relative=0,staffsize=19,line-width=16\cm]
378 \mergeDifferentlyDottedOn
379 << {d8. e16 e4. d16 e} \\ {d4 a2} >>
381 bes g' f e16( f g a bes d,)
383 << {d'8. e16 e4. d16 e} \\ {<f, a>4 a2} >>
387 [LilyPond snippet above not finished]
389 [a few bars of LilyPond vs. Finale can go here]
391 @node Flexible architecture
392 @unnumberedsubsec Flexible architecture
394 How do we go about implementing typography? If craftsmen need
395 over ten years to become true masters, how could we simple hackers
396 ever write a program to take over their jobs?
398 The answer is: we cannot. Typography relies on human judgment of
399 appearance, so people cannot be replaced completely. However,
400 much of the dull work can be automated. If LilyPond solves most
401 of the common situations correctly, this will be a huge
402 improvement over existing software. The remaining cases can be
403 tuned by hand. Over the course of years, the software can be
404 refined to do more and more things automatically, so manual
405 overrides are less and less necessary.
407 When we started, we wrote the LilyPond program entirely in the C++
408 programming language; the program's functionality was set in stone
409 by the developers. That proved to be unsatisfactory for a number
414 @item When LilyPond makes mistakes, users need to override
415 formatting decisions. Therefore, the user must have access to the
416 formatting engine. Hence, rules and settings cannot be fixed by
417 us at compile-time but must be accessible for users at run-time.
419 @item Engraving is a matter of visual judgment, and therefore a
420 matter of taste. As knowledgeable as we are, users can disagree
421 with our personal decisions. Therefore, the definitions of
422 typographical style must also be accessible to the user.
424 @item Finally, we continually refine the formatting algorithms, so
425 we need a flexible approach to rules. The C++ language forces a
426 certain method of grouping rules that cannot readily be applied to
427 formatting music notation.
431 @cindex Scheme programming language
433 These problems have been addressed by integrating an interpreter
434 for the Scheme programming language and rewriting parts of
435 LilyPond in Scheme. The current formatting architecture is built
436 around the notion of graphical objects, described by Scheme
437 variables and functions. This architecture encompasses formatting
438 rules, typographical style and individual formatting decisions.
439 The user has direct access to most of these controls.
441 Scheme variables control layout decisions. For example, many
442 graphical objects have a direction variable that encodes the
443 choice between up and down (or left and right). Here you see two
444 chords, with accents and arpeggios. In the first chord, the
445 graphical objects have all directions down (or left). The second
446 chord has all directions up (right).
448 @lilypond[quote,ragged-right]
450 \override SpacingSpanner #'spacing-increment = #3
451 \override TimeSignature #'transparent = ##t
453 \stemDown <e g b>4_>-\arpeggio
454 \override Arpeggio #'direction = #RIGHT
455 \stemUp <e g b>4^>-\arpeggio
459 @cindex score formatting
460 @cindex formatting a score
461 @cindex formatting rules
464 The process of formatting a score consists of reading and writing
465 the variables of graphical objects. Some variables have a preset
466 value. For example, the thickness of many lines -- a
467 characteristic of typographical style -- is a variable with a
468 preset value. You are free to alter this value, giving your score
469 a different typographical impression.
471 @lilypond[quote,ragged-right]
474 c'4-~ c'16 as g f e16 g bes c' des'4
479 \override Beam #'beam-thickness = #0.3
480 \override Stem #'thickness = #0.5
481 \override Bar #'thickness = #3.6
482 \override Tie #'thickness = #2.2
483 \override StaffSymbol #'thickness = #3.0
484 \override Tie #'extra-offset = #'(0 . 0.3)
490 Formatting rules are also preset variables: each object has
491 variables containing procedures. These procedures perform the
492 actual formatting, and by substituting different ones, we can
493 change the appearance of objects. In the following example, the
494 rule governing which note head objects are used to produce the
495 note head symbol is changed during the music fragment.
497 @lilypond[quote,ragged-right]
498 #(set-global-staff-size 30)
500 #(define (mc-squared grob orig current)
501 (let* ((interfaces (ly:grob-interfaces grob))
502 (pos (ly:grob-property grob 'staff-position)))
503 (if (memq 'note-head-interface interfaces)
505 (ly:grob-set-property! grob 'stencil
506 (grob-interpret-markup grob
507 (make-lower-markup 0.5
511 ((-2) (make-smaller-markup (make-bold-markup "2")))
514 \new Voice \relative c' {
516 \set autoBeaming = ##f
519 \once \override NoteHead #'stencil = #note-head::brew-ez-stencil
520 \once \override NoteHead #'font-size = #-7
521 \once \override NoteHead #'font-family = #'sans
522 \once \override NoteHead #'font-series = #'bold
524 \once \override NoteHead #'style = #'cross
526 \applyOutput #'Voice #mc-squared
529 { d8[ es-( fis^^ g] fis2-) }
530 \repeat unfold 5 { \applyOutput #'Voice #mc-squared s8 }
536 @node What symbols to engrave?
537 @unnumberedsec What symbols to engrave?
544 The formatting process decides where to place symbols. However,
545 this can only be done once it is decided @emph{what} symbols
546 should be printed -- in other words, what notation to use.
548 Common music notation is a system of recording music that has
549 evolved over the past 1000 years. The form that is now in common
550 use dates from the early Renaissance. Although the basic form
551 (i.e., note heads on a 5-line staff) has not changed, the details
552 still evolve to express the innovations of contemporary notation.
553 Hence, common music notation encompasses some 500 years of music.
554 Its applications range from monophonic melodies to monstrous
555 counterpoints for a large orchestra.
557 How can we get a grip on such a seven-headed beast, and force it
558 into the confines of a computer program? Our solution is to break
559 up the problem of notation (as opposed to engraving, i.e.,
560 typography) into digestible and programmable chunks: every type of
561 symbol is handled by a separate module, a so-called plug-in. Each
562 plug-in is completely modular and independent, so each can be
563 developed and improved separately. Such plug-ins are called
564 @code{engraver}s, by analogy with craftsmen who translate musical
565 ideas to graphic symbols.
567 In the following example, we start out with a plug-in for note
568 heads, the @code{Note_heads_engraver}.
570 @lilypond[quote,ragged-right]
571 \include "engraver-example.ily"
578 \remove "Stem_engraver"
579 \remove "Phrasing_slur_engraver"
580 \remove "Slur_engraver"
581 \remove "Script_engraver"
582 \remove "Beam_engraver"
583 \remove "Auto_beam_engraver"
587 \remove "Accidental_engraver"
588 \remove "Key_engraver"
589 \remove "Clef_engraver"
590 \remove "Bar_engraver"
591 \remove "Time_signature_engraver"
592 \remove "Staff_symbol_engraver"
593 \consists "Pitch_squash_engraver"
600 Then a @code{Staff_symbol_engraver} adds the staff,
602 @lilypond[quote,ragged-right]
603 \include "engraver-example.ily"
610 \remove "Stem_engraver"
611 \remove "Phrasing_slur_engraver"
612 \remove "Slur_engraver"
613 \remove "Script_engraver"
614 \remove "Beam_engraver"
615 \remove "Auto_beam_engraver"
619 \remove "Accidental_engraver"
620 \remove "Key_engraver"
621 \remove "Clef_engraver"
622 \remove "Bar_engraver"
623 \consists "Pitch_squash_engraver"
624 \remove "Time_signature_engraver"
631 the @code{Clef_engraver} defines a reference point for the staff,
633 @lilypond[quote,ragged-right]
634 \include "engraver-example.ily"
641 \remove "Stem_engraver"
642 \remove "Phrasing_slur_engraver"
643 \remove "Slur_engraver"
644 \remove "Script_engraver"
645 \remove "Beam_engraver"
646 \remove "Auto_beam_engraver"
650 \remove "Accidental_engraver"
651 \remove "Key_engraver"
652 \remove "Bar_engraver"
653 \remove "Time_signature_engraver"
660 and the @code{Stem_engraver} adds stems.
662 @lilypond[quote,ragged-right]
663 \include "engraver-example.ily"
670 \remove "Phrasing_slur_engraver"
671 \remove "Slur_engraver"
672 \remove "Script_engraver"
673 \remove "Beam_engraver"
674 \remove "Auto_beam_engraver"
678 \remove "Accidental_engraver"
679 \remove "Key_engraver"
680 \remove "Bar_engraver"
681 \remove "Time_signature_engraver"
688 The @code{Stem_engraver} is notified of any note head coming
689 along. Every time one (or more, for a chord) note head is seen, a
690 stem object is created and connected to the note head. By adding
691 engravers for beams, slurs, accents, accidentals, bar lines, time
692 signature, and key signature, we get a complete piece of notation.
694 @lilypond[quote,ragged-right]
695 \include "engraver-example.ily"
700 @cindex engraving multiple voices
703 This system works well for monophonic music, but what about
704 polyphony? In polyphonic notation, many voices can share a staff.
706 @lilypond[quote,ragged-right]
707 \include "engraver-example.ily"
708 \new Staff << \topVoice \\ \botVoice >>
711 In this situation, the accidentals and staff are shared, but the
712 stems, slurs, beams, etc., are private to each voice. Hence,
713 engravers should be grouped. The engravers for note heads, stems,
714 slurs, etc., go into a group called @q{Voice context,} while the
715 engravers for key, accidental, bar, etc., go into a group called
716 @q{Staff context.} In the case of polyphony, a single Staff
717 context contains more than one Voice context. Similarly, multiple
718 Staff contexts can be put into a single Score context. The Score
719 context is the top level notation context.
723 Internals Reference: @rinternals{Contexts}.
726 @lilypond[quote,ragged-right]
727 \include "engraver-example.ily"
730 \new Staff << \topVoice \\ \botVoice >>
731 \new Staff << \pah \\ \hoom >>
737 @node Music representation
738 @unnumberedsec Music representation
741 @cindex recursive structures
743 Ideally, the input format for any high-level formatting system is
744 an abstract description of the content. In this case, that would
745 be the music itself. This poses a formidable problem: how can we
746 define what music really is? Instead of trying to find an answer,
747 we have reversed the question. We write a program capable of
748 producing sheet music, and adjust the format to be as lean as
749 possible. When the format can no longer be trimmed down, by
750 definition we are left with content itself. Our program serves as
751 a formal definition of a music document.
753 The syntax is also the user-interface for LilyPond, hence it is
763 to create a quarter note on middle C (C1) and an eighth note on
764 the D above middle C (D1).
772 On a microscopic scale, such syntax is easy to use. On a larger
773 scale, syntax also needs structure. How else can you enter
774 complex pieces like symphonies and operas? The structure is
775 formed by the concept of music expressions: by combining small
776 fragments of music into larger ones, more complex music can be
777 expressed. For example
779 @lilypond[quote,verbatim,fragment,relative=1]
784 Simultaneous notes can be constructed by enclosing them with
785 @code{<<} and @code{>>}:
791 @lilypond[quote,fragment,relative=1]
792 \new Voice { <<c4 d4 e>> }
796 This expression is put in sequence by enclosing it in curly braces
797 @code{@{@tie{}@dots{}@tie{}@}}:
800 @{ f4 <<c4 d4 e4>> @}
803 @lilypond[quote,relative=1,fragment]
808 The above is also an expression, and so it may be combined again
809 with another simultaneous expression (a half note) using
810 @code{<<}, @code{\\}, and @code{>>}:
813 << g2 \\ @{ f4 <<c4 d4 e4>> @} >>
816 @lilypond[quote,fragment,relative=2]
817 \new Voice { << g2 \\ { f4 <<c d e>> } >> }
820 Such recursive structures can be specified neatly and formally in
821 a context-free grammar. The parsing code is also generated from
822 this grammar. In other words, the syntax of LilyPond is clearly
823 and unambiguously defined.
825 User-interfaces and syntax are what people see and deal with most.
826 They are partly a matter of taste, and also the subject of much
827 discussion. Although discussions on taste do have their merit,
828 they are not very productive. In the larger picture of LilyPond,
829 the importance of input syntax is small: inventing neat syntax is
830 easy, while writing decent formatting code is much harder. This
831 is also illustrated by the line-counts for the respective
832 components: parsing and representation take up less than 10% of
836 @node Example applications
837 @unnumberedsec Example applications
839 @cindex simple examples
840 @cindex examples, simple
842 We have written LilyPond as an experiment of how to condense the
843 art of music engraving into a computer program. Thanks to all
844 that hard work, the program can now be used to perform useful
845 tasks. The simplest application is printing notes.
847 @lilypond[quote,relative=1]
855 By adding chord names and lyrics we obtain a lead sheet.
857 @lilypond[quote,ragged-right]
859 \chords { c2 c f2 c }
865 \addlyrics { twin -- kle twin -- kle lit -- tle star }
869 Polyphonic notation and piano music can also be printed. The
870 following example combines some more exotic constructs.
874 title = "Screech and boink"
875 subtitle = "Random complex notation"
876 composer = "Han-Wen Nienhuys"
880 \context PianoStaff <<
885 \revert Stem #'direction
887 \set subdivideBeams = ##t
899 \set followVoice = ##t
900 c'''32([ b''16 a''16 gis''16 g''32)]
902 s4 \times 2/3 { d'16[ f' g'] } as'32[ b''32 e'' d'']
904 s4 \autoBeamOff d''8.. f''32
910 \new Staff = "down" {
913 \set subdivideBeams = ##f
914 \override Stem #'french-beaming = ##t
915 \override Beam #'beam-thickness = #0.3
916 \override Stem #'thickness = #4.0
923 \override Staff.Arpeggio #'arpeggio-direction =#down
924 <cis, e, gis, b, cis>4\arpeggio
931 tempoWholesPerMinute = #(ly:make-moment 60 8)
937 \consists Horizontal_bracket_engraver
943 The fragments shown above have all been written by hand, but that
944 is not a requirement. Since the formatting engine is mostly
945 automatic, it can serve as an output means for other programs that
946 manipulate music. For example, it can also be used to convert
947 databases of musical fragments to images for use on websites and
948 multimedia presentations.
950 This manual also shows an application: the input format is text,
951 and can therefore be easily embedded in other text-based formats
952 such as @LaTeX{}, HTML, or in the case of this manual, Texinfo.
953 By means of a special program, the input fragments can be replaced
954 by music images in the resulting PDF or HTML output files. This
955 makes it easy to mix music and text in documents.
958 TODO: add extra chapter for computer aesthetics?