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}.
37 The term derives from the traditional process of music printing.
38 Just a few decades ago, sheet music was made by cutting and
39 stamping the music into a zinc or pewter plate in mirror image.
40 The plate would be inked, and the depressions caused by the cutting
41 and stamping would hold ink. An image was formed by pressing
42 paper to the plate. The stamping and cutting was done completely
43 by hand. Making a correction was cumbersome, if possible at all,
44 so the engraving had to be perfect in one go. Engraving was a
45 highly specialized skill; a craftsman had to complete around five
46 years of training before earning the title of master engraver, and
47 another five years of experience were necessary to become truly
50 Nowadays, all newly printed music is produced with computers.
51 This has obvious advantages: prints are cheaper to make, and
52 editorial work can be delivered by email. Unfortunately, the
53 pervasive use of computers has also decreased the graphical
54 quality of scores. Computer printouts have a bland, mechanical
55 look, which makes them unpleasant to play from.
58 @c introduce illustrating aspects of engraving, font...
59 The images below illustrate the difference between traditional
60 engraving and typical computer output, and the third picture shows
61 how LilyPond mimics the traditional look. The left picture shows
62 a scan of a flat symbol from an edition published in 2000. The
63 center depicts a symbol from a hand-engraved Bärenreiter edition
64 of the same music. The left scan illustrates typical flaws of
65 computer print: the staff lines are thin, the weight of the flat
66 symbol matches the light lines and it has a straight layout with
67 sharp corners. By contrast, the Bärenreiter flat has a bold,
68 almost voluptuous rounded look. Our flat symbol is designed
69 after this one, among others. It is rounded, and its weight
70 harmonizes with the thickness of our staff lines, which are also
71 much thicker than lines in the computer edition.
73 @multitable @columnfractions .125 .25 .25 .25 .125
77 @image{henle-flat-gray,,4cm}
80 @image{henle-flat-gray,,,png}
85 @image{baer-flat-gray,,4cm}
88 @image{baer-flat-gray,,,png}
93 @image{lily-flat-bw,,4cm}
96 @image{lily-flat-bw,,,png}
100 @image{lilypond/henle-flat-bw,,,,png} @image{lilypond/baer-flat-bw,,,,png}
101 @image{lilypond/lily-flat-bw,,,,png}
109 LilyPond Feta font (2003)
114 @cindex musical symbols
119 @c introduce illustrating aspects of engraving, spacing...
120 In spacing, the distribution of space should reflect the durations
121 between notes. However, many modern scores adhere to the
122 durations with mathematical precision, which leads to poor
123 results. In the next example a motive is printed twice: once
124 using exact mathematical spacing, and once with corrections. Can
125 you spot which fragment is which?
127 @cindex optical spacing
128 @c file spacing-optical.
129 @c need to include it here, because we want two images.
150 \override NoteSpacing #'stem-spacing-correction = #0.6
175 \override NoteSpacing #'stem-spacing-correction = #0.0
176 \override NoteSpacing #'same-direction-correction = #0.0
177 \override StaffSpacing #'stem-spacing-correction = #0.0
183 @cindex regular rhythms
184 @cindex regular spacing
185 @cindex spacing, regular
187 Each bar in the fragment only uses notes that are played in a
188 constant rhythm. The spacing should reflect that. Unfortunately,
189 the eye deceives us a little; not only does it notice the distance
190 between note heads, it also takes into account the distance
191 between consecutive stems. As a result, the notes of an
192 up-stem/@/down-stem combination should be put farther apart, and
193 the notes of a down-stem/@/up-stem combination should be put
194 closer together, all depending on the combined vertical positions
195 of the notes. The upper two measures are printed with this
196 correction, the lower two measures, however, form
197 down-stem/@/up-stem clumps of notes.
200 Musicians are usually more absorbed with performing than with
201 studying the looks of a piece of music, so nitpicking
202 typographical details may seem academic. But it is not. In
203 larger pieces with monotonous rhythms, spacing corrections lead to
204 subtle variations in the layout of every line, giving each one a
205 distinct visual signature. Without this signature all lines would
206 look the same, and they become like a labyrinth. A distinct visual
207 signature helps to keep musicians from losing their place on the
208 page when they look away or have a lapse in concentration.
210 Similarly, the strong visual look of bold symbols on heavy staff
211 lines stands out better when the music is far away from the
212 reader: for example, if it is on a music stand. A careful
213 distribution of white space allows music to be set very tightly
214 without crowding symbols together. The result minimizes the
215 number of page turns, which is a great advantage.
217 This is a common characteristic of typography. Layout should be
218 pretty, not only for its own sake, but especially because it helps
219 the reader in her task. For performance material like sheet
220 music, this is of double importance: musicians have a limited
221 amount of attention. The less attention they need for reading,
222 the more they can focus on playing the music. In other words,
223 better typography translates to better performances.
225 These examples demonstrate that music typography is an art that is
226 subtle and complex, and that producing it requires considerable
227 expertise, which musicians usually do not have. LilyPond is our
228 effort to bring the graphical excellence of hand-engraved music to
229 the computer age, and make it available to normal musicians. We
230 have tuned our algorithms, font-designs, and program settings to
231 produce prints that match the quality of the old editions we love
232 to see and love to play from.
235 @node Automated engraving
236 @unnumberedsec Automated engraving
238 @cindex engraving, automated
239 @cindex automated engraving
241 How do we go about implementing typography? If craftsmen need
242 over ten years to become true masters, how could we simple hackers
243 ever write a program to take over their jobs?
245 The answer is: we cannot. Typography relies on human judgment of
246 appearance, so people cannot be replaced completely. However,
247 much of the dull work can be automated. If LilyPond solves most
248 of the common situations correctly, this will be a huge
249 improvement over existing software. The remaining cases can be
250 tuned by hand. Over the course of years, the software can be
251 refined to do more and more things automatically, so manual
252 overrides are less and less necessary.
254 When we started, we wrote the LilyPond program entirely in the C++
255 programming language; the program's functionality was set in stone
256 by the developers. That proved to be unsatisfactory for a number
261 @item When LilyPond makes mistakes, users need to override
262 formatting decisions. Therefore, the user must have access to the
263 formatting engine. Hence, rules and settings cannot be fixed by
264 us at compile-time but must be accessible for users at run-time.
266 @item Engraving is a matter of visual judgment, and therefore a
267 matter of taste. As knowledgeable as we are, users can disagree
268 with our personal decisions. Therefore, the definitions of
269 typographical style must also be accessible to the user.
271 @item Finally, we continually refine the formatting algorithms, so
272 we need a flexible approach to rules. The C++ language forces a
273 certain method of grouping rules that cannot readily be applied to
274 formatting music notation.
278 @cindex Scheme programming language
280 These problems have been addressed by integrating an interpreter
281 for the Scheme programming language and rewriting parts of
282 LilyPond in Scheme. The current formatting architecture is built
283 around the notion of graphical objects, described by Scheme
284 variables and functions. This architecture encompasses formatting
285 rules, typographical style and individual formatting decisions.
286 The user has direct access to most of these controls.
288 Scheme variables control layout decisions. For example, many
289 graphical objects have a direction variable that encodes the
290 choice between up and down (or left and right). Here you see two
291 chords, with accents and arpeggios. In the first chord, the
292 graphical objects have all directions down (or left). The second
293 chord has all directions up (right).
295 @lilypond[quote,ragged-right]
297 \override SpacingSpanner #'spacing-increment = #3
298 \override TimeSignature #'transparent = ##t
300 \stemDown <e g b>4_>-\arpeggio
301 \override Arpeggio #'direction = #RIGHT
302 \stemUp <e g b>4^>-\arpeggio
306 @cindex score formatting
307 @cindex formatting a score
308 @cindex formatting rules
311 The process of formatting a score consists of reading and writing
312 the variables of graphical objects. Some variables have a preset
313 value. For example, the thickness of many lines -- a
314 characteristic of typographical style -- is a variable with a
315 preset value. You are free to alter this value, giving your score
316 a different typographical impression.
318 @lilypond[quote,ragged-right]
321 c'4-~ c'16 as g f e16 g bes c' des'4
326 \override Beam #'thickness = #0.3
327 \override Stem #'thickness = #0.5
328 \override Bar #'thickness = #3.6
329 \override Tie #'thickness = #2.2
330 \override StaffSymbol #'thickness = #3.0
331 \override Tie #'extra-offset = #'(0 . 0.3)
337 Formatting rules are also preset variables: each object has
338 variables containing procedures. These procedures perform the
339 actual formatting, and by substituting different ones, we can
340 change the appearance of objects. In the following example, the
341 rule governing which note head objects are used to produce the
342 note head symbol is changed during the music fragment.
344 @lilypond[quote,ragged-right]
345 #(set-global-staff-size 30)
347 #(define (mc-squared grob orig current)
348 (let* ((interfaces (ly:grob-interfaces grob))
349 (pos (ly:grob-property grob 'staff-position)))
350 (if (memq 'note-head-interface interfaces)
352 (ly:grob-set-property! grob 'stencil
353 (grob-interpret-markup grob
354 (make-lower-markup 0.5
358 ((-2) (make-smaller-markup (make-bold-markup "2")))
361 \new Voice \relative c' {
363 \set autoBeaming = ##f
366 \once \override NoteHead #'stencil = #ly:note-head::brew-ez-stencil
367 \once \override NoteHead #'font-size = #-7
368 \once \override NoteHead #'font-family = #'sans
369 \once \override NoteHead #'font-series = #'bold
371 \once \override NoteHead #'style = #'cross
373 \applyOutput #'Voice #mc-squared
376 { d8[ es-( fis^^ g] fis2-) }
377 \repeat unfold 5 { \applyOutput #'Voice #mc-squared s8 }
383 @node What symbols to engrave?
384 @unnumberedsec What symbols to engrave?
391 The formatting process decides where to place symbols. However,
392 this can only be done once it is decided @emph{what} symbols
393 should be printed -- in other words, what notation to use.
395 Common music notation is a system of recording music that has
396 evolved over the past 1000 years. The form that is now in common
397 use dates from the early Renaissance. Although the basic form
398 (i.e., note heads on a 5-line staff) has not changed, the details
399 still evolve to express the innovations of contemporary notation.
400 Hence, common music notation encompasses some 500 years of music.
401 Its applications range from monophonic melodies to monstrous
402 counterpoints for a large orchestra.
404 How can we get a grip on such a seven-headed beast, and force it
405 into the confines of a computer program? Our solution is to break
406 up the problem of notation (as opposed to engraving, i.e.,
407 typography) into digestible and programmable chunks: every type of
408 symbol is handled by a separate module, a so-called plug-in. Each
409 plug-in is completely modular and independent, so each can be
410 developed and improved separately. Such plug-ins are called
411 @code{engraver}s, by analogy with craftsmen who translate musical
412 ideas to graphic symbols.
414 In the following example, we start out with a plug-in for note
415 heads, the @code{Note_heads_engraver}.
417 @lilypond[quote,ragged-right]
418 \include "engraver-example.ily"
425 \remove "Stem_engraver"
426 \remove "Phrasing_slur_engraver"
427 \remove "Slur_engraver"
428 \remove "Script_engraver"
429 \remove "Beam_engraver"
430 \remove "Auto_beam_engraver"
434 \remove "Accidental_engraver"
435 \remove "Key_engraver"
436 \remove "Clef_engraver"
437 \remove "Bar_engraver"
438 \remove "Time_signature_engraver"
439 \remove "Staff_symbol_engraver"
440 \consists "Pitch_squash_engraver"
447 Then a @code{Staff_symbol_engraver} adds the staff,
449 @lilypond[quote,ragged-right]
450 \include "engraver-example.ily"
457 \remove "Stem_engraver"
458 \remove "Phrasing_slur_engraver"
459 \remove "Slur_engraver"
460 \remove "Script_engraver"
461 \remove "Beam_engraver"
462 \remove "Auto_beam_engraver"
466 \remove "Accidental_engraver"
467 \remove "Key_engraver"
468 \remove "Clef_engraver"
469 \remove "Bar_engraver"
470 \consists "Pitch_squash_engraver"
471 \remove "Time_signature_engraver"
478 the @code{Clef_engraver} defines a reference point for the staff,
480 @lilypond[quote,ragged-right]
481 \include "engraver-example.ily"
488 \remove "Stem_engraver"
489 \remove "Phrasing_slur_engraver"
490 \remove "Slur_engraver"
491 \remove "Script_engraver"
492 \remove "Beam_engraver"
493 \remove "Auto_beam_engraver"
497 \remove "Accidental_engraver"
498 \remove "Key_engraver"
499 \remove "Bar_engraver"
500 \remove "Time_signature_engraver"
507 and the @code{Stem_engraver} adds stems.
509 @lilypond[quote,ragged-right]
510 \include "engraver-example.ily"
517 \remove "Phrasing_slur_engraver"
518 \remove "Slur_engraver"
519 \remove "Script_engraver"
520 \remove "Beam_engraver"
521 \remove "Auto_beam_engraver"
525 \remove "Accidental_engraver"
526 \remove "Key_engraver"
527 \remove "Bar_engraver"
528 \remove "Time_signature_engraver"
535 The @code{Stem_engraver} is notified of any note head coming
536 along. Every time one (or more, for a chord) note head is seen, a
537 stem object is created and connected to the note head. By adding
538 engravers for beams, slurs, accents, accidentals, bar lines, time
539 signature, and key signature, we get a complete piece of notation.
541 @lilypond[quote,ragged-right]
542 \include "engraver-example.ily"
547 @cindex engraving multiple voices
550 This system works well for monophonic music, but what about
551 polyphony? In polyphonic notation, many voices can share a staff.
553 @lilypond[quote,ragged-right]
554 \include "engraver-example.ily"
555 \new Staff << \topVoice \\ \botVoice >>
558 In this situation, the accidentals and staff are shared, but the
559 stems, slurs, beams, etc., are private to each voice. Hence,
560 engravers should be grouped. The engravers for note heads, stems,
561 slurs, etc., go into a group called @q{Voice context,} while the
562 engravers for key, accidental, bar, etc., go into a group called
563 @q{Staff context.} In the case of polyphony, a single Staff
564 context contains more than one Voice context. Similarly, multiple
565 Staff contexts can be put into a single Score context. The Score
566 context is the top level notation context.
570 Internals Reference: @rinternals{Contexts}.
573 @lilypond[quote,ragged-right]
574 \include "engraver-example.ily"
577 \new Staff << \topVoice \\ \botVoice >>
578 \new Staff << \pah \\ \hoom >>
584 @node Music representation
585 @unnumberedsec Music representation
588 @cindex recursive structures
590 Ideally, the input format for any high-level formatting system is
591 an abstract description of the content. In this case, that would
592 be the music itself. This poses a formidable problem: how can we
593 define what music really is? Instead of trying to find an answer,
594 we have reversed the question. We write a program capable of
595 producing sheet music, and adjust the format to be as lean as
596 possible. When the format can no longer be trimmed down, by
597 definition we are left with content itself. Our program serves as
598 a formal definition of a music document.
600 The syntax is also the user-interface for LilyPond, hence it is
610 to create a quarter note on middle C (C1) and an eighth note on
611 the D above middle C (D1).
619 On a microscopic scale, such syntax is easy to use. On a larger
620 scale, syntax also needs structure. How else can you enter
621 complex pieces like symphonies and operas? The structure is
622 formed by the concept of music expressions: by combining small
623 fragments of music into larger ones, more complex music can be
624 expressed. For example
626 @lilypond[quote,verbatim,fragment,relative=1]
631 Simultaneous notes can be constructed by enclosing them with
632 @code{<<} and @code{>>}:
638 @lilypond[quote,fragment,relative=1]
639 \new Voice { <<c4 d4 e>> }
643 This expression is put in sequence by enclosing it in curly braces
644 @code{@{@tie{}@dots{}@tie{}@}}:
647 @{ f4 <<c4 d4 e4>> @}
650 @lilypond[quote,relative=1,fragment]
655 The above is also an expression, and so it may be combined again
656 with another simultaneous expression (a half note) using
657 @code{<<}, @code{\\}, and @code{>>}:
660 << g2 \\ @{ f4 <<c4 d4 e4>> @} >>
663 @lilypond[quote,fragment,relative=2]
664 \new Voice { << g2 \\ { f4 <<c d e>> } >> }
667 Such recursive structures can be specified neatly and formally in
668 a context-free grammar. The parsing code is also generated from
669 this grammar. In other words, the syntax of LilyPond is clearly
670 and unambiguously defined.
672 User-interfaces and syntax are what people see and deal with most.
673 They are partly a matter of taste, and also the subject of much
674 discussion. Although discussions on taste do have their merit,
675 they are not very productive. In the larger picture of LilyPond,
676 the importance of input syntax is small: inventing neat syntax is
677 easy, while writing decent formatting code is much harder. This
678 is also illustrated by the line-counts for the respective
679 components: parsing and representation take up less than 10% of
683 @node Example applications
684 @unnumberedsec Example applications
686 @cindex simple examples
687 @cindex examples, simple
689 We have written LilyPond as an experiment of how to condense the
690 art of music engraving into a computer program. Thanks to all
691 that hard work, the program can now be used to perform useful
692 tasks. The simplest application is printing notes.
694 @lilypond[quote,relative=1]
702 By adding chord names and lyrics we obtain a lead sheet.
704 @lilypond[quote,ragged-right]
706 \chords { c2 c f2 c }
712 \addlyrics { twin -- kle twin -- kle lit -- tle star }
716 Polyphonic notation and piano music can also be printed. The
717 following example combines some more exotic constructs.
721 title = "Screech and boink"
722 subtitle = "Random complex notation"
723 composer = "Han-Wen Nienhuys"
727 \context PianoStaff <<
732 \revert Stem #'direction
734 \set subdivideBeams = ##t
746 \set followVoice = ##t
747 c'''32([ b''16 a''16 gis''16 g''32)]
749 s4 \times 2/3 { d'16[ f' g'] } as'32[ b''32 e'' d'']
751 s4 \autoBeamOff d''8.. f''32
757 \new Staff = "down" {
760 \set subdivideBeams = ##f
761 \override Stem #'french-beaming = ##t
762 \override Beam #'thickness = #0.3
763 \override Stem #'thickness = #4.0
770 \override Staff.Arpeggio #'arpeggio-direction =#down
771 <cis, e, gis, b, cis>4\arpeggio
778 tempoWholesPerMinute = #(ly:make-moment 60 8)
784 \consists Horizontal_bracket_engraver
790 The fragments shown above have all been written by hand, but that
791 is not a requirement. Since the formatting engine is mostly
792 automatic, it can serve as an output means for other programs that
793 manipulate music. For example, it can also be used to convert
794 databases of musical fragments to images for use on websites and
795 multimedia presentations.
797 This manual also shows an application: the input format is text,
798 and can therefore be easily embedded in other text-based formats
799 such as @LaTeX{}, HTML, or in the case of this manual, Texinfo.
800 By means of a special program, the input fragments can be replaced
801 by music images in the resulting PDF or HTML output files. This
802 makes it easy to mix music and text in documents.
805 TODO: add extra chapter for computer aesthetics?