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
48 A basic example of a LilyPond input file is
51 \version @w{"@version{}"}
53 @var{...compound music expression...} % all the music goes here!
61 There are many variations of this basic pattern, but this
62 example serves as a useful starting place.
64 Up to this point none of the examples you have seen has used a
65 @code{\score@{@}} command. This is because LilyPond automatically
66 adds the extra commands which are needed when you give it simple
67 input. LilyPond treats input like this:
76 as shorthand for this:
93 In other words, if the input contains a single music expression,
94 LilyPond will interpret the file as though the music expression
95 was wrapped up inside the commands shown above.
97 @strong{A word of warning!} Many of the examples in the LilyPond
98 documentation will omit the @code{\new Staff} and @code{\new Voice}
99 commands, leaving them to be created implicitly. For simple
100 examples this works well, but for more complex examples, especially
101 when additional commands are used, the implicit creation of contexts
102 can give surprising results, maybe creating extra unwanted staves.
103 When entering more than a few lines of music it is advisable to
104 always create staves and voices explicitly, see
105 @ref{Contexts and engravers}.
107 For now, though, let us return to the first example and examine the
108 @code{\score} command, leaving the others to default.
110 A @code{\score} block must always contain just one music expression,
111 and this must appear immediately after the @code{\score} command.
112 Remember that a music expression could be anything from a single
113 note to a huge compound expression like
118 @var{...insert the whole score of a Wagner opera in here...}
124 Since everything is inside @code{@{ ... @}}, it counts
125 as one music expression.
127 As we saw previously, the @code{\score} block can contain other
140 Note that these three commands -- @code{\header}, @code{\layout}
141 and @code{\midi} -- are special: unlike all other commands which
142 begin with a backward slash (@code{\}) they are @emph{not} music
143 expressions and are not part of any music expression.
144 So they may be placed inside a @code{\score} block
145 or outside it. In fact, these commands are commonly placed
146 outside the @code{\score} block -- for example, @code{\header}
147 is often placed above the @code{\score} command because headers
148 naturally appear at the top of a score. That's just another
149 shorthand that LilyPond accepts.
151 Two more commands you have not previously seen are
152 @code{\layout @{ @}} and @code{\midi @{@}}. If these appear as
153 shown they will cause LilyPond to produce a printed output and a
154 MIDI output respectively. They are described fully in the
155 Notation Reference -- @ruser{Score layout} and
156 @ruser{Creating MIDI files}.
158 You may code multiple @code{\score} blocks. Each will be
159 treated as a separate score, but they will be all combined into
160 a single output file. A @code{\book} command is not necessary
161 -- one will be implicitly created. However, if you would like
162 separate output files from one @code{.ly} file then the
163 @code{\book} command should be used to separate the different
164 sections: each @code{\book} block will produce a
165 separate output file.
169 Every @code{\book} block creates a separate output file (e.g., a
170 pdf file). If you haven't explicitly added one, LilyPond wraps
171 your entire input code in a @code{\book} block implicitly.
173 Every @code{\score} block is a separate chunk of music within a
176 Every @code{\layout} block affects the @code{\score} or
177 @code{\book} block in which it appears -- i.e., a @code{\layout}
178 block inside a @code{\score} block affects only that @code{\score}
179 block, but a @code{\layout} block outside of a @code{\score} block
180 (and thus in a @code{\book} block, either explicitly or
181 implicitly) will affect every @code{\score} in that @code{\book}.
183 Every @code{\context} block will affect the named context (e.g.,
184 @code{\StaffGroup}) throughout the block (@code{\score} or
185 @code{\book}) in which it appears.
187 For details see @ruser{Multiple scores in a book}.
191 Another great shorthand is the ability to define variables. All
192 the templates use this
195 melody = \relative c' @{
204 When LilyPond looks at this file, it takes the value of
205 @code{melody} (everything after the equals sign) and inserts it
206 whenever it sees @code{\melody}. There's nothing special about
207 the names -- it could be @code{melody}, @code{global},
209 @code{pianorighthand}, or @code{foofoobarbaz}. For more details,
210 see @ref{Saving typing with variables and functions}.
211 Remember that you can use almost any name you like as long
212 as it contains just alphabetic characters and is distinct from
213 LilyPond command names. The exact
214 limitations on variable names are detailed in
215 @ruser{File structure}.
221 For a complete definition of the input format, see
222 @ruser{File structure}.
224 @node Score is a (single) compound musical expression
225 @subsection Score is a (single) compound musical expression
227 @cindex Compound music expression
228 @cindex Music expression, compound
230 We saw the general organization of LilyPond input files in the
231 previous section, @ref{How LilyPond input files work}. But we seemed to
232 skip over the most important part: how do we figure out what to
233 write after @code{\score}?
235 We didn't skip over it at all. The big mystery is simply that
236 there @emph{is} no mystery. This line explains it all:
239 @emph{A @code{\score} block must begin with a compound music expression.}
243 You may find it useful to review
244 @ref{Music expressions explained}. In that section, we saw how to
245 build big music expressions from small pieces -- we started from
246 notes, then chords, etc. Now we're going to start from a big
247 music expression and work our way down.
251 @{ % this brace begins the overall compound music expression
253 @var{...insert the whole score of a Wagner opera in here...}
255 @} % this brace ends the overall compound music expression
260 A whole Wagner opera would easily double the length of this
261 manual, so let's just add a singer and piano. We don't need a
262 @code{GrandStaff} for this ensemble, which simply groups a number
263 of staves together with a brace at the left, so we shall remove
264 it. We @emph{do} need a singer and a piano, though.
269 \new Staff = "singer" <<
271 \new PianoStaff = piano <<
278 Remember that we use @code{<< ... >>} instead of
279 @code{@{ ... @}} to show simultaneous
280 music. And we definitely want to show the vocal part and piano
281 part at the same time, not one after the other! However, the
282 @code{<< ... >>} construct is not really necessary for the Singer
283 staff, as it contains only one music expression, but Staves often
284 do require simultaneous Voices within them, so using
286 rather than braces is a good habit to adopt. We'll add some real
287 music later; for now let's just put in some dummy notes and lyrics.
289 @lilypond[verbatim,quote,ragged-right]
292 \new Staff = "singer" <<
293 \new Voice = "vocal" { c'1 }
296 \new PianoStaff = "piano" <<
297 \new Staff = "upper" { c'1 }
298 \new Staff = "lower" { c'1 }
305 Now we have a lot more details. We have the singer's staff: it
306 contains a @code{Voice} (in LilyPond, this term refers to a set of
307 notes, not necessarily vocal notes -- for example, a violin
308 generally plays one voice) and some lyrics. We also have a piano
309 staff: it contains an upper staff (right hand) and a lower staff
312 At this stage, we could start filling in notes. Inside the curly
313 braces next to @code{\new Voice = vocal}, we could start writing
321 But if we did that, the @code{\score} section would get pretty
322 long, and it would be harder to understand what was happening. So
323 let's use variables instead. These were introduced at the end
324 of the previous section, remember? So, adding a few notes, we
325 now have a piece of real music:
327 @lilypond[verbatim,quote,ragged-right]
328 melody = \relative c'' { r4 d8\noBeam g, c4 r }
329 text = \lyricmode { And God said, }
330 upper = \relative c'' { <g d g,>2~ <g d g,> }
331 lower = \relative c { b2 e2 }
335 \new Staff = "singer" <<
336 \new Voice = "vocal" { \melody }
339 \new PianoStaff = "piano" <<
340 \new Staff = "upper" { \upper }
341 \new Staff = "lower" {
352 Be careful about the difference between notes, which are introduced
353 with @code{\relative}, and lyrics, which are introduced with
354 @code{\lyricmode}. These are essential to tell LilyPond
355 to interpret the following content as music and text
358 When writing (or reading) a @code{\score} section, just take it
359 slowly and carefully. Start with the outer layer, then work on
360 each smaller layer. It also really helps to be strict with
361 indentation -- make sure that each item on the same layer starts
362 on the same horizontal position in your text editor.
365 @node Nesting music expressions
366 @subsection Nesting music expressions
368 It is not essential to declare all staves at the beginning;
369 they may be introduced temporarily at any point. This is
370 particularly useful for creating ossia sections
371 (see @rglos{ossia}). Here is a simple example showing how
372 to introduce a new staff temporarily for the duration of
375 @lilypond[verbatim,quote,ragged-right]
392 Note that the size of the clef is the same as a clef printed
393 following a clef change -- slightly smaller than the clef
394 at the beginning of the line. This is usual for clefs printed
395 in the middle of a line.
397 The ossia section may be placed above the staff
400 @lilypond[verbatim,quote,ragged-right]
408 alignAboveContext = "main" }
416 This example uses @code{\with}, which will be explained more
417 fully later. It is a means of modifying the default behavior
418 of a single Staff. Here it says that the new staff should be
419 placed above the staff called @qq{main} instead of the default
420 position which is below.
422 Ossia are often written without clef and without
423 time signature and are usually in a smaller font.
424 These require further commands which
425 have not yet been introduced. See @ref{Size of objects}
427 @node On the un-nestedness of brackets and ties
428 @subsection On the un-nestedness of brackets and ties
430 You have already met a number of different types of bracket in
431 writing the input file to LilyPond. These obey different rules
432 which can be confusing at first. Before we explain the rules
433 let's first review the different types of bracket.
435 @c attempt to force this onto a new page
437 @multitable @columnfractions .3 .7
438 @headitem Bracket Type
440 @item @code{@{ .. @}}
441 @tab Encloses a sequential segment of music
443 @tab Encloses the notes of a chord
444 @item @code{<< .. >>}
445 @tab Encloses concurrent or simultaneous sections
447 @tab Marks the start and end of a slur
448 @item @code{\( .. \)}
449 @tab Marks the start and end of a phrase mark
451 @tab Marks the start and end of a manual beam
454 To these we should add other constructs which generate lines
455 between or across notes: ties (marked by a tilde, @code{~}),
456 tuplets written as @code{\times x/y @{..@}}, and grace notes
457 written as @code{\grace@{..@}}.
459 Outside LilyPond, the conventional use of brackets requires
460 the different types to be properly nested, like this,
461 @code{<< [ @{ ( .. ) @} ] >>}, with the closing brackets being
462 encountered in exactly the opposite order to the opening
463 brackets. This @strong{is} a requirement for the three types of
464 bracket described by the word @q{Encloses} in the table above --
465 they must nest properly.
466 However, the remaining brackets, described with the word
467 @q{Marks} in the table above together with ties and tuplets,
468 do @strong{not} have to nest
469 properly with any of the brackets. In fact, these are not
470 brackets in the sense that
471 they enclose something -- they are simply markers to indicate
472 where something starts and ends.
474 So, for example, a phrasing slur can start before a manually
475 inserted beam and end before the end of the beam -- not very
476 musical, perhaps, but possible:
478 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
479 { g8\( a b[ c b\) a] }
482 In general, different kinds of brackets, and those implied by
483 tuplets, ties and grace notes, may be mixed freely.
484 This example shows a beam extending into a tuplet (line 1),
485 a slur extending into a tuplet (line 2),
486 a beam and a slur extending into a tuplet, a tie crossing
487 two tuplets, and a phrasing slur extending out of a tuplet
490 @lilypond[quote,verbatim,fragment,ragged-right]
492 r16[ g16 \times 2/3 {r16 e'8] }
493 g16( a \times 2/3 {b d) e' }
494 g8[( a \times 2/3 {b d') e'~]}
495 \times 4/5 {e'32\( a b d' e'} a'4.\)
500 @node Voices contain music
501 @section Voices contain music
503 Singers need voices to sing, and so does LilyPond.
504 The actual music for all instruments in a score
505 is contained in Voices -- the most fundamental
506 of all LilyPond's concepts.
509 * I'm hearing Voices::
510 * Explicitly instantiating voices::
511 * Voices and vocals::
514 @node I'm hearing Voices
515 @subsection I'm hearing Voices
519 @cindex Voice context
521 The lowest, most fundamental or innermost layers in a LilyPond
522 score are called @q{Voice contexts} or just @q{Voices} for short.
523 Voices are sometimes called @q{layers} in other notation
526 In fact, a Voice layer or context is the only one which can
527 contain music. If a Voice context is not explicitly declared
528 one is created automatically, as we saw at the beginning of
529 this chapter. Some instruments such as an
530 Oboe can play only one note at a time. Music written for
531 such instruments is monophonic and requires just a single
532 voice. Instruments which can play more than one note at a
533 time like the piano will often require multiple voices to
534 encode the different concurrent notes and rhythms they are
537 A single voice can contain many notes in a chord, of course,
538 so when exactly are multiple voices needed? Look first at
539 this example of four chords:
541 @lilypond[quote,verbatim,fragment,ragged-right,relative=1]
543 <d g>4 <d fis> <d a'> <d g>
546 This can be expressed using just the single angle bracket chord
547 symbols, @code{< ... >}, and for this just a single voice is
548 needed. But suppose the F-sharp were actually an eighth-note
549 followed by an eighth-note G, a passing note on the way to the A?
550 Now we have two notes which start at the same time but have
551 different durations: the quarter-note D and the eighth-note
552 F-sharp. How are these to be coded? They cannot be written as
553 a chord because all the notes in a chord must have the same
554 duration. And they cannot be written as two separate notes
555 as they need to start at the same time. This is when two
558 Let us see how this is done in LilyPond input syntax.
563 The easiest way to enter fragments with more than one voice on a
564 staff is to enter each voice as a sequence (with @code{@{...@}}),
565 and combine them simultaneously with angle brackets, @code{<<...>>}.
566 The fragments must also be separated with double backward slashes,
567 @code{\\}, to place them in separate voices. Without these, the
568 notes would be entered into a single voice, which would usually
569 cause errors. This technique is particularly suited to pieces of
570 music which are largely monophonic with occasional short sections
573 Here's how we split the chords above into two voices and add both
574 the passing note and a slur:
576 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
578 % Voice "1" Voice "2"
579 << { g4 fis8( g) a4 g } \\ { d4 d d d } >> |
582 Notice how the stems of the second voice now point down.
584 Here's another simple example:
586 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
588 % Voice "1" Voice "2"
589 << { r4 g g4. a8 } \\ { d,2 d4 g } >> |
590 << { bes4 bes c bes } \\ { g4 g g8( a) g4 } >> |
591 << { a2. r4 } \\ { fis2. s4 } >> |
594 It is not necessary to use a separate @code{<< \\ >>} construct
595 for each bar. For music with few notes in each bar this layout
596 can help the legibility of the code, but if there are many
597 notes in each bar it may be better to split out each voice
598 separately, like this:
600 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
616 This example has just two voices, but the same construct may be
617 used to encode three or more voices by adding more back-slash
620 The Voice contexts bear the names @code{"1"}, @code{"2"}, etc.
621 In each of these contexts, the vertical direction of slurs,
622 stems, ties, dynamics etc., is set appropriately.
624 @lilypond[quote,verbatim,fragment]
625 \new Staff \relative c' {
628 % Voice "1" Voice "2" Voice "3"
629 << { g4 f e } \\ { r8 e4 d c8 ~ } >> |
630 << { d2 e2 } \\ { c8 b16 a b8 g ~ g2 } \\ { s4 b4 c2 } >> |
634 These voices are all separate from the main voice that contains
635 the notes just outside the @code{<< .. >>} construct. Let's call
636 this the @emph{simultaneous construct}. Slurs and ties may only
637 connect notes within the same voice, so slurs and ties cannot go
638 into or out of a simultaneous construct. Conversely,
639 parallel voices from separate simultaneous constructs on the same
640 staff are the same voice. Other voice-related properties also
641 carry across simultaneous constructs. Here is the same example,
642 with different colors and note heads for each voice. Note that
643 changes in one voice do not affect other voices, but they do
644 persist in the same voice later. Note also that tied notes may be
645 split across the same voices in two constructs, shown here in the
648 @lilypond[quote,verbatim]
649 \new Staff \relative c' {
668 { c8 b16 a b8 g ~ g2 }
678 The commands @code{\voiceXXXStyle} are mainly intended for use in
679 educational documents such as this one. They modify the color
680 of the note head, the stem and the beams, and the style of the
681 note head, so that the voices may be easily distinguished.
682 Voice one is set to red diamonds, voice two to blue triangles,
683 voice three to green crossed circles, and voice four (not used
684 here) to magenta crosses. We shall see later how commands like
685 these may be created by the user.
686 See @ref{Visibility and color of objects}
687 TODO Add link to using variables for tweaks
689 Polyphony does not change the relationship of notes within a
690 @code{\relative @{ @}} block. Each note is still calculated
691 relative to the note immediately preceding it, or to the first
692 note of the preceding chord. So in
695 \relative c' @{ noteA << < noteB noteC > \\ noteD >> noteE @}
699 @code{noteB} is relative to @code{noteA} @*
700 @code{noteC} is relative to @code{noteB}, not @code{noteA}; @*
701 @code{noteD} is relative to @code{noteB}, not @code{noteA} or
703 @code{noteE} is relative to @code{noteD}, not @code{noteA}
705 An alternative way, which may be clearer if the notes in the
706 voices are widely separated, is to place a @code{\relative}
707 command at the start of each voice:
710 \relative c' @{ noteA ... @}
712 \relative c'' @{ < noteB noteC > ... @}
714 \relative g' @{ noteD ... @}
716 \relative c' @{ noteE ... @}
719 Let us finally analyze the voices in a more complex piece of
721 the notes from the first two bars of the second of Chopin's
722 Deux Nocturnes, Op 32. This example will be used at later
723 stages in this and the next chapter to illustrate several
724 techniques for producing notation, so please ignore for now
725 anything in the underlying code which looks mysterious and
726 concentrate just on the music and the voices -- the
727 complications will all be explained in later sections.
729 @c The following should appear as music without code
730 @lilypond[quote,ragged-right]
731 \new Staff \relative c'' {
740 % Ignore these for now - they are explained in Ch 4
741 \once \override NoteColumn #'force-hshift = #0
743 \once \override NoteColumn #'force-hshift = #0.5
751 The direction of the stems is often used to indicate the
752 continuity of two simultaneous melodic lines. Here the
753 stems of the highest notes are all pointing up and the
754 stems of the lower notes are all pointing down.
755 This is the first indication that more than one voice
758 But the real need for multiple voices arises when notes
759 which start at the same time have different durations.
760 Look at the notes which start at beat three in the first
761 bar. The A-flat is a dotted quarter note, the F is a
762 quarter note and the D-flat is a half note. These
763 cannot be written as a chord as all the notes in a chord
764 must have the same duration. Neither can they be written
765 as sequential notes, as they must start at the same time.
766 This section of the bar requires three voices, and the
767 normal practice would be to write the whole bar as three
768 voices, as shown below, where we have used different note heads
769 and colors for the three voices. Again, the code behind this
770 example will be explained later, so ignore anything you do
773 @c The following should appear as music without code
774 @c The three voice styles should be defined in -init
775 @lilypond[quote,ragged-right]
776 \new Staff \relative c'' {
787 \\ % No Voice three (we want stems down)
790 % Ignore these for now - they are explained in Ch 4
791 \once \override NoteColumn #'force-hshift = #0
793 \once \override NoteColumn #'force-hshift = #0.5
802 Let us try to encode this music from scratch. As we
803 shall see, this encounters some difficulties. We begin as
804 we have learnt, using the @code{<< \\ >>} construct to
805 enter the music of the first bar in three voices:
807 @lilypond[quote,verbatim,fragment,ragged-right]
808 \new Staff \relative c'' {
811 { c2 aes4. bes8 } \\ { aes2 f4 fes } \\ { <ees c>2 des2 }
820 The stem directions are automatically assigned with the
821 odd-numbered voices taking upward stems and the even-numbered
822 voices downward ones. The stems for voices 1 and 2 are right,
823 but the stems in voice 3 should go down in this particular piece
824 of music. We can correct this simply by missing out voice three
825 and placing the music in voice four:
827 @lilypond[quote,verbatim,fragment,ragged-right]
828 \new Staff \relative c'' {
834 \\ % Omit Voice three
843 We see that this fixes the stem direction, but exposes a
844 problem sometimes encountered with multiple voices -- the
845 stems of the notes in one voice can collide with the note heads
846 in other voices. In laying out the notes, LilyPond allows the
847 notes or chords from two voices to occupy the same vertical
848 note column provided the stems are in opposite directions, but
849 the notes from the third and fourth voices are displaced to if
850 necessary to avoid the note heads
851 colliding. This usually works well, but in this example the
852 notes of the lowest voice are clearly not well placed by default.
853 LilyPond provides several ways to adjust the horizontal placing
854 of notes. We are not quite ready yet to see how to correct this,
855 so we shall leave this problem until a later section
856 (see the force-hshift property in @ref{Fixing overlapping
859 @node Explicitly instantiating voices
860 @subsection Explicitly instantiating voices
864 @funindex \voiceThree
867 Voice contexts can also be created manually
868 inside a @code{<< >>} block to create polyphonic music, using
869 @code{\voiceOne} ... @code{\voiceFour} to indicate the required
870 directions of stems, slurs, etc. In longer scores this method
871 is clearer, as it permits the voices to be separated and to be
872 given more descriptive names.
874 Specifically, the construct @code{<< \\ >>} which we used in
875 the previous section:
880 << @{ e4 f g a @} \\ @{ c,4 d e f @} >>
890 \new Voice = "1" @{ \voiceOne \relative c' @{ e4 f g a @} @}
891 \new Voice = "2" @{ \voiceTwo \relative c' @{ c4 d e f @} @}
895 Both of the above would produce
897 @c The following example should not display the code
898 @lilypond[ragged-right,quote]
900 \new Voice = "1" { \voiceOne \relative c' { e4 f g a } }
901 \new Voice = "2" { \voiceTwo \relative c' { c4 d e f } }
905 The @code{\voiceXXX} commands set the direction of stems, slurs,
906 ties, articulations, text annotations, augmentation dots of dotted
907 notes, and fingerings. @code{\voiceOne} and @code{\voiceThree}
908 make these objects point upwards, while @code{\voiceTwo} and
909 @code{\voiceFour} make them point downwards. These commands also
910 generate a horizontal shift for each voice when this is required
911 to avoid clashes of note heads. The command @code{\oneVoice}
912 reverts the settings back to the normal values for a single voice.
914 Let us see in some simple examples exactly what effect
915 @code{\oneVoice}, @code{\voiceOne} and @code{voiceTwo} have on
916 markup, ties, slurs, and dynamics:
918 @lilypond[quote,ragged-right,verbatim]
920 % Default behavior or behavior after \oneVoice
921 c d8 ~ d e4 ( f g a ) b-> c
925 @lilypond[quote,ragged-right,verbatim]
928 c d8 ~ d e4 ( f g a ) b-> c
930 c, d8 ~ d e4 ( f g a ) b-> c
934 @lilypond[quote,ragged-right,verbatim]
937 c d8 ~ d e4 ( f g a ) b-> c
939 c, d8 ~ d e4 ( f g a ) b-> c
943 An expression that appears directly inside a @code{<< >>} belongs
944 to the main voice (but, note, @strong{not} in a @code{<< \\ >>}
945 construct). This is useful when extra voices appear while the
946 main voice is playing. Here is a more correct rendition of the
947 example from the previous section. The red diamond-shaped notes
948 demonstrate that the main melody is now in a single voice context,
949 permitting a phrasing slur to be drawn over them.
951 @lilypond[quote,ragged-right,verbatim]
952 \new Staff \relative c' {
954 % The following notes are monophonic
956 % Start simultaneous section of three voices
958 % Continue the main voice in parallel
960 % Initiate second voice
962 % Set stems, etc, down
964 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2
966 % Initiate third voice
976 @cindex nesting music expressions
977 @cindex nesting simultaneous constructs
979 More deeply nested polyphony constructs are possible, and if a
980 voice appears only briefly this might be a more natural way to
983 @lilypond[quote,ragged-right,verbatim]
984 \new Staff \relative c' {
1004 This method of nesting new voices briefly is useful
1005 when only small sections of the music
1006 are polyphonic, but when the whole staff is largely polyphonic
1007 it can be clearer to use multiple voices throughout, using
1008 spacing notes to step over sections where the voice is silent,
1011 @lilypond[quote,ragged-right,verbatim]
1012 \new Staff \relative c' <<
1013 % Initiate first voice
1016 c16^( d e f g4 f e | d2 e2) |
1018 % Initiate second voice
1020 % set stems, etc down
1022 s4 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2 |
1024 % Initiate third voice
1034 @cindex shift commands
1038 @funindex \shiftOnnn
1040 Closely spaced notes in a chord, or notes occurring at the same
1041 time in different voices, are arranged in two, occasionally more,
1042 columns to prevent the note heads overlapping. These are called
1043 note columns. There are separate columns for each voice, and
1044 the currently specified voice-dependent shift is applied to the
1045 note column if there would otherwise be a collision. This can
1046 be seen in the example above. In bar 2 the C in voice two is
1047 shifted to the right relative to the D in voice one, and in the
1048 final chord the C in voice three is also shifted to the right
1049 relative to the other notes.
1051 The @code{\shiftOn}, @code{\shiftOnn}, @code{\shiftOnnn}, and
1052 @code{\shiftOff} commands specify the degree to which notes and
1053 chords of the voice should be shifted if a collision
1054 would otherwise occur. By default, the outer voices (normally
1055 voices one and two) have @code{\shiftOff} specified, while the
1056 inner voices (three and four) have @code{\shiftOn} specified.
1057 When a shift is applied, Voices one and three are shifted to
1058 the right and voices two and four to the left.
1060 @code{\shiftOnn} and @code{\shiftOnnn} define further shift
1061 levels which may be specified temporarily to resolve collisions
1062 in complex situations -- see @ref{Real music example}.
1064 A note column can contain just one note (or chord) from a voice
1065 with stems up and one note (or chord) from a voice with stems
1066 down. If notes from two voices which have their stems in the
1067 same direction are placed at the same position and both voices
1068 have no shift or the same shift specified, the error message
1069 @qq{Too many clashing note columns} will be produced.
1071 @node Voices and vocals
1072 @subsection Voices and vocals
1074 Vocal music presents a special difficulty: we need to combine two
1075 expressions -- notes and lyrics.
1077 You have already seen the @code{\addlyrics@{@}} command, which
1078 handles simple scores well. However, this technique is
1079 quite limited. For more complex music, you must introduce the
1080 lyrics in a @code{Lyrics} context using @code{\new Lyrics} and
1082 the lyrics to the notes with @code{\lyricsto@{@}}, using the
1083 name assigned to the Voice.
1085 @lilypond[quote,verbatim,fragment]
1087 \new Voice = "one" \relative c'' {
1090 c4 b8. a16 g4. f8 e4 d c2
1092 \new Lyrics \lyricsto "one" {
1093 No more let sins and sor -- rows grow.
1098 Note that the lyrics must be linked to a @code{Voice} context,
1099 @emph{not} a @code{Staff} context. This is a case where it is
1100 necessary to create @code{Staff} and @code{Voice} contexts
1103 The automatic beaming which LilyPond uses by default works well
1104 for instrumental music, but not so well for music with lyrics,
1105 where beaming is either not required at all or is used to indicate
1106 melismata in the lyrics. In the example above we use the command
1107 @code{\autoBeamOff} to turn off the automatic beaming.
1109 Let us reuse the earlier example from Judas Maccabæus to
1110 illustrate this more flexible technique. We first recast
1111 it to use variables so the music and lyrics can be separated
1112 from the staff structure. We also introduce a ChoirStaff
1113 bracket. The lyrics themselves must be introduced with
1114 @code{\lyricmode} to ensure they are interpreted as lyrics
1117 @lilypond[quote,verbatim]
1118 global = { \time 6/8 \partial 8 \key f \major}
1119 SopOneMusic = \relative c'' {
1120 c8 | c([ bes)] a a([ g)] f | f'4. b, | c4.~ c4 }
1121 SopTwoMusic = \relative c' {
1122 r8 | r4. r4 c8 | a'([ g)] f f([ e)] d | e([ d)] c bes' }
1123 SopOneLyrics = \lyricmode {
1124 Let | flee -- cy flocks the | hills a -- dorn, __ }
1125 SopTwoLyrics = \lyricmode {
1126 Let | flee -- cy flocks the | hills a -- dorn, }
1131 \new Voice = "SopOne" {
1135 \new Lyrics \lyricsto "SopOne" {
1140 \new Voice = "SopTwo" {
1144 \new Lyrics \lyricsto "SopTwo" {
1152 This is the basic structure of all vocal scores. More staves may
1153 be added as required, more voices may be added to the staves,
1154 more verses may be added to the lyrics,
1155 and the variables containing the music can easily be placed
1156 in separate files should they become too long.
1158 Here is a example of the first line of a hymn with four
1159 verses, set for SATB. In this case the words for all four
1162 @lilypond[quote,verbatim]
1163 TimeKey = { \time 4/4 \partial 4 \key c \major}
1164 SopMusic = \relative c' { c4 | e4. e8 g4 g | a a g }
1165 AltoMusic = \relative c' { c4 | c4. c8 e4 e | f f e }
1166 TenorMusic = \relative c { e4 | g4. g8 c4. b8 | a8 b c d e4 }
1167 BassMusic = \relative c { c4 | c4. c8 c4 c | f8 g a b c4 }
1168 VerseOne = \lyricmode {
1169 E -- | ter -- nal fa -- ther, | strong to save, }
1170 VerseTwo = \lyricmode {
1171 O | Christ, whose voice the | wa -- ters heard, }
1172 VerseThree = \lyricmode {
1173 O | Ho -- ly Spi -- rit, | who didst brood }
1174 VerseFour = \lyricmode {
1175 O | Tri -- ni -- ty of | love and pow'r }
1181 \new Voice = "Sop" { \voiceOne \TimeKey \SopMusic }
1182 \new Voice = "Alto" { \voiceTwo \AltoMusic }
1183 \new Lyrics \lyricsto "Sop" { \VerseOne }
1184 \new Lyrics \lyricsto "Sop" { \VerseTwo }
1185 \new Lyrics \lyricsto "Sop" { \VerseThree }
1186 \new Lyrics \lyricsto "Sop" { \VerseFour }
1190 \new Voice = "Tenor" { \voiceOne \TimeKey \TenorMusic }
1191 \new Voice = "Bass" { \voiceTwo \BassMusic }
1197 We end with an example to show how we might code a solo verse which
1198 continues into a two-part refrain in two staves. The
1199 positioning of the sequential and simultaneous sections to achieve
1200 this within a single score is quite tricky, so follow the
1201 explanation carefully!
1203 Let's start with a score block containing a @code{ChoirStaff}, as
1204 we would like the brace to appear at the start of the chorus.
1205 Normally you would need angle brackets after @code{\new ChoirStaff}
1206 to bring in all the staves in parallel, but here we want to
1207 defer the parallelism during the solo so we use braces, although
1208 angle brackets here wouldn't hurt. Inside the @code{ChoirStaff} we
1209 want first the staff which will contain the verse. This must
1210 contain notes and lyrics in parallel, so here we need angle
1211 brackets around the @code{\new Voice} and @code{\new Lyrics} to
1212 start them at the same time:
1214 @lilypond[quote,verbatim,ragged-right]
1215 versenotes = \relative c'' {
1218 \time 3/4 g g g b b b
1220 versewords = \lyricmode {
1221 One two three four five six
1226 \new Voice = "verse" {
1229 \new Lyrics \lyricsto verse {
1237 That gives the verse line.
1239 Now we want to continue with refrainA on the same staff while a
1240 second staff is introduced in parallel with it for refrainB, so
1241 this is a parallel section which must be positioned immediately
1242 following the @code{\break} in the verse Voice. Yes, @emph{within}
1243 the verse Voice! Here's that parallel section. More staves
1244 could be introduced here in the same way.
1249 \new Lyrics \lyricsto verse @{
1253 \new Voice = "refrainB" @{
1256 \new Lyrics \lyricsto "refrainB" @{
1263 Here's the final result with two staves in the chorus showing
1264 how the parallel section is positioned within the verse Voice:
1266 @lilypond[quote,verbatim, ragged-right]
1267 versenotes = \relative c'' {
1270 \time 3/4 g g g b b b
1272 refrainnotesA = \relative c'' {
1276 refrainnotesB = \relative c {
1281 versewords = \lyricmode {
1282 One two three four five six
1284 refrainwordsA = \lyricmode {
1287 refrainwordsB = \lyricmode {
1293 \context Voice = "verse" {
1297 \new Lyrics \lyricsto "verse" {
1301 \new Voice = "refrainB" {
1304 \new Lyrics \lyricsto "refrainB" {
1310 \new Lyrics \lyricsto "verse" {
1318 @cindex book, example of using
1321 However, although this is an interesting and useful exercise to
1322 help you to understand how sequential and simultaneous blocks work,
1323 in practice one would perhaps choose to code this as two
1324 @code{\score} blocks within an implicit @code{\book} block, as
1327 @lilypond[quote,verbatim,ragged-right]
1328 versenotes = \relative c'' {
1331 \time 3/4 g g g b b b
1333 refrainnotesA = \relative c'' {
1337 refrainnotesB = \relative c {
1342 versewords = \lyricmode {
1343 One two three four five six
1345 refrainwordsA = \lyricmode {
1348 refrainwordsB = \lyricmode {
1353 \new Voice = "verse" {
1356 \new Lyrics \lyricsto "verse" {
1365 \new Voice = "refrainA" {
1368 \new Lyrics \lyricsto "refrainA" {
1373 \new Voice = "refrainB" {
1376 \new Lyrics \lyricsto "refrainB" {
1384 @node Contexts and engravers
1385 @section Contexts and engravers
1387 Contexts and engravers have been mentioned informally
1388 in earlier sections; we now must look at
1389 these concepts in more detail, as they are important
1390 in the fine-tuning of LilyPond output.
1394 * Contexts explained::
1395 * Creating contexts::
1396 * Engravers explained::
1397 * Modifying context properties::
1398 * Adding and removing engravers::
1401 @node Contexts explained
1402 @subsection Contexts explained
1404 When music is printed, many notational elements which do not
1405 appear explicitly in the input file must be added to the
1406 output. For example, compare the input and output of the
1409 @lilypond[quote,verbatim,relative=2,fragment]
1413 The input is rather sparse, but in the output, bar lines,
1414 accidentals, clef, and time signature have been added. When
1415 LilyPond @emph{interprets} the input the musical information
1416 is inspected in time order, similar to reading a score from left
1417 to right. While reading the input, the program remembers where
1418 measure boundaries are, and which pitches require explicit
1419 accidentals. This information must be held on several levels.
1420 For example, the effect of an accidental is limited
1421 to a single staff, while a bar line must be synchronized across
1424 Within LilyPond, these rules and bits of information are grouped
1425 in @emph{Contexts}. We have already met the
1426 @code{Voice} context.
1427 Others are the @code{Staff} and @code{Score} contexts.
1428 Contexts are hierarchical to reflect the hierarchical nature of
1430 For example: a @code{Staff} context can contain many
1431 @code{Voice} contexts, and a @code{Score} context can
1432 contain many @code{Staff} contexts.
1435 @sourceimage{context-example,5cm,,}
1438 Each context has the responsibility for enforcing some notation rules,
1439 creating some notation objects and maintaining the associated
1440 properties. For example, the @code{Voice} context may introduce an
1441 accidental and then the @code{Staff} context maintains the rule to
1442 show or suppress the accidental for the remainder of the measure.
1444 As another example, the synchronization of bar lines is, by default,
1445 handled in the @code{Score} context.
1446 However, in some music we may not want the bar lines to be
1447 synchronized -- consider a polymetric score in 4/4 and 3/4 time.
1448 In such cases, we must modify the default settings of the
1449 @code{Score} and @code{Staff} contexts.
1451 For very simple scores, contexts are created implicitly, and you need
1452 not be aware of them. For larger pieces, such as anything with more
1453 than one staff, they must be
1454 created explicitly to make sure that you get as many staves as you
1455 need, and that they are in the correct order. For typesetting pieces
1456 with specialized notation, it is usual to modify existing, or
1457 even to define totally new, contexts.
1459 In addition to the @code{Score,} @code{Staff} and
1460 @code{Voice} contexts there are contexts which fit between
1461 the score and staff levels to control staff groups, such as the
1462 @code{PianoStaff} and @code{ChoirStaff} contexts. There
1463 are also alternative staff and voice contexts, and contexts for
1464 lyrics, percussion, fret boards, figured bass, etc.
1466 The names of all context types are formed from one or more
1467 words, each word being capitalized and joined immediately to the
1468 preceding word with no hyphen or underscore, e.g.,
1469 @code{GregorianTranscriptionStaff}.
1471 @node Creating contexts
1472 @subsection Creating contexts
1474 There can be only one top level context: the
1476 context. This is created with the @code{\score} command,
1477 or, in simple scores, it is created automatically.
1479 For scores with only one voice and one staff, the
1480 @code{Voice} and @code{Staff} contexts may be left to be
1481 created automatically, but for more complex scores it is
1482 necessary to create them by hand.
1483 The simplest command that does this is @code{\new}.
1484 It is prepended to a music expression, for example
1487 @cindex new contexts
1488 @cindex Context, creating
1491 \new @var{type} @var{music-expression}
1495 where @var{type} is a context name (like @code{Staff} or
1496 @code{Voice}). This command creates a new context, and starts
1497 interpreting the @var{music-expression} within that context.
1499 Note that there is no @code{\new Score} command;
1500 the single top-level @code{Score} context is introduced
1503 The @code{\new} command may also give a identifying name to the
1504 context to distinguish it from other contexts of the same type,
1507 \new @var{type} = @var{id} @var{music-expression}
1510 Note the distinction between the name of the context type,
1511 @code{Staff}, @code{Voice}, etc, and
1512 the identifying name of a particular instance of that type,
1513 which can be any sequence of letters invented by the user.
1514 The identifying name is used to refer back to that particular
1515 instance of a context. We saw this in use in the section on
1516 lyrics in @ref{Voices and vocals}.
1519 @node Engravers explained
1520 @subsection Engravers explained
1524 Every mark on the printed output of a score produced by LilyPond
1525 is produced by an @code{Engraver}. Thus there is an engraver
1526 to print staves, one to print note heads, one for stems, one for
1527 beams, etc, etc. In total there are over 120 such engravers!
1528 Fortunately, for most scores it is not necessary to know about
1529 more than a few, and for simple scores you do not need to know
1532 Engravers live and operate in Contexts.
1533 Engravers such as the @code{Metronome_mark_engraver}, whose
1534 action and output applies to the score as a whole, operate in
1535 the highest level context -- the @code{Score} context.
1537 The @code{Clef_engraver} and @code{Key_engraver} are to be
1538 found in every Staff Context, as different staves may require
1539 different clefs and keys.
1541 The @code{Note_heads_engraver} and @code{Stem_engraver} live
1542 in every @code{Voice} context, the lowest level context of all.
1544 Each engraver processes the particular objects associated
1545 with its function, and maintains the properties that relate
1546 to that function. These properties, like the properties
1547 associated with contexts, may be modified to change the
1548 operation of the engraver or the appearance of those elements
1549 in the printed score.
1551 Engravers all have compound names formed from words which
1552 describe their function. Just the first word is capitalized,
1553 and the remainder are joined to it with underscores. Thus
1554 the @code{Staff_symbol_engraver} is responsible for creating the
1555 lines of the staff, the @code{Clef_engraver} determines and sets
1556 the pitch reference point on the staff by drawing a clef symbol.
1558 Here are some of the most common engravers together with their
1559 function. You will see it is easy to guess the function from
1560 the name, or vice versa.
1562 @multitable @columnfractions .3 .7
1565 @item Accidental_engraver
1566 @tab Makes accidentals, cautionary and suggested accidentals
1571 @item Completion_heads_engraver
1572 @tab Splits notes which cross bar lines
1573 @item Dynamic_engraver
1574 @tab Creates hairpins and dynamic texts
1575 @item Forbid_line_break_engraver
1576 @tab Prevents line breaks if a musical element is still active
1578 @tab Creates the key signature
1579 @item Metronome_mark_engraver
1580 @tab Engraves metronome marking
1581 @item Note_heads_engraver
1582 @tab Engraves note heads
1585 @item Staff_symbol_engraver
1586 @tab Engraves the five (by default) lines of the staff
1588 @tab Creates stems and single-stem tremolos
1589 @item Time_signature_engraver
1590 @tab Creates time signatures
1595 We shall see later how the output of LilyPond can be changed
1596 by modifying the action of Engravers.
1599 @node Modifying context properties
1600 @subsection Modifying context properties
1602 @cindex context properties
1606 Contexts are responsible for holding the values of a number of
1607 context @emph{properties}. Many of them can be changed to
1608 influence the interpretation of the input and so change the
1609 appearance of the output. They are changed by the
1610 @code{\set} command. This takes the form
1613 \set @emph{ContextName}.@emph{propertyName} = #@emph{value}
1616 Where the @emph{ContextName} is usually @code{Score},
1617 @code{Staff} or @code{Voice}. It may be omitted,
1618 in which case @code{Voice} is assumed.
1620 The names of context properties consist of words joined
1621 together with no hyphens or underscores, all except the
1622 first having a capital letter. Here are a few examples
1623 of some commonly used ones. There are many more.
1625 @c attempt to force this onto a new page
1627 @multitable @columnfractions .25 .15 .45 .15
1628 @headitem propertyName
1634 @tab If true, set extra natural signs before accidentals
1635 @tab @code{#t}, @code{#f}
1636 @item currentBarNumber
1638 @tab Set the current bar number
1642 @tab If true, print slurs both above and below notes
1643 @tab @code{#t}, @code{#f}
1644 @item instrumentName
1646 @tab Set the name to be placed at the start of the staff
1647 @tab @code{"Cello I"}
1650 @tab Increase or decrease the font size
1654 @tab Set the text to print before the start of a verse
1659 where a Boolean is either True (@code{#t}) or False (@code{#f}),
1660 an Integer is a positive whole number, a Real is a positive
1661 or negative decimal number, and text is enclosed in double
1662 apostrophes. Note the occurrence of hash signs,
1663 (@code{#}), in two different places -- as part of the Boolean
1664 value before the @code{t} or @code{f}, and before @emph{value}
1665 in the @code{\set} statement. So when a Boolean is being
1666 entered you need to code two hash signs, e.g., @code{##t}.
1668 Before we can set any of these properties we need to know
1669 in which context they operate. Sometimes this is obvious,
1670 but occasionally it can be tricky. If the wrong context
1671 is specified, no error message is produced, but the expected
1672 action will not take place. For example, the
1673 @code{instrumentName} clearly lives in the Staff context, since
1674 it is the staff that is to be named.
1675 In this example the first staff is labelled, but not the second,
1676 because we omitted the context name.
1678 @lilypond[quote,verbatim,ragged-right]
1680 \new Staff \relative c'' {
1681 \set Staff.instrumentName = #"Soprano"
1684 \new Staff \relative c' {
1685 \set instrumentName = #"Alto" % Wrong!
1691 Remember the default context name is Voice, so the second
1692 @code{\set} command set the property @code{instrumentName} in the
1693 Voice context to @qq{Alto}, but as LilyPond does not look
1694 for any such property in the @code{Voice} context, no
1695 further action took place. This is not an error, and no error
1696 message is logged in the log file.
1698 Similarly, if the property name is mis-spelt no error message
1699 is produced, and clearly the expected action cannot be performed.
1700 If fact, you can set any (fictitious) @q{property} using any
1701 name you like in any context that exists by using the
1702 @code{\set} command. But if the name is not
1703 known to LilyPond it will not cause any action to be taken.
1704 This is one of the reasons why it is highly recommended to
1705 use a context-sensitive editor with syntax highlighting for
1706 editing LilyPond input files, such as Vim, Jedit, ConTEXT or Emacs,
1707 since unknown property names will be highlighted differently.
1709 The @code{instrumentName} property will take effect only
1710 if it is set in the @code{Staff} context, but
1711 some properties can be set in more than one context.
1712 For example, the property @code{extraNatural} is by
1713 default set to ##t (true) for all staves.
1714 If it is set to ##f (false) in one particular @code{Staff}
1715 context it applies just to the accidentals on that staff.
1716 If it is set to false in the @code{Score} context
1717 it applies to all staves.
1719 So this turns off extra naturals in one staff:
1721 @lilypond[quote,verbatim,ragged-right]
1723 \new Staff \relative c'' {
1726 \new Staff \relative c'' {
1727 \set Staff.extraNatural = ##f
1734 and this turns them off in all staves:
1736 @lilypond[quote,verbatim,ragged-right]
1738 \new Staff \relative c'' {
1741 \new Staff \relative c'' {
1742 \set Score.extraNatural = ##f
1748 As another example, if @code{clefOctavation} is set in
1749 the @code{Score} context this immediately changes the value
1750 of the octavation in all current staves and sets a new default
1751 value which will be applied to all staves.
1753 The opposite command, @code{\unset}, effectively removes the
1754 property from the context, which causes most properties to
1755 revert to their default value. Usually @code{\unset} is not
1756 required as a new @code{\set} command will achieve what is
1759 The @code{\set} and @code{\unset} commands can appear anywhere
1760 in the input file and will take effect from the time they are
1761 encountered until the end of the score or until the property is
1762 @code{\set} or @code{\unset} again. Let's try changing the
1763 font size, which affects the size of the note heads (among
1764 other things) several times. The change is from the default
1765 value, not the most recently set value.
1767 @lilypond[quote,verbatim,ragged-right,relative=1,fragment]
1769 % make note heads smaller
1772 % make note heads larger
1773 \set fontSize = #2.5
1775 % return to default size
1780 We have now seen how to set the values of several different
1781 types of property. Note that integers and numbers are alway
1782 preceded by a hash sign, @code{#}, while a true or false value
1783 is specified by ##t and ##f, with two hash signs. A text
1784 property should be enclosed in double quotation signs, as above,
1785 although we shall see later that text can actually be specified
1786 in a much more general way by using the very powerful
1787 @code{markup} command.
1792 Context properties may also be set at the time the context is
1793 created. Sometimes this is a clearer way of specifying a
1794 property value if it is to remain fixed for the duration of
1795 the context. When a context is created with a @code{\new}
1796 command it may be followed immediately by a
1797 @code{\with @{ .. @}} block in which the property values are
1798 set. For example, if we wish to suppress the printing of
1799 extra naturals for the duration of a staff we would write:
1802 \new Staff \with @{ extraNatural = ##f @}
1808 @lilypond[quote,verbatim,ragged-right]
1814 \new Staff \with { extraNatural = ##f }
1821 Properties set in this way may still be changed dynamically using
1822 @code{\set} and returned to their default value with @code{\unset}.
1824 The @code{fontSize} property is treated differently. If this is
1825 set in a @code{\with} clause it effectively resets the default
1826 value of the font size. If it is later changed with @code{\set}
1827 this new default value may be restored with the
1828 @code{\unset fontSize} command.
1830 @node Adding and removing engravers
1831 @subsection Adding and removing engravers
1833 @cindex Engravers, adding
1834 @cindex Engravers, removing
1839 We have seen that contexts each contain several engravers, each
1840 of which is responsible for producing a particular part of the
1841 output, like bar lines, staves, note heads, stems, etc. If an
1842 engraver is removed from a context it can no longer produce its
1843 output. This is a crude way of modifying the output, but it
1844 can sometimes be useful.
1846 @subsubheading Changing a single context
1848 To remove an engraver from a single context we use the
1849 @code{\with} command placed immediately after the context creation
1850 command, as in the previous section.
1853 illustration let's repeat an example from the previous
1854 section with the staff lines removed. Remember that the
1855 staff lines are produced by the Staff_symbol_engraver.
1857 @lilypond[quote,verbatim,ragged-right]
1859 \remove Staff_symbol_engraver
1863 \set fontSize = #-4 % make note heads smaller
1865 \set fontSize = #2.5 % make note heads larger
1867 \unset fontSize % return to original size
1872 @cindex ambitus engraver
1874 Engravers can also be added to individual contexts.
1875 The command to do this is
1877 @code{\consists @emph{Engraver_name}},
1879 placed inside a @code{\with} block. Some vocal scores
1880 have an @rglos{ambitus} placed at the beginning of a
1881 staff to indicate the range of notes in that staff.
1882 The ambitus is produced by the @code{Ambitus_engraver},
1883 which is not normally included in any context. If
1884 we add it to the @code{Voice} context it calculates
1885 the range from that voice only:
1887 @lilypond[quote,verbatim,ragged-right]
1890 \consists Ambitus_engraver
1905 but if we add the Ambitus engraver to the
1906 @code{Staff} context it calculates the range from all
1907 the notes in all the voices on that staff:
1909 @lilypond[quote,verbatim,ragged-right]
1911 \consists Ambitus_engraver
1927 @subsubheading Changing all contexts of the same type
1929 The examples above show how to remove or add engravers to
1930 individual contexts. It is also possible to remove or add
1931 engravers to every context of a specific type by placing the
1932 commands in the appropriate context in a @code{\layout}
1933 block. For example, if we wanted to show an ambitus for every
1934 staff in a four-staff score we could write
1936 @lilypond[quote,verbatim,ragged-right]
1940 \relative c'' { c a b g }
1943 \relative c' { c a b g }
1947 \relative c' { c a b g }
1951 \relative c { c a b g }
1957 \consists Ambitus_engraver
1964 The default values of context properties may also be set
1965 for all contexts of a particular type by including the
1966 @code{\set} command in a @code{\context} block in the
1969 @node Extending the templates
1970 @section Extending the templates
1972 You've read the tutorial, you know how to write music, you
1973 understand the fundamental concepts. But how can you
1974 get the staves that you want? Well, you can find lots of
1975 templates (see @ref{Templates}) which may give you a start.
1977 if you want something that isn't covered there? Read on.
1979 TODO Add links to templates after they have been moved to LSR
1982 * Soprano and cello::
1983 * Four-part SATB vocal score::
1984 * Building a score from scratch::
1987 @node Soprano and cello
1988 @subsection Soprano and cello
1990 Start off with the template that seems closest to what you want to end
1991 up with. Let's say that you want to write something for soprano and
1992 cello. In this case, we would start with @q{Notes and lyrics} (for the
1996 \version @w{"@version{}"}
1997 melody = \relative c' @{
2004 text = \lyricmode @{
2010 \new Voice = "one" @{
2014 \new Lyrics \lyricsto "one" \text
2021 Now we want to add a cello part. Let's look at the @q{Notes only} example:
2024 \version @w{"@version{}"}
2025 melody = \relative c' @{
2039 We don't need two @code{\version} commands. We'll need the
2040 @code{melody} section. We don't want two @code{\score} sections
2041 -- if we had two @code{\score}s, we'd get the two parts separately.
2042 We want them together, as a duet. Within the @code{\score}
2043 section, we don't need two @code{\layout} or @code{\midi}.
2045 If we simply cut and paste the @code{melody} section, we would
2046 end up with two @code{melody} definitions. This would not generate
2047 an error, but the second one would be used for both melodies.
2048 So let's rename them to make them distinct. We'll call the
2049 section for the soprano @code{sopranoMusic} and the section for
2050 the cello @code{celloMusic}. While we're doing this, let's rename
2051 @code{text} to be @code{sopranoLyrics}. Remember to rename both
2052 instances of all these names -- both the initial definition (the
2053 @code{melody = \relative c' @{ } part) and the name's use (in the
2054 @code{\score} section).
2056 While we're doing this, let's change the cello part's staff --
2057 celli normally use bass clef. We'll also give the cello some
2061 \version @w{"@version{}"}
2062 sopranoMusic = \relative c' @{
2069 sopranoLyrics = \lyricmode @{
2073 celloMusic = \relative c @{
2082 \new Voice = "one" @{
2086 \new Lyrics \lyricsto "one" \sopranoLyrics
2093 This is looking promising, but the cello part won't appear in the
2094 score -- we haven't used it in the @code{\score} section. If we
2095 want the cello part to appear under the soprano part, we need to add
2098 \new Staff \celloMusic
2102 underneath the soprano stuff. We also need to add @code{<<} and
2103 @code{>>} around the music -- that tells LilyPond that there's
2104 more than one thing (in this case, two @code{Staves}) happening
2105 at once. The @code{\score} looks like this now
2107 @c Indentation in this example is deliberately poor
2112 \new Voice = "one" @{
2116 \new Lyrics \lyricsto "one" \sopranoLyrics
2118 \new Staff \celloMusic
2126 This looks a bit messy; the indentation is messed up now. That is
2127 easily fixed. Here's the complete soprano and cello template.
2129 @lilypond[quote,verbatim,ragged-right,addversion]
2130 sopranoMusic = \relative c' {
2137 sopranoLyrics = \lyricmode {
2141 celloMusic = \relative c {
2151 \new Voice = "one" {
2155 \new Lyrics \lyricsto "one" \sopranoLyrics
2157 \new Staff \celloMusic
2165 @node Four-part SATB vocal score
2166 @subsection Four-part SATB vocal score
2168 Most vocal scores of music written for four-part mixed choir
2169 with orchestral accompaniment such as Mendelssohn's Elijah or
2170 Handel's Messiah have the choral music and words on four
2171 staves, one for each of SATB, with a piano reduction of the
2172 orchestral accompaniment underneath. Here's an example
2173 from Handel's Messiah:
2175 @c The following should appear as music without code
2176 @lilypond[quote,ragged-right]
2177 global = { \key d \major \time 4/4 }
2178 sopMusic = \relative c'' {
2180 r4 d2 a4 | d4. d8 a2 | cis4 d cis2 |
2182 sopWords = \lyricmode {
2183 Wor -- thy is the lamb that was slain
2185 altoMusic = \relative a' {
2187 r4 a2 a4 | fis4. fis8 a2 | g4 fis e2 |
2189 altoWords = \sopWords
2190 tenorMusic = \relative c' {
2192 r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 |
2194 tenorWords = \sopWords
2195 bassMusic = \relative c' {
2197 r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 |
2199 bassWords = \sopWords
2200 upper = \relative a' {
2203 r4 <a d fis>2 <a e' a>4 |
2204 <d fis d'>4. <d fis d'>8 <a d a'>2 |
2205 <g cis g'>4 <a d fis> <a cis e>2 |
2207 lower = \relative c, {
2210 <d d'>4 <d d'>2 <cis cis'>4 |
2211 <b b'>4. <b' b'>8 <fis fis'>2 |
2212 <e e'>4 <d d'> <a' a'>2 |
2216 << % combine ChoirStaff and PianoStaff in parallel
2218 \new Staff = "sopranos" <<
2219 \set Staff.instrumentName = "Soprano"
2220 \new Voice = "sopranos" { \global \sopMusic }
2222 \new Lyrics \lyricsto "sopranos" { \sopWords }
2223 \new Staff = "altos" <<
2224 \set Staff.instrumentName = "Alto"
2225 \new Voice = "altos" { \global \altoMusic }
2227 \new Lyrics \lyricsto "altos" { \altoWords }
2228 \new Staff = "tenors" <<
2229 \set Staff.instrumentName = "Tenor"
2230 \new Voice = "tenors" { \global \tenorMusic }
2232 \new Lyrics \lyricsto "tenors" { \tenorWords }
2233 \new Staff = "basses" <<
2234 \set Staff.instrumentName = "Bass"
2235 \new Voice = "basses" { \global \bassMusic }
2237 \new Lyrics \lyricsto "basses" { \bassWords }
2241 \set PianoStaff.instrumentName = "Piano "
2242 \new Staff = "upper" \upper
2243 \new Staff = "lower" \lower
2249 None of the templates provides this layout exactly. The
2250 nearest is @q{SATB vocal score and automatic piano reduction},
2251 but we need to change the layout and add a piano
2252 accompaniment which is not derived automatically from the
2253 vocal parts. The variables holding the music and words for
2254 the vocal parts are fine, but we shall need to add variables for
2255 the piano reduction.
2257 The order in which the contexts appear in the ChoirStaff of
2258 the template do not correspond with the order in the vocal
2259 score shown above. We need to rearrange them so there are
2260 four staves with the words written directly underneath the
2261 notes for each part.
2262 All the voices should be @code{\voiceOne}, which is
2263 the default, so the @code{\voiceXXX} commands should be removed.
2264 We also need to specify the tenor clef for the tenors.
2265 The way in which lyrics are specified in the template has not yet
2266 been encountered so we need to use the method with which we are
2267 familiar. We should also add the names of each staff.
2269 Doing this gives for our ChoirStaff:
2273 \new Staff = "sopranos" <<
2274 \set Staff.instrumentName = "Soprano"
2275 \new Voice = "sopranos" @{ \global \sopMusic @}
2277 \new Lyrics \lyricsto "sopranos" @{ \sopWords @}
2278 \new Staff = "altos" <<
2279 \set Staff.instrumentName = "Alto"
2280 \new Voice = "altos" @{ \global \altoMusic @}
2282 \new Lyrics \lyricsto "altos" @{ \altoWords @}
2283 \new Staff = "tenors" <<
2284 \set Staff.instrumentName = "Tenor"
2285 \new Voice = "tenors" @{ \global \tenorMusic @}
2287 \new Lyrics \lyricsto "tenors" @{ \tenorWords @}
2288 \new Staff = "basses" <<
2289 \set Staff.instrumentName = "Bass"
2290 \new Voice = "basses" @{ \global \bassMusic @}
2292 \new Lyrics \lyricsto "basses" @{ \bassWords @}
2296 Next we must work out the piano part. This is
2297 easy - we just pull out the piano part from the
2298 @q{Solo piano} template:
2302 \set PianoStaff.instrumentName = "Piano "
2303 \new Staff = "upper" \upper
2304 \new Staff = "lower" \lower
2308 and add the variable definitions for @code{upper}
2311 The ChoirStaff and PianoStaff must be combined
2312 using angle brackets as we want them to be
2313 stacked one above the other:
2316 << % combine ChoirStaff and PianoStaff one above the other
2318 \new Staff = "sopranos" <<
2319 \new Voice = "sopranos" @{ \global \sopMusic @}
2321 \new Lyrics \lyricsto "sopranos" @{ \sopWords @}
2322 \new Staff = "altos" <<
2323 \new Voice = "altos" @{ \global \altoMusic @}
2325 \new Lyrics \lyricsto "altos" @{ \altoWords @}
2326 \new Staff = "tenors" <<
2327 \clef "G_8" % tenor clef
2328 \new Voice = "tenors" @{ \global \tenorMusic @}
2330 \new Lyrics \lyricsto "tenors" @{ \tenorWords @}
2331 \new Staff = "basses" <<
2333 \new Voice = "basses" @{ \global \bassMusic @}
2335 \new Lyrics \lyricsto "basses" @{ \bassWords @}
2339 \set PianoStaff.instrumentName = "Piano "
2340 \new Staff = "upper" \upper
2341 \new Staff = "lower" \lower
2346 Combining all these together and adding the music
2347 for the three bars of the example above gives:
2349 @lilypond[quote,verbatim,ragged-right,addversion]
2350 global = { \key d \major \time 4/4 }
2351 sopMusic = \relative c'' {
2353 r4 d2 a4 | d4. d8 a2 | cis4 d cis2 |
2355 sopWords = \lyricmode {
2356 Wor -- thy is the lamb that was slain
2358 altoMusic = \relative a' {
2360 r4 a2 a4 | fis4. fis8 a2 | g4 fis fis2 |
2362 altoWords = \sopWords
2363 tenorMusic = \relative c' {
2365 r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 |
2367 tenorWords = \sopWords
2368 bassMusic = \relative c' {
2370 r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 |
2372 bassWords = \sopWords
2373 upper = \relative a' {
2376 r4 <a d fis>2 <a e' a>4 |
2377 <d fis d'>4. <d fis d'>8 <a d a'>2 |
2378 <g cis g'>4 <a d fis> <a cis e>2 |
2380 lower = \relative c, {
2383 <d d'>4 <d d'>2 <cis cis'>4 |
2384 <b b'>4. <b' b'>8 <fis fis'>2 |
2385 <e e'>4 <d d'> <a' a'>2 |
2389 << % combine ChoirStaff and PianoStaff in parallel
2391 \new Staff = "sopranos" <<
2392 \set Staff.instrumentName = "Soprano"
2393 \new Voice = "sopranos" { \global \sopMusic }
2395 \new Lyrics \lyricsto "sopranos" { \sopWords }
2396 \new Staff = "altos" <<
2397 \set Staff.instrumentName = "Alto"
2398 \new Voice = "altos" { \global \altoMusic }
2400 \new Lyrics \lyricsto "altos" { \altoWords }
2401 \new Staff = "tenors" <<
2402 \set Staff.instrumentName = "Tenor"
2403 \new Voice = "tenors" { \global \tenorMusic }
2405 \new Lyrics \lyricsto "tenors" { \tenorWords }
2406 \new Staff = "basses" <<
2407 \set Staff.instrumentName = "Bass"
2408 \new Voice = "basses" { \global \bassMusic }
2410 \new Lyrics \lyricsto "basses" { \bassWords }
2414 \set PianoStaff.instrumentName = "Piano "
2415 \new Staff = "upper" \upper
2416 \new Staff = "lower" \lower
2423 @node Building a score from scratch
2424 @subsection Building a score from scratch
2426 After gaining some facility with writing LilyPond code you
2427 may find that it is easier to build a score from scratch
2428 rather than modifying one of the templates. You can also
2429 develop your own style this way to suit the sort of music you
2430 like. Let's see how to put together the score for an organ
2431 prelude as an example.
2433 We begin with a header section. Here go the title, name
2434 of composer, etc, then come any variable definitions, and
2435 finally the score block. Let's start with these in outline
2436 and fill in the details later.
2438 We'll use the first two bars of Bach's prelude
2439 based on @emph{Jesu, meine Freude} which is written for two
2440 manuals and pedal organ. You can see these two bars of music
2441 at the bottom of this section. The top manual part has two voices,
2442 the lower and pedal organ one each. So we need four
2443 music definitions and one to define the time signature
2447 \version @w{"@version{}"}
2449 title = "Jesu, meine Freude"
2450 composer = "J S Bach"
2452 TimeKey = @{ \time 4/4 \key c \minor @}
2453 ManualOneVoiceOneMusic = @{s1@}
2454 ManualOneVoiceTwoMusic = @{s1@}
2455 ManualTwoMusic = @{s1@}
2456 PedalOrganMusic = @{s1@}
2462 For now we've just used a spacer note, @code{s1},
2463 instead of the real music. We'll add that later.
2465 Next let's see what should go in the score block.
2466 We simply mirror the staff structure we want.
2467 Organ music is usually written on three staves,
2468 one for each manual and one for the pedals. The
2469 manual staves should be bracketed together so we
2470 need to use a PianoStaff for them. The first
2471 manual part needs two voices and the second manual
2476 \new Staff = "ManualOne" <<
2477 \new Voice @{ \ManualOneVoiceOneMusic @}
2478 \new Voice @{ \ManualOneVoiceTwoMusic @}
2479 >> % end ManualOne Staff context
2480 \new Staff = "ManualTwo" <<
2481 \new Voice @{ \ManualTwoMusic @}
2482 >> % end ManualTwo Staff context
2483 >> % end PianoStaff context
2486 Next we need to add a staff for the pedal organ.
2487 This goes underneath the PianoStaff, but it must
2488 be simultaneous with it, so we need angle brackets
2489 round the two. Missing these out would generate
2490 an error in the log file. It's a common mistake
2491 which you'll make sooner or later! Try copying
2492 the final example at the end of this section,
2493 remove these angle brackets, and compile it to
2494 see what errors it generates.
2497 << % PianoStaff and Pedal Staff must be simultaneous
2499 \new Staff = "ManualOne" <<
2500 \new Voice @{ \ManualOneVoiceOneMusic @}
2501 \new Voice @{ \ManualOneVoiceTwoMusic @}
2502 >> % end ManualOne Staff context
2503 \new Staff = "ManualTwo" <<
2504 \new Voice @{ \ManualTwoMusic @}
2505 >> % end ManualTwo Staff context
2506 >> % end PianoStaff context
2507 \new Staff = "PedalOrgan" <<
2508 \new Voice @{ \PedalOrganMusic @}
2513 It is not strictly necessary to use the simultaneous construct
2514 @code{<< >>} for the manual two staff and the pedal organ staff,
2515 since they contain only one music expression, but it does no harm
2516 and always using angle brackets after @code{\new Staff} is a good
2517 habit to cultivate in case there are multiple voices.
2519 Let's add this structure to the score block, and adjust the
2520 indenting. We also add the appropriate clefs, ensure the
2521 second voice stems point down with @code{\voiceTwo} and
2522 enter the time signature and key to each staff using our
2523 predefined variable, @code{\TimeKey}.
2527 << % PianoStaff and Pedal Staff must be simultaneous
2529 \new Staff = "ManualOne" <<
2530 \TimeKey % set time signature and key
2532 \new Voice @{ \ManualOneVoiceOneMusic @}
2533 \new Voice @{ \voiceTwo \ManualOneVoiceTwoMusic @}
2534 >> % end ManualOne Staff context
2535 \new Staff = "ManualTwo" <<
2538 \new Voice @{ \ManualTwoMusic @}
2539 >> % end ManualTwo Staff context
2540 >> % end PianoStaff context
2541 \new Staff = "PedalOrgan" <<
2544 \new Voice @{ \PedalOrganMusic @}
2545 >> % end PedalOrgan Staff
2547 @} % end Score context
2550 That completes the structure. Any three-staff organ music
2551 will have a similar structure, although the number of voices
2552 may vary. All that remains now
2553 is to add the music, and combine all the parts together.
2555 @lilypond[quote,verbatim,ragged-right,addversion]
2557 title = "Jesu, meine Freude"
2558 composer = "J S Bach"
2560 TimeKey = { \time 4/4 \key c \minor }
2561 ManualOneVoiceOneMusic = \relative g' {
2562 g4 g f ees | d2 c2 |
2564 ManualOneVoiceTwoMusic = \relative c' {
2565 ees16 d ees8~ ees16 f ees s c8 d~ d c~ |
2566 c c4 b8 c8. g16 c b c d |
2568 ManualTwoMusic = \relative c' {
2569 c16 b c8~ c16 b c g a8 g~ g16 g aes ees |
2570 f ees f d g aes g f ees d e8~ ees16 f ees d |
2572 PedalOrganMusic = \relative c {
2573 r8 c16 d ees d ees8~ ees16 a, b g c b c8 |
2574 r16 g ees f g f g8 c,2 |
2578 << % PianoStaff and Pedal Staff must be simultaneous
2580 \new Staff = "ManualOne" <<
2581 \TimeKey % set time signature and key
2583 \new Voice { \ManualOneVoiceOneMusic }
2584 \new Voice { \voiceTwo \ManualOneVoiceTwoMusic }
2585 >> % end ManualOne Staff context
2586 \new Staff = "ManualTwo" <<
2589 \new Voice { \ManualTwoMusic }
2590 >> % end ManualTwo Staff context
2591 >> % end PianoStaff context
2592 \new Staff = "PedalOrgan" <<
2595 \new Voice { \PedalOrganMusic }
2596 >> % end PedalOrgan Staff
2598 } % end Score context