1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @c This file is part of lilypond.tely
10 * Automated engraving::
11 * What symbols to engrave?::
12 * Music representation::
13 * Example applications::
21 The art of music typography is called @emph{(plate) engraving}. The
22 term derives from the traditional process of music printing. Just a
23 few decades ago, sheet music was made by cutting and stamping the
24 music into a zinc or pewter plate in mirror image. The plate would be
25 inked, the depressions caused by the cutting and stamping would hold
26 ink. An image was formed by pressing paper to the plate. The
27 stamping and cutting was completely done by hand. Making a correction
28 was cumbersome, if possible at all, so the engraving had to be perfect
29 in one go. Engraving was a highly specialized skill; a craftsman had
30 to complete around five years of training before earning the title of
31 master engraver, and another five years of experience were
32 necessary to become truly skilled.
34 Nowadays, all newly printed music is produced with computers. This
35 has obvious advantages; prints are cheaper to make, and editorial work
36 can be delivered by email. Unfortunately, the pervasive use of
37 computers has also decreased the graphical quality of scores.
38 Computer printouts have a bland, mechanical look, which makes them
39 unpleasant to play from.
42 @c introduce illustrating aspects of engraving, font...
43 The images below illustrate the difference between traditional
44 engraving and typical computer output, and the third picture shows how
45 LilyPond mimics the traditional look. The left picture shows a scan
46 of a flat symbol from an edition published in 2000. The center
47 depicts a symbol from a hand-engraved B@"{a}renreiter edition of the
48 same music. The left scan illustrates typical flaws of computer
49 print: the staff lines are thin, the weight of the flat symbol matches
50 the light lines and it has a straight layout with sharp corners. By
51 contrast, the B@"{a}renreiter flat has a bold, almost voluptuous
52 rounded look. Our flat symbol is designed after, among others, this
53 one. It is rounded, and its weight harmonizes with the thickness of
54 our staff lines, which are also much thicker than lines in the
57 @multitable @columnfractions .05 .3 .3 .3 .05
61 @image{henle-flat-gray,,8cm}
64 @image{henle-flat-gray,,,png}
69 @image{baer-flat-gray,,8.4cm}
72 @image{baer-flat-gray,,,png}
77 @image{lily-flat-bw,,8cm}
80 @image{lily-flat-bw,,,png}
84 @c workaround for makeinfo-4.6: line breaks and multi-column cookies
85 @image{henle-flat-bw,,,png} @image{baer-flat-bw,,,png}
86 @image{lily-flat-bw,,,png}
92 B@"{a}renreiter (1950)
94 LilyPond Feta font (2003)
99 @cindex musical symbols
104 @c introduce illustrating aspects of engraving, spacing...
105 In spacing, the distribution of space should reflect the durations
106 between notes. However, many modern scores adhere to the durations
107 with mathematical precision, which leads to poor results. In the
108 next example a motive is printed twice. It is printed once using
109 exact mathematical spacing, and once with corrections. Can you
110 spot which fragment is which?
112 @cindex optical spacing
113 @c file spacing-optical.
114 @c need to include it here, because we want two images.
135 \override NoteSpacing #'stem-spacing-correction = #0.6
160 \override NoteSpacing #'stem-spacing-correction = #0.0
161 \override NoteSpacing #'same-direction-correction = #0.0
162 \override StaffSpacing #'stem-spacing-correction = #0.0
168 @cindex regular rhythms
169 @cindex regular spacing
171 The fragment only uses quarter notes: notes that are played in a
172 constant rhythm. The spacing should reflect that. Unfortunately, the
173 eye deceives us a little; not only does it notice the distance between
174 note heads, it also takes into account the distance between
175 consecutive stems. As a result, the notes of an up-stem/@/down-stem
176 combination should be put farther apart, and the notes of a
178 combination should be put closer together, all depending on the
179 combined vertical positions of the notes. The first two measures are
180 printed with this correction, the last two measures without. The notes
181 in the last two measures form down-stem/@/up-stem clumps of notes.
185 Musicians are usually more absorbed with performing than with studying
186 the looks of a piece of music, so nitpicking about typographical details
187 may seem academical. But it is not. In larger pieces with monotonous
188 rhythms, spacing corrections lead to subtle variations in the layout
189 of every line, giving each one a distinct visual signature. Without
190 this signature all lines would look the same, and they become like a
191 labyrinth. If a musician looks away once or has a lapse in
192 concentration, the lines might lose their place on the page.
194 Similarly, the strong visual look of bold symbols on heavy staff lines
195 stands out better when the music is far away from the reader, for example,
196 if it is on a music stand. A careful distribution of white space allows
197 music to be set very tightly without cluttering symbols together. The
198 result minimizes the number of page turns, which is a great advantage.
200 This is a common characteristic of typography. Layout should be
201 pretty, not only for its own sake, but especially because it helps the
202 reader in her task. For performance material like sheet music, this is
203 of double importance: musicians have a limited amount of attention. The
204 less attention they need for reading, the more they can focus on
205 playing the music. In other words, better typography translates to better
208 These examples demonstrate that music typography is an art that is
209 subtle and complex, and that producing it requires considerable
210 expertise, which musicians usually do not have. LilyPond is our
211 effort to bring the graphical excellence of hand-engraved music to the
212 computer age, and make it available to normal musicians. We have
213 tuned our algorithms, font-designs, and program settings to produce
214 prints that match the quality of the old editions we love to see and
220 @node Automated engraving
221 @section Automated engraving
223 How do we go about implementing typography? If craftsmen need over
224 ten years to become true masters, how could we simple hackers ever
225 write a program to take over their jobs?
227 The answer is: we cannot. Typography relies on human judgment of
228 appearance, so people cannot be replaced completely. However, much of
229 the dull work can be automated. If LilyPond solves most of the common
230 situations correctly, this will be a huge improvement over existing
231 software. The remaining cases can be tuned by hand. Over the course
232 of years, the software can be refined to do more and more things
233 automatically, so manual overrides are less and less necessary.
235 When we started, we wrote the LilyPond program entirely in the C++
236 programming language; the program's functionality was set in stone by
237 the developers. That proved to be unsatisfactory for a number of
241 @item When LilyPond makes mistakes,
242 users need to override formatting decisions. Therefore, the user must
243 have access to the formatting engine. Hence, rules and settings cannot
244 be fixed by us at compile-time but must be accessible for users at
247 @item Engraving is a matter of visual judgment, and therefore a matter of
248 taste. As knowledgeable as we are, users can disagree with our
249 personal decisions. Therefore, the definitions of typographical style
250 must also be accessible to the user.
252 @item Finally, we continually refine the formatting algorithms, so we
253 need a flexible approach to rules. The C++ language forces a certain
254 method of grouping rules that do not match well with how music
258 These problems have been addressed by integrating an interpreter for
259 the Scheme programming language and rewriting parts of LilyPond in
260 Scheme. The current formatting architecture is built around the
261 notion of graphical objects, described by Scheme variables and
262 functions. This architecture encompasses formatting rules,
263 typographical style and individual formatting decisions. The user has
264 direct access to most of these controls.
266 Scheme variables control layout decisions. For example, many
267 graphical objects have a direction variable that encodes the choice
268 between up and down (or left and right). Here you see two chords,
269 with accents and arpeggios. In the first chord, the graphical objects
270 have all directions down (or left). The second chord has all
271 directions up (right).
273 @lilypond[quote,ragged-right]
275 \override SpacingSpanner #'spacing-increment = #3
276 \override TimeSignature #'transparent = ##t
278 \stemDown <e g b>4_>-\arpeggio
279 \override Arpeggio #'direction = #RIGHT
280 \stemUp <e g b>4^>-\arpeggio
285 The process of formatting a score consists of reading and writing the
286 variables of graphical objects. Some variables have a preset value. For
287 example, the thickness of many lines -- a characteristic of typographical
288 style -- is a variable with a preset value. You are free to alter this
289 value, giving your score a different typographical impression.
291 @lilypond[quote,ragged-right]
294 c'4-~ c'16 as g f e16 g bes c' des'4
299 \override Beam #'thickness = #0.3
300 \override Stem #'thickness = #0.5
301 \override Bar #'thickness = #3.6
302 \override Tie #'thickness = #2.2
303 \override StaffSymbol #'thickness = #3.0
304 \override Tie #'extra-offset = #'(0 . 0.3)
310 Formatting rules are also preset variables: each object has variables
311 containing procedures. These procedures perform the actual
312 formatting, and by substituting different ones, we can change the
313 appearance of objects. In the following example, the rule which note
314 head objects are used to produce their symbol is changed during the music
317 @lilypond[quote,ragged-right]
318 #(define (mc-squared grob orig current)
319 (let ((interfaces (ly:grob-property grob 'interfaces))
320 (pos (ly:grob-property grob 'staff-position)))
321 (if (and (memq 'note-head-interface interfaces)
322 (memq pos '(-2 -3 -5)))
324 (ly:grob-set-property! grob 'stencil ly:text-interface::print)
325 (ly:grob-set-property! grob 'font-family 'roman)
326 (ly:grob-set-property!
331 ((-5) (make-simple-markup "m"))
332 ((-3) (make-simple-markup "c "))
333 ((-2) (make-smaller-markup (make-bold-markup "2")))
334 (else (make-simple-markup "bla")))))))))
336 \new Voice \relative c' {
338 \set autoBeaming = ##f
341 \once \override NoteHead #'stencil = #ly:note-head::brew-ez-stencil
343 \once \override NoteHead #'style = #'cross
345 \applyOutput #'Voice #mc-squared
348 { d8[ es-( fis^^ g] fis2-) }
349 \repeat unfold 5 { \applyOutput #'Voice #mc-squared s8 }
356 @node What symbols to engrave?
357 @section What symbols to engrave?
362 The formatting process decides where to place
363 symbols. However, this can only be done once it is decided @emph{what}
364 symbols should be printed, in other words what notation to use.
366 Common music notation is a system of recording music that has evolved
367 over the past 1000 years. The form that is now in common use dates
368 from the early renaissance. Although the basic form (i.e., note heads on a
369 5-line staff) has not changed, the details still evolve to express the
370 innovations of contemporary notation. Hence, it encompasses some 500
371 years of music. Its applications range from monophonic melodies to
372 monstrous counterpoints for large orchestras.
374 How can we get a grip on such a many-headed beast, and force it into
375 the confines of a computer program? Our solution is to break up the
376 problem of notation (as opposed to engraving, i.e., typography) into
377 digestible and programmable chunks: every type of symbol is handled by
378 a separate module, a so-called plug-in. Each plug-in is completely
379 modular and independent, so each can be developed and improved
380 separately. Such plug-ins are called @code{engraver}s, by analogy with
381 craftsmen who translate musical ideas to graphic symbols.
383 In the following example, we see how we start out with a plug-in for
384 note heads, the @code{Note_heads_engraver}.
386 @lilypond[quote,ragged-right]
387 \include "engraver-example.ily"
394 \remove "Stem_engraver"
395 \remove "Phrasing_slur_engraver"
396 \remove "Slur_engraver"
397 \remove "Script_engraver"
398 \remove "Beam_engraver"
399 \remove "Auto_beam_engraver"
403 \remove "Accidental_engraver"
404 \remove "Key_engraver"
405 \remove "Clef_engraver"
406 \remove "Bar_engraver"
407 \remove "Time_signature_engraver"
408 \remove "Staff_symbol_engraver"
409 \consists "Pitch_squash_engraver"
416 Then a @code{Staff_symbol_engraver} adds the staff
418 @lilypond[quote,ragged-right]
419 \include "engraver-example.ily"
426 \remove "Stem_engraver"
427 \remove "Phrasing_slur_engraver"
428 \remove "Slur_engraver"
429 \remove "Script_engraver"
430 \remove "Beam_engraver"
431 \remove "Auto_beam_engraver"
435 \remove "Accidental_engraver"
436 \remove "Key_engraver"
437 \remove "Clef_engraver"
438 \remove "Bar_engraver"
439 \consists "Pitch_squash_engraver"
440 \remove "Time_signature_engraver"
447 the @code{Clef_engraver} defines a reference point for 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 "Bar_engraver"
469 \remove "Time_signature_engraver"
476 and the @code{Stem_engraver} adds stems.
478 @lilypond[quote,ragged-right]
479 \include "engraver-example.ily"
486 \remove "Phrasing_slur_engraver"
487 \remove "Slur_engraver"
488 \remove "Script_engraver"
489 \remove "Beam_engraver"
490 \remove "Auto_beam_engraver"
494 \remove "Accidental_engraver"
495 \remove "Key_engraver"
496 \remove "Bar_engraver"
497 \remove "Time_signature_engraver"
503 The @code{Stem_engraver} is notified of any note head coming along.
504 Every time one (or more, for a chord) note head is seen, a stem
505 object is created and connected to the note head. By adding
506 engravers for beams, slurs, accents, accidentals, bar lines,
507 time signature, and key signature, we get a complete piece of
510 @lilypond[quote,ragged-right]
511 \include "engraver-example.ily"
515 This system works well for monophonic music, but what about
516 polyphony? In polyphonic notation, many voices can share a staff.
518 @lilypond[quote,ragged-right]
519 \include "engraver-example.ily"
520 \new Staff << \topVoice \\ \botVoice >>
523 In this situation, the accidentals and staff are shared, but the stems,
524 slurs, beams, etc., are private to each voice. Hence, engravers should
525 be grouped. The engravers for note heads, stems, slurs, etc., go into a
526 group called `Voice context,' while the engravers for key, accidental,
527 bar, etc., go into a group called `Staff context.' In the case of
528 polyphony, a single Staff context contains more than one Voice context.
529 Similarly, multiple Staff contexts can be put into a single Score
530 context. The Score context is the top level notation context.
534 Program reference: @internalsref{Contexts}.
536 @lilypond[quote,ragged-right]
537 \include "engraver-example.ily"
540 \new Staff << \topVoice \\ \botVoice >>
541 \new Staff << \pah \\ \hoom >>
546 @node Music representation
547 @section Music representation
549 Ideally, the input format for any high-level formatting system is an
550 abstract description of the content. In this case, that would be the
551 music itself. This poses a formidable problem: how can we define what
552 music really is? Instead of trying to find an answer, we have reversed
553 the question. We write a program capable of producing sheet music,
554 and adjust the format to be as lean as possible. When the format can
555 no longer be trimmed down, by definition we are left with content
556 itself. Our program serves as a formal definition of a music
559 The syntax is also the user-interface for LilyPond, hence it is easy
567 a quarter note C1 (middle C) and an eighth note D1 (D above middle C)
569 @lilypond[quote,fragment]
573 On a microscopic scale, such syntax is easy to use. On a larger
574 scale, syntax also needs structure. How else can you enter complex
575 pieces like symphonies and operas? The structure is formed by the
576 concept of music expressions: by combining small fragments of music
577 into larger ones, more complex music can be expressed. For example
579 @lilypond[quote,verbatim,fragment,relative=1]
584 Chords can be constructed with @code{<<} and @code{>>} enclosing the notes
586 @c < > is not a music expression,
587 @c so we use <<>> iso. <> to drive home the point of
588 @c expressions. Don't change this back --hwn.
593 @lilypond[quote,fragment,relative=1]
594 \new Voice { <<c4 d4 e>> }
598 This expression is put in sequence by enclosing it in curly braces
599 @code{@{@tie{}@dots{}@tie{}@}}
602 @{ f4 <<c4 d4 e4>> @}
605 @lilypond[quote,relative=1,fragment]
610 The above is also an expression, and so it may be combined
611 again with another simultaneous expression (a half note) using <<,
615 << g2 \\ @{ f4 <<c4 d4 e4>> @} >>
618 @lilypond[quote,fragment,relative=2]
619 \new Voice { << g2 \\ { f4 <<c d e>> } >> }
622 Such recursive structures can be specified neatly and formally in a
623 context-free grammar. The parsing code is also generated from this
624 grammar. In other words, the syntax of LilyPond is clearly and
625 unambiguously defined.
627 User-interfaces and syntax are what people see and deal with
628 most. They are partly a matter of taste, and also subject of much
629 discussion. Although discussions on taste do have their merit, they
630 are not very productive. In the larger picture of LilyPond, the
631 importance of input syntax is small: inventing neat syntax is easy, while
632 writing decent formatting code is much harder. This is also
633 illustrated by the line-counts for the respective components: parsing
634 and representation take up less than 10% of the source code.
637 @node Example applications
638 @section Example applications
640 We have written LilyPond as an experiment of how to condense the art
641 of music engraving into a computer program. Thanks to all that hard
642 work, the program can now be used to perform useful tasks. The
643 simplest application is printing notes.
645 @lilypond[quote,relative=1,fragment]
646 \time 2/4 c4 c g'4 g a4 a g2
650 By adding chord names and lyrics we obtain a lead sheet.
652 @lilypond[quote,ragged-right]
654 \chords { c2 c f2 c }
655 \new Staff \relative c' { \time 2/4 c4 c g'4 g a4 a g2 }
656 \new Lyrics \lyricmode { twin4 kle twin kle lit tle star2 }
660 Polyphonic notation and piano music can also be printed. The following
661 example combines some more exotic constructs.
663 @lilypondfile[quote,ragged-right]{screech-boink.ly}
665 The fragments shown above have all been written by hand, but that is
666 not a requirement. Since the formatting engine is mostly automatic, it
667 can serve as an output means for other programs that manipulate
668 music. For example, it can also be used to convert databases of
669 musical fragments to images for use on websites and multimedia
672 This manual also shows an application: the input format is text, and
673 can therefore be easily embedded in other text-based formats such as
674 La@TeX{}, HTML, or in the case of this manual, Texinfo. By means of a
675 special program, the input fragments can be replaced by music images
676 in the resulting PDF or HTML output files. This makes it easy
677 to mix music and text in documents.
681 @node About this manual
682 @section About this manual
684 The manual is divided into the following chapters:
691 @emph{@ref{Tutorial}}
692 gives a gentle introduction to typesetting music. First time
693 users should start here.
696 @emph{@ref{Working on LilyPond projects}}
697 demonstrates practical uses of LilyPond.
700 @emph{@ref{Running LilyPond}}
701 shows how to run LilyPond and its helper
702 programs. In addition, this section explains how to upgrade input
703 files from previous versions of LilyPond.
706 @emph{@ref{Basic notation}}
707 discusses topics grouped by notation construct. This section gives
708 details about basic notation that will be useful in almost any
712 @emph{@ref{Instrument-specific notation}}
713 discusses topics grouped by notation construct. This section gives
714 details about special notation that will only be useful for particular
715 instrument (or vocal) groups.
718 @emph{@ref{Advanced notation}}
719 discusses topics grouped by notation construct. This section gives
720 details about complicated or unusual notation.
723 @emph{@ref{Changing defaults}}
724 explains how to fine tune layout.
727 @emph{@ref{Global issues}}
728 discusses issues which affect the global output, such as selecting
729 paper size or which MIDI instruments to use.
732 @emph{@ref{LilyPond-book}} explains the details behind creating
733 documents with in-line music examples, like this manual.
736 @emph{@ref{Converting from other formats}}
737 explains how to run the conversion programs. These programs
738 are supplied with the LilyPond package, and convert a variety of music
739 formats to the @code{.ly} format.
745 @emph{@ref{Literature list}}
746 contains a set of useful reference books for those who wish to know
747 more on notation and engraving.
750 @emph{@ref{Example templates}}
751 provides templates of LilyPond pieces. Just cut and paste a
752 template into a file, add notes, and you're done!
757 Once you are an experienced user, you can use the manual as reference:
758 there is an extensive index@footnote{If you are looking for something,
759 and you cannot find it in the manual, that is considered a bug. In
760 that case, please file a bug report.}, but the document is also
766 @uref{source/Documentation/user/lilypond.html, one big page},
768 which can be searched easily using the search facility of a web
770 @cindex search in manual
771 @cindex using the manual
774 @c add/integrate glossary, put in list above
775 If you are not familiar with music notation or music terminology
776 (especially if you are a non-native English speaker), it is advisable
777 to consult the glossary as well.
779 The music glossary explains musical terms, and includes translations
780 to various languages. It is a separate document, available in HTML
784 The @ref{Top,Music glossary,,music-glossary}, explains musical terms and
785 includes translations to various languages. It is also available in
791 @cindex foreign languages
795 This manual is not complete without a number of other documents. They
796 are not available in print, but should be included with the
797 documentation package for your platform
805 @ref{Top,Program reference,,lilypond-internals}.
808 The program reference is a set of heavily cross linked HTML pages,
809 which document the nitty-gritty details of each and every LilyPond
810 class, object, and function. It is produced directly from the
811 formatting definitions used.
813 Almost all formatting functionality that is used internally, is
814 available directly to the user. For example, all variables that
815 control thickness values, distances, etc., can be changed in input
816 files. There are a huge number of formatting options, and all of them
817 are described in this document. Each section of the
818 notation manual has a @b{See also} subsection, which refers to the
819 generated documentation. In the HTML document, these subsections
820 have clickable links.
825 Various input examples.
828 @c Works, but link name is not so nice; so write-out macro
829 @c @inputfileref{input/test,Various input examples}.
830 @uref{source/input/test/collated-files.html,Various input examples}.
833 This collection of files shows various tips and tricks, and is
834 available as a big HTML document, with pictures and explanatory texts
839 The regression tests.
842 @c Works, but link name is not so nice; so write-out macro
843 @c @inputfileref{input/regression,The regression tests}.
844 @uref{source/input/regression/collated-files.html,The regression tests}.
847 This collection of files tests each notation and engraving feature of
848 LilyPond in one file. The collection is primarily there to help us
849 debug problems, but it can be instructive to see how we exercise the
850 program. The format is similar to the tips and tricks document.
854 In all HTML documents that have music fragments embedded, the LilyPond
855 input that was used to produce that image can be viewed by clicking
858 The location of the documentation files that are mentioned here can
859 vary from system to system. On occasion, this manual refers to
860 initialization and example files. Throughout this manual, we refer to
861 input files relative to the top-directory of the source archive. For
862 example, @file{input/@/test/@/bla@/.ly} may refer to the file
863 @file{lilypond@/-2.8.0/@/input/@/test/@/bla@/.ly}. On binary packages
864 for the Unix platform, the documentation and examples can typically be
865 found somewhere below @file{/usr/@/share/@/doc/@/lilypond/}.
866 Initialization files, for example @file{scm/@/lily@/.scm}, or
867 @file{ly/@/engraver@/-init@/.ly}, are usually found in the directory
868 @file{/usr/@/share/@/lilypond/}.
870 @cindex adjusting output
873 @cindex lilypond-internals
874 @cindex internal documentation
876 @cindex extending lilypond
879 Finally, this and all other manuals, are available online both as PDF
880 files and HTML from the web site, which can be found at
881 @uref{http://@/www@/.lilypond@/.org/}.