1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @c This file is part of lilypond-learning.tely
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.
12 @node Fundamental concepts
13 @chapter Fundamental concepts
15 You've seen in the Tutorial how to produce beautifully printed
16 music from a simple text file. This section introduces the
17 concepts and techniques required to produce equally beautiful
18 but more complex scores.
21 * How LilyPond input files work::
22 * Voices contain music::
23 * Contexts and engravers::
24 * Extending the templates::
28 @node How LilyPond input files work
29 @section How LilyPond input files work
31 The LilyPond input format is quite free-form, giving experienced
32 users a lot of flexibility to structure their files however they
33 wish. But this flexibility can make things confusing for new
34 users. This section will explain some of this structure, but may
35 gloss over some details in favor of simplicity. For a complete
36 description of the input format, see @ruser{File structure}.
39 * Introduction to the LilyPond file structure::
40 * Score is a (single) compound musical expression::
41 * Nesting music expressions::
42 * On the un-nestedness of brackets and ties::
45 @node Introduction to the LilyPond file structure
46 @subsection Introduction to the LilyPond file structure
49 @cindex file structure
51 A basic example of a LilyPond input file is
54 \version @w{"@version{}"}
56 @var{...compound music expression...} % all the music goes here!
64 There are many variations of this basic pattern, but this
65 example serves as a useful starting place.
72 Up to this point none of the examples you have seen has used a
73 @code{\score@{@}} command. This is because LilyPond automatically
74 adds the extra commands which are needed when you give it simple
75 input. LilyPond treats input like this:
84 as shorthand for this:
101 In other words, if the input contains a single music expression,
102 LilyPond will interpret the file as though the music expression
103 was wrapped up inside the commands shown above.
105 @cindex implicit contexts
107 @strong{A word of warning!} Many of the examples in the LilyPond
108 documentation will omit the @code{\new Staff} and @code{\new Voice}
109 commands, leaving them to be created implicitly. For simple
110 examples this works well, but for more complex examples, especially
111 when additional commands are used, the implicit creation of contexts
112 can give surprising results, maybe creating extra unwanted staves.
113 The way to create contexts explicitly is explained in
114 @ref{Contexts and engravers}.
116 @warning{When entering more than a few lines of music it is
117 advisable to always create staves and voices explicitly.}
119 For now, though, let us return to the first example and examine the
120 @code{\score} command, leaving the others to default.
122 A @code{\score} block must always contain just one music expression,
123 and this must appear immediately after the @code{\score} command.
124 Remember that a music expression could be anything from a single
125 note to a huge compound expression like
130 @var{...insert the whole score of a Wagner opera in here...}
136 Since everything is inside @code{@{ ... @}}, it counts
137 as one music expression.
139 As we saw previously, the @code{\score} block can contain other
159 Note that these three commands -- @code{\header}, @code{\layout}
160 and @code{\midi} -- are special: unlike all other commands which
161 begin with a backward slash (@code{\}) they are @emph{not} music
162 expressions and are not part of any music expression.
163 So they may be placed inside a @code{\score} block
164 or outside it. In fact, these commands are commonly placed
165 outside the @code{\score} block -- for example, @code{\header}
166 is often placed above the @code{\score} command because headers
167 naturally appear at the top of a score. That's just another
168 shorthand that LilyPond accepts.
170 Two more commands you have not previously seen are
171 @code{\layout @{ @}} and @code{\midi @{@}}. If these appear as
172 shown they will cause LilyPond to produce a printed output and a
173 MIDI output respectively. They are described fully in the
174 Notation Reference -- @ruser{Score layout} and
175 @ruser{Creating MIDI files}.
177 @cindex scores, multiple
179 You may code multiple @code{\score} blocks. Each will be
180 treated as a separate score, but they will be all combined into
181 a single output file. A @code{\book} command is not necessary
182 -- one will be implicitly created. However, if you would like
183 separate output files from one @code{.ly} file then the
184 @code{\book} command should be used to separate the different
185 sections: each @code{\book} block will produce a
186 separate output file.
190 Every @code{\book} block creates a separate output file (e.g., a
191 pdf file). If you haven't explicitly added one, LilyPond wraps
192 your entire input code in a @code{\book} block implicitly.
194 Every @code{\score} block is a separate chunk of music within a
197 Every @code{\layout} block affects the @code{\score} or
198 @code{\book} block in which it appears -- i.e., a @code{\layout}
199 block inside a @code{\score} block affects only that @code{\score}
200 block, but a @code{\layout} block outside of a @code{\score} block
201 (and thus in a @code{\book} block, either explicitly or
202 implicitly) will affect every @code{\score} in that @code{\book}.
204 Every @code{\context} block will affect the named context (e.g.,
205 @code{\StaffGroup}) throughout the block (@code{\score} or
206 @code{\book}) in which it appears.
208 For details see @ruser{Multiple scores in a book}.
212 Another great shorthand is the ability to define variables. All
213 the templates use this
216 melody = \relative c' @{
225 When LilyPond looks at this file, it takes the value of
226 @code{melody} (everything after the equals sign) and inserts it
227 whenever it sees @code{\melody}. There's nothing special about
228 the names -- it could be @code{melody}, @code{global},
230 @code{pianorighthand}, or @code{foofoobarbaz}. For more details,
231 see @ref{Saving typing with variables and functions}.
232 Remember that you can use almost any name you like as long
233 as it contains just alphabetic characters and is distinct from
234 LilyPond command names. The exact
235 limitations on variable names are detailed in
236 @ruser{File structure}.
242 For a complete definition of the input format, see
243 @ruser{File structure}.
245 @node Score is a (single) compound musical expression
246 @subsection Score is a (single) compound musical expression
250 @cindex Compound music expression
251 @cindex Music expression, compound
253 We saw the general organization of LilyPond input files in the
254 previous section, @ref{How LilyPond input files work}. But we seemed to
255 skip over the most important part: how do we figure out what to
256 write after @code{\score}?
258 We didn't skip over it at all. The big mystery is simply that
259 there @emph{is} no mystery. This line explains it all:
262 @emph{A @code{\score} block must begin with a compound music expression.}
266 To understand what is meant by a music expression and a compound
267 music expression you may find it useful to review
268 @ref{Music expressions explained}. In that section, we saw how to
269 build big music expressions from small pieces -- we started from
270 notes, then chords, etc. Now we're going to start from a big
271 music expression and work our way down.
275 @{ % this brace begins the overall compound music expression
277 @var{...insert the whole score of a Wagner opera in here...}
279 @} % this brace ends the overall compound music expression
284 A whole Wagner opera would easily double the length of this
285 manual, so let's just add a singer and piano. We don't need a
286 @code{GrandStaff} for this ensemble, which simply groups a number
287 of staves together with a brace at the left, so we shall remove
288 it. We @emph{do} need a singer and a piano, though.
293 \new Staff = "singer" <<
295 \new PianoStaff = piano <<
302 Remember that we use @code{<< ... >>} instead of
303 @code{@{ ... @}} to show simultaneous
304 music. And we definitely want to show the vocal part and piano
305 part at the same time, not one after the other! However, the
306 @code{<< ... >>} construct is not really necessary for the Singer
307 staff, as it contains only one music expression, but Staves often
308 do require simultaneous Voices within them, so using
310 rather than braces is a good habit to adopt. We'll add some real
311 music later; for now let's just put in some dummy notes and lyrics.
313 @lilypond[verbatim,quote,ragged-right]
316 \new Staff = "singer" <<
317 \new Voice = "vocal" { c'1 }
320 \new PianoStaff = "piano" <<
321 \new Staff = "upper" { c'1 }
322 \new Staff = "lower" { c'1 }
329 Now we have a lot more details. We have the singer's staff: it
330 contains a @code{Voice} (in LilyPond, this term refers to a set of
331 notes, not necessarily vocal notes -- for example, a violin
332 generally plays one voice) and some lyrics. We also have a piano
333 staff: it contains an upper staff (right hand) and a lower staff
336 At this stage, we could start filling in notes. Inside the curly
337 braces next to @code{\new Voice = vocal}, we could start writing
345 But if we did that, the @code{\score} section would get pretty
346 long, and it would be harder to understand what was happening. So
347 let's use variables instead. These were introduced at the end
348 of the previous section, remember? So, adding a few notes, we
349 now have a piece of real music:
351 @lilypond[verbatim,quote,ragged-right]
352 melody = \relative c'' { r4 d8\noBeam g, c4 r }
353 text = \lyricmode { And God said, }
354 upper = \relative c'' { <g d g,>2~ <g d g,> }
355 lower = \relative c { b2 e2 }
359 \new Staff = "singer" <<
360 \new Voice = "vocal" { \melody }
363 \new PianoStaff = "piano" <<
364 \new Staff = "upper" { \upper }
365 \new Staff = "lower" {
376 Be careful about the difference between notes, which are introduced
377 with @code{\relative}, and lyrics, which are introduced with
378 @code{\lyricmode}. These are essential to tell LilyPond
379 to interpret the following content as music and text
382 When writing (or reading) a @code{\score} section, just take it
383 slowly and carefully. Start with the outer layer, then work on
384 each smaller layer. It also really helps to be strict with
385 indentation -- make sure that each item on the same layer starts
386 on the same horizontal position in your text editor.
389 @node Nesting music expressions
390 @subsection Nesting music expressions
392 @cindex staves, temporary
395 It is not essential to declare all staves at the beginning;
396 they may be introduced temporarily at any point. This is
397 particularly useful for creating ossia sections
398 (see @rglos{ossia}). Here is a simple example showing how
399 to introduce a new staff temporarily for the duration of
402 @lilypond[verbatim,quote,ragged-right]
419 Note that the size of the clef is the same as a clef printed
420 following a clef change -- slightly smaller than the clef
421 at the beginning of the line. This is usual for clefs printed
422 in the middle of a line.
424 @cindex staff, positioning
426 The ossia section may be placed above the staff
429 @lilypond[verbatim,quote,ragged-right]
437 alignAboveContext = "main" }
445 This example uses @code{\with}, which will be explained more
446 fully later. It is a means of modifying the default behavior
447 of a single Staff. Here it says that the new staff should be
448 placed above the staff called @qq{main} instead of the default
449 position which is below.
451 Ossia are often written without clef and without
452 time signature and are usually in a smaller font.
453 These require further commands which
454 have not yet been introduced. See @ref{Size of objects}
456 @node On the un-nestedness of brackets and ties
457 @subsection On the un-nestedness of brackets and ties
459 @cindex brackets, nesting
461 You have already met a number of different types of bracket in
462 writing the input file to LilyPond. These obey different rules
463 which can be confusing at first. Before we explain the rules
464 let's first review the different types of bracket.
466 @c attempt to force this onto a new page
468 @multitable @columnfractions .3 .7
469 @headitem Bracket Type
471 @item @code{@{ .. @}}
472 @tab Encloses a sequential segment of music
474 @tab Encloses the notes of a chord
475 @item @code{<< .. >>}
476 @tab Encloses concurrent or simultaneous sections
478 @tab Marks the start and end of a slur
479 @item @code{\( .. \)}
480 @tab Marks the start and end of a phrase mark
482 @tab Marks the start and end of a manual beam
485 To these we should add other constructs which generate lines
486 between or across notes: ties (marked by a tilde, @code{~}),
487 tuplets written as @code{\times x/y @{..@}}, and grace notes
488 written as @code{\grace@{..@}}.
490 Outside LilyPond, the conventional use of brackets requires
491 the different types to be properly nested, like this,
492 @code{<< [ @{ ( .. ) @} ] >>}, with the closing brackets being
493 encountered in exactly the opposite order to the opening
494 brackets. This @strong{is} a requirement for the three types of
495 bracket described by the word @q{Encloses} in the table above --
496 they must nest properly.
497 However, the remaining brackets, described with the word
498 @q{Marks} in the table above together with ties and tuplets,
499 do @strong{not} have to nest
500 properly with any of the brackets. In fact, these are not
501 brackets in the sense that
502 they enclose something -- they are simply markers to indicate
503 where something starts and ends.
505 So, for example, a phrasing slur can start before a manually
506 inserted beam and end before the end of the beam -- not very
507 musical, perhaps, but possible:
509 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
510 { g8\( a b[ c b\) a] }
513 In general, different kinds of brackets, and those implied by
514 tuplets, ties and grace notes, may be mixed freely.
515 This example shows a beam extending into a tuplet (line 1),
516 a slur extending into a tuplet (line 2),
517 a beam and a slur extending into a tuplet, a tie crossing
518 two tuplets, and a phrasing slur extending out of a tuplet
521 @lilypond[quote,verbatim,fragment,ragged-right]
523 r16[ g16 \times 2/3 {r16 e'8] }
524 g16( a \times 2/3 {b d) e' }
525 g8[( a \times 2/3 {b d') e'~]}
526 \times 4/5 {e'32\( a b d' e'} a'4.\)
531 @node Voices contain music
532 @section Voices contain music
534 Singers need voices to sing, and so does LilyPond.
535 The actual music for all instruments in a score
536 is contained in Voices -- the most fundamental
537 of all LilyPond's concepts.
540 * I'm hearing Voices::
541 * Explicitly instantiating voices::
542 * Voices and vocals::
545 @node I'm hearing Voices
546 @subsection I'm hearing Voices
550 @cindex multiple voices
551 @cindex Voice context
552 @cindex context, Voice
553 @cindex simultaneous music
554 @cindex concurrent music
556 The lowest, most fundamental or innermost layers in a LilyPond
557 score are called @q{Voice contexts} or just @q{Voices} for short.
558 Voices are sometimes called @q{layers} in other notation
561 In fact, a Voice layer or context is the only one which can
562 contain music. If a Voice context is not explicitly declared
563 one is created automatically, as we saw at the beginning of
564 this chapter. Some instruments such as an
565 Oboe can play only one note at a time. Music written for
566 such instruments is monophonic and requires just a single
567 voice. Instruments which can play more than one note at a
568 time like the piano will often require multiple voices to
569 encode the different concurrent notes and rhythms they are
572 A single voice can contain many notes in a chord, of course,
573 so when exactly are multiple voices needed? Look first at
574 this example of four chords:
576 @lilypond[quote,verbatim,fragment,ragged-right,relative=1]
578 <d g>4 <d fis> <d a'> <d g>
581 This can be expressed using just the single angle bracket chord
582 symbols, @code{< ... >}, and for this just a single voice is
583 needed. But suppose the F-sharp were actually an eighth-note
584 followed by an eighth-note G, a passing note on the way to the A?
585 Now we have two notes which start at the same time but have
586 different durations: the quarter-note D and the eighth-note
587 F-sharp. How are these to be coded? They cannot be written as
588 a chord because all the notes in a chord must have the same
589 duration. And they cannot be written as two separate notes
590 as they need to start at the same time. This is when two
593 Let us see how this is done in LilyPond input syntax.
598 The easiest way to enter fragments with more than one voice on a
599 staff is to enter each voice as a sequence (with @code{@{...@}}),
600 and combine them simultaneously with angle brackets, @code{<<...>>}.
601 The fragments must also be separated with double backward slashes,
602 @code{\\}, to place them in separate voices. Without these, the
603 notes would be entered into a single voice, which would usually
604 cause errors. This technique is particularly suited to pieces of
605 music which are largely monophonic with occasional short sections
608 Here's how we split the chords above into two voices and add both
609 the passing note and a slur:
611 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
613 % Voice "1" Voice "2"
614 << { g4 fis8( g) a4 g } \\ { d4 d d d } >> |
617 Notice how the stems of the second voice now point down.
619 Here's another simple example:
621 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
623 % Voice "1" Voice "2"
624 << { r4 g g4. a8 } \\ { d,2 d4 g } >> |
625 << { bes4 bes c bes } \\ { g4 g g8( a) g4 } >> |
626 << { a2. r4 } \\ { fis2. s4 } >> |
629 It is not necessary to use a separate @code{<< \\ >>} construct
630 for each bar. For music with few notes in each bar this layout
631 can help the legibility of the code, but if there are many
632 notes in each bar it may be better to split out each voice
633 separately, like this:
635 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
651 This example has just two voices, but the same construct may be
652 used to encode three or more voices by adding more back-slash
655 The Voice contexts bear the names @code{"1"}, @code{"2"}, etc.
656 In each of these contexts, the vertical direction of slurs,
657 stems, ties, dynamics etc., is set appropriately.
659 @lilypond[quote,verbatim,fragment]
660 \new Staff \relative c' {
663 % Voice "1" Voice "2" Voice "3"
664 << { g4 f e } \\ { r8 e4 d c8 ~ } >> |
665 << { d2 e2 } \\ { c8 b16 a b8 g ~ g2 } \\ { s4 b4 c2 } >> |
669 These voices are all separate from the main voice that contains
670 the notes just outside the @code{<< .. >>} construct. Let's call
671 this the @emph{simultaneous construct}. Slurs and ties may only
672 connect notes within the same voice, so slurs and ties cannot go
673 into or out of a simultaneous construct. Conversely,
674 parallel voices from separate simultaneous constructs on the same
675 staff are the same voice. Other voice-related properties also
676 carry across simultaneous constructs. Here is the same example,
677 with different colors and note heads for each voice. Note that
678 changes in one voice do not affect other voices, but they do
679 persist in the same voice later. Note also that tied notes may be
680 split across the same voices in two constructs, shown here in the
683 @lilypond[quote,verbatim]
684 \new Staff \relative c' {
703 { c8 b16 a b8 g ~ g2 }
713 @funindex \voiceXXXStyle
715 The commands @code{\voiceXXXStyle} are mainly intended for use in
716 educational documents such as this one. They modify the color
717 of the note head, the stem and the beams, and the style of the
718 note head, so that the voices may be easily distinguished.
719 Voice one is set to red diamonds, voice two to blue triangles,
720 voice three to green crossed circles, and voice four (not used
721 here) to magenta crosses. We shall see later how commands like
722 these may be created by the user.
723 See @ref{Visibility and color of objects} and
724 @ref{Using variables for tweaks}.
726 Polyphony does not change the relationship of notes within a
727 @code{\relative @{ @}} block. Each note is still calculated
728 relative to the note immediately preceding it, or to the first
729 note of the preceding chord. So in
732 \relative c' @{ noteA << < noteB noteC > \\ noteD >> noteE @}
736 @code{noteB} is relative to @code{noteA} @*
737 @code{noteC} is relative to @code{noteB}, not @code{noteA}; @*
738 @code{noteD} is relative to @code{noteB}, not @code{noteA} or
740 @code{noteE} is relative to @code{noteD}, not @code{noteA}
742 An alternative way, which may be clearer if the notes in the
743 voices are widely separated, is to place a @code{\relative}
744 command at the start of each voice:
747 \relative c' @{ noteA ... @}
749 \relative c'' @{ < noteB noteC > ... @}
751 \relative g' @{ noteD ... @}
753 \relative c' @{ noteE ... @}
756 Let us finally analyze the voices in a more complex piece of
758 the notes from the first two bars of the second of Chopin's
759 Deux Nocturnes, Op 32. This example will be used at later
760 stages in this and the next chapter to illustrate several
761 techniques for producing notation, so please ignore for now
762 anything in the underlying code which looks mysterious and
763 concentrate just on the music and the voices -- the
764 complications will all be explained in later sections.
766 @c The following should appear as music without code
767 @lilypond[quote,ragged-right]
768 \new Staff \relative c'' {
777 % Ignore these for now - they are explained in Ch 4
778 \once \override NoteColumn #'force-hshift = #0
780 \once \override NoteColumn #'force-hshift = #0.5
788 The direction of the stems is often used to indicate the
789 continuity of two simultaneous melodic lines. Here the
790 stems of the highest notes are all pointing up and the
791 stems of the lower notes are all pointing down.
792 This is the first indication that more than one voice
795 But the real need for multiple voices arises when notes
796 which start at the same time have different durations.
797 Look at the notes which start at beat three in the first
798 bar. The A-flat is a dotted quarter note, the F is a
799 quarter note and the D-flat is a half note. These
800 cannot be written as a chord as all the notes in a chord
801 must have the same duration. Neither can they be written
802 as sequential notes, as they must start at the same time.
803 This section of the bar requires three voices, and the
804 normal practice would be to write the whole bar as three
805 voices, as shown below, where we have used different note heads
806 and colors for the three voices. Again, the code behind this
807 example will be explained later, so ignore anything you do
810 @c The following should appear as music without code
811 @c The three voice styles should be defined in -init
812 @lilypond[quote,ragged-right]
813 \new Staff \relative c'' {
824 \\ % No Voice three (we want stems down)
827 % Ignore these for now - they are explained in Ch 4
828 \once \override NoteColumn #'force-hshift = #0
830 \once \override NoteColumn #'force-hshift = #0.5
839 Let us try to encode this music from scratch. As we
840 shall see, this encounters some difficulties. We begin as
841 we have learnt, using the @code{<< \\ >>} construct to
842 enter the music of the first bar in three voices:
844 @lilypond[quote,verbatim,fragment,ragged-right]
845 \new Staff \relative c'' {
848 { c2 aes4. bes8 } \\ { aes2 f4 fes } \\ { <ees c>2 des2 }
857 The stem directions are automatically assigned with the
858 odd-numbered voices taking upward stems and the even-numbered
859 voices downward ones. The stems for voices 1 and 2 are right,
860 but the stems in voice 3 should go down in this particular piece
861 of music. We can correct this simply by missing out voice three
862 and placing the music in voice four:
864 @lilypond[quote,verbatim,fragment,ragged-right]
865 \new Staff \relative c'' {
871 \\ % Omit Voice three
880 We see that this fixes the stem direction, but exposes a
881 problem sometimes encountered with multiple voices -- the
882 stems of the notes in one voice can collide with the note heads
883 in other voices. In laying out the notes, LilyPond allows the
884 notes or chords from two voices to occupy the same vertical
885 note column provided the stems are in opposite directions, but
886 the notes from the third and fourth voices are displaced to if
887 necessary to avoid the note heads
888 colliding. This usually works well, but in this example the
889 notes of the lowest voice are clearly not well placed by default.
890 LilyPond provides several ways to adjust the horizontal placing
891 of notes. We are not quite ready yet to see how to correct this,
892 so we shall leave this problem until a later section
893 (see the force-hshift property in @ref{Fixing overlapping
896 @node Explicitly instantiating voices
897 @subsection Explicitly instantiating voices
901 @funindex \voiceThree
904 @cindex Voice contexts, creating
906 Voice contexts can also be created manually
907 inside a @code{<< >>} block to create polyphonic music, using
908 @code{\voiceOne} ... @code{\voiceFour} to indicate the required
909 directions of stems, slurs, etc. In longer scores this method
910 is clearer, as it permits the voices to be separated and to be
911 given more descriptive names.
913 Specifically, the construct @code{<< \\ >>} which we used in
914 the previous section:
919 << @{ e4 f g a @} \\ @{ c,4 d e f @} >>
929 \new Voice = "1" @{ \voiceOne \relative c' @{ e4 f g a @} @}
930 \new Voice = "2" @{ \voiceTwo \relative c' @{ c4 d e f @} @}
934 Both of the above would produce
936 @c The following example should not display the code
937 @lilypond[ragged-right,quote]
939 \new Voice = "1" { \voiceOne \relative c' { e4 f g a } }
940 \new Voice = "2" { \voiceTwo \relative c' { c4 d e f } }
944 The @code{\voiceXXX} commands set the direction of stems, slurs,
945 ties, articulations, text annotations, augmentation dots of dotted
946 notes, and fingerings. @code{\voiceOne} and @code{\voiceThree}
947 make these objects point upwards, while @code{\voiceTwo} and
948 @code{\voiceFour} make them point downwards. These commands also
949 generate a horizontal shift for each voice when this is required
950 to avoid clashes of note heads. The command @code{\oneVoice}
951 reverts the settings back to the normal values for a single voice.
953 Let us see in some simple examples exactly what effect
954 @code{\oneVoice}, @code{\voiceOne} and @code{voiceTwo} have on
955 markup, ties, slurs, and dynamics:
957 @lilypond[quote,ragged-right,verbatim]
959 % Default behavior or behavior after \oneVoice
960 c d8 ~ d e4 ( f g a ) b-> c
964 @lilypond[quote,ragged-right,verbatim]
967 c d8 ~ d e4 ( f g a ) b-> c
969 c, d8 ~ d e4 ( f g a ) b-> c
973 @lilypond[quote,ragged-right,verbatim]
976 c d8 ~ d e4 ( f g a ) b-> c
978 c, d8 ~ d e4 ( f g a ) b-> c
982 Now let's look at three different ways to notate the same passage
983 of polyphonic music, each of which is advantageous in different
984 circumstances, using the example from the previous section.
986 An expression that appears directly inside a @code{<< >>} belongs
987 to the main voice (but, note, @strong{not} in a @code{<< \\ >>}
988 construct). This is useful when extra voices appear while the
989 main voice is playing. Here is a more correct rendition of our
990 example. The red diamond-shaped notes
991 demonstrate that the main melody is now in a single voice context,
992 permitting a phrasing slur to be drawn over them.
994 @lilypond[quote,ragged-right,verbatim]
995 \new Staff \relative c' {
997 % The following notes are monophonic
999 % Start simultaneous section of three voices
1001 % Continue the main voice in parallel
1003 % Initiate second voice
1005 % Set stems, etc, down
1007 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2
1009 % Initiate third voice
1011 % Set stems, etc, up
1019 @cindex nesting music expressions
1020 @cindex nesting simultaneous constructs
1022 @cindex voices, temporary
1023 @cindex voices, nesting
1025 More deeply nested polyphony constructs are possible, and if a
1026 voice appears only briefly this might be a more natural way to
1029 @lilypond[quote,ragged-right,verbatim]
1030 \new Staff \relative c' {
1038 {c8 b16 a b8 g ~ g2}
1049 @cindex spacing notes
1051 This method of nesting new voices briefly is useful
1052 when only small sections of the music
1053 are polyphonic, but when the whole staff is largely polyphonic
1054 it can be clearer to use multiple voices throughout, using
1055 spacing notes to step over sections where the voice is silent,
1058 @lilypond[quote,ragged-right,verbatim]
1059 \new Staff \relative c' <<
1060 % Initiate first voice
1063 c16^( d e f g4 f e | d2 e2) |
1065 % Initiate second voice
1067 % set stems, etc down
1069 s4 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2 |
1071 % Initiate third voice
1080 @subsubheading Note columns
1083 @cindex shift commands
1087 @funindex \shiftOnnn
1089 Closely spaced notes in a chord, or notes occurring at the same
1090 time in different voices, are arranged in two, occasionally more,
1091 columns to prevent the note heads overlapping. These are called
1092 note columns. There are separate columns for each voice, and
1093 the currently specified voice-dependent shift is applied to the
1094 note column if there would otherwise be a collision. This can
1095 be seen in the example above. In bar 2 the C in voice two is
1096 shifted to the right relative to the D in voice one, and in the
1097 final chord the C in voice three is also shifted to the right
1098 relative to the other notes.
1100 The @code{\shiftOn}, @code{\shiftOnn}, @code{\shiftOnnn}, and
1101 @code{\shiftOff} commands specify the degree to which notes and
1102 chords of the voice should be shifted if a collision
1103 would otherwise occur. By default, the outer voices (normally
1104 voices one and two) have @code{\shiftOff} specified, while the
1105 inner voices (three and four) have @code{\shiftOn} specified.
1106 When a shift is applied, Voices one and three are shifted to
1107 the right and voices two and four to the left.
1109 @code{\shiftOnn} and @code{\shiftOnnn} define further shift
1110 levels which may be specified temporarily to resolve collisions
1111 in complex situations -- see @ref{Real music example}.
1113 A note column can contain just one note (or chord) from a voice
1114 with stems up and one note (or chord) from a voice with stems
1115 down. If notes from two voices which have their stems in the
1116 same direction are placed at the same position and both voices
1117 have no shift or the same shift specified, the error message
1118 @qq{Too many clashing note columns} will be produced.
1120 @node Voices and vocals
1121 @subsection Voices and vocals
1123 Vocal music presents a special difficulty: we need to combine two
1124 expressions -- notes and lyrics.
1126 @funindex \new Lyrics
1128 @cindex Lyrics context, creating
1129 @cindex lyrics, linking to voice
1131 You have already seen the @code{\addlyrics@{@}} command, which
1132 handles simple scores well. However, this technique is
1133 quite limited. For more complex music, you must introduce the
1134 lyrics in a @code{Lyrics} context using @code{\new Lyrics} and
1136 the lyrics to the notes with @code{\lyricsto@{@}}, using the
1137 name assigned to the Voice.
1139 @lilypond[quote,verbatim,fragment]
1141 \new Voice = "one" \relative c'' {
1144 c4 b8. a16 g4. f8 e4 d c2
1146 \new Lyrics \lyricsto "one" {
1147 No more let sins and sor -- rows grow.
1152 Note that the lyrics must be linked to a @code{Voice} context,
1153 @emph{not} a @code{Staff} context. This is a case where it is
1154 necessary to create @code{Staff} and @code{Voice} contexts
1157 @cindex lyrics and beaming
1158 @cindex beaming and lyrics
1159 @funindex \autoBeamOff
1161 The automatic beaming which LilyPond uses by default works well
1162 for instrumental music, but not so well for music with lyrics,
1163 where beaming is either not required at all or is used to indicate
1164 melismata in the lyrics. In the example above we use the command
1165 @code{\autoBeamOff} to turn off the automatic beaming.
1167 @funindex \new ChoirStaff
1168 @funindex \lyricmode
1169 @cindex vocal score structure
1171 Let us reuse the earlier example from Judas Maccabæus to
1172 illustrate this more flexible technique. We first recast
1173 it to use variables so the music and lyrics can be separated
1174 from the staff structure. We also introduce a ChoirStaff
1175 bracket. The lyrics themselves must be introduced with
1176 @code{\lyricmode} to ensure they are interpreted as lyrics
1179 @lilypond[quote,verbatim]
1180 global = { \time 6/8 \partial 8 \key f \major}
1181 SopOneMusic = \relative c'' {
1182 c8 | c([ bes)] a a([ g)] f | f'4. b, | c4.~ c4 }
1183 SopTwoMusic = \relative c' {
1184 r8 | r4. r4 c8 | a'([ g)] f f([ e)] d | e([ d)] c bes' }
1185 SopOneLyrics = \lyricmode {
1186 Let | flee -- cy flocks the | hills a -- dorn, __ }
1187 SopTwoLyrics = \lyricmode {
1188 Let | flee -- cy flocks the | hills a -- dorn, }
1193 \new Voice = "SopOne" {
1197 \new Lyrics \lyricsto "SopOne" {
1202 \new Voice = "SopTwo" {
1206 \new Lyrics \lyricsto "SopTwo" {
1214 This is the basic structure of all vocal scores. More staves may
1215 be added as required, more voices may be added to the staves,
1216 more verses may be added to the lyrics,
1217 and the variables containing the music can easily be placed
1218 in separate files should they become too long.
1220 @cindex hymn structure
1222 Here is a example of the first line of a hymn with four
1223 verses, set for SATB. In this case the words for all four
1224 parts are the same. Note how we use variables to separate the
1225 music notation and words from the staff structure. See too
1226 how a variable, which we have chosen to call @q{TimeKey}, is used
1227 to hold several commands for use within the two staves. In other
1228 examples this is often called @q{global}.
1230 @lilypond[quote,verbatim]
1231 TimeKey = { \time 4/4 \partial 4 \key c \major}
1232 SopMusic = \relative c' { c4 | e4. e8 g4 g | a a g }
1233 AltoMusic = \relative c' { c4 | c4. c8 e4 e | f f e }
1234 TenorMusic = \relative c { e4 | g4. g8 c4. b8 | a8 b c d e4 }
1235 BassMusic = \relative c { c4 | c4. c8 c4 c | f8 g a b c4 }
1236 VerseOne = \lyricmode {
1237 E -- | ter -- nal fa -- ther, | strong to save, }
1238 VerseTwo = \lyricmode {
1239 O | Christ, whose voice the | wa -- ters heard, }
1240 VerseThree = \lyricmode {
1241 O | Ho -- ly Spi -- rit, | who didst brood }
1242 VerseFour = \lyricmode {
1243 O | Tri -- ni -- ty of | love and pow'r }
1249 \new Voice = "Sop" { \voiceOne \TimeKey \SopMusic }
1250 \new Voice = "Alto" { \voiceTwo \AltoMusic }
1251 \new Lyrics \lyricsto "Sop" { \VerseOne }
1252 \new Lyrics \lyricsto "Sop" { \VerseTwo }
1253 \new Lyrics \lyricsto "Sop" { \VerseThree }
1254 \new Lyrics \lyricsto "Sop" { \VerseFour }
1258 \new Voice = "Tenor" { \voiceOne \TimeKey \TenorMusic }
1259 \new Voice = "Bass" { \voiceTwo \BassMusic }
1265 @cindex verse and refrain
1267 We end with an example to show how we might code a solo verse which
1268 continues into a two-part refrain in two staves. The
1269 positioning of the sequential and simultaneous sections to achieve
1270 this within a single score is quite tricky, so follow the
1271 explanation carefully!
1273 Let's start with a score block containing a @code{ChoirStaff}, as
1274 we would like the brace to appear at the start of the chorus.
1275 Normally you would need angle brackets after @code{\new ChoirStaff}
1276 to bring in all the staves in parallel, but here we want to
1277 defer the parallelism during the solo so we use braces, although
1278 angle brackets here wouldn't hurt. Inside the @code{ChoirStaff} we
1279 want first the staff which will contain the verse. This must
1280 contain notes and lyrics in parallel, so here we need angle
1281 brackets around the @code{\new Voice} and @code{\new Lyrics} to
1282 start them at the same time:
1284 @lilypond[quote,verbatim,ragged-right]
1285 versenotes = \relative c'' {
1288 \time 3/4 g g g b b b
1290 versewords = \lyricmode {
1291 One two three four five six
1296 \new Voice = "verse" {
1299 \new Lyrics \lyricsto verse {
1307 That gives the verse line.
1309 Now we want to continue with refrainA on the same staff while a
1310 second staff is introduced in parallel with it for refrainB, so
1311 this is a parallel section which must be positioned immediately
1312 following the @code{\break} in the verse Voice. Yes, @emph{within}
1313 the verse Voice! Here's that parallel section. More staves
1314 could be introduced here in the same way.
1319 \new Lyrics \lyricsto verse @{
1323 \new Voice = "refrainB" @{
1326 \new Lyrics \lyricsto "refrainB" @{
1333 Here's the final result with two staves in the chorus showing
1334 how the parallel section is positioned within the verse Voice:
1336 @lilypond[quote,verbatim, ragged-right]
1337 versenotes = \relative c'' {
1340 \time 3/4 g g g b b b
1342 refrainnotesA = \relative c'' {
1346 refrainnotesB = \relative c {
1351 versewords = \lyricmode {
1352 One two three four five six
1354 refrainwordsA = \lyricmode {
1357 refrainwordsB = \lyricmode {
1363 \context Voice = "verse" {
1367 \new Lyrics \lyricsto "verse" {
1371 \new Voice = "refrainB" {
1374 \new Lyrics \lyricsto "refrainB" {
1380 \new Lyrics \lyricsto "verse" {
1388 @cindex book, example of using
1391 However, although this is an interesting and useful exercise to
1392 help you to understand how sequential and simultaneous blocks work,
1393 in practice one would perhaps choose to code this as two
1394 @code{\score} blocks within an implicit @code{\book} block, as
1397 @lilypond[quote,verbatim,ragged-right]
1398 versenotes = \relative c'' {
1401 \time 3/4 g g g b b b
1403 refrainnotesA = \relative c'' {
1407 refrainnotesB = \relative c {
1412 versewords = \lyricmode {
1413 One two three four five six
1415 refrainwordsA = \lyricmode {
1418 refrainwordsB = \lyricmode {
1423 \new Voice = "verse" {
1426 \new Lyrics \lyricsto "verse" {
1435 \new Voice = "refrainA" {
1438 \new Lyrics \lyricsto "refrainA" {
1443 \new Voice = "refrainB" {
1446 \new Lyrics \lyricsto "refrainB" {
1454 @node Contexts and engravers
1455 @section Contexts and engravers
1457 Contexts and engravers have been mentioned informally
1458 in earlier sections; we now must look at
1459 these concepts in more detail, as they are important
1460 in the fine-tuning of LilyPond output.
1464 * Contexts explained::
1465 * Creating contexts::
1466 * Engravers explained::
1467 * Modifying context properties::
1468 * Adding and removing engravers::
1471 @node Contexts explained
1472 @subsection Contexts explained
1474 @cindex contexts explained
1476 When music is printed, many notational elements which do not
1477 appear explicitly in the input file must be added to the
1478 output. For example, compare the input and output of the
1481 @lilypond[quote,verbatim,relative=2,fragment]
1485 The input is rather sparse, but in the output, bar lines,
1486 accidentals, clef, and time signature have been added. When
1487 LilyPond @emph{interprets} the input the musical information
1488 is inspected in time order, similar to reading a score from left
1489 to right. While reading the input, the program remembers where
1490 measure boundaries are, and which pitches require explicit
1491 accidentals. This information must be held on several levels.
1492 For example, the effect of an accidental is limited
1493 to a single staff, while a bar line must be synchronized across
1496 Within LilyPond, these rules and bits of information are grouped
1497 in @emph{Contexts}. We have already met the
1498 @code{Voice} context.
1499 Others are the @code{Staff} and @code{Score} contexts.
1500 Contexts are hierarchical to reflect the hierarchical nature of
1502 For example: a @code{Staff} context can contain many
1503 @code{Voice} contexts, and a @code{Score} context can
1504 contain many @code{Staff} contexts.
1507 @sourceimage{context-example,5cm,,}
1510 Each context has the responsibility for enforcing some notation rules,
1511 creating some notation objects and maintaining the associated
1512 properties. For example, the @code{Voice} context may introduce an
1513 accidental and then the @code{Staff} context maintains the rule to
1514 show or suppress the accidental for the remainder of the measure.
1516 As another example, the synchronization of bar lines is, by default,
1517 handled in the @code{Score} context.
1518 However, in some music we may not want the bar lines to be
1519 synchronized -- consider a polymetric score in 4/4 and 3/4 time.
1520 In such cases, we must modify the default settings of the
1521 @code{Score} and @code{Staff} contexts.
1523 For very simple scores, contexts are created implicitly, and you need
1524 not be aware of them. For larger pieces, such as anything with more
1525 than one staff, they must be
1526 created explicitly to make sure that you get as many staves as you
1527 need, and that they are in the correct order. For typesetting pieces
1528 with specialized notation, it is usual to modify existing, or
1529 even to define totally new, contexts.
1531 In addition to the @code{Score,} @code{Staff} and
1532 @code{Voice} contexts there are contexts which fit between
1533 the score and staff levels to control staff groups, such as the
1534 @code{PianoStaff} and @code{ChoirStaff} contexts. There
1535 are also alternative staff and voice contexts, and contexts for
1536 lyrics, percussion, fret boards, figured bass, etc.
1538 The names of all context types are formed from one or more
1539 words, each word being capitalized and joined immediately to the
1540 preceding word with no hyphen or underscore, e.g.,
1541 @code{GregorianTranscriptionStaff}.
1543 @node Creating contexts
1544 @subsection Creating contexts
1547 @cindex new contexts
1548 @cindex creating contexts
1549 @cindex contexts, creating
1551 There can be only one top level context: the
1553 context. This is created with the @code{\score} command,
1554 or, in simple scores, it is created automatically.
1556 For scores with only one voice and one staff, the
1557 @code{Voice} and @code{Staff} contexts may be left to be
1558 created automatically, but for more complex scores it is
1559 necessary to create them by hand.
1560 The simplest command that does this is @code{\new}.
1561 It is prepended to a music expression, for example
1564 \new @var{type} @var{music-expression}
1568 where @var{type} is a context name (like @code{Staff} or
1569 @code{Voice}). This command creates a new context, and starts
1570 interpreting the @var{music-expression} within that context.
1572 Note that there is no @code{\new Score} command;
1573 the single top-level @code{Score} context is introduced
1576 You have seen many practical examples which created new
1577 @code{Staff} and @code{Voice} contexts in earlier sections, but
1578 to remind you how these commands are used in practice, here's an
1579 annotated real-music example:
1581 @lilypond[quote,verbatim,ragged-right]
1582 \score { % start single compound music expression
1583 << % start of simultaneous staves section
1585 \new Staff { % create RH staff
1588 \new Voice { % create voice for RH notes
1589 \relative c'' { % start of RH notes
1595 \new Staff << % create LH staff; needs two simultaneous voices
1598 \new Voice { % create LH voice one
1600 \relative g { % start of LH voice one notes
1601 g8 <bes d> ees, <g c> |
1602 g8 <bes d> ees, <g c> |
1603 } % end of LH voice one notes
1604 } % end of first LH voice
1605 \new Voice { % create LH voice two
1607 \relative g { % start of LH voice two notes
1610 } % end of LH voice two notes
1611 } % end of LH voice two
1612 >> % end of LH staff
1613 >> % end of simultaneous staves section
1614 } % end of single compound music expression
1617 (Note how all the statements which open a block with either a
1618 curly bracket, @code{@{}, or double angle brackets, @code{<<},
1619 are indented by two further spaces, and the corresponding
1620 closing bracket is indented by exactly the same amount. While
1621 this is not required, following this practice will greatly
1622 reduce the number of @q{unmatched bracket} errors, and is
1623 strongly recommended. It enables the structure of the music to
1624 be seen at a glance, and any unmatched brackets will be obvious.
1625 Note too how the LH staff is created using double angle brackets
1626 because it requires two voices for its music, whereas the RH staff
1627 is created with a single music expression surrounded by curly
1628 brackets because it requires only one voice.)
1630 @cindex contexts, naming
1631 @cindex naming contexts
1633 The @code{\new} command may also give a identifying name to the
1634 context to distinguish it from other contexts of the same type,
1637 \new @var{type} = @var{id} @var{music-expression}
1640 Note the distinction between the name of the context type,
1641 @code{Staff}, @code{Voice}, etc, and
1642 the identifying name of a particular instance of that type,
1643 which can be any sequence of letters invented by the user.
1644 The identifying name is used to refer back to that particular
1645 instance of a context. We saw this in use in the section on
1646 lyrics in @ref{Voices and vocals}.
1649 @node Engravers explained
1650 @subsection Engravers explained
1654 Every mark on the printed output of a score produced by LilyPond
1655 is produced by an @code{Engraver}. Thus there is an engraver
1656 to print staves, one to print note heads, one for stems, one for
1657 beams, etc, etc. In total there are over 120 such engravers!
1658 Fortunately, for most scores it is not necessary to know about
1659 more than a few, and for simple scores you do not need to know
1662 Engravers live and operate in Contexts.
1663 Engravers such as the @code{Metronome_mark_engraver}, whose
1664 action and output applies to the score as a whole, operate in
1665 the highest level context -- the @code{Score} context.
1667 The @code{Clef_engraver} and @code{Key_engraver} are to be
1668 found in every Staff Context, as different staves may require
1669 different clefs and keys.
1671 The @code{Note_heads_engraver} and @code{Stem_engraver} live
1672 in every @code{Voice} context, the lowest level context of all.
1674 Each engraver processes the particular objects associated
1675 with its function, and maintains the properties that relate
1676 to that function. These properties, like the properties
1677 associated with contexts, may be modified to change the
1678 operation of the engraver or the appearance of those elements
1679 in the printed score.
1681 Engravers all have compound names formed from words which
1682 describe their function. Just the first word is capitalized,
1683 and the remainder are joined to it with underscores. Thus
1684 the @code{Staff_symbol_engraver} is responsible for creating the
1685 lines of the staff, the @code{Clef_engraver} determines and sets
1686 the pitch reference point on the staff by drawing a clef symbol.
1688 Here are some of the most common engravers together with their
1689 function. You will see it is usually easy to guess the function
1690 from the name, or vice versa.
1692 @multitable @columnfractions .3 .7
1695 @item Accidental_engraver
1696 @tab Makes accidentals, cautionary and suggested accidentals
1701 @item Completion_heads_engraver
1702 @tab Splits notes which cross bar lines
1703 @item Dynamic_engraver
1704 @tab Creates hairpins and dynamic texts
1705 @item Forbid_line_break_engraver
1706 @tab Prevents line breaks if a musical element is still active
1708 @tab Creates the key signature
1709 @item Metronome_mark_engraver
1710 @tab Engraves metronome marking
1711 @item Note_heads_engraver
1712 @tab Engraves note heads
1715 @item Staff_symbol_engraver
1716 @tab Engraves the five (by default) lines of the staff
1718 @tab Creates stems and single-stem tremolos
1719 @item Time_signature_engraver
1720 @tab Creates time signatures
1725 We shall see later how the output of LilyPond can be changed
1726 by modifying the action of Engravers.
1729 @node Modifying context properties
1730 @subsection Modifying context properties
1732 @cindex context properties
1733 @cindex context properties, modifying
1734 @cindex modifying context properties
1738 Contexts are responsible for holding the values of a number of
1739 context @emph{properties}. Many of them can be changed to
1740 influence the interpretation of the input and so change the
1741 appearance of the output. They are changed by the
1742 @code{\set} command. This takes the form
1745 \set @emph{ContextName}.@emph{propertyName} = #@emph{value}
1748 Where the @emph{ContextName} is usually @code{Score},
1749 @code{Staff} or @code{Voice}. It may be omitted,
1750 in which case @code{Voice} is assumed.
1752 The names of context properties consist of words joined
1753 together with no hyphens or underscores, all except the
1754 first having a capital letter. Here are a few examples
1755 of some commonly used ones. There are many more.
1757 @c attempt to force this onto a new page
1759 @multitable @columnfractions .25 .15 .45 .15
1760 @headitem propertyName
1766 @tab If true, set extra natural signs before accidentals
1767 @tab @code{#t}, @code{#f}
1768 @item currentBarNumber
1770 @tab Set the current bar number
1774 @tab If true, print slurs both above and below notes
1775 @tab @code{#t}, @code{#f}
1776 @item instrumentName
1778 @tab Set the name to be placed at the start of the staff
1779 @tab @code{"Cello I"}
1782 @tab Increase or decrease the font size
1786 @tab Set the text to print before the start of a verse
1791 where a Boolean is either True (@code{#t}) or False (@code{#f}),
1792 an Integer is a positive whole number, a Real is a positive
1793 or negative decimal number, and text is enclosed in double
1794 apostrophes. Note the occurrence of hash signs,
1795 (@code{#}), in two different places -- as part of the Boolean
1796 value before the @code{t} or @code{f}, and before @emph{value}
1797 in the @code{\set} statement. So when a Boolean is being
1798 entered you need to code two hash signs, e.g., @code{##t}.
1800 Before we can set any of these properties we need to know
1801 in which context they operate. Sometimes this is obvious,
1802 but occasionally it can be tricky. If the wrong context
1803 is specified, no error message is produced, but the expected
1804 action will not take place. For example, the
1805 @code{instrumentName} clearly lives in the Staff context, since
1806 it is the staff that is to be named.
1807 In this example the first staff is labelled, but not the second,
1808 because we omitted the context name.
1810 @lilypond[quote,verbatim,ragged-right]
1812 \new Staff \relative c'' {
1813 \set Staff.instrumentName = #"Soprano"
1816 \new Staff \relative c' {
1817 \set instrumentName = #"Alto" % Wrong!
1823 Remember the default context name is Voice, so the second
1824 @code{\set} command set the property @code{instrumentName} in the
1825 Voice context to @qq{Alto}, but as LilyPond does not look
1826 for any such property in the @code{Voice} context, no
1827 further action took place. This is not an error, and no error
1828 message is logged in the log file.
1830 Similarly, if the property name is mis-spelt no error message
1831 is produced, and clearly the expected action cannot be performed.
1832 If fact, you can set any (fictitious) @q{property} using any
1833 name you like in any context that exists by using the
1834 @code{\set} command. But if the name is not
1835 known to LilyPond it will not cause any action to be taken.
1836 This is one of the reasons why it is highly recommended to
1837 use a context-sensitive editor with syntax highlighting for
1838 editing LilyPond input files, such as Vim, Jedit, ConTEXT or Emacs,
1839 since unknown property names will be highlighted differently.
1841 The @code{instrumentName} property will take effect only
1842 if it is set in the @code{Staff} context, but
1843 some properties can be set in more than one context.
1844 For example, the property @code{extraNatural} is by
1845 default set to ##t (true) for all staves.
1846 If it is set to ##f (false) in one particular @code{Staff}
1847 context it applies just to the accidentals on that staff.
1848 If it is set to false in the @code{Score} context
1849 it applies to all staves.
1851 So this turns off extra naturals in one staff:
1853 @lilypond[quote,verbatim,ragged-right]
1855 \new Staff \relative c'' {
1858 \new Staff \relative c'' {
1859 \set Staff.extraNatural = ##f
1866 and this turns them off in all staves:
1868 @lilypond[quote,verbatim,ragged-right]
1870 \new Staff \relative c'' {
1873 \new Staff \relative c'' {
1874 \set Score.extraNatural = ##f
1880 As another example, if @code{clefOctavation} is set in
1881 the @code{Score} context this immediately changes the value
1882 of the octavation in all current staves and sets a new default
1883 value which will be applied to all staves.
1885 The opposite command, @code{\unset}, effectively removes the
1886 property from the context, which causes most properties to
1887 revert to their default value. Usually @code{\unset} is not
1888 required as a new @code{\set} command will achieve what is
1891 The @code{\set} and @code{\unset} commands can appear anywhere
1892 in the input file and will take effect from the time they are
1893 encountered until the end of the score or until the property is
1894 @code{\set} or @code{\unset} again. Let's try changing the
1895 font size, which affects the size of the note heads (among
1896 other things) several times. The change is from the default
1897 value, not the most recently set value.
1899 @lilypond[quote,verbatim,ragged-right,relative=1,fragment]
1901 % make note heads smaller
1904 % make note heads larger
1905 \set fontSize = #2.5
1907 % return to default size
1912 We have now seen how to set the values of several different
1913 types of property. Note that integers and numbers are always
1914 preceded by a hash sign, @code{#}, while a true or false value
1915 is specified by ##t and ##f, with two hash signs. A text
1916 property should be enclosed in double quotation signs, as above,
1917 although we shall see later that text can actually be specified
1918 in a much more general way by using the very powerful
1919 @code{markup} command.
1923 @cindex context properties, setting with \with
1925 Context properties may also be set at the time the context is
1926 created. Sometimes this is a clearer way of specifying a
1927 property value if it is to remain fixed for the duration of
1928 the context. When a context is created with a @code{\new}
1929 command it may be followed immediately by a
1930 @code{\with @{ .. @}} block in which the property values are
1931 set. For example, if we wish to suppress the printing of
1932 extra naturals for the duration of a staff we would write:
1935 \new Staff \with @{ extraNatural = ##f @}
1941 @lilypond[quote,verbatim,ragged-right]
1947 \new Staff \with { extraNatural = ##f }
1954 Properties set in this way may still be changed dynamically using
1955 @code{\set} and returned to their default value with @code{\unset}.
1957 The @code{fontSize} property is treated differently. If this is
1958 set in a @code{\with} clause it effectively resets the default
1959 value of the font size. If it is later changed with @code{\set}
1960 this new default value may be restored with the
1961 @code{\unset fontSize} command.
1963 @node Adding and removing engravers
1964 @subsection Adding and removing engravers
1966 @cindex engravers, adding
1967 @cindex engravers, removing
1972 We have seen that contexts each contain several engravers, each
1973 of which is responsible for producing a particular part of the
1974 output, like bar lines, staves, note heads, stems, etc. If an
1975 engraver is removed from a context it can no longer produce its
1976 output. This is a crude way of modifying the output, but it
1977 can sometimes be useful.
1979 @subsubheading Changing a single context
1981 To remove an engraver from a single context we use the
1982 @code{\with} command placed immediately after the context creation
1983 command, as in the previous section.
1986 illustration let's repeat an example from the previous
1987 section with the staff lines removed. Remember that the
1988 staff lines are produced by the Staff_symbol_engraver.
1990 @lilypond[quote,verbatim,ragged-right]
1992 \remove Staff_symbol_engraver
1996 \set fontSize = #-4 % make note heads smaller
1998 \set fontSize = #2.5 % make note heads larger
2000 \unset fontSize % return to original size
2005 @cindex ambitus engraver
2007 Engravers can also be added to individual contexts.
2008 The command to do this is
2010 @code{\consists @emph{Engraver_name}},
2012 placed inside a @code{\with} block. Some vocal scores
2013 have an @rglos{ambitus} placed at the beginning of a
2014 staff to indicate the range of notes in that staff.
2015 The ambitus is produced by the @code{Ambitus_engraver},
2016 which is not normally included in any context. If
2017 we add it to the @code{Voice} context it calculates
2018 the range from that voice only:
2020 @lilypond[quote,verbatim,ragged-right]
2023 \consists Ambitus_engraver
2038 but if we add the Ambitus engraver to the
2039 @code{Staff} context it calculates the range from all
2040 the notes in all the voices on that staff:
2042 @lilypond[quote,verbatim,ragged-right]
2044 \consists Ambitus_engraver
2060 @subsubheading Changing all contexts of the same type
2064 The examples above show how to remove or add engravers to
2065 individual contexts. It is also possible to remove or add
2066 engravers to every context of a specific type by placing the
2067 commands in the appropriate context in a @code{\layout}
2068 block. For example, if we wanted to show an ambitus for every
2069 staff in a four-staff score we could write
2071 @lilypond[quote,verbatim,ragged-right]
2075 \relative c'' { c a b g }
2078 \relative c' { c a b g }
2082 \relative c' { c a b g }
2086 \relative c { c a b g }
2092 \consists Ambitus_engraver
2099 The values of context properties may also be set
2100 for all contexts of a particular type by including the
2101 @code{\set} command in a @code{\context} block in the
2104 @node Extending the templates
2105 @section Extending the templates
2107 You've read the tutorial, you know how to write music, you
2108 understand the fundamental concepts. But how can you
2109 get the staves that you want? Well, you can find lots of
2110 templates (see @ref{Templates}) which may give you a start.
2112 if you want something that isn't covered there? Read on.
2114 TODO Add links to templates after they have been moved to LSR
2117 * Soprano and cello::
2118 * Four-part SATB vocal score::
2119 * Building a score from scratch::
2122 @node Soprano and cello
2123 @subsection Soprano and cello
2125 @cindex template, modifying
2127 Start off with the template that seems closest to what you want to end
2128 up with. Let's say that you want to write something for soprano and
2129 cello. In this case, we would start with @q{Notes and lyrics} (for the
2133 \version @w{"@version{}"}
2134 melody = \relative c' @{
2141 text = \lyricmode @{
2147 \new Voice = "one" @{
2151 \new Lyrics \lyricsto "one" \text
2158 Now we want to add a cello part. Let's look at the @q{Notes only} example:
2161 \version @w{"@version{}"}
2162 melody = \relative c' @{
2176 We don't need two @code{\version} commands. We'll need the
2177 @code{melody} section. We don't want two @code{\score} sections
2178 -- if we had two @code{\score}s, we'd get the two parts separately.
2179 We want them together, as a duet. Within the @code{\score}
2180 section, we don't need two @code{\layout} or @code{\midi}.
2182 If we simply cut and paste the @code{melody} section, we would
2183 end up with two @code{melody} definitions. This would not generate
2184 an error, but the second one would be used for both melodies.
2185 So let's rename them to make them distinct. We'll call the
2186 section for the soprano @code{sopranoMusic} and the section for
2187 the cello @code{celloMusic}. While we're doing this, let's rename
2188 @code{text} to be @code{sopranoLyrics}. Remember to rename both
2189 instances of all these names -- both the initial definition (the
2190 @code{melody = \relative c' @{ } part) and the name's use (in the
2191 @code{\score} section).
2193 While we're doing this, let's change the cello part's staff --
2194 celli normally use bass clef. We'll also give the cello some
2198 \version @w{"@version{}"}
2199 sopranoMusic = \relative c' @{
2206 sopranoLyrics = \lyricmode @{
2210 celloMusic = \relative c @{
2219 \new Voice = "one" @{
2223 \new Lyrics \lyricsto "one" \sopranoLyrics
2230 This is looking promising, but the cello part won't appear in the
2231 score -- we haven't used it in the @code{\score} section. If we
2232 want the cello part to appear under the soprano part, we need to add
2235 \new Staff \celloMusic
2239 underneath the soprano stuff. We also need to add @code{<<} and
2240 @code{>>} around the music -- that tells LilyPond that there's
2241 more than one thing (in this case, two @code{Staves}) happening
2242 at once. The @code{\score} looks like this now
2244 @c Indentation in this example is deliberately poor
2249 \new Voice = "one" @{
2253 \new Lyrics \lyricsto "one" \sopranoLyrics
2255 \new Staff \celloMusic
2263 This looks a bit messy; the indentation is messed up now. That is
2264 easily fixed. Here's the complete soprano and cello template.
2266 @lilypond[quote,verbatim,ragged-right,addversion]
2267 sopranoMusic = \relative c' {
2274 sopranoLyrics = \lyricmode {
2278 celloMusic = \relative c {
2288 \new Voice = "one" {
2292 \new Lyrics \lyricsto "one" \sopranoLyrics
2294 \new Staff \celloMusic
2302 @node Four-part SATB vocal score
2303 @subsection Four-part SATB vocal score
2305 @cindex template, SATB
2306 @cindex SATB template
2308 Most vocal scores of music written for four-part mixed choir
2309 with orchestral accompaniment such as Mendelssohn's Elijah or
2310 Handel's Messiah have the choral music and words on four
2311 staves, one for each of SATB, with a piano reduction of the
2312 orchestral accompaniment underneath. Here's an example
2313 from Handel's Messiah:
2315 @c The following should appear as music without code
2316 @lilypond[quote,ragged-right]
2317 global = { \key d \major \time 4/4 }
2318 sopMusic = \relative c'' {
2320 r4 d2 a4 | d4. d8 a2 | cis4 d cis2 |
2322 sopWords = \lyricmode {
2323 Wor -- thy is the lamb that was slain
2325 altoMusic = \relative a' {
2327 r4 a2 a4 | fis4. fis8 a2 | g4 fis e2 |
2329 altoWords = \sopWords
2330 tenorMusic = \relative c' {
2332 r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 |
2334 tenorWords = \sopWords
2335 bassMusic = \relative c' {
2337 r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 |
2339 bassWords = \sopWords
2340 upper = \relative a' {
2343 r4 <a d fis>2 <a e' a>4 |
2344 <d fis d'>4. <d fis d'>8 <a d a'>2 |
2345 <g cis g'>4 <a d fis> <a cis e>2 |
2347 lower = \relative c, {
2350 <d d'>4 <d d'>2 <cis cis'>4 |
2351 <b b'>4. <b' b'>8 <fis fis'>2 |
2352 <e e'>4 <d d'> <a' a'>2 |
2356 << % combine ChoirStaff and PianoStaff in parallel
2358 \new Staff = "sopranos" <<
2359 \set Staff.instrumentName = "Soprano"
2360 \new Voice = "sopranos" { \global \sopMusic }
2362 \new Lyrics \lyricsto "sopranos" { \sopWords }
2363 \new Staff = "altos" <<
2364 \set Staff.instrumentName = "Alto"
2365 \new Voice = "altos" { \global \altoMusic }
2367 \new Lyrics \lyricsto "altos" { \altoWords }
2368 \new Staff = "tenors" <<
2369 \set Staff.instrumentName = "Tenor"
2370 \new Voice = "tenors" { \global \tenorMusic }
2372 \new Lyrics \lyricsto "tenors" { \tenorWords }
2373 \new Staff = "basses" <<
2374 \set Staff.instrumentName = "Bass"
2375 \new Voice = "basses" { \global \bassMusic }
2377 \new Lyrics \lyricsto "basses" { \bassWords }
2381 \set PianoStaff.instrumentName = "Piano"
2382 \new Staff = "upper" \upper
2383 \new Staff = "lower" \lower
2389 None of the templates provides this layout exactly. The
2390 nearest is @q{SATB vocal score and automatic piano reduction},
2391 but we need to change the layout and add a piano
2392 accompaniment which is not derived automatically from the
2393 vocal parts. The variables holding the music and words for
2394 the vocal parts are fine, but we shall need to add variables for
2395 the piano reduction.
2397 The order in which the contexts appear in the ChoirStaff of
2398 the template do not correspond with the order in the vocal
2399 score shown above. We need to rearrange them so there are
2400 four staves with the words written directly underneath the
2401 notes for each part.
2402 All the voices should be @code{\voiceOne}, which is
2403 the default, so the @code{\voiceXXX} commands should be removed.
2404 We also need to specify the tenor clef for the tenors.
2405 The way in which lyrics are specified in the template has not yet
2406 been encountered so we need to use the method with which we are
2407 familiar. We should also add the names of each staff.
2409 Doing this gives for our ChoirStaff:
2413 \new Staff = "sopranos" <<
2414 \set Staff.instrumentName = "Soprano"
2415 \new Voice = "sopranos" @{ \global \sopMusic @}
2417 \new Lyrics \lyricsto "sopranos" @{ \sopWords @}
2418 \new Staff = "altos" <<
2419 \set Staff.instrumentName = "Alto"
2420 \new Voice = "altos" @{ \global \altoMusic @}
2422 \new Lyrics \lyricsto "altos" @{ \altoWords @}
2423 \new Staff = "tenors" <<
2424 \set Staff.instrumentName = "Tenor"
2425 \new Voice = "tenors" @{ \global \tenorMusic @}
2427 \new Lyrics \lyricsto "tenors" @{ \tenorWords @}
2428 \new Staff = "basses" <<
2429 \set Staff.instrumentName = "Bass"
2430 \new Voice = "basses" @{ \global \bassMusic @}
2432 \new Lyrics \lyricsto "basses" @{ \bassWords @}
2436 Next we must work out the piano part. This is
2437 easy - we just pull out the piano part from the
2438 @q{Solo piano} template:
2442 \set PianoStaff.instrumentName = "Piano "
2443 \new Staff = "upper" \upper
2444 \new Staff = "lower" \lower
2448 and add the variable definitions for @code{upper}
2451 The ChoirStaff and PianoStaff must be combined
2452 using angle brackets as we want them to be
2453 stacked one above the other:
2456 << % combine ChoirStaff and PianoStaff one above the other
2458 \new Staff = "sopranos" <<
2459 \new Voice = "sopranos" @{ \global \sopMusic @}
2461 \new Lyrics \lyricsto "sopranos" @{ \sopWords @}
2462 \new Staff = "altos" <<
2463 \new Voice = "altos" @{ \global \altoMusic @}
2465 \new Lyrics \lyricsto "altos" @{ \altoWords @}
2466 \new Staff = "tenors" <<
2467 \clef "G_8" % tenor clef
2468 \new Voice = "tenors" @{ \global \tenorMusic @}
2470 \new Lyrics \lyricsto "tenors" @{ \tenorWords @}
2471 \new Staff = "basses" <<
2473 \new Voice = "basses" @{ \global \bassMusic @}
2475 \new Lyrics \lyricsto "basses" @{ \bassWords @}
2479 \set PianoStaff.instrumentName = "Piano"
2480 \new Staff = "upper" \upper
2481 \new Staff = "lower" \lower
2486 Combining all these together and adding the music
2487 for the three bars of the example above gives:
2489 @lilypond[quote,verbatim,ragged-right,addversion]
2490 global = { \key d \major \time 4/4 }
2491 sopMusic = \relative c'' {
2493 r4 d2 a4 | d4. d8 a2 | cis4 d cis2 |
2495 sopWords = \lyricmode {
2496 Wor -- thy is the lamb that was slain
2498 altoMusic = \relative a' {
2500 r4 a2 a4 | fis4. fis8 a2 | g4 fis fis2 |
2502 altoWords = \sopWords
2503 tenorMusic = \relative c' {
2505 r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 |
2507 tenorWords = \sopWords
2508 bassMusic = \relative c' {
2510 r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 |
2512 bassWords = \sopWords
2513 upper = \relative a' {
2516 r4 <a d fis>2 <a e' a>4 |
2517 <d fis d'>4. <d fis d'>8 <a d a'>2 |
2518 <g cis g'>4 <a d fis> <a cis e>2 |
2520 lower = \relative c, {
2523 <d d'>4 <d d'>2 <cis cis'>4 |
2524 <b b'>4. <b' b'>8 <fis fis'>2 |
2525 <e e'>4 <d d'> <a' a'>2 |
2529 << % combine ChoirStaff and PianoStaff in parallel
2531 \new Staff = "sopranos" <<
2532 \set Staff.instrumentName = "Soprano"
2533 \new Voice = "sopranos" { \global \sopMusic }
2535 \new Lyrics \lyricsto "sopranos" { \sopWords }
2536 \new Staff = "altos" <<
2537 \set Staff.instrumentName = "Alto"
2538 \new Voice = "altos" { \global \altoMusic }
2540 \new Lyrics \lyricsto "altos" { \altoWords }
2541 \new Staff = "tenors" <<
2542 \set Staff.instrumentName = "Tenor"
2543 \new Voice = "tenors" { \global \tenorMusic }
2545 \new Lyrics \lyricsto "tenors" { \tenorWords }
2546 \new Staff = "basses" <<
2547 \set Staff.instrumentName = "Bass"
2548 \new Voice = "basses" { \global \bassMusic }
2550 \new Lyrics \lyricsto "basses" { \bassWords }
2554 \set PianoStaff.instrumentName = "Piano "
2555 \new Staff = "upper" \upper
2556 \new Staff = "lower" \lower
2563 @node Building a score from scratch
2564 @subsection Building a score from scratch
2566 @cindex template, writing your own
2568 After gaining some facility with writing LilyPond code you
2569 may find that it is easier to build a score from scratch
2570 rather than modifying one of the templates. You can also
2571 develop your own style this way to suit the sort of music you
2572 like. Let's see how to put together the score for an organ
2573 prelude as an example.
2575 We begin with a header section. Here go the title, name
2576 of composer, etc, then come any variable definitions, and
2577 finally the score block. Let's start with these in outline
2578 and fill in the details later.
2580 We'll use the first two bars of Bach's prelude
2581 based on @emph{Jesu, meine Freude} which is written for two
2582 manuals and pedal organ. You can see these two bars of music
2583 at the bottom of this section. The top manual part has two voices,
2584 the lower and pedal organ one each. So we need four
2585 music definitions and one to define the time signature
2589 \version @w{"@version{}"}
2591 title = "Jesu, meine Freude"
2592 composer = "J S Bach"
2594 TimeKey = @{ \time 4/4 \key c \minor @}
2595 ManualOneVoiceOneMusic = @{s1@}
2596 ManualOneVoiceTwoMusic = @{s1@}
2597 ManualTwoMusic = @{s1@}
2598 PedalOrganMusic = @{s1@}
2604 For now we've just used a spacer note, @code{s1},
2605 instead of the real music. We'll add that later.
2607 Next let's see what should go in the score block.
2608 We simply mirror the staff structure we want.
2609 Organ music is usually written on three staves,
2610 one for each manual and one for the pedals. The
2611 manual staves should be bracketed together so we
2612 need to use a PianoStaff for them. The first
2613 manual part needs two voices and the second manual
2618 \new Staff = "ManualOne" <<
2619 \new Voice @{ \ManualOneVoiceOneMusic @}
2620 \new Voice @{ \ManualOneVoiceTwoMusic @}
2621 >> % end ManualOne Staff context
2622 \new Staff = "ManualTwo" <<
2623 \new Voice @{ \ManualTwoMusic @}
2624 >> % end ManualTwo Staff context
2625 >> % end PianoStaff context
2628 Next we need to add a staff for the pedal organ.
2629 This goes underneath the PianoStaff, but it must
2630 be simultaneous with it, so we need angle brackets
2631 around the two. Missing these out would generate
2632 an error in the log file. It's a common mistake
2633 which you'll make sooner or later! Try copying
2634 the final example at the end of this section,
2635 remove these angle brackets, and compile it to
2636 see what errors it generates.
2639 << % PianoStaff and Pedal Staff must be simultaneous
2641 \new Staff = "ManualOne" <<
2642 \new Voice @{ \ManualOneVoiceOneMusic @}
2643 \new Voice @{ \ManualOneVoiceTwoMusic @}
2644 >> % end ManualOne Staff context
2645 \new Staff = "ManualTwo" <<
2646 \new Voice @{ \ManualTwoMusic @}
2647 >> % end ManualTwo Staff context
2648 >> % end PianoStaff context
2649 \new Staff = "PedalOrgan" <<
2650 \new Voice @{ \PedalOrganMusic @}
2655 It is not strictly necessary to use the simultaneous construct
2656 @code{<< .. >>} for the manual two staff and the pedal organ staff,
2657 since they contain only one music expression, but it does no harm
2658 and always using angle brackets after @code{\new Staff} is a good
2659 habit to cultivate in case there are multiple voices. The opposite
2660 is true for Voices: these should habitually be followed by braces
2661 @code{@{ .. @}} in case your music is coded in several variables
2662 which need to run consecutively.
2664 Let's add this structure to the score block, and adjust the
2665 indenting. We also add the appropriate clefs, ensure the
2666 second voice stems point down with @code{\voiceTwo} and
2667 enter the time signature and key to each staff using our
2668 predefined variable, @code{\TimeKey}.
2672 << % PianoStaff and Pedal Staff must be simultaneous
2674 \new Staff = "ManualOne" <<
2675 \TimeKey % set time signature and key
2677 \new Voice @{ \ManualOneVoiceOneMusic @}
2678 \new Voice @{ \voiceTwo \ManualOneVoiceTwoMusic @}
2679 >> % end ManualOne Staff context
2680 \new Staff = "ManualTwo" <<
2683 \new Voice @{ \ManualTwoMusic @}
2684 >> % end ManualTwo Staff context
2685 >> % end PianoStaff context
2686 \new Staff = "PedalOrgan" <<
2689 \new Voice @{ \PedalOrganMusic @}
2690 >> % end PedalOrgan Staff
2692 @} % end Score context
2695 That completes the structure. Any three-staff organ music
2696 will have a similar structure, although the number of voices
2697 may vary. All that remains now
2698 is to add the music, and combine all the parts together.
2700 @lilypond[quote,verbatim,ragged-right,addversion]
2702 title = "Jesu, meine Freude"
2703 composer = "J S Bach"
2705 TimeKey = { \time 4/4 \key c \minor }
2706 ManualOneVoiceOneMusic = \relative g' {
2707 g4 g f ees | d2 c2 |
2709 ManualOneVoiceTwoMusic = \relative c' {
2710 ees16 d ees8~ ees16 f ees d c8 d~ d c~ |
2711 c c4 b8 c8. g16 c b c d |
2713 ManualTwoMusic = \relative c' {
2714 c16 b c8~ c16 b c g a8 g~ g16 g aes ees |
2715 f ees f d g aes g f ees d e8~ ees16 f ees d |
2717 PedalOrganMusic = \relative c {
2718 r8 c16 d ees d ees8~ ees16 a, b g c b c8 |
2719 r16 g ees f g f g8 c,2 |
2723 << % PianoStaff and Pedal Staff must be simultaneous
2725 \new Staff = "ManualOne" <<
2726 \TimeKey % set time signature and key
2728 \new Voice { \ManualOneVoiceOneMusic }
2729 \new Voice { \voiceTwo \ManualOneVoiceTwoMusic }
2730 >> % end ManualOne Staff context
2731 \new Staff = "ManualTwo" <<
2734 \new Voice { \ManualTwoMusic }
2735 >> % end ManualTwo Staff context
2736 >> % end PianoStaff context
2737 \new Staff = "PedalOrgan" <<
2740 \new Voice { \PedalOrganMusic }
2741 >> % end PedalOrgan Staff
2743 } % end Score context