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 When entering more than a few lines of music it is advisable to
114 always create staves and voices explicitly, see
115 @ref{Contexts and engravers}.
117 For now, though, let us return to the first example and examine the
118 @code{\score} command, leaving the others to default.
120 A @code{\score} block must always contain just one music expression,
121 and this must appear immediately after the @code{\score} command.
122 Remember that a music expression could be anything from a single
123 note to a huge compound expression like
128 @var{...insert the whole score of a Wagner opera in here...}
134 Since everything is inside @code{@{ ... @}}, it counts
135 as one music expression.
137 As we saw previously, the @code{\score} block can contain other
157 Note that these three commands -- @code{\header}, @code{\layout}
158 and @code{\midi} -- are special: unlike all other commands which
159 begin with a backward slash (@code{\}) they are @emph{not} music
160 expressions and are not part of any music expression.
161 So they may be placed inside a @code{\score} block
162 or outside it. In fact, these commands are commonly placed
163 outside the @code{\score} block -- for example, @code{\header}
164 is often placed above the @code{\score} command because headers
165 naturally appear at the top of a score. That's just another
166 shorthand that LilyPond accepts.
168 Two more commands you have not previously seen are
169 @code{\layout @{ @}} and @code{\midi @{@}}. If these appear as
170 shown they will cause LilyPond to produce a printed output and a
171 MIDI output respectively. They are described fully in the
172 Notation Reference -- @ruser{Score layout} and
173 @ruser{Creating MIDI files}.
175 @cindex scores, multiple
177 You may code multiple @code{\score} blocks. Each will be
178 treated as a separate score, but they will be all combined into
179 a single output file. A @code{\book} command is not necessary
180 -- one will be implicitly created. However, if you would like
181 separate output files from one @code{.ly} file then the
182 @code{\book} command should be used to separate the different
183 sections: each @code{\book} block will produce a
184 separate output file.
188 Every @code{\book} block creates a separate output file (e.g., a
189 pdf file). If you haven't explicitly added one, LilyPond wraps
190 your entire input code in a @code{\book} block implicitly.
192 Every @code{\score} block is a separate chunk of music within a
195 Every @code{\layout} block affects the @code{\score} or
196 @code{\book} block in which it appears -- i.e., a @code{\layout}
197 block inside a @code{\score} block affects only that @code{\score}
198 block, but a @code{\layout} block outside of a @code{\score} block
199 (and thus in a @code{\book} block, either explicitly or
200 implicitly) will affect every @code{\score} in that @code{\book}.
202 Every @code{\context} block will affect the named context (e.g.,
203 @code{\StaffGroup}) throughout the block (@code{\score} or
204 @code{\book}) in which it appears.
206 For details see @ruser{Multiple scores in a book}.
210 Another great shorthand is the ability to define variables. All
211 the templates use this
214 melody = \relative c' @{
223 When LilyPond looks at this file, it takes the value of
224 @code{melody} (everything after the equals sign) and inserts it
225 whenever it sees @code{\melody}. There's nothing special about
226 the names -- it could be @code{melody}, @code{global},
228 @code{pianorighthand}, or @code{foofoobarbaz}. For more details,
229 see @ref{Saving typing with variables and functions}.
230 Remember that you can use almost any name you like as long
231 as it contains just alphabetic characters and is distinct from
232 LilyPond command names. The exact
233 limitations on variable names are detailed in
234 @ruser{File structure}.
240 For a complete definition of the input format, see
241 @ruser{File structure}.
243 @node Score is a (single) compound musical expression
244 @subsection Score is a (single) compound musical expression
248 @cindex Compound music expression
249 @cindex Music expression, compound
251 We saw the general organization of LilyPond input files in the
252 previous section, @ref{How LilyPond input files work}. But we seemed to
253 skip over the most important part: how do we figure out what to
254 write after @code{\score}?
256 We didn't skip over it at all. The big mystery is simply that
257 there @emph{is} no mystery. This line explains it all:
260 @emph{A @code{\score} block must begin with a compound music expression.}
264 You may find it useful to review
265 @ref{Music expressions explained}. In that section, we saw how to
266 build big music expressions from small pieces -- we started from
267 notes, then chords, etc. Now we're going to start from a big
268 music expression and work our way down.
272 @{ % this brace begins the overall compound music expression
274 @var{...insert the whole score of a Wagner opera in here...}
276 @} % this brace ends the overall compound music expression
281 A whole Wagner opera would easily double the length of this
282 manual, so let's just add a singer and piano. We don't need a
283 @code{GrandStaff} for this ensemble, which simply groups a number
284 of staves together with a brace at the left, so we shall remove
285 it. We @emph{do} need a singer and a piano, though.
290 \new Staff = "singer" <<
292 \new PianoStaff = piano <<
299 Remember that we use @code{<< ... >>} instead of
300 @code{@{ ... @}} to show simultaneous
301 music. And we definitely want to show the vocal part and piano
302 part at the same time, not one after the other! However, the
303 @code{<< ... >>} construct is not really necessary for the Singer
304 staff, as it contains only one music expression, but Staves often
305 do require simultaneous Voices within them, so using
307 rather than braces is a good habit to adopt. We'll add some real
308 music later; for now let's just put in some dummy notes and lyrics.
310 @lilypond[verbatim,quote,ragged-right]
313 \new Staff = "singer" <<
314 \new Voice = "vocal" { c'1 }
317 \new PianoStaff = "piano" <<
318 \new Staff = "upper" { c'1 }
319 \new Staff = "lower" { c'1 }
326 Now we have a lot more details. We have the singer's staff: it
327 contains a @code{Voice} (in LilyPond, this term refers to a set of
328 notes, not necessarily vocal notes -- for example, a violin
329 generally plays one voice) and some lyrics. We also have a piano
330 staff: it contains an upper staff (right hand) and a lower staff
333 At this stage, we could start filling in notes. Inside the curly
334 braces next to @code{\new Voice = vocal}, we could start writing
342 But if we did that, the @code{\score} section would get pretty
343 long, and it would be harder to understand what was happening. So
344 let's use variables instead. These were introduced at the end
345 of the previous section, remember? So, adding a few notes, we
346 now have a piece of real music:
348 @lilypond[verbatim,quote,ragged-right]
349 melody = \relative c'' { r4 d8\noBeam g, c4 r }
350 text = \lyricmode { And God said, }
351 upper = \relative c'' { <g d g,>2~ <g d g,> }
352 lower = \relative c { b2 e2 }
356 \new Staff = "singer" <<
357 \new Voice = "vocal" { \melody }
360 \new PianoStaff = "piano" <<
361 \new Staff = "upper" { \upper }
362 \new Staff = "lower" {
373 Be careful about the difference between notes, which are introduced
374 with @code{\relative}, and lyrics, which are introduced with
375 @code{\lyricmode}. These are essential to tell LilyPond
376 to interpret the following content as music and text
379 When writing (or reading) a @code{\score} section, just take it
380 slowly and carefully. Start with the outer layer, then work on
381 each smaller layer. It also really helps to be strict with
382 indentation -- make sure that each item on the same layer starts
383 on the same horizontal position in your text editor.
386 @node Nesting music expressions
387 @subsection Nesting music expressions
389 @cindex staves, temporary
392 It is not essential to declare all staves at the beginning;
393 they may be introduced temporarily at any point. This is
394 particularly useful for creating ossia sections
395 (see @rglos{ossia}). Here is a simple example showing how
396 to introduce a new staff temporarily for the duration of
399 @lilypond[verbatim,quote,ragged-right]
416 Note that the size of the clef is the same as a clef printed
417 following a clef change -- slightly smaller than the clef
418 at the beginning of the line. This is usual for clefs printed
419 in the middle of a line.
421 @cindex staff, positioning
423 The ossia section may be placed above the staff
426 @lilypond[verbatim,quote,ragged-right]
434 alignAboveContext = "main" }
442 This example uses @code{\with}, which will be explained more
443 fully later. It is a means of modifying the default behavior
444 of a single Staff. Here it says that the new staff should be
445 placed above the staff called @qq{main} instead of the default
446 position which is below.
448 Ossia are often written without clef and without
449 time signature and are usually in a smaller font.
450 These require further commands which
451 have not yet been introduced. See @ref{Size of objects}
453 @node On the un-nestedness of brackets and ties
454 @subsection On the un-nestedness of brackets and ties
456 @cindex brackets, nesting
458 You have already met a number of different types of bracket in
459 writing the input file to LilyPond. These obey different rules
460 which can be confusing at first. Before we explain the rules
461 let's first review the different types of bracket.
463 @c attempt to force this onto a new page
465 @multitable @columnfractions .3 .7
466 @headitem Bracket Type
468 @item @code{@{ .. @}}
469 @tab Encloses a sequential segment of music
471 @tab Encloses the notes of a chord
472 @item @code{<< .. >>}
473 @tab Encloses concurrent or simultaneous sections
475 @tab Marks the start and end of a slur
476 @item @code{\( .. \)}
477 @tab Marks the start and end of a phrase mark
479 @tab Marks the start and end of a manual beam
482 To these we should add other constructs which generate lines
483 between or across notes: ties (marked by a tilde, @code{~}),
484 tuplets written as @code{\times x/y @{..@}}, and grace notes
485 written as @code{\grace@{..@}}.
487 Outside LilyPond, the conventional use of brackets requires
488 the different types to be properly nested, like this,
489 @code{<< [ @{ ( .. ) @} ] >>}, with the closing brackets being
490 encountered in exactly the opposite order to the opening
491 brackets. This @strong{is} a requirement for the three types of
492 bracket described by the word @q{Encloses} in the table above --
493 they must nest properly.
494 However, the remaining brackets, described with the word
495 @q{Marks} in the table above together with ties and tuplets,
496 do @strong{not} have to nest
497 properly with any of the brackets. In fact, these are not
498 brackets in the sense that
499 they enclose something -- they are simply markers to indicate
500 where something starts and ends.
502 So, for example, a phrasing slur can start before a manually
503 inserted beam and end before the end of the beam -- not very
504 musical, perhaps, but possible:
506 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
507 { g8\( a b[ c b\) a] }
510 In general, different kinds of brackets, and those implied by
511 tuplets, ties and grace notes, may be mixed freely.
512 This example shows a beam extending into a tuplet (line 1),
513 a slur extending into a tuplet (line 2),
514 a beam and a slur extending into a tuplet, a tie crossing
515 two tuplets, and a phrasing slur extending out of a tuplet
518 @lilypond[quote,verbatim,fragment,ragged-right]
520 r16[ g16 \times 2/3 {r16 e'8] }
521 g16( a \times 2/3 {b d) e' }
522 g8[( a \times 2/3 {b d') e'~]}
523 \times 4/5 {e'32\( a b d' e'} a'4.\)
528 @node Voices contain music
529 @section Voices contain music
531 Singers need voices to sing, and so does LilyPond.
532 The actual music for all instruments in a score
533 is contained in Voices -- the most fundamental
534 of all LilyPond's concepts.
537 * I'm hearing Voices::
538 * Explicitly instantiating voices::
539 * Voices and vocals::
542 @node I'm hearing Voices
543 @subsection I'm hearing Voices
547 @cindex multiple voices
548 @cindex Voice context
549 @cindex context, Voice
550 @cindex simultaneous music
551 @cindex concurrent music
553 The lowest, most fundamental or innermost layers in a LilyPond
554 score are called @q{Voice contexts} or just @q{Voices} for short.
555 Voices are sometimes called @q{layers} in other notation
558 In fact, a Voice layer or context is the only one which can
559 contain music. If a Voice context is not explicitly declared
560 one is created automatically, as we saw at the beginning of
561 this chapter. Some instruments such as an
562 Oboe can play only one note at a time. Music written for
563 such instruments is monophonic and requires just a single
564 voice. Instruments which can play more than one note at a
565 time like the piano will often require multiple voices to
566 encode the different concurrent notes and rhythms they are
569 A single voice can contain many notes in a chord, of course,
570 so when exactly are multiple voices needed? Look first at
571 this example of four chords:
573 @lilypond[quote,verbatim,fragment,ragged-right,relative=1]
575 <d g>4 <d fis> <d a'> <d g>
578 This can be expressed using just the single angle bracket chord
579 symbols, @code{< ... >}, and for this just a single voice is
580 needed. But suppose the F-sharp were actually an eighth-note
581 followed by an eighth-note G, a passing note on the way to the A?
582 Now we have two notes which start at the same time but have
583 different durations: the quarter-note D and the eighth-note
584 F-sharp. How are these to be coded? They cannot be written as
585 a chord because all the notes in a chord must have the same
586 duration. And they cannot be written as two separate notes
587 as they need to start at the same time. This is when two
590 Let us see how this is done in LilyPond input syntax.
595 The easiest way to enter fragments with more than one voice on a
596 staff is to enter each voice as a sequence (with @code{@{...@}}),
597 and combine them simultaneously with angle brackets, @code{<<...>>}.
598 The fragments must also be separated with double backward slashes,
599 @code{\\}, to place them in separate voices. Without these, the
600 notes would be entered into a single voice, which would usually
601 cause errors. This technique is particularly suited to pieces of
602 music which are largely monophonic with occasional short sections
605 Here's how we split the chords above into two voices and add both
606 the passing note and a slur:
608 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
610 % Voice "1" Voice "2"
611 << { g4 fis8( g) a4 g } \\ { d4 d d d } >> |
614 Notice how the stems of the second voice now point down.
616 Here's another simple example:
618 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
620 % Voice "1" Voice "2"
621 << { r4 g g4. a8 } \\ { d,2 d4 g } >> |
622 << { bes4 bes c bes } \\ { g4 g g8( a) g4 } >> |
623 << { a2. r4 } \\ { fis2. s4 } >> |
626 It is not necessary to use a separate @code{<< \\ >>} construct
627 for each bar. For music with few notes in each bar this layout
628 can help the legibility of the code, but if there are many
629 notes in each bar it may be better to split out each voice
630 separately, like this:
632 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
648 This example has just two voices, but the same construct may be
649 used to encode three or more voices by adding more back-slash
652 The Voice contexts bear the names @code{"1"}, @code{"2"}, etc.
653 In each of these contexts, the vertical direction of slurs,
654 stems, ties, dynamics etc., is set appropriately.
656 @lilypond[quote,verbatim,fragment]
657 \new Staff \relative c' {
660 % Voice "1" Voice "2" Voice "3"
661 << { g4 f e } \\ { r8 e4 d c8 ~ } >> |
662 << { d2 e2 } \\ { c8 b16 a b8 g ~ g2 } \\ { s4 b4 c2 } >> |
666 These voices are all separate from the main voice that contains
667 the notes just outside the @code{<< .. >>} construct. Let's call
668 this the @emph{simultaneous construct}. Slurs and ties may only
669 connect notes within the same voice, so slurs and ties cannot go
670 into or out of a simultaneous construct. Conversely,
671 parallel voices from separate simultaneous constructs on the same
672 staff are the same voice. Other voice-related properties also
673 carry across simultaneous constructs. Here is the same example,
674 with different colors and note heads for each voice. Note that
675 changes in one voice do not affect other voices, but they do
676 persist in the same voice later. Note also that tied notes may be
677 split across the same voices in two constructs, shown here in the
680 @lilypond[quote,verbatim]
681 \new Staff \relative c' {
700 { c8 b16 a b8 g ~ g2 }
710 @funindex \voiceXXXStyle
712 The commands @code{\voiceXXXStyle} are mainly intended for use in
713 educational documents such as this one. They modify the color
714 of the note head, the stem and the beams, and the style of the
715 note head, so that the voices may be easily distinguished.
716 Voice one is set to red diamonds, voice two to blue triangles,
717 voice three to green crossed circles, and voice four (not used
718 here) to magenta crosses. We shall see later how commands like
719 these may be created by the user.
720 See @ref{Visibility and color of objects} and
721 @ref{Using variables for tweaks}.
723 Polyphony does not change the relationship of notes within a
724 @code{\relative @{ @}} block. Each note is still calculated
725 relative to the note immediately preceding it, or to the first
726 note of the preceding chord. So in
729 \relative c' @{ noteA << < noteB noteC > \\ noteD >> noteE @}
733 @code{noteB} is relative to @code{noteA} @*
734 @code{noteC} is relative to @code{noteB}, not @code{noteA}; @*
735 @code{noteD} is relative to @code{noteB}, not @code{noteA} or
737 @code{noteE} is relative to @code{noteD}, not @code{noteA}
739 An alternative way, which may be clearer if the notes in the
740 voices are widely separated, is to place a @code{\relative}
741 command at the start of each voice:
744 \relative c' @{ noteA ... @}
746 \relative c'' @{ < noteB noteC > ... @}
748 \relative g' @{ noteD ... @}
750 \relative c' @{ noteE ... @}
753 Let us finally analyze the voices in a more complex piece of
755 the notes from the first two bars of the second of Chopin's
756 Deux Nocturnes, Op 32. This example will be used at later
757 stages in this and the next chapter to illustrate several
758 techniques for producing notation, so please ignore for now
759 anything in the underlying code which looks mysterious and
760 concentrate just on the music and the voices -- the
761 complications will all be explained in later sections.
763 @c The following should appear as music without code
764 @lilypond[quote,ragged-right]
765 \new Staff \relative c'' {
774 % Ignore these for now - they are explained in Ch 4
775 \once \override NoteColumn #'force-hshift = #0
777 \once \override NoteColumn #'force-hshift = #0.5
785 The direction of the stems is often used to indicate the
786 continuity of two simultaneous melodic lines. Here the
787 stems of the highest notes are all pointing up and the
788 stems of the lower notes are all pointing down.
789 This is the first indication that more than one voice
792 But the real need for multiple voices arises when notes
793 which start at the same time have different durations.
794 Look at the notes which start at beat three in the first
795 bar. The A-flat is a dotted quarter note, the F is a
796 quarter note and the D-flat is a half note. These
797 cannot be written as a chord as all the notes in a chord
798 must have the same duration. Neither can they be written
799 as sequential notes, as they must start at the same time.
800 This section of the bar requires three voices, and the
801 normal practice would be to write the whole bar as three
802 voices, as shown below, where we have used different note heads
803 and colors for the three voices. Again, the code behind this
804 example will be explained later, so ignore anything you do
807 @c The following should appear as music without code
808 @c The three voice styles should be defined in -init
809 @lilypond[quote,ragged-right]
810 \new Staff \relative c'' {
821 \\ % No Voice three (we want stems down)
824 % Ignore these for now - they are explained in Ch 4
825 \once \override NoteColumn #'force-hshift = #0
827 \once \override NoteColumn #'force-hshift = #0.5
836 Let us try to encode this music from scratch. As we
837 shall see, this encounters some difficulties. We begin as
838 we have learnt, using the @code{<< \\ >>} construct to
839 enter the music of the first bar in three voices:
841 @lilypond[quote,verbatim,fragment,ragged-right]
842 \new Staff \relative c'' {
845 { c2 aes4. bes8 } \\ { aes2 f4 fes } \\ { <ees c>2 des2 }
854 The stem directions are automatically assigned with the
855 odd-numbered voices taking upward stems and the even-numbered
856 voices downward ones. The stems for voices 1 and 2 are right,
857 but the stems in voice 3 should go down in this particular piece
858 of music. We can correct this simply by missing out voice three
859 and placing the music in voice four:
861 @lilypond[quote,verbatim,fragment,ragged-right]
862 \new Staff \relative c'' {
868 \\ % Omit Voice three
877 We see that this fixes the stem direction, but exposes a
878 problem sometimes encountered with multiple voices -- the
879 stems of the notes in one voice can collide with the note heads
880 in other voices. In laying out the notes, LilyPond allows the
881 notes or chords from two voices to occupy the same vertical
882 note column provided the stems are in opposite directions, but
883 the notes from the third and fourth voices are displaced to if
884 necessary to avoid the note heads
885 colliding. This usually works well, but in this example the
886 notes of the lowest voice are clearly not well placed by default.
887 LilyPond provides several ways to adjust the horizontal placing
888 of notes. We are not quite ready yet to see how to correct this,
889 so we shall leave this problem until a later section
890 (see the force-hshift property in @ref{Fixing overlapping
893 @node Explicitly instantiating voices
894 @subsection Explicitly instantiating voices
898 @funindex \voiceThree
901 @cindex Voice contexts, creating
903 Voice contexts can also be created manually
904 inside a @code{<< >>} block to create polyphonic music, using
905 @code{\voiceOne} ... @code{\voiceFour} to indicate the required
906 directions of stems, slurs, etc. In longer scores this method
907 is clearer, as it permits the voices to be separated and to be
908 given more descriptive names.
910 Specifically, the construct @code{<< \\ >>} which we used in
911 the previous section:
916 << @{ e4 f g a @} \\ @{ c,4 d e f @} >>
926 \new Voice = "1" @{ \voiceOne \relative c' @{ e4 f g a @} @}
927 \new Voice = "2" @{ \voiceTwo \relative c' @{ c4 d e f @} @}
931 Both of the above would produce
933 @c The following example should not display the code
934 @lilypond[ragged-right,quote]
936 \new Voice = "1" { \voiceOne \relative c' { e4 f g a } }
937 \new Voice = "2" { \voiceTwo \relative c' { c4 d e f } }
941 The @code{\voiceXXX} commands set the direction of stems, slurs,
942 ties, articulations, text annotations, augmentation dots of dotted
943 notes, and fingerings. @code{\voiceOne} and @code{\voiceThree}
944 make these objects point upwards, while @code{\voiceTwo} and
945 @code{\voiceFour} make them point downwards. These commands also
946 generate a horizontal shift for each voice when this is required
947 to avoid clashes of note heads. The command @code{\oneVoice}
948 reverts the settings back to the normal values for a single voice.
950 Let us see in some simple examples exactly what effect
951 @code{\oneVoice}, @code{\voiceOne} and @code{voiceTwo} have on
952 markup, ties, slurs, and dynamics:
954 @lilypond[quote,ragged-right,verbatim]
956 % Default behavior or behavior after \oneVoice
957 c d8 ~ d e4 ( f g a ) b-> c
961 @lilypond[quote,ragged-right,verbatim]
964 c d8 ~ d e4 ( f g a ) b-> c
966 c, d8 ~ d e4 ( f g a ) b-> c
970 @lilypond[quote,ragged-right,verbatim]
973 c d8 ~ d e4 ( f g a ) b-> c
975 c, d8 ~ d e4 ( f g a ) b-> c
979 An expression that appears directly inside a @code{<< >>} belongs
980 to the main voice (but, note, @strong{not} in a @code{<< \\ >>}
981 construct). This is useful when extra voices appear while the
982 main voice is playing. Here is a more correct rendition of the
983 example from the previous section. The red diamond-shaped notes
984 demonstrate that the main melody is now in a single voice context,
985 permitting a phrasing slur to be drawn over them.
987 @lilypond[quote,ragged-right,verbatim]
988 \new Staff \relative c' {
990 % The following notes are monophonic
992 % Start simultaneous section of three voices
994 % Continue the main voice in parallel
996 % Initiate second voice
998 % Set stems, etc, down
1000 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2
1002 % Initiate third voice
1004 % Set stems, etc, up
1012 @cindex nesting music expressions
1013 @cindex nesting simultaneous constructs
1015 @cindex voices, temporary
1016 @cindex voices, nesting
1018 More deeply nested polyphony constructs are possible, and if a
1019 voice appears only briefly this might be a more natural way to
1022 @lilypond[quote,ragged-right,verbatim]
1023 \new Staff \relative c' {
1031 {c8 b16 a b8 g ~ g2}
1042 @cindex spacing notes
1044 This method of nesting new voices briefly is useful
1045 when only small sections of the music
1046 are polyphonic, but when the whole staff is largely polyphonic
1047 it can be clearer to use multiple voices throughout, using
1048 spacing notes to step over sections where the voice is silent,
1051 @lilypond[quote,ragged-right,verbatim]
1052 \new Staff \relative c' <<
1053 % Initiate first voice
1056 c16^( d e f g4 f e | d2 e2) |
1058 % Initiate second voice
1060 % set stems, etc down
1062 s4 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2 |
1064 % Initiate third voice
1074 @cindex shift commands
1078 @funindex \shiftOnnn
1080 Closely spaced notes in a chord, or notes occurring at the same
1081 time in different voices, are arranged in two, occasionally more,
1082 columns to prevent the note heads overlapping. These are called
1083 note columns. There are separate columns for each voice, and
1084 the currently specified voice-dependent shift is applied to the
1085 note column if there would otherwise be a collision. This can
1086 be seen in the example above. In bar 2 the C in voice two is
1087 shifted to the right relative to the D in voice one, and in the
1088 final chord the C in voice three is also shifted to the right
1089 relative to the other notes.
1091 The @code{\shiftOn}, @code{\shiftOnn}, @code{\shiftOnnn}, and
1092 @code{\shiftOff} commands specify the degree to which notes and
1093 chords of the voice should be shifted if a collision
1094 would otherwise occur. By default, the outer voices (normally
1095 voices one and two) have @code{\shiftOff} specified, while the
1096 inner voices (three and four) have @code{\shiftOn} specified.
1097 When a shift is applied, Voices one and three are shifted to
1098 the right and voices two and four to the left.
1100 @code{\shiftOnn} and @code{\shiftOnnn} define further shift
1101 levels which may be specified temporarily to resolve collisions
1102 in complex situations -- see @ref{Real music example}.
1104 A note column can contain just one note (or chord) from a voice
1105 with stems up and one note (or chord) from a voice with stems
1106 down. If notes from two voices which have their stems in the
1107 same direction are placed at the same position and both voices
1108 have no shift or the same shift specified, the error message
1109 @qq{Too many clashing note columns} will be produced.
1111 @node Voices and vocals
1112 @subsection Voices and vocals
1114 Vocal music presents a special difficulty: we need to combine two
1115 expressions -- notes and lyrics.
1117 @funindex \new Lyrics
1119 @cindex Lyrics context, creating
1120 @cindex lyrics, linking to voice
1122 You have already seen the @code{\addlyrics@{@}} command, which
1123 handles simple scores well. However, this technique is
1124 quite limited. For more complex music, you must introduce the
1125 lyrics in a @code{Lyrics} context using @code{\new Lyrics} and
1127 the lyrics to the notes with @code{\lyricsto@{@}}, using the
1128 name assigned to the Voice.
1130 @lilypond[quote,verbatim,fragment]
1132 \new Voice = "one" \relative c'' {
1135 c4 b8. a16 g4. f8 e4 d c2
1137 \new Lyrics \lyricsto "one" {
1138 No more let sins and sor -- rows grow.
1143 Note that the lyrics must be linked to a @code{Voice} context,
1144 @emph{not} a @code{Staff} context. This is a case where it is
1145 necessary to create @code{Staff} and @code{Voice} contexts
1148 @cindex lyrics and beaming
1149 @cindex beaming and lyrics
1150 @funindex \autoBeamOff
1152 The automatic beaming which LilyPond uses by default works well
1153 for instrumental music, but not so well for music with lyrics,
1154 where beaming is either not required at all or is used to indicate
1155 melismata in the lyrics. In the example above we use the command
1156 @code{\autoBeamOff} to turn off the automatic beaming.
1158 @funindex \new ChoirStaff
1159 @funindex \lyricmode
1160 @cindex vocal score structure
1162 Let us reuse the earlier example from Judas Maccabæus to
1163 illustrate this more flexible technique. We first recast
1164 it to use variables so the music and lyrics can be separated
1165 from the staff structure. We also introduce a ChoirStaff
1166 bracket. The lyrics themselves must be introduced with
1167 @code{\lyricmode} to ensure they are interpreted as lyrics
1170 @lilypond[quote,verbatim]
1171 global = { \time 6/8 \partial 8 \key f \major}
1172 SopOneMusic = \relative c'' {
1173 c8 | c([ bes)] a a([ g)] f | f'4. b, | c4.~ c4 }
1174 SopTwoMusic = \relative c' {
1175 r8 | r4. r4 c8 | a'([ g)] f f([ e)] d | e([ d)] c bes' }
1176 SopOneLyrics = \lyricmode {
1177 Let | flee -- cy flocks the | hills a -- dorn, __ }
1178 SopTwoLyrics = \lyricmode {
1179 Let | flee -- cy flocks the | hills a -- dorn, }
1184 \new Voice = "SopOne" {
1188 \new Lyrics \lyricsto "SopOne" {
1193 \new Voice = "SopTwo" {
1197 \new Lyrics \lyricsto "SopTwo" {
1205 This is the basic structure of all vocal scores. More staves may
1206 be added as required, more voices may be added to the staves,
1207 more verses may be added to the lyrics,
1208 and the variables containing the music can easily be placed
1209 in separate files should they become too long.
1211 @cindex hymn structure
1213 Here is a example of the first line of a hymn with four
1214 verses, set for SATB. In this case the words for all four
1217 @lilypond[quote,verbatim]
1218 TimeKey = { \time 4/4 \partial 4 \key c \major}
1219 SopMusic = \relative c' { c4 | e4. e8 g4 g | a a g }
1220 AltoMusic = \relative c' { c4 | c4. c8 e4 e | f f e }
1221 TenorMusic = \relative c { e4 | g4. g8 c4. b8 | a8 b c d e4 }
1222 BassMusic = \relative c { c4 | c4. c8 c4 c | f8 g a b c4 }
1223 VerseOne = \lyricmode {
1224 E -- | ter -- nal fa -- ther, | strong to save, }
1225 VerseTwo = \lyricmode {
1226 O | Christ, whose voice the | wa -- ters heard, }
1227 VerseThree = \lyricmode {
1228 O | Ho -- ly Spi -- rit, | who didst brood }
1229 VerseFour = \lyricmode {
1230 O | Tri -- ni -- ty of | love and pow'r }
1236 \new Voice = "Sop" { \voiceOne \TimeKey \SopMusic }
1237 \new Voice = "Alto" { \voiceTwo \AltoMusic }
1238 \new Lyrics \lyricsto "Sop" { \VerseOne }
1239 \new Lyrics \lyricsto "Sop" { \VerseTwo }
1240 \new Lyrics \lyricsto "Sop" { \VerseThree }
1241 \new Lyrics \lyricsto "Sop" { \VerseFour }
1245 \new Voice = "Tenor" { \voiceOne \TimeKey \TenorMusic }
1246 \new Voice = "Bass" { \voiceTwo \BassMusic }
1252 @cindex verse and refrain
1254 We end with an example to show how we might code a solo verse which
1255 continues into a two-part refrain in two staves. The
1256 positioning of the sequential and simultaneous sections to achieve
1257 this within a single score is quite tricky, so follow the
1258 explanation carefully!
1260 Let's start with a score block containing a @code{ChoirStaff}, as
1261 we would like the brace to appear at the start of the chorus.
1262 Normally you would need angle brackets after @code{\new ChoirStaff}
1263 to bring in all the staves in parallel, but here we want to
1264 defer the parallelism during the solo so we use braces, although
1265 angle brackets here wouldn't hurt. Inside the @code{ChoirStaff} we
1266 want first the staff which will contain the verse. This must
1267 contain notes and lyrics in parallel, so here we need angle
1268 brackets around the @code{\new Voice} and @code{\new Lyrics} to
1269 start them at the same time:
1271 @lilypond[quote,verbatim,ragged-right]
1272 versenotes = \relative c'' {
1275 \time 3/4 g g g b b b
1277 versewords = \lyricmode {
1278 One two three four five six
1283 \new Voice = "verse" {
1286 \new Lyrics \lyricsto verse {
1294 That gives the verse line.
1296 Now we want to continue with refrainA on the same staff while a
1297 second staff is introduced in parallel with it for refrainB, so
1298 this is a parallel section which must be positioned immediately
1299 following the @code{\break} in the verse Voice. Yes, @emph{within}
1300 the verse Voice! Here's that parallel section. More staves
1301 could be introduced here in the same way.
1306 \new Lyrics \lyricsto verse @{
1310 \new Voice = "refrainB" @{
1313 \new Lyrics \lyricsto "refrainB" @{
1320 Here's the final result with two staves in the chorus showing
1321 how the parallel section is positioned within the verse Voice:
1323 @lilypond[quote,verbatim, ragged-right]
1324 versenotes = \relative c'' {
1327 \time 3/4 g g g b b b
1329 refrainnotesA = \relative c'' {
1333 refrainnotesB = \relative c {
1338 versewords = \lyricmode {
1339 One two three four five six
1341 refrainwordsA = \lyricmode {
1344 refrainwordsB = \lyricmode {
1350 \context Voice = "verse" {
1354 \new Lyrics \lyricsto "verse" {
1358 \new Voice = "refrainB" {
1361 \new Lyrics \lyricsto "refrainB" {
1367 \new Lyrics \lyricsto "verse" {
1375 @cindex book, example of using
1378 However, although this is an interesting and useful exercise to
1379 help you to understand how sequential and simultaneous blocks work,
1380 in practice one would perhaps choose to code this as two
1381 @code{\score} blocks within an implicit @code{\book} block, as
1384 @lilypond[quote,verbatim,ragged-right]
1385 versenotes = \relative c'' {
1388 \time 3/4 g g g b b b
1390 refrainnotesA = \relative c'' {
1394 refrainnotesB = \relative c {
1399 versewords = \lyricmode {
1400 One two three four five six
1402 refrainwordsA = \lyricmode {
1405 refrainwordsB = \lyricmode {
1410 \new Voice = "verse" {
1413 \new Lyrics \lyricsto "verse" {
1422 \new Voice = "refrainA" {
1425 \new Lyrics \lyricsto "refrainA" {
1430 \new Voice = "refrainB" {
1433 \new Lyrics \lyricsto "refrainB" {
1441 @node Contexts and engravers
1442 @section Contexts and engravers
1444 Contexts and engravers have been mentioned informally
1445 in earlier sections; we now must look at
1446 these concepts in more detail, as they are important
1447 in the fine-tuning of LilyPond output.
1451 * Contexts explained::
1452 * Creating contexts::
1453 * Engravers explained::
1454 * Modifying context properties::
1455 * Adding and removing engravers::
1458 @node Contexts explained
1459 @subsection Contexts explained
1461 @cindex contexts explained
1463 When music is printed, many notational elements which do not
1464 appear explicitly in the input file must be added to the
1465 output. For example, compare the input and output of the
1468 @lilypond[quote,verbatim,relative=2,fragment]
1472 The input is rather sparse, but in the output, bar lines,
1473 accidentals, clef, and time signature have been added. When
1474 LilyPond @emph{interprets} the input the musical information
1475 is inspected in time order, similar to reading a score from left
1476 to right. While reading the input, the program remembers where
1477 measure boundaries are, and which pitches require explicit
1478 accidentals. This information must be held on several levels.
1479 For example, the effect of an accidental is limited
1480 to a single staff, while a bar line must be synchronized across
1483 Within LilyPond, these rules and bits of information are grouped
1484 in @emph{Contexts}. We have already met the
1485 @code{Voice} context.
1486 Others are the @code{Staff} and @code{Score} contexts.
1487 Contexts are hierarchical to reflect the hierarchical nature of
1489 For example: a @code{Staff} context can contain many
1490 @code{Voice} contexts, and a @code{Score} context can
1491 contain many @code{Staff} contexts.
1494 @sourceimage{context-example,5cm,,}
1497 Each context has the responsibility for enforcing some notation rules,
1498 creating some notation objects and maintaining the associated
1499 properties. For example, the @code{Voice} context may introduce an
1500 accidental and then the @code{Staff} context maintains the rule to
1501 show or suppress the accidental for the remainder of the measure.
1503 As another example, the synchronization of bar lines is, by default,
1504 handled in the @code{Score} context.
1505 However, in some music we may not want the bar lines to be
1506 synchronized -- consider a polymetric score in 4/4 and 3/4 time.
1507 In such cases, we must modify the default settings of the
1508 @code{Score} and @code{Staff} contexts.
1510 For very simple scores, contexts are created implicitly, and you need
1511 not be aware of them. For larger pieces, such as anything with more
1512 than one staff, they must be
1513 created explicitly to make sure that you get as many staves as you
1514 need, and that they are in the correct order. For typesetting pieces
1515 with specialized notation, it is usual to modify existing, or
1516 even to define totally new, contexts.
1518 In addition to the @code{Score,} @code{Staff} and
1519 @code{Voice} contexts there are contexts which fit between
1520 the score and staff levels to control staff groups, such as the
1521 @code{PianoStaff} and @code{ChoirStaff} contexts. There
1522 are also alternative staff and voice contexts, and contexts for
1523 lyrics, percussion, fret boards, figured bass, etc.
1525 The names of all context types are formed from one or more
1526 words, each word being capitalized and joined immediately to the
1527 preceding word with no hyphen or underscore, e.g.,
1528 @code{GregorianTranscriptionStaff}.
1530 @node Creating contexts
1531 @subsection Creating contexts
1534 @cindex new contexts
1535 @cindex creating contexts
1536 @cindex contexts, creating
1538 There can be only one top level context: the
1540 context. This is created with the @code{\score} command,
1541 or, in simple scores, it is created automatically.
1543 For scores with only one voice and one staff, the
1544 @code{Voice} and @code{Staff} contexts may be left to be
1545 created automatically, but for more complex scores it is
1546 necessary to create them by hand.
1547 The simplest command that does this is @code{\new}.
1548 It is prepended to a music expression, for example
1551 \new @var{type} @var{music-expression}
1555 where @var{type} is a context name (like @code{Staff} or
1556 @code{Voice}). This command creates a new context, and starts
1557 interpreting the @var{music-expression} within that context.
1559 Note that there is no @code{\new Score} command;
1560 the single top-level @code{Score} context is introduced
1563 @cindex contexts, naming
1564 @cindex naming contexts
1566 The @code{\new} command may also give a identifying name to the
1567 context to distinguish it from other contexts of the same type,
1570 \new @var{type} = @var{id} @var{music-expression}
1573 Note the distinction between the name of the context type,
1574 @code{Staff}, @code{Voice}, etc, and
1575 the identifying name of a particular instance of that type,
1576 which can be any sequence of letters invented by the user.
1577 The identifying name is used to refer back to that particular
1578 instance of a context. We saw this in use in the section on
1579 lyrics in @ref{Voices and vocals}.
1582 @node Engravers explained
1583 @subsection Engravers explained
1587 Every mark on the printed output of a score produced by LilyPond
1588 is produced by an @code{Engraver}. Thus there is an engraver
1589 to print staves, one to print note heads, one for stems, one for
1590 beams, etc, etc. In total there are over 120 such engravers!
1591 Fortunately, for most scores it is not necessary to know about
1592 more than a few, and for simple scores you do not need to know
1595 Engravers live and operate in Contexts.
1596 Engravers such as the @code{Metronome_mark_engraver}, whose
1597 action and output applies to the score as a whole, operate in
1598 the highest level context -- the @code{Score} context.
1600 The @code{Clef_engraver} and @code{Key_engraver} are to be
1601 found in every Staff Context, as different staves may require
1602 different clefs and keys.
1604 The @code{Note_heads_engraver} and @code{Stem_engraver} live
1605 in every @code{Voice} context, the lowest level context of all.
1607 Each engraver processes the particular objects associated
1608 with its function, and maintains the properties that relate
1609 to that function. These properties, like the properties
1610 associated with contexts, may be modified to change the
1611 operation of the engraver or the appearance of those elements
1612 in the printed score.
1614 Engravers all have compound names formed from words which
1615 describe their function. Just the first word is capitalized,
1616 and the remainder are joined to it with underscores. Thus
1617 the @code{Staff_symbol_engraver} is responsible for creating the
1618 lines of the staff, the @code{Clef_engraver} determines and sets
1619 the pitch reference point on the staff by drawing a clef symbol.
1621 Here are some of the most common engravers together with their
1622 function. You will see it is usually easy to guess the function
1623 from the name, or vice versa.
1625 @multitable @columnfractions .3 .7
1628 @item Accidental_engraver
1629 @tab Makes accidentals, cautionary and suggested accidentals
1634 @item Completion_heads_engraver
1635 @tab Splits notes which cross bar lines
1636 @item Dynamic_engraver
1637 @tab Creates hairpins and dynamic texts
1638 @item Forbid_line_break_engraver
1639 @tab Prevents line breaks if a musical element is still active
1641 @tab Creates the key signature
1642 @item Metronome_mark_engraver
1643 @tab Engraves metronome marking
1644 @item Note_heads_engraver
1645 @tab Engraves note heads
1648 @item Staff_symbol_engraver
1649 @tab Engraves the five (by default) lines of the staff
1651 @tab Creates stems and single-stem tremolos
1652 @item Time_signature_engraver
1653 @tab Creates time signatures
1658 We shall see later how the output of LilyPond can be changed
1659 by modifying the action of Engravers.
1662 @node Modifying context properties
1663 @subsection Modifying context properties
1665 @cindex context properties
1666 @cindex context properties, modifying
1667 @cindex modifying context properties
1671 Contexts are responsible for holding the values of a number of
1672 context @emph{properties}. Many of them can be changed to
1673 influence the interpretation of the input and so change the
1674 appearance of the output. They are changed by the
1675 @code{\set} command. This takes the form
1678 \set @emph{ContextName}.@emph{propertyName} = #@emph{value}
1681 Where the @emph{ContextName} is usually @code{Score},
1682 @code{Staff} or @code{Voice}. It may be omitted,
1683 in which case @code{Voice} is assumed.
1685 The names of context properties consist of words joined
1686 together with no hyphens or underscores, all except the
1687 first having a capital letter. Here are a few examples
1688 of some commonly used ones. There are many more.
1690 @c attempt to force this onto a new page
1692 @multitable @columnfractions .25 .15 .45 .15
1693 @headitem propertyName
1699 @tab If true, set extra natural signs before accidentals
1700 @tab @code{#t}, @code{#f}
1701 @item currentBarNumber
1703 @tab Set the current bar number
1707 @tab If true, print slurs both above and below notes
1708 @tab @code{#t}, @code{#f}
1709 @item instrumentName
1711 @tab Set the name to be placed at the start of the staff
1712 @tab @code{"Cello I"}
1715 @tab Increase or decrease the font size
1719 @tab Set the text to print before the start of a verse
1724 where a Boolean is either True (@code{#t}) or False (@code{#f}),
1725 an Integer is a positive whole number, a Real is a positive
1726 or negative decimal number, and text is enclosed in double
1727 apostrophes. Note the occurrence of hash signs,
1728 (@code{#}), in two different places -- as part of the Boolean
1729 value before the @code{t} or @code{f}, and before @emph{value}
1730 in the @code{\set} statement. So when a Boolean is being
1731 entered you need to code two hash signs, e.g., @code{##t}.
1733 Before we can set any of these properties we need to know
1734 in which context they operate. Sometimes this is obvious,
1735 but occasionally it can be tricky. If the wrong context
1736 is specified, no error message is produced, but the expected
1737 action will not take place. For example, the
1738 @code{instrumentName} clearly lives in the Staff context, since
1739 it is the staff that is to be named.
1740 In this example the first staff is labelled, but not the second,
1741 because we omitted the context name.
1743 @lilypond[quote,verbatim,ragged-right]
1745 \new Staff \relative c'' {
1746 \set Staff.instrumentName = #"Soprano"
1749 \new Staff \relative c' {
1750 \set instrumentName = #"Alto" % Wrong!
1756 Remember the default context name is Voice, so the second
1757 @code{\set} command set the property @code{instrumentName} in the
1758 Voice context to @qq{Alto}, but as LilyPond does not look
1759 for any such property in the @code{Voice} context, no
1760 further action took place. This is not an error, and no error
1761 message is logged in the log file.
1763 Similarly, if the property name is mis-spelt no error message
1764 is produced, and clearly the expected action cannot be performed.
1765 If fact, you can set any (fictitious) @q{property} using any
1766 name you like in any context that exists by using the
1767 @code{\set} command. But if the name is not
1768 known to LilyPond it will not cause any action to be taken.
1769 This is one of the reasons why it is highly recommended to
1770 use a context-sensitive editor with syntax highlighting for
1771 editing LilyPond input files, such as Vim, Jedit, ConTEXT or Emacs,
1772 since unknown property names will be highlighted differently.
1774 The @code{instrumentName} property will take effect only
1775 if it is set in the @code{Staff} context, but
1776 some properties can be set in more than one context.
1777 For example, the property @code{extraNatural} is by
1778 default set to ##t (true) for all staves.
1779 If it is set to ##f (false) in one particular @code{Staff}
1780 context it applies just to the accidentals on that staff.
1781 If it is set to false in the @code{Score} context
1782 it applies to all staves.
1784 So this turns off extra naturals in one staff:
1786 @lilypond[quote,verbatim,ragged-right]
1788 \new Staff \relative c'' {
1791 \new Staff \relative c'' {
1792 \set Staff.extraNatural = ##f
1799 and this turns them off in all staves:
1801 @lilypond[quote,verbatim,ragged-right]
1803 \new Staff \relative c'' {
1806 \new Staff \relative c'' {
1807 \set Score.extraNatural = ##f
1813 As another example, if @code{clefOctavation} is set in
1814 the @code{Score} context this immediately changes the value
1815 of the octavation in all current staves and sets a new default
1816 value which will be applied to all staves.
1818 The opposite command, @code{\unset}, effectively removes the
1819 property from the context, which causes most properties to
1820 revert to their default value. Usually @code{\unset} is not
1821 required as a new @code{\set} command will achieve what is
1824 The @code{\set} and @code{\unset} commands can appear anywhere
1825 in the input file and will take effect from the time they are
1826 encountered until the end of the score or until the property is
1827 @code{\set} or @code{\unset} again. Let's try changing the
1828 font size, which affects the size of the note heads (among
1829 other things) several times. The change is from the default
1830 value, not the most recently set value.
1832 @lilypond[quote,verbatim,ragged-right,relative=1,fragment]
1834 % make note heads smaller
1837 % make note heads larger
1838 \set fontSize = #2.5
1840 % return to default size
1845 We have now seen how to set the values of several different
1846 types of property. Note that integers and numbers are always
1847 preceded by a hash sign, @code{#}, while a true or false value
1848 is specified by ##t and ##f, with two hash signs. A text
1849 property should be enclosed in double quotation signs, as above,
1850 although we shall see later that text can actually be specified
1851 in a much more general way by using the very powerful
1852 @code{markup} command.
1856 @cindex context properties, setting with \with
1858 Context properties may also be set at the time the context is
1859 created. Sometimes this is a clearer way of specifying a
1860 property value if it is to remain fixed for the duration of
1861 the context. When a context is created with a @code{\new}
1862 command it may be followed immediately by a
1863 @code{\with @{ .. @}} block in which the property values are
1864 set. For example, if we wish to suppress the printing of
1865 extra naturals for the duration of a staff we would write:
1868 \new Staff \with @{ extraNatural = ##f @}
1874 @lilypond[quote,verbatim,ragged-right]
1880 \new Staff \with { extraNatural = ##f }
1887 Properties set in this way may still be changed dynamically using
1888 @code{\set} and returned to their default value with @code{\unset}.
1890 The @code{fontSize} property is treated differently. If this is
1891 set in a @code{\with} clause it effectively resets the default
1892 value of the font size. If it is later changed with @code{\set}
1893 this new default value may be restored with the
1894 @code{\unset fontSize} command.
1896 @node Adding and removing engravers
1897 @subsection Adding and removing engravers
1899 @cindex engravers, adding
1900 @cindex engravers, removing
1905 We have seen that contexts each contain several engravers, each
1906 of which is responsible for producing a particular part of the
1907 output, like bar lines, staves, note heads, stems, etc. If an
1908 engraver is removed from a context it can no longer produce its
1909 output. This is a crude way of modifying the output, but it
1910 can sometimes be useful.
1912 @subsubheading Changing a single context
1914 To remove an engraver from a single context we use the
1915 @code{\with} command placed immediately after the context creation
1916 command, as in the previous section.
1919 illustration let's repeat an example from the previous
1920 section with the staff lines removed. Remember that the
1921 staff lines are produced by the Staff_symbol_engraver.
1923 @lilypond[quote,verbatim,ragged-right]
1925 \remove Staff_symbol_engraver
1929 \set fontSize = #-4 % make note heads smaller
1931 \set fontSize = #2.5 % make note heads larger
1933 \unset fontSize % return to original size
1938 @cindex ambitus engraver
1940 Engravers can also be added to individual contexts.
1941 The command to do this is
1943 @code{\consists @emph{Engraver_name}},
1945 placed inside a @code{\with} block. Some vocal scores
1946 have an @rglos{ambitus} placed at the beginning of a
1947 staff to indicate the range of notes in that staff.
1948 The ambitus is produced by the @code{Ambitus_engraver},
1949 which is not normally included in any context. If
1950 we add it to the @code{Voice} context it calculates
1951 the range from that voice only:
1953 @lilypond[quote,verbatim,ragged-right]
1956 \consists Ambitus_engraver
1971 but if we add the Ambitus engraver to the
1972 @code{Staff} context it calculates the range from all
1973 the notes in all the voices on that staff:
1975 @lilypond[quote,verbatim,ragged-right]
1977 \consists Ambitus_engraver
1993 @subsubheading Changing all contexts of the same type
1997 The examples above show how to remove or add engravers to
1998 individual contexts. It is also possible to remove or add
1999 engravers to every context of a specific type by placing the
2000 commands in the appropriate context in a @code{\layout}
2001 block. For example, if we wanted to show an ambitus for every
2002 staff in a four-staff score we could write
2004 @lilypond[quote,verbatim,ragged-right]
2008 \relative c'' { c a b g }
2011 \relative c' { c a b g }
2015 \relative c' { c a b g }
2019 \relative c { c a b g }
2025 \consists Ambitus_engraver
2032 The values of context properties may also be set
2033 for all contexts of a particular type by including the
2034 @code{\set} command in a @code{\context} block in the
2037 @node Extending the templates
2038 @section Extending the templates
2040 You've read the tutorial, you know how to write music, you
2041 understand the fundamental concepts. But how can you
2042 get the staves that you want? Well, you can find lots of
2043 templates (see @ref{Templates}) which may give you a start.
2045 if you want something that isn't covered there? Read on.
2047 TODO Add links to templates after they have been moved to LSR
2050 * Soprano and cello::
2051 * Four-part SATB vocal score::
2052 * Building a score from scratch::
2055 @node Soprano and cello
2056 @subsection Soprano and cello
2058 @cindex template, modifying
2060 Start off with the template that seems closest to what you want to end
2061 up with. Let's say that you want to write something for soprano and
2062 cello. In this case, we would start with @q{Notes and lyrics} (for the
2066 \version @w{"@version{}"}
2067 melody = \relative c' @{
2074 text = \lyricmode @{
2080 \new Voice = "one" @{
2084 \new Lyrics \lyricsto "one" \text
2091 Now we want to add a cello part. Let's look at the @q{Notes only} example:
2094 \version @w{"@version{}"}
2095 melody = \relative c' @{
2109 We don't need two @code{\version} commands. We'll need the
2110 @code{melody} section. We don't want two @code{\score} sections
2111 -- if we had two @code{\score}s, we'd get the two parts separately.
2112 We want them together, as a duet. Within the @code{\score}
2113 section, we don't need two @code{\layout} or @code{\midi}.
2115 If we simply cut and paste the @code{melody} section, we would
2116 end up with two @code{melody} definitions. This would not generate
2117 an error, but the second one would be used for both melodies.
2118 So let's rename them to make them distinct. We'll call the
2119 section for the soprano @code{sopranoMusic} and the section for
2120 the cello @code{celloMusic}. While we're doing this, let's rename
2121 @code{text} to be @code{sopranoLyrics}. Remember to rename both
2122 instances of all these names -- both the initial definition (the
2123 @code{melody = \relative c' @{ } part) and the name's use (in the
2124 @code{\score} section).
2126 While we're doing this, let's change the cello part's staff --
2127 celli normally use bass clef. We'll also give the cello some
2131 \version @w{"@version{}"}
2132 sopranoMusic = \relative c' @{
2139 sopranoLyrics = \lyricmode @{
2143 celloMusic = \relative c @{
2152 \new Voice = "one" @{
2156 \new Lyrics \lyricsto "one" \sopranoLyrics
2163 This is looking promising, but the cello part won't appear in the
2164 score -- we haven't used it in the @code{\score} section. If we
2165 want the cello part to appear under the soprano part, we need to add
2168 \new Staff \celloMusic
2172 underneath the soprano stuff. We also need to add @code{<<} and
2173 @code{>>} around the music -- that tells LilyPond that there's
2174 more than one thing (in this case, two @code{Staves}) happening
2175 at once. The @code{\score} looks like this now
2177 @c Indentation in this example is deliberately poor
2182 \new Voice = "one" @{
2186 \new Lyrics \lyricsto "one" \sopranoLyrics
2188 \new Staff \celloMusic
2196 This looks a bit messy; the indentation is messed up now. That is
2197 easily fixed. Here's the complete soprano and cello template.
2199 @lilypond[quote,verbatim,ragged-right,addversion]
2200 sopranoMusic = \relative c' {
2207 sopranoLyrics = \lyricmode {
2211 celloMusic = \relative c {
2221 \new Voice = "one" {
2225 \new Lyrics \lyricsto "one" \sopranoLyrics
2227 \new Staff \celloMusic
2235 @node Four-part SATB vocal score
2236 @subsection Four-part SATB vocal score
2238 @cindex template, SATB
2239 @cindex SATB template
2241 Most vocal scores of music written for four-part mixed choir
2242 with orchestral accompaniment such as Mendelssohn's Elijah or
2243 Handel's Messiah have the choral music and words on four
2244 staves, one for each of SATB, with a piano reduction of the
2245 orchestral accompaniment underneath. Here's an example
2246 from Handel's Messiah:
2248 @c The following should appear as music without code
2249 @lilypond[quote,ragged-right]
2250 global = { \key d \major \time 4/4 }
2251 sopMusic = \relative c'' {
2253 r4 d2 a4 | d4. d8 a2 | cis4 d cis2 |
2255 sopWords = \lyricmode {
2256 Wor -- thy is the lamb that was slain
2258 altoMusic = \relative a' {
2260 r4 a2 a4 | fis4. fis8 a2 | g4 fis e2 |
2262 altoWords = \sopWords
2263 tenorMusic = \relative c' {
2265 r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 |
2267 tenorWords = \sopWords
2268 bassMusic = \relative c' {
2270 r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 |
2272 bassWords = \sopWords
2273 upper = \relative a' {
2276 r4 <a d fis>2 <a e' a>4 |
2277 <d fis d'>4. <d fis d'>8 <a d a'>2 |
2278 <g cis g'>4 <a d fis> <a cis e>2 |
2280 lower = \relative c, {
2283 <d d'>4 <d d'>2 <cis cis'>4 |
2284 <b b'>4. <b' b'>8 <fis fis'>2 |
2285 <e e'>4 <d d'> <a' a'>2 |
2289 << % combine ChoirStaff and PianoStaff in parallel
2291 \new Staff = "sopranos" <<
2292 \set Staff.instrumentName = "Soprano"
2293 \new Voice = "sopranos" { \global \sopMusic }
2295 \new Lyrics \lyricsto "sopranos" { \sopWords }
2296 \new Staff = "altos" <<
2297 \set Staff.instrumentName = "Alto"
2298 \new Voice = "altos" { \global \altoMusic }
2300 \new Lyrics \lyricsto "altos" { \altoWords }
2301 \new Staff = "tenors" <<
2302 \set Staff.instrumentName = "Tenor"
2303 \new Voice = "tenors" { \global \tenorMusic }
2305 \new Lyrics \lyricsto "tenors" { \tenorWords }
2306 \new Staff = "basses" <<
2307 \set Staff.instrumentName = "Bass"
2308 \new Voice = "basses" { \global \bassMusic }
2310 \new Lyrics \lyricsto "basses" { \bassWords }
2314 \set PianoStaff.instrumentName = "Piano "
2315 \new Staff = "upper" \upper
2316 \new Staff = "lower" \lower
2322 None of the templates provides this layout exactly. The
2323 nearest is @q{SATB vocal score and automatic piano reduction},
2324 but we need to change the layout and add a piano
2325 accompaniment which is not derived automatically from the
2326 vocal parts. The variables holding the music and words for
2327 the vocal parts are fine, but we shall need to add variables for
2328 the piano reduction.
2330 The order in which the contexts appear in the ChoirStaff of
2331 the template do not correspond with the order in the vocal
2332 score shown above. We need to rearrange them so there are
2333 four staves with the words written directly underneath the
2334 notes for each part.
2335 All the voices should be @code{\voiceOne}, which is
2336 the default, so the @code{\voiceXXX} commands should be removed.
2337 We also need to specify the tenor clef for the tenors.
2338 The way in which lyrics are specified in the template has not yet
2339 been encountered so we need to use the method with which we are
2340 familiar. We should also add the names of each staff.
2342 Doing this gives for our ChoirStaff:
2346 \new Staff = "sopranos" <<
2347 \set Staff.instrumentName = "Soprano"
2348 \new Voice = "sopranos" @{ \global \sopMusic @}
2350 \new Lyrics \lyricsto "sopranos" @{ \sopWords @}
2351 \new Staff = "altos" <<
2352 \set Staff.instrumentName = "Alto"
2353 \new Voice = "altos" @{ \global \altoMusic @}
2355 \new Lyrics \lyricsto "altos" @{ \altoWords @}
2356 \new Staff = "tenors" <<
2357 \set Staff.instrumentName = "Tenor"
2358 \new Voice = "tenors" @{ \global \tenorMusic @}
2360 \new Lyrics \lyricsto "tenors" @{ \tenorWords @}
2361 \new Staff = "basses" <<
2362 \set Staff.instrumentName = "Bass"
2363 \new Voice = "basses" @{ \global \bassMusic @}
2365 \new Lyrics \lyricsto "basses" @{ \bassWords @}
2369 Next we must work out the piano part. This is
2370 easy - we just pull out the piano part from the
2371 @q{Solo piano} template:
2375 \set PianoStaff.instrumentName = "Piano "
2376 \new Staff = "upper" \upper
2377 \new Staff = "lower" \lower
2381 and add the variable definitions for @code{upper}
2384 The ChoirStaff and PianoStaff must be combined
2385 using angle brackets as we want them to be
2386 stacked one above the other:
2389 << % combine ChoirStaff and PianoStaff one above the other
2391 \new Staff = "sopranos" <<
2392 \new Voice = "sopranos" @{ \global \sopMusic @}
2394 \new Lyrics \lyricsto "sopranos" @{ \sopWords @}
2395 \new Staff = "altos" <<
2396 \new Voice = "altos" @{ \global \altoMusic @}
2398 \new Lyrics \lyricsto "altos" @{ \altoWords @}
2399 \new Staff = "tenors" <<
2400 \clef "G_8" % tenor clef
2401 \new Voice = "tenors" @{ \global \tenorMusic @}
2403 \new Lyrics \lyricsto "tenors" @{ \tenorWords @}
2404 \new Staff = "basses" <<
2406 \new Voice = "basses" @{ \global \bassMusic @}
2408 \new Lyrics \lyricsto "basses" @{ \bassWords @}
2412 \set PianoStaff.instrumentName = "Piano "
2413 \new Staff = "upper" \upper
2414 \new Staff = "lower" \lower
2419 Combining all these together and adding the music
2420 for the three bars of the example above gives:
2422 @lilypond[quote,verbatim,ragged-right,addversion]
2423 global = { \key d \major \time 4/4 }
2424 sopMusic = \relative c'' {
2426 r4 d2 a4 | d4. d8 a2 | cis4 d cis2 |
2428 sopWords = \lyricmode {
2429 Wor -- thy is the lamb that was slain
2431 altoMusic = \relative a' {
2433 r4 a2 a4 | fis4. fis8 a2 | g4 fis fis2 |
2435 altoWords = \sopWords
2436 tenorMusic = \relative c' {
2438 r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 |
2440 tenorWords = \sopWords
2441 bassMusic = \relative c' {
2443 r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 |
2445 bassWords = \sopWords
2446 upper = \relative a' {
2449 r4 <a d fis>2 <a e' a>4 |
2450 <d fis d'>4. <d fis d'>8 <a d a'>2 |
2451 <g cis g'>4 <a d fis> <a cis e>2 |
2453 lower = \relative c, {
2456 <d d'>4 <d d'>2 <cis cis'>4 |
2457 <b b'>4. <b' b'>8 <fis fis'>2 |
2458 <e e'>4 <d d'> <a' a'>2 |
2462 << % combine ChoirStaff and PianoStaff in parallel
2464 \new Staff = "sopranos" <<
2465 \set Staff.instrumentName = "Soprano"
2466 \new Voice = "sopranos" { \global \sopMusic }
2468 \new Lyrics \lyricsto "sopranos" { \sopWords }
2469 \new Staff = "altos" <<
2470 \set Staff.instrumentName = "Alto"
2471 \new Voice = "altos" { \global \altoMusic }
2473 \new Lyrics \lyricsto "altos" { \altoWords }
2474 \new Staff = "tenors" <<
2475 \set Staff.instrumentName = "Tenor"
2476 \new Voice = "tenors" { \global \tenorMusic }
2478 \new Lyrics \lyricsto "tenors" { \tenorWords }
2479 \new Staff = "basses" <<
2480 \set Staff.instrumentName = "Bass"
2481 \new Voice = "basses" { \global \bassMusic }
2483 \new Lyrics \lyricsto "basses" { \bassWords }
2487 \set PianoStaff.instrumentName = "Piano "
2488 \new Staff = "upper" \upper
2489 \new Staff = "lower" \lower
2496 @node Building a score from scratch
2497 @subsection Building a score from scratch
2499 @cindex template, writing your own
2501 After gaining some facility with writing LilyPond code you
2502 may find that it is easier to build a score from scratch
2503 rather than modifying one of the templates. You can also
2504 develop your own style this way to suit the sort of music you
2505 like. Let's see how to put together the score for an organ
2506 prelude as an example.
2508 We begin with a header section. Here go the title, name
2509 of composer, etc, then come any variable definitions, and
2510 finally the score block. Let's start with these in outline
2511 and fill in the details later.
2513 We'll use the first two bars of Bach's prelude
2514 based on @emph{Jesu, meine Freude} which is written for two
2515 manuals and pedal organ. You can see these two bars of music
2516 at the bottom of this section. The top manual part has two voices,
2517 the lower and pedal organ one each. So we need four
2518 music definitions and one to define the time signature
2522 \version @w{"@version{}"}
2524 title = "Jesu, meine Freude"
2525 composer = "J S Bach"
2527 TimeKey = @{ \time 4/4 \key c \minor @}
2528 ManualOneVoiceOneMusic = @{s1@}
2529 ManualOneVoiceTwoMusic = @{s1@}
2530 ManualTwoMusic = @{s1@}
2531 PedalOrganMusic = @{s1@}
2537 For now we've just used a spacer note, @code{s1},
2538 instead of the real music. We'll add that later.
2540 Next let's see what should go in the score block.
2541 We simply mirror the staff structure we want.
2542 Organ music is usually written on three staves,
2543 one for each manual and one for the pedals. The
2544 manual staves should be bracketed together so we
2545 need to use a PianoStaff for them. The first
2546 manual part needs two voices and the second manual
2551 \new Staff = "ManualOne" <<
2552 \new Voice @{ \ManualOneVoiceOneMusic @}
2553 \new Voice @{ \ManualOneVoiceTwoMusic @}
2554 >> % end ManualOne Staff context
2555 \new Staff = "ManualTwo" <<
2556 \new Voice @{ \ManualTwoMusic @}
2557 >> % end ManualTwo Staff context
2558 >> % end PianoStaff context
2561 Next we need to add a staff for the pedal organ.
2562 This goes underneath the PianoStaff, but it must
2563 be simultaneous with it, so we need angle brackets
2564 round the two. Missing these out would generate
2565 an error in the log file. It's a common mistake
2566 which you'll make sooner or later! Try copying
2567 the final example at the end of this section,
2568 remove these angle brackets, and compile it to
2569 see what errors it generates.
2572 << % PianoStaff and Pedal Staff must be simultaneous
2574 \new Staff = "ManualOne" <<
2575 \new Voice @{ \ManualOneVoiceOneMusic @}
2576 \new Voice @{ \ManualOneVoiceTwoMusic @}
2577 >> % end ManualOne Staff context
2578 \new Staff = "ManualTwo" <<
2579 \new Voice @{ \ManualTwoMusic @}
2580 >> % end ManualTwo Staff context
2581 >> % end PianoStaff context
2582 \new Staff = "PedalOrgan" <<
2583 \new Voice @{ \PedalOrganMusic @}
2588 It is not strictly necessary to use the simultaneous construct
2589 @code{<< .. >>} for the manual two staff and the pedal organ staff,
2590 since they contain only one music expression, but it does no harm
2591 and always using angle brackets after @code{\new Staff} is a good
2592 habit to cultivate in case there are multiple voices. The opposite
2593 is true for Voices: these should habitually be followed by braces
2594 @code{@{ .. @}} in case your music is coded in several variables
2595 which need to run consecutively.
2597 Let's add this structure to the score block, and adjust the
2598 indenting. We also add the appropriate clefs, ensure the
2599 second voice stems point down with @code{\voiceTwo} and
2600 enter the time signature and key to each staff using our
2601 predefined variable, @code{\TimeKey}.
2605 << % PianoStaff and Pedal Staff must be simultaneous
2607 \new Staff = "ManualOne" <<
2608 \TimeKey % set time signature and key
2610 \new Voice @{ \ManualOneVoiceOneMusic @}
2611 \new Voice @{ \voiceTwo \ManualOneVoiceTwoMusic @}
2612 >> % end ManualOne Staff context
2613 \new Staff = "ManualTwo" <<
2616 \new Voice @{ \ManualTwoMusic @}
2617 >> % end ManualTwo Staff context
2618 >> % end PianoStaff context
2619 \new Staff = "PedalOrgan" <<
2622 \new Voice @{ \PedalOrganMusic @}
2623 >> % end PedalOrgan Staff
2625 @} % end Score context
2628 That completes the structure. Any three-staff organ music
2629 will have a similar structure, although the number of voices
2630 may vary. All that remains now
2631 is to add the music, and combine all the parts together.
2633 @lilypond[quote,verbatim,ragged-right,addversion]
2635 title = "Jesu, meine Freude"
2636 composer = "J S Bach"
2638 TimeKey = { \time 4/4 \key c \minor }
2639 ManualOneVoiceOneMusic = \relative g' {
2640 g4 g f ees | d2 c2 |
2642 ManualOneVoiceTwoMusic = \relative c' {
2643 ees16 d ees8~ ees16 f ees s c8 d~ d c~ |
2644 c c4 b8 c8. g16 c b c d |
2646 ManualTwoMusic = \relative c' {
2647 c16 b c8~ c16 b c g a8 g~ g16 g aes ees |
2648 f ees f d g aes g f ees d e8~ ees16 f ees d |
2650 PedalOrganMusic = \relative c {
2651 r8 c16 d ees d ees8~ ees16 a, b g c b c8 |
2652 r16 g ees f g f g8 c,2 |
2656 << % PianoStaff and Pedal Staff must be simultaneous
2658 \new Staff = "ManualOne" <<
2659 \TimeKey % set time signature and key
2661 \new Voice { \ManualOneVoiceOneMusic }
2662 \new Voice { \voiceTwo \ManualOneVoiceTwoMusic }
2663 >> % end ManualOne Staff context
2664 \new Staff = "ManualTwo" <<
2667 \new Voice { \ManualTwoMusic }
2668 >> % end ManualTwo Staff context
2669 >> % end PianoStaff context
2670 \new Staff = "PedalOrgan" <<
2673 \new Voice { \PedalOrganMusic }
2674 >> % end PedalOrgan Staff
2676 } % end Score context